Skip to content

Enterprise agent platform for building, deploying, and operating AI teammates.

68.8 KB
Raw Blame
import { afterEach, beforeEach, describe, expect, it, vi } from "vitest"

import { evaluateWidgetScript, widgetScript } from "@/test-utils/widget-script"

function runWidget(attributes: Record<string, string>, evaluate = evaluateWidgetScript) {
  const script = document.createElement("script")
  script.src = "https://chat.example/widget.js"
  for (const [name, value] of Object.entries(attributes)) {
    script.setAttribute(name, value)
  }
  document.body.appendChild(script)
  Object.defineProperty(document, "currentScript", {
    configurable: true,
    value: script,
  })

  evaluate()
}

describe("widget bootstrap", () => {
  const fetchMock = vi.fn()
  let currentScriptDescriptor: PropertyDescriptor | undefined

  beforeEach(() => {
    currentScriptDescriptor = Object.getOwnPropertyDescriptor(document, "currentScript")
    document.head.innerHTML = ""
    document.body.innerHTML = ""
    // innerHTML resets don't touch inline styles on body itself, and it's
    // shared across every test in this file (not just the panel-resize
    // describe below) -- reset here, not just in a nested beforeEach, so any
    // test anywhere in the file that touches these can't leak into another.
    document.body.style.userSelect = ""
    document.body.style.cursor = ""
    // The scroll lock targets document.scrollingElement -- <html> in jsdom
    // (it has no scrollingElement at all) and in any real standards-mode
    // browser regardless of which element's CSS actually governs page
    // scrolling (see scrollLockTarget's own comment in widget.js).
    document.documentElement.style.overflow = ""
    document.documentElement.classList.remove("xagent-widget-scroll-locked")
    // A test that leaves the widget open at the end (deliberately, to assert
    // the lock is still held) would otherwise leak the scroll lock's
    // ref-count expando into the next test via the shared element.
    delete (document.documentElement as unknown as Record<string, unknown>).__xagentScrollLockV2
    localStorage.setItem("xagent_guest_id", "guest-fixed")
    vi.stubGlobal("fetch", fetchMock)
    fetchMock.mockReset()
  })

  afterEach(() => {
    if (currentScriptDescriptor) {
      Object.defineProperty(document, "currentScript", currentScriptDescriptor)
    } else {
      Reflect.deleteProperty(document, "currentScript")
    }
    vi.unstubAllGlobals()
    vi.restoreAllMocks()
  })

  it("fails closed without a widget key on the default token channel", () => {
    const errorSpy = vi.spyOn(console, "error").mockImplementation(() => undefined)

    runWidget({})

    expect(fetchMock).not.toHaveBeenCalled()
    expect(document.querySelector(".xagent-widget-container")).toBeNull()
    expect(document.head.querySelector("style")).toBeNull()
    expect(errorSpy).toHaveBeenCalledWith(expect.stringContaining("Missing data-widget-key"))
  })

  it("also boots the exact uninstrumented browser artifact", () => {
    runWidget({ "data-token": "legacy-token" }, () => window.eval(widgetScript))
    expect(document.querySelector<HTMLIFrameElement>(".xagent-widget-iframe")?.src).toBe(
      "https://chat.example/widget/chat/legacy-token?guest_id=guest-fixed",
    )
    expect(document.querySelector(".xagent-widget-fab")).not.toBeNull()
    expect(fetchMock).not.toHaveBeenCalled()
  })

  it("delegates clipboard writes to the cross-origin chat iframe", () => {
    runWidget({ "data-token": "legacy-token" })
    expect(document.querySelector<HTMLIFrameElement>(".xagent-widget-iframe")?.getAttribute("allow"))
      .toBe("clipboard-write")
  })

  it("generates and persists a guest id for a first-time visitor", async () => {
    localStorage.removeItem("xagent_guest_id")
    vi.spyOn(Math, "random")
      .mockReturnValueOnce(0.123456)
      .mockReturnValueOnce(0.654321)
    fetchMock.mockResolvedValueOnce(new Response(JSON.stringify({
      ticket: "ticket/one",
      agent_id: 17,
    }), {
      status: 200,
      headers: { "Content-Type": "application/json" },
    }))

    runWidget({ "data-widget-key": "widget-secret" })

    const guestId = localStorage.getItem("xagent_guest_id")
    expect(guestId).toBe("guest_4fzyo82mvyqnk000qvgin")
    await vi.waitFor(() => {
      expect(document.querySelector<HTMLIFrameElement>(".xagent-widget-iframe")?.src).toBe(
        `https://chat.example/widget/chat/default?guest_id=${guestId}&agent_id=17&embed_ticket=ticket%2Fone`,
      )
    })
  })

  it("loads an embed-ticket iframe URL without exposing the widget key", async () => {
    fetchMock.mockResolvedValueOnce(new Response(JSON.stringify({
      ticket: "ticket/one",
      agent_id: 17,
    }), {
      status: 200,
      headers: { "Content-Type": "application/json" },
    }))

    runWidget({ "data-widget-key": "widget-secret" })

    await vi.waitFor(() => {
      expect(document.querySelector<HTMLIFrameElement>(".xagent-widget-iframe")?.src).toBe(
        "https://chat.example/widget/chat/default?guest_id=guest-fixed&agent_id=17&embed_ticket=ticket%2Fone",
      )
    })
    expect(fetchMock).toHaveBeenCalledTimes(1)
    expect(fetchMock).toHaveBeenNthCalledWith(
      1,
      "https://chat.example/api/widget/embed-ticket",
      {
        method: "POST",
        headers: { "Content-Type": "application/json" },
        body: JSON.stringify({ widget_key: "widget-secret" }),
      },
    )
    expect(document.querySelector<HTMLIFrameElement>(".xagent-widget-iframe")?.src)
      .not.toContain("widget-secret")
  })

  it("does not navigate the iframe on a non-OK embed-ticket response", async () => {
    const errorSpy = vi.spyOn(console, "error").mockImplementation(() => undefined)
    fetchMock.mockResolvedValueOnce(new Response("forbidden", { status: 403 }))

    runWidget({ "data-widget-key": "widget-secret" })

    await vi.waitFor(() => {
      expect(errorSpy).toHaveBeenCalledWith(expect.stringContaining("embed authorization failed"))
    })
    expect(document.querySelector<HTMLIFrameElement>(".xagent-widget-iframe")?.getAttribute("src")).toBeNull()
  })

  it("does not navigate the iframe on an embed-ticket network failure", async () => {
    const errorSpy = vi.spyOn(console, "error").mockImplementation(() => undefined)
    fetchMock.mockRejectedValueOnce(new Error("network unavailable"))

    runWidget({ "data-widget-key": "widget-secret" })

    await vi.waitFor(() => {
      expect(errorSpy).toHaveBeenCalledWith(expect.stringContaining("embed authorization request failed"))
    })
    expect(document.querySelector<HTMLIFrameElement>(".xagent-widget-iframe")?.getAttribute("src")).toBeNull()
  })

  it("keeps the deprecated non-default token channel available without a ticket", () => {
    runWidget({ "data-token": "legacy-token" })

    expect(fetchMock).not.toHaveBeenCalled()
    expect(document.querySelector<HTMLIFrameElement>(".xagent-widget-iframe")?.src).toBe(
      "https://chat.example/widget/chat/legacy-token?guest_id=guest-fixed",
    )
  })

  describe("panel resize", () => {
    let originalInnerWidth: number

    beforeEach(() => {
      originalInnerWidth = window.innerWidth
      // userSelect/cursor are reset in the outer beforeEach above.
      fetchMock.mockResolvedValue(new Response(JSON.stringify({
        ticket: "ticket/one",
        agent_id: 17,
      }), {
        status: 200,
        headers: { "Content-Type": "application/json" },
      }))
    })

    afterEach(() => {
      setInnerWidth(originalInnerWidth)
    })

    function setInnerWidth(value: number) {
      Object.defineProperty(window, "innerWidth", { configurable: true, value })
    }

    function panel() {
      return document.querySelector<HTMLDivElement>(".xagent-widget-panel")!
    }

    function handle() {
      return document.querySelector<HTMLDivElement>(".xagent-widget-resize-handle")!
    }

    function openPanel() {
      // The handle is only draggable while the panel carries the 'open'
      // class (see the pointerdown guard in widget.js) -- click the FAB,
      // the same real-world path a user takes, rather than poking the class
      // directly.
      document.querySelector<HTMLButtonElement>(".xagent-widget-fab")!.click()
    }

    function widgetIframe() {
      return document.querySelector<HTMLIFrameElement>(".xagent-widget-iframe")!
    }

    function firePointerEvent(
      target: EventTarget,
      type: string,
      init: { pointerId: number; clientX: number; button?: number },
    ) {
      // jsdom has no PointerEvent constructor; a plain Event with the fields
      // the widget reads is enough since addEventListener matches by type.
      const event = new MouseEvent(type, {
        bubbles: true,
        cancelable: true,
        clientX: init.clientX,
        button: init.button ?? 0,
      })
      Object.defineProperty(event, "pointerId", { value: init.pointerId })
      target.dispatchEvent(event)
      return event
    }

    it("applies the default width on a fresh visit", () => {
      runWidget({ "data-widget-key": "widget-secret" })
      expect(panel().style.width).toBe("380px")
    })

    it("applies a persisted width from localStorage", () => {
      localStorage.setItem("xagent_widget_width", "500")
      runWidget({ "data-widget-key": "widget-secret" })
      expect(panel().style.width).toBe("500px")
    })

    it("falls back to the default width for a corrupt stored value", () => {
      localStorage.setItem("xagent_widget_width", "not-a-number")
      runWidget({ "data-widget-key": "widget-secret" })
      expect(panel().style.width).toBe("380px")
    })

    it("falls back to the default width for an out-of-range stored value", () => {
      localStorage.setItem("xagent_widget_width", "99999")
      runWidget({ "data-widget-key": "widget-secret" })
      expect(panel().style.width).toBe("380px")
    })

    it("falls back to the default width for a stored value below the minimum", () => {
      // Only the upper bound was covered above; MIN_PANEL_WIDTH is a
      // separate comparison in the same guard.
      localStorage.setItem("xagent_widget_width", "100")
      runWidget({ "data-widget-key": "widget-secret" })
      expect(panel().style.width).toBe("380px")
    })

    it("accepts a stored value at exactly the minimum boundary", () => {
      // readStoredWidth rejects strictly below MIN_PANEL_WIDTH (320) -- pin
      // that the boundary value itself is accepted, not folded into the
      // rejected range by an off-by-one.
      localStorage.setItem("xagent_widget_width", "320")
      runWidget({ "data-widget-key": "widget-secret" })
      expect(panel().style.width).toBe("320px")
    })

    it("accepts a stored value at exactly the maximum boundary", () => {
      // Same as above for the upper MAX_PANEL_WIDTH (720) boundary.
      localStorage.setItem("xagent_widget_width", "720")
      runWidget({ "data-widget-key": "widget-secret" })
      expect(panel().style.width).toBe("720px")
    })

    it("falls back to the default width when reading storage throws", () => {
      const realGetItem = window.localStorage.getItem.bind(window.localStorage)
      vi.spyOn(window.localStorage, "getItem").mockImplementation((key) => {
        if (key === "xagent_widget_width") throw new Error("blocked")
        return realGetItem(key)
      })
      runWidget({ "data-widget-key": "widget-secret" })
      expect(panel().style.width).toBe("380px")
    })

    it("round-trips a dragged width through storage into a fresh load", () => {
      // Every other persistence test either seeds storage directly or checks
      // it after a drag -- neither proves a value a drag itself wrote is
      // actually what the *next* page load reads back. Simulate that next
      // load by tearing down this instance's DOM and re-running the
      // bootstrap script, the same way a real page refresh would.
      // The describe-level mock resolves every call with the same Response
      // instance, whose body a single fetch already consumes -- this test
      // fetches twice (once per runWidget), so it needs a fresh Response per
      // call instead.
      fetchMock.mockImplementation(() => Promise.resolve(new Response(JSON.stringify({
        ticket: "ticket/one",
        agent_id: 17,
      }), {
        status: 200,
        headers: { "Content-Type": "application/json" },
      })))
      runWidget({ "data-widget-key": "widget-secret" })
      openPanel()

      firePointerEvent(handle(), "pointerdown", { pointerId: 10, clientX: 300 })
      firePointerEvent(handle(), "pointermove", { pointerId: 10, clientX: 200 })
      expect(panel().style.width).toBe("480px")
      firePointerEvent(handle(), "pointerup", { pointerId: 10, clientX: 200 })
      expect(localStorage.getItem("xagent_widget_width")).toBe("480")

      document.head.innerHTML = ""
      document.body.innerHTML = ""
      runWidget({ "data-widget-key": "widget-secret" })
      expect(panel().style.width).toBe("480px")
    })

    it("re-clamps to the viewport on resize without losing the stored preference", () => {
      localStorage.setItem("xagent_widget_width", "600")
      runWidget({ "data-widget-key": "widget-secret" })
      expect(panel().style.width).toBe("600px")

      setInnerWidth(500)
      window.dispatchEvent(new Event("resize"))
      expect(panel().style.width).toBe("460px")

      setInnerWidth(1024)
      window.dispatchEvent(new Event("resize"))
      expect(panel().style.width).toBe("600px")
    })

    it("does not corrupt a stored preference wider than the load-time viewport", () => {
      localStorage.setItem("xagent_widget_width", "700")
      setInnerWidth(600) // viewportMax = 560, so the initial render clamps the display
      runWidget({ "data-widget-key": "widget-secret" })
      expect(panel().style.width).toBe("560px")

      // A click-and-release with no movement must not persist the render
      // clamp over the raw stored preference.
      openPanel()
      firePointerEvent(handle(), "pointerdown", { pointerId: 6, clientX: 300 })
      firePointerEvent(handle(), "pointerup", { pointerId: 6, clientX: 300 })
      expect(localStorage.getItem("xagent_widget_width")).toBe("700")

      // Widening the viewport back must recover the full preference, not the
      // narrower value that was ever rendered.
      setInnerWidth(1024)
      window.dispatchEvent(new Event("resize"))
      expect(panel().style.width).toBe("700px")
    })

    it("does not lose a wider preference to a drag that never escapes the viewport ceiling", () => {
      localStorage.setItem("xagent_widget_width", "700")
      setInnerWidth(600) // viewportMax = 560
      runWidget({ "data-widget-key": "widget-secret" })
      expect(panel().style.width).toBe("560px")

      // A 1px nudge attempting to widen further is fully absorbed by the
      // ceiling -- the rendered width never actually changes, unlike a true
      // zero-movement release.
      openPanel()
      firePointerEvent(handle(), "pointerdown", { pointerId: 11, clientX: 300 })
      firePointerEvent(handle(), "pointermove", { pointerId: 11, clientX: 299 })
      expect(panel().style.width).toBe("560px")
      firePointerEvent(handle(), "pointerup", { pointerId: 11, clientX: 299 })

      // The 700px preference must survive this drag, not get silently
      // replaced by the 560px ceiling it never actually moved past.
      expect(localStorage.getItem("xagent_widget_width")).toBe("700")
      setInnerWidth(1024)
      window.dispatchEvent(new Event("resize"))
      expect(panel().style.width).toBe("700px")
    })

    it("does adopt a genuinely smaller width when a drag visibly shrinks past the ceiling", () => {
      localStorage.setItem("xagent_widget_width", "700")
      setInnerWidth(600) // viewportMax = 560
      runWidget({ "data-widget-key": "widget-secret" })

      // Drag right (shrink) past the ceiling: a real, visible size change,
      // as opposed to the previous test's absorbed widening attempt.
      openPanel()
      firePointerEvent(handle(), "pointerdown", { pointerId: 12, clientX: 300 })
      firePointerEvent(handle(), "pointermove", { pointerId: 12, clientX: 350 })
      expect(panel().style.width).toBe("510px") // 560 - 50, a real shrink
      firePointerEvent(handle(), "pointerup", { pointerId: 12, clientX: 350 })

      expect(localStorage.getItem("xagent_widget_width")).toBe("510")
    })

    it("hides the inline width below the mobile breakpoint and restores it above", () => {
      runWidget({ "data-widget-key": "widget-secret" })

      setInnerWidth(400)
      window.dispatchEvent(new Event("resize"))
      expect(panel().style.width).toBe("")

      setInnerWidth(1024)
      window.dispatchEvent(new Event("resize"))
      expect(panel().style.width).toBe("380px")
    })

    it("declares the mobile media rule that actually hides the resize handle", () => {
      // jsdom doesn't evaluate CSS, so the inline-width behavior above can't
      // prove the stylesheet itself still hides the handle below the
      // breakpoint -- assert the injected rule text directly, so weakening
      // or dropping that declaration fails here even though it wouldn't
      // change any inline style the other tests observe.
      runWidget({ "data-widget-key": "widget-secret" })
      const css = document.head.querySelector("style")!.textContent!

      expect(css).toMatch(/@media\s*\(max-width:\s*480px\)/)
      const mobileBlock = css.slice(css.indexOf("@media"))
      expect(mobileBlock).toMatch(/\.xagent-widget-resize-handle\s*{[^}]*display:\s*none/)
    })

    it("declares the closed-panel rule that hides the resize handle without JS", () => {
      // Same rationale as the mobile-rule test above: the JS-level
      // panel.classList.contains('open') check in the pointerdown guard is
      // defense in depth, not the primary mechanism -- this stylesheet rule
      // is what actually keeps the handle un-hit-testable while the panel is
      // closed on a real page.
      runWidget({ "data-widget-key": "widget-secret" })
      const css = document.head.querySelector("style")!.textContent!

      expect(css).toMatch(
        /\.xagent-widget-panel:not\(\.open\)\s*\.xagent-widget-resize-handle\s*{[^}]*display:\s*none/,
      )
    })

    it("declares the closed-panel rule that stops it swallowing clicks during its fade-out", () => {
      // Same visibility-transition gap as the resize-handle rule above, but
      // for the panel itself: without pointer-events: none here, a closed
      // panel stays hit-testable for the whole ~300ms fade, silently
      // intercepting input meant for the host page underneath -- the full
      // viewport on mobile, not just the small desktop popup's footprint.
      runWidget({ "data-widget-key": "widget-secret" })
      const css = document.head.querySelector("style")!.textContent!

      expect(css).toMatch(/\.xagent-widget-panel:not\(\.open\)\s*\{[^}]*pointer-events:\s*none;/)
    })

    it("declares the scroll-lock class rule with !important, so it wins over a host page's own inline overflow", () => {
      runWidget({ "data-widget-key": "widget-secret" })
      const css = document.head.querySelector("style")!.textContent!

      expect(css).toMatch(/\.xagent-widget-scroll-locked\s*\{[^}]*overflow:\s*hidden\s*!important;/)
    })

    it("ignores a drag start below the mobile breakpoint", () => {
      setInnerWidth(400)
      runWidget({ "data-widget-key": "widget-secret" })
      openPanel()

      // Isolate the mobile-viewport guard specifically: with the panel open,
      // only isMobileViewport() can be blocking this pointerdown.
      firePointerEvent(handle(), "pointerdown", { pointerId: 1, clientX: 100 })

      expect(document.body.style.userSelect).toBe("")
      expect(document.body.style.cursor).toBe("")
      expect(widgetIframe().style.pointerEvents).toBe("")
      // Proves dragState was never created, not just that these three
      // particular side effects happen to be unset.
      firePointerEvent(handle(), "pointermove", { pointerId: 1, clientX: 250 })
      expect(panel().style.width).toBe("")
    })

    it("ignores a drag start while expanded", () => {
      // The expanded rule's own width would otherwise get fought over an
      // inline width from a drag that isn't blocked here.
      runWidget({ "data-widget-key": "widget-secret" })
      openPanel()
      window.dispatchEvent(new MessageEvent("message", {
        data: { xagent: true, v: 1, type: "widget_expand" },
        origin: "https://chat.example",
        source: widgetIframe().contentWindow as Window,
      }))
      expect(panel()).toHaveClass("expanded")

      firePointerEvent(handle(), "pointerdown", { pointerId: 1, clientX: 100 })

      expect(document.body.style.userSelect).toBe("")
      // Proves dragState was never created, not just that userSelect happens
      // to be unset: a real drag would set an inline width here, clobbering
      // the .expanded rule's own width.
      firePointerEvent(handle(), "pointermove", { pointerId: 1, clientX: 250 })
      expect(panel().style.width).toBe("")
    })

    it("cancels an already-active drag when expand arrives mid-drag", () => {
      // isMobileViewport()/isExpanded in the pointerdown guard only block a
      // *new* drag from starting once expanded -- they don't touch a drag
      // already under way. That's reachable in practice: this drag's
      // pointerId is independent of whatever pointer taps "Expand window"
      // inside the iframe (e.g. a second finger, on a touch-capable
      // desktop-width device, while the first still holds the handle down),
      // and the host page's XagentWidget.open({ expanded: true }) can also
      // arrive mid-drag.
      // Without expandPanel() cancelling it, this pointerId's next
      // pointermove would go on setting an inline width, desyncing the
      // panel's rendered width from the .expanded class it now also carries.
      runWidget({ "data-widget-key": "widget-secret" })
      openPanel()

      firePointerEvent(handle(), "pointerdown", { pointerId: 30, clientX: 300 })
      firePointerEvent(handle(), "pointermove", { pointerId: 30, clientX: 200 })
      expect(panel().style.width).toBe("480px")
      expect(document.body.style.userSelect).toBe("none")

      window.dispatchEvent(new MessageEvent("message", {
        data: { xagent: true, v: 1, type: "widget_expand" },
        origin: "https://chat.example",
        source: widgetIframe().contentWindow as Window,
      }))

      expect(panel()).toHaveClass("expanded")
      expect(panel().style.width).toBe("")
      expect(document.body.style.userSelect).toBe("")
      // The abandoned in-progress width (480) must not have been committed
      // as the user's stored preference -- cancelDrag(), not endDrag().
      expect(localStorage.getItem("xagent_widget_width")).toBeNull()

      // The drag is over: this pointerId's continuation is a no-op, not a
      // desync between an inline width and the .expanded class.
      firePointerEvent(handle(), "pointermove", { pointerId: 30, clientX: 50 })
      expect(panel().style.width).toBe("")
      expect(panel()).toHaveClass("expanded")
    })

    it("cancels an already-active drag when the host page's open({ expanded: true }) arrives mid-drag", () => {
      runWidget({ "data-widget-key": "widget-secret" })
      openPanel()
      firePointerEvent(handle(), "pointerdown", { pointerId: 31, clientX: 300 })
      firePointerEvent(handle(), "pointermove", { pointerId: 31, clientX: 200 })
      expect(panel().style.width).toBe("480px")

      ;(window as unknown as { XagentWidget: { open: (options: unknown) => void } }).XagentWidget.open({ expanded: true })

      expect(panel()).toHaveClass("expanded")
      expect(panel().style.width).toBe("")
      expect(document.body.style.userSelect).toBe("")
      expect(localStorage.getItem("xagent_widget_width")).toBeNull()
      firePointerEvent(handle(), "pointermove", { pointerId: 31, clientX: 50 })
      expect(panel().style.width).toBe("")
      expect(panel()).toHaveClass("expanded")
    })

    it("boundary: applies the mobile CSS at exactly the breakpoint width, not just below it", () => {
      // isMobileViewport() uses <=, matching the CSS media query's own
      // max-width: 480px (also <= in CSS terms) -- off by one here would
      // mean inline width wins over the media query by specificity right at
      // this exact width, which is the one case the whole mobile branch
      // exists to prevent (see the comment above applyPanelWidth). 480 is
      // MOBILE_BREAKPOINT's value, not importable from widget.js's IIFE
      // closure -- the CSS-rule-content test above already pins that the
      // constant itself is 480, so hardcoding it here is safe.
      setInnerWidth(480)
      runWidget({ "data-widget-key": "widget-secret" })

      expect(panel().style.width).toBe("")
    })

    it("resizes the panel while dragging and persists the final width on release", () => {
      runWidget({ "data-widget-key": "widget-secret" })
      openPanel()
      document.body.style.userSelect = "text"

      firePointerEvent(handle(), "pointerdown", { pointerId: 7, clientX: 300 })
      expect(document.body.style.userSelect).toBe("none")
      expect(widgetIframe().style.pointerEvents).toBe("none")

      // startWidth is read from computed style, which reflects the panel's
      // width at drag start (380px, the default applied on load).
      firePointerEvent(handle(), "pointermove", { pointerId: 7, clientX: 400 })
      expect(panel().style.width).toBe("320px") // 380 - 100 = 280, clamped to MIN_PANEL_WIDTH

      firePointerEvent(handle(), "pointermove", { pointerId: 7, clientX: 180 })
      expect(panel().style.width).toBe("500px") // 380 + 120 = 500, within bounds

      firePointerEvent(handle(), "pointerup", { pointerId: 7, clientX: 180 })
      expect(document.body.style.userSelect).toBe("text")
      expect(widgetIframe().style.pointerEvents).toBe("")
      expect(localStorage.getItem("xagent_widget_width")).toBe("500")
    })

    it("clamps a drag to the static MAX_PANEL_WIDTH, not just the viewport ceiling", () => {
      // The other ceiling-clamp tests all clamp against a narrowed viewport
      // (viewportMax below 720) -- this one keeps the default wide viewport
      // (viewportMax = 984) so the static 720px cap itself is what stops the
      // drag, not window width.
      runWidget({ "data-widget-key": "widget-secret" })
      openPanel()

      firePointerEvent(handle(), "pointerdown", { pointerId: 9, clientX: 300 })
      firePointerEvent(handle(), "pointermove", { pointerId: 9, clientX: -100 }) // 380 + 400 = 780, capped to 720
      expect(panel().style.width).toBe("720px")

      firePointerEvent(handle(), "pointerup", { pointerId: 9, clientX: -100 })
      expect(localStorage.getItem("xagent_widget_width")).toBe("720")
    })

    it("commits the width the drag actually ends at, not the widest point it passed through", () => {
      // A very ordinary gesture: overshoot while dragging, then correct back
      // -- while still wider than the start, i.e. never triggering the old
      // "shrunk past the ceiling" escape hatch. The committed width must
      // match what's actually rendered when the pointer is released.
      runWidget({ "data-widget-key": "widget-secret" })
      openPanel()

      firePointerEvent(handle(), "pointerdown", { pointerId: 8, clientX: 300 })
      firePointerEvent(handle(), "pointermove", { pointerId: 8, clientX: 180 }) // overshoot to 500px
      expect(panel().style.width).toBe("500px")
      firePointerEvent(handle(), "pointermove", { pointerId: 8, clientX: 280 }) // correct back to 400px
      expect(panel().style.width).toBe("400px")

      firePointerEvent(handle(), "pointerup", { pointerId: 8, clientX: 280 })
      expect(panel().style.width).toBe("400px") // unchanged by the commit itself
      expect(localStorage.getItem("xagent_widget_width")).toBe("400") // not the passed-through 500
    })

    it("continues tracking the drag when pointermove/pointerup arrive on document rather than the handle", () => {
      // jsdom has no PointerEvent/setPointerCapture at all, so every other
      // test in this file dispatching pointermove/pointerup directly on
      // handle() can't distinguish "capture is retargeting these events"
      // from "these listeners just happen to live on the same element".
      // Real Pointer Capture would retarget events to the handle
      // regardless of what's under the cursor; bypass that entirely here by
      // dispatching where an event would actually land if capture were
      // unavailable and the cursor were, say, over the iframe.
      runWidget({ "data-widget-key": "widget-secret" })
      openPanel()

      firePointerEvent(handle(), "pointerdown", { pointerId: 27, clientX: 300 })
      firePointerEvent(document, "pointermove", { pointerId: 27, clientX: 200 })
      expect(panel().style.width).toBe("480px")

      firePointerEvent(document, "pointerup", { pointerId: 27, clientX: 200 })
      expect(localStorage.getItem("xagent_widget_width")).toBe("480")
    })

    it("releases pointer capture when a drag is cancelled, not just on a real release", () => {
      // Browsers auto-release capture on pointerup/pointercancel, but not on
      // blur or a plain resize -- restoreDragSideEffects releases it
      // explicitly for those paths. jsdom doesn't implement (release)
      // PointerCapture at all, so stub it directly on the handle instance to
      // observe the call (production code already guards the call in a
      // try/catch for exactly this kind of absence).
      runWidget({ "data-widget-key": "widget-secret" })
      openPanel()
      const releaseSpy = vi.fn()
      handle().releasePointerCapture = releaseSpy

      firePointerEvent(handle(), "pointerdown", { pointerId: 28, clientX: 300 })
      window.dispatchEvent(new Event("blur")) // cancels, no pointerup/pointercancel ever fires

      expect(releaseSpy).toHaveBeenCalledWith(28)
    })

    it("cancels rather than commits on pointercancel, reverting the in-progress width", () => {
      // pointercancel is an involuntary interruption (a touch gesture
      // reinterpreted as a scroll, an OS-level interrupt), not the user
      // confirming a release -- it must not persist wherever the drag had
      // gotten to.
      runWidget({ "data-widget-key": "widget-secret" })
      openPanel()

      firePointerEvent(handle(), "pointerdown", { pointerId: 2, clientX: 300 })
      firePointerEvent(handle(), "pointermove", { pointerId: 2, clientX: 250 }) // mid-drag, unconfirmed
      expect(panel().style.width).toBe("430px")

      firePointerEvent(handle(), "pointercancel", { pointerId: 2, clientX: 250 })

      expect(document.body.style.userSelect).toBe("")
      expect(widgetIframe().style.pointerEvents).toBe("")
      expect(panel().style.width).toBe("380px") // reverted, not left at the abandoned 430px
      expect(localStorage.getItem("xagent_widget_width")).toBeNull()
    })

    it("does not let a cancelled drag's abandoned width survive to be committed by a later no-op drag", () => {
      // A cancelled drag must never have touched the committed panelWidth in
      // the first place -- otherwise the abandoned in-progress value stays
      // the module's current width, and an unrelated zero-movement drag
      // later on would commit it via a normal release.
      runWidget({ "data-widget-key": "widget-secret" })
      openPanel()

      firePointerEvent(handle(), "pointerdown", { pointerId: 21, clientX: 300 })
      firePointerEvent(handle(), "pointermove", { pointerId: 21, clientX: 250 }) // -> 430px, abandoned below
      window.dispatchEvent(new Event("blur")) // cancels: 430 must never reach panelWidth
      expect(panel().style.width).toBe("380px")

      // An unrelated click-and-release with zero movement -- a true no-op,
      // so it persists nothing at all rather than re-affirming 380.
      firePointerEvent(handle(), "pointerdown", { pointerId: 22, clientX: 300 })
      firePointerEvent(handle(), "pointerup", { pointerId: 22, clientX: 300 })

      expect(localStorage.getItem("xagent_widget_width")).not.toBe("430")
      expect(localStorage.getItem("xagent_widget_width")).toBeNull()
    })

    it("restores the host page's own cursor rather than clearing it", () => {
      runWidget({ "data-widget-key": "widget-secret" })
      openPanel()
      document.body.style.cursor = "help"

      firePointerEvent(handle(), "pointerdown", { pointerId: 23, clientX: 300 })
      expect(document.body.style.cursor).toBe("ew-resize")

      firePointerEvent(handle(), "pointerup", { pointerId: 23, clientX: 300 })
      expect(document.body.style.cursor).toBe("help")
    })

    it("ignores a non-primary pointer button", () => {
      runWidget({ "data-widget-key": "widget-secret" })
      openPanel()

      // Isolate the button guard: with the panel open, only a non-primary
      // button can be blocking this pointerdown.
      firePointerEvent(handle(), "pointerdown", { pointerId: 24, clientX: 300, button: 2 })

      expect(document.body.style.userSelect).toBe("")
      expect(document.body.style.cursor).toBe("")
      expect(widgetIframe().style.pointerEvents).toBe("")
      // Proves dragState itself was never created, not just that these three
      // particular side effects happen to be unset: if the button guard were
      // moved after dragState's assignment, this assertion alone wouldn't
      // catch it, but a subsequent move actually changing the width would.
      firePointerEvent(handle(), "pointermove", { pointerId: 24, clientX: 100 })
      expect(panel().style.width).toBe("380px")
    })

    it("ignores a second concurrent pointer without disrupting the first pointer's drag", () => {
      runWidget({ "data-widget-key": "widget-secret" })
      openPanel()

      firePointerEvent(handle(), "pointerdown", { pointerId: 1, clientX: 300 })
      firePointerEvent(handle(), "pointerdown", { pointerId: 2, clientX: 100 })
      firePointerEvent(handle(), "pointermove", { pointerId: 2, clientX: 0 })
      expect(panel().style.width).toBe("380px") // untouched: pointer 2 was never tracked

      firePointerEvent(handle(), "pointerup", { pointerId: 2, clientX: 0 })
      expect(document.body.style.userSelect).toBe("none") // pointer 1's drag is still active

      firePointerEvent(handle(), "pointermove", { pointerId: 1, clientX: 250 })
      expect(panel().style.width).toBe("430px") // 380 + 50, from pointer 1's own startWidth

      firePointerEvent(handle(), "pointerup", { pointerId: 1, clientX: 250 })
      expect(document.body.style.userSelect).toBe("")
      expect(localStorage.getItem("xagent_widget_width")).toBe("430")
    })

    it("cancels (without persisting) an interrupted drag on window blur", () => {
      runWidget({ "data-widget-key": "widget-secret" })
      openPanel()

      firePointerEvent(handle(), "pointerdown", { pointerId: 3, clientX: 300 })
      firePointerEvent(handle(), "pointermove", { pointerId: 3, clientX: 250 }) // mid-drag, unconfirmed
      expect(document.body.style.cursor).toBe("ew-resize")

      window.dispatchEvent(new Event("blur"))

      expect(document.body.style.userSelect).toBe("")
      expect(document.body.style.cursor).toBe("")
      expect(widgetIframe().style.pointerEvents).toBe("")
      // A blur interruption is not the user confirming a width via release --
      // nothing was ever persisted in this test.
      expect(localStorage.getItem("xagent_widget_width")).toBeNull()
      // Reverted, not left at the abandoned 430px (380 + 50 from the move above).
      expect(panel().style.width).toBe("380px")

      // The cancelled drag is really over: further movement on the same
      // pointer does nothing, regardless of where it goes.
      firePointerEvent(handle(), "pointermove", { pointerId: 3, clientX: 100 })
      expect(panel().style.width).toBe("380px")
    })

    it("ignores a blur caused by focus moving into the widget's own iframe", () => {
      runWidget({ "data-widget-key": "widget-secret" })
      openPanel()
      vi.spyOn(document, "hasFocus").mockReturnValue(true)

      firePointerEvent(handle(), "pointerdown", { pointerId: 17, clientX: 300 })
      expect(document.body.style.userSelect).toBe("none")

      window.dispatchEvent(new Event("blur"))

      // document.hasFocus() still true means the window itself never lost
      // focus -- this blur doesn't interrupt the drag.
      expect(document.body.style.userSelect).toBe("none")

      firePointerEvent(handle(), "pointerup", { pointerId: 17, clientX: 300 })
      expect(document.body.style.userSelect).toBe("")
    })

    it("cancels an active drag on a genuine viewport change and re-renders for the new viewport", () => {
      runWidget({ "data-widget-key": "widget-secret" })
      openPanel()

      firePointerEvent(handle(), "pointerdown", { pointerId: 18, clientX: 300 })
      firePointerEvent(handle(), "pointermove", { pointerId: 18, clientX: 100 }) // -> 580px, abandoned below
      expect(panel().style.width).toBe("580px")
      expect(document.body.style.userSelect).toBe("none")

      // A real viewport change (not just a bare resize event) invalidates
      // this drag's frozen startX/startWidth anchors -- rather than let the
      // next pointermove misread the viewport's own movement as the user
      // shrinking the panel, the drag is cancelled outright, and the panel
      // re-renders for the *new* viewport off the untouched preference
      // (380), not a stale snapshot of the old render or the abandoned 580.
      setInnerWidth(350) // now below the mobile breakpoint
      window.dispatchEvent(new Event("resize"))

      expect(document.body.style.userSelect).toBe("")
      expect(widgetIframe().style.pointerEvents).toBe("")
      expect(localStorage.getItem("xagent_widget_width")).toBeNull()
      expect(panel().style.width).toBe("") // mobile now: inline width cleared, not "380px" or "580px"

      firePointerEvent(handle(), "pointermove", { pointerId: 18, clientX: 50 })
      expect(panel().style.width).toBe("") // still unaffected: the drag is over
    })

    it("does not cancel an active drag on a resize event that leaves the viewport width unchanged", () => {
      // Mobile browsers fire a bare `resize` event when the on-screen
      // keyboard opens/closes (innerHeight changes, innerWidth doesn't) --
      // startX/startWidth depend only on innerWidth, so this must not abort
      // an in-progress drag the way the genuine-width-change test above does.
      runWidget({ "data-widget-key": "widget-secret" })
      openPanel()

      firePointerEvent(handle(), "pointerdown", { pointerId: 26, clientX: 300 })
      firePointerEvent(handle(), "pointermove", { pointerId: 26, clientX: 250 })
      expect(panel().style.width).toBe("430px")
      expect(document.body.style.userSelect).toBe("none")

      window.dispatchEvent(new Event("resize")) // innerWidth unchanged

      expect(document.body.style.userSelect).toBe("none") // drag still active
      expect(panel().style.width).toBe("430px")

      firePointerEvent(handle(), "pointermove", { pointerId: 26, clientX: 200 })
      expect(panel().style.width).toBe("480px")
      firePointerEvent(handle(), "pointerup", { pointerId: 26, clientX: 200 })
      expect(localStorage.getItem("xagent_widget_width")).toBe("480")
    })

    it("keeps a wider preference across a drag that shrinks past the ceiling and returns to it", () => {
      localStorage.setItem("xagent_widget_width", "700")
      setInnerWidth(600) // viewportMax = 560
      runWidget({ "data-widget-key": "widget-secret" })
      openPanel()
      expect(panel().style.width).toBe("560px")

      firePointerEvent(handle(), "pointerdown", { pointerId: 19, clientX: 300 })
      // Genuinely shrink past the ceiling first...
      firePointerEvent(handle(), "pointermove", { pointerId: 19, clientX: 350 })
      expect(panel().style.width).toBe("510px")
      // ...then drag back up to exactly the ceiling value. Since this drag
      // already demonstrated a real shrink, this is now a deliberate choice
      // of 560, not an unmoved starting position -- it must NOT snap back to
      // the untouched 700px preference.
      firePointerEvent(handle(), "pointermove", { pointerId: 19, clientX: 300 })
      expect(panel().style.width).toBe("560px")
      firePointerEvent(handle(), "pointerup", { pointerId: 19, clientX: 300 })

      expect(localStorage.getItem("xagent_widget_width")).toBe("560")
    })

    it("does not restore userSelect if the host page changed it since drag start", () => {
      runWidget({ "data-widget-key": "widget-secret" })
      openPanel()

      firePointerEvent(handle(), "pointerdown", { pointerId: 13, clientX: 300 })
      expect(document.body.style.userSelect).toBe("none")

      // Host page sets its own value mid-drag, e.g. while rebuilding its own UI.
      document.body.style.userSelect = "all"

      firePointerEvent(handle(), "pointerup", { pointerId: 13, clientX: 300 })
      // Must NOT be clobbered back to the pre-drag snapshot.
      expect(document.body.style.userSelect).toBe("all")
    })

    it("does not restore cursor if the host page changed it since drag start", () => {
      // Same guard as userSelect above, applied to cursor -- restoreDragSideEffects
      // has two symmetric checks and this one had no dedicated negative-space
      // coverage of its own.
      runWidget({ "data-widget-key": "widget-secret" })
      openPanel()

      firePointerEvent(handle(), "pointerdown", { pointerId: 14, clientX: 300 })
      expect(document.body.style.cursor).toBe("ew-resize")

      document.body.style.cursor = "wait"

      firePointerEvent(handle(), "pointerup", { pointerId: 14, clientX: 300 })
      expect(document.body.style.cursor).toBe("wait")
    })

    it("does not throw when persisting the width fails", () => {
      runWidget({ "data-widget-key": "widget-secret" })
      openPanel()
      vi.spyOn(window.localStorage, "setItem").mockImplementation(() => {
        throw new Error("quota exceeded")
      })

      firePointerEvent(handle(), "pointerdown", { pointerId: 4, clientX: 300 })
      expect(() => firePointerEvent(handle(), "pointerup", { pointerId: 4, clientX: 300 }))
        .not.toThrow()
    })

    it("falls back to the default width if computed style is unreadable", () => {
      runWidget({ "data-widget-key": "widget-secret" })
      openPanel()
      vi.spyOn(window, "getComputedStyle").mockReturnValue({ width: "auto" } as CSSStyleDeclaration)

      firePointerEvent(handle(), "pointerdown", { pointerId: 5, clientX: 300 })
      firePointerEvent(handle(), "pointermove", { pointerId: 5, clientX: 250 })

      expect(panel().style.width).toBe("430px") // DEFAULT_PANEL_WIDTH (380) + 50
    })

    it("tears down cleanup immediately on DOM removal, even mid-drag, without waiting for blur", async () => {
      runWidget({ "data-widget-key": "widget-secret" })
      openPanel()
      document.body.style.userSelect = "text"

      firePointerEvent(handle(), "pointerdown", { pointerId: 14, clientX: 300 })
      expect(document.body.style.userSelect).toBe("none")

      document.querySelector(".xagent-widget-container")?.remove()
      // The teardown observer's callback fires as a microtask.
      await Promise.resolve()

      // Cleanup already ran on removal itself -- no blur or resize needed.
      expect(document.body.style.userSelect).toBe("text")
    })

    it("skips persisting the width for a drag interrupted by DOM removal", async () => {
      runWidget({ "data-widget-key": "widget-secret" })
      openPanel()

      firePointerEvent(handle(), "pointerdown", { pointerId: 15, clientX: 300 })
      firePointerEvent(handle(), "pointermove", { pointerId: 15, clientX: 200 }) // mid-drag, unconfirmed
      expect(panel().style.width).not.toBe("380px")

      document.querySelector(".xagent-widget-container")?.remove()
      await Promise.resolve()

      // The unconfirmed mid-drag width must not have been written to
      // storage -- nothing was ever persisted in this test at all.
      expect(localStorage.getItem("xagent_widget_width")).toBeNull()
    })

    it("tears down when the panel is removed directly, without container itself leaving the DOM", async () => {
      // Regression coverage for subtree: true. A remove() on .xagent-widget-
      // container (used by every other teardown test in this file) is
      // already a direct childList change on document.body, so it would
      // pass even with the narrower { childList: true } this diff replaced.
      // Removing panel out from under container, while container stays put,
      // only shows up as a *subtree* mutation of document.body -- this is
      // the one scenario that actually distinguishes the two.
      runWidget({ "data-widget-key": "widget-secret" })
      openPanel()
      document.body.style.userSelect = "text"

      firePointerEvent(handle(), "pointerdown", { pointerId: 25, clientX: 300 })
      expect(document.body.style.userSelect).toBe("none")

      panel().remove()
      await Promise.resolve()

      expect(document.body.style.userSelect).toBe("text")
    })

    it("never starts a new drag if the same panel node is later re-inserted into the DOM", async () => {
      runWidget({ "data-widget-key": "widget-secret" })
      openPanel()
      const container = document.querySelector(".xagent-widget-container")!
      const detachedHandle = handle()

      container.remove()
      await Promise.resolve() // teardown observer fires and disconnects

      // Re-inserting the SAME node (e.g. a host SPA's portal/keep-alive
      // remounting it) flips isConnected back to true without re-arming the
      // (already-disconnected) observer or any removed listener.
      document.body.appendChild(container)
      expect(container.isConnected).toBe(true)

      document.body.style.userSelect = "text"
      firePointerEvent(detachedHandle, "pointerdown", { pointerId: 20, clientX: 300 })
      // The torndown flag blocks this permanently, regardless of isConnected
      // -- the panel was opened above, so the open-state guard can't be
      // masking this as the actual reason.
      expect(document.body.style.userSelect).toBe("text")
    })

    it("starts fully closed if the same open panel node is later re-inserted into the DOM", async () => {
      // Regression coverage: fab.onclick and the iframe's own postMessage
      // close channel are BOTH permanently guarded by the torndown flag, so
      // a reinserted node that still carried a stale 'open'/readiness class
      // from before teardown would render an unclosable full-screen mobile
      // overlay -- the FAB hidden by CSS, and neither remaining "close" path
      // able to do anything about it.
      runWidget({ "data-widget-key": "widget-secret" })
      openPanel()
      window.dispatchEvent(new MessageEvent("message", {
        data: { xagent: true, v: 1, type: "widget_chrome_ready" },
        origin: "https://chat.example",
        source: widgetIframe().contentWindow as Window,
      }))
      expect(panel()).toHaveClass("open")
      expect(panel()).toHaveClass("xagent-widget-chrome-ready")
      const container = document.querySelector(".xagent-widget-container")!
      const detachedFab = document.querySelector<HTMLButtonElement>(".xagent-widget-fab")!

      container.remove()
      await Promise.resolve() // teardown observer fires and disconnects

      document.body.appendChild(container)

      expect(panel()).not.toHaveClass("open")
      expect(panel()).not.toHaveClass("xagent-widget-chrome-ready")
      expect(detachedFab.style.display).toBe("none")
    })

    it("stops reacting to window/document listeners once the panel leaves the DOM", async () => {
      // Spy without mockImplementation so these still call through -- we
      // want the real listeners attached, just also recorded.
      const winAddSpy = vi.spyOn(window, "addEventListener")
      const docAddSpy = vi.spyOn(document, "addEventListener")
      const winRemoveSpy = vi.spyOn(window, "removeEventListener")
      const docRemoveSpy = vi.spyOn(document, "removeEventListener")
      runWidget({ "data-widget-key": "widget-secret" })
      openPanel()
      const detachedHandle = handle()
      const detachedPanel = panel()

      function addedListener(spy: typeof winAddSpy, type: string) {
        const matches = spy.mock.calls.filter(([calledType]) => calledType === type)
        // Fail loudly on zero or multiple matches rather than silently
        // returning undefined (a legal, if useless, arg to
        // toHaveBeenCalledWith) or picking an arbitrary one of several.
        expect(matches).toHaveLength(1)
        return matches[0][1]
      }
      // Captured before removal so removeEventListener can be checked
      // against the *exact* function reference that was added -- not just
      // "any function", which would also pass if the wrong handler (or a
      // fresh unrelated one) were removed instead.
      const resizeListener = addedListener(winAddSpy, "resize")
      const blurListener = addedListener(winAddSpy, "blur")
      const pointermoveListener = addedListener(docAddSpy, "pointermove")
      const pointerupListener = addedListener(docAddSpy, "pointerup")
      const pointercancelListener = addedListener(docAddSpy, "pointercancel")

      document.querySelector(".xagent-widget-container")?.remove()
      await Promise.resolve()

      expect(winRemoveSpy).toHaveBeenCalledWith("resize", resizeListener)
      expect(winRemoveSpy).toHaveBeenCalledWith("blur", blurListener)
      expect(docRemoveSpy).toHaveBeenCalledWith("pointermove", pointermoveListener)
      expect(docRemoveSpy).toHaveBeenCalledWith("pointerup", pointerupListener)
      expect(docRemoveSpy).toHaveBeenCalledWith("pointercancel", pointercancelListener)

      // Behavioral proof for the resize listener specifically: below the
      // mobile breakpoint this would normally clear the inline width, so an
      // unchanged value after dispatch proves the listener is truly gone,
      // not just idle.
      const widthBeforeResize = detachedPanel.style.width
      setInnerWidth(400)
      window.dispatchEvent(new Event("resize"))
      expect(detachedPanel.style.width).toBe(widthBeforeResize)

      // Functional proof, not just a spy check that could pass even if the
      // handler removed were the wrong one: the torndown flag permanently
      // blocks pointerdown on this instance's handle -- covering a host SPA
      // re-inserting this same panel node later, which flips
      // panel.isConnected back to true without re-arming anything -- so a
      // fresh drag never starts and userSelect is never touched at all.
      document.body.style.userSelect = "text"
      firePointerEvent(detachedHandle, "pointerdown", { pointerId: 16, clientX: 300 })
      expect(document.body.style.userSelect).toBe("text")

      window.dispatchEvent(new Event("blur"))
      expect(document.body.style.userSelect).toBe("text")
    })
  })

  describe("mobile full screen", () => {
    function styleText() {
      return document.head.querySelector("style")!.innerHTML
    }

    // Slices from the @media marker to the end of the stylesheet text (it's
    // the last block in the template) rather than trying to match a precise
    // closing brace -- formatting drift inside the block (added/reordered
    // declarations) then can't make this fragile.
    function mobileBlock() {
      const text = styleText()
      const index = text.indexOf('@media (max-width: 480px)')
      if (index === -1) throw new Error("mobile media query block not found in generated <style>")
      return text.slice(index)
    }

    beforeEach(() => {
      fetchMock.mockResolvedValue(new Response(JSON.stringify({
        ticket: "ticket/one",
        agent_id: 17,
      }), {
        status: 200,
        headers: { "Content-Type": "application/json" },
      }))
    })

    it("makes the panel a true edge-to-edge overlay under the 480px breakpoint", () => {
      runWidget({ "data-widget-key": "widget-secret" })

      const block = mobileBlock()
      expect(block).toMatch(/\.xagent-widget-panel\s*\{[^}]*position:\s*fixed;/)
      expect(block).toMatch(/\.xagent-widget-panel\s*\{[^}]*inset:\s*0;/)
      expect(block).toMatch(/\.xagent-widget-panel\s*\{[^}]*border-radius:\s*0;/)
      // inset: 0 alone does not override the base rule's explicit
      // width: 380px / height: 600px / max-height: calc(100vh - 100px) --
      // these three overrides are what actually makes it edge-to-edge.
      expect(block).toMatch(/\.xagent-widget-panel\s*\{[^}]*width:\s*100%;/)
      // Anchored to a declaration boundary (start of the rule body, or right
      // after a preceding ';\n'), not just "not preceded by max-" -- a bare
      // negative lookbehind on "max-" still matches inside line-height,
      // min-height, or a custom property like --panel-height, any of which
      // could satisfy this if the real height: declaration were removed.
      expect(block).toMatch(/\.xagent-widget-panel\s*\{[^}]*(?:^|\n)\s*height:\s*100%;/)
      expect(block).toMatch(/\.xagent-widget-panel\s*\{[^}]*max-height:\s*100%;/)
      // Progressive enhancement over the two 100% fallbacks above -- tracks
      // a mobile browser's address-bar show/hide instead of leaving a gap
      // or an overflow against the "large" viewport 100% resolves against.
      expect(block).toMatch(/\.xagent-widget-panel\s*\{[^}]*(?:^|\n)\s*height:\s*100dvh;/)
      expect(block).toMatch(/\.xagent-widget-panel\s*\{[^}]*max-height:\s*100dvh;/)
      // Order matters, not just presence: on equal specificity the LAST
      // declaration wins, so the 100dvh enhancement must come after its 100%
      // fallback -- reordering them would still make every assertion above
      // pass while silently breaking the fallback for browsers that don't
      // parse dvh at all (they'd apply 100dvh as an unrecognized value, no
      // fallback left behind it).
      const panelRule = block.match(/\.xagent-widget-panel\s*\{([^}]*)\}/)![1]
      expect(panelRule.search(/(?:^|\n)\s*height:\s*100dvh;/)).toBeGreaterThan(panelRule.search(/(?:^|\n)\s*height:\s*100%;/))
      expect(panelRule.search(/max-height:\s*100dvh;/)).toBeGreaterThan(panelRule.search(/max-height:\s*100%;/))
    })

    it("respects device safe areas instead of drawing under a notch or home indicator", () => {
      runWidget({ "data-widget-key": "widget-secret" })

      // Scoped to the panel rule's own body, not the whole mobile media
      // block -- an unscoped match would still pass if these declarations
      // were ever moved into an unrelated rule in the same block.
      const panelRule = mobileBlock().match(/\.xagent-widget-panel\s*\{([^}]*)\}/)![1]
      // Match the whole env() expression, fallback included -- a regex that
      // stops at the property name would still pass if the ", 0px" fallback
      // (the only thing keeping non-supporting browsers at zero padding) were
      // ever dropped.
      expect(panelRule).toMatch(/padding-top:\s*env\(safe-area-inset-top,\s*0px\)/)
      expect(panelRule).toMatch(/padding-bottom:\s*env\(safe-area-inset-bottom,\s*0px\)/)
      // Landscape can put a side notch on either edge.
      expect(panelRule).toMatch(/padding-left:\s*env\(safe-area-inset-left,\s*0px\)/)
      expect(panelRule).toMatch(/padding-right:\s*env\(safe-area-inset-right,\s*0px\)/)
    })

    it("stops the safe-area padding strips from chaining a touch-scroll through to the host page", () => {
      runWidget({ "data-widget-key": "widget-secret" })

      const panelRule = mobileBlock().match(/\.xagent-widget-panel\s*\{([^}]*)\}/)![1]
      expect(panelRule).toMatch(/overscroll-behavior:\s*none;/)
    })

    it("hides the FAB only once the iframe has confirmed its own close control is mounted", () => {
      runWidget({ "data-widget-key": "widget-secret" })

      const block = mobileBlock()
      // Gated on .xagent-widget-chrome-ready (toggled by onChromeMessage in response
      // to widget_chrome_ready/widget_chrome_not_ready), not just .open --
      // see widget-chrome.test.ts for the message-driven class toggling this
      // selector depends on. Without that gate, a loading/auth-failure/
      // degraded Session state (none of which render a header) would hide
      // the parent's only close control on a full-screen mobile panel with
      // nothing to replace it.
      expect(block).toMatch(/\.xagent-widget-panel\.open\.xagent-widget-chrome-ready\s*~\s*\.xagent-widget-fab\s*\{[^}]*display:\s*none;/)
    })

    it("stacks the fallback FAB above the fixed panel instead of letting it paint underneath", () => {
      // The FAB is a plain in-flow (position: static) element by default;
      // the panel becomes position: fixed at this breakpoint. A positioned
      // element always paints above a non-positioned sibling regardless of
      // DOM order, so without an explicit stacking rule here the fixed
      // full-screen panel would visually cover -- and fail hit-testing
      // against -- the FAB in every state above that intentionally keeps it
      // as the fallback close control.
      runWidget({ "data-widget-key": "widget-secret" })

      const block = mobileBlock()
      expect(block).toMatch(/\.xagent-widget-fab\s*\{[^}]*position:\s*relative;/)
      expect(block).toMatch(/\.xagent-widget-fab\s*\{[^}]*z-index:\s*1;/)
    })

    it("offsets the fallback FAB's anchor point for device safe areas too", () => {
      // The panel's own safe-area padding has no effect on the FAB, which
      // is anchored by the container's bottom/right instead -- without this,
      // a safe-area inset wider than the base 20px can leave part of the
      // touch target inside a notch/home-indicator/gesture area while the
      // child hasn't confirmed readiness.
      runWidget({ "data-widget-key": "widget-secret" })

      const block = mobileBlock()
      expect(block).toMatch(/\.xagent-widget-container\s*\{[^}]*bottom:\s*calc\(20px \+ env\(safe-area-inset-bottom,\s*0px\)\);/)
      expect(block).toMatch(/\.xagent-widget-container\s*\{[^}]*right:\s*calc\(20px \+ env\(safe-area-inset-right,\s*0px\)\);/)
    })

    it("keeps the panel and FAB as siblings, with the panel first, which the FAB-hiding sibling selector depends on", () => {
      // .xagent-widget-panel.open.xagent-widget-chrome-ready ~ .xagent-widget-fab
      // is a general sibling combinator: it requires the panel and FAB to
      // share the same parent AND the panel to precede the FAB. Document
      // order alone (compareDocumentPosition) doesn't prove same-parent
      // membership -- a future wrapper around just the FAB (or just the
      // panel) could keep the panel textually first while making this
      // selector permanently inert, leaving the ready-state FAB visible
      // forever with no other test catching it.
      runWidget({ "data-widget-key": "widget-secret" })

      const panel = document.querySelector(".xagent-widget-panel")!
      const fab = document.querySelector(".xagent-widget-fab")!
      expect(panel.parentElement).toBe(fab.parentElement)
      const panelComesFirst = Boolean(panel.compareDocumentPosition(fab) & Node.DOCUMENT_POSITION_FOLLOWING)
      expect(panelComesFirst).toBe(true)
    })
  })

  describe("matchMedia-driven viewport detection", () => {
    let originalInnerWidth: number

    beforeEach(() => {
      originalInnerWidth = window.innerWidth
      fetchMock.mockResolvedValue(new Response(JSON.stringify({
        ticket: "ticket/one",
        agent_id: 17,
      }), {
        status: 200,
        headers: { "Content-Type": "application/json" },
      }))
    })

    afterEach(() => {
      setInnerWidth(originalInnerWidth)
    })

    function setInnerWidth(value: number) {
      Object.defineProperty(window, "innerWidth", { configurable: true, value })
    }

    // isMobileViewport() prefers window.matchMedia over window.innerWidth,
    // but jsdom (every other test in this file) has no matchMedia at all --
    // that only exercises the innerWidth fallback branch. These tests stub
    // matchMedia in so the primary branch itself is actually covered, not
    // just assumed correct from reading the source.
    function stubMatchMedia() {
      let matches = false
      const mql = {
        get matches() {
          return matches
        },
        media: "",
      }
      const matchMediaSpy = vi.fn((query: string) => {
        mql.media = query
        return mql as unknown as MediaQueryList
      })
      vi.stubGlobal("matchMedia", matchMediaSpy)
      return { matchMediaSpy, set: (value: boolean) => { matches = value } }
    }

    function panelWidthStyle() {
      return document.querySelector<HTMLDivElement>(".xagent-widget-panel")!.style.width
    }

    it("queries the exact mobile breakpoint media string", () => {
      const { matchMediaSpy } = stubMatchMedia()

      runWidget({ "data-widget-key": "widget-secret" })

      expect(matchMediaSpy).toHaveBeenCalledWith("(max-width: 480px)")
    })

    it("prefers matchMedia over a conflicting innerWidth when deciding mobile behavior", () => {
      // A genuine innerWidth-vs-CSS-viewport-width disagreement (see
      // isMobileViewport()'s own comment) is exactly why matchMedia exists
      // here -- innerWidth alone would say "desktop" at this width.
      setInnerWidth(1280)
      const { set } = stubMatchMedia()
      set(true) // the CSS engine says mobile

      runWidget({ "data-widget-key": "widget-secret" })

      // Mobile means the CSS media query owns sizing -- no inline width.
      expect(panelWidthStyle()).toBe("")
    })

    it("re-reads a stubbed matchMedia's answer on resize, not just at initial load", () => {
      setInnerWidth(1280)
      const { set } = stubMatchMedia()
      set(false)
      runWidget({ "data-widget-key": "widget-secret" })
      expect(panelWidthStyle()).not.toBe("")

      set(true)
      setInnerWidth(1281) // must actually change, or onWindowResize no-ops
      window.dispatchEvent(new Event("resize"))

      expect(panelWidthStyle()).toBe("")
    })
  })

  describe("mobile scroll lock", () => {
    let originalInnerWidth: number

    beforeEach(() => {
      originalInnerWidth = window.innerWidth
      fetchMock.mockResolvedValue(new Response(JSON.stringify({
        ticket: "ticket/one",
        agent_id: 17,
      }), {
        status: 200,
        headers: { "Content-Type": "application/json" },
      }))
    })

    afterEach(() => {
      setInnerWidth(originalInnerWidth)
    })

    function setInnerWidth(value: number) {
      Object.defineProperty(window, "innerWidth", { configurable: true, value })
    }

    function openViaFab() {
      document.querySelector<HTMLButtonElement>(".xagent-widget-fab")!.click()
    }

    function isLocked() {
      return document.documentElement.classList.contains("xagent-widget-scroll-locked")
    }

    it("locks the host page's scroll on mobile while the panel is open", () => {
      setInnerWidth(400)
      runWidget({ "data-widget-key": "widget-secret" })

      openViaFab()

      expect(isLocked()).toBe(true)
    })

    it("locks document.scrollingElement (documentElement, where jsdom has no scrollingElement), not body specifically", () => {
      // Regression coverage: a host page that sets its own overflow
      // directly on <html> (e.g. html { overflow-y: scroll }, a common
      // technique to avoid scrollbar-width layout shift) breaks the usual
      // body-to-viewport overflow propagation -- a body-only lock would do
      // nothing at all on such a page, leaving the background scrollable
      // behind the "full-screen" panel.
      setInnerWidth(400)
      runWidget({ "data-widget-key": "widget-secret" })

      openViaFab()

      expect(document.documentElement).toHaveClass("xagent-widget-scroll-locked")
      expect(document.body).not.toHaveClass("xagent-widget-scroll-locked")
    })

    it("never touches the host page's own overflow value, before, during, or after the lock", () => {
      // The lock is a namespaced class, not a read/write of the shared
      // overflow value a host page might independently use for its own
      // scroll-locking -- there's nothing to "restore" because nothing is
      // ever captured or written to that value in the first place.
      setInnerWidth(400)
      document.documentElement.style.overflow = "auto"
      runWidget({ "data-widget-key": "widget-secret" })

      openViaFab()
      expect(isLocked()).toBe(true)
      expect(document.documentElement.style.overflow).toBe("auto")

      openViaFab()
      expect(isLocked()).toBe(false)
      expect(document.documentElement.style.overflow).toBe("auto")
    })

    it("leaves a host page's own overflow value alone even if it independently uses the same value the old lock used to write", () => {
      // Regression coverage for the bug the class-based lock replaced: the
      // previous overflow='hidden' implementation could not tell its own
      // value apart from a host page's own, separately-managed modal using
      // the same string -- closing the widget could silently unlock that
      // still-open host modal. A class-only lock can't make that mistake
      // because it never inspects this value at all.
      setInnerWidth(400)
      runWidget({ "data-widget-key": "widget-secret" })
      openViaFab()
      expect(isLocked()).toBe(true)

      // The host page's own, unrelated modal also locks scroll the same way.
      document.documentElement.style.overflow = "hidden"

      openViaFab() // closes the widget

      expect(isLocked()).toBe(false)
      // The host's own value is untouched -- not silently cleared by the
      // widget's release.
      expect(document.documentElement.style.overflow).toBe("hidden")
    })

    it("keeps its own lock in force even if the host page changes its own overflow value while still open", () => {
      // The reverse interleaving: the host releasing (or otherwise
      // changing) its own overflow value must not be able to accidentally
      // unlock the widget's still-open full-screen panel.
      setInnerWidth(400)
      runWidget({ "data-widget-key": "widget-secret" })
      openViaFab()
      expect(isLocked()).toBe(true)

      document.documentElement.style.overflow = ""

      expect(isLocked()).toBe(true)
    })

    it("never locks on desktop", () => {
      setInnerWidth(1280)
      runWidget({ "data-widget-key": "widget-secret" })

      openViaFab()

      expect(isLocked()).toBe(false)
    })

    it("unlocks if a device rotation crosses the breakpoint while the panel stays open", () => {
      setInnerWidth(400)
      runWidget({ "data-widget-key": "widget-secret" })
      openViaFab()
      expect(isLocked()).toBe(true)

      setInnerWidth(800)
      window.dispatchEvent(new Event("resize"))

      expect(isLocked()).toBe(false)
    })

    it("locks if a device rotation crosses the breakpoint the other way while open", () => {
      setInnerWidth(800)
      runWidget({ "data-widget-key": "widget-secret" })
      openViaFab()
      expect(isLocked()).toBe(false)

      setInnerWidth(400)
      window.dispatchEvent(new Event("resize"))

      expect(isLocked()).toBe(true)
    })

    it("releases the lock if a host SPA removes the widget while open on mobile", async () => {
      setInnerWidth(400)
      runWidget({ "data-widget-key": "widget-secret" })
      openViaFab()
      expect(isLocked()).toBe(true)

      document.querySelector(".xagent-widget-container")?.remove()
      // The teardown observer's callback fires as a microtask.
      await Promise.resolve()

      expect(isLocked()).toBe(false)
    })

    it("keeps the lock held while a second widget instance on the same page still needs it", () => {
      // Ref-counted on the lock target element, precisely so one instance closing
      // can't unlock scrolling out from under another instance still open.
      setInnerWidth(400)
      // A single shared Response instance (the describe-level default) can
      // only have its body read once -- give each of the two instances'
      // embed-ticket fetch its own fresh Response so the second doesn't log
      // a spurious "Body is unusable" failure unrelated to what's under test.
      fetchMock.mockImplementation(() => Promise.resolve(new Response(JSON.stringify({
        ticket: "ticket/one",
        agent_id: 17,
      }), {
        status: 200,
        headers: { "Content-Type": "application/json" },
      })))
      runWidget({ "data-widget-key": "widget-secret" })
      runWidget({ "data-widget-key": "widget-secret-2" })
      const fabs = document.querySelectorAll<HTMLButtonElement>(".xagent-widget-fab")
      expect(fabs.length).toBe(2)

      fabs[0]!.click()
      fabs[1]!.click()
      expect(isLocked()).toBe(true)

      fabs[0]!.click() // closes only the first instance
      expect(isLocked()).toBe(true)

      fabs[1]!.click() // closes the second and last instance
      expect(isLocked()).toBe(false)
    })

    it("does not re-lock scroll on a FAB click after the panel is torn down while open", async () => {
      // Regression coverage: the panel can be removed directly while the
      // container/FAB stay in the DOM (see the "tears down when the panel is
      // removed directly" test elsewhere in this file). Teardown itself
      // releases the lock, but the FAB's click handler used to have no
      // torndown guard, so a later click could still call openPanel() on the
      // now-detached panel and reacquire the lock -- with the teardown
      // observer already disconnected, nothing would ever release it again.
      setInnerWidth(400)
      runWidget({ "data-widget-key": "widget-secret" })
      openViaFab()
      expect(isLocked()).toBe(true)

      document.querySelector(".xagent-widget-panel")?.remove()
      await Promise.resolve() // teardown observer's callback fires as a microtask
      expect(isLocked()).toBe(false)

      openViaFab() // the FAB is still in the DOM and clickable
      expect(isLocked()).toBe(false)
    })
  })
})