@lightworkai.official/debug-capture 0.16.0 → 0.17.0

package/dist/ink.d.ts

@@ -0,0 +1,102 @@
+/**
+ * Marks on a shared screen — ชี้ · วาด · กรอบ (0.17; the support host's docs/CALLS-PLAN.md §17).
+ *
+ * Whoever watches a shared screen points at it, draws on it and boxes a part of it; whoever shares it sees the marks
+ * on their own page, where they are working — the way Google Meet's "disappearing ink" and the co-browsing tools'
+ * laser pointer do it. One module draws them everywhere: the watcher's own view (the support host), the sharer's page
+ * on the support host, and the host app's page (this widget, under its call frame) — so they look and fade alike.
+ *
+ * What travels is small and plain: an op names a mark (`id`), its kind and colour once, then points as fractions of
+ * the shared picture (0–1 across, 0–1 down) — a picture of any size maps onto a page of any size. Everything received
+ * goes through `readInkOp` first: anything else, or too much of it, is dropped, never drawn.
+ *
+ * Time is each side's own: a mark fades from when THIS side saw it end, so two clocks never need to agree.
+ */
+export type InkKind = "pen" | "rect" | "laser";
+export type InkPoint = readonly [number, number];
+export type InkOp = {
+    op: "begin";
+    id: string;
+    kind: InkKind;
+    color: string;
+    pts: InkPoint[];
+} | {
+    op: "add";
+    id: string;
+    pts: InkPoint[];
+} | {
+    op: "end";
+    id: string;
+} | {
+    op: "clear";
+};
+/** At most this many points in one op — a pointer's ~30 ms, many times over. */
+export declare const INK_MAX_POINTS_PER_OP = 64;
+/** A line or a box stays this long after it is finished, then fades over INK_FADE_MS. */
+export declare const INK_HOLD_MS = 3500;
+export declare const INK_FADE_MS = 700;
+/** The pointer's tail, and how long its dot stays after the pointer left the picture. */
+export declare const LASER_TRAIL_MS = 450;
+export declare const LASER_LINGER_MS = 900;
+/** A mark that stopped receiving anything this long ago is finished, ended or not — a dropped connection never leaves one up. */
+export declare const INK_STALE_MS = 20000;
+/** The colours, one per tool — seen on any page: each is drawn on a white halo. */
+export declare const INK_COLORS: Record<InkKind, string>;
+/** An op as received — from a socket, from another window — or null: never drawn. Points clamped into the picture. */
+export declare function readInkOp(v: unknown): InkOp | null;
+/** How visible a mark is at `now`, 0–1. */
+export declare function inkAlpha(kind: InkKind, endedAt: number | null, now: number): number;
+export declare class InkScene {
+    private marks;
+    apply(op: InkOp, now?: number): void;
+    /** Something still to draw at `now`; the gone ones are let go. */
+    alive(now?: number): boolean;
+    get size(): number;
+    /** Draw every mark onto a context sized `w` × `h` (CSS pixels — the caller has set the device-pixel scale). */
+    draw(ctx: CanvasRenderingContext2D, w: number, h: number, now?: number): void;
+}
+/** A canvas of `w` × `h` CSS pixels, sharp on this screen; its context scaled to CSS pixels. */
+export declare function sizeInkCanvas(canvas: HTMLCanvasElement, w: number, h: number, dpr?: number): CanvasRenderingContext2D | null;
+/** Paints a scene on a canvas on every frame while it has marks, and stops — a page with no marks pays nothing. */
+export declare class InkPainter {
+    private readonly canvas;
+    private readonly scene;
+    private readonly box;
+    private frame;
+    constructor(canvas: HTMLCanvasElement, scene: InkScene, box: () => {
+        w: number;
+        h: number;
+    });
+    /** Something changed: paint until there is nothing left. */
+    kick(): void;
+    stop(): void;
+}
+/** One op every this often while drawing — ~30 a second at most. */
+export declare const INK_SEND_EVERY_MS = 33;
+/** A mark held still says so this often — well inside INK_STALE_MS. */
+export declare const INK_KEEP_MS = 5000;
+/**
+ * The watcher's pen: every point drawn on its own scene at once (it must feel like ink), and sent to the sharer in
+ * batches — begin, then a points op each ~33 ms, then end — never a message per pointer event.
+ */
+export declare class InkSender {
+    private readonly send;
+    private readonly scene;
+    private readonly onChange;
+    private id;
+    private kind;
+    private pending;
+    private last;
+    private lastSent;
+    private timer;
+    private keep;
+    constructor(send: (op: InkOp) => void, scene: InkScene, onChange?: () => void);
+    get drawing(): InkKind | null;
+    begin(kind: InkKind, p: InkPoint): void;
+    private stillHere;
+    move(p: InkPoint): void;
+    /** Send what is waiting now. */
+    flush(): void;
+    end(): void;
+    clear(): void;
+}

