windowmaker-wl/MULTI_MONITOR_IMPLEMENTATION_PLAN.md

WindowMaker Multi-Monitor Implementation Plan

Purpose

Implement multi-monitor support in a way that another coding agent can execute with minimal guesswork.

This plan is written for the current wmaker tree and assumes:

• X11 and Wayland backends both remain supported
• shared policy code should continue to use the existing head abstraction
• the initial goal is correct multi-monitor geometry and behavior, not a redesign of workspaces

Scope

In scope

• Populate WScreen.heads[], head_count, and primary_head correctly on both backends
• Make Wayland support multiple outputs instead of only one
• Recompute monitor geometry on output changes
• Keep placement, maximize, fullscreen, icons, dock reservations, and menus head-aware
• Handle output hotplug without leaving windows off-screen
• Preserve existing single-monitor behavior

Out of scope for phase 1

• Per-monitor workspaces
• Per-monitor dock/clip instances
• Full mixed-DPI polish beyond basic correctness

---

Existing architecture to preserve

Shared abstraction

The core already has a backend-neutral monitor/head abstraction.

Relevant files:

• src/screen.h
• src/xinerama.h
• src/xinerama.c

Important fields in WScreen:

• heads
• head_count
• primary_head
• usableArea
• totalUsableArea

Important helper APIs:

• wGetHeadForRect
• wGetHeadForWindow
• wGetHeadRelativeToCurrentHead
• wGetHeadForPoint
• wGetHeadForPointerLocation
• wGetRectForHead
• wGetUsableAreaForHead
• wGetPointToCenterRectInHead

Existing backend support

X11

• Monitor enumeration already exists in:
  • src/backend/x11/x11_monitor.c
• Uses Xinerama with RandR screen-change subscriptions

Wayland

• Output layout support already exists via wlroots:
  • src/backend/wayland/wl_backend.c
  • src/backend/wayland/wl_output.c
  • src/backend/wayland/wl_screen.c
• Current limitation:
  • wl_screen.c populates only heads[0]
  • some Wayland code assumes usableArea[0]

---

Non-goals and policy choices

Workspace policy

Do not implement per-monitor workspaces in this effort.

Use this policy instead:

• a workspace still spans the full virtual desktop
• placement/maximize/focus/icon logic remains head-aware within that workspace

This keeps the patch set tractable and aligns with the current helper model.

Dock / Clip policy

For now:

• keep one logical Dock and one logical Clip model
• make their geometry reservations and placement logic head-aware

Do not introduce per-head docks in this plan.

---

Canonical monitor contract

Before changing behavior, normalize the meaning of heads[].

Required invariants

1. scr->heads contains monitor rectangles in global root coordinates.
2. scr->head_count >= 1 after screen initialization succeeds.
3. scr->primary_head is always a valid index when head_count > 0.
4. scr->scr_width / scr->scr_height represent the bounding box of the full virtual desktop.
5. wGetRectForHead(scr, i) must always return a valid monitor rectangle for 0 <= i < head_count.
6. Single-monitor mode should still behave correctly.

Preferred normalization

Use one explicit head even in single-monitor mode.

That means avoiding the old pattern where head_count == 0 implies fallback-to-single-head behavior.

If changing all callers at once is too risky, do this in two steps:

1. preserve compatibility in helpers
2. gradually move callers to assume head_count >= 1

---

Execution plan

Phase 1 — Audit and normalize head initialization

Goal

Make head data reliable and backend-neutral before extending Wayland.

Files

• src/screen.h
• src/xinerama.h
• src/xinerama.c
• src/screen.c
• src/backend/x11/x11_monitor.c

Tasks

1. Audit all places that read:
   • scr->heads
   • scr->head_count
   • scr->primary_head
2. Decide whether to enforce head_count >= 1 immediately or via compatibility layer.
3. Ensure the X11 path populates a valid single fallback head when Xinerama is inactive.
4. Ensure head arrays are allocated/freed consistently.
5. Add comments documenting the head contract.

Acceptance criteria

• X11 single-monitor behavior is unchanged.
• There is a clear contract for head_count, heads, and primary_head.
• Helper functions behave correctly with one or many heads.

---

Phase 2 — Implement Wayland monitor enumeration

Goal

Populate all heads from wlr_output_layout, not just one.

