@lightworkai.official/debug-capture 0.17.1 → 0.17.2

package/dist/ui/callFrame.d.ts

@@ -19,8 +19,15 @@ export interface FrameHandlers {
     /** 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;
 }
-/** The support host's page for this call. Pure, for the tests. */
-export declare function frameUrl(supportHost: string, realmKey: string, token: string, id: string): string;
+/**
+ * The support host's page for this call. Pure, for the tests. Without a token (0.17.2): `hand=1` — the page asks for it
+ * by message, so it can load while the host is still fetching it.
+ */
+export declare function frameUrl(supportHost: string, realmKey: string, token: string | null, id: string): string;
+/** รับสาย pressed on our card: the frame answers the moment it is ready — now, if it is. */
+export declare function answerInFrame(id: string): void;
+/** ทดสอบไมค์และลำโพง pressed on our card: the frame's voice settings, the moment it is ready. */
+export declare function voiceInFrame(id: string): void;
 /** Within the window, by at least the margin — a corner dragged off screen comes back. Pure, for the tests. */
 export declare function clampTo(p: {
     x: number;
@@ -46,5 +53,5 @@ export declare function fromFrame(e: {
 }): FrameMessage | null;
 export declare function callFrameFor(): string | null;
 /** Open the call's frame — once per call; the same call again changes nothing. Shown when it says it is ready. */
-export declare function openCallFrame(src: string, id: string, h: FrameHandlers, readyWithinMs?: number): void;
+export declare function openCallFrame(src: string, id: string, h: FrameHandlers, readyWithinMs?: number, token?: Promise<string | null> | null): void;
 export declare function closeCallFrame(): void;

package/dist/ui/ring.d.ts

@@ -4,14 +4,24 @@ export interface RingCall {
     ticketTitle: string;
 }
 export interface RingHandlers {
-    /** Runs INSIDE the press: a tab can be opened only there, before anything is awaited. */
+    /** The portal's way: runs INSIDE the press — a tab can be opened only there, before anything is awaited. */
     open: () => void;
     decline: () => void;
+    /** The call's frame is coming (0.17.2): รับสาย here — the frame answers the moment it is ready. */
+    answer?: () => void;
+    /** …and ทดสอบไมค์และลำโพง — the frame's voice settings, the moment it is ready. */
+    voice?: () => void;
 }
+/** `frame`: the call's own card while its frame comes; `portal`: answer in a new tab (no frame, or it failed). */
+export type RingMode = "frame" | "portal";
 /** "เรื่อง CALL-12 · title" — the line under the card's title. Pure, for the tests. */
 export declare function ringAbout(template: string, call: RingCall): string;
 /** Show the ring for this call — once; the same call again changes nothing. */
-export declare function showRing(call: RingCall, handlers: RingHandlers): void;
+export declare function showRing(call: RingCall, handlers: RingHandlers, mode?: RingMode): void;
+/** รับสาย pressed while the call's frame comes: said, and nothing more to press until it is there. */
+export declare function ringAnswering(id: string): void;
+/** The call's frame could not come up: the same card, now the portal's way — a new tab, which needs a fresh press. */
+export declare function ringFallback(call: RingCall, handlers: RingHandlers): void;
 /** Opened: the card says where to answer, and stops ringing. `blockedUrl` — the browser refused the tab: a link, which is a fresh press. */
 export declare function ringOpened(blockedUrl?: string): void;
 /**

package/dist/ui/strings.d.ts

@@ -113,5 +113,12 @@ export interface Strings {
     ringBlocked: string;
     ringClose: string;
     ringTab: string;
+    /** The call's own card, while its frame is coming (0.17.2): the same words as the support host's ring card. */
+    ringHint: string;
+    ringTest: string;
+    ringAnswer: string;
+    ringAnswering: string;
+    /** The frame could not come up: answer in a new tab instead. */
+    ringFallback: string;
 }
 export declare function strings(locale: "th" | "en" | undefined): Strings;

package/package.json

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

@@ -24,8 +24,8 @@
  */
 import { getConfig } from "./config";
 import { preparePortalUrl } from "./portal";
-import { hideRing, quietRing, ringOpened, ringShownFor, showRing } from "./ui/ring";
-import { callFrameFor, closeCallFrame, frameUrl, openCallFrame } from "./ui/callFrame";
+import { hideRing, quietRing, ringAnswering, ringFallback, ringOpened, ringShownFor, showRing, type RingHandlers } from "./ui/ring";
+import { answerInFrame, callFrameFor, closeCallFrame, frameUrl, openCallFrame, voiceInFrame } from "./ui/callFrame";
 
 export interface RingingCall {
   id: string;
@@ -98,6 +98,7 @@ export function startLiveRing(): void {
   if (!config.identity || config.ring === false) return;
   started = true;
   stopped = false;
+  warmUp(config.host);
   void connect();
 }
 
@@ -203,36 +204,62 @@ function markFramed(id: string | null): void {
   }
 }
 
-let framing: string | null = null;
+/**
+ * The support host, met before the first ring (0.17.2): its name looked up and its connection made while the page is
+ * idle, so the call's frame does not start with them. A hint the browser may ignore; nothing is fetched.
+ */
+let warmed = false;
+function warmUp(supportHost: string): void {
+  if (warmed || typeof document === "undefined") return;
+  warmed = true;
+  try {
+    const href = new URL(supportHost).origin;
+    for (const rel of ["dns-prefetch", "preconnect"]) {
+      const link = document.createElement("link");
+      link.rel = rel;
+      link.href = href;
+      if (rel === "preconnect") link.crossOrigin = "anonymous";
+      link.dataset.debugReporter = "true";
+      document.head.append(link);
+    }
+  } catch {
+    /* not a host we can name */
+  }
+}
+
 /** 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> {
+function frameFor(call: RingingCall): 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;
+  if (config.callFrame === false || callFrameFor() === call.id) 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);
+  // At once (0.17.2): the frame loads while the host fetches its token — handed over when the frame says hello.
+  openCallFrame(
+    frameUrl(config.host, config.realmKey, null, call.id),
+    call.id,
+    {
+      ready: () => quietRing(call.id),
+      done: () => {
+        markFramed(null);
+        hideRing(call.id);
+      },
+      // The same card, now the portal's way: a new tab — a fresh press, since one cannot be opened after a wait.
+      failed: () => {
+        markFramed(null);
+        ringFallback(call, portalWay(call));
+      },
     },
-    // Our card carries the call again — still ringing, its button opens the portal to answer.
-    failed: () => {
-      markFramed(null);
-      quietRing(call.id, false);
-    },
-  });
+    15_000,
+    hostToken(),
+  );
 }
+const portalWay = (call: RingingCall): RingHandlers => ({ open: () => answer(call), decline: () => void decline(call) });
 
 /** 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)) {
     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);
+    if (call.status === "active" && framedHere() === call.id && !callFrameFor()) 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(() => {
@@ -244,8 +271,23 @@ function hear(call: RingingCall): void {
     }
     return;
   }
-  showRing(call, { open: () => answer(call), decline: () => void decline(call) });
-  void frameFor(call);
+  if (getConfig().callFrame === false) showRing(call, portalWay(call), "portal");
+  else {
+    // The call's own card from the first moment — รับสาย pressed before its frame is up is kept, and done when it is.
+    showRing(
+      call,
+      {
+        ...portalWay(call),
+        answer: () => {
+          ringAnswering(call.id);
+          answerInFrame(call.id);
+        },
+        voice: () => voiceInFrame(call.id),
+      },
+      "frame",
+    );
+    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

@@ -12,6 +12,11 @@
  * 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 at once (0.17.2, the support host's §20): the owner, "it shows [the widget's card] a few seconds then turns into
+ * [the call's card] — why". The frame used to wait for the host's token before it began to load. Now it opens the
+ * moment the call rings and says `hello`; the token follows by message when the host gives it (and is never in an
+ * address). A รับสาย pressed on our card meanwhile is kept and passed on the moment the frame is ready (`answer`).
+ *
  * 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
@@ -39,6 +44,8 @@ export interface FrameMessage {
   reason?: string;
   op?: unknown;
 }
+/** What we tell the frame: where its corner is, the host's token, and a press it should act on. */
+type HostMessage = { type: "corner"; x: number; y: number; width: number } | { type: "token"; token: string } | { type: "answer" } | { type: "voice" };
 export interface FrameHandlers {
   /** The call is on screen in the frame. */
   ready(): void;
@@ -57,21 +64,47 @@ let layout: FrameLayout = "card";
 let size = { width: CARD_WIDTH, height: 0 };
 let readyTimer: ReturnType<typeof setTimeout> | undefined;
 let isReady = false;
+/** The host's token, on its way since the call rang — handed to the frame when it says hello (0.17.2). */
+let tokenOnItsWay: Promise<string | null> | null = null;
+/** Presses on our card while the frame was coming: passed on once it is ready. */
+let pending: { answer: boolean; voice: boolean } = { answer: false, voice: 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;
 /** A drag of the call's top line: where the press began (screen), where the frame was, and the last place it was moved to. */
 let drag: { sx: number; sy: number; x: number; y: number; lx: number; ly: 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 {
+/**
+ * The support host's page for this call. Pure, for the tests. Without a token (0.17.2): `hand=1` — the page asks for it
+ * by message, so it can load while the host is still fetching it.
+ */
+export function frameUrl(supportHost: string, realmKey: string, token: string | null, id: string): string {
   const url = new URL("embed/call", supportHost.endsWith("/") ? supportHost : `${supportHost}/`);
   url.searchParams.set("realm", realmKey);
-  url.searchParams.set("token", token);
+  if (token) url.searchParams.set("token", token);
+  else url.searchParams.set("hand", "1");
   url.searchParams.set("call", id);
   return url.toString();
 }
 
+/** Tell the frame something — only the support host's origin may read it. */
+function tellFrame(m: HostMessage): void {
+  frame?.contentWindow?.postMessage({ source: "lw-call-host", ...m }, origin);
+}
+
+/** รับสาย pressed on our card: the frame answers the moment it is ready — now, if it is. */
+export function answerInFrame(id: string): void {
+  if (callId !== id) return;
+  pending.answer = true;
+  if (isReady) tellFrame({ type: "answer" });
+}
+/** ทดสอบไมค์และลำโพง pressed on our card: the frame's voice settings, the moment it is ready. */
+export function voiceInFrame(id: string): void {
+  if (callId !== id) return;
+  pending.voice = true;
+  if (isReady) tellFrame({ type: "voice" });
+}
+
 /** 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 {
@@ -92,13 +125,15 @@ export function callFrameFor(): string | 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 {
+export function openCallFrame(src: string, id: string, h: FrameHandlers, readyWithinMs = 15_000, token: Promise<string | null> | null = null): void {
   if (typeof document === "undefined") return;
   if (callId === id && host?.isConnected) return;
   closeCallFrame();
   callId = id;
   handlers = h;
   isReady = false;
+  tokenOnItsWay = token;
+  pending = { answer: false, voice: false };
   layout = "card";
   size = { width: CARD_WIDTH, height: 0 };
   origin = new URL(src).origin;
@@ -146,6 +181,8 @@ export function closeCallFrame(): void {
   callId = null;
   handlers = null;
   drag = null;
+  tokenOnItsWay = null;
+  pending = { answer: false, voice: false };
 }
 
 function fail(reason: string): void {
@@ -159,11 +196,22 @@ function onMessage(e: MessageEvent): void {
   const m = fromFrame(e, { origin, window: frame.contentWindow });
   if (!m) return;
   switch (m.type) {
+    case "hello":
+      // The page is up and asks for the host's token (it was not in its address): given when the host has it.
+      void tokenOnItsWay?.then((token) => {
+        if (!frame || callId === null) return;
+        if (token) tellFrame({ type: "token", token });
+        else fail("no_token");
+      });
+      return;
     case "ready":
       isReady = true;
       clearTimeout(readyTimer);
       frame.classList.add("on");
       handlers?.ready();
+      // What was pressed on our card while it came: done now.
+      if (pending.answer) tellFrame({ type: "answer" });
+      if (pending.voice) tellFrame({ type: "voice" });
       return;
     case "size":
       if (typeof m.width === "number" && typeof m.height === "number") size = { width: m.width, height: m.height };
@@ -260,7 +308,7 @@ function followHere(on: boolean): void {
 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);
+  tellFrame({ type: "corner", x: Math.round(r.left), y: Math.round(r.top), width: Math.round(r.width) });
 }
 
 function savePlace(): void {

package/src/ui/ring.ts

@@ -17,48 +17,70 @@ import { strings } from "./strings";
 
 const HOST_TAG = "lw-call-ring";
 
+/*
+ * The support host's own ring card, drawn the same (0.17.2, its §20): the call's frame takes this card's place when it is
+ * ready, and the owner saw two different cards — ours (เปิดเพื่อรับสาย) for a few seconds, then the call's (รับสาย). Now
+ * the same size, place, colours, words and buttons; the swap is not seen. Its values are the support host's default
+ * theme (--app-primary, --app-danger, emerald-600, --app-muted, --app-border; rounded-2xl, shadow-2xl, 22rem).
+ */
 const CSS = `
 :host { all: initial; }
 .card {
   position: fixed; right: 16px; bottom: 16px; z-index: 2147483002;
-  width: min(340px, calc(100vw - 32px)); box-sizing: border-box;
-  padding: 16px; border-radius: 16px; background: #fff; color: #0f172a;
-  border: 1px solid #e2e8f0; box-shadow: 0 24px 60px rgba(15, 23, 42, 0.24);
-  font-family: system-ui, -apple-system, "Segoe UI", Roboto, "Noto Sans Thai", sans-serif;
+  width: min(352px, calc(100vw - 32px)); box-sizing: border-box;
+  padding: 16px; border-radius: 16px; background: #fff; color: #1a1a1e;
+  border: 1px solid #e8e8ec; box-shadow: 0 25px 50px -12px rgba(0, 0, 0, 0.25);
+  font-family: "Inter Variable", "Noto Sans Thai Variable", "IBM Plex Sans Thai", -apple-system, "Segoe UI", Roboto, "Noto Sans Thai", sans-serif;
   animation: in 200ms cubic-bezier(0.16, 1, 0.3, 1);
 }
-@media (max-width: 480px) { .card { right: 8px; left: 8px; bottom: 8px; width: auto; } }
+@media (max-width: 639px) { .card { right: 8px; left: 8px; bottom: 8px; width: auto; } }
 .head { display: flex; align-items: center; gap: 12px; }
 .icon {
-  position: relative; flex: none; width: 44px; height: 44px; border-radius: 50%;
-  display: grid; place-items: center; background: #ecfdf5; color: #059669;
+  position: relative; flex: none; width: 48px; height: 48px; border-radius: 50%;
+  display: grid; place-items: center; background: rgba(0, 70, 143, 0.1); color: #00468f;
 }
 .icon::after {
   content: ""; position: absolute; inset: 0; border-radius: 50%;
-  background: rgba(16, 185, 129, 0.25); animation: ping 1.4s ease-out infinite;
+  background: rgba(0, 70, 143, 0.2); animation: ping 1s cubic-bezier(0, 0, 0.2, 1) infinite;
 }
 .icon svg { position: relative; width: 20px; height: 20px; }
-h2 { margin: 0; font-size: 15px; font-weight: 600; line-height: 1.4; }
-.about { margin: 2px 0 0; font-size: 12px; color: #475569; overflow: hidden; text-overflow: ellipsis; white-space: nowrap; max-width: 250px; }
-.how { margin: 10px 0 0; font-size: 12px; line-height: 1.6; color: #64748b; }
-.how a { color: #0369a1; font-weight: 600; }
-.actions { display: flex; gap: 8px; margin-top: 12px; }
+.words { min-width: 0; }
+h2 { margin: 0; font-size: 15px; font-weight: 600; line-height: 1.5; color: #1a1a1e; }
+.about { margin: 0; font-size: 12px; line-height: 1.5; color: #6b7280; overflow: hidden; text-overflow: ellipsis; white-space: nowrap; }
+.how { margin: 10px 0 0; font-size: 12px; line-height: 1.5; color: #6b7280; }
+.how a { color: #00468f; font-weight: 600; }
+.test {
+  margin: 6px 0 0; padding: 0; border: 0; background: none; cursor: pointer;
+  display: inline-flex; align-items: center; gap: 4px; font: inherit; font-size: 12px; font-weight: 500; color: #00468f;
+}
+.test:hover { text-decoration: underline; text-underline-offset: 2px; }
+.test svg { width: 14px; height: 14px; }
+.actions { display: grid; grid-template-columns: 1fr 1fr; gap: 8px; margin-top: 12px; }
+.actions.one { grid-template-columns: 1fr; }
 .actions button {
-  flex: 1; box-sizing: border-box; display: inline-flex; align-items: center; justify-content: center;
-  height: 40px; padding: 0 12px; border-radius: 999px; font: inherit; font-size: 14px; font-weight: 600; cursor: pointer;
+  box-sizing: border-box; display: inline-flex; align-items: center; justify-content: center; gap: 8px;
+  height: 44px; padding: 0 12px; border: none; border-radius: 999px; font: inherit; font-size: 14px; font-weight: 500; cursor: pointer; color: #fff;
 }
-.decline { border: 1px solid #fecdd3; background: #fff1f2; color: #be123c; }
-.decline:hover { background: #ffe4e6; }
-.open { border: none; background: #059669; color: #fff; }
-.open:hover { background: #047857; }
-.close { border: 1px solid #e2e8f0; background: #fff; color: #334155; }
-.actions button:focus-visible { outline: 2px solid #0ea5e9; outline-offset: 2px; }
+.actions button svg { width: 16px; height: 16px; }
+.actions button:disabled { opacity: 0.6; cursor: default; }
+.decline { background: #f44336; }
+.decline:hover:not(:disabled) { background: #dd3a2f; }
+.open, .answer { background: #059669; }
+.open:hover, .answer:hover:not(:disabled) { background: #04875f; }
+.close { border: 1px solid #e8e8ec !important; background: #fff; color: #1a1a1e !important; }
+.spin { animation: spin 0.9s linear infinite; }
+.actions button:focus-visible, .test:focus-visible { outline: 2px solid #00468f; outline-offset: 2px; }
 @keyframes in { from { opacity: 0; transform: translateY(8px); } to { opacity: 1; transform: none; } }
-@keyframes ping { from { transform: scale(1); opacity: 1; } to { transform: scale(1.6); opacity: 0; } }
-@media (prefers-reduced-motion: reduce) { .card { animation: none; } .icon::after { animation: none; opacity: 0; } }
+@keyframes ping { 75%, 100% { transform: scale(2); opacity: 0; } }
+@keyframes spin { to { transform: rotate(360deg); } }
+@media (prefers-reduced-motion: reduce) { .card { animation: none; } .icon::after { animation: none; opacity: 0; } .spin { animation: none; } }
 `;
 
-const PHONE = `<svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><path d="M22 16.92v3a2 2 0 0 1-2.18 2 19.79 19.79 0 0 1-8.63-3.07 19.5 19.5 0 0 1-6-6 19.79 19.79 0 0 1-3.07-8.67A2 2 0 0 1 4.11 2h3a2 2 0 0 1 2 1.72c.13.96.36 1.9.7 2.81a2 2 0 0 1-.45 2.11L8.09 9.91a16 16 0 0 0 6 6l1.27-1.27a2 2 0 0 1 2.11-.45c.91.34 1.85.57 2.81.7A2 2 0 0 1 22 16.92z"/></svg>`;
+const SVG = (d: string) => `<svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true">${d}</svg>`;
+const PHONE = SVG(`<path d="M22 16.92v3a2 2 0 0 1-2.18 2 19.79 19.79 0 0 1-8.63-3.07 19.5 19.5 0 0 1-6-6 19.79 19.79 0 0 1-3.07-8.67A2 2 0 0 1 4.11 2h3a2 2 0 0 1 2 1.72c.13.96.36 1.9.7 2.81a2 2 0 0 1-.45 2.11L8.09 9.91a16 16 0 0 0 6 6l1.27-1.27a2 2 0 0 1 2.11-.45c.91.34 1.85.57 2.81.7A2 2 0 0 1 22 16.92z"/>`);
+const PHONE_OFF = SVG(`<path d="M10.68 13.31a16 16 0 0 0 3.41 2.6l1.27-1.27a2 2 0 0 1 2.11-.45 12.84 12.84 0 0 0 2.81.7 2 2 0 0 1 1.72 2v3a2 2 0 0 1-2.18 2 19.79 19.79 0 0 1-8.63-3.07 19.42 19.42 0 0 1-3.33-2.67m-2.67-3.34a19.79 19.79 0 0 1-3.07-8.63A2 2 0 0 1 4.11 2h3a2 2 0 0 1 2 1.72 12.84 12.84 0 0 0 .7 2.81 2 2 0 0 1-.45 2.11L8.09 9.91"/><line x1="22" x2="2" y1="2" y2="22"/>`);
+const SLIDERS = SVG(`<path d="M20 7h-9"/><path d="M14 17H5"/><circle cx="17" cy="17" r="3"/><circle cx="7" cy="7" r="3"/>`);
+const SPINNER = SVG(`<path d="M21 12a9 9 0 1 1-6.219-8.56"/>`).replace("<svg ", '<svg class="spin" ');
 
 export interface RingCall {
   id: string;
@@ -67,11 +89,18 @@ export interface RingCall {
 }
 
 export interface RingHandlers {
-  /** Runs INSIDE the press: a tab can be opened only there, before anything is awaited. */
+  /** The portal's way: runs INSIDE the press — a tab can be opened only there, before anything is awaited. */
   open: () => void;
   decline: () => void;
+  /** The call's frame is coming (0.17.2): รับสาย here — the frame answers the moment it is ready. */
+  answer?: () => void;
+  /** …and ทดสอบไมค์และลำโพง — the frame's voice settings, the moment it is ready. */
+  voice?: () => void;
 }
 
+/** `frame`: the call's own card while its frame comes; `portal`: answer in a new tab (no frame, or it failed). */
+export type RingMode = "frame" | "portal";
+
 let host: HTMLElement | null = null;
 let shownId: string | null = null;
 let titleBefore: string | null = null;
@@ -94,12 +123,23 @@ function mount(): ShadowRoot | null {
   return root;
 }
 
-/** Show the ring for this call — once; the same call again changes nothing. */
-export function showRing(call: RingCall, handlers: RingHandlers): void {
-  if (shownId === call.id && host?.isConnected) return;
-  const root = mount();
-  if (!root) return;
-  shownId = call.id;
+function button(className: string, html: string, data: string, onClick: () => void): HTMLButtonElement {
+  const b = document.createElement("button");
+  b.type = "button";
+  b.className = className;
+  b.innerHTML = html;
+  b.dataset.lwRing = data;
+  b.onclick = onClick;
+  return b;
+}
+const label = (text: string) => {
+  const span = document.createElement("span");
+  span.textContent = text;
+  return span.outerHTML;
+};
+
+/** The card's insides, for a mode — the head stays the same in both. */
+function render(root: ShadowRoot, call: RingCall, handlers: RingHandlers, mode: RingMode, note?: string): void {
   const s = t();
   root.innerHTML = "";
   const style = document.createElement("style");
@@ -109,12 +149,14 @@ export function showRing(call: RingCall, handlers: RingHandlers): void {
   card.setAttribute("role", "alertdialog");
   card.setAttribute("aria-label", s.ringTitle);
   card.dataset.lwCallRing = call.id;
+  card.dataset.lwRingMode = mode;
   const head = document.createElement("div");
   head.className = "head";
   const icon = document.createElement("span");
   icon.className = "icon";
   icon.innerHTML = PHONE;
   const words = document.createElement("div");
+  words.className = "words";
   const h = document.createElement("h2");
   h.textContent = s.ringTitle;
   const about = document.createElement("p");
@@ -125,30 +167,53 @@ export function showRing(call: RingCall, handlers: RingHandlers): void {
   head.append(icon, words);
   const how = document.createElement("p");
   how.className = "how";
-  how.textContent = s.ringHow;
+  how.textContent = note ?? (mode === "frame" ? s.ringHint : s.ringHow);
   const actions = document.createElement("div");
   actions.className = "actions";
-  const decline = document.createElement("button");
-  decline.type = "button";
-  decline.className = "decline";
-  decline.textContent = s.ringDecline;
-  decline.dataset.lwRing = "decline";
-  decline.onclick = () => handlers.decline();
-  const open = document.createElement("button");
-  open.type = "button";
-  open.className = "open";
-  open.textContent = s.ringOpen;
-  open.dataset.lwRing = "open";
-  open.onclick = () => handlers.open();
-  actions.append(decline, open);
-  card.append(head, how, actions);
+  const decline = button("decline", PHONE_OFF + label(s.ringDecline), "decline", () => handlers.decline());
+  card.append(head, how);
+  if (mode === "frame" && handlers.answer) {
+    if (handlers.voice) card.append(button("test", SLIDERS + label(s.ringTest), "test", () => handlers.voice?.()));
+    const answer = button("answer", PHONE + label(s.ringAnswer), "answer", () => handlers.answer?.());
+    actions.append(decline, answer);
+  } else actions.append(decline, button("open", label(s.ringOpen), "open", () => handlers.open()));
+  card.append(actions);
   root.append(style, card);
+}
+
+/** Show the ring for this call — once; the same call again changes nothing. */
+export function showRing(call: RingCall, handlers: RingHandlers, mode: RingMode = "portal"): void {
+  if (shownId === call.id && host?.isConnected) return;
+  const root = mount();
+  if (!root) return;
+  shownId = call.id;
+  render(root, call, handlers, mode);
   startTone();
   if (titleBefore === null) {
     titleBefore = document.title;
-    document.title = `${s.ringTab} — ${titleBefore}`;
+    document.title = `${t().ringTab} — ${titleBefore}`;
+  }
+}
+
+/** รับสาย pressed while the call's frame comes: said, and nothing more to press until it is there. */
+export function ringAnswering(id: string): void {
+  const root = host?.shadowRoot;
+  if (!root || shownId !== id) return;
+  const answer = root.querySelector<HTMLButtonElement>(".answer");
+  if (answer) {
+    answer.innerHTML = SPINNER + label(t().ringAnswering);
+    answer.disabled = true;
   }
-  open.focus({ preventScroll: true });
+  const decline = root.querySelector<HTMLButtonElement>(".decline");
+  if (decline) decline.disabled = true;
+}
+
+/** The call's frame could not come up: the same card, now the portal's way — a new tab, which needs a fresh press. */
+export function ringFallback(call: RingCall, handlers: RingHandlers): void {
+  const root = host?.isConnected ? host.shadowRoot : null;
+  if (!root || shownId !== call.id) return showRing(call, handlers, "portal");
+  host!.style.display = "";
+  render(root, call, handlers, "portal", t().ringFallback);
 }
 
 /** Opened: the card says where to answer, and stops ringing. `blockedUrl` — the browser refused the tab: a link, which is a fresh press. */
@@ -192,8 +257,22 @@ export function ringOpened(blockedUrl?: string): void {
  */
 export function quietRing(id: string, quiet = true): void {
   if (!host?.isConnected || shownId !== id) return;
-  host.style.display = quiet ? "none" : "";
+  const h = host;
+  clearTimeout(fading);
+  if (!quiet) {
+    h.style.display = "";
+    h.style.opacity = "";
+    return;
+  }
+  // Under the call's own card (the frame is above ours): a short fade, so a line that wraps differently in its fonts
+  // is not seen to jump (0.17.2).
+  h.style.transition = "opacity 150ms ease-out";
+  h.style.opacity = "0";
+  fading = setTimeout(() => {
+    if (h.style.opacity === "0") h.style.display = "none";
+  }, 160);
 }
+let fading: ReturnType<typeof setTimeout> | undefined;
 
 /** The call is no longer ringing for this person — answered, declined, missed or ended. */
 export function hideRing(id?: string): void {

package/src/ui/strings.ts

@@ -118,6 +118,13 @@ export interface Strings {
   ringBlocked: string;
   ringClose: string;
   ringTab: string;
+  /** The call's own card, while its frame is coming (0.17.2): the same words as the support host's ring card. */
+  ringHint: string;
+  ringTest: string;
+  ringAnswer: string;
+  ringAnswering: string;
+  /** The frame could not come up: answer in a new tab instead. */
+  ringFallback: string;
 }
 
 const th: Strings = {
@@ -202,6 +209,11 @@ const th: Strings = {
   ringBlocked: "เบราว์เซอร์บล็อกแท็บใหม่ — กดที่นี่เพื่อเปิดหน้ารับสาย",
   ringClose: "ปิด",
   ringTab: "📞 สายเข้า",
+  ringHint: "เมื่อรับสาย เบราว์เซอร์จะขอใช้ไมโครโฟน · ระหว่างคุย ทีมงานอาจขอดูหน้าจอ — คุณเลือกได้เสมอว่าจะให้ดูหรือไม่",
+  ringTest: "ทดสอบไมค์และลำโพงก่อนรับสาย",
+  ringAnswer: "รับสาย",
+  ringAnswering: "กำลังรับสาย…",
+  ringFallback: "เปิดสายในหน้านี้ไม่ได้ — รับสายในแท็บใหม่แทน ไม่ต้องเข้าสู่ระบบอีก",
 };
 
 const en: Strings = {
@@ -286,6 +298,11 @@ const en: Strings = {
   ringBlocked: "Your browser blocked the new tab — open the call here",
   ringClose: "Close",
   ringTab: "📞 Incoming call",
+  ringHint: "When you answer, your browser asks for the microphone · during the call the team may ask to see your screen — you always choose",
+  ringTest: "Test the microphone and speaker first",
+  ringAnswer: "Answer",
+  ringAnswering: "Answering…",
+  ringFallback: "The call can't open on this page — answer in a new tab instead, already signed in",
 };
 
 export function strings(locale: "th" | "en" | undefined): Strings {