@celestia-island/hikari 0.40.24 → 0.40.26

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@celestia-island/hikari",
-  "version": "0.40.24",
+  "version": "0.40.26",
   "private": false,
   "type": "module",
   "description": "Hikari Vue 3 component library — production-grade UI components based on shittim-chest design system",

package/src/components/HkAffixPicker.scss

@@ -179,6 +179,16 @@
   max-width: min(19rem, calc(100vw - 2rem));
 }
 
+/* Mobile sheet context (#424 pattern): inside the full-width select sheet
+ * the popup's designed measure becomes a centered cap instead of a
+ * left-glued clamp — the list reads as one designed block inside the
+ * viewport-wide sheet rather than hugging its left edge. */
+.hk-select-sheet-panel .hk-affix-scroll {
+  max-width: min(19rem, 100%);
+  margin-inline: auto;
+  width: 100%;
+}
+
 .hk-affix-list {
   display: flex;
   flex-direction: column;

package/src/components/HkAffixPicker.sheetcap.test.ts

@@ -0,0 +1,27 @@
+/**
+ * Source contract for the affix picker's measure inside the mobile select
+ * sheet (2026-09-08 scan wave 2, finding F2 — #424 pattern).
+ *
+ * The picker renders on phones inside the full-width `.hk-select-sheet-panel`;
+ * the base 19rem (304px) cap left-glued with ~92px dead space right. Pinned
+ * here so the sheet-context centering rule cannot be dropped in a refactor:
+ * the designed measure stays as a cap but the list reads as one centered
+ * block inside the viewport-wide sheet.
+ */
+import { describe, expect, it } from "vitest";
+import { readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const here = dirname(fileURLToPath(import.meta.url));
+const src = readFileSync(join(here, "HkAffixPicker.scss"), "utf-8");
+
+describe("HkAffixPicker mobile sheet measure contract", () => {
+  it("caps and centers the list inside the full-width select sheet", () => {
+    const block =
+      src.match(/\.hk-select-sheet-panel \.hk-affix-scroll\s*{[^}]*}/)?.[0] ??
+      "";
+    expect(block).toContain("max-width: min(19rem, 100%)");
+    expect(block).toContain("margin-inline: auto");
+  });
+});

package/src/components/HkButton.scss

@@ -12,7 +12,15 @@
   border: 1px solid transparent;
   border-radius: var(--radius-sm);
   cursor: pointer;
-  transition: background-color, border-color, color, box-shadow, opacity, transform, filter var(--duration-normal) var(--ease-standard);
+  /* Longhand on purpose: the former comma-separated shorthand
+   * `transition: background-color, ..., filter var(--duration-normal) ...`
+   * declares one transition PER property where only the LAST carries the
+   * duration — every property but `filter` animated at 0s and hover states
+   * snapped (host overrides kept patching over it). One property LIST with
+   * one duration/easing animates them all. */
+  transition-property: background-color, border-color, color, box-shadow, opacity, transform, filter;
+  transition-duration: var(--duration-normal);
+  transition-timing-function: var(--ease-standard);
   white-space: nowrap;
   user-select: none;
   outline: none;

package/src/components/HkButton.transition.test.ts

@@ -0,0 +1,39 @@
+/**
+ * Source contract for the HkButton transition declaration (2026-09-08 scan
+ * wave 2, finding F5).
+ *
+ * The former comma-separated shorthand
+ * `transition: background-color, ..., filter var(--duration-normal) ...`
+ * declared one transition PER property where only the LAST carried the
+ * duration/easing — every property but `filter` animated at 0s and hover
+ * color/border/background snapped instead of fading (hosts kept patching
+ * over it; chest's deleted .hk-btn-ghost override was one). Pinned here so
+ * the malformed shorthand cannot silently return.
+ */
+import { describe, expect, it } from "vitest";
+import { readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const here = dirname(fileURLToPath(import.meta.url));
+const src = readFileSync(join(here, "HkButton.scss"), "utf-8");
+// Comments stripped before the negative assertion: the explanatory comment
+// intentionally QUOTES the old malformed shorthand, and this contract is
+// about live CSS, not prose.
+const css = src
+  .replace(/\/\*[\s\S]*?\*\//g, "")
+  .replace(/^[ \t]*\/\/.*$/gm, "");
+
+describe("HkButton transition contract", () => {
+  it("declares the transition in longhand with one shared duration/easing", () => {
+    expect(src).toContain(
+      "transition-property: background-color, border-color, color, box-shadow, opacity, transform, filter;"
+    );
+    expect(src).toContain("transition-duration: var(--duration-normal);");
+    expect(src).toContain("transition-timing-function: var(--ease-standard);");
+  });
+
+  it("does not regress to the malformed comma-separated shorthand", () => {
+    expect(css).not.toMatch(/transition:\s*background-color,/);
+  });
+});

package/src/components/HkDrawer.scss

@@ -165,3 +165,58 @@
   border-top: 1px solid var(--hi-color-border, rgba(0, 0, 0, 0.06));
   flex-shrink: 0;
 }
+
+// ------
+// Mobile bottom drawer = the sheet family (2026-09-08 scan wave 2).
+// HkAdaptiveDialog renders its mobile form as a bottom drawer, which
+// made it the ONLY bottom-docked window outside the HkModal / HkPopover /
+// HkSelectPanel sheet family contract: glued to `bottom: 0` (hosts lifting
+// --hk-sheet-bottom-gap saw no effect), capped by the inline `size` 70vh
+// with no top-inset reservation (a tall dialog covered the secondary-window
+// breadcrumb strip), 8px corners against the family's 12px, a footer that
+// ignored the home-bar safe area, and sm/md footer buttons without the
+// family's 44px touch lift. Same geometry, same tokens, one family.
+// ------
+@media (max-width: 767px) {
+  .hk-drawer-bottom {
+    bottom: var(--hk-sheet-bottom-gap, 0px);
+    border-radius: var(--hk-modal-radius, var(--hi-radius-lg, 12px))
+                   var(--hk-modal-radius, var(--hi-radius-lg, 12px))
+                   0 0;
+    // The inline maxHeight from the `size` prop must lose to the family cap
+    // (plain-vh fallback first for dvh-less engines, then dvh) — same
+    // inline-beating !important pattern as HkModal's mobile max-width.
+    max-height: calc(
+      100vh - var(--hk-sheet-top-inset, 4.25rem) - var(--hk-sheet-bottom-gap, 0px)
+    ) !important;
+    max-height: calc(
+      100dvh - var(--hk-sheet-top-inset, 4.25rem) - var(--hk-sheet-bottom-gap, 0px)
+    ) !important;
+  }
+
+  // Scoped to BOTTOM drawers only: side drawers (admin panels etc.) keep
+  // their desktop footer contract on phones — the sheet family is the
+  // bottom-docked form factor. Three-value padding keeps the axes right:
+  // the --hk-drawer-footer-padding hook owns the TOP, 1rem the sides, and
+  // the home-bar safe area lands on the BOTTOM where it belongs (a 2-value
+  // form would put the safe-area calc on the horizontal axis — and for
+  // hosts that zero the var it would strip the bottom protection entirely,
+  // the exact opposite of the intent).
+  .hk-drawer-bottom .hk-drawer-footer {
+    // Family baseline: home-bar safe area stacked on the base inset (same
+    // stacking as HkModal's mobile footer), on top of the existing
+    // --hk-drawer-footer-padding hook for menu-panel hosts.
+    padding: var(--hk-drawer-footer-padding, 0.625rem 1rem) 1rem
+      calc(0.375rem + var(--hk-sheet-footer-gap, 0.5rem) + env(safe-area-inset-bottom, 0px));
+
+    // Footer actions are the drawer's primary touch targets on phones:
+    // lift sm/md buttons to the 44px class, exactly like HkModal's mobile
+    // footer (padding/min-height only; font-size stays --text-base).
+    .hk-btn-sm,
+    .hk-btn-md {
+      min-height: 2.75rem;
+      padding: var(--space-8) var(--space-16);
+      font-size: var(--text-base);
+    }
+  }
+}

package/src/components/HkDrawer.sheetfamily.test.ts

@@ -0,0 +1,87 @@
+/**
+ * Source contract for the mobile bottom-drawer sheet family membership
+ * (2026-09-08 scan wave 2, finding F1).
+ *
+ * HkAdaptiveDialog renders its mobile form as a bottom drawer, which made
+ * it the ONLY bottom-docked window outside the HkModal / HkPopover /
+ * HkSelectPanel sheet family contract. Pinned here so a refactor cannot
+ * silently regress to the pre-family geometry:
+ *   - docks on the shared --hk-sheet-bottom-gap hook (was hard `bottom: 0`)
+ *   - capped by the family formula (top inset + bottom gap), NOT the inline
+ *     `size` 70vh — the inline maxHeight must lose via !important (same
+ *     inline-beating pattern as HkModal's mobile `max-width: 100%
+ *     !important`), with the plain-vh fallback ahead of the dvh twin
+ *   - 12px family corners (was 8px)
+ *   - footer stacks the home-bar safe area on the BOTTOM axis (3-value
+ *     padding: hook top / 1rem sides / safe-area bottom — a 2-value form
+ *     would put the safe-area calc on the horizontal axis and strip the
+ *     bottom protection for hosts that zero the hook) and is scoped to
+ *     BOTTOM drawers only (side drawers keep their desktop footer
+ *     contract on phones); sm/md buttons lift to the 44px class, like
+ *     HkModal's mobile footer
+ */
+import { beforeAll, describe, expect, it } from "vitest";
+import { readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const here = dirname(fileURLToPath(import.meta.url));
+const src = readFileSync(join(here, "HkDrawer.scss"), "utf-8");
+
+describe("HkDrawer mobile bottom sheet-family contract", () => {
+  let media = "";
+  let drawer = "";
+  let footer = "";
+  beforeAll(() => {
+    media = src.slice(src.indexOf("@media (max-width: 767px)"));
+    drawer = media.match(/\.hk-drawer-bottom\s*{[^}]*}/)?.[0] ?? "";
+    footer = media.match(/\.hk-drawer-bottom \.hk-drawer-footer\s*{[\s\S]*?^  }/m)?.[0] ?? "";
+  });
+
+  it("docks the bottom drawer on the shared --hk-sheet-bottom-gap hook", () => {
+    expect(drawer).toContain("bottom: var(--hk-sheet-bottom-gap");
+  });
+
+  it("caps the sheet with the family top-inset formula in both vh and dvh", () => {
+    expect(drawer).toContain("100vh - var(--hk-sheet-top-inset");
+    expect(drawer).toContain("100dvh - var(--hk-sheet-top-inset");
+    // dvh-less engines (older Android WebView / Tauri) drop the whole dvh
+    // calc — the plain-vh fallback must stay ahead of it.
+    expect(drawer.indexOf("100vh - var(")).toBeLessThan(
+      drawer.indexOf("100dvh - var(")
+    );
+  });
+
+  it("beats the inline `size` maxHeight with !important on both caps", () => {
+    // HkDrawer applies `maxHeight: props.size` (default 70vh) inline for
+    // horizontal drawers — inline beats stylesheet, so the family cap must
+    // carry !important on the vh fallback AND the dvh twin.
+    expect(drawer.match(/\) !important;/g)).toHaveLength(2);
+  });
+
+  it("adopts the 12px family corner radius", () => {
+    expect(drawer).toContain("border-radius: var(--hk-modal-radius, var(--hi-radius-lg, 12px))");
+  });
+
+  it("stacks the home-bar safe area on the mobile footer's BOTTOM axis", () => {
+    expect(footer).toContain("env(safe-area-inset-bottom");
+    expect(footer).toContain("--hk-sheet-footer-gap");
+    // 3-value padding: hook top / 1rem sides / safe-area calc bottom. The
+    // safe-area calc must be the THIRD value, not the second (2-value form
+    // puts it on the horizontal axis and zeroes the bottom for hook=0 hosts).
+    expect(footer).toMatch(
+      /padding: var\(--hk-drawer-footer-padding,[^)]*\) 1rem\s*\n?\s*calc\(0\.375rem \+ var\(--hk-sheet-footer-gap/
+    );
+  });
+
+  it("scopes the mobile footer rules to bottom drawers only", () => {
+    // Side drawers (admin panels) keep the desktop footer contract on
+    // phones — the media block must not carry an unscoped .hk-drawer-footer.
+    expect(media).not.toMatch(/@media[\s\S]*?\n  \.hk-drawer-footer\s*{/);
+  });
+
+  it("lifts sm/md footer buttons to the 44px touch-target class", () => {
+    expect(footer).toMatch(/\.hk-btn-sm,\s*\n\s*\.hk-btn-md/);
+    expect(footer).toContain("min-height: 2.75rem");
+  });
+});

package/src/components/HkImageLightbox.scss

@@ -102,9 +102,16 @@
     top: 0;
     bottom: auto;
     left: 0;
-    width: 100vw;
+    // Full-bleed width from the containing block, NOT 100vw and NOT the
+    // desktop rule's inherited `min(96vw, 80rem)`: that unconditional
+    // same-specificity width would persist into mobile and, over-constrained
+    // against the inherited `left: 0; right: 0` pair, drop `right` under
+    // LTR — a persistent ~4vw dead strip on the right edge (the exact gap
+    // class this wave hunts). 100vw itself also measures the ICB including
+    // classic scrollbar gutters.
     // Plain-vh fallback first for dvh-less engines (older Android
     // WebView / Tauri), then the dynamic-viewport height.
+    width: 100%;
     height: 100vh;
     height: 100dvh;
     max-height: none;

package/src/components/HkImageLightbox.width.test.ts

@@ -0,0 +1,48 @@
+/**
+ * Source contract for the mobile lightbox horizontal sizing (2026-09-08
+ * scan wave 2, finding F3 + round-3 fix).
+ *
+ * The fullscreen mobile block used to declare `width: 100vw`, but 100vw
+ * measures the ICB including classic scrollbar gutters — combined with the
+ * inherited `left: 0; right: 0` docking it over-constrained the box (LTR
+ * dropped `right`) and clipped the right edge under a classic scrollbar.
+ * Deleting the width alone was NOT enough (round-3 adversarial catch):
+ * the unconditional desktop rule `width: min(96vw, 80rem)` (same selector,
+ * same specificity) then persisted into mobile and, over-constrained
+ * against left/right, dropped `right` — a persistent ~4vw dead strip on
+ * the right edge. The mobile block must declare its OWN width: 100% so
+ * the containing block (not the viewport unit, not the desktop measure)
+ * owns the full-bleed. Pinned here so neither regression can return.
+ */
+import { describe, expect, it } from "vitest";
+import { readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const here = dirname(fileURLToPath(import.meta.url));
+const src = readFileSync(join(here, "HkImageLightbox.scss"), "utf-8");
+
+describe("HkImageLightbox mobile width contract", () => {
+  let mobile = "";
+  it("declares its own full-bleed width in the mobile block", () => {
+    mobile = src.slice(src.indexOf("@media (max-width: 767px)"));
+    const panel = mobile.match(/\.hk-modal-content\.hk-image-lightbox\s*{[^}]*}/)?.[0] ?? "";
+    expect(panel).toContain("left: 0;");
+    expect(panel).toContain("width: 100%;");
+  });
+
+  it("keeps 100vw sizing out (scrollbar-gutter divergence)", () => {
+    expect(mobile).not.toContain("width: 100vw");
+  });
+
+  it("keeps the desktop 96vw measure out of the mobile block", () => {
+    // The unconditional desktop rule keeps min(96vw, 80rem) — only the
+    // mobile panel block's own width: 100% stops it from leaking in.
+    // Comments are stripped first: the rationale text legitimately quotes
+    // the desktop measure, and only live declarations are under contract.
+    const panel = (mobile.match(/\.hk-modal-content\.hk-image-lightbox\s*{[^}]*}/)?.[0] ?? "")
+      .replace(/\/\*[\s\S]*?\*\//g, "")
+      .replace(/^\s*\/\/.*$/gm, "");
+    expect(panel).not.toContain("96vw");
+  });
+});

package/src/components/HkModal.scss

@@ -393,8 +393,15 @@
     // sits off the very bottom edge (chest asked for a visibly narrower
     // gap than body bottom + safe area on phones). Safe area is added ON
     // TOP of the gap so home-bar devices never lose tappable chrome.
-    padding: 0.625rem 1rem
-      calc(0.375rem + var(--hk-sheet-footer-gap, 0.5rem) + env(safe-area-inset-bottom, 0px));
+    // --hk-modal-footer-padding-mobile is the host-tunable mobile footer
+    // inset: a host with edge-to-edge footer content (chest's report
+    // reply bar) sets it to 0 instead of repainting the rule and
+    // duplicating the formula — desktop keeps --hk-modal-padding-footer.
+    padding: var(
+      --hk-modal-footer-padding-mobile,
+      0.625rem 1rem
+        calc(0.375rem + var(--hk-sheet-footer-gap, 0.5rem) + env(safe-area-inset-bottom, 0px))
+    );
 
     // Footer actions are the sheet's primary touch targets: lift sm/md
     // buttons one size up to the 44px class regardless of the caller's

package/src/components/HkPopover.scss

@@ -132,6 +132,16 @@
         var(--hk-sheet-bottom-gap, 0px)
     )
   );
+  /* Dynamic-viewport pairing (HkModal parity): the dvh twin follows the
+   * vh cap so a maxed sheet cannot extend under the URL bar on
+   * dynamic-toolbar browsers. */
+  max-height: min(
+    72vh,
+    calc(
+      100dvh - var(--hk-sheet-top-inset, 4.25rem) -
+        var(--hk-sheet-bottom-gap, 0px)
+    )
+  );
   display: flex;
   flex-direction: column;
   overflow-y: auto;

package/src/components/HkSelect.scss

@@ -271,6 +271,16 @@
         var(--hk-sheet-bottom-gap, 0px)
     )
   );