Files

• src/backend/wayland/wl_screen.c
• src/backend/wayland/wl_output.c
• src/backend/wayland/wl_backend.c
• src/backend/backend_types.h

Tasks

1. Audit the Wayland global state for available outputs and layout access.
2. In wl_screen_open() or the appropriate geometry refresh path:
   • enumerate all active outputs
   • query each output's box via wlr_output_layout_get_box
   • build a WHeadGeometry[]
3. Set:
   • scr->heads
   • scr->head_count
   • scr->primary_head
4. Set scr->scr_width and scr->scr_height from the union of all head rectangles, not from a single output.
5. Preserve deterministic ordering of heads.
   • Recommended: sort by (x, y) or preserve wlroots layout iteration order if stable.
6. Choose primary head policy.
   • Recommended initial policy: first active output or currently selected backend primary output.

Acceptance criteria

• On Wayland with two outputs, scr->head_count == 2.
• wGetRectForHead() returns both outputs with correct geometry.
• scr->scr_width / scr->scr_height reflect the virtual desktop bounds.

Notes for the implementing agent

• Keep this backend-only.
• Do not add special placement logic here.
• Just make monitor geometry correct and complete.

---

Phase 3 — Add dynamic output refresh / hotplug support

Goal

Rebuild monitor geometry whenever outputs change.

Files

• src/backend/wayland/wl_output.c
• src/backend/wayland/wl_screen.c
• src/screen.c
• optionally src/window.c, src/dock.c

Tasks

1. Identify Wayland output lifecycle hooks:
   • new output
   • destroyed/removed output
   • layout or mode change
2. Add a shared helper to rebuild screen head data.
   • Example helper name: wl_screen_refresh_heads(scr)
3. Recompute after each relevant event:
   • heads
   • virtual bounds
   • usable areas
4. If an output disappears, repair windows/icons that now lie outside all heads.

Suggested repair policy

For each affected window:

1. find nearest surviving head
2. preserve relative position when possible
3. clamp inside that head if necessary
4. fall back to centering in primary_head

For icons/appicons:

• do the same, but prefer the head they touched before removal

Acceptance criteria

• Plugging/unplugging outputs does not leave windows permanently off-screen.
• Head helpers reflect the new output topology immediately.

---

Phase 4 — Make usable-area and reservations per-head

Goal

Ensure placement/maximize respects per-head reserved areas.

Files

• src/xinerama.c
• src/screen.c
• src/dock.c
• src/backend/wayland/wl_dock.c

Known problem to fix

Wayland dock code currently assumes scr->usableArea[0] in places.

Tasks

1. Audit all reads/writes of:
   • scr->usableArea
   • scr->totalUsableArea
   • scr->reservedAreas
2. Ensure these arrays are sized for all heads.
3. Ensure dock/clip reservations affect the correct head.
4. When monitor geometry changes, recompute all per-head usable areas.
5. Remove hardcoded [0] assumptions.

Acceptance criteria

• Docks and clips reserve space only on the relevant head.
• Maximize avoids reserved space on the current head.
• Single-monitor behavior remains unchanged.

---

Phase 5 — Audit all head-aware placement and movement paths

Goal

Make all geometry-sensitive actions consistent across monitors.

Files to audit

• src/placement.c
• src/window.c
• src/actions.c
• src/cycling.c
• src/rootmenu.c
• src/dialog.c
• src/dock.c

Tasks

Audit and fix the following behaviors:

New window placement

• New windows should open on:
  • the pointer head, or
  • the owner/transient head, or
  • the current head policy already used by helpers

Restore/session placement

• Restored geometry should be clamped or translated to a valid head.

Maximize/fullscreen

• Maximize should apply to the window's current head unless multi-head fullscreen is explicitly requested.
• Existing fullscreen-monitor helpers in actions.c should keep working.

Menus/dialogs/transients

• Menus should open on the head that contains the invocation point.
• Transients should prefer the owner head.
• Dialog centering should use the correct head.

Icons / miniwindows

• Icon placement should remain on the window's head.
• Auto-arrange should consider all heads, not just head 0.

Acceptance criteria

• Placement/maximize/fullscreen/menus/transients/icons all behave correctly on two monitors.

---

Phase 6 — Add explicit monitor navigation commands

