@lightworkai.official/debug-capture 0.19.4 → 0.19.6

package/dist/ui/bubblePlace.d.ts

@@ -0,0 +1,104 @@
+/**
+ * WHERE THE BUBBLE MAY STAND (0.19.6) — out of the host page's way, and where its desk says for a page.
+ *
+ * The owner, 2026-11-02, of the ERP's เอกสาร page: "our chat bubble is over the action button on some page or even i move
+ * it out it still over on this menu … but for most of the page it worked fine … any idea to solve this?" — the page's own
+ * toolbar (`fixed right-4 z-40`, a column up most of the right edge) sits where the bubble does, and wherever it was let
+ * go on the right it landed on it again.
+ *
+ *   THE PAGE'S OWN FLOATING CONTROLS ARE OBSTACLES. What is topmost under the bubble's column and stays put while the
+ *   page scrolls: inside a small `fixed` box (or a `sticky` one, stuck) — a toolbar, a FAB, a bottom bar, a sidebar —
+ *   whatever shows, each piece by its own box (the ERP's tray opens as an absolute child above its `fixed` toggle, so
+ *   the fixed box alone is only the toggle); inside a box as big as the window (an app's fixed frame, a full-screen
+ *   sheet) or a page that does not scroll, a control that is not in a scroller (a sheet's บันทึก, a footer's links).
+ *   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. Once it
+ *   stepped aside on a page it stays there while that place is free (`settleSpot`): a toolbar opening and closing
+ *   does not send it back and forth across the screen.
+ *
+ *   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.
+ *
+ * The arithmetic is pure (bubblePlace.test.ts); `scanColumns` reads the page.
+ */
+export interface Rect {
+    top: number;
+    bottom: number;
+    left: number;
+    right: number;
+}
+export type Side = "right" | "left";
+/** Clear space kept between the bubble and an obstacle, px. */
+export declare const CLEAR = 8;
+/** What moving to the other side costs, in px of climbing — a short lift stays on its side, a long one crosses. */
+export declare const SWITCH_COST = 160;
+/** An obstacle is smaller than this share of the window — a box as big as the page is the page. */
+export declare const OBSTACLE_MAX_AREA = 0.34;
+/**
+ * The bubble's heights (px up from the bottom to its lower edge) an obstacle rules out, as [lo, hi] — for a bubble of
+ * `size` in the column `col`: every obstacle across the column, widened by CLEAR. Pure.
+ */
+export declare function blockedRanges(obstacles: readonly Rect[], col: {
+    left: number;
+    right: number;
+}, 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): {
+    side: Side;
+    y: number;
+};
+/**
+ * Where it stands now, given where it stood: kept while that place is still free and it was chosen for the same wish
+ * (`prev` is null when the wish, the page or the person's own place changed) — else `chooseSpot`. 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 interface PlaceRule {
+    /** "/saraban/edoc-management" — the page and every page under it; `*` one segment, `**` any. */
+    path: string;
+    show: "hide" | Side;
+    /** Up from the bottom, px. */
+    y: number;
+}
+/** A rule's path as a test of a page's path: from its start, ending at a segment's end. Pure; null when malformed. */
+export declare function pathTest(pattern: string): RegExp | null;
+/** The rule for this page — the most specific (the longest path) of those that match; null when none. Pure. */
+export declare function placeFor(pathname: string, rules: readonly PlaceRule[] | null | undefined): PlaceRule | null;
+/**
+ * The page's pieces the bubble must not cover, for each column — sampled every `step` px down it at three points
+ * across, the topmost piece of the page at each (this library's own skipped); one pass, the styles read once:
+ * - 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;
+ * - anything else scrolls with the page, and is not.
+ */
+export declare function scanColumns(cols: readonly {
+    left: number;
+    right: number;
+}[], view: {
+    w: number;
+    h: number;
+}, opts?: {
+    step?: number;
+    extra?: string | null;
+}): Rect[][];

package/dist/ui/chatBubble.d.ts

@@ -1,3 +1,4 @@
+import { type PlaceRule } from "./bubblePlace";
 /** The panel's address: the support host's page, told the realm, signing in by hand-off (no token in the address). */
 export declare function supportFrameUrl(host: string, realmKey: string): string;
 /** Where the panel's เปิดในระบบแจ้งปัญหา may land: the person's chat or their เรื่อง — anything else, their chat. Pure. */