+  /* Dynamic-viewport pairing (HkModal parity): the dvh twin follows the
+   * vh cap so a maxed sheet cannot extend under the URL bar on
+   * dynamic-toolbar browsers. */
+  max-height: min(
+    72vh,
+    calc(
+      100dvh - var(--hk-sheet-top-inset, 4.25rem) -
+        var(--hk-sheet-bottom-gap, 0px)
+    )
+  );
   background: rgb(var(--color-surface));
   border-radius: var(--hk-modal-radius, var(--hi-radius-lg, 12px))
                  var(--hk-modal-radius, var(--hi-radius-lg, 12px))

package/src/runtime/usePopupManager.test.ts

@@ -198,3 +198,83 @@ describe("usePopupManager blocking flag (breadcrumb levels)", () => {
     }
   });
 });
+
+describe("usePopupManager window stack (blocking sheets reband)", () => {
+  it("stacks a blocking sheet with windows in open order — a window opened from inside the sheet paints above it", () => {
+    // The chest mobile regression: the theme menu docks as a bottom
+    // sheet, its row's edit affordance opens a MODAL — kind bands put
+    // the sheet (dropdown, 2000) above the modal (1000) and the editor
+    // rendered BEHIND its own opener. A blocking sheet is a window: it
+    // must share the window band and lose to windows pushed after it.
+    const m = freshManager();
+    const sheet = m.register("dropdown", false, "Themes", true);
+    expect(sheet.zIndex).toBe(POPUP_Z_BANDS.modal);
+
+    const editor = m.register("modal", true, "Edit theme");
+    expect(editor.zIndex).toBe(sheet.zIndex + POPUP_Z_STEP);
+
+    // A sheet opened from INSIDE that modal pushes on top of it.
+    const innerSheet = m.register("dropdown", false, "Picker", true);
+    expect(innerSheet.zIndex).toBe(editor.zIndex + POPUP_Z_STEP);
+  });
+
+  it("keeps an ANCHORED dropdown above the whole window stack, blocking sheets included", () => {
+    // The in-modal select flow: anchored panels stay in the dropdown
+    // band so they paint above whichever window (modal OR blocking
+    // sheet) contains them.
+    const m = freshManager();
+    const sheet = m.register("dropdown", false, "Themes", true);
+    const modal = m.register("modal", true, "Edit");
+    const panel = m.register("dropdown", false);
+    expect(panel.zIndex).toBe(POPUP_Z_BANDS.dropdown);
+    expect(panel.zIndex).toBeGreaterThan(sheet.zIndex);
+    expect(panel.zIndex).toBeGreaterThan(modal.zIndex);
+  });
+
+  it("reclaims window-band slots across mixed windows and sheets", () => {
+    const m = freshManager();
+    const sheet = m.register("dropdown", false, "Themes", true);
+    const modal = m.register("modal", true, "Edit");
+    expect(modal.zIndex).toBe(sheet.zIndex + POPUP_Z_STEP);
+
+    m.unregister(modal.id);
+    const drawer = m.register("drawer", true, "Details");
+    // The drawer reclaims the modal's slot, not a third one.
+    expect(drawer.zIndex).toBe(modal.zIndex);
+  });
+
+  it("setBlocking promotion pushes onto the top of the window band, demotion returns to the anchored band", () => {
+    const m = freshManager();
+    const modal = m.register("modal", true, "Edit");
+    // Anchored first: above every window while non-blocking.
+    const popup = m.register("dropdown", false, "Menu");
+    expect(popup.zIndex).toBe(POPUP_Z_BANDS.dropdown);
+
+    // Viewport crosses the mobile breakpoint: the popover docks as a
+    // sheet — becoming a window is a PUSH, so it lands above the modal.
+    m.setBlocking(popup.id, true);
+    expect(m.registry.value.get(popup.id)!.zIndex).toBe(modal.zIndex + POPUP_Z_STEP);
+
+    // Back to desktop: an anchored attachment again — top of the
+    // anchored band, above the whole window stack.
+    m.setBlocking(popup.id, false);
+    const entry = m.registry.value.get(popup.id)!;
+    expect(entry.zIndex).toBe(POPUP_Z_BANDS.dropdown);
+    expect(entry.zIndex).toBeGreaterThan(modal.zIndex);
+  });
+
+  it("orders the breadcrumb window stack by push order (sheet → editor)", () => {
+    // HkModalBreadcrumb sorts by zIndex; with blocking sheets sharing
+    // the window band, the strip reads in navigation order: the sheet
+    // that opened the editor, then the editor as the current level.
+    const m = freshManager();
+    const sheet = m.register("dropdown", false, "Themes", true);
+    const editor = m.register("modal", true, "Edit theme");
+    const levels = [...m.registry.value.values()]
+      .filter((e) => e.kind === "modal" || e.kind === "drawer" || e.blocking)
+      .sort((a, b) => a.zIndex - b.zIndex)
+      .map((e) => e.title);
+    expect(levels).toEqual(["Themes", "Edit theme"]);
+    expect(editor.zIndex).toBeGreaterThan(sheet.zIndex);
+  });
+});