Goal

Expose useful multi-monitor actions to users.

Files

• src/actions.c
• src/defaults.c
• WPrefs.app/KeyboardShortcuts.c
• possibly menu/defaults docs

Tasks

1. Audit existing actions using:
   • wGetHeadRelativeToCurrentHead
   • wGetHeadForWindow
2. Finish or add commands such as:
   • move window to next monitor
   • move window to previous monitor
   • move focus to next monitor
   • maximize on current monitor
3. Expose them through defaults and WPrefs if not already exposed.

Acceptance criteria

• A user can move windows between monitors with shortcuts.
• The actions behave correctly on X11 and Wayland.

---

Phase 7 — Mixed scale / DPI follow-up (optional but recommended)

Goal

Avoid rendering problems on mixed-scale Wayland outputs.

Files

• src/backend/wayland/wl_output.c
• src/backend/wayland/wl_screen.c
• WINGs font/render paths

Tasks

1. Track output scale per output/head.
2. Set output scale in wlroots where appropriate.
3. Feed DPI/scale into font/layout code.
4. Validate titlebars, menus, icons, screenshots, and WINGs rendering.

Acceptance criteria

• Multi-output works correctly even when outputs have different scales.

---

Concrete code audit checklist

Use this as a literal checklist while implementing.

Shared monitor/head code

• src/xinerama.c
• src/xinerama.h
• src/screen.c
• src/screen.h

X11 backend

• src/backend/x11/x11_monitor.c

Wayland backend

• src/backend/wayland/wl_backend.c
• src/backend/wayland/wl_output.c
• src/backend/wayland/wl_screen.c
• src/backend/wayland/wl_dock.c

Placement/window policy

• src/placement.c
• src/window.c
• src/actions.c
• src/cycling.c
• src/rootmenu.c
• src/dialog.c
• src/dock.c

User-facing configuration

• src/defaults.c
• WPrefs.app/KeyboardShortcuts.c
• docs / release notes

---

Suggested implementation order for an agent

If working incrementally, use this order:

1. Normalize head contract
2. Enumerate all Wayland outputs into heads[]
3. Set virtual desktop bounds correctly
4. Recompute heads on hotplug / output change
5. Fix per-head usable area and dock reservations
6. Audit maximize/placement/fullscreen
7. Audit menus/transients/icons
8. Add monitor-navigation actions
9. Do scale/DPI follow-up

Do not start with user-facing shortcuts or DPI. Start with geometry correctness.

---

Test matrix

X11 tests

• single monitor
• dual monitor horizontal
• dual monitor vertical
• mixed resolutions
• RandR hotplug/unplug
• maximize on each head
• fullscreen on each head
• menu placement
• dialog placement
• icon placement

Wayland tests

Use nested mode if needed.

Suggested setup:

• WMAKER_WAYLAND_NESTED=1
• adjust outputs with wlr-randr

Run:

• single output
• two outputs horizontal
• two outputs vertical
• asymmetric offset layout
• output removal with windows present
• output addition after startup
• maximize/fullscreen correctness
• dock/clip reservation correctness
• pointer-head placement correctness
• WINGs app placement correctness
• XWayland client placement correctness

---

Debugging guidance for the implementing agent

When behavior is wrong, log these values first:

• scr->head_count
• all scr->heads[i]
• scr->primary_head
• scr->scr_width, scr->scr_height
• result of wGetHeadForWindow() for the affected window
• result of wGetHeadForPointerLocation() during placement
• per-head usableArea and totalUsableArea

For Wayland output changes, log:

• output add/remove
• output layout box for each output
• geometry refresh entry/exit
• window migration decisions on output removal

---

Definition of done

This effort is complete when all of the following are true:

• heads[] is correct on X11 and Wayland
• Wayland supports more than one output
• output hotplug updates geometry correctly
• windows never remain stranded off-screen after output removal
• maximize/fullscreen/placement/icons/menus are head-aware
• dock/clip reservations are per-head
• single-monitor behavior is unchanged

---

Minimal deliverable if time is limited

If this must be split across multiple PRs, the minimum useful first PR is:

1. normalize monitor contract
2. populate all Wayland heads
3. set correct virtual desktop bounds
4. fix obvious usableArea[0] assumptions

That alone provides the base needed for all follow-up work.