@artooi/ag-ui-web-component 0.48.0 → 0.50.0

package/src/ui/placement/panel_placement.ts

@@ -50,6 +50,25 @@ const DOCK_RIGHT = "--_dock-right";
 /** Per-tab persistence key for a dragged launcher position. */
 const LAUNCHER_KEY = "ag-ui-chat:launcher";
 
+/**
+ * Persistence key for where the user dragged a docked panel. Its own key, not
+ * the launcher's: a spot stored under the corner launcher describes another
+ * surface, and reading it here would open every panel away from the bar for a
+ * host that switched to the bar after its users had dragged their corner
+ * panels.
+ */
+const DOCK_KEY = "ag-ui-chat:dock";
+
+/**
+ * Where the user last put a corner panel's launcher, and the panel itself when
+ * they stated that too. The shape the launcher's record is stored in.
+ */
+interface CornerSpot {
+  readonly left: number;
+  readonly top: number;
+  readonly panel?: { readonly left: number; readonly top: number };
+}
+
 /** A stored `{ left, top }` pair, or null for anything that is not one. */
 function asPoint(value: unknown): { readonly left: number; readonly top: number } | null {
   if (typeof value !== "object" || value === null) {
@@ -70,6 +89,34 @@ function coversViewport(box: Extent, viewport: Extent): boolean {
   return box.width >= viewport.width - 1 && box.height >= viewport.height - 1;
 }
 
+/**
+ * Whether a box that covers the usable viewport stands off any edge of it.
+ *
+ * The far edges are read against the layout viewport rather than the usable box,
+ * because a keyboard shortens the second and pans the panel down inside the
+ * first: a phone's full-bleed panel is correctly past the usable box's foot then,
+ * and pinning it back would put its header above the screen.
+ */
+function hangsOff(box: PanelRect, viewport: ViewportBox, screen: Extent): boolean {
+  const slack = 0.5;
+  return (
+    box.left < viewport.left - slack ||
+    box.top < viewport.top - slack ||
+    box.right > screen.width + slack ||
+    box.bottom > screen.height + slack
+  );
+}
+
+/** A box of the same size as `box`, standing at the start of the usable viewport. */
+function atStartOf(viewport: ViewportBox, box: PanelRect): PanelRect {
+  return {
+    left: viewport.left,
+    top: viewport.top,
+    right: viewport.left + (box.right - box.left),
+    bottom: viewport.top + (box.bottom - box.top),
+  };
+}
+
 /**
  * The `--ag-ui-inset` value that pins `box` by `corner`.
  *
@@ -156,8 +203,9 @@ export class PanelPlacement {
    * header on screen, and the launcher is the handle then.
    */
   enablePanelDrag(header: HTMLElement): void {
+    this.#header = header;
     enablePanelDrag(header, {
-      enabled: () => !this.#host.collapsed() && this.#launcherDraggable(),
+      enabled: () => !this.#host.collapsed() && this.#canDragPanel(),
       rect: () => this.#host.element.getBoundingClientRect(),
       apply: (box, from) => this.#movePanel(box, from),
       commit: (box, from) => this.#commitPanel(box, from),
@@ -182,12 +230,22 @@ export class PanelPlacement {
 
   /** Build the eight resize grips into `chat`, with one of them in the tab order. */
   mountResizeGrips(chat: HTMLElement): void {
+    // The grips a key gesture was on are gone, and a key that comes up on nothing
+    // ends nothing, so an element taken out mid-gesture would otherwise come back
+    // deaf to every window resize.
+    this.#resizing = false;
     for (const grip of RESIZE_GRIPS) {
       const handle = createResizeHandle(grip, {
         axis: () => this.#resizeAxis(),
         rect: () => this.#host.element.getBoundingClientRect(),
-        apply: (box) => this.#applyResize(grip, box),
-        commit: (box) => this.#commitResize(grip, box),
+        apply: (box) => {
+          this.#resizing = true;
+          this.#applyResize(grip, box);
+        },
+        commit: (box) => {
+          this.#resizing = false;
+          this.#commitResize(grip, box);
+        },
         label: this.#host.strings().resizePanel,
       });
       // Only one of the eight is in the tab order. Eight separators between the
@@ -213,16 +271,72 @@ export class PanelPlacement {
    * Drop the dragged size and its stored copy, so the placement's own size and
    * the host's tokens apply again. For a host entering a sized state of its
    * own, which a user's drag would otherwise outrank.
+   *
+   * A docked panel the user dragged off its dock goes back to it as well, and
+   * the stored spot with it: there the position is part of the same resting
+   * state the host is asking for. A corner panel keeps a dragged position, as
+   * it always has.
    */
   resetSize(): void {
+    const sized = this.#host.element.getBoundingClientRect();
     this.#host.element.style.removeProperty(DRAG_WIDTH);
     this.#host.element.style.removeProperty(DRAG_HEIGHT);
     this.#host.clearPreference(SIZE_KEY);
+    if (this.#docked()) {
+      if (this.#dockPos !== null) {
+        this.#host.element.style.removeProperty("--ag-ui-inset");
+      }
+      this.#dockPos = null;
+      this.#storeDockPosition(null);
+    } else {
+      this.#carrySpotWithSize(sized);
+    }
     // The anchor was measured against the dragged box; the resting one may
     // pin different edges.
     this.syncResizeAnchor();
   }
 
+  /**
+   * Carry a stated corner spot along with a dragged size coming off.
+   *
+   * The size comes off toward the corner the layout holds still, so the top-left
+   * the spot is kept as moves with it, and a restore from the old one would swing
+   * the panel away from its launcher. Only that movement goes onto the spot, not
+   * where the box stands: in a window narrower than the spot the box is held
+   * short of it, and that is not something the user stated.
+   *
+   * Left alone while a host's own size is in force, because that cannot be told
+   * from the dragged size coming off, and it may be a state the host is about to
+   * leave: counting it would throw the spot off by as much as that state is
+   * bigger. A panel that is the screen needs no case of its own: the small-viewport
+   * block ignores a dragged size, so its box does not move.
+   *
+   * Left alone too under data-launcher-drag="false", where a spot left over from
+   * before the attribute is a record kept for the day it comes off, and nothing
+   * that happens to the box now is a statement about it.
+   */
+  #carrySpotWithSize(sized: DOMRect): void {
+    const element = this.#host.element;
+    const box = element.getBoundingClientRect();
+    const spot = this.#cornerSpot ?? this.#readLauncherPosition();
+    const style = getComputedStyle(element);
+    if (
+      spot?.panel === undefined ||
+      !this.#launcherDraggable() ||
+      style.getPropertyValue("--ag-ui-width") !== "" ||
+      style.getPropertyValue("--ag-ui-height") !== ""
+    ) {
+      return;
+    }
+    this.#writeCornerSpot({
+      ...spot,
+      panel: {
+        left: spot.panel.left + box.left - sized.left,
+        top: spot.panel.top + box.top - sized.top,
+      },
+    });
+  }
+
   /**
    * A zero-sized box carrying the host's viewport insets as padding, so they
    * can be read back as used pixel lengths. See the `.viewport-probe` rule for
@@ -250,6 +364,54 @@ export class PanelPlacement {
    */
   #panelPos: { readonly left: number; readonly top: number } | null = null;
 
+  /**
+   * The spot #launcherPos and #panelPos were last stated as, or null while
+   * nothing has been stated since this element connected.
+   *
+   * Those two say where the launcher and the panel stand now, held inside the
+   * viewport, because that is where a press finds them and a drag starts from.
+   * This is what the user asked for, kept apart so that a window narrower than
+   * the spot, or a phone that took the panel full-bleed, gives it back unchanged
+   * once there is room again. Only a gesture, a move or a dragged size coming off
+   * changes it; re-applying it against a viewport never does, which is the difference from a clamped
+   * position quietly becoming the record one resize at a time.
+   */
+  #cornerSpot: CornerSpot | null = null;
+
+  /**
+   * The inset a grip wrote on a corner panel with no spot, or null. A grip on an
+   * edge the layout holds moves the panel without stating a spot, so this is the
+   * only way to tell its inline inset from one a host wrote there, which stays,
+   * and to give it back once a phone has taken the panel full-bleed.
+   */
+  #gripInset: string | null = null;
+
+  /**
+   * The inset standing a panel with no spot at the start of a window a host's
+   * size fills, or null. Told apart from a host's own for the same reason, and it
+   * lasts only as long as that size does.
+   */
+  #fillInset: string | null = null;
+
+  /**
+   * Where the user dragged a docked panel, in viewport coordinates, or null
+   * while it stands on the bar or the anchor.
+   *
+   * Apart from the two corner positions above because it moves nothing else:
+   * a docked panel has no launcher to carry, and the corner it opens from is
+   * the dock's. Held as the user stated it and never as clamped, so a bar that
+   * grew, or a phone that took the panel full-bleed, gives the spot back
+   * unchanged once there is room for it again.
+   */
+  #dockPos: { readonly left: number; readonly top: number } | null = null;
+
+  /**
+   * The line a docked panel stays above, in viewport coordinates: the bar's
+   * top, or the anchor's. Infinite where neither is drawn. Measured by
+   * syncDock, which runs on every change either can make.
+   */
+  #dockTop = Number.POSITIVE_INFINITY;
+
   /**
    * The corner the panel opens away from, once this element is placing itself.
    * Null means the host's layout still decides, and the anchor is measured.
@@ -263,6 +425,12 @@ export class PanelPlacement {
    */
   #anchor: ResizeAnchor = { x: "right", y: "bottom" };
 
+  /** The header the panel drag listens on, stamped by #stampHeader. */
+  #header: HTMLElement | null = null;
+
+  /** Whether a grip has applied a box it has not committed yet. */
+  #resizing = false;
+
   /** The eight grips, by name, so the keyboard-reachable one can be moved. */
   readonly #resizeHandles = new Map<string, HTMLDivElement>();
 
@@ -281,7 +449,10 @@ export class PanelPlacement {
    * rather than collapsed to nothing.
    */
   #withinViewport(box: PanelRect): PanelRect {
-    const viewport = this.#viewport();
+    // A docked panel that moves has its room stop at the dock, so no grip
+    // pulls it over the bar it minimises to. A placement that owns its
+    // position keeps the bound it always had.
+    const viewport = this.#docked() && this.#panelMovable() ? this.#dockRoom() : this.#viewport();
     // The same bound a drag stops at, so a grip pulled to the edge and a panel
     // dragged to it come to rest on the same line. The inner Math.max/min pair
     // keeps an already-inverted box from turning inside out.
@@ -302,12 +473,16 @@ export class PanelPlacement {
    *
    * Read from the stamp the drag helpers already set, rather than tracked
    * separately: one source of truth, and it clears on `pointercancel` as well
-   * as `pointerup`, which is the end a touch gesture usually gets.
+   * as `pointerup`, which is the end a touch gesture usually gets. The one
+   * gesture that stamps nothing is an arrow key on a grip, which applies a box
+   * per key and states it only when the key comes up, hence #resizing.
    */
   dragging(): boolean {
     return (
+      this.#resizing ||
       this.#host.launcher.hasAttribute("data-dragging") ||
-      this.#host.root.querySelector(".header[data-dragging]") !== null
+      this.#host.root.querySelector(".header[data-dragging], .resize-handle[data-dragging]") !==
+        null
     );
   }
 
@@ -321,8 +496,13 @@ export class PanelPlacement {
       collapseTo: this.#surface().collapseTo,
       collapsed: this.#host.collapsed(),
       collapsible: this.#host.collapsible(),
-      movable: this.#launcherDraggable() && !fullBleed,
-      draggable: this.#launcherDraggable(),
+      movable: this.#panelMovable() && !fullBleed,
+      // The page's setting alone: true for every placement unless the host set
+      // `data-launcher-drag="false"`. Whether this panel moves is `movable`,
+      // and reading the launcher or the dock in here made the field change
+      // with `collapse-to`, so a docked sidebar reported that the page had
+      // turned moving off when the placement owned its position.
+      draggable: this.#host.element.getAttribute("data-launcher-drag") !== "false",
       fullBleed,
       box: {
         left: Math.round(box.left),
@@ -341,7 +521,7 @@ export class PanelPlacement {
 
   /** The move behind `AgUiChat.moveTo`, whose doc is the contract. */
   moveTo(corner: ChatCorner, options: { readonly announce?: boolean } = {}): boolean {
-    if (!this.#launcherDraggable()) {
+    if (!this.#panelMovable()) {
       return false;
     }
     const restore = options.announce === true ? this.#captureGeometry() : null;
@@ -351,23 +531,31 @@ export class PanelPlacement {
       return false;
     }
     const [edgeY, edgeX] = corner.split("-");
+    // A docked panel's bottom corners are above its dock, not on the bar.
+    const docked = this.#docked();
+    const room = docked ? this.#dockRoom() : viewport;
     // Every term is an absolute screen coordinate, because that is what the
     // clamps and the insets both speak. The usable box carries an origin, so
     // its near edge is `viewport.left`, not zero, and its far edge is
     // `viewport.left + viewport.width` -- a margin applied to the extents
     // alone would send the agent's own move under the chrome the host
     // reserved, which is the failure the usable box exists to prevent.
-    const nearX = viewport.left + EDGE_MARGIN;
-    const nearY = viewport.top + EDGE_MARGIN;
+    const nearX = room.left + EDGE_MARGIN;
+    const nearY = room.top + EDGE_MARGIN;
     const left =
-      edgeX === "left"
-        ? nearX
-        : Math.max(nearX, viewport.left + viewport.width - EDGE_MARGIN - box.width);
+      edgeX === "left" ? nearX : Math.max(nearX, room.left + room.width - EDGE_MARGIN - box.width);
     const top =
-      edgeY === "top"
-        ? nearY
-        : Math.max(nearY, viewport.top + viewport.height - EDGE_MARGIN - box.height);
+      edgeY === "top" ? nearY : Math.max(nearY, room.top + room.height - EDGE_MARGIN - box.height);
     const host = { left, top, right: left + box.width, bottom: top + box.height };
+    if (docked) {
+      this.#dockPos = { left, top };
+      this.#writeDockInset(host);
+      this.#storeDockPosition(this.#dockPos);
+      if (restore !== null) {
+        this.#host.announceSurfaceChange(this.#host.strings().chatMoved, restore);
+      }
+      return true;
+    }
     // Both axes measured, rather than one read twice: a host can restyle the
     // launcher as a pill, and squaring it here would put it off the corner.
     const launcherWidth = this.#host.launcher.offsetWidth;
@@ -394,6 +582,13 @@ export class PanelPlacement {
    * puts the box back and animates it out of the wrong side. Absent values are
    * captured as absent and removed on the way back, rather than written as
    * empty strings that would outrank the placement.
+   *
+   * The surface may have changed by the time of the undo, so the two halves are
+   * put back apart. Both records are, always, each to its own store, so the
+   * memory and the storage cannot disagree and the surface they belong to finds
+   * them when it comes back. The inline values only mean something to the surface
+   * they were read from: written on any other, they pin a sidebar to where a
+   * floating panel used to be.
    */
   #captureGeometry(): () => void {
     const inset = this.#host.element.style.getPropertyValue("--ag-ui-inset");
@@ -401,32 +596,52 @@ export class PanelPlacement {
     const corner = this.#host.element.getAttribute("data-expand-corner");
     const launcherPos = this.#launcherPos;
     const panelPos = this.#panelPos;
+    const dockPos = this.#dockPos ?? this.#readDockPosition();
     const expandCorner = this.#expandCorner;
+    const cornerSpot = this.#cornerSpot ?? this.#readLauncherPosition();
+    const owner = this.#positionOwner();
     return () => {
-      this.#restoreProperty("--ag-ui-inset", inset);
-      this.#restoreProperty("--ag-ui-launcher-inset", launcherInset);
-      if (corner === null) {
-        this.#host.element.removeAttribute("data-expand-corner");
+      this.#dockPos = dockPos;
+      this.#storeDockPosition(dockPos);
+      // Erased rather than rewritten when there was nothing to go back to,
+      // which would leave the move this is undoing sitting in storage -- and
+      // since that store outlives the tab, the next resize or reload would
+      // quietly put the panel back in the corner the user had just rejected.
+      if (cornerSpot === null) {
+        this.#cornerSpot = null;
+        this.#host.clearPreference(LAUNCHER_KEY);
       } else {
-        this.#host.element.setAttribute("data-expand-corner", corner);
+        this.#writeCornerSpot(cornerSpot);
       }
-      this.#launcherPos = launcherPos;
-      this.#panelPos = panelPos;
-      this.#expandCorner = expandCorner;
-      // Erased rather than rewritten when there was nothing to go back to.
-      // #storeLauncherPosition returns early for a null position, which would
-      // leave the move this is undoing sitting in storage -- and since that
-      // store outlives the tab, the next resize or reload would quietly put
-      // the panel back in the corner the user had just rejected.
-      if (launcherPos === null) {
-        this.#host.clearPreference(LAUNCHER_KEY);
+      if (owner === this.#positionOwner()) {
+        this.#restoreProperty("--ag-ui-inset", inset);
+        this.#restoreProperty("--ag-ui-launcher-inset", launcherInset);
+        if (corner === null) {
+          this.#host.element.removeAttribute("data-expand-corner");
+        } else {
+          this.#host.element.setAttribute("data-expand-corner", corner);
+        }
+        this.#launcherPos = launcherPos;
+        this.#panelPos = panelPos;
+        this.#expandCorner = expandCorner;
       } else {
-        this.#storeLauncherPosition();
+        this.#forgetCornerPosition();
       }
+      // Against the viewport there is now, which may be a phone's: the insets
+      // put back above were written for the one the move was made in.
+      this.restoreLauncherPosition();
       this.syncResizeAnchor();
     };
   }
 
+  /** Which of the three kinds of surface decides where the panel stands. */
+  #positionOwner(): "dock" | "corner" | "placement" {
+    if (this.#docked()) {
+      return "dock";
+    }
+    return this.#surface().launcherDraggable ? "corner" : "placement";
+  }
+
   /**
    * Which axes the current placement allows.
    *
@@ -518,6 +733,19 @@ export class PanelPlacement {
     this.#anchor = anchor;
     this.#host.element.setAttribute("data-resize-anchor", `${anchor.y}-${anchor.x}`);
     this.#focusableGrip();
+    this.#stampHeader();
+  }
+
+  /**
+   * Tell the stylesheet whether the panel is the screen, for the header's cursor.
+   *
+   * Only this half of what refuses a header drag: the resting rules already answer
+   * for the placement and for data-launcher-drag="false", and neither of those
+   * re-applies anything when it changes, so a stamp taking them in would go on
+   * refusing, in the cursor, a drag the header would take.
+   */
+  #stampHeader(): void {
+    this.#header?.toggleAttribute("data-fills-screen", this.#fillsScreen());
   }
 
   /** Put a custom property back to a previous value, or remove it if there was none. */
@@ -583,7 +811,10 @@ export class PanelPlacement {
     return surfaceFor(element.getAttribute("placement"), element.getAttribute("collapse-to"));
   }
 
-  /** Whether the panel rises from the bottom bar or the host's anchor. */
+  /**
+   * Whether the panel rises from the bottom bar or the host's anchor, until the
+   * user drags it somewhere else.
+   */
   #docked(): boolean {
     const target = this.#surface().collapseTo;
     return target === "bar" || target === "none";
@@ -617,9 +848,121 @@ export class PanelPlacement {
       element.style.removeProperty(DOCK_RIGHT);
     }
     element.toggleAttribute("data-dock-anchored", target === "none" && anchor !== null);
+    this.#dockTop =
+      target === "bar" && height > 0
+        ? bar.getBoundingClientRect().top
+        : target === "none" && anchor !== null
+          ? anchor.getBoundingClientRect().top
+          : Number.POSITIVE_INFINITY;
+    // Every change the dock can make passes through here -- the bar's height
+    // arrives by a ResizeObserver after the first restore, and a bar that grew
+    // since the drag would otherwise cover the panel's foot -- so the dragged
+    // spot is held against it here rather than only when it is restored.
+    this.#placeDocked();
     return height;
   }
 
+  /**
+   * The part of the usable viewport a docked panel may stand in: all of it
+   * above the dock's line. The bar is what it minimises to, and the anchor is
+   * the host's own way back, so a dragged panel never covers either.
+   */
+  #dockRoom(): ViewportBox {
+    const viewport = this.#viewport();
+    const bottom = Math.min(viewport.top + viewport.height, this.#dockTop);
+    return { ...viewport, height: Math.max(0, bottom - viewport.top) };
+  }
+
+  /**
+   * Put a docked panel back where the user dragged it, held inside its room.
+   *
+   * The inline inset comes off first, which is both how the panel's resting
+   * box is measured and what leaves a phone full-bleed: the small-viewport
+   * block reads the host's inset before its own, so a dragged spot written
+   * there would hold the panel off the screen's edges. The spot itself stays,
+   * for the next time there is room for it.
+   */
+  #placeDocked(): void {
+    if (!this.#docked() || !this.#panelMovable() || this.dragging()) {
+      return;
+    }
+    const at = this.#dockPos ?? this.#readDockPosition();
+    if (at === null) {
+      return;
+    }
+    this.#dockPos = at;
+    this.#host.element.style.removeProperty("--ag-ui-inset");
+    const rest = this.#host.element.getBoundingClientRect();
+    if (coversViewport(rest, this.#viewport())) {
+      return;
+    }
+    // Measured at the dock, so the inset below is written from the corner the
+    // dock holds still and a resize grows the panel away from it.
+    this.syncResizeAnchor();
+    this.#writeDockInset(
+      clampPanel(
+        { left: at.left, top: at.top, right: at.left + rest.width, bottom: at.top + rest.height },
+        this.#dockRoom(),
+        SCREEN_EDGE_MARGIN,
+      ),
+    );
+  }
+
+  /** Write the inset that stands a docked panel at `box`. */
+  #writeDockInset(box: PanelRect): void {
+    this.#host.element.style.setProperty(
+      "--ag-ui-inset",
+      insetFrom(this.#anchor, box, this.#screen()),
+    );
+  }
+
+  /** Remember a docked panel's dragged spot, or forget it for null. */
+  #storeDockPosition(at: { readonly left: number; readonly top: number } | null): void {
+    if (at === null) {
+      this.#host.clearPreference(DOCK_KEY);
+      return;
+    }
+    this.#host.writePreference(DOCK_KEY, JSON.stringify({ left: at.left, top: at.top }));
+  }
+
+  /** The stored spot of a docked panel, or null for none or anything corrupt. */
+  #readDockPosition(): { readonly left: number; readonly top: number } | null {
+    const raw = this.#host.readPreference(DOCK_KEY);
+    if (raw === null) {
+      return null;
+    }
+    try {
+      return asPoint(JSON.parse(raw));
+    } catch {
+      return null;
+    }
+  }
+
+  /**
+   * Whether the header drag and moveTo may move the open panel: the
+   * placement's answer, unless the host turned moving off.
+   */
+  #panelMovable(): boolean {
+    return (
+      this.#host.element.getAttribute("data-launcher-drag") !== "false" &&
+      this.#surface().panelMovable
+    );
+  }
+
+  /**
+   * Whether a header drag may start now. A panel that is the screen, on a phone
+   * or by a host's own sizing, has nowhere to go, and a drag there would pull it
+   * off the edges it fills.
+   */
+  #canDragPanel(): boolean {
+    return this.#panelMovable() && !this.#fillsScreen();
+  }
+
+  /** Whether the panel covers the usable viewport, as it stands now. */
+  #fillsScreen(): boolean {
+    return coversViewport(this.#host.element.getBoundingClientRect(), this.#viewport());
+  }
+
   /**
    * Whether this placement lets the launcher be dragged, read per interaction
    * because `placement` is a live attribute. `data-launcher-drag="false"` opts
@@ -806,12 +1149,6 @@ export class PanelPlacement {
    * back rather than leaving a stale inline one behind.
    */
   #applyLauncherPlacement(at: { readonly left: number; readonly top: number }): void {
-    // The single gate: callers hand over a position and this decides whether
-    // it is this element's to honour. Checking in both places instead would
-    // leave one of the two checks permanently unreachable.
-    if (!this.#launcherDraggable()) {
-      return;
-    }
     this.#launcherPos = at;
     // Dropping the bubble hands the panel's position back to the placement.
     // Keeping a stated one would pin the panel where it was dragged and leave
@@ -839,6 +1176,9 @@ export class PanelPlacement {
 
   /** Move the launcher live during a drag, without persisting. */
   #moveLauncher(left: number, top: number): void {
+    // Stated from the first move, not the last: a key gesture only ends at its
+    // keyup, and an Enter pressed before then expands by way of a restore.
+    this.#cornerSpot = { left, top };
     this.#applyLauncherPlacement({ left, top });
   }
 
@@ -863,6 +1203,13 @@ export class PanelPlacement {
    * other still names the old one would move the launcher for no reason.
    */
   #movePanel(box: PanelRect, from: PanelRect): { held: PanelRect; launcher: LauncherBox | null } {
+    if (this.#docked()) {
+      // Inside the room above the dock, with nothing carried along.
+      const held = clampPanel(box, this.#dockRoom(), SCREEN_EDGE_MARGIN);
+      this.#dockPos = { left: held.left, top: held.top };
+      this.#writeDockInset(held);
+      return { held, launcher: null };
+    }
     if (!this.#launcherDraggable()) {
       return { held: box, launcher: null };
     }
@@ -936,6 +1283,10 @@ export class PanelPlacement {
     // again. Recomputing it is how the two came apart: releasing the drag
     // moved the bubble by the panel's whole travel a second time.
     const { held, launcher } = this.#movePanel(box, from);
+    if (this.#docked()) {
+      this.#storeDockPosition({ left: held.left, top: held.top });
+      return;
+    }
     if (launcher === null) {
       return;
     }
@@ -973,9 +1324,6 @@ export class PanelPlacement {
    * its own right.
    */
   #restorePanelPosition(at: { readonly left: number; readonly top: number }): void {
-    if (!this.#launcherDraggable()) {
-      return;
-    }
     const rect = this.#host.element.getBoundingClientRect();
     // The same bound the drag itself used. Taking the default here instead is
     // what made a panel dragged to an edge jump a whole resting gutter inward
@@ -1006,6 +1354,9 @@ export class PanelPlacement {
    * with it, the panel goes back where it was put; without it, the panel is
    * re-derived from the launcher and opens into whatever room the viewport has
    * now.
+   *
+   * Every caller is a gesture ending or a move being made, so where the two
+   * stand now is what was stated. A restore never calls this.
    */
   #storeLauncherPosition(): void {
     const position = this.#launcherPos;
@@ -1013,10 +1364,13 @@ export class PanelPlacement {
       return;
     }
     const panel = this.#panelPos;
-    this.#host.writePreference(
-      LAUNCHER_KEY,
-      JSON.stringify(panel === null ? position : { ...position, panel }),
-    );
+    this.#writeCornerSpot(panel === null ? position : { ...position, panel });
+  }
+
+  /** Make `spot` the stated one, and remember it. */
+  #writeCornerSpot(spot: CornerSpot): void {
+    this.#cornerSpot = spot;
+    this.#host.writePreference(LAUNCHER_KEY, JSON.stringify(spot));
   }
 
   /**
@@ -1024,34 +1378,149 @@ export class PanelPlacement {
    * whenever the window resizes, and before an expand. The viewport that
    * stored a position may since have shrunk, and a launcher past the edge is
    * unreachable -- it is the only way back to a collapsed conversation.
+   *
+   * The one gate on whether a stored position is this element's to honour: the
+   * gestures check their own before they ever reach the placing below.
    */
   restoreLauncherPosition(): void {
-    const stored = this.#readLauncherPosition();
-    const launcher = this.#launcherPos ?? stored;
-    if (launcher === null) {
+    this.#placeFromRecord(true);
+    this.#stampHeader();
+  }
+
+  /**
+   * Re-apply it for a change in the panel's own layout, which needs no window or
+   * reopen to happen: a line typed in the composer is one. A position waiting to
+   * be handed back under data-launcher-drag="false" waits on, because a panel that leaves for the
+   * host's corner as the reader starts typing is a jump with no cause they can see.
+   */
+  settleLauncherPosition(): void {
+    this.#placeFromRecord(false);
+    this.#stampHeader();
+  }
+
+  /** The placing behind {@link restoreLauncherPosition}. */
+  #placeFromRecord(handBack: boolean): void {
+    // Before the launcher's record is read at all: it belongs to the corner
+    // surface, and seeding anything from it would put a spot dragged there on
+    // a panel that should stand on its dock.
+    if (this.#docked()) {
+      this.#placeDocked();
+      return;
+    }
+    if (!this.#surface().launcherDraggable) {
+      return;
+    }
+    // Under data-launcher-drag="false" the widget is wherever the host's CSS puts
+    // it, so a position this element took before the attribute went on is handed
+    // back here, at the first window resize or reopen, and the record stays for the
+    // day the attribute comes off. Nothing watches the attribute: it is read per
+    // interaction, like every other answer here.
+    const draggable = this.#launcherDraggable();
+    if (!draggable && this.#launcherPos !== null) {
+      if (!handBack) {
+        return;
+      }
+      this.releaseLauncherPosition();
+    }
+    const spot = draggable ? (this.#cornerSpot ?? this.#readLauncherPosition()) : null;
+    if (spot === null) {
+      this.#placeUnstated();
+      return;
+    }
+    if (this.#standFullBleed(spot)) {
       return;
     }
-    const panel = this.#panelPos ?? stored?.panel ?? null;
-    if (panel !== null) {
+    if (spot.panel !== undefined) {
       // Stated rather than derived: the launcher is only read here to keep the
       // offset the two were left with, so it has to be seeded before the panel
       // is placed around it.
-      this.#launcherPos = { left: launcher.left, top: launcher.top };
-      this.#restorePanelPosition(panel);
+      this.#launcherPos = { left: spot.left, top: spot.top };
+      this.#restorePanelPosition(spot.panel);
       return;
     }
     const box = this.#launcherBox();
     this.#applyLauncherPlacement(
-      clampLauncher({ ...box, left: launcher.left, top: launcher.top }, this.#viewport()),
+      clampLauncher({ ...box, left: spot.left, top: spot.top }, this.#viewport()),
     );
   }
 
+  /**
+   * Leave a corner panel full-bleed if it has become the screen, and say whether
+   * it has.
+   *
+   * The inline inset comes off, because the small-viewport block reads the
+   * host's inset before its own: a spot written there holds the panel off the
+   * edges it should fill, and past them by the same amount, since its size is
+   * the screen's. What the panel covers is read before that, from the size
+   * alone, which no inset changes.
+   *
+   * The launcher stays a place of its own. It is positioned from the host box,
+   * so it is measured again from the box that has just moved, and it is held on
+   * the screen, because it is the way back from a collapsed conversation. The
+   * spot itself is untouched, for the next time there is room for it.
+   *
+   * Above the breakpoint nothing in the stylesheet takes the panel to the edges.
+   * A host's own size makes it the screen while the resting inset still spends a
+   * gutter on one corner, which hangs the box off the opposite one, so there it
+   * stands at the start of the room the host left free and keeps that inset. A
+   * box the placement already holds on the screen has no inset to keep, which is
+   * every phone, and a host's rule that placed the box itself.
+   */
+  #standFullBleed(spot: CornerSpot): boolean {
+    const element = this.#host.element;
+    const viewport = this.#viewport();
+    if (!coversViewport(element.getBoundingClientRect(), viewport)) {
+      return false;
+    }
+    element.style.removeProperty("--ag-ui-inset");
+    const rest = element.getBoundingClientRect();
+    const hanging = hangsOff(rest, viewport, this.#screen());
+    const box = hanging ? atStartOf(viewport, rest) : rest;
+    const launcher = { ...this.#launcherBox(), left: spot.left, top: spot.top };
+    this.#placePanelAndLauncher(box, { ...launcher, ...clampLauncher(launcher, viewport) });
+    if (!hanging) {
+      element.style.removeProperty("--ag-ui-inset");
+    }
+    return true;
+  }
+
+  /**
+   * Place a corner panel that has no spot, the half of {@link #standFullBleed}
+   * with nothing stated to keep and no launcher of its own to measure.
+   *
+   * Only an inset this element wrote comes off or goes back. One the host wrote
+   * inline is a token a host may state on a phone as anywhere else, and with no
+   * spot it never came from here.
+   */
+  #placeUnstated(): void {
+    const element = this.#host.element;
+    const inline = element.style.getPropertyValue("--ag-ui-inset");
+    const viewport = this.#viewport();
+    if (!coversViewport(element.getBoundingClientRect(), viewport)) {
+      if (inline === "" || inline === this.#fillInset) {
+        this.#restoreProperty("--ag-ui-inset", this.#gripInset ?? "");
+        this.syncResizeAnchor();
+      }
+      this.#fillInset = null;
+      return;
+    }
+    if (inline === this.#gripInset || inline === this.#fillInset) {
+      element.style.removeProperty("--ag-ui-inset");
+    }
+    const rest = element.getBoundingClientRect();
+    const screen = this.#screen();
+    if (
+      element.style.getPropertyValue("--ag-ui-inset") === "" &&
+      hangsOff(rest, viewport, screen)
+    ) {
+      this.#fillInset = insetFrom({ x: "left", y: "top" }, atStartOf(viewport, rest), screen);
+      element.style.setProperty("--ag-ui-inset", this.#fillInset);
+      this.syncResizeAnchor();
+    }
+  }
+
   /** The persisted position for this instance, or null. */
-  #readLauncherPosition(): {
-    readonly left: number;
-    readonly top: number;
-    readonly panel?: { readonly left: number; readonly top: number };
-  } | null {
+  #readLauncherPosition(): CornerSpot | null {
     const raw = this.#host.readPreference(LAUNCHER_KEY);
     if (raw === null) {
       return null;
@@ -1083,12 +1552,26 @@ export class PanelPlacement {
    * the switch inline and pins a sidebar to wherever the floating launcher was.
    */
   releaseLauncherPosition(): void {
+    // A dragged dock spot belongs to a docked panel that moves. Any other
+    // surface hands it back; a docked one keeps it, and syncDock holds it
+    // against the new dock.
+    if (this.#dockPos !== null && !(this.#docked() && this.#panelMovable())) {
+      this.#dockPos = null;
+      this.#host.element.style.removeProperty("--ag-ui-inset");
+    }
     if (this.#launcherDraggable()) {
       return;
     }
+    this.#forgetCornerPosition();
+  }
+
+  /** Take everything off that placed a corner panel, leaving its record alone. */
+  #forgetCornerPosition(): void {
     this.#launcherPos = null;
     this.#panelPos = null;
     this.#expandCorner = null;
+    this.#gripInset = null;
+    this.#fillInset = null;
     this.#host.element.style.removeProperty("--ag-ui-inset");
     this.#host.element.style.removeProperty("--ag-ui-launcher-inset");
     this.#host.element.removeAttribute("data-expand-corner");
@@ -1110,11 +1593,12 @@ export class PanelPlacement {
    */
   #applyResize(grip: ResizeGrip, box: PanelRect): PanelRect {
     box = this.#withinViewport(box);
-    if (this.#docked()) {
-      // A docked panel keeps its resize but never its position: the edges it
+    if (this.#docked() && this.#dockPos === null) {
+      // A panel standing on its dock keeps it through a resize: the edges it
       // stands on are the bar's or the anchor's, and a grip on one of them
       // would write the position below and take the panel off its dock. So
       // the pinned edges stay where they are and only the free ones follow.
+      // Once dragged off, it resizes like a corner panel, below.
       const now = this.#host.element.getBoundingClientRect();
       box = {
         left: grip.x === this.#anchor.x ? now.left : box.left,
@@ -1126,28 +1610,38 @@ export class PanelPlacement {
       return box;
     }
     this.#applySize({ width: box.right - box.left, height: box.bottom - box.top });
-    if (grip.x !== this.#anchor.x && grip.y !== this.#anchor.y) {
-      return box;
+    if (this.#docked()) {
+      // Any grip moves the top-left corner the spot is kept as, including one
+      // on a free edge, which leaves the inset alone.
+      this.#dockPos = { left: box.left, top: box.top };
     }
-    // The whole screen, not the usable box: a CSS inset on a fixed element is
-    // measured from the real edges, so expressing a right or bottom against a
-    // box the host has inset comes out short by exactly that inset.
-    const anchor = this.#anchor;
-    this.#host.element.style.setProperty("--ag-ui-inset", insetFrom(anchor, box, this.#screen()));
-    // The launcher lives at this corner of the panel, so a corner that moved
-    // takes it along. Without this the next expand would re-derive the panel's
-    // position from a launcher still standing where the panel used to be, and
-    // undo the move.
-    if (this.#launcherPos !== null) {
-      const size = this.#host.launcher.offsetWidth;
-      this.#launcherPos = {
-        left: anchor.x === "left" ? box.left : box.right - size,
-        top: anchor.y === "top" ? box.top : box.bottom - size,
-      };
+    if (grip.x === this.#anchor.x || grip.y === this.#anchor.y) {
+      // The whole screen, not the usable box: a CSS inset on a fixed element is
+      // measured from the real edges, so expressing a right or bottom against a
+      // box the host has inset comes out short by exactly that inset.
+      const anchor = this.#anchor;
+      const inset = insetFrom(anchor, box, this.#screen());
+      this.#host.element.style.setProperty("--ag-ui-inset", inset);
+      this.#gripInset = this.#launcherPos === null && !this.#docked() ? inset : null;
+      // The launcher lives at this corner of the panel, so a corner that moved
+      // takes it along. Without this the next expand would re-derive the panel's
+      // position from a launcher still standing where the panel used to be, and
+      // undo the move.
+      if (this.#launcherPos !== null) {
+        const size = this.#host.launcher.offsetWidth;
+        this.#launcherPos = {
+          left: anchor.x === "left" ? box.left : box.right - size,
+          top: anchor.y === "top" ? box.top : box.bottom - size,
+        };
+      }
     }
-    // A stated panel position is a claim about this box, so it moves with it.
-    if (this.#panelPos !== null) {
-      this.#panelPos = { left: box.left, top: box.top };
+    // A stated corner panel's spot is a claim about this box, so it moves with
+    // it, by a free edge as well as by a pinned one. Read from what was drawn,
+    // not what the pointer asked for, because a host's maximum stops the box short
+    // of the pointer. Not while docked: this position belongs to the corner.
+    if (this.#panelPos !== null && !this.#docked()) {
+      const drawn = this.#host.element.getBoundingClientRect();
+      this.#panelPos = { left: drawn.left, top: drawn.top };
     }
     return box;
   }
@@ -1159,8 +1653,19 @@ export class PanelPlacement {
     // mount, which is the same disagreement between apply and commit that made
     // the header drag jump on release.
     const held = this.#applyResize(grip, box);
+    // A grip on the free edges of a panel standing at the start of a filled window
+    // leaves that inset alone, and the size it stated takes the panel off the
+    // screen's shape. It has to stay where the grip left it, so the inset stops
+    // being one that lasts only as long as the host's size does.
+    if (this.#host.element.style.getPropertyValue("--ag-ui-inset") === this.#fillInset) {
+      this.#gripInset = this.#fillInset;
+      this.#fillInset = null;
+    }
     this.#persistSize({ width: held.right - held.left, height: held.bottom - held.top });
     this.#storeLauncherPosition();
+    if (this.#dockPos !== null) {
+      this.#storeDockPosition(this.#dockPos);
+    }
     // Re-stamp after the drag: a host whose layout changed underneath us would
     // otherwise keep the tab-reachable grip in the old corner, which reads as
     // the control being in the wrong place even though the drag was right.