Z-index escalation: unbounded counter exceeds modals and menus

[gfazioli]

Description

When using Window or Window.Group, the z-index counter increments unboundedly on every bringToFront call. In long-running applications or with frequent window interactions, the z-index eventually exceeds modal and menu z-indexes, breaking the expected stacking order.

Root Cause

• WindowGroup.tsx (lines 123-127): bringToFront increments zIndexCounterRef without any cap
• use-window-state.ts (lines 313-321): same issue for non-group windows with global portalZIndex/containerZIndex counters
• Starting values: 200 for portal, 1 for container — no maximum defined

Expected Behavior

Z-index should stay within reasonable bounds and not exceed system-level z-indexes (modals, menus, tooltips). Options:

• Cap the z-index at a configurable maximum
• Normalize/compact z-indexes periodically (reassign 1..N based on current stacking order)
• Provide a maxZIndex or zIndexStrategy prop on Window.Group

Reproduction

1. Create a Window.Group with multiple windows
2. Click on windows repeatedly to bring them to front
3. Open a Mantine Modal — the windows will eventually render above the modal

Reported by

Discord user 0x7d8 (05/04/2026)

[gfazioli]

Fixed in v3.1.0 (merged via #25).

Three new props coordinate z-index behavior:

• zIndexStrategy on Window.Group — 'increment' (default, legacy) or 'normalize' for compact derived z-indexes that never exceed initialZIndex + stack.length
• initialZIndex / maxZIndex on both Window.Group and stand-alone Window — when the 'increment' counter would exceed maxZIndex, it wraps back to initialZIndex

Recommended setup when coexisting with Mantine modals/menus:

```tsx
<Window.Group zIndexStrategy="normalize" initialZIndex={100} maxZIndex={199}>
{/* windows */}
</Window.Group>
```

The module-level counters for stand-alone Window instances are now also bounded via maxZIndex, and the counter is seeded up to initialZIndex so bringToFront can never move a window backward.

Details in the Upgrade guide and the new Z-index Management docs section. Thanks @0x7d8 for the report!