package/src/runtime/usePopupManager.ts

@@ -5,23 +5,28 @@ export type PopupKind = "dropdown" | "modal" | "drawer" | "tooltip" | "toast";
 /**
  * Kind-priority z bands — the single source of truth for popup stacking.
  *
- * Every registered popup lands in its kind's band, so layering is decided
- * by WHAT a surface is, never by WHEN it happened to register. Bands are
- * ordered low → high:
+ * Layering is decided by WHAT a surface IS — window or attachment — never
+ * by WHEN it happened to register:
  *
- *   modal    (1000)  centered dialogs + phone bottom sheets
- *   drawer   (1000)  edge drawers share the overlay band with modals —
- *                    inside the band they stack in open order, so a
- *                    drawer opened over a modal still paints above it
- *   dropdown (2000)  anchor-attached popovers, select panels, menus —
- *                    ABOVE the overlay band on purpose: a select panel
- *                    opened from inside a modal portals to <body> and
- *                    must paint above the modal that contains it (the
- *                    common in-modal form flow). A page-level dropdown
- *                    can only coexist with a modal programmatically (the
- *                    modal overlay intercepts pointers), so the rare
- *                    stale-dropdown-over-modal case is accepted, matching
- *                    Ant Design
+ *   modal    (1000)  the WINDOW band: centered dialogs + phone bottom
+ *   drawer   (1000)  sheets + edge drawers. Anything that BLOCKS the page
+ *                    like a window is a window: modals and drawers by
+ *                    kind, and a dropdown-kind surface while it is docked
+ *                    as a mobile bottom sheet (`blocking`). Within the
+ *                    band surfaces stack purely in open order (push/pop
+ *                    stack semantics), so a window opened FROM inside a
+ *                    sheet always paints above it — the sheet keeps no
+ *                    kind-priority claim over windows opened later.
+ *   dropdown (2000)  ANCHORED popovers, select panels, menus — surfaces
+ *                    attached to an anchor on whatever window is on top,
+ *                    not windows themselves. ABOVE the window band on
+ *                    purpose: a select panel opened from inside a modal
+ *                    portals to <body> and must paint above the modal
+ *                    that contains it (the common in-modal form flow). A
+ *                    page-level anchored dropdown can only coexist with a
+ *                    modal programmatically (the modal overlay intercepts
+ *                    pointers), so the rare stale-dropdown-over-modal case
+ *                    is accepted, matching Ant Design
  *   tooltip  (3000)  transient annotations must stay visible above the
  *                    surfaces they annotate
  *   toast    (4000)  ALWAYS the topmost surface — a toast must never be
@@ -33,8 +38,11 @@ export type PopupKind = "dropdown" | "modal" | "drawer" | "tooltip" | "toast";
  * freed slots are reclaimed automatically because the next z derives from
  * the CURRENT live entries of that band only — no monotonic counter, no
  * cross-band coupling (a persistent toast/tooltip registration can no
- * longer push later modals up the ladder; that ordering bug is what this
- * band scheme replaces). Overlay roots are spaced one Z_STEP apart so each
+ * longer push later modals up the ladder). A dropdown flipping its
+ * blocking flag (anchored popover docking as a sheet, or the reverse)
+ * REBANDS in place: promotion pushes onto the top of the window band
+ * (becoming a window IS a push), demotion lands on the top of the
+ * anchored band. Overlay roots are spaced one Z_STEP apart so each
  * overlay's +1 content/panel layer always has a free slot above its own
  * root and below the next overlay.
  *
@@ -49,6 +57,17 @@ export const POPUP_Z_BANDS: Record<PopupKind, number> = {
   toast: 4000,
 };
 
+/**
+ * The band a popup CURRENTLY stacks in. Dropdown-kind surfaces have two:
+ * the anchored band while attached to an anchor, the WINDOW band
+ * (shared with modals/drawers) while docked as a blocking bottom sheet.
+ * Window kinds always live in the window band.
+ */
+function effectiveBand(kind: PopupKind, blocking: boolean): number {
+  if (kind === "dropdown") return blocking ? POPUP_Z_BANDS.modal : POPUP_Z_BANDS.dropdown;
+  return POPUP_Z_BANDS[kind];
+}
+
 /** In-band stacking step. Even numbers leave the odd slot free for the
  * +1 content/panel layer each overlay puts above its own root. */
 export const POPUP_Z_STEP = 2;
@@ -61,11 +80,15 @@ export interface PopupEntry {
   title?: string;
   /**
    * True while the popup is a blocking window the user "navigates" —
-   * a mobile bottom sheet that rose from a dropdown-kind surface. The
-   * modal-stack breadcrumb lists window kinds (modal/drawer) always and
-   * dropdown kinds only while they block like this; an anchored desktop
-   * popover stays a hidden level. Named surfaces only: a blocking popup
-   * without a title is a naming bug (dev warn at registration).
+   * a mobile bottom sheet that rose from a dropdown-kind surface. This
+   * flag is window-stack MEMBERSHIP: it lists the popup in the
+   * modal-stack breadcrumb AND moves it into the window z band (see
+   * effectiveBand) — a blocking sheet is a window in every sense, so
+   * windows opened from inside it stack above it. Window kinds
+   * (modal/drawer) are windows by kind and always listed; an anchored
+   * desktop popover stays a hidden level. Named surfaces only: a
+   * blocking popup without a title is a naming bug (dev warn at
+   * registration).
    */
   blocking: boolean;
 }
@@ -121,11 +144,14 @@ export function usePopupManager() {
     blocking = false,
   ): PopupHandle {
     const id = uid();
-    const band = POPUP_Z_BANDS[kind];
+    const band = effectiveBand(kind, blocking);
     // Next slot = one step above the highest LIVE entry of the same band.
+    // Band membership follows the entry's CURRENT shape (see
+    // effectiveBand): a blocking sheet scans the window band, so it lands
+    // above every window opened before it.
     let maxSlot = -1;
     for (const entry of registry.value.values()) {
-      if (POPUP_Z_BANDS[entry.kind] !== band) continue;
+      if (effectiveBand(entry.kind, entry.blocking) !== band) continue;
       const slot = (entry.zIndex - band) / POPUP_Z_STEP;
       if (slot > maxSlot) maxSlot = slot;
     }
@@ -151,11 +177,26 @@ export function usePopupManager() {
    * Flip the blocking flag while the popup stays open — a dropdown that
    * docks as a bottom sheet when the viewport crosses the mobile
    * breakpoint becomes a breadcrumb level mid-flight (and back).
+   *
+   * The flip also REBANDS the z: promotion pushes the sheet onto the top
+   * of the window band (becoming a window is a push — it must cover the
+   * page), demotion lands it on the top of the anchored band. The freed
+   * slot in the old band reclaims lazily via the usual max-live-slot
+   * derivation.
    */
   function setBlocking(id: string, blocking: boolean) {
     const entry = registry.value.get(id);
     if (!entry || entry.blocking === blocking) return;
     entry.blocking = blocking;
+    const band = effectiveBand(entry.kind, entry.blocking);
+    let maxSlot = -1;
+    for (const other of registry.value.values()) {
+      if (other === entry) continue;
+      if (effectiveBand(other.kind, other.blocking) !== band) continue;
+      const slot = (other.zIndex - band) / POPUP_Z_STEP;
+      if (slot > maxSlot) maxSlot = slot;
+    }
+    entry.zIndex = band + (maxSlot + 1) * POPUP_Z_STEP;
     registry.value = new Map(registry.value);
     if (blocking) warnUntitled(entry.kind, true, entry.title);
   }