@jxsuite/studio 4.1.0 → 5.1.0

package/src/ui/panel-resize.ts

@@ -1,12 +1,37 @@
 /// <reference lib="dom" />
 /**
- * Panel-resize.js — Draggable resize handles for the three docks.
+ * Panel-resize — the three dock splitters, driven as `jx-split` elements, and the adapter that
+ * drives any other pixel-sized thing from one.
  *
- * Self-initializing module. Import it and the resize handles become interactive.
+ * Self-initializing module. Import it and the frame's three `jx-split`s become the docks' handles.
  *
  * The handles are the only thing here: dock sizes, their persistence and their projection onto the
- * grid's CSS custom properties all belong to the reactive `shell` record (`../shell`). A drag
- * writes `setDockSize()` and the shell's own effect moves the track; release persists once.
+ * grid's CSS custom properties all belong to the reactive `shell` record (`../shell`). A gesture
+ * writes `setDockSize()` and the shell's own effect moves the track; a commit persists once.
+ *
+ * **What this module does is TRANSLATE, in one place.** A dock is sized in PIXELS — a 240px
+ * Navigator stays 240px when the window grows, which is what every dock a reader has met does — and
+ * `jx-split` speaks in the leading side's SHARE of the box it divides, because a pane split is a
+ * proportion that should survive a resize as one. Both models are right for their case, so the
+ * element keeps its contract and this adapter carries the arithmetic: the share the element shows
+ * is derived from the target's pixels and the track, an `input` is converted back, and the numbers
+ * are re-derived at the START of every gesture and on every window resize, so the element never
+ * drags against a stale track. Those listeners are the one thing `jx-split`'s own `gap` was
+ * designed to spare a host, and they are owed here for a different reason — a dock's bounds are a
+ * pixel floor and a viewport ceiling, and neither is a constant share.
+ *
+ * The docks also sit behind FIXED tracks the shell does not size — the rail's 56px column, the
+ * command bar's 36px row, the status bar's 24px — so a handle's "leading side" is the dock PLUS an
+ * offset. {@link ResizeTarget.lead} is that offset, and it is why `value` is not simply `size /
+ * track`.
+ *
+ * **The Edit column's two handles are the fourth and fifth thing this drives**, through the same
+ * {@link bindSplit} (`canvas/edit-width-drag.ts`), and they are why a snap is here at all: that
+ * column pulls its width onto the document's breakpoints with Alt as the way through, and the
+ * element reports the modifiers each `input` was made with precisely so a host's own snap can
+ * decide. The last handle that was driven by pointer events alone — `setupHandle`, kept for that
+ * one caller while the element had no such hook — is gone with the gap it survived for, and with it
+ * the SC 2.1.1 debt `specs/ui.md` §5.5 recorded.
  */
 
 import {
@@ -17,32 +42,77 @@ import {
   shell,
 } from "../shell";
 import type { DockId } from "../shell";
+import { effect } from "../reactivity";
+import { rectOf } from "../utils/geometry";
+import { splitModifiersOf } from "@jxsuite/ui/behaviors/split";
+import type { SplitModifiers } from "@jxsuite/ui/behaviors/split";
 
 /**
- * What a handle drags.
+ * What a handle drives: a pixel-sized thing, described so {@link bindSplit} can speak to a
+ * `jx-split` about it in shares.
+ *
+ * Generalised out of the three dock rows so the Edit column's own handles can be the fourth and
+ * fifth. Each is sized in px against a different reference, which is the whole of the difference:
+ * `scale` says how many of the target's units one pixel of the HANDLE's travel is worth, and which
+ * way — and everything else, the element owns: capture, the drag state, the keyboard, the collapse
+ * toggle, and the `input`/`change` pair this adapter turns into `write` and `settle`.
  *
- * Generalised out of the three dock rows so the pane splitter can be the fourth. A dock is sized in
- * px and a pane split is a ratio, which is the whole of the difference: `scale` converts a pointer
- * delta in px into the target's own units, and everything else — capture, the dragging class, the
- * text-selection suppression, the double-click reset, the one persist on release — is identical and
- * was worth having once.
+ * **There is no pointer path left in this module**, and it is worth recording why rather than
+ * quietly dropping it: a handle driven by pointer events alone is unreachable from a keyboard,
+ * which is an SC 2.1.1 failure however it is drawn. The pane split moved to `jx-split` first (ui.md
+ * §5.5), the three docks followed, and the Edit column was last because its handle SNAPS — and the
+ * element had no way to tell a host which modifiers a step carried. It has now: every `input`
+ * carries them, so a snap lives in {@link bindSplit} rather than in a pointer handler of this
+ * module's own.
  */
 export interface ResizeTarget {
   /** Which coordinate the drag reads. */
   axis: "x" | "y";
   /** The current value. */
   read: () => number;
-  /** Set it. Called on every pointermove, so it must be cheap and idempotent. */
+  /** Set it. Called on every `input`, so it must be cheap and idempotent. */
   write: (value: number) => void;
-  /** The value a double-click restores. */
+  /** The value the collapse toggle — Enter, or a double click — goes to. */
   reset: () => number;
   /** Lower and upper bounds, read fresh because both can depend on the viewport. */
   min: () => number;
   max: () => number;
-  /** Target units per pixel of pointer movement, signed: negative grows toward the origin. */
+  /**
+   * Target units per pixel of the handle's travel, signed.
+   *
+   * The magnitude is a ratio: a dock's edge moves as far as the dock grows, so it is `1`; the Edit
+   * column is centred, so an edge that moves `dx` widens the column by `2·dx`, and it is `2`. The
+   * sign is which side of the handle the target is on: positive when the target IS the leading side
+   * and grows as the share grows, negative when it is the trailing side. One statement of both,
+   * because a pointer delta no longer reads it separately from the share arithmetic.
+   */
   scale: () => number;
-  /** Persist. Called once on release and once on reset — never during the drag. */
+  /** Persist. Called once per commit — never during the drag. */
   settle: () => void;
+  /**
+   * Pull the value onto a preferred one before it is written — magnetic snapping.
+   *
+   * Offered a value already inside `min`/`max`, and RE-CLAMPED afterwards, because a snap has no
+   * way to know the bounds: `snapEditWidth` returns any target within its tolerance, so a
+   * breakpoint declared 4px past the pane's own width would otherwise be reachable and the stored
+   * width, the readout and the rendered column would all disagree. Clamping on both sides means a
+   * target outside the range simply does not take.
+   *
+   * The modifiers are the ones the element reported on this step — a pointer move and a keyboard
+   * step alike — because a snap has to be escapable: the Edit canvas offers Alt as the bypass.
+   * Omitted by the three docks, which snap to nothing.
+   */
+  snap?: (value: number, modifiers: SplitModifiers) => number;
+  /**
+   * The FIXED length of the leading side, in px — the part the target's own size does not account
+   * for. For a dock it is the tracks the shell does not size on the dock's side of the handle: the
+   * Navigator's handle has the 56px rail before it, the Inspector's has nothing after it, the
+   * Bottom dock's has the 24px status bar below it. For the centred Edit column it is the centre
+   * line itself, since each edge sits half the width away from it. Read fresh, and given the track
+   * because a centre is a fact about the track: a collapsed rail, a hidden status bar or a
+   * scrollbar would move any of these.
+   */
+  lead?: (track: number) => number;
 }
 
 /**
@@ -60,10 +130,11 @@ const MAX_RATIO = 0.5;
 /**
  * Which handle drives which dock, and which direction grows it.
  *
- * Three rows, and the third resizes on the other axis: `grow` is the sign a pointer moving in the
+ * Three rows, and the third resizes on the other axis: `grow` is the sign a handle moving in the
  * positive direction of `axis` contributes, so the Navigator grows rightward, and the Inspector and
- * the Bottom dock grow back toward the pointer's origin. The assistant is not here and never will
- * be — it is an Inspector TAB, resized by resizing the Inspector.
+ * the Bottom dock grow back toward the origin. It becomes the sign of the target's `scale`. The
+ * assistant is not here and never will be — it is an Inspector TAB, resized by resizing the
+ * Inspector.
  */
 const HANDLES: { selector: string; dock: DockId; axis: "x" | "y"; grow: 1 | -1 }[] = [
   { axis: "x", dock: "left", grow: 1, selector: "#resize-left" },
@@ -71,60 +142,146 @@ const HANDLES: { selector: string; dock: DockId; axis: "x" | "y"; grow: 1 | -1 }
   { axis: "y", dock: "bottom", grow: -1, selector: "#resize-bottom" },
 ];
 
+/** Bound, snap, bound again — see {@link ResizeTarget.snap} for why the second one is not spare. */
+function resolveValue(target: ResizeTarget, wanted: number, modifiers: SplitModifiers): number {
+  const bound = (v: number) => Math.min(target.max(), Math.max(target.min(), v));
+  const bounded = bound(wanted);
+  if (!target.snap) {
+    return bounded;
+  }
+  return bound(target.snap(bounded, modifiers));
+}
+
+/** The `jx-split` element as the adapter writes it: a share, its bounds, and its collapse point. */
+export interface SplitElement extends HTMLElement {
+  value: number;
+  min: number;
+  max: number;
+  collapse: number;
+}
+
 /**
- * Wire one handle to one dock.
- *
- * @param {HTMLElement} handle
- * @param {DockId} dock
- * @param {"x" | "y"} axis — which coordinate the drag reads
- * @param {1 | -1} grow — the sign a positive move along `axis` contributes to the dock's size
+ * The length of the box a handle divides, along its axis — the same box `jx-split` measures at
+ * pointerdown, read here so the share this adapter writes and the one the element drags against are
+ * two readings of one number.
  */
-export function setupHandle(handle: HTMLElement, target: ResizeTarget) {
-  const { axis } = target;
-  let drag: { start: number; startSize: number } | null = null;
-  const coord = (e: { clientX: number; clientY: number }) => (axis === "x" ? e.clientX : e.clientY);
-
-  handle.addEventListener("pointerdown", (e) => {
-    e.preventDefault();
-    try {
-      handle.setPointerCapture(e.pointerId);
-    } catch {
-      /* Synthetic events */
+function trackOf(handle: HTMLElement, axis: "x" | "y"): number {
+  for (let node = handle.parentElement; node; node = node.parentElement) {
+    if (globalThis.getComputedStyle(node).display === "contents") {
+      continue;
     }
-    handle.classList.add("dragging");
-    document.body.style.userSelect = "none";
-    drag = { start: coord(e), startSize: target.read() };
-  });
-
-  handle.addEventListener("pointermove", (e) => {
-    if (!drag) {
-      return;
+    const box = rectOf(node);
+    const length = axis === "x" ? box.width : box.height;
+    if (length > 0) {
+      return length;
     }
-    const delta = (coord(e) - drag.start) * target.scale();
-    const wanted = drag.startSize + delta;
-    const floored = Math.max(target.min(), wanted);
-    target.write(Math.min(target.max(), floored));
-  });
+  }
+  return 0;
+}
+
+/**
+ * A target's pixel size as the leading side's share of the track, and back.
+ *
+ * The handle sits `lead + size / |scale|` px into the leading side. With the target ON the leading
+ * side (`scale > 0`) the share is that over the track; on the trailing side it is one minus that.
+ * Both directions are one pair so the two cannot drift: converting a share back to pixels is the
+ * same line solved for `size`.
+ */
+function shareOf(target: ResizeTarget, size: number, track: number): number {
+  const scale = target.scale();
+  const lead = target.lead?.(track) ?? 0;
+  const leading = (lead + size / Math.abs(scale)) / track;
+  return scale > 0 ? leading : 1 - leading;
+}
+function sizeOf(target: ResizeTarget, share: number, track: number): number {
+  const scale = target.scale();
+  const lead = target.lead?.(track) ?? 0;
+  const leading = scale > 0 ? share : 1 - share;
+  return (leading * track - lead) * Math.abs(scale);
+}
 
-  handle.addEventListener("pointerup", (e) => {
-    if (!drag) {
+/**
+ * Drive a `jx-split` from a {@link ResizeTarget}.
+ *
+ * The element owns the gesture, the keyboard, the role and the announcement; this owns the units.
+ * Four writes go INTO the element — `value`, `min`, `max`, `collapse`, every one a share — and two
+ * events come OUT: `input` on every move, which becomes `target.write` in pixels, and `change` on a
+ * commit, which becomes `target.settle`.
+ *
+ * **The four writes are re-derived at the start of every gesture**, on `pointerdown` and `keydown`
+ * in the capture phase so they land before the element records where the gesture started. A share
+ * that was right against one track is wrong against another while the pixels it stands for are
+ * unchanged, and the track moves for more reasons than a window resize: the Edit column's is the
+ * canvas, which a dock opening, a pane split or a scrollbar all change with no event this adapter
+ * could have heard. Measuring at the gesture is the same rule the element itself keeps for its
+ * track, and it is what stops the first pixel of a drag being a jump. A window resize re-derives
+ * them too, so the ANNOUNCED share is honest between gestures and not only during one.
+ *
+ * **The snap runs here**, on the pixels the element asked for and before they are written, with the
+ * modifiers the element reported for this step — see {@link ResizeTarget.snap}. The corrected
+ * pixels go BACK to the element as a share, or its announced value and the drawn track would
+ * disagree until the next step; a pointer gesture recomputes from its origin on every move, so the
+ * correction never compounds.
+ *
+ * The shell's own record can also move a dock without a gesture — a command toggling it, a restored
+ * session — so {@link syncSplits} is exported for the caller that knows when that happened; the
+ * docks subscribe through the shell surface's lifecycle.
+ *
+ * @returns A function that unbinds everything, for a handle taken out of the document.
+ */
+export function bindSplit(handle: SplitElement, target: ResizeTarget): () => void {
+  const sync = (): void => {
+    const track = trackOf(handle, target.axis);
+    if (track <= 0) {
       return;
     }
-    drag = null;
-    try {
-      handle.releasePointerCapture(e.pointerId);
-    } catch {
-      /* Synthetic events */
+    const lo = shareOf(target, target.min(), track);
+    const hi = shareOf(target, target.max(), track);
+    handle.min = Math.min(lo, hi);
+    handle.max = Math.max(lo, hi);
+    handle.collapse = shareOf(target, target.reset(), track);
+    handle.value = shareOf(target, target.read(), track);
+  };
+  const onInput = (event: Event): void => {
+    const track = trackOf(handle, target.axis);
+    if (track <= 0) {
+      return;
     }
-    handle.classList.remove("dragging");
-    document.body.style.userSelect = "";
+    const wanted = sizeOf(target, handle.value, track);
+    const value = resolveValue(target, wanted, splitModifiersOf(event));
+    target.write(value);
+    /* A snap or a clamp moved the pixels; say so back to the element, or its announced share and
+       the drawn track disagree until the next gesture. An equal write is skipped by the runtime. */
+    handle.value = shareOf(target, value, track);
+  };
+  const onChange = (): void => {
     target.settle();
-  });
+  };
+  handle.addEventListener("input", onInput);
+  handle.addEventListener("change", onChange);
+  handle.addEventListener("pointerdown", sync, true);
+  handle.addEventListener("keydown", sync, true);
+  globalThis.addEventListener("resize", sync);
+  sync();
+  bound.set(handle, sync);
+  return () => {
+    handle.removeEventListener("input", onInput);
+    handle.removeEventListener("change", onChange);
+    handle.removeEventListener("pointerdown", sync, true);
+    handle.removeEventListener("keydown", sync, true);
+    globalThis.removeEventListener("resize", sync);
+    bound.delete(handle);
+  };
+}
 
-  handle.addEventListener("dblclick", () => {
-    target.write(target.reset());
-    target.settle();
-  });
+/** Each bound handle's re-derivation, so a size the SHELL moved can be pushed to the element. */
+const bound = new Map<HTMLElement, () => void>();
+
+/** Re-derive every bound handle from the shell's record — after a command moved a dock. */
+export function syncSplits(): void {
+  for (const sync of bound.values()) {
+    sync();
+  }
 }
 
 /** The largest a dock may be dragged to along `axis`. */
@@ -137,6 +294,7 @@ function maxDockSize(axis: "x" | "y"): number {
 function dockTarget(dock: DockId, axis: "x" | "y", grow: 1 | -1): ResizeTarget {
   return {
     axis,
+    lead: () => DOCK_LEAD[dock],
     max: () => maxDockSize(axis),
     min: () => MIN_SIZE[axis],
     read: () => shell.docks[dock].size,
@@ -147,17 +305,46 @@ function dockTarget(dock: DockId, axis: "x" | "y", grow: 1 | -1): ResizeTarget {
   };
 }
 
+/**
+ * The fixed tracks on each dock's side of its handle, in px of the frame's grid
+ * (`styles/shell-frame.json`): the rail's `56px` column before the Navigator, nothing after the
+ * Inspector, and the status bar's `24px` row below the Bottom dock. Constants here because they are
+ * constants there, and the two must agree — a test holds them to the generated sheet.
+ */
+export const DOCK_LEAD: Readonly<Record<DockId, number>> = { bottom: 24, left: 56, right: 0 };
+
 /** Attach every handle present in the document. Idempotent per element by construction. */
 export function mountPanelResize(): void {
   for (const { axis, dock, grow, selector } of HANDLES) {
-    const handle = document.querySelector<HTMLElement>(selector);
+    const handle = document.querySelector<SplitElement>(selector);
     if (handle) {
-      setupHandle(handle, dockTarget(dock, axis, grow));
+      unbinders.push(bindSplit(handle, dockTarget(dock, axis, grow)));
     }
   }
+  /* A dock the SHELL moves — a command opening it, a session restoring it — must reach the element
+     too, or its announced share is the old one. One effect over the three sizes; every write the
+     shell makes is a reactive write, so this is the same subscription the grid's own projection
+     already holds. */
+  stopSync = effect(() => {
+    for (const { dock } of HANDLES) {
+      void shell.docks[dock].size;
+    }
+    syncSplits();
+  });
+}
+
+const unbinders: (() => void)[] = [];
+let stopSync: (() => void) | null = null;
+
+function unmountPanelResize(): void {
+  for (const unbind of unbinders.splice(0)) {
+    unbind();
+  }
+  stopSync?.();
+  stopSync = null;
 }
 
 /* Mounted through the shell's own lifecycle rather than by a bare `mountPanelResize()` at module
    scope. The import-time call read `document` before anything had said the tree existed, which is
    the one part of `registerShellSurface`'s bargain this module was not keeping. */
-registerShellSurface({ mount: mountPanelResize, unmount: () => {} });
+registerShellSurface({ mount: mountPanelResize, unmount: unmountPanelResize });

package/src/ui/popover-surface.ts

@@ -0,0 +1,153 @@
+/// <reference lib="dom" />
+/**
+ * One way to put a surface DOCUMENT in the popover layer.
+ *
+ * `renderPopover` is the lit answer to the same question: it takes a template, appends an anonymous
+ * slot and hands back a handle. A document cannot use it — a document CLEARS the host it is given
+ * and lit renders BESIDE foreign nodes, so the two can never share a container — and every
+ * converted panel would otherwise re-derive the same six steps: take a named slot, mount, wait for
+ * the element's own `jx-ready`, show the platform popover, listen for its `toggle`, and tear the
+ * slot down once. Three of the grid's surfaces needed exactly that on the same day, which is what
+ * made it a module rather than a paragraph copied three times.
+ *
+ * **The panel is a `jx-popover`, so the PLATFORM owns dismissal.** Light dismissal, Escape, the top
+ * layer and focus restoration to the invoker are the popover's own contract; nothing here binds a
+ * document listener, and `dismissOnOutsideClick` — which the lit helper had to implement, and had
+ * to un-arm again to stop a corpse closing its successor — has no counterpart because there is
+ * nothing to arm.
+ *
+ * **Each panel owns its own slot, and that is not a detail.** A NAMED slot (`getLayerSlot`) is
+ * reused while it is still parented, and the platform's own stacking is what makes that fatal:
+ * showing a second `popover=auto` hides the first, the first's `toggle` runs its teardown, and the
+ * teardown clears a slot the second is already mounted in — so the panel that just opened
+ * disappears and nothing reports an error. A slot created here and removed here can only ever take
+ * its own panel down with it. The region id is still `overlay.<kind>:<id>`, so the surface stays
+ * addressable by name.
+ *
+ * @docs extending/ui-kit
+ */
+
+import { layerHost } from "./layers";
+import { overlayRegion, REGION_ATTR } from "./regions";
+import { mountSurface } from "./surface";
+import type { JxMountOptions } from "@jxsuite/runtime/types";
+import type { SurfaceHandle } from "./surface";
+
+/** A popover panel element, as the platform's popover API sees it. */
+type PanelElement = HTMLElement & {
+  open?: boolean;
+  showPopover: (options?: { source?: Element }) => void;
+  hidePopover: () => void;
+};
+
+export interface PopoverSurfaceHandle {
+  /** The named layer slot, which is what carries the `overlay.<kind>:<id>` region. */
+  readonly host: HTMLElement;
+  /** Settles once the document is mounted and the panel shown, or it was closed first. */
+  readonly ready: Promise<void>;
+  /** Whether the panel is still up. */
+  readonly isOpen: () => boolean;
+  /** Close it now. Idempotent, and it does not call `onDismissed`. */
+  readonly close: () => void;
+}
+
+export interface OpenPopoverSurfaceOptions {
+  /** The registered surface name — its document's root must be a `jx-popover`. */
+  name: string;
+  /** The panel's instance name; its region becomes `overlay.<kind>:<id>`. */
+  slot: string;
+  /** The reactive scope the document reads. */
+  scope: Record<string, unknown>;
+  /**
+   * The control it was opened from. It becomes the popover's invoker, so a press on that control
+   * does not light-dismiss the panel its own click is about to toggle, and focus goes back to it.
+   */
+  anchor?: HTMLElement | null;
+  /** The platform closed it — clicked outside, Escape, or a second press on the invoker. */
+  onDismissed?: () => void;
+  /**
+   * A node the document made exists. The one seam an island reaches its host through (§9.4), passed
+   * straight to the runtime.
+   */
+  onNodeCreated?: JxMountOptions["onNodeCreated"];
+}
+
+/**
+ * Mount a surface document into a named popover slot and show it.
+ *
+ * @param {OpenPopoverSurfaceOptions} options
+ * @returns {PopoverSurfaceHandle}
+ */
+export function openPopoverSurface(options: OpenPopoverSurfaceOptions): PopoverSurfaceHandle {
+  const { anchor, name, scope, slot: slotId } = options;
+  const host = document.createElement("div");
+  host.style.pointerEvents = "auto";
+  host.setAttribute(REGION_ATTR, overlayRegion("popover", slotId));
+  layerHost("popover").append(host);
+  const controller = new AbortController();
+  let panel: PanelElement | null = null;
+  let mounted: SurfaceHandle | null = null;
+  let closed = false;
+
+  const finish = (fromPlatform: boolean): void => {
+    if (closed) {
+      return;
+    }
+    closed = true;
+    controller.abort();
+    mounted?.dispose();
+    mounted = null;
+    host.remove();
+    if (fromPlatform) {
+      options.onDismissed?.();
+    }
+  };
+
+  const ready = (async () => {
+    const surface = await mountSurface(name, scope, host, {
+      signal: controller.signal,
+      ...(options.onNodeCreated ? { onNodeCreated: options.onNodeCreated } : {}),
+    });
+    if (controller.signal.aborted) {
+      return;
+    }
+    mounted = surface;
+    panel = surface.root as PanelElement;
+    /* On the PANEL as well as the slot: a popover is `position: fixed` in the top layer, so the
+       slot around it has a zero-height box and the screenshots lane refuses it ("has an empty
+       box"). Both carry the id; the measurement takes the last match, which is the panel. */
+    panel.setAttribute(REGION_ATTR, overlayRegion("popover", slotId));
+    panel.addEventListener("toggle", (event) => {
+      if ((event as { newState?: string }).newState === "closed") {
+        finish(true);
+      }
+    });
+    /* A custom element connects asynchronously: `jx-ready` is the panel saying its `popover`
+       attribute is on and it may be shown. Showing before that is a silent no-op — the panel is
+       built, correctly styled, and never in the top layer. */
+    if (!panel.hasAttribute("popover")) {
+      await new Promise<void>((resolve) => {
+        panel?.addEventListener("jx-ready", () => resolve(), { once: true });
+      });
+    }
+    if (controller.signal.aborted) {
+      return;
+    }
+    panel.showPopover(anchor ? { source: anchor } : undefined);
+  })();
+
+  return {
+    close: () => {
+      if (closed) {
+        return;
+      }
+      if (panel?.open) {
+        panel.hidePopover();
+      }
+      finish(false);
+    },
+    host,
+    isOpen: () => !closed,
+    ready,
+  };
+}

package/src/ui/progress-modal.ts

@@ -20,14 +20,16 @@
  * `packages/pull-package-sync.ts`, `packages/jxsuite-update.ts` and
  * `settings/dependencies-editor.ts`. Every other long operation calls `beginActivity` directly and
  * blocks nobody.
+ *
+ * The surface itself is `surfaces/progress-modal.json`, a `jx-dialog`; this module is the flow
+ * around it and owns nothing that is drawn.
  */
 
-import { html } from "lit-html";
 import { beginActivity } from "../panels/activity-panel";
 import { setBottomTab } from "../shell";
-import { openModal } from "./layers";
+import { layerHost } from "./layers";
+import { openProgressSurface } from "../surfaces/progress-modal";
 import type { ActivityHandle } from "../panels/activity-panel";
-import type { TemplateResult } from "lit-html";
 
 export interface ProgressModalHandle {
   /** Update the status line shown under the title. Also the Activity entry's status. */
@@ -57,46 +59,6 @@ export interface ProgressModalOptions {
   cancel?: () => void;
 }
 
-function card(body: TemplateResult): TemplateResult {
-  return html`
-    <sp-underlay open></sp-underlay>
-    <div class="progress-modal" aria-live="polite">${body}</div>
-  `;
-}
-
-/**
- * The running view: the spinner, the status line, and the two ways out.
- *
- * `Run in the background` is not a cancel and does not pretend to be — it dismisses the BLOCKING
- * part and leaves the operation running where it can be watched, which is the affordance a modal
- * with no exit never had.
- */
-function runningView(
-  title: string,
-  status: string,
-  actions: { background: () => void; cancel?: (() => void) | undefined },
-): TemplateResult {
-  return card(html`
-    <div class="progress-head">
-      <sp-progress-circle indeterminate size="m" aria-label=${title}></sp-progress-circle>
-      <div class="progress-lines">
-        <strong class="progress-title">${title}</strong>
-        ${status ? html`<span class="progress-status">${status}</span>` : ""}
-      </div>
-    </div>
-    <div class="progress-actions">
-      <sp-button size="s" variant="secondary" treatment="outline" @click=${actions.background}>
-        Run in the background
-      </sp-button>
-      ${
-        actions.cancel
-          ? html`<sp-button size="s" variant="negative" @click=${actions.cancel}>Cancel</sp-button>`
-          : ""
-      }
-    </div>
-  `);
-}
-
 /**
  * Show a blocking progress modal, and record the operation in Activity either way.
  *
@@ -118,7 +80,7 @@ export function showProgressModal(opts: ProgressModalOptions): ProgressModalHand
       return;
     }
     closed = true;
-    modal.close();
+    surface.close();
   };
 
   /** Hand the app back and put the operation where it can be watched. */
@@ -127,21 +89,21 @@ export function showProgressModal(opts: ProgressModalOptions): ProgressModalHand
     setBottomTab("activity");
   };
 
-  const cancel = opts.cancel
-    ? () => {
-        close();
-        opts.cancel?.();
-      }
-    : undefined;
-
-  const view = (status: string) => runningView(opts.title, status, { background, cancel });
-
-  const modal = openModal(view(opts.status ?? ""), {
-    label: opts.title,
-    // Escape means the same thing the button does: stop BLOCKING, not stop working. The operation
-    // Owned the modal outright before, and swallowing Escape was the only honest thing a surface
-    // With nowhere to put a running operation could do.
-    onDismiss: background,
+  const surface = openProgressSurface({
+    cancellable: opts.cancel !== undefined,
+    layer: layerHost("modal"),
+    // Escape means the same thing the confirm button does: stop BLOCKING, not stop working. The
+    // Operation owned the modal outright before, and swallowing Escape was the only honest thing a
+    // Surface with nowhere to put a running operation could do.
+    onBackground: background,
+    onCancel: () => {
+      close();
+      opts.cancel?.();
+    },
+    // The platform's own close, whatever reached it: the document goes with the dialog.
+    onClosed: close,
+    status: opts.status ?? "",
+    title: opts.title,
   });
 
   return {
@@ -171,7 +133,7 @@ export function showProgressModal(opts: ProgressModalOptions): ProgressModalHand
     setStatus(text: string) {
       activity.setStatus(text);
       if (!closed) {
-        modal.update(view(text));
+        surface.setStatus(text);
       }
     },
   };