package/dist/ui/callFrame.d.ts

@@ -1,17 +1,3 @@
-/**
- * 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.
- */
 export type FrameLayout = "card" | "full";
 export interface FrameMessage {
     source?: string;
@@ -23,6 +9,7 @@ export interface FrameMessage {
     x?: number;
     y?: number;
     reason?: string;
+    op?: unknown;
 }
 export interface FrameHandlers {
     /** The call is on screen in the frame. */

package/dist/ui/inkOverlay.d.ts

@@ -0,0 +1,18 @@
+/**
+ * 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 { type InkOp } from "../ink";
+/** A mark from the team, as the call's frame handed it up (already read by `readInkOp`). */
+export declare function inkOnPage(op: InkOp): void;
+export declare function inkMarksOnPage(): number;
+/** The call is over: the layer goes. */
+export declare function removeInkLayer(): void;

package/package.json

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

@@ -44,6 +44,9 @@ export { defineReporterElement, setErroredQueriesSource, REPORTER_TAG } from "./
 export { showToast } from "./ui/toast";
 // A call from the support team, rung in the host app — started by install; a host that renders its own UI may start or stop it.
 export { startLiveRing, stopLiveRing } from "./live";
+// Marks on a shared screen (0.17) — the same drawing on the support host and here.
+export { readInkOp, InkScene, InkPainter, InkSender, sizeInkCanvas, inkAlpha, INK_COLORS, INK_HOLD_MS, INK_FADE_MS, INK_STALE_MS, INK_MAX_POINTS_PER_OP, LASER_LINGER_MS, LASER_TRAIL_MS, INK_SEND_EVERY_MS, INK_KEEP_MS } from "./ink";
+export type { InkOp, InkKind, InkPoint } from "./ink";
 
 /*
  * The annotator ENGINE, shared by every framework package.

package/src/ink.ts

@@ -0,0 +1,386 @@
+/**
+ * Marks on a shared screen — ชี้ · วาด · กรอบ (0.17; the support host's docs/CALLS-PLAN.md §17).
+ *
+ * Whoever watches a shared screen points at it, draws on it and boxes a part of it; whoever shares it sees the marks
+ * on their own page, where they are working — the way Google Meet's "disappearing ink" and the co-browsing tools'
+ * laser pointer do it. One module draws them everywhere: the watcher's own view (the support host), the sharer's page
+ * on the support host, and the host app's page (this widget, under its call frame) — so they look and fade alike.
+ *
+ * What travels is small and plain: an op names a mark (`id`), its kind and colour once, then points as fractions of
+ * the shared picture (0–1 across, 0–1 down) — a picture of any size maps onto a page of any size. Everything received
+ * goes through `readInkOp` first: anything else, or too much of it, is dropped, never drawn.
+ *
+ * Time is each side's own: a mark fades from when THIS side saw it end, so two clocks never need to agree.
+ */
+
+export type InkKind = "pen" | "rect" | "laser";
+export type InkPoint = readonly [number, number];
+export type InkOp =
+  | { op: "begin"; id: string; kind: InkKind; color: string; pts: InkPoint[] }
+  | { op: "add"; id: string; pts: InkPoint[] }
+  | { op: "end"; id: string }
+  | { op: "clear" };
+
+/** At most this many points in one op — a pointer's ~30 ms, many times over. */
+export const INK_MAX_POINTS_PER_OP = 64;
+/** A line or a box stays this long after it is finished, then fades over INK_FADE_MS. */
+export const INK_HOLD_MS = 3500;
+export const INK_FADE_MS = 700;
+/** The pointer's tail, and how long its dot stays after the pointer left the picture. */
+export const LASER_TRAIL_MS = 450;
+export const LASER_LINGER_MS = 900;
+/** A mark that stopped receiving anything this long ago is finished, ended or not — a dropped connection never leaves one up. */
+export const INK_STALE_MS = 20_000;
+/** The colours, one per tool — seen on any page: each is drawn on a white halo. */
+export const INK_COLORS: Record<InkKind, string> = { pen: "#ef4444", rect: "#f59e0b", laser: "#ef4444" };
+
+const MAX_MARKS = 120;
+const MAX_POINTS = 4000;
+const ID = /^[A-Za-z0-9_-]{1,32}$/;
+const COLOR = /^#[0-9a-fA-F]{6}$/;
+const KINDS: readonly InkKind[] = ["pen", "rect", "laser"];
+
+const clamp01 = (v: number) => (v < 0 ? 0 : v > 1 ? 1 : v);
+
+function readPoints(v: unknown, min: number): InkPoint[] | null {
+  if (!Array.isArray(v) || v.length < min || v.length > INK_MAX_POINTS_PER_OP) return null;
+  const out: InkPoint[] = [];
+  for (const p of v) {
+    if (!Array.isArray(p) || p.length !== 2) return null;
+    const [x, y] = p as unknown[];
+    if (typeof x !== "number" || typeof y !== "number" || !Number.isFinite(x) || !Number.isFinite(y)) return null;
+    out.push([clamp01(x), clamp01(y)]);
+  }
+  return out;
+}
+
+/** An op as received — from a socket, from another window — or null: never drawn. Points clamped into the picture. */
+export function readInkOp(v: unknown): InkOp | null {
+  if (!v || typeof v !== "object") return null;
+  const o = v as Record<string, unknown>;
+  if (o.op === "clear") return { op: "clear" };
+  if (typeof o.id !== "string" || !ID.test(o.id)) return null;
+  if (o.op === "end") return { op: "end", id: o.id };
+  if (o.op === "add") {
+    const pts = readPoints(o.pts, 1);
+    return pts ? { op: "add", id: o.id, pts } : null;
+  }
+  if (o.op === "begin") {
+    if (!KINDS.includes(o.kind as InkKind) || typeof o.color !== "string" || !COLOR.test(o.color)) return null;
+    const pts = readPoints(o.pts, 1);
+    return pts ? { op: "begin", id: o.id, kind: o.kind as InkKind, color: o.color, pts } : null;
+  }
+  return null;
+}
+
+/* ── The marks ─────────────────────────────────────────────────────────── */
+
+interface Mark {
+  kind: InkKind;
+  color: string;
+  pts: { x: number; y: number; t: number }[];
+  endedAt: number | null;
+  lastAt: number;
+}
+
+/** When a mark ended — told, or taken as ended once nothing came for INK_STALE_MS. */
+function endOf(m: Mark, now: number): number | null {
+  if (m.endedAt !== null) return m.endedAt;
+  return now - m.lastAt > INK_STALE_MS ? m.lastAt : null;
+}
+
+/** How visible a mark is at `now`, 0–1. */
+export function inkAlpha(kind: InkKind, endedAt: number | null, now: number): number {
+  if (endedAt === null) return 1;
+  const since = now - endedAt;
+  if (kind === "laser") return since >= LASER_LINGER_MS ? 0 : 1 - since / LASER_LINGER_MS;
+  if (since <= INK_HOLD_MS) return 1;
+  return Math.max(0, 1 - (since - INK_HOLD_MS) / INK_FADE_MS);
+}
+
+export class InkScene {
+  private marks = new Map<string, Mark>();
+
+  apply(op: InkOp, now = Date.now()): void {
+    if (op.op === "clear") {
+      this.marks.clear();
+      return;
+    }
+    if (op.op === "begin") {
+      // The oldest goes first when there are too many — a page is never asked to draw without end.
+      while (this.marks.size >= MAX_MARKS) this.marks.delete(this.marks.keys().next().value as string);
+      this.marks.delete(op.id);
+      this.marks.set(op.id, { kind: op.kind, color: op.color, pts: op.pts.map(([x, y]) => ({ x, y, t: now })), endedAt: null, lastAt: now });
+      return;
+    }
+    const m = this.marks.get(op.id);
+    if (!m || endOf(m, now) !== null) return;
+    if (op.op === "end") {
+      m.endedAt = now;
+      return;
+    }
+    m.lastAt = now;
+    if (m.kind === "rect") {
+      // A box is its first corner and the corner being dragged: the latest point replaces the second.
+      const [x, y] = op.pts[op.pts.length - 1]!;
+      m.pts = [m.pts[0]!, { x, y, t: now }];
+      return;
+    }
+    for (const [x, y] of op.pts) m.pts.push({ x, y, t: now });
+    if (m.pts.length > MAX_POINTS) m.pts.splice(0, m.pts.length - MAX_POINTS);
+  }
+
+  /** Something still to draw at `now`; the gone ones are let go. */
+  alive(now = Date.now()): boolean {
+    for (const [id, m] of this.marks) if (inkAlpha(m.kind, endOf(m, now), now) <= 0) this.marks.delete(id);
+    return this.marks.size > 0;
+  }
+
+  get size(): number {
+    return this.marks.size;
+  }
+
+  /** Draw every mark onto a context sized `w` × `h` (CSS pixels — the caller has set the device-pixel scale). */
+  draw(ctx: CanvasRenderingContext2D, w: number, h: number, now = Date.now()): void {
+    ctx.clearRect(0, 0, w, h);
+    const unit = Math.max(1, Math.min(w, h));
+    for (const m of this.marks.values()) {
+      const alpha = inkAlpha(m.kind, endOf(m, now), now);
+      if (alpha <= 0 || !m.pts.length) continue;
+      ctx.save();
+      ctx.lineCap = "round";
+      ctx.lineJoin = "round";
+      if (m.kind === "pen") drawPen(ctx, m, w, h, Math.max(3, unit * 0.0045), alpha);
+      else if (m.kind === "rect") drawRect(ctx, m, w, h, Math.max(2.5, unit * 0.003), alpha);
+      else drawLaser(ctx, m, w, h, Math.max(6, unit * 0.008), alpha, now);
+      ctx.restore();
+    }
+  }
+}
+
+function pathThrough(ctx: CanvasRenderingContext2D, pts: { x: number; y: number }[], w: number, h: number): void {
+  ctx.beginPath();
+  ctx.moveTo(pts[0]!.x * w, pts[0]!.y * h);
+  if (pts.length === 1) {
+    ctx.lineTo(pts[0]!.x * w + 0.01, pts[0]!.y * h);
+    return;
+  }
+  // Through the midpoints: a line drawn by a hand, not a polygon.
+  for (let i = 1; i < pts.length - 1; i++) {
+    const a = pts[i]!;
+    const b = pts[i + 1]!;
+    ctx.quadraticCurveTo(a.x * w, a.y * h, ((a.x + b.x) / 2) * w, ((a.y + b.y) / 2) * h);
+  }
+  const last = pts[pts.length - 1]!;
+  ctx.lineTo(last.x * w, last.y * h);
+}
+
+function drawPen(ctx: CanvasRenderingContext2D, m: Mark, w: number, h: number, width: number, alpha: number): void {
+  ctx.globalAlpha = alpha;
+  pathThrough(ctx, m.pts, w, h);
+  ctx.strokeStyle = "rgba(255,255,255,0.92)";
+  ctx.lineWidth = width + 3;
+  ctx.stroke();
+  ctx.strokeStyle = m.color;
+  ctx.lineWidth = width;
+  ctx.stroke();
+}
+
+function drawRect(ctx: CanvasRenderingContext2D, m: Mark, w: number, h: number, width: number, alpha: number): void {
+  const a = m.pts[0]!;
+  const b = m.pts[m.pts.length - 1]!;
+  const x = Math.min(a.x, b.x) * w;
+  const y = Math.min(a.y, b.y) * h;
+  const rw = Math.abs(b.x - a.x) * w;
+  const rh = Math.abs(b.y - a.y) * h;
+  ctx.globalAlpha = alpha;
+  ctx.fillStyle = m.color;
+  ctx.globalAlpha = alpha * 0.14;
+  ctx.fillRect(x, y, rw, rh);
+  ctx.globalAlpha = alpha;
+  ctx.strokeStyle = "rgba(255,255,255,0.92)";
+  ctx.lineWidth = width + 3;
+  ctx.strokeRect(x, y, rw, rh);
+  ctx.strokeStyle = m.color;
+  ctx.lineWidth = width;
+  ctx.strokeRect(x, y, rw, rh);
+}
+
+function drawLaser(ctx: CanvasRenderingContext2D, m: Mark, w: number, h: number, r: number, alpha: number, now: number): void {
+  // The tail: the last moments of the pointer, fading with their age.
+  const tail = m.pts.filter((p) => now - p.t <= LASER_TRAIL_MS);
+  for (let i = 1; i < tail.length; i++) {
+    const p = tail[i - 1]!;
+    const q = tail[i]!;
+    ctx.globalAlpha = alpha * Math.max(0, 1 - (now - q.t) / LASER_TRAIL_MS) * 0.7;
+    ctx.strokeStyle = m.color;
+    ctx.lineWidth = r * 0.9;
+    ctx.beginPath();
+    ctx.moveTo(p.x * w, p.y * h);
+    ctx.lineTo(q.x * w, q.y * h);
+    ctx.stroke();
+  }
+  const dot = m.pts[m.pts.length - 1]!;
+  ctx.globalAlpha = alpha;
+  ctx.shadowColor = m.color;
+  ctx.shadowBlur = r * 2;
+  ctx.fillStyle = m.color;
+  ctx.beginPath();
+  ctx.arc(dot.x * w, dot.y * h, r, 0, Math.PI * 2);
+  ctx.fill();
+  ctx.shadowBlur = 0;
+  ctx.strokeStyle = "rgba(255,255,255,0.95)";
+  ctx.lineWidth = 2;
+  ctx.stroke();
+}
+
+/* ── Drawing a scene on a canvas, for as long as it has something to show ──── */
+
+/** A canvas of `w` × `h` CSS pixels, sharp on this screen; its context scaled to CSS pixels. */
+export function sizeInkCanvas(canvas: HTMLCanvasElement, w: number, h: number, dpr = typeof window === "undefined" ? 1 : window.devicePixelRatio || 1): CanvasRenderingContext2D | null {
+  const pw = Math.max(1, Math.round(w * dpr));
+  const ph = Math.max(1, Math.round(h * dpr));
+  if (canvas.width !== pw) canvas.width = pw;
+  if (canvas.height !== ph) canvas.height = ph;
+  const ctx = canvas.getContext("2d");
+  ctx?.setTransform(dpr, 0, 0, dpr, 0, 0);
+  return ctx;
+}
+
+/** Paints a scene on a canvas on every frame while it has marks, and stops — a page with no marks pays nothing. */
+export class InkPainter {
+  private frame = 0;
+  constructor(
+    private readonly canvas: HTMLCanvasElement,
+    private readonly scene: InkScene,
+    private readonly box: () => { w: number; h: number },
+  ) {}
+
+  /** Something changed: paint until there is nothing left. */
+  kick(): void {
+    if (this.frame || typeof requestAnimationFrame === "undefined") return;
+    const step = () => {
+      this.frame = 0;
+      const { w, h } = this.box();
+      const ctx = sizeInkCanvas(this.canvas, w, h);
+      const now = Date.now();
+      const alive = this.scene.alive(now);
+      if (ctx) this.scene.draw(ctx, w, h, now);
+      if (alive) this.frame = requestAnimationFrame(step);
+    };
+    this.frame = requestAnimationFrame(step);
+  }
+
+  stop(): void {
+    if (this.frame && typeof cancelAnimationFrame !== "undefined") cancelAnimationFrame(this.frame);
+    this.frame = 0;
+  }
+}
+
+/* ── Drawing as the watcher: local at once, sent in small batches ──────────── */
+
+/** One op every this often while drawing — ~30 a second at most. */
+export const INK_SEND_EVERY_MS = 33;
+/** A mark held still says so this often — well inside INK_STALE_MS. */
+export const INK_KEEP_MS = 5000;
+/** Closer than this to the last point (a fraction of the picture) is the same point. */
+const SAME = 0.0012;
+
+let seq = 0;
+const newId = () => `${Date.now().toString(36)}${(seq++).toString(36)}${Math.random().toString(36).slice(2, 6)}`.slice(0, 32);
+
+/**
+ * The watcher's pen: every point drawn on its own scene at once (it must feel like ink), and sent to the sharer in
+ * batches — begin, then a points op each ~33 ms, then end — never a message per pointer event.
+ */
+export class InkSender {
+  private id: string | null = null;
+  private kind: InkKind | null = null;
+  private pending: InkPoint[] = [];
+  private last: InkPoint | null = null;
+  private lastSent = 0;
+  private timer: ReturnType<typeof setTimeout> | undefined;
+  private keep: ReturnType<typeof setInterval> | undefined;
+
+  constructor(
+    private readonly send: (op: InkOp) => void,
+    private readonly scene: InkScene,
+    private readonly onChange: () => void = () => undefined,
+  ) {}
+
+  get drawing(): InkKind | null {
+    return this.id ? this.kind : null;
+  }
+
+  begin(kind: InkKind, p: InkPoint): void {
+    this.end();
+    this.id = newId();
+    this.kind = kind;
+    this.last = p;
+    this.lastSent = Date.now();
+    const op: InkOp = { op: "begin", id: this.id, kind, color: INK_COLORS[kind], pts: [p] };
+    this.scene.apply(op);
+    this.send(op);
+    // Held still (a pointer resting on a button, a pen pressed and thinking): a word every few seconds, so neither side
+    // takes the mark as finished (INK_STALE_MS) while it is still being held.
+    this.keep = setInterval(() => this.stillHere(), INK_KEEP_MS);
+    this.onChange();
+  }
+
+  private stillHere(): void {
+    if (!this.id || !this.last || Date.now() - this.lastSent < INK_KEEP_MS) return;
+    this.flush();
+    const op: InkOp = { op: "add", id: this.id, pts: [this.last] };
+    this.scene.apply(op);
+    this.send(op);
+    this.lastSent = Date.now();
+  }
+
+  move(p: InkPoint): void {
+    if (!this.id || !this.kind) return;
+    // Nothing sent for so long the other side may have taken the mark as finished (a tab whose timers were held back):
+    // a new one, or the move is lost.
+    if (Date.now() - this.lastSent > INK_STALE_MS / 2) return this.begin(this.kind, p);
+    if (this.last && Math.abs(p[0] - this.last[0]) < SAME && Math.abs(p[1] - this.last[1]) < SAME) return;
+    this.last = p;
+    this.scene.apply({ op: "add", id: this.id, pts: [p] });
+    this.onChange();
+    // A box only needs where its corner is now; a line, every point.
+    if (this.kind === "rect") this.pending = [p];
+    else this.pending.push(p);
+    if (this.pending.length >= INK_MAX_POINTS_PER_OP) this.flush();
+    else if (!this.timer) this.timer = setTimeout(() => this.flush(), Math.max(0, INK_SEND_EVERY_MS - (Date.now() - this.lastSent)));
+  }
+
+  /** Send what is waiting now. */
+  flush(): void {
+    clearTimeout(this.timer);
+    this.timer = undefined;
+    if (!this.id || !this.pending.length) return;
+    this.send({ op: "add", id: this.id, pts: this.pending });
+    this.pending = [];
+    this.lastSent = Date.now();
+  }
+
+  end(): void {
+    if (!this.id) return;
+    clearInterval(this.keep);
+    this.keep = undefined;
+    this.flush();
+    const op: InkOp = { op: "end", id: this.id };
+    this.scene.apply(op);
+    this.send(op);
+    this.id = null;
+    this.kind = null;
+    this.last = null;
+    this.onChange();
+  }
+
+  clear(): void {
+    this.end();
+    const op: InkOp = { op: "clear" };
+    this.scene.apply(op);
+    this.send(op);
+    this.onChange();
+  }
+}

package/src/ui/callFrame.ts

@@ -11,7 +11,14 @@
  *
  * 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";
@@ -30,6 +37,7 @@ export interface FrameMessage {
   x?: number;
   y?: number;
   reason?: string;
+  op?: unknown;
 }
 export interface FrameHandlers {
   /** The call is on screen in the frame. */
@@ -117,6 +125,7 @@ iframe.on { visibility: visible; }`;
   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");
@@ -124,6 +133,8 @@ iframe.on { visibility: visible; }`;
 }
 
 export function closeCallFrame(): void {
+  if (host) nameTab(null);
+  removeInkLayer();
   clearTimeout(readyTimer);
   window.removeEventListener("message", onMessage);
   window.removeEventListener("resize", place);
@@ -174,6 +185,27 @@ function onMessage(e: MessageEvent): void {
     }
     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 */
   }
 }
 

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;
+}