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

package/src/ui/chart_block.ts

@@ -11,6 +11,20 @@
  * Hand-rolled rather than a charting library, and the difference is not
  * marginal: the whole renderer costs single-digit kilobytes where a library
  * costs roughly half this bundle again, in a component distributed over a CDN.
+ *
+ * **The drawing is sized in CSS pixels, not scaled to them.** An SVG with a
+ * fixed viewBox and `width: 100%` is a picture the browser magnifies: widen the
+ * panel and every stroke, every label and the whole frame grow with it. So the
+ * geometry is computed for the width the block actually has, one user unit to
+ * one CSS pixel, and recomputed when that width changes -- a 10px label is
+ * 10px at every size the block is given.
+ *
+ * How wide the block is allowed to get is the stylesheet's question, not this
+ * module's, and the answer there is that a chart stops at its own width rather
+ * than stretching with the panel, the way a message does. The two halves are
+ * separate on purpose: this one keeps a chart from being magnified, that one
+ * keeps it from being stretched, and a host that raises the cap gets a bigger
+ * chart with the same 10px labels rather than a magnified one.
  */
 
 const SVG_NS = "http://www.w3.org/2000/svg";
@@ -32,11 +46,55 @@ export interface ChartSpec {
   readonly series: readonly ChartSeries[];
 }
 
-const WIDTH = 480;
-const HEIGHT = 220;
+/** The frame a chart is drawn into, in CSS pixels. */
+interface Geometry {
+  readonly width: number;
+  readonly height: number;
+  /** The plotting area inside the padding. */
+  readonly plotW: number;
+  readonly plotH: number;
+}
+
 const PAD = { top: 20, right: 12, bottom: 30, left: 44 };
-const PLOT_W = WIDTH - PAD.left - PAD.right;
-const PLOT_H = HEIGHT - PAD.top - PAD.bottom;
+
+/**
+ * The width drawn before the block has been measured -- while it is still
+ * detached, and in a caller that never puts it in a document at all. It is the
+ * width this renderer drew at unconditionally before it could measure, so a
+ * chart that is never measured looks exactly as it always did.
+ */
+const DEFAULT_WIDTH = 480;
+
+/**
+ * The narrowest frame worth computing. Below this the SVG scales down as it
+ * always did, which is the right answer at the bottom end: a 200px chart with
+ * 10px labels has no room for the labels either way, and shrinking them keeps
+ * the shape readable.
+ */
+const MIN_WIDTH = 220;
+
+/**
+ * How tall a chart is for its width, and the band that holds. The ratio is the
+ * old fixed 480x220 frame, so the default width draws precisely what it drew
+ * before; the band is what stops a wide panel from turning a chart into a
+ * banner or a narrow one into a strip.
+ */
+const HEIGHT_RATIO = 220 / 480;
+const MIN_HEIGHT = 160;
+const MAX_HEIGHT = 320;
+
+/**
+ * The step a measured width is rounded to before it is redrawn.
+ *
+ * The SVG keeps `width="100%"`, so it fills its block exactly whatever the
+ * viewBox says; rounding the viewBox to 8px therefore costs at most a 3%
+ * scale at the narrow end and nothing anyone can see, while cutting the
+ * redraws during a panel drag from one per pixel to one per eight.
+ */
+const WIDTH_STEP = 8;
+
+/** A rough advance width per character for the 10px axis font. */
+const AXIS_CHAR_WIDTH = 5.6;
 
 // Read from the host's own palette rather than a fixed ramp: the component
 // themes through custom properties everywhere else, and a chart that ignored
@@ -57,6 +115,18 @@ export function seriesColor(index: number): string {
   return SERIES_COLORS[index % SERIES_COLORS.length] as string;
 }
 
