staffa 0.18.0 → 0.18.2

package/src/components/panels.ts

@@ -193,7 +193,7 @@ export interface Panel<P = Record<string, string | number | string[]>> {
 	 * Every size is capped at the content area, so on a phone they all come to
 	 * the same thing: one screen at a time. And a width depends only on the
 	 * window, never on what else is open, so opening or closing a panel never
-	 * resizes another — the run of columns just recentres in the area.
+	 * resizes another — the run of columns just shifts over in the area.
 	 *
 	 * The ask is a ceiling only; there is no matching floor, since the window can
 	 * be any width. Aim your layout at 360px — about the narrowest phone still in
@@ -211,10 +211,11 @@ export interface Panel<P = Record<string, string | number | string[]>> {
 	maxWidth?: PanelSize;
 	/**
 	 * Set this while you're fetching what the panel needs, and back to `false`
-	 * when you're done. A new panel waits a moment before sliding in, so it can
-	 * arrive with real content instead of empty; if the wait drags on it slides
-	 * in anyway and shows a loading indicator until the flag clears. It only
-	 * affects the animation; the stack and the URL never wait for it.
+	 * when you're done. A new panel slides into place right away but waits a
+	 * moment before fading in, so it can appear with real content instead of
+	 * empty; if the wait drags on it fades in anyway and shows a loading
+	 * indicator until the flag clears. It only affects the animation; the
+	 * stack and the URL never wait for it.
 	 */
 	loading?: boolean;
 	/**
@@ -415,11 +416,12 @@ function matchRoute(r: { segs: Seg[] }, segments: string[]): Record<string, any>
 
 /**
  * The one duration every bit of shell motion shares: the enter/exit fades, the
- * sideways `left` moves, the narrow-screen nav slide. Published below as the
- * `--s-panel-ms` custom property, so CSS and JS can't drift apart.
+ * slides, the narrow-screen nav slide. Interpolated into every transition as a
+ * literal — the shared constant is what keeps CSS and JS in step — and also
+ * published as the `--s-panel-ms` custom property for app CSS.
  */
-const PAGE_MS = 250;
-/** How long a freshly pushed `loading` panel holds its enter animation. */
+export const PAGE_MS = 250;
+/** How long a freshly pushed `loading` panel holds its fade-in. */
 const LOADING_HOLD_MS = 300;
 /**
  * The bounds of a column: at most 540px — the width columns aim for, the area
@@ -428,13 +430,6 @@ const LOADING_HOLD_MS = 300;
  */
 const SMALL_MIN_PX = 360;
 export const SMALL_MAX_PX = 540;
-/**
- * Two `z-index` steps per panel: a panel sits on the odd layer for its depth in
- * the stack, a *closing* one on the even layer just below. So a replacement
- * comes in over the panel it replaces, while a closing panel fades out over
- * whatever it was covering.
- */
-const LAYER_STEP = 2;
 
 // ─── Module-level styling ────────────────────────────────────────────────────
 
@@ -442,9 +437,9 @@ A.insertGlobalCss({
 	":root": `--s-panel-ms:${PAGE_MS}ms`,
 	// The clipping viewport the columns slide through; panels are absolutely
 	// positioned inside it, sized and offset from JS (see `layout()`).
-	// `isolation` keeps their z-index layers (see LAYER_STEP) below the shell's
-	// own chrome. It paints the same PANEL_SHEEN as every panel, so columns and
-	// the ground beside them read as one surface.
+	// `isolation` keeps their z-index layers below the shell's own chrome. It
+	// paints the same PANEL_SHEEN as every panel, so columns and the ground
+	// beside them read as one surface.
 	// `overflow:clip`, not `hidden`: a hidden box is still a scroll container,
 	// and anything that scrolls it (find-in-page, an in-page anchor) shifts every
 	// column sideways permanently, with nothing to scroll it back.
@@ -452,48 +447,65 @@ A.insertGlobalCss({
 		"flex:1 min-width:0 min-height:0 position:relative overflow:clip isolation:isolate " +
 		PANEL_SHEEN,
 	".s-panel": {
-		// A panel rests at a plain `left` offset with no transform: a transformed
-		// element is composited, costing it subpixel text antialiasing. Transform
-		// is used only for the enter/exit slides. No `width` transition either —
-		// animating one reflows the column's content every frame.
-		// The fade is deliberately `linear` while the drift eases out: an eased
-		// opacity spends its last stretch near zero, reading as a vanish.
-		// Layering is set from JS (`layout()`, `beginClose`), not DOM order: a
-		// closing panel is no longer in the reactive list, so its element's
-		// position among the live ones is Aberdeen's business. See LAYER_STEP.
+		// The shell knows three motions, and this vocabulary is all of them:
+		// a panel that MOVES slides — every mover in a pass shares this one
+		// duration and ease-out, so panels travelling the same distance travel
+		// as one — a CREATED panel joins the strip beside the old position of
+		// the panels beneath it and rides their slide while fading in, and a
+		// CLOSED one keeps its seat beside the surviving panel beneath it and
+		// rides that panel's slide while fading out — its creation played
+		// backwards. Nothing else ever animates.
+		// A slide is a `transform` playing out to none (see `layout`), never an
+		// animated `left`: left is a layout property, so animating it would
+		// relayout and repaint every travelling column on every frame, where a
+		// transform moves composited layers. `left` always holds the resting
+		// position — it is not in the transition list — and the transform
+		// exists only while a panel travels, so text gets its subpixel
+		// antialiasing back the moment it settles. No `width` transition
+		// either — animating one reflows the column every frame. And the fade
+		// is `linear` while the moves ease out: an eased opacity spends its
+		// last stretch near zero, reading as a vanish.
+		// Layering is fixed per state, not per stack depth: live panels never
+		// overlap each other (the strip keeps them adjacent, see `layout()`), so
+		// only the fading ones need an order — below, in both directions, per
+		// the classes underneath.
 		// PANEL_SHEEN gives every panel an opaque ground (panels animate over one
 		// another, and two transparent ones mean text sliding over text).
 		"&":
 			"position:absolute top:0 bottom:0 left:0 display:flex flex-direction:column " +
 			PANEL_SHEEN + " " +
-			"visibility:visible transition: left var(--s-panel-ms) ease, transform var(--s-panel-ms) ease-out, opacity var(--s-panel-ms) linear, visibility 0s;",
+			`z-index:2 transition: transform ${PAGE_MS}ms ease-out, opacity ${PAGE_MS}ms linear;`,
 		// The hairline between two columns, fading at both ends (like the sidebar's
 		// `.s-nav-sep`). Columns tile with no gutter — each brings its own `$3` of
 		// padding — so this sits exactly on the boundary.
 		"&.s-panel-sep::before":
 			"content:'' position:absolute left:0 top:0.6rem bottom:0.6rem width:1px z-index:1 " +
 			"background: linear-gradient(to bottom, transparent, $s-faint 18%, $s-faint 82%, transparent);",
-		// Enter and exit share one vocabulary: a fade, drifting a short 8cqw
-		// (`cqw`: `.s-main` is the container) only when the navigation really
-		// moves — a push opening a new column, a back closing one. A panel
-		// replacing another simply fades in on top of it (see LAYER_STEP), the
-		// old one fading in place beneath. The enter start state is applied with
-		// transitions off and then dropped, so the panel settles instead of jumping.
-		"&.s-panel-enter": "opacity:0 transition:none",
-		// On its way out; leaves the DOM when the fade ends (see `playExit`).
-		"&.s-panel-closing": "opacity:0 pointer-events:none",
-		// The sideways drift, as an enter's start state or a close's destination.
-		"&.s-panel-drift": "transform: translateX(8cqw);",
-		// Off screen but open: crowded out at the left edge (`hidden`) or parked
-		// past the right one (`parked`). Both keep their DOM — and so their scroll
-		// position and half-typed forms — hence `visibility`, not `display:none`.
-		// Transitioning it counts as *visible* for the whole fade, flipping at the
-		// very end; the rule above (`visibility 0s`) reveals it again instantly.
-		"&.s-panel-hidden, &.s-panel-parked":
-			"opacity:0 visibility:hidden " +
-			"transition: left var(--s-panel-ms) ease, transform var(--s-panel-ms) ease-out, opacity var(--s-panel-ms) linear, visibility var(--s-panel-ms);",
-		"&.s-panel-hidden": "transform: translateX(-8cqw);",
-		"&.s-panel-parked": "transform: translateX(8cqw);",
+		// Still owed or playing its entry fade: beneath the settled panels, so
+		// whatever slides across its spot passes over it. Dropped once the fade
+		// is over (see `releaseEnter`).
+		"&.s-panel-new": "z-index:1",
+		// On its way out: it fades, still riding the strip (see `layout`),
+		// beneath every live panel (declared after `.s-panel-new`, so closing
+		// mid-enter drops a panel to the bottom), and leaves the DOM when the
+		// fade ends (see `playExit`).
+		"&.s-panel-closing": "z-index:0 opacity:0 pointer-events:none",
+		// The fade-in's start state: a newcomer wears it from creation until its
+		// content is ready — usually the very pass that placed it, later for a
+		// `loading` panel holding out for data — sliding invisibly meanwhile.
+		// Dropping the class is what starts the fade (see `releaseEnter`).
+		"&.s-panel-enter": "opacity:0",
+		// Off screen but open: the strip simply continues past the viewport's
+		// edges, so these rest at their true positions, clipped — being crowded
+		// out or revealed is an ordinary move, not a fade. Both keep their DOM —
+		// and so their scroll position and half-typed forms — hence
+		// `visibility`, not `display:none`. The flip is timed by `layout()`,
+		// never transitioned: a panel sliding offstage gets the class once its
+		// slide ends and drops it the moment it is revealed. `visibility` is
+		// not compositable, and Chrome composites an element's transitions as
+		// a group, so listing it here would drag the slide itself onto the
+		// main thread — relaid out and repainted every frame.
+		"&.s-panel-hidden, &.s-panel-parked": "visibility:hidden",
 	},
 	// The scroll container, with the column's own padding. Its scrollbar sits
 	// flush against the column edge (unlike content mode's inset one), so it meets
@@ -599,14 +611,24 @@ interface PanelEntry {
 	hash?: string;
 	/** Set once the panel is on its way out, playing its exit animation. */
 	closing?: boolean;
-	/** Set while an enter animation is still to be played. */
+	/**
+	 * The nearest surviving panel beneath this one when it closed. The exit
+	 * rides that panel's motion (see `layout`), the mirror of how a newcomer
+	 * rides the panels it opens over, so a close plays the open backwards.
+	 */
+	anchor?: string;
+	/** Set while the fade-in is still owed (a `loading` hold can owe it past placement). */
 	enter?: boolean;
-	/** Whether that enter — or the exit, once `closing` — carries the sideways drift. */
-	drift?: boolean;
 	/** Whether the panel has been through a full layout pass (and so may animate). */
 	placed?: boolean;
 	/** Whether its `loading` hold has already expired, so it can't hold again. */
 	holdDone?: boolean;
+	/**
+	 * Whether the last layout pass put this panel off screen. The deferred
+	 * visibility flip (see `layout`) consults it when it fires, so a panel
+	 * revealed again before its slide out ended is never hidden by mistake.
+	 */
+	offstage?: boolean;
 	/** What the panel asks for, kept in step with its `$panel.maxWidth`. */
 	maxWidth: PanelSize;
 	/**
@@ -813,6 +835,8 @@ export class PanelStackController implements PanelStack {
 	private lastGeom?: Geometry;
 	private layoutQueued = false;
 	private timers = new Set<ReturnType<typeof setTimeout>>();
+	/** Elements playing their exit fade, each riding its anchor's motion (see `layout`). */
+	private exiting = new Set<{ el: HTMLElement; anchor?: string; ride: number }>();
 	/** The arrangement the navigation in flight is heading for; see {@link intended}. */
 	private intent: Arrangement | null = null;
 	/** The navigation the router hasn't settled yet, if any. */
@@ -1032,12 +1056,6 @@ export class PanelStackController implements PanelStack {
 		const pinned = route.current.state.pinned;
 		const seedPins = new Set<string>(Array.isArray(pinned) ? pinned.map(String) : []);
 		const existing = new Map(this.$state.live.map((entry) => [entry.path, entry]));
-		// A replacement — something enters while something closes — just fades:
-		// the new panel in on top, the old ones out in place beneath it (see the
-		// `.s-panel-drift` comment). A pure push or a pure close drifts sideways.
-		const entering = nav !== "load" && nav !== "back";
-		const drift = !(entering && target.stack.some((p) => !existing.has(p)) &&
-			this.$state.live.some((e) => !target.stack.includes(e.path)));
 		const next: PanelEntry[] = [];
 		for (const path of target.stack) {
 			const kept = existing.get(path);
@@ -1048,16 +1066,20 @@ export class PanelStackController implements PanelStack {
 				continue;
 			}
 			const entry = this.createEntry(path, next.length <= target.focus, seedPins.has(path));
-			// An initial load just appears, and so do panels *revealed* by a back:
-			// they belong underneath the ones sliding away.
-			if (entering) {
-				entry.enter = true;
-				entry.drift = drift;
-			}
+			// An initial load just appears; any later navigation animates its new
+			// panels in — beneath what's already there, so a back that re-creates
+			// a panel plays out under the one it takes away.
+			if (nav !== "load") entry.enter = true;
 			next.push(entry);
 			this.$open[path] = entry;
 		}
-		for (const entry of existing.values()) this.beginClose(entry, drift);
+		// What remains in `existing` closes, each remembering the nearest
+		// surviving panel beneath it — the anchor its exit fade rides.
+		let anchor: string | undefined;
+		for (const entry of this.$state.live) {
+			if (existing.has(entry.path)) this.beginClose(entry, anchor);
+			else anchor = entry.path;
+		}
 		this.$state.live = next;
 		this.$state.focus = Math.min(target.focus, next.length - 1);
 		this.scheduleLayout();
@@ -1098,41 +1120,54 @@ export class PanelStackController implements PanelStack {
 	 * at the end of the animation. Only the element lingers to play that animation,
 	 * which is what `drawPanel`'s `destroy=` hook hands to {@link playExit}.
 	 */
-	private beginClose(entry: PanelEntry, drift: boolean): void {
+	private beginClose(entry: PanelEntry, anchor?: string): void {
 		entry.closing = true;
-		entry.drift = drift;
+		entry.anchor = anchor;
 		entry.$panel.visible = false;
-		// Frozen one layer below where it was, so it fades out over the panel it
-		// uncovers and under the one replacing it (see LAYER_STEP). Set here, while
-		// the element is still ours — a moment later `entry.el` is gone.
-		if (entry.el) entry.el.style.zIndex = String(LAYER_STEP * this.$state.live.indexOf(entry));
 		delete this.$open[entry.path];
 	}
 
 	/**
-	 * A closed panel's send-off, run by Aberdeen once its scope is gone: it fades
-	 * where it stands, inert, and leaves the DOM on `transitionend`. A fixed timer
-	 * would race the transition and pull the element a frame early, making the
-	 * panel appear to fade half-way and vanish; the timeout is only a fallback for
-	 * when no `transitionend` is coming (transitions off, element never placed).
+	 * A closed panel's send-off, run by Aberdeen once its scope is gone: it fades,
+	 * inert, riding its anchor's slide (see `layout`), and leaves the DOM once
+	 * the fade is over (see {@link afterFade}).
 	 */
 	private playExit(entry: PanelEntry, el: HTMLElement): void {
 		// A panel being *redrawn* replaces its element through here too; that one
 		// simply goes, so the new one isn't drawn over a ghost of the old.
 		if (!entry.closing) { el.remove(); return; }
 		el.classList.add("s-panel-closing");
-		if (entry.drift) el.classList.add("s-panel-drift");
 		el.setAttribute("inert", "");
-		const drop = () => {
-			clearTimeout(timer);
-			this.timers.delete(timer);
+		// Only a placed panel has a seat on the strip to ride out from.
+		const exit = entry.placed ? { el, anchor: entry.anchor, ride: 0 } : null;
+		if (exit) this.exiting.add(exit);
+		this.afterTransition(el, "opacity", () => {
+			if (exit) this.exiting.delete(exit);
 			el.remove();
-		};
-		el.addEventListener("transitionend", (e: TransitionEvent) => {
-			if (e.target === el && e.propertyName === "opacity") drop();
 		});
-		const timer = setTimeout(drop, PAGE_MS + 80);
+	}
+
+	/**
+	 * Run `done` once `el`'s transition of `prop` is over. The real signal is
+	 * `transitionend` — or `transitioncancel`, for one a resize snaps short —
+	 * so the transition's actual length rules, however long: DevTools' slowed
+	 * animations stretch it tenfold without touching any timer. The timer only
+	 * stands in for a transition that never starts at all (transitions off,
+	 * element never placed, nothing to travel), which is why one proving real
+	 * (`transitionrun`) disarms it.
+	 */
+	private afterTransition(el: HTMLElement, prop: string, done: () => void): void {
+		let called = false;
+		const timer = setTimeout(() => finish(), PAGE_MS + 80);
 		this.timers.add(timer);
+		const disarm = () => { clearTimeout(timer); this.timers.delete(timer); };
+		const finish = () => { disarm(); if (!called) { called = true; done(); } };
+		const forProp = (fn: () => void) => (e: TransitionEvent) => {
+			if (e.target === el && e.propertyName === prop) fn();
+		};
+		el.addEventListener("transitionrun", forProp(disarm));
+		el.addEventListener("transitionend", forProp(finish));
+		el.addEventListener("transitioncancel", forProp(finish));
 	}
 
 	// ── Navigation ─────────────────────────────────────────────────────────
@@ -1819,9 +1854,11 @@ export class PanelStackController implements PanelStack {
 			}
 		}
 
-		// The content area is a fixed width, so a run that doesn't fill it centres
-		// rather than hanging off the left edge — the chrome around it never moves.
-		const left = (geom.area - runSum) / 2;
+		// A run that doesn't fill the fixed-width area centres in it — unless
+		// panels sit crowded out on its left: then it hugs the left edge instead,
+		// so the strip crosses that edge with no gap and a reveal is a plain
+		// slide back in.
+		const left = first > 0 ? 0 : (geom.area - runSum) / 2;
 
 		for (let i = first; i <= cur; i++) live[i].width = width(live[i]);
 		// Never-visible panels get their would-be width, so a reveal doesn't start
@@ -1830,58 +1867,139 @@ export class PanelStackController implements PanelStack {
 			if (!entry.width) entry.width = width(entry);
 		}
 
-		// Phase 1 — every panel's *start* state for this frame. Panels on screen
-		// simply move; freshly mounted ones still have transitions off, so what is
-		// set here is adopted instantly and becomes the "before" of their enter.
+		// Phase 1 — lay the strip out for this frame: each panel flush against
+		// its neighbours, the visible run [first..cur] in the viewport, earlier
+		// panels continuing off its left edge and parked ones held past its
+		// right. `left` gets each new resting position outright — it never
+		// animates — and the slide to it is a FLIP: a mover is held at its
+		// current visual spot by a transform (its mid-slide offset plus the
+		// distance), a newcomer at its start beside the OLD position of the
+		// nearest placed panel beneath it (`delta`, so the slide in is one
+		// motion with the panels making room; with nothing beneath it to come
+		// from, it simply fades in place). Phase 3 plays every held transform
+		// out to none. A snap pass holds nothing: geometry must land, not
+		// travel.
 		const fresh: PanelEntry[] = [];
+		const movers: HTMLElement[] = [];
+		const deltas = new Map<string, number>();
+		// All reads before all writes: a mover may still be mid-slide, and its
+		// current offset must come out of the computed style before this pass
+		// dirties it (one style recalc, then cached).
+		const txs = new Map<PanelEntry, number>();
+		if (!snap) for (const entry of live) { if (entry.placed) txs.set(entry, transformX(entry.el!)); }
 		let x = left;
+		let delta = 0;
+		for (let i = 0; i < first; i++) x -= live[i].width;
 		for (let i = 0; i < n; i++) {
 			const entry = live[i];
 			const el = entry.el!;
 			const shown = i >= first && i <= cur;
-			// Visible columns tile the run left to right; crowded-out ones rest at
-			// its left edge and parked ones just past its right, both keeping their
-			// last width. Deeper panels layer over shallower (see LAYER_STEP).
-			place(el, shown ? x : i > cur ? left + runSum : left, entry.width, LAYER_STEP * i + 1);
+			// Parked panels never dip into the viewport, however short the run.
+			if (i === cur + 1) x = Math.max(x, geom.area);
+			// A panel that mounts while still fetching holds its fade for a
+			// moment, so it can appear with real content instead of empty.
+			if (entry.enter || !entry.placed) {
+				if (!entry.$panel.loading || entry.holdDone) entry.$ui.holding = false;
+				else if (!entry.$ui.holding) { entry.$ui.holding = true; this.holdEnter(entry); }
+			}
+			if (entry.placed) {
+				delta = parseFloat(el.style.left) - x;
+				deltas.set(entry.path, delta);
+				if (delta && !snap) {
+					// Hold the visual spot while `left` jumps beneath it. The
+					// inline transition keeps the transform still — and only it:
+					// running fades carry on, and one starting this pass (a
+					// release below) still gets its linear curve.
+					el.style.transition = `opacity ${PAGE_MS}ms linear`;
+					el.style.transform = `translateX(${(txs.get(entry) ?? 0) + delta}px)`;
+					movers.push(el);
+				}
+				el.style.left = `${x}px`;
+				// A fade held back for content starts the moment its hold lifts.
+				if (entry.enter && !entry.$ui.holding) this.releaseEnter(entry);
+			} else {
+				fresh.push(entry);
+				el.style.left = `${x}px`;
+				if (entry.enter && shown) {
+					el.style.transform = `translateX(${delta}px)`;
+					el.classList.add("s-panel-enter", "s-panel-new");
+				}
+			}
+			el.style.width = `${entry.width}px`;
+			x += entry.width;
 			// Written only on a change, so per-panel UI hanging off `visible` or
 			// `width` isn't rebuilt by every pass.
 			if (entry.$panel.visible !== shown) entry.$panel.visible = shown;
 			if (entry.$panel.width !== entry.width) entry.$panel.width = entry.width;
-			if (shown) x += entry.width;
 			el.classList.toggle("s-panel-sep", shown && i > first);
-			// Off-screen panels fade out and stop rendering, keeping their DOM.
-			el.classList.toggle("s-panel-hidden", i < first);
-			el.classList.toggle("s-panel-parked", i > cur);
+			// Off-screen panels stop rendering, keeping their DOM. A revealed
+			// panel is visible at once; one sliding offstage stays visible for
+			// the whole slide, its visibility class deferred to the slide's
+			// end — but applied outright when it is already invisible, about
+			// to be (a newcomer offstage from birth), or snapping.
+			const hidden = i < first;
+			const wasOff = el.classList.contains("s-panel-hidden") || el.classList.contains("s-panel-parked");
+			if (shown) {
+				el.classList.remove("s-panel-hidden", "s-panel-parked");
+			} else if (wasOff || !entry.placed || snap) {
+				el.classList.toggle("s-panel-hidden", hidden);
+				el.classList.toggle("s-panel-parked", !hidden);
+			} else {
+				this.afterTransition(el, "transform", () => {
+					if (entry.el !== el || !entry.offstage) return;
+					el.classList.toggle("s-panel-hidden", hidden);
+					el.classList.toggle("s-panel-parked", !hidden);
+				});
+			}
+			entry.offstage = !shown;
 			el.toggleAttribute("inert", !shown);
-			if (entry.placed) continue;
-			fresh.push(entry);
-			// A panel that mounts while still fetching holds here for a moment, so
-			// it can enter with real content instead of an empty column.
-			if (!entry.$panel.loading || entry.holdDone) entry.$ui.holding = false;
-			else if (!entry.$ui.holding) { entry.$ui.holding = true; this.holdEnter(entry); }
-			// Already at its resting place; the enter is the transparency (and,
-			// when drifting, the offset one edge to the right) it starts from.
-			if (entry.enter && shown) {
-				el.classList.add("s-panel-enter");
-				if (entry.drift) el.classList.add("s-panel-drift");
+		}
+
+		// Closing panels keep their seat on the strip while they fade: each
+		// travels exactly as far as its anchor — the surviving panel it stood
+		// on — so a close slides back out the way the open slid in, and one
+		// whose anchor stays put is the plain crossfade it should be. A plain
+		// retarget, no holding: the transition picks the slide up from wherever
+		// the element is now.
+		for (const exit of this.exiting) {
+			const d = exit.anchor == null ? undefined : deltas.get(exit.anchor);
+			if (d) {
+				exit.ride -= d;
+				exit.el.style.transform = `translateX(${exit.ride}px)`;
 			}
 		}
 
 		// Phase 2 — reading a layout property forces the browser to adopt those
-		// start states (and a snap pass's transition-free geometry) to animate from.
-		if (fresh.length || snap) void container.offsetWidth;
+		// held spots (and a snap pass's transition-free geometry) to slide from.
+		if (fresh.length || movers.length || snap) void container.offsetWidth;
 		if (snap) shell.classList.remove("s-shell-snap");
-		// Phase 3 — transitions back on, start state dropped, and off they go.
+		// Phase 3 — every held transform plays out to none: the slides start
+		// now, and the newcomers' fades with them — unless a panel is holding
+		// for its content, which keeps the fade's start state on until then.
+		for (const el of movers) {
+			el.style.transition = "";
+			el.style.transform = "";
+		}
 		for (const entry of fresh) {
-			if (entry.$ui.holding) continue;
-			entry.el!.style.transition = "";
-			entry.el!.classList.remove("s-panel-enter", "s-panel-drift");
-			entry.enter = false;
+			const el = entry.el!;
+			el.style.transition = "";
+			el.style.transform = "";
 			entry.placed = true;
+			if (!entry.$ui.holding) this.releaseEnter(entry);
 		}
 	}
 
-	/** Let a `loading` panel's enter animation wait — but not indefinitely. */
+	/** Start (or skip) a newcomer's fade-in; any slide is already underway. */
+	private releaseEnter(entry: PanelEntry): void {
+		entry.enter = false;
+		const el = entry.el;
+		if (!el || !el.classList.contains("s-panel-enter")) return;
+		el.classList.remove("s-panel-enter");
+		// Keep it beneath its elders until the fade is over.
+		this.afterTransition(el, "opacity", () => el.classList.remove("s-panel-new"));
+	}
+
+	/** Let a `loading` panel's fade-in wait — but not indefinitely. */
 	private holdEnter(entry: PanelEntry): void {
 		const timer = setTimeout(() => {
 			this.timers.delete(timer);
@@ -1895,19 +2013,18 @@ export class PanelStackController implements PanelStack {
 	}
 }
 
-/** Put a panel at rest: `x` from the region's left edge, `width` pixels wide, on layer `z`. */
-function place(el: HTMLElement, x: number, width: number, z: number): void {
-	el.style.left = `${x}px`;
-	el.style.width = `${width}px`;
-	el.style.zIndex = String(z);
-}
-
 // ─── Helpers ─────────────────────────────────────────────────────────────────
 
 function sameStack(a: string[], b: string[]): boolean {
 	return a.length === b.length && a.every((v, i) => v === b[i]);
 }
 
+/** The X offset of `el`'s computed transform — where a slide has it right now. */
+function transformX(el: HTMLElement): number {
+	const t = getComputedStyle(el).transform;
+	return t && t !== "none" ? new DOMMatrixReadOnly(t).m41 : 0;
+}
+
 /**
  * The first non-empty text inside `el`, trimmed and capped at a name-like
  * length — the stand-in title for a panel that never set one.

package/src/theme.ts

@@ -32,9 +32,11 @@ import A from "aberdeen";
  * declaration, at the given angle. A shared constant rather than a `--s-sheen`
  * custom property: `var()`s inside a custom property resolve where it is
  * *defined*, so every surface would get the page's wash instead of its own.
+ * The shorthand names `$s-bg` as well as the gradient: a `background:` that
+ * gave only an image would reset the colour under it to transparent.
  */
 const sheen = (angle: string) =>
-	`background: linear-gradient(${angle}, color-mix(in oklab, $s-bg, white 9%), color-mix(in oklab, $s-bg, black 9%));`;
+	`background: $s-bg linear-gradient(${angle}, color-mix(in oklab, $s-bg, white 9%), color-mix(in oklab, $s-bg, black 9%));`;
 
 /** The surface sheen: the wash every surface (and the page) is painted with. */
 export const SURFACE_SHEEN = sheen("170deg");
@@ -120,7 +122,14 @@ A.insertGlobalCss({
 	// A lightweight reset: bare semantic HTML, with less ugly defaults.
 	"*, *::before, *::after": "box-sizing:border-box",
 	html: "text-size-adjust:100%",
-	body: "m:0 p:$3 line-height:1.5 font-family: system-ui, -apple-system, 'Segoe UI', Roboto, sans-serif; -webkit-font-smoothing:antialiased background-color:$s-bg text:$s-text",
+	// The page wears the same wash as a surface, on a page at least as tall as
+	// what that wash is painted on: <body>'s background is propagated to the
+	// canvas, which covers the whole viewport, while the gradient is still
+	// *sized* from the root box. So a page shorter than the viewport — a bare
+	// spinner while an app boots — would tile its wash down the rest of the
+	// canvas in bands. `dvh`, not `vh`: a mobile viewport that grows as the URL
+	// bar retracts would open a band again.
+	body: "m:0 p:$3 min-height:100dvh line-height:1.5 font-family: system-ui, -apple-system, 'Segoe UI', Roboto, sans-serif; -webkit-font-smoothing:antialiased text:$s-text " + SURFACE_SHEEN,
 	// The contextual link colour: `--s-link` on neutral surfaces, the ink on accent ones.
 	a: "color: $s-link-fg; text-decoration:underline text-underline-offset:2px; transition: color 0.12s, filter 0.12s;",
 	"a:hover": "filter: brightness(1.15)",
@@ -196,9 +205,9 @@ A.insertGlobalCss({
 		"--s-muted: color-mix(in oklab, $s-text, $s-bg 42%); " +
 		"--s-faint: color-mix(in oklab, $s-text, $s-bg 80%); " +
 		"color:$s-text accent-color:$s-accent scrollbar-width:thin scrollbar-color: $s-faint transparent;",
-	// Subtle single-colour gradient sheen, painted on every surface (and the page).
-	".s-s, body": SURFACE_SHEEN,
-	".s-s": "r:$s-radius",
+	// Subtle single-colour gradient sheen, painted on every surface (the page
+	// gets its own, up in the reset).
+	".s-s": SURFACE_SHEEN + " r:$s-radius",
 	// A neutral surface owns a hairline border, so a card reads as a card without
 	// any component help. `:where()` keeps it zero-specificity, so a bar that wants
 	// only a divider overrides it with a single plain rule.