@@ -65,6 +66,18 @@ export declare function bubbleLabel(s: {
     shown: boolean;
     isNew: boolean;
 } | null;
+export interface DeskLook {
+    label?: string;
+    color?: string;
+    /** A path on the support host; null: the chat glyph on the colour. */
+    faceUrl?: string | null;
+    /** Step aside from the page's own floating controls (0.19.6) — the desk's switch; on unless false. */
+    avoid?: boolean;
+    /** A page's own place (0.19.6): hidden there, or started in a corner at a height — the desk's rules. */
+    places?: PlaceRule[];
+}
+/** The face's address for a desk's look: its own path on the support host, the shipped one, or none (the glyph). Pure. */
+export declare function lookFaceUrl(host: string, look: DeskLook | null): string | null;
 /** Open the panel — from the bubble, or from the host app's own button (`openSupportChat`). */
 export declare function openSupportChat(): void;
 /** Fold the panel — it stays loaded, so the chat is there as it was the next time. */
@@ -72,4 +85,6 @@ export declare function closeSupportChat(refocus?: boolean): void;
 /** The bubble, once — hidden until the host's token says somebody is signed in. */
 export declare function mountSupportChat(): void;
 /** Take it away — for a host that unmounts, and for the tests. */
+/** Ask again whether there is a bubble, and what waits (0.19.5) — after a sign-in or a sign-out, or `show` changed. */
+export declare function refreshSupportChat(): Promise<void>;
 export declare function unmountSupportChat(): void;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lightworkai.official/debug-capture",
-  "version": "0.19.4",
+  "version": "0.19.6",
   "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",

package/src/config.ts

@@ -69,8 +69,11 @@ export interface DebugCaptureConfig {
    *            { algorithm: 'HS256', expiresIn: '1h' })
    *
    * The SECRET NEVER REACHES THE BROWSER. This callback fetches the finished
-   * token from your own backend; it is called per request, so cache it on your
-   * side until it is close to expiring.
+   * token from your own backend. Mint a FRESH one on every call — never hand
+   * back a kept one: besides its own reads, the widget signs the person in with
+   * it (the chat panel, the portal, a call), and a sign-in takes a token only
+   * while it is two minutes old, and only once. Sharing one request already in
+   * flight is fine.
    *
    * Returning null means "nobody is signed in" — the panel says so rather than
    * failing.
@@ -232,6 +235,18 @@ export interface ChatOptions {
    * of "แชทกับทีมงาน", or `false` for the button alone.
    */
   label?: string | false;
+  /**
+   * Whether the bubble is for whoever is signed in now (0.19.5) — asked before every read; false: no bubble. For a
+   * host whose own staff should not chat with its support desk, or not on every page. Ask again after a sign-in with
+   * `refreshSupportChat()`.
+   */
+  show?: () => boolean;
+  /**
+   * Out of the page's own way (0.19.6): the bubble steps aside from the page's floating controls — a toolbar, a FAB, a
+   * bottom bar, a fixed sidebar — to the nearest free place. On unless `false`; a CSS selector names more of your own
+   * to keep clear of, whatever their position (`"[data-floating], .my-dock"`). The desk can turn it off too (ปุ่มแชท).
+   */
+  avoid?: boolean | string;
 }
 
 /** The bubble's place, from `chat`: null when it is off. */

package/src/index.ts

@@ -77,7 +77,7 @@ export type { OpenPortalOptions } from "./portal";
  * แชทกับทีม (0.19): `chat` in the config mounts the bubble on install; a host with its own button opens and closes
  * the same panel. The panel is the support host's page, framed — as the tickets are, maintained where they live.
  */
-export { openSupportChat, closeSupportChat, mountSupportChat, unmountSupportChat, supportFrameUrl, badgeText, chatLift, panelHeight } from "./ui/chatBubble";
+export { openSupportChat, closeSupportChat, mountSupportChat, unmountSupportChat, refreshSupportChat, supportFrameUrl, badgeText, chatLift, panelHeight } from "./ui/chatBubble";
 export type { ChatOptions } from "./config";
 
 export type * from "./types";

package/src/ui/bubblePlace.ts

@@ -0,0 +1,258 @@
+/**
+ * WHERE THE BUBBLE MAY STAND (0.19.6) — out of the host page's way, and where its desk says for a page.
+ *
+ * The owner, 2026-11-02, of the ERP's เอกสาร page: "our chat bubble is over the action button on some page or even i move
+ * it out it still over on this menu … but for most of the page it worked fine … any idea to solve this?" — the page's own
+ * toolbar (`fixed right-4 z-40`, a column up most of the right edge) sits where the bubble does, and wherever it was let
+ * go on the right it landed on it again.
+ *
+ *   THE PAGE'S OWN FLOATING CONTROLS ARE OBSTACLES. What is topmost under the bubble's column and stays put while the
+ *   page scrolls: inside a small `fixed` box (or a `sticky` one, stuck) — a toolbar, a FAB, a bottom bar, a sidebar —
+ *   whatever shows, each piece by its own box (the ERP's tray opens as an absolute child above its `fixed` toggle, so
+ *   the fixed box alone is only the toggle); inside a box as big as the window (an app's fixed frame, a full-screen
+ *   sheet) or a page that does not scroll, a control that is not in a scroller (a sheet's บันทึก, a footer's links).
+ *   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. Once it
+ *   stepped aside on a page it stays there while that place is free (`settleSpot`): a toolbar opening and closing
+ *   does not send it back and forth across the screen.
+ *
+ *   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.
+ *
+ * The arithmetic is pure (bubblePlace.test.ts); `scanColumns` reads the page.
+ */
+
+export interface Rect {
+  top: number;
+  bottom: number;
+  left: number;
+  right: number;
+}
+export type Side = "right" | "left";
+
+/** Clear space kept between the bubble and an obstacle, px. */
+export const CLEAR = 8;
+/** What moving to the other side costs, in px of climbing — a short lift stays on its side, a long one crosses. */
+export const SWITCH_COST = 160;
+/** An obstacle is smaller than this share of the window — a box as big as the page is the page. */
+export const OBSTACLE_MAX_AREA = 0.34;
+
+/**
+ * The bubble's heights (px up from the bottom to its lower edge) an obstacle rules out, as [lo, hi] — for a bubble of
+ * `size` in the column `col`: every obstacle across the column, widened by CLEAR. Pure.
+ */
+export function blockedRanges(obstacles: readonly Rect[], col: { left: number; right: number }, viewH: number, size: number): [number, number][] {
+  const out: [number, number][] = [];
+  for (const o of obstacles) {
+    if (o.right <= col.left || o.left >= col.right || o.bottom <= o.top) continue;
+    // The bubble spans viewport [viewH - y - size, viewH - y]; it meets [o.top - CLEAR, o.bottom + CLEAR] when
+    // viewH - y > o.top - CLEAR and viewH - y - size < o.bottom + CLEAR.
+    out.push([viewH - o.bottom - CLEAR - size, viewH - o.top + CLEAR]);
+  }
+  return out.sort((a, b) => a[0] - b[0]);
+}
+
+/** The free height nearest `want` within [min, max], outside every range (open ends) — null when none. Up wins a tie. Pure. */
+export function nearestFreeY(want: number, ranges: readonly [number, number][], min: number, max: number): number | null {
+  if (max < min) return null;
+  const inside = (y: number) => ranges.some(([lo, hi]) => y > lo && y < hi);
+  const clamp = (y: number) => Math.min(Math.max(y, min), max);
+  const w = clamp(want);
+  if (!inside(w)) return w;
+  // The candidates are the ranges' edges (and the bounds) — the nearest free one is among them.
+  const edges = [min, max, ...ranges.flatMap(([lo, hi]) => [lo, hi])].map(clamp).filter((y) => !inside(y));
+  if (!edges.length) return null;
+  return edges.reduce((best, y) => {
+    const d = Math.abs(y - w);
+    const bd = Math.abs(best - w);
+    return d < bd || (d === bd && y > best) ? y : best;
+  });
+}
+
+/**
+ * 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 function chooseSpot(want: { side: Side; y: number }, free: Record<Side, readonly [number, number][]>, min: number, max: number): { side: Side; y: number } {
+  const other: Side = want.side === "right" ? "left" : "right";
+  const here = nearestFreeY(want.y, free[want.side], min, max);
+  const there = nearestFreeY(want.y, free[other], min, max);
+  if (here === null && there === null) return want;
+  const costHere = here === null ? Infinity : Math.abs(here - want.y);
+  const costThere = there === null ? Infinity : SWITCH_COST + Math.abs(there - want.y);
+  return costHere <= costThere ? { side: want.side, y: here! } : { side: other, y: there! };
+}
+
+/**
+ * Where it stands now, given where it stood: kept while that place is still free and it was chosen for the same wish
+ * (`prev` is null when the wish, the page or the person's own place changed) — else `chooseSpot`. Pure.
+ */
+export 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 } {
+  if (prev && nearestFreeY(prev.y, free[prev.side], min, max) === prev.y) return prev;
+  return chooseSpot(want, free, min, max);
+}
+
+/* ── A page's own place: the desk's rules ───────────────────────────────── */
+
+export interface PlaceRule {
+  /** "/saraban/edoc-management" — the page and every page under it; `*` one segment, `**` any. */
+  path: string;
+  show: "hide" | Side;
+  /** Up from the bottom, px. */
+  y: number;
+}
+
+/** A rule's path as a test of a page's path: from its start, ending at a segment's end. Pure; null when malformed. */
+export function pathTest(pattern: string): RegExp | null {
+  if (typeof pattern !== "string" || !pattern.startsWith("/") || pattern.length > 200) return null;
+  const trimmed = pattern.length > 1 ? pattern.replace(/\/+$/, "") : "";
+  const body = trimmed
+    .split(/(\*\*|\*)/)
+    .map((part) => (part === "**" ? ".*" : part === "*" ? "[^/]*" : part.replace(/[.+?^${}()|[\]\\]/g, "\\$&")))
+    .join("");
+  try {
+    return new RegExp(`^${body}(?:/.*)?$`);
+  } catch {
+    return null;
+  }
+}
+
+/** The rule for this page — the most specific (the longest path) of those that match; null when none. Pure. */
+export function placeFor(pathname: string, rules: readonly PlaceRule[] | null | undefined): PlaceRule | null {
+  let best: PlaceRule | null = null;
+  for (const r of rules ?? []) {
+    const test = pathTest(r.path);
+    if (!test || !test.test(pathname)) continue;
+    if (!best || r.path.replace(/\*/g, "").length > best.path.replace(/\*/g, "").length) best = r;
+  }
+  return best;
+}
+
+/* ── Reading the page ──────────────────────────────────────────────────── */
+
+/** This library's own boxes (the bubble, the call's ring and frame, the toasts): never obstacles. */
+const OURS = /^LW-/;
+/** What a hand presses — a piece of a page that must never be covered. */
+const CONTROL =
+  'a[href],button,input,select,textarea,summary,label,[role="button"],[role="link"],[role="tab"],[role="menuitem"],[role="checkbox"],[role="switch"],[role="radio"],[role="option"],[role="slider"],[role="combobox"],[role="textbox"],[contenteditable=""],[contenteditable="true"],[tabindex]:not([tabindex="-1"])';
+const SCROLLS = /(auto|scroll|overlay)/;
+
+/**
+ * The page's pieces the bubble must not cover, for each column — sampled every `step` px down it at three points
+ * across, the topmost piece of the page at each (this library's own skipped); one pass, the styles read once:
+ * - 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;
+ * - anything else scrolls with the page, and is not.
+ */
+export function scanColumns(cols: readonly { left: number; right: number }[], view: { w: number; h: number }, opts: { step?: number; extra?: string | null } = {}): Rect[][] {
+  if (typeof document === "undefined" || typeof document.elementsFromPoint !== "function") return cols.map(() => []);
+  const step = opts.step ?? 12;
+  const html = document.documentElement;
+  const body = document.body;
+  const styles = new Map<Element, CSSStyleDeclaration>();
+  const style = (el: Element) => styles.get(el) ?? (styles.set(el, getComputedStyle(el)), styles.get(el)!);
+  const area = view.w * view.h;
+  const big = (r: { width: number; height: number }) => r.width * r.height > OBSTACLE_MAX_AREA * area || (r.width >= view.w * 0.9 && r.height >= view.h * 0.9);
+  const scrolls = (n: Element) => {
+    const s = style(n);
+    return (SCROLLS.test(s.overflowY) && n.scrollHeight > n.clientHeight + 1) || (SCROLLS.test(s.overflowX) && n.scrollWidth > n.clientWidth + 1);
+  };
+  const se = document.scrollingElement ?? html;
+  const pageScrolls = se.scrollHeight > se.clientHeight + 1 && style(html).overflowY !== "hidden" && (!body || style(body).overflowY !== "hidden");
+  /** A sticky box at the edge it sticks to — of its own scroller, or of the window. */
+  const stuck = (n: Element, s: CSSStyleDeclaration) => {
+    let port = { top: 0, bottom: view.h };
+    for (let p = n.parentElement; p && p !== html && p !== body; p = p.parentElement) {
+      const ps = style(p);
+      if (ps.overflowY !== "visible" && ps.overflowY !== "clip") {
+        const r = p.getBoundingClientRect();
+        port = { top: r.top, bottom: r.bottom };
+        break;
+      }
+    }
+    const r = n.getBoundingClientRect();
+    const top = parseFloat(s.top);
+    const bottom = parseFloat(s.bottom);
+    return (!Number.isNaN(bottom) && r.bottom >= port.bottom - bottom - 1) || (!Number.isNaN(top) && r.top <= port.top + top + 1);
+  };
+  /** Its nearest floating box, whether a scroller lies between, and how much of it shows. */
+  const pinOf = (el: Element) => {
+    let float: Element | null = null;
+    let scrolled = false;
+    let opacity = 1;
+    for (let n: Element | null = el; n && n !== html && n !== body; n = n.parentElement) {
+      const s = style(n);
+      const o = parseFloat(s.opacity);
+      if (!Number.isNaN(o)) opacity *= o;
+      if (s.position === "fixed" || (s.position === "sticky" && stuck(n, s))) {
+        float = n;
+        break;
+      }
+      if (n !== el && scrolls(n)) scrolled = true;
+    }
+    if (!float && pageScrolls) scrolled = true;
+    return { float, scrolled, opacity };
+  };
+  const pins = new Map<Element, ReturnType<typeof pinOf>>();
+  return cols.map((col) => {
+    const seen = new Set<Element>();
+    const kept = new Set<Element>();
+    const out: Rect[] = [];
+    const keep = (el: Element) => {
+      if (kept.has(el)) return;
+      kept.add(el);
+      const r = el.getBoundingClientRect();
+      if (r.width > 0 && r.height > 0)
+        out.push({
+          top: r.top,
+          bottom: r.bottom,
+          left: r.left,
+          right: r.right,
+        });
+    };
+    const xs = [col.left + 6, (col.left + col.right) / 2, col.right - 6];
+    for (let y = step / 2; y < view.h; y += step) {
+      for (const x of xs) {
+        const top = document.elementsFromPoint(x, y).find((e) => !OURS.test(e.tagName));
+        if (!top || top === html || top === body || seen.has(top)) continue;
+        seen.add(top);
+        if (opts.extra) {
+          let named: Element | null = null;
+          try {
+            named = top.closest(opts.extra);
+          } catch {
+            named = null;
+          }
+          if (named) {
+            keep(named);
+            continue;
+          }
+        }
+        const { float, scrolled, opacity } = pins.get(top) ?? (pins.set(top, pinOf(top)), pins.get(top)!);
+        if (opacity < 0.05) continue;
+        const control = top.closest(CONTROL);
+        const own = control && (!float || float.contains(control)) ? control : null;
+        if (float && !big(float.getBoundingClientRect())) {
+          const piece = own ?? top;
+          if (!big(piece.getBoundingClientRect())) keep(piece);
+          continue;
+        }
+        // The page itself — a scrolling page, or what is in a frame as big as the window: only a control that stays put.
+        if (scrolled || !own || big(own.getBoundingClientRect())) continue;
+        keep(own);
+      }
+    }
+    return out;
+  });
+}