+/** The frame for a block of this width. */
+function geometryFor(width: number): Geometry {
+  const w = Math.max(MIN_WIDTH, width);
+  const h = Math.min(MAX_HEIGHT, Math.max(MIN_HEIGHT, Math.round(w * HEIGHT_RATIO)));
+  return {
+    width: w,
+    height: h,
+    plotW: w - PAD.left - PAD.right,
+    plotH: h - PAD.top - PAD.bottom,
+  };
+}
+
 function el<K extends keyof SVGElementTagNameMap>(
   name: K,
   attrs: Record<string, string | number>,
@@ -108,23 +178,44 @@ function extent(spec: ChartSpec): { min: number; max: number } {
   return max === min ? { min, max: max + 1 } : { min, max };
 }
 
-function scaleY(value: number, min: number, max: number): number {
-  return PAD.top + PLOT_H - ((value - min) / (max - min)) * PLOT_H;
+function scaleY(value: number, min: number, max: number, geo: Geometry): number {
+  return PAD.top + geo.plotH - ((value - min) / (max - min)) * geo.plotH;
 }
 
-function bandCentre(index: number, count: number): number {
-  const step = PLOT_W / count;
+function bandCentre(index: number, count: number, geo: Geometry): number {
+  const step = geo.plotW / count;
   return PAD.left + step * index + step / 2;
 }
 
-function drawAxes(svg: SVGSVGElement, spec: ChartSpec, min: number, max: number): void {
+/**
+ * Draw every nth label, for the smallest n whose labels have room.
+ *
+ * Axis text is a fixed 10px now rather than something that shrank with the
+ * frame, so at the narrow end the labels are the first thing to collide -- and
+ * a smear of overlapping words says less than half as many words with space
+ * around them. The character estimate only has to be good enough to pick a
+ * step; measuring text properly would mean laying it out first.
+ */
+function labelStride(labels: readonly string[], geo: Geometry): number {
+  const band = geo.plotW / labels.length;
+  const widest = Math.max(...labels.map((label) => label.length)) * AXIS_CHAR_WIDTH;
+  return Math.max(1, Math.ceil(widest / band));
+}
+
+function drawAxes(
+  svg: SVGSVGElement,
+  spec: ChartSpec,
+  geo: Geometry,
+  min: number,
+  max: number,
+): void {
   for (const value of [min, max]) {
-    const y = scaleY(value, min, max);
+    const y = scaleY(value, min, max, geo);
     svg.appendChild(
       el("line", {
         x1: PAD.left,
         y1: y,
-        x2: WIDTH - PAD.right,
+        x2: geo.width - PAD.right,
         y2: y,
         stroke: "currentColor",
         "stroke-opacity": value === min ? 0.35 : 0.12,
@@ -134,24 +225,34 @@ function drawAxes(svg: SVGSVGElement, spec: ChartSpec, min: number, max: number)
       text(String(Math.round(value)), { x: PAD.left - 6, y: y + 4, "text-anchor": "end" }),
     );
   }
+  const stride = labelStride(spec.labels, geo);
   spec.labels.forEach((label, i) => {
+    if (i % stride !== 0) {
+      return;
+    }
     svg.appendChild(
       text(label, {
-        x: bandCentre(i, spec.labels.length),
-        y: HEIGHT - PAD.bottom + 16,
+        x: bandCentre(i, spec.labels.length, geo),
+        y: geo.height - PAD.bottom + 16,
         "text-anchor": "middle",
       }),
     );
   });
 }
 
-function drawBars(svg: SVGSVGElement, spec: ChartSpec, min: number, max: number): void {
-  const step = PLOT_W / spec.labels.length;
+function drawBars(
+  svg: SVGSVGElement,
+  spec: ChartSpec,
+  geo: Geometry,
+  min: number,
+  max: number,
+): void {
+  const step = geo.plotW / spec.labels.length;
   const width = (step * 0.7) / spec.series.length;
-  const base = scaleY(min, min, max);
+  const base = scaleY(min, min, max, geo);
   spec.series.forEach((series, s) => {
     series.points.forEach((value, i) => {
-      const y = scaleY(value, min, max);
+      const y = scaleY(value, min, max, geo);
       svg.appendChild(
         el("rect", {
           x: PAD.left + step * i + step * 0.15 + width * s,
@@ -166,8 +267,14 @@ function drawBars(svg: SVGSVGElement, spec: ChartSpec, min: number, max: number)
   });
 }
 
-function drawStacked(svg: SVGSVGElement, spec: ChartSpec, min: number, max: number): void {
-  const step = PLOT_W / spec.labels.length;
+function drawStacked(
+  svg: SVGSVGElement,
+  spec: ChartSpec,
+  geo: Geometry,
+  min: number,
+  max: number,
+): void {
+  const step = geo.plotW / spec.labels.length;
   const width = step * 0.7;
   // Indexed by the same `i` it was built from, so every read is a hit; cast
   // rather than defaulting, which would add a branch nothing can reach.
@@ -182,13 +289,13 @@ function drawStacked(svg: SVGSVGElement, spec: ChartSpec, min: number, max: numb
       const from = running[i] ?? 0;
       const to = from + value;
       running[i] = to;
-      const y = scaleY(to, min, max);
+      const y = scaleY(to, min, max, geo);
       svg.appendChild(
         el("rect", {
           x: PAD.left + step * i + step * 0.15,
           y,
           width,
-          height: Math.max(1, scaleY(from, min, max) - y),
+          height: Math.max(1, scaleY(from, min, max, geo) - y),
           fill: seriesColor(s),
         }),
       );
@@ -196,10 +303,18 @@ function drawStacked(svg: SVGSVGElement, spec: ChartSpec, min: number, max: numb
   });
 }
 
-function drawLines(svg: SVGSVGElement, spec: ChartSpec, min: number, max: number): void {
+function drawLines(
+  svg: SVGSVGElement,
+  spec: ChartSpec,
+  geo: Geometry,
+  min: number,
+  max: number,
+): void {
   spec.series.forEach((series, s) => {
     const points = series.points
-      .map((value, i) => `${bandCentre(i, spec.labels.length)},${scaleY(value, min, max)}`)
+      .map(
+        (value, i) => `${bandCentre(i, spec.labels.length, geo)},${scaleY(value, min, max, geo)}`,
+      )
       .join(" ");
     svg.appendChild(
       el("polyline", {
@@ -213,13 +328,19 @@ function drawLines(svg: SVGSVGElement, spec: ChartSpec, min: number, max: number
   });
 }
 
-function drawScatter(svg: SVGSVGElement, spec: ChartSpec, min: number, max: number): void {
+function drawScatter(
+  svg: SVGSVGElement,
+  spec: ChartSpec,
+  geo: Geometry,
+  min: number,
+  max: number,
+): void {
   spec.series.forEach((series, s) => {
     series.points.forEach((value, i) => {
       svg.appendChild(
         el("circle", {
-          cx: bandCentre(i, spec.labels.length),
-          cy: scaleY(value, min, max),
+          cx: bandCentre(i, spec.labels.length, geo),
+          cy: scaleY(value, min, max, geo),
           r: 4,
           fill: seriesColor(s),
           "fill-opacity": 0.85,
@@ -231,15 +352,15 @@ function drawScatter(svg: SVGSVGElement, spec: ChartSpec, min: number, max: numb
 
 /**
  * Pie draws the **first** series' points as shares of their own total, one
- * wedge per label — the only kind whose slices are the labels rather than the
+ * wedge per label -- the only kind whose slices are the labels rather than the
  * series, so a second series has nowhere to go and is ignored rather than
  * silently summed into the first.
  */
-function drawPie(svg: SVGSVGElement, points: readonly number[]): void {
+function drawPie(svg: SVGSVGElement, points: readonly number[], geo: Geometry): void {
   const total = points.reduce((sum, value) => sum + value, 0);
-  const cx = WIDTH / 2;
-  const cy = PAD.top + PLOT_H / 2;
-  const r = Math.min(PLOT_W, PLOT_H) / 2;
+  const cx = geo.width / 2;
+  const cy = PAD.top + geo.plotH / 2;
+  const r = Math.min(geo.plotW, geo.plotH) / 2;
   if (total === 0) {
     // Every share is zero, so there is no wedge to draw and a full circle would
     // claim one slice owns everything. An outline says "nothing here" honestly.
@@ -273,6 +394,42 @@ function drawPie(svg: SVGSVGElement, points: readonly number[]): void {
   });
 }
 
+/** The whole drawing for one spec at one width. */
+function drawSvg(spec: ChartSpec, geo: Geometry): SVGSVGElement {
+  const svg = el("svg", {
+    viewBox: `0 0 ${geo.width} ${geo.height}`,
+    width: "100%",
+    role: "img",
+  });
+  svg.setAttribute("aria-label", spec.title ?? `${spec.kind} chart`);
+
+  if (spec.kind === "pie") {
+    // `series[0]` is guaranteed by renderChart's early return; a pie's slices
+    // are its labels, so a second series has nowhere to go and is ignored
+    // rather than silently summed into the first. Negative shares are floored,
+    // since a wedge cannot sweep backwards.
+    const first = spec.series[0] as ChartSeries;
+    drawPie(
+      svg,
+      first.points.map((value) => Math.max(0, value)),
+      geo,
+    );
+    return svg;
+  }
+  const { min, max } = extent(spec);
+  drawAxes(svg, spec, geo, min, max);
+  if (spec.kind === "bar") {
+    drawBars(svg, spec, geo, min, max);
+  } else if (spec.kind === "stacked") {
+    drawStacked(svg, spec, geo, min, max);
+  } else if (spec.kind === "line") {
+    drawLines(svg, spec, geo, min, max);
+  } else {
+    drawScatter(svg, spec, geo, min, max);
+  }
+  return svg;
+}
+
 function buildLegend(entries: readonly string[]): HTMLDivElement | null {
   if (entries.length < 2) {
     return null;
@@ -292,12 +449,34 @@ function buildLegend(entries: readonly string[]): HTMLDivElement | null {
   return row;
 }
 
+/**
+ * Redraw `block`'s chart whenever the width it has to fill changes.
+ *
+ * Nothing disconnects this, and nothing needs to: the observer is referenced
+ * only by the closure that made it, and an active observer holds its target
+ * rather than the other way round -- so a chart removed from the transcript
+ * takes its observer with it.
+ *
+ * The block's own width is read rather than the entry's box, because that is
+ * the number the redraw has to match and the entry carries several.
+ */
+function fitToWidth(block: HTMLElement, redraw: (width: number) => void): void {
+  const observer = new ResizeObserver(() => {
+    redraw(Math.round(block.clientWidth / WIDTH_STEP) * WIDTH_STEP);
+  });
+  observer.observe(block);
+}
+
 /**
  * Render one spec as a self-contained block, or `null` when it says nothing.
  *
  * A spec with no labels or no series is not drawn: an empty frame reads as
  * "there is no data" when the truth is "the caller sent nothing", and the two
  * deserve different answers.
+ *
+ * The block returned is already drawn at {@link DEFAULT_WIDTH} and redraws
+ * itself once it is in a document and knows how wide it really is, so a caller
+ * appends it exactly as before and never has to say how big it should be.
  */
 export function renderChart(spec: ChartSpec): HTMLDivElement | null {
   if (spec.labels.length === 0 || spec.series.length === 0) {
@@ -315,32 +494,8 @@ export function renderChart(spec: ChartSpec): HTMLDivElement | null {
     block.appendChild(heading);
   }
 
-  const svg = el("svg", { viewBox: `0 0 ${WIDTH} ${HEIGHT}`, width: "100%", role: "img" });
-  svg.setAttribute("aria-label", spec.title ?? `${spec.kind} chart`);
-
-  if (spec.kind === "pie") {
-    // `series[0]` is guaranteed by the early return above; a pie's slices are
-    // its labels, so a second series has nowhere to go and is ignored rather
-    // than silently summed into the first. Negative shares are floored, since a
-    // wedge cannot sweep backwards.
-    const first = spec.series[0] as ChartSeries;
-    drawPie(
-      svg,
-      first.points.map((value) => Math.max(0, value)),
-    );
-  } else {
-    const { min, max } = extent(spec);
-    drawAxes(svg, spec, min, max);
-    if (spec.kind === "bar") {
-      drawBars(svg, spec, min, max);
-    } else if (spec.kind === "stacked") {
-      drawStacked(svg, spec, min, max);
-    } else if (spec.kind === "line") {
-      drawLines(svg, spec, min, max);
-    } else {
-      drawScatter(svg, spec, min, max);
-    }
-  }
+  let width = DEFAULT_WIDTH;
+  let svg = drawSvg(spec, geometryFor(width));
   block.appendChild(svg);
 
   // Pie's slices are its labels; every other kind's are its series.
@@ -350,5 +505,15 @@ export function renderChart(spec: ChartSpec): HTMLDivElement | null {
   if (legend !== null) {
     block.appendChild(legend);
   }
+
+  fitToWidth(block, (measured) => {
+    if (measured === width) {
+      return;
+    }
+    width = measured;
+    const next = drawSvg(spec, geometryFor(width));
+    svg.replaceWith(next);
+    svg = next;
+  });
   return block;
 }

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

@@ -0,0 +1,30 @@
+import { EDGE_MARGIN } from "../constants.js";
+import type { ViewportBox } from "./launcher_placement.js";
+import type { PanelRect } from "./resize_handle.js";
+
+/**
+ * Hold a panel inside the viewport, keeping its size.
+ *
+ * The near edge is clamped and the far edge follows, so a panel too large for
+ * the viewport is held against the near margin and left to the max-width and
+ * max-height rules rather than centred by force. The lower bound wins a
+ * contradiction for the same reason: `Math.min` first would put an oversized
+ * panel off the left edge instead of against the margin it can still honour.
+ */
+export function clampPanel(
+  host: PanelRect,
+  viewport: ViewportBox,
+  margin: number = EDGE_MARGIN,
+): PanelRect {
+  const width = host.right - host.left;
+  const height = host.bottom - host.top;
+  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

package/src/ui/launcher_placement.ts

@@ -1,3 +1,7 @@
+import { SCREEN_EDGE_MARGIN } from "../constants.js";
+import { clampPanel } from "./clamp_panel.js";
+import { placeWidget } from "./place_widget.js";
+
 /** A box in viewport coordinates. */
 export interface LauncherBox {
   readonly left: number;
@@ -6,6 +10,20 @@ export interface LauncherBox {
   readonly height: number;
 }
 
+/**
+ * The part of the screen a widget may rest in: a width and height, and the
+ * corner they start from.
+ *
+ * The origin is not always zero. A host can reserve the edges its own chrome
+ * occupies, and a panel clamped against a viewport that starts at the top-left
+ * of the screen will happily park itself underneath a sticky header -- where it
+ * cannot be reached, and where collapsing it only hides it further.
+ */
+export interface ViewportBox extends Extent {
+  readonly left: number;
+  readonly top: number;
+}
+
 /** A width/height pair, in CSS pixels. */
 export interface Extent {
   readonly width: number;
@@ -33,13 +51,6 @@ export interface LauncherPlacement {
   readonly launcherInset: string;
 }
 
-/**
- * The gutter a panel keeps from the viewport edge, matching the default
- * `--ag-ui-inset` so an undragged widget resolves to exactly the placement it
- * already had. Changing this moves every clamped panel.
- */
-const EDGE_MARGIN = 24;
-
 /**
  * Decide where a panel should open from a launcher the user has dragged.
  *
@@ -74,70 +85,49 @@ const EDGE_MARGIN = 24;
 export function launcherPlacement(
   launcher: LauncherBox,
   panel: Extent,
-  viewport: Extent,
-  margin: number = EDGE_MARGIN,
+  viewport: ViewportBox,
+  screen: Extent,
+  margin: number = SCREEN_EDGE_MARGIN,
 ): LauncherPlacement {
   // Room for a panel pinned to each side of the launcher. A tie goes to the
   // first branch, so the result is deterministic for a centred launcher.
-  const roomRunningRight = viewport.width - launcher.left;
-  const roomRunningLeft = launcher.left + launcher.width;
-  const roomRunningDown = viewport.height - launcher.top;
-  const roomRunningUp = launcher.top + launcher.height;
+  //
+  // Measured against the usable box's own edges, not against its width and
+  // height as if it started at the origin. The launcher's coordinates are the
+  // screen's, while the extents have already had the host's reserved edges
+  // taken out of them, so mixing the two understates the room on one side and
+  // overstates it on the other -- by the same reserved inset, in opposite
+  // directions, which is what makes the comparison flip rather than merely
+  // drift. The clamp below reads `viewport.left`/`top`; this had to as well.
+  const roomRunningRight = viewport.left + viewport.width - launcher.left;
+  const roomRunningLeft = launcher.left + launcher.width - viewport.left;
+  const roomRunningDown = viewport.top + viewport.height - launcher.top;
+  const roomRunningUp = launcher.top + launcher.height - viewport.top;
   const corner: ExpandCorner = {
     x: roomRunningRight >= roomRunningLeft ? "left" : "right",
     y: roomRunningDown >= roomRunningUp ? "top" : "bottom",
   };
 
-  // The box the panel wants, then the box it can actually have. Clamping the
-  // near edge covers the far edge too: the panel is a fixed size here, and a
-  // panel too large for the viewport is held against the near margin and left
-  // to the max-width and max-height rules rather than centred by force.
+  // The box the panel wants, then the box it can actually have. The launcher
+  // is not moved by that clamp -- it is the fixed point of this gesture, so its
+  // own inset carries the difference and it can end up outside the host box.
   const wantedLeft =
     corner.x === "left" ? launcher.left : launcher.left + launcher.width - panel.width;
   const wantedTop =
     corner.y === "top" ? launcher.top : launcher.top + launcher.height - panel.height;
-  const hostLeft = clamp(wantedLeft, margin, viewport.width - margin - panel.width);
-  const hostTop = clamp(wantedTop, margin, viewport.height - margin - panel.height);
-
-  const hostRight = hostLeft + panel.width;
-  const hostBottom = hostTop + panel.height;
-
-  return {
-    corner,
-    hostInset: inset({
-      top: corner.y === "top" ? hostTop : null,
-      right: corner.x === "right" ? viewport.width - hostRight : null,
-      bottom: corner.y === "bottom" ? viewport.height - hostBottom : null,
-      left: corner.x === "left" ? hostLeft : null,
-    }),
-    // Measured from the host box's pinned corner to the launcher's matching
-    // corner, so the launcher lands exactly where it was dropped.
-    launcherInset: inset({
-      top: corner.y === "top" ? launcher.top - hostTop : null,
-      right: corner.x === "right" ? hostRight - (launcher.left + launcher.width) : null,
-      bottom: corner.y === "bottom" ? hostBottom - (launcher.top + launcher.height) : null,
-      left: corner.x === "left" ? launcher.left - hostLeft : null,
-    }),
-  };
-}
-
-/**
- * Constrain a value, with the lower bound winning a contradiction. `Math.min`
- * first would put a panel wider than the viewport off the left edge instead of
- * against the near margin.
- */
-function clamp(value: number, low: number, high: number): number {
-  return Math.max(low, Math.min(value, high));
-}
+  const host = clampPanel(
+    {
+      left: wantedLeft,
+      top: wantedTop,
+      right: wantedLeft + panel.width,
+      bottom: wantedTop + panel.height,
+    },
+    viewport,
+    margin,
+  );
 
-/** An `inset` shorthand; a null side is `auto`, so the opposite one pins it. */
-function inset(sides: {
-  top: number | null;
-  right: number | null;
-  bottom: number | null;
-  left: number | null;
-}): string {
-  const side = (value: number | null): string =>
-    value === null ? "auto" : `${Math.round(value)}px`;
-  return `${side(sides.top)} ${side(sides.right)} ${side(sides.bottom)} ${side(sides.left)}`;
+  // The usable box decides where things may rest; the screen is what the
+  // resulting insets are measured from. They are the same only when the host
+  // has reserved nothing.
+  return { corner, ...placeWidget(host, launcher, corner, screen) };
 }