@artooi/ag-ui-web-component 0.34.0 → 0.35.0

package/src/dom/animations.ts

@@ -6,6 +6,7 @@
  * Each is configurable; pass small/zero durations in tests (or use fake timers).
  */
 
+import { showHighlightOverlay } from "./highlight_overlay.js";
 import { setNativeChecked, setNativeValue } from "./native_setter.js";
 
 /** Ring colour when the host page has not themed `--ag-ui-accent`. */
@@ -180,6 +181,20 @@ export interface FlashOptions {
   flashMs?: number;
   /** Ring colour. Defaults to the target's `--ag-ui-accent`, else the package accent. */
   color?: string;
+  /**
+   * Dim everything except the target.
+   *
+   * Switches the ring from an outline on the element to an overlay drawn
+   * outside it -- see {@link showHighlightOverlay} for why those are the same
+   * decision. The overlay never takes a pointer event, so a scrim here does
+   * not stop the page being used, or the driver clicking what it just pointed
+   * at.
+   */
+  scrim?: boolean;
+  /** Draw the ring as a moving gradient. Also an overlay, for the same reason. */
+  gradient?: boolean;
+  /** Gap between the target's box and an overlay ring. Default 4. */
+  ringPadding?: number;
   /**
    * Move keyboard focus to the element as well. Defaults to false for
    * {@link flash} and true for {@link focusWithFlash}.
@@ -201,6 +216,21 @@ async function flashRing(
   if (flashMs <= 0) {
     return;
   }
+  // A scrim or a gradient cannot be an outline on the element -- an outline
+  // takes a colour, and anything that can be a gradient is a property of the
+  // target and so is clipped by whatever is clipping the target. Both are the
+  // same overlay, so asking for either takes that path.
+  if (options.scrim === true || options.gradient === true) {
+    const dismiss = showHighlightOverlay(el, {
+      scrim: options.scrim === true,
+      gradient: options.gradient === true,
+      ...(options.color === undefined ? {} : { color: options.color }),
+      ...(options.ringPadding === undefined ? {} : { padding: options.ringPadding }),
+    });
+    await delay(flashMs);
+    dismiss();
+    return;
+  }
   const previousOutline = el.style.outline;
   const previousOffset = el.style.outlineOffset;
   const previousTransition = el.style.transition;

package/src/dom/highlight_overlay.ts

@@ -0,0 +1,256 @@
+import { HIGHLIGHT_OVERLAY_Z_INDEX } from "../constants.js";
+
+/** The package accent, used when the host has themed nothing. */
+const ACCENT = "#4f46e5";
+
+/** How the overlay is drawn around the element being pointed at. */
+export interface HighlightOverlayOptions {
+  /** Dim everything except the target. Default false. */
+  readonly scrim?: boolean;
+  /** Draw the ring as a moving gradient rather than a flat colour. Default false. */
+  readonly gradient?: boolean;
+  /** Ring colour, and the flat fallback for the gradient. */
+  readonly color?: string;
+  /** Gap between the target's box and the ring. Default 4. */
+  readonly padding?: number;
+  /** Corner radius of the cut-out and the ring. Default: the target's own. */
+  readonly radius?: number;
+  /** Ring thickness. Default 3, or `--ag-ui-highlight-ring-width` on the target. */
+  readonly ringWidth?: number;
+  /** One pass of the gradient. Default 2400, or `--ag-ui-highlight-flow-ms`. */
+  readonly flowMs?: number;
+}
+
+/**
+ * Read a `--ag-ui-*` token from the element being pointed at.
+ *
+ * From the *target*, not from the overlay. The overlay is appended to the
+ * document body so it can escape the clipping this exists to avoid, which also
+ * means a `var()` in its own inline style resolves against the body's cascade --
+ * so a host that themes the widget the documented way, on `ag-ui-chat` or on a
+ * wrapper, would never reach it. The target is on the host's page and inherits
+ * the host's cascade, which is the same reason the flat ring reads its accent
+ * there.
+ */
+function tokenOn(target: HTMLElement, name: string, fallback: string): string {
+  const value = window.getComputedStyle(target).getPropertyValue(name).trim();
+  return value === "" ? fallback : value;
+}
+
+/** Default gap between the target's border box and the ring around it. */
+const DEFAULT_PADDING_PX = 4;
+
+/**
+ * Draw an overlay that points at `target`, and return a function that removes
+ * it.
+ *
+ * **Why an overlay rather than a style on the target.** The flat highlight
+ * writes an `outline` onto the element itself, and that is deliberate: a
+ * `box-shadow` paints outside the border box, so any `overflow: hidden`
+ * ancestor sharing the target's box -- a card, a table cell -- clips the whole
+ * ring away while the helper still reports success. But an outline takes a
+ * *colour*. There is no `outline-image`, so a gradient ring cannot be one, and
+ * every alternative that can be a gradient is a property of the target and
+ * lands back inside whatever is clipping it.
+ *
+ * Dimming everything else wants the same thing from the other direction: a
+ * surface larger than the target, which cannot be a property of the target. So
+ * the scrim and the gradient are one mechanism rather than two features, and
+ * both escape the clipping the outline was chosen to avoid, because nothing
+ * here is a descendant of the element being pointed at.
+ *
+ * **It is inert.** The overlay never takes a pointer event, at the cut-out or
+ * anywhere else. A dim that swallows clicks is a modal the user did not open,
+ * and the driver's own point-then-click helper has to reach the control it just
+ * finished pointing at.
+ *
+ * **It follows.** The cut-out is recomputed on scroll and resize, because a
+ * highlight that stays where the target used to be is worse than none: it
+ * points confidently at the wrong thing.
+ */
+export function showHighlightOverlay(
+  target: HTMLElement,
+  options: HighlightOverlayOptions = {},
+): () => void {
+  const root = document.createElement("div");
+  root.setAttribute("data-ag-ui-highlight", "");
+  // aria-hidden because the ring is decoration: the announcement that this
+  // element matters is the agent's message, and a screen reader reaching a
+  // second, contentless copy of it learns nothing.
+  root.setAttribute("aria-hidden", "true");
+  root.style.cssText = [
+    "position: fixed",
+    "inset: 0",
+    "pointer-events: none",
+    // Above the widget's own default, because the overlay's whole job is to
+    // point at something on the page the widget is sitting over. A host whose
+    // chrome stacks higher still can say so.
+    `z-index: ${tokenOn(target, "--ag-ui-highlight-z-index", String(HIGHLIGHT_OVERLAY_Z_INDEX))}`,
+  ].join(";");
+
+  const scrim = document.createElement("div");
+  const ring = document.createElement("div");
+  // Named, because this overlay lives in the host's document rather than in
+  // the shadow tree: `::part` cannot reach it, so a class is the only handle a
+  // host has on the two boxes beyond the tokens they read.
+  root.className = "ag-ui-highlight";
+  scrim.className = "ag-ui-highlight-scrim";
+  ring.className = "ag-ui-highlight-ring";
+  if (options.scrim === true) {
+    root.append(scrim);
+  }
+  root.append(ring);
+
+  const ringWidth =
+    options.ringWidth ?? Number.parseFloat(tokenOn(target, "--ag-ui-highlight-ring-width", "3"));
+  const flowMs =
+    options.flowMs ?? Number.parseFloat(tokenOn(target, "--ag-ui-highlight-flow-ms", "2400"));
+
+  const paint = (): void => {
+    const box = target.getBoundingClientRect();
+    const pad = options.padding ?? DEFAULT_PADDING_PX;
+    // No fallback for an unparseable radius: getComputedStyle on an element in
+    // the document always resolves this, and the overlay is only ever shown for
+    // one the driver has already found. A guard here would be a branch no test
+    // can reach honestly.
+    const radius = options.radius ?? Number.parseFloat(getComputedStyle(target).borderRadius);
+    const left = box.left - pad;
+    const top = box.top - pad;
+    const width = box.width + pad * 2;
+    const height = box.height + pad * 2;
+
+    if (options.scrim === true) {
+      // A hole rather than four rectangles: one element, and it stays a hole
+      // through a radius. The outer ring runs clockwise and the inner one
+      // anticlockwise, which is what makes evenodd treat the inside as outside.
+      scrim.style.cssText = [
+        "position: absolute",
+        "inset: 0",
+        `background: ${tokenOn(target, "--ag-ui-highlight-scrim", "rgba(15, 15, 25, 0.45)")}`,
+        `clip-path: path(evenodd, '${holePath(left, top, width, height, radius + pad)}')`,
+      ].join(";");
+    }
+
+    ring.style.cssText = [
+      "position: absolute",
+      `left: ${left}px`,
+      `top: ${top}px`,
+      `width: ${width}px`,
+      `height: ${height}px`,
+      `border-radius: ${radius + pad}px`,
+      `border: ${ringWidth}px solid transparent`,
+      "box-sizing: border-box",
+      ringPaint(target, options),
+    ].join(";");
+  };
+
+  paint();
+  // Animated from script rather than a CSS keyframe, because the overlay lives
+  // in the host's document and not in the shadow tree: a keyframe would mean
+  // injecting a rule into someone else's stylesheet and remembering whether it
+  // had already been injected, which is module-level state this package does
+  // not keep.
+  //
+  // Reduced motion asks for no animation, not for no feedback -- the gradient
+  // is still drawn, it simply stops travelling.
+  let flow: Animation | null = null;
+  if (options.gradient === true && !window.matchMedia("(prefers-reduced-motion: reduce)").matches) {
+    flow = ring.animate([{ backgroundPosition: "100% 0" }, { backgroundPosition: "-100% 0" }], {
+      duration: flowMs,
+      iterations: Number.POSITIVE_INFINITY,
+      easing: "linear",
+    });
+  }
+  // Capture, so a scroll inside any container reaches this and not just one on
+  // the document. Passive: this only reads geometry and paints.
+  const listen = { capture: true, passive: true } as const;
+  window.addEventListener("scroll", paint, listen);
+  window.addEventListener("resize", paint, listen);
+  document.body.appendChild(root);
+
+  return () => {
+    window.removeEventListener("scroll", paint, listen);
+    window.removeEventListener("resize", paint, listen);
+    // Cancelled as well as detached. An infinite animation never finishes, so
+    // it is never auto-removed the way a finite one is; removing the node
+    // ought to make it irrelevant and collectable, but that is a claim about
+    // when an engine drops a non-relevant animation rather than something this
+    // function controls. Cancelling makes the teardown total and costs a call.
+    flow?.cancel();
+    root.remove();
+  };
+}
+
+/**
+ * A caller's colour, or `null` if it is not one.
+ *
+ * The value is joined into a `;`-separated `cssText` run, so a string carrying
+ * its own semicolon would write further declarations onto a `position: fixed;
+ * inset: 0` element in the host's page. This function is newly public and
+ * "point at this element in colour X" is the obvious wiring for it, with X
+ * coming from wherever the host got it -- which can be the agent.
+ */
+function safeColor(value: string | undefined): string | null {
+  if (value === undefined) {
+    return null;
+  }
+  return CSS.supports("color", value) ? value : null;
+}
+
+/**
+ * The ring's paint: a flat border, or a gradient masked to the border box.
+ *
+ * A gradient border needs the mask because a background paints inside the
+ * border, not on it -- the two-layer mask keeps the border box and subtracts
+ * the padding box, leaving the frame.
+ */
+function ringPaint(target: HTMLElement, options: HighlightOverlayOptions): string {
+  const color = safeColor(options.color) ?? tokenOn(target, "--ag-ui-accent", ACCENT);
+  if (options.gradient !== true) {
+    return `border-color: ${color}`;
+  }
+  const image = tokenOn(
+    target,
+    "--ag-ui-highlight-gradient",
+    `linear-gradient(115deg, transparent 20%, ${color} 50%, transparent 80%)`,
+  );
+  const mask = "linear-gradient(#000 0 0) content-box, linear-gradient(#000 0 0)";
+  return [
+    `background-image: ${image}`,
+    "background-origin: border-box",
+    "background-size: 300% 100%",
+    `-webkit-mask: ${mask}`,
+    `mask: ${mask}`,
+    "-webkit-mask-composite: xor",
+    "mask-composite: exclude",
+    "background-position: 50% 0",
+  ].join(";");
+}
+
+/**
+ * A viewport-sized rectangle with a rounded rectangle cut out of it, as an SVG
+ * path for `clip-path: path(evenodd, ...)`.
+ *
+ * Written in absolute commands and closed explicitly, because a `clip-path`
+ * that fails to parse is not an error anywhere -- the declaration is dropped
+ * and the scrim silently covers the target it was meant to reveal.
+ */
+function holePath(x: number, y: number, width: number, height: number, radius: number): string {
+  const r = Math.max(0, Math.min(radius, width / 2, height / 2));
+  const right = x + width;
+  const bottom = y + height;
+  const outer = `M 0 0 H ${window.innerWidth} V ${window.innerHeight} H 0 Z`;
+  const hole = [
+    `M ${x + r} ${y}`,
+    `H ${right - r}`,
+    `A ${r} ${r} 0 0 1 ${right} ${y + r}`,
+    `V ${bottom - r}`,
+    `A ${r} ${r} 0 0 1 ${right - r} ${bottom}`,
+    `H ${x + r}`,
+    `A ${r} ${r} 0 0 1 ${x} ${bottom - r}`,
+    `V ${y + r}`,
+    `A ${r} ${r} 0 0 1 ${x + r} ${y}`,
+    "Z",
+  ].join(" ");
+  return `${outer} ${hole}`;
+}

package/src/index.ts

@@ -107,8 +107,20 @@ export {
   setControlValue,
   toggleCheckbox,
 } from "./dom/dom_driver.js";
+export {
+  type HighlightOverlayOptions,
+  showHighlightOverlay,
+} from "./dom/highlight_overlay.js";
 export { setNativeChecked, setNativeValue } from "./dom/native_setter.js";
 export type { Skill } from "./skills/skill.js";
+export {
+  CHAT_CORNERS,
+  type ChatCorner,
+  type ChatSurface,
+  type ChatSurfaceReport,
+  createChatSurfaceTools,
+  isChatCorner,
+} from "./tools/chat_surface_tools.js";
 export { type ClientTool, ClientToolRegistry } from "./tools/client_tool_registry.js";
 export { isDestructive } from "./tools/is_destructive.js";
 export { isNavigates } from "./tools/is_navigates.js";

package/src/tools/chat_surface_tools.ts

@@ -0,0 +1,207 @@
+import { X_SUMMARY_KEY } from "../constants.js";
+import type { ClientTool } from "./client_tool_registry.js";
+
+/** Every corner the panel can be sent to, in the order the schema states them. */
+export const CHAT_CORNERS = ["top-left", "top-right", "bottom-left", "bottom-right"] as const;
+
+/** A corner the panel can be sent to. */
+export type ChatCorner = (typeof CHAT_CORNERS)[number];
+
+/** What the agent is told about the surface it is speaking from. */
+export interface ChatSurfaceReport {
+  /** The placement in force, or `null` when the host set none. */
+  readonly placement: string | null;
+  /** Whether the panel is currently at its launcher. */
+  readonly collapsed: boolean;
+  /** Whether this placement has a collapsed state at all. */
+  readonly collapsible: boolean;
+  /** Whether the panel can be moved, or the placement owns its position. */
+  readonly movable: boolean;
+  /**
+   * Whether this page allows the panel to be moved at all.
+   *
+   * Reported apart from {@link ChatSurfaceReport.movable} only because the two
+   * reasons a move is refused call for different sentences: a host that turned
+   * dragging off is not the placement owning the position, and telling the
+   * user the second when the first is true is a plain falsehood.
+   */
+  readonly draggable: boolean;
+  /** Whether the panel currently covers the whole viewport. */
+  readonly fullBleed: boolean;
+  /** The panel's box, in viewport coordinates. */
+  readonly box: {
+    readonly left: number;
+    readonly top: number;
+    readonly width: number;
+    readonly height: number;
+  };
+  /**
+   * The part of the viewport the panel may rest in.
+   *
+   * With an origin, because it is not always the screen's: a host can reserve
+   * the edges its own chrome occupies, and an agent reasoning about the room
+   * to the left of `box.left` would otherwise be mixing two coordinate frames
+   * without being told there were two.
+   */
+  readonly viewport: {
+    readonly left: number;
+    readonly top: number;
+    readonly width: number;
+    readonly height: number;
+  };
+}
+
+/** Whether a string names one of the four corners. */
+export function isChatCorner(value: string): value is ChatCorner {
+  return (CHAT_CORNERS as readonly string[]).includes(value);
+}
+
+/**
+ * The part of the widget these tools drive.
+ *
+ * A narrow port rather than the element itself, because the element imports
+ * this module to build its own tools and importing it back would be a cycle.
+ * It also says exactly what the agent is allowed to reach, which is a shorter
+ * list than the element's public surface.
+ */
+export interface ChatSurface {
+  describeSurface(): ChatSurfaceReport;
+  /**
+   * `announce` writes a notice into the transcript with an undo beside it.
+   * The tools always pass it: a panel that rearranges itself mid-conversation
+   * has to say so, and a host driving the same method is arranging its own
+   * page and needs no telling.
+   */
+  moveTo(corner: ChatCorner, options?: { readonly announce?: boolean }): boolean;
+  setCollapsed(collapsed: boolean, options?: { readonly announce?: boolean }): void;
+}
+
+/**
+ * Tools that let the agent move the panel it is speaking from.
+ *
+ * This is the affordance nobody else can offer: every other assistant's chat
+ * is a surface of its own, so there is nothing for it to be in the way *of*.
+ * Ours is mounted in the page the user is working in, which is what makes
+ * "let me move this aside so you can see the table" a sentence the agent can
+ * act on rather than apologise for.
+ *
+ * **They report what happened, not what was asked.** A full-bleed panel on a
+ * phone has nowhere to move to, and a placement that places itself owns its
+ * position -- so `move_chat` answers `moved: false` with the reason and what
+ * would work instead, rather than returning success on a panel that did not
+ * budge. The same rule the page actions already follow: a tool reports that it
+ * fired, not that it worked.
+ *
+ * `read_chat_surface` exists so the agent can ask before it acts rather than
+ * discovering the answer through a failure. It is deliberately a tool and not
+ * ambient context: a snapshot the agent chose to take is honest about being
+ * one, and it needs no channel that does not already exist.
+ */
+export function createChatSurfaceTools(surface: ChatSurface): ClientTool[] {
+  return [
+    {
+      name: "read_chat_surface",
+      description:
+        "Describe the chat panel you are speaking from: its placement, whether it is " +
+        "collapsed, whether it can be moved, and the box it occupies. Read this before " +
+        "moving or minimising yourself, since a full-screen panel has nowhere to move to. " +
+        "Read-only.",
+      parameters: {
+        type: "object",
+        properties: {},
+        required: [],
+        [X_SUMMARY_KEY]: "Read the chat's own position",
+      },
+      handler: () => surface.describeSurface(),
+    },
+    {
+      name: "move_chat",
+      description:
+        "Move your own panel to a corner, to uncover something the user needs to see. " +
+        "`corner` is top-left, top-right, bottom-left or bottom-right. Answers " +
+        "`moved: false` with a reason when the placement owns its position or the panel " +
+        "fills the screen; check `read_chat_surface` first, and prefer minimise_chat when " +
+        "there is nowhere to move to.",
+      parameters: {
+        type: "object",
+        properties: {
+          corner: {
+            type: "string",
+            enum: [...CHAT_CORNERS],
+          },
+        },
+        required: ["corner"],
+        [X_SUMMARY_KEY]: "Move the chat out of the way",
+      },
+      handler: (args) => {
+        const asked = String(args["corner"] ?? "");
+        const report = surface.describeSurface();
+        // Checked, not cast. `required` is advisory and a model can answer
+        // with a corner that does not exist; `moveTo` would then match none of
+        // its edge tests, send the panel bottom-right, and this would report
+        // success for the corner it was asked for -- so the agent tells the
+        // user it moved the chat somewhere it did not.
+        if (!isChatCorner(asked)) {
+          return {
+            moved: false,
+            reason: `"${asked}" is not a corner; use one of ${CHAT_CORNERS.join(", ")}`,
+          };
+        }
+        if (!report.movable) {
+          // Named rather than thrown: this is a fact about the surface the
+          // agent can act on -- minimise instead -- not a malformed call.
+          return {
+            moved: false,
+            reason: report.fullBleed
+              ? "the panel fills the screen, so there is nowhere to move it to"
+              : report.draggable === false
+                ? "this page has turned off moving the panel"
+                : `the "${report.placement ?? ""}" placement owns the panel's position`,
+            suggestion: report.collapsible ? "minimise_chat" : null,
+          };
+        }
+        return { moved: surface.moveTo(asked, { announce: true }), corner: asked };
+      },
+    },
+    {
+      name: "minimise_chat",
+      description:
+        "Collapse your own panel to its launcher, so the user can see the whole page. " +
+        "The launcher stays visible and reopens it. Answers `minimised: false` when the " +
+        "placement has no collapsed state, which is the case for a full-page chat.",
+      parameters: {
+        type: "object",
+        properties: {},
+        required: [],
+        [X_SUMMARY_KEY]: "Minimise the chat",
+      },
+      handler: () => {
+        const report = surface.describeSurface();
+        if (!report.collapsible) {
+          return {
+            minimised: false,
+            reason: "this placement has no collapsed state, so there is no launcher to return to",
+          };
+        }
+        surface.setCollapsed(true, { announce: true });
+        return { minimised: true };
+      },
+    },
+    {
+      name: "restore_chat",
+      description: "Open your own panel again after minimising it.",
+      parameters: {
+        type: "object",
+        properties: {},
+        required: [],
+        [X_SUMMARY_KEY]: "Restore the chat",
+      },
+      handler: () => {
+        // No notice: the user can see the panel come back, and a notice about
+        // something visibly happening is noise.
+        surface.setCollapsed(false);
+        return { restored: true };
+      },
+    },
+  ];
+}

package/src/tools/page_action_tools.ts

@@ -13,6 +13,8 @@ export type ResolvePageTarget = (target: string) => HTMLElement | null;
 export const PAGE_ACTIONS = {
   SCROLL: "scroll",
   DRAG: "drag",
+  /** The widget's own position: see `createChatSurfaceTools`. */
+  CHAT: "chat",
 } as const;
 
 /**

package/src/ui/clamp_launcher.ts

@@ -1,20 +1,38 @@
-import type { Extent, LauncherBox } from "./launcher_placement.js";
+import { SCREEN_EDGE_MARGIN } from "../constants.js";
+import type { LauncherBox, ViewportBox } from "./launcher_placement.js";
 
 /**
- * Keep a launcher fully on screen.
+ * Keep a launcher fully on screen, and a little clear of the edge.
  *
  * Applied to a dragged position and again to a restored one, because the
  * viewport that stored it may since have shrunk. A launcher parked past the
  * edge is unreachable, and it is the only way back to a collapsed
- * conversation -- so this clamps to the viewport itself rather than to the
- * panel's margin, which would refuse the corners users actually want.
+ * conversation.
+ *
+ * Not the panel's 24px gutter, which was rejected here on purpose: a launcher
+ * held that far in refuses the corners people actually drag it to. But not
+ * zero either -- the bubble is a circle with a drop shadow, and one flush
+ * against the boundary has its shadow cut and its curve running into the edge,
+ * which reads as clipped whether or not a pixel is actually missing.
  */
 export function clampLauncher(
   launcher: LauncherBox,
-  viewport: Extent,
+  viewport: ViewportBox,
+  margin: number = SCREEN_EDGE_MARGIN,
 ): { readonly left: number; readonly top: number } {
+  // The margin is given up rather than enforced where it does not fit: a
+  // viewport narrower than the bubble and its two margins would otherwise
+  // produce a lower bound above the upper one and pin it to the wrong edge.
+  const room = Math.min(margin, Math.max(0, (viewport.width - launcher.width) / 2));
+  const vertical = Math.min(margin, Math.max(0, (viewport.height - launcher.height) / 2));
   return {
-    left: Math.max(0, Math.min(launcher.left, viewport.width - launcher.width)),
-    top: Math.max(0, Math.min(launcher.top, viewport.height - launcher.height)),
+    left: Math.max(
+      viewport.left + room,
+      Math.min(launcher.left, viewport.left + viewport.width - launcher.width - room),
+    ),
+    top: Math.max(
+      viewport.top + vertical,
+      Math.min(launcher.top, viewport.top + viewport.height - launcher.height - vertical),
+    ),
   };
 }

package/src/ui/clamp_panel.ts

@@ -1,5 +1,5 @@
 import { EDGE_MARGIN } from "../constants.js";
-import type { Extent } from "./launcher_placement.js";
+import type { ViewportBox } from "./launcher_placement.js";
 import type { PanelRect } from "./resize_handle.js";
 
 /**
@@ -13,12 +13,18 @@ import type { PanelRect } from "./resize_handle.js";
  */
 export function clampPanel(
   host: PanelRect,
-  viewport: Extent,
+  viewport: ViewportBox,
   margin: number = EDGE_MARGIN,
 ): PanelRect {
   const width = host.right - host.left;
   const height = host.bottom - host.top;
-  const left = Math.max(margin, Math.min(host.left, viewport.width - margin - width));
-  const top = Math.max(margin, Math.min(host.top, viewport.height - margin - height));
+  const left = Math.max(
+    viewport.left + margin,
+    Math.min(host.left, viewport.left + viewport.width - margin - width),
+  );
+  const top = Math.max(
+    viewport.top + margin,
+    Math.min(host.top, viewport.top + viewport.height - margin - height),
+  );
   return { left, top, right: left + width, bottom: top + height };
 }

package/src/ui/launcher_drag.ts

@@ -1,5 +1,5 @@
 import { clampLauncher } from "./clamp_launcher.js";
-import type { Extent, LauncherBox } from "./launcher_placement.js";
+import type { LauncherBox, ViewportBox } from "./launcher_placement.js";
 
 /** What the drag needs from its host to do its job. */
 export interface LauncherDragOptions {
@@ -12,7 +12,7 @@ export interface LauncherDragOptions {
   /** The launcher's current box, in viewport coordinates. */
   readonly rect: () => LauncherBox;
   /** The viewport the launcher has to stay inside. */
-  readonly viewport: () => Extent;
+  readonly viewport: () => ViewportBox;
   /** Put the launcher's top-left at this point. Called per pointer move. */
   readonly apply: (left: number, top: number) => void;
   /**
@@ -106,6 +106,7 @@ export function enableLauncherDrag(launcher: HTMLElement, options: LauncherDragO
     const onUp = (up: PointerEvent): void => {
       window.removeEventListener("pointermove", onMove);
       window.removeEventListener("pointerup", onUp);
+      window.removeEventListener("pointercancel", onUp);
       if (!dragging) {
         return;
       }
@@ -124,8 +125,16 @@ export function enableLauncherDrag(launcher: HTMLElement, options: LauncherDragO
 
     // Listeners on `window`, not the launcher: a fast drag outruns the pointer
     // and would otherwise strand it mid-move with no pointerup.
+    //
+    // pointercancel matters on touch, where it is routine rather than
+    // exceptional: the browser takes the pointer back for a scroll or a system
+    // gesture and never sends pointerup. Without this the move listeners stay
+    // attached and the drag stamp never clears, which leaves the launcher
+    // following a finger that has stopped and the element believing a gesture
+    // is still in flight.
     window.addEventListener("pointermove", onMove);
     window.addEventListener("pointerup", onUp);
+    window.addEventListener("pointercancel", onUp);
   });
 
   // The position this key gesture has applied but not yet persisted. The