@lightworkai.official/debug-capture 0.15.0 → 0.17.0

package/src/live.ts

@@ -9,10 +9,14 @@
  * for the host's signed token at `/ingest/live-ticket`, told about their own
  * requests and calls and nothing else — and a call rings here as a card.
  *
- * Answering happens on the support host, where the call's media lives: the
- * card's button opens the reporter's request there, signed in by the same
- * hand-off the portal button uses — a tab opened INSIDE the press (a browser
- * allows nothing later), its address set once the token is in hand.
+ * Answering happens in THIS app since 0.16 (`callFrame`, default on): the
+ * support host's own call — ring card, call corner, screen sharing, voice
+ * settings — opens in a frame here (ui/callFrame), signed in by the same
+ * token the portal button uses; our card steps aside once the frame is up,
+ * and comes back if it never does. Before 0.16, and with `callFrame: false`,
+ * the card's button opens the reporter's request on the support host — a tab
+ * opened INSIDE the press (a browser allows nothing later), its address set
+ * once the token is in hand.
  *
  * Quiet by design. No identity, calls off, a support host older than this
  * package, a token refused: no socket, no card, nothing in the console — the
@@ -20,7 +24,8 @@
  */
 import { getConfig } from "./config";
 import { preparePortalUrl } from "./portal";
-import { hideRing, ringOpened, ringShownFor, showRing } from "./ui/ring";
+import { hideRing, quietRing, ringOpened, ringShownFor, showRing } from "./ui/ring";
+import { callFrameFor, closeCallFrame, frameUrl, openCallFrame } from "./ui/callFrame";
 
 export interface RingingCall {
   id: string;
@@ -33,6 +38,7 @@ export interface RingingCall {
 }
 
 const RETRY_MS = [2000, 5000, 15_000, 30_000, 60_000];
+const LIVE_STATES = new Set(["ringing", "active"]);
 const PING_MS = 20_000;
 
 let started = false;
@@ -109,6 +115,7 @@ export function stopLiveRing(): void {
   }
   socket = null;
   hideRing();
+  closeCallFrame();
 }
 
 function schedule(slow = false): void {
@@ -178,10 +185,67 @@ async function connect(): Promise<void> {
   };
 }
 
-/** The support host's word on a call: ringing here shows the card; anything else takes it away. */
+/** The call this tab holds in its frame — taken back after a reload, so the call goes on. */
+const FRAMED_KEY = "lw-call-framed";
+function framedHere(): string | null {
+  try {
+    return sessionStorage.getItem(FRAMED_KEY);
+  } catch {
+    return null;
+  }
+}
+function markFramed(id: string | null): void {
+  try {
+    if (id) sessionStorage.setItem(FRAMED_KEY, id);
+    else sessionStorage.removeItem(FRAMED_KEY);
+  } catch {
+    /* this tab only, when it can */
+  }
+}
+
+let framing: string | null = null;
+/** The call in a frame here (0.16): the support host's own call UI, signed in with the host's token. */
+async function frameFor(call: RingingCall): Promise<void> {
+  const config = getConfig();
+  if (config.callFrame === false || callFrameFor() === call.id || framing === call.id) return;
+  framing = call.id;
+  const token = await hostToken();
+  framing = null;
+  if (!token) return;
+  markFramed(call.id);
+  openCallFrame(frameUrl(config.host, config.realmKey, token, call.id), call.id, {
+    ready: () => quietRing(call.id),
+    done: () => {
+      markFramed(null);
+      hideRing(call.id);
+    },
+    // Our card carries the call again — still ringing, its button opens the portal to answer.
+    failed: () => {
+      markFramed(null);
+      quietRing(call.id, false);
+    },
+  });
+}
+
+/** The support host's word on a call: ringing here shows the card (and its frame); anything else takes the card away — the frame stays, it IS the call. */
 function hear(call: RingingCall): void {
-  if (!ringsHere(call)) return hideRing(call.id);
+  if (!ringsHere(call)) {
+    hideRing(call.id);
+    // Answered in this tab's frame, then the page reloaded: the frame comes back and takes the call back.
+    if (call.status === "active" && framedHere() === call.id && !callFrameFor()) void frameFor(call);
+    // Over: the frame says its last word and goes — and goes anyway if it cannot.
+    if (!LIVE_STATES.has(call.status) && callFrameFor() === call.id) {
+      setTimeout(() => {
+        if (callFrameFor() === call.id) {
+          closeCallFrame();
+          markFramed(null);
+        }
+      }, 12_000);
+    }
+    return;
+  }
   showRing(call, { open: () => answer(call), decline: () => void decline(call) });
+  void frameFor(call);
   // Never longer than it rings: a socket that dropped mid-ring must not leave a card up for good.
   clearTimeout(expiry);
   const left = new Date(call.ringUntil).getTime() - Date.now();

package/src/ui/callFrame.ts

@@ -0,0 +1,272 @@
+/**
+ * The call, in this app — the support host's own call UI in a frame (0.16; the support host's docs/CALLS-PLAN.md §15).
+ *
+ * A reporter used to answer in a new tab on the support host: a hand-off, a popup a browser might block, and the app
+ * with the problem left behind just when the team asks to see it. Now the support host's `/embed/call` opens here, in a
+ * frame of our own — the same ring card, call corner, screen-sharing question and voice settings as its portal, so
+ * they never drift apart — signed in by the token the portal button uses, given the microphone, camera and screen.
+ *
+ * The frame says how to hold it (its messages, below): ready, its size and whether a moment covers the page, a drag
+ * of its top line, done, failed. We listen only to that frame's own window, from the support host's origin.
+ *
+ * Its own shadow root, like the ring card: it lands on pages we do not control. Marked as ours, so a report filed
+ * during a call does not photograph it.
+ *
+ * And the team's marks (0.17, ชี้ · วาด · กรอบ): the frame hands each one up (`ink`) and ui/inkOverlay draws it over
+ * the page. So the call can tell whether the tab being shared is this one — where the marks can be seen — this page
+ * is named for the call while it lasts (Capture Handle, Chrome and Edge: `lw-call:<id>`, readable by the support host
+ * only); the frame compares it with what it captured.
+ */
+import { readInkOp } from "../ink";
+import { inkOnPage, removeInkLayer } from "./inkOverlay";
+
+const HOST_TAG = "lw-call-frame";
+const SOURCE = "lw-call";
+const MARGIN = 16;
+/** The call corner's width — the support host's dock, plus the frame's room for its shadow. */
+const CARD_WIDTH = 368;
+
+export type FrameLayout = "card" | "full";
+export interface FrameMessage {
+  source?: string;
+  type?: string;
+  width?: number;
+  height?: number;
+  layout?: FrameLayout;
+  phase?: "start" | "move" | "end";
+  x?: number;
+  y?: number;
+  reason?: string;
+  op?: unknown;
+}
+export interface FrameHandlers {
+  /** The call is on screen in the frame. */
+  ready(): void;
+  /** Nothing left to show — the frame is gone already. */
+  done(): void;
+  /** It could not sign in or never came up — the frame is gone; the caller's own card carries the call. */
+  failed(reason: string): void;
+}
+
+let host: HTMLElement | null = null;
+let frame: HTMLIFrameElement | null = null;
+let callId: string | null = null;
+let origin = "";
+let handlers: FrameHandlers | null = null;
+let layout: FrameLayout = "card";
+let size = { width: CARD_WIDTH, height: 0 };
+let readyTimer: ReturnType<typeof setTimeout> | undefined;
+let isReady = false;
+/** Where the corner was moved to (left, top), or null: bottom right. Kept for this tab. */
+let placed: { x: number; y: number } | null = null;
+let drag: { sx: number; sy: number; x: number; y: number } | null = null;
+const PLACE_KEY = "lw-call-frame-place";
+
+/** The support host's page for this call. Pure, for the tests. */
+export function frameUrl(supportHost: string, realmKey: string, token: string, id: string): string {
+  const url = new URL("embed/call", supportHost.endsWith("/") ? supportHost : `${supportHost}/`);
+  url.searchParams.set("realm", realmKey);
+  url.searchParams.set("token", token);
+  url.searchParams.set("call", id);
+  return url.toString();
+}
+
+/** Within the window, by at least the margin — a corner dragged off screen comes back. Pure, for the tests. */
+export function clampTo(p: { x: number; y: number }, box: { w: number; h: number }, view: { w: number; h: number }): { x: number; y: number } {
+  return {
+    x: Math.min(Math.max(p.x, MARGIN / 2), Math.max(MARGIN / 2, view.w - box.w - MARGIN / 2)),
+    y: Math.min(Math.max(p.y, MARGIN / 2), Math.max(MARGIN / 2, view.h - box.h - MARGIN / 2)),
+  };
+}
+
+/** Is this message from our frame, about the call? */
+export function fromFrame(e: { origin: string; source: unknown; data: unknown }, expected: { origin: string; window: unknown }): FrameMessage | null {
+  if (e.origin !== expected.origin || e.source !== expected.window) return null;
+  const d = e.data as FrameMessage | null;
+  return d && typeof d === "object" && d.source === SOURCE && typeof d.type === "string" ? d : null;
+}
+
+export function callFrameFor(): string | null {
+  return host?.isConnected ? callId : null;
+}
+
+/** Open the call's frame — once per call; the same call again changes nothing. Shown when it says it is ready. */
+export function openCallFrame(src: string, id: string, h: FrameHandlers, readyWithinMs = 15_000): void {
+  if (typeof document === "undefined") return;
+  if (callId === id && host?.isConnected) return;
+  closeCallFrame();
+  callId = id;
+  handlers = h;
+  isReady = false;
+  layout = "card";
+  size = { width: CARD_WIDTH, height: 0 };
+  origin = new URL(src).origin;
+  try {
+    placed = JSON.parse(sessionStorage.getItem(PLACE_KEY) ?? "null");
+  } catch {
+    placed = null;
+  }
+  host = document.createElement(HOST_TAG);
+  host.dataset.debugReporter = "true";
+  const root = host.attachShadow({ mode: "open" });
+  const style = document.createElement("style");
+  style.textContent = `:host { all: initial; }
+iframe { position: fixed; z-index: 2147483003; border: 0; background: transparent; color-scheme: normal; visibility: hidden; }
+iframe.on { visibility: visible; }`;
+  frame = document.createElement("iframe");
+  // What a call needs: to hear and be heard, to show a face or a screen, to play the other side's voice.
+  frame.allow = "microphone; camera; display-capture; autoplay; clipboard-write; fullscreen";
+  frame.title = "สายจากทีมงาน";
+  frame.dataset.lwCallFrame = id;
+  frame.setAttribute("allowtransparency", "true");
+  frame.src = src;
+  root.append(style, frame);
+  document.body.append(host);
+  place();
+  window.addEventListener("message", onMessage);
+  window.addEventListener("resize", place);
+  nameTab(`lw-call:${id}`);
+  // Never came up — a host that forbids the frame, a network that dropped it: the caller's card carries the call.
+  readyTimer = setTimeout(() => {
+    if (!isReady) fail("timeout");
+  }, readyWithinMs);
+}
+
+export function closeCallFrame(): void {
+  if (host) nameTab(null);
+  removeInkLayer();
+  clearTimeout(readyTimer);
+  window.removeEventListener("message", onMessage);
+  window.removeEventListener("resize", place);
+  host?.remove();
+  host = null;
+  frame = null;
+  callId = null;
+  handlers = null;
+  drag = null;
+}
+
+function fail(reason: string): void {
+  const h = handlers;
+  closeCallFrame();
+  h?.failed(reason);
+}
+
+function onMessage(e: MessageEvent): void {
+  if (!frame) return;
+  const m = fromFrame(e, { origin, window: frame.contentWindow });
+  if (!m) return;
+  switch (m.type) {
+    case "ready":
+      isReady = true;
+      clearTimeout(readyTimer);
+      frame.classList.add("on");
+      handlers?.ready();
+      return;
+    case "size":
+      if (typeof m.width === "number" && typeof m.height === "number") size = { width: m.width, height: m.height };
+      if (m.layout === "card" || m.layout === "full") {
+        // About to cover the page: the call is told where its corner is, so it stays there while the frame grows.
+        if (m.layout === "full" && layout === "card") tellCorner();
+        layout = m.layout;
+      }
+      return place();
+    case "drag":
+      return onDrag(m);
+    case "home":
+      placed = null;
+      savePlace();
+      return place();
+    case "done": {
+      const h = handlers;
+      closeCallFrame();
+      h?.done();
+      return;
+    }
+    case "failed":
+      return fail(m.reason ?? "failed");
+    case "ink": {
+      // Read again here — never drawn as received.
+      const op = readInkOp(m.op);
+      if (op) inkOnPage(op);
+      return;
+    }
+  }
+}
+
+/**
+ * This page, named for the call while it lasts — so a screen shared from the call's frame can be told to be THIS tab
+ * (`MediaStreamTrack.getCaptureHandle()`), where the team's marks show. Only the support host may read the name; a
+ * browser without Capture Handle simply has no name to give, and the call says it cannot tell.
+ */
+type CaptureHandleConfig = { handle?: string; exposeOrigin?: boolean; permittedOrigins?: string[] };
+function nameTab(handle: string | null): void {
+  const md = (typeof navigator === "undefined" ? undefined : navigator.mediaDevices) as (MediaDevices & { setCaptureHandleConfig?: (c: CaptureHandleConfig) => void }) | undefined;
+  try {
+    md?.setCaptureHandleConfig?.(handle ? { handle, exposeOrigin: false, permittedOrigins: [origin] } : {});
+  } catch {
+    /* not a top-level page, or not this browser */
+  }
+}
+
+/** The corner moved by its top line: from where the press began, by how far the pointer went on the screen. */
+function onDrag(m: FrameMessage): void {
+  if (!frame || layout !== "card" || typeof m.x !== "number" || typeof m.y !== "number") return;
+  if (m.phase === "start") {
+    const r = frame.getBoundingClientRect();
+    drag = { sx: m.x, sy: m.y, x: r.left, y: r.top };
+    return;
+  }
+  if (!drag) return;
+  placed = clampTo({ x: drag.x + (m.x - drag.sx), y: drag.y + (m.y - drag.sy) }, boxOf(), viewOf());
+  place();
+  if (m.phase === "end") {
+    drag = null;
+    savePlace();
+  }
+}
+
+/** Where the corner is on the page — the frame asks nothing else of us, and is told nothing else. */
+function tellCorner(): void {
+  if (!frame?.contentWindow) return;
+  const r = frame.getBoundingClientRect();
+  frame.contentWindow.postMessage({ source: "lw-call-host", type: "corner", x: Math.round(r.left), y: Math.round(r.top), width: Math.round(r.width) }, origin);
+}
+
+function savePlace(): void {
+  try {
+    if (placed) sessionStorage.setItem(PLACE_KEY, JSON.stringify(placed));
+    else sessionStorage.removeItem(PLACE_KEY);
+  } catch {
+    /* this tab only, when it can */
+  }
+}
+
+const viewOf = () => ({ w: window.innerWidth, h: window.innerHeight });
+/**
+ * The corner: always the dock's width — the call fills whatever width it is given, so a width it reported while it
+ * had the whole window must never come back as the corner's (measured: 1264 px after a screen share) — and the
+ * height it says it needs.
+ */
+function boxOf(): { w: number; h: number } {
+  const view = viewOf();
+  return { w: Math.min(CARD_WIDTH, view.w - MARGIN), h: Math.min(size.height || 0, view.h - MARGIN) };
+}
+
+/** The whole window for a moment that covers it; otherwise the corner — bottom right, or where it was moved. */
+function place(): void {
+  if (!frame) return;
+  const s = frame.style;
+  if (layout === "full") {
+    Object.assign(s, { left: "0px", top: "0px", right: "", bottom: "", width: "100vw", height: "100vh" });
+    return;
+  }
+  const box = boxOf();
+  const narrow = viewOf().w < 480;
+  s.width = narrow ? `calc(100vw - ${MARGIN}px)` : `${box.w}px`;
+  s.height = `${box.h}px`;
+  if (placed && !narrow) {
+    const p = clampTo(placed, box, viewOf());
+    Object.assign(s, { left: `${p.x}px`, top: `${p.y}px`, right: "", bottom: "" });
+  } else Object.assign(s, { left: narrow ? `${MARGIN / 2}px` : "", top: "", right: narrow ? "" : `${MARGIN / 2}px`, bottom: `${MARGIN / 2}px` });
+}

package/src/ui/inkOverlay.ts

@@ -0,0 +1,59 @@
+/**
+ * The team's marks on this page (0.17) — ชี้ · วาด · กรอบ, drawn by the support team on the screen this person is
+ * sharing with them, shown here where they are working (the support host's docs/CALLS-PLAN.md §17).
+ *
+ * The call lives in its frame in a corner (ui/callFrame), which cannot draw outside itself; it hands each mark up and
+ * this layer draws it over the whole page: never in the way (no pointer events — every click goes to the app beneath),
+ * gone when the marks fade, and taken away with the call. The same drawing as the support host's (../ink). Marked as
+ * ours, so a report filed meanwhile does not photograph it.
+ *
+ * It covers the page exactly as the shared picture does: a tab is shared as its viewport, so a mark at a fraction of
+ * the picture is at that fraction of the window.
+ */
+import { InkPainter, InkScene, type InkOp } from "../ink";
+
+const HOST_TAG = "lw-call-ink";
+
+let host: HTMLElement | null = null;
+let scene: InkScene | null = null;
+let painter: InkPainter | null = null;
+
+function mount(): void {
+  if (host?.isConnected && painter) return;
+  host = document.createElement(HOST_TAG);
+  host.dataset.debugReporter = "true";
+  const root = host.attachShadow({ mode: "open" });
+  const style = document.createElement("style");
+  // Over the page and its scrollbar, as the shared picture is; under the call's own frame.
+  style.textContent = `:host { all: initial; }
+canvas { position: fixed; left: 0; top: 0; width: 100vw; height: 100vh; pointer-events: none; z-index: 2147483002; }`;
+  const canvas = document.createElement("canvas");
+  canvas.setAttribute("aria-hidden", "true");
+  canvas.dataset.lwCallInk = "";
+  root.append(style, canvas);
+  document.body.append(host);
+  scene = new InkScene();
+  painter = new InkPainter(canvas, scene, () => ({ w: window.innerWidth, h: window.innerHeight }));
+}
+
+/** A mark from the team, as the call's frame handed it up (already read by `readInkOp`). */
+export function inkOnPage(op: InkOp): void {
+  if (typeof document === "undefined") return;
+  if (op.op === "clear" && !host) return;
+  mount();
+  scene!.apply(op);
+  painter!.kick();
+}
+
+export function inkMarksOnPage(): number {
+  return scene?.size ?? 0;
+}
+
+/** The call is over: the layer goes. */
+export function removeInkLayer(): void {
+  painter?.stop();
+  host?.remove();
+  host = null;
+  scene = null;
+  painter = null;
+}

package/src/ui/ring.ts

@@ -185,6 +185,16 @@ export function ringOpened(blockedUrl?: string): void {
   }
 }
 
+/**
+ * The call's own frame is up (ui/callFrame, 0.16): its ring card is the one to press, so ours steps out of sight —
+ * the ring and the title stay, rung from this page, until the call stops ringing. `false` brings ours back (the frame
+ * failed: our card carries the call again).
+ */
+export function quietRing(id: string, quiet = true): void {
+  if (!host?.isConnected || shownId !== id) return;
+  host.style.display = quiet ? "none" : "";
+}
+
 /** The call is no longer ringing for this person — answered, declined, missed or ended. */
 export function hideRing(id?: string): void {
   if (id && shownId && id !== shownId) return;