Understand the desktop.
Then design the types.

struct Client {
	char name[256];
	float mina, maxa;
	int x, y, w, h;
	int oldx, oldy, oldw, oldh;
	int basew, baseh, incw, inch, maxw, maxh, minw, minh, hintsvalid;
	int bw, oldbw;
	unsigned int tags;
	int isfixed, isfloating, isurgent, neverfocus, oldstate, isfullscreen;
	Client *next;
	Client *snext;
	Monitor *mon;
	Window win;
};

struct Monitor {
	char ltsymbol[16];
	float mfact;
	int nmaster;
	int num;
	int by;               /* bar geometry */
	int mx, my, mw, mh;   /* screen size */
	int wx, wy, ww, wh;   /* window area  */
	unsigned int seltags;
	unsigned int sellt;
	unsigned int tagset[2];
	int showbar;
	int topbar;
	Client *clients;
	Client *sel;
	Client *stack;
	Monitor *next;
	Window barwin;
	const Layout *lt[2];
};

next and snext are different linked orders. mon is a back pointer. In Rust, stores own the values and typed IDs express these relationships.

DWM rewrite in Rust

The goal is a small X11 window manager with DWM's familiar behavior, implemented in readable, idiomatic Rust. Optimize for understanding ownership and behavior before minimizing line count. This is a rewrite guided by observable behavior, rather than a function-by-function translation.

The local C baseline is now DWM 6.8 in reference/dwm-6.8/, unpacked unchanged from the user-provided download and identified by archive and file checksums. No local AGENTS.md was found. Record any personal patches and configuration separately before implementation. No Rust-specific skill was found among the installed skills; the Rust API Guidelines are the design reference.

1. Scope and compatibility baseline

First release: X11, tagging, tiled/monocle/floating layouts, keyboard and mouse actions, rules, focus, fullscreen, multiple monitors, and a status bar. Preserve relevant ICCCM and EWMH behavior supported by the pinned baseline. Wayland, a plugin framework, runtime configuration reload, and arbitrary DWM patch compatibility are separate projects.

Write a compatibility matrix before coding. Cover startup with existing windows, transient/dialog handling, override-redirect windows, focus history, layout order, current/previous tag views, current/previous layouts, window size hints, fullscreen restoration, urgency, status text, bar clicks, spawning, and clean shutdown. Mark intentional changes explicitly.

DWM tags must remain sets: a client can belong to multiple tags and a monitor can show multiple tags. Do not replace this with one workspace per window. Record rule matching and precedence, geometry rounding, and focus behavior as examples that can become tests.

2. Architecture: one crate, a few explicit boundaries

Start with one Cargo package containing a library for testable policy and a thin executable. Avoid a workspace of tiny crates.

src/
  main.rs          startup, diagnostics, exit handling
  wm.rs            event orchestration and cross-object operations
  model/           clients, monitors, tags, geometry, layouts
  x11/             connection, atoms, properties, protocol requests
  input.rs         bindings, modifier handling, pointer interaction
  config.rs        typed defaults, bindings, rules, validation
  bar.rs           bar content, geometry, hit testing, drawing
  process.rs       spawning and child reaping

The normal path should be easy to follow:

X11 event → handler → policy/state update → X11 requests → flush

Keep X11-generated types near the protocol boundary. Extract typed window metadata before changing policy. Layout calculation should return placements without talking to X11. Introduce a small effects enum only if it makes event ordering and testing clearer; do not build an elaborate command bus.

Begin with a single-threaded synchronous event loop. A pointer drag is explicit interaction state processed by that loop, so window destruction and other events remain handled during a drag.

3. Types and the behavior they own

Prefer methods when a type owns the behavior or invariant. A client may update its fullscreen state, but the manager coordinates resulting monitor layout and X11 requests. Free functions remain appropriate for stateless algorithms without a natural receiver.

Use descriptive names: master_count, master_ratio, selected_client, work_area. Replace the C Arg union and function-pointer bindings with Action variants carrying their actual argument types.

Use enums where alternatives exclude each other. Represent normal placement as tiled or floating and fullscreen as a state carrying the previous placement, geometry and border width. Keep independent facts such as urgency as independent fields. Do not combine unrelated flags into one enormous enum.

Keep fields private where mutation could break an invariant. Use Option<ClientId> for absent focus, rather than a zero identifier. Validate configuration at startup. A rule may have no tag override; a managed client and active view must have a nonempty valid tag set. Model DWM's zero-argument “previous view” operation as a distinct action.

Start with concrete types and exhaustive matches. Introduce a trait only for a real interchangeable behavior or a useful test boundary. A trait for every struct, broad dyn dispatch, or a generic backend threaded through every type would increase reading effort without a demonstrated benefit.

4. Ownership and collections

WindowManager owns the client store, monitor store and selected monitor. Monitors contain client IDs rather than references; clients identify their monitor by ID. Keep layout order and focus history as separate ID vectors, because they serve different behaviors.

Start with a typed ID and standard map plus a window-to-client lookup. Never use unordered map iteration to determine layout or focus. Allocate client IDs independently from reusable X11 window IDs. Add a generational arena only if stale references or complexity justify it.

Maintain these invariants through manager methods:

• Every managed client belongs to exactly one live monitor.
• Monitor orders contain no duplicate or missing client IDs.
• Removing a client removes all membership and focus-history entries.
• The selected client belongs to its monitor and is eligible under the focus policy.
• Removing a monitor migrates its clients before deleting its state.

Avoid self-referential structures, mutable globals, and routine Rc<RefCell<_>>. Resolve borrowing conflicts by splitting fields, narrowing borrow scopes, or collecting IDs before mutation. Copying a small ID or geometry value is reasonable; cloning the entire manager to bypass borrowing is not.

5. X11 and rendering decisions

Use x11rb with its pure-Rust RustConnection as the first backend candidate. Pin the dependency after a small startup/event-loop spike. Check extension availability and provide a single-monitor fallback. Begin with monitor discovery compatible with the chosen DWM baseline; treat RandR hotplug support as an explicit addition if it exceeds that baseline.

For the bar, time-box a rendering spike comparing retaining Xft behind a narrow FFI wrapper with Cairo/Pango rendering uploaded to the X11 bar window. Decide using Unicode rendering, fallback fonts, dependency footprint, and code readability. Do not promise pixel-identical text rendering before this spike. Keep unsafe code, if needed, contained and documented.

Classify errors deliberately: another window manager owning root redirection is a startup failure; a client disappearing during a request is an expected race; a broken X connection ends the session. Surface checked request errors and asynchronous errors. Validate property types, formats and lengths. Do not use blanket error suppression or unwrap() on external input.

Use explicit shutdown for restoring windows and best-effort cleanup. Resource wrappers can use Drop for local cleanup, but shutdown requests that can fail should have an explicit path. Spawn argument vectors without implicit shell interpolation, and reap children.

6. Implementation milestones

The first runnable milestone is startup → manage a terminal → tile it → focus it → close it → exit cleanly. Build that vertical slice before completing every abstraction.

Keep configuration in readable Rust initially: Config::default() plus explicit binding/rule constructors. Recompilation preserves DWM's customization approach. Add a file format only if users need it; keep policy and validation independent of the format.

7. Verification and readability gates

Use pure unit tests for tags, views, rules, fullscreen transitions, geometry and layouts. Add property tests where they catch meaningful invariant failures, such as arbitrary tag toggles or client removal sequences.

Run integration scenarios under Xephyr or Xvfb with small controlled X clients. Compare behavior with the pinned C baseline: window geometry, visibility, focus, stacking and published properties. Compare observable outcomes, not internal structures. Check hidden-window behavior carefully: changing visibility implementation can alter client lifecycle events.

Exercise real terminals, browsers, dialogs and fullscreen applications. Include keyboard mapping changes, lock modifiers, Unicode titles, rapid map/unmap/destroy sequences, negative monitor coordinates and a window disappearing during dragging.

Before accepting each milestone, run cargo fmt --check, appropriate tests and Clippy. Review readability separately: can a reader trace an event to its outcome, find who owns an invariant, and understand a public method without consulting distant global state? Explain protocol quirks in comments; avoid comments that merely restate the code.

Success means the agreed DWM behaviors pass the compatibility matrix, state invariants survive lifecycle races, and policy code can be understood without learning X11 request encoding. Performance should be measured for event handling and layout before adding caching or concurrency.

References

• Upstream DWM implementation
• DWM manual
• Default configuration
• DWM rendering implementation
• x11rb RustConnection
• Rust API Guidelines: checklist
• Rust API Guidelines: type safety

Detailed design and validation

• Types, ownership, and event-flow diagrams.
• Compilable Rust type and transition sketches.
• Regression strategy and C test migration.
• Local C baseline and checksums.

The detailed documents use the downloaded 6.8 source as the reference. The sketches demonstrate policy only; they are not a runnable window manager.

Types and flow, grounded in DWM 6.8

Read alongside ../reference/dwm-6.8/dwm.c and the compilable ../examples/type_sketch.rs. The reference is unchanged. The Rust code is a policy sketch, not the beginning of a runnable WM. Unused-field warnings are expected because protocol integration, constructors and many operations are deliberately absent.

Ownership graph

The ownership diagram describes where values live; cross-object relationships use ID lookups, not Rust references. State has no X connection, so its transitions can be tested directly.

screen includes the full monitor; work_area excludes the bar. Fullscreen uses screen; tiling uses work_area. Rect coordinates are signed because monitors may sit left of the origin. Use wider intermediates for intersection and border arithmetic; convert to X11's wire ranges only at the backend boundary.

Preserve two independent lists from C Client.next and Client.snext: layout order and focus history. New clients are prepended in the baseline. HashMap traversal must never decide either order. monitor_order also makes keyboard monitor traversal deterministic. Fresh internal client IDs prevent accidental confusion with reused X window IDs; remove pending interaction state when a client disappears.

A production State constructor establishes at least one monitor and validates tag sets against one configured mask. The sketch's TagSet construction enforces valid bits, but values created with different TagMask instances can still be mixed: production accepts only the startup configuration's mask and validates configuration/actions at that boundary. This is a runtime invariant, not a claim of compile-time proof.

Behavior belongs where its inputs and invariants live

Do not move every C function into one giant impl WindowManager. Use methods for meaningful receivers and keep plain algorithm helpers when no receiver is natural. Do not make Client::focus() reach into global monitor state or issue X11 requests.

Event and action graph

Reconciliation is a named sequence with explicit ordering, not a magical full-state diff. Map/startup operations may need requests before and after insertion. Retain those phases instead of forcing every lifecycle operation through the same generic pipeline. Release mutable state borrows before protocol I/O; collect small IDs/placements, not clones of the entire state.

An illustrative integration outline (not part of the compiled sketch):

fn handle_action(&mut self, action: Action) -> Result<(), WmError> {
    if let Some(monitor) = self.state.apply_action(action)? {
        self.reconcile_monitor(monitor)?;
    }
    self.backend.flush()?;
    Ok(())
}

The sketch's PolicyError::MissingMonitor must become a structured WmError conversion. Recover an expected client-disappearance race at the lifecycle boundary; do not silently swallow all protocol errors. State and server are not one atomic transaction: partial requests require cleanup or another reconciliation.

Managing a new window

The baseline maprequest queries attributes, ignores override-redirect, then calls manage only for unknown windows. manage performs an ordered mix of metadata, state and protocol work. The Rust implementation should make those phases explicit.

A known managed transient inherits its parent's monitor and tags before ordinary rules; transient/fixed-size behavior affects floating placement. Fullscreen metadata also participates during management. Track these cases as separate tests rather than reducing all metadata to a single is_floating rule.

Rules use substring matches. Matching rules accumulate tag bits, while later matches overwrite floating status and valid monitor choice. An invalid monitor target does not erase an earlier valid choice. No resulting tag bits means use the chosen monitor's active view. An idiomatic rewrite must preserve this order explicitly.

Fullscreen state graph

Use Presentation::Fullscreen { restore: NormalState, geometry: Rect } so saved state exists exactly when needed. Keep urgency and input-focus eligibility separate. Floating layout at monitor level does not mean every client's persistent placement should become floating.

For monitor resizing while fullscreen, update current fullscreen geometry without overwriting the saved normal state. On leave, a tiled client may immediately receive new tiled geometry during arrangement; the saved rectangle is not a promise of its final tiled position.

Layout flow and code quality

The C tile advances offsets using actual HEIGHT(c) after resize, which can apply size hints. Computing all ideal rectangles and constraining them only afterward can produce different placement. Either integrate pure hint calculation into the layout pass or return placements iteratively with actual constrained sizes. Preserve float ratio rounding/truncation before considering a different numeric representation.

Readable code should express this dependency in names such as remaining_height, clients_remaining, constrained_size, and outer_height. Use explicit loops where each result feeds the next iteration. A long iterator chain would hide that dependency.

The standalone sketch below supplies working definitions for validated tags, view transitions, IDs, presentation state, typed actions and the ownership container. It deliberately omits layout algorithms, X11, rules and bar drawing. It is a design example, not evidence of WM compatibility.

Compilable Rust examples

These excerpts are copied from examples/type_sketch.rs; run its tests using the commands at the end.

Tag view owns its transitions

/// Mirrors dwm's two tag slots. Toggle edits the current slot in place.
#[derive(Clone, Copy, Debug, PartialEq, Eq)]
pub struct TagView {
    current: TagSet,
    previous: TagSet,
}
impl TagView {
    pub fn new(tags: TagSet) -> Self {
        Self {
            current: tags,
            previous: tags,
        }
    }
    pub fn current(&self) -> TagSet {
        self.current
    }
    pub fn select(&mut self, tags: TagSet) -> bool {
        if tags == self.current {
            return false;
        }
        self.previous = self.current;
        self.current = tags;
        true
    }
    pub fn toggle(&mut self, tags: TagSet) -> bool {
        match self.current.toggled(tags) {
            Some(next) => {
                self.current = next;
                true
            }
            None => false,
        }
    }
    pub fn restore_previous(&mut self) {
        std::mem::swap(&mut self.current, &mut self.previous);
    }
}

Client owns fullscreen state

#[derive(Clone, Copy, Debug, PartialEq, Eq)]
pub enum Presentation {
    Normal(NormalState),
    Fullscreen {
        restore: NormalState,
        geometry: Rect,
    },
}
#[derive(Debug)]
pub struct Client {
    window: WindowId,
    monitor: MonitorId,
    tags: TagSet,
    presentation: Presentation,
    urgent: bool,
}
impl Client {
    pub fn is_visible_on(&self, view: &TagView) -> bool {
        self.tags.intersects(view.current())
    }
    /// Repeated fullscreen requests do not overwrite the saved state.
    pub fn enter_fullscreen(&mut self, screen: Rect) -> bool {
        match self.presentation {
            Presentation::Normal(restore) => {
                self.presentation = Presentation::Fullscreen {
                    restore,
                    geometry: screen,
                };
                true
            }
            Presentation::Fullscreen { .. } => false,
        }
    }
    pub fn leave_fullscreen(&mut self) -> bool {
        match self.presentation {
            Presentation::Fullscreen { restore, .. } => {
                self.presentation = Presentation::Normal(restore);
                true
            }
            Presentation::Normal(_) => false,
        }
    }
}

Typed action dispatch returns affected monitor

impl State {
    /// Returns the monitor whose focus/layout/bar must be reconciled.
    /// No X11 calls occur while this method holds a mutable monitor borrow.
    pub fn apply_action(&mut self, action: Action) -> Result<Option<MonitorId>, PolicyError> {
        let monitor = self
            .monitors
            .get_mut(&self.selected_monitor)
            .ok_or(PolicyError::MissingMonitor)?;
        let changed = match action {
            Action::ViewTags(tags) => monitor.view.select(tags),
            Action::ToggleView(tags) => monitor.view.toggle(tags),
            Action::PreviousView => {
                monitor.view.restore_previous();
                true
            }
            Action::SetLayout(layout) => {
                monitor.layouts.select(layout);
                true
            }
        };
        Ok(changed.then_some(self.selected_monitor))
    }
}

rustfmt --edition 2021 --check examples/type_sketch.rs
rustc --edition=2021 --test examples/type_sketch.rs -o /tmp/dwm-type-tests
/tmp/dwm-type-tests

Four tests exercise tag validation, previous-view semantics, fullscreen restoration/idempotence, and layout selection. They validate only the sketches. Full regression validation is described in REGRESSION_PLAN.md.

Regression validation and migrating C tests

Existing tests and limits

DWM 6.8 has no automated test suite, test directory, assertions or Makefile test target. transient.c is a manual Xlib exerciser with no assertions or bounded termination. There is therefore no suite to directly translate into Rust tests.

Establish executable characterization tests against the frozen C implementation first. Then run identical fixtures and external scenarios against Rust. Passing establishes compatibility for covered scenarios, not proof that every possible application/event ordering is regression-free.

The current repository has four standalone Rust sketch tests only. The C oracle, X11 clients, runners, CI and Rust WM below are planned deliverables. No WM regression result is claimed yet.

Shared test architecture

tests/fixtures/                 inputs and explicit expected observations
tests/scenarios/                language-independent external scenarios
tests/support/xclient.c         controllable Xlib client
tests/support/c_oracle.c        test-only access to actual C policy
tests/support/reference.patch  minimal observation hooks if required
tests/runner/                   isolated-server lifecycle and comparison
build/reference/               disposable baseline build copy
artifacts/regressions/          logs, snapshots, seeds and failure images

Keep reference sources unchanged and retain their license. Build copies under build/reference/; record source hashes, compiler options, scenario configuration and server/font versions. Test-hook patches need review: changing the oracle can hide a regression.

1. Build a reproducible C baseline

Verify SHA256SUMS from the reference directory, copy the source into build/reference/, and generate a fixed test config.h there. Match Rust tag count, bindings, borders, master ratio/count, resize hints, rules, bar position and fonts.

The C build needs a compiler, Xlib, Xft, fontconfig, FreeType and Xinerama development files. Build using the original Makefile in the copy; build the manual client separately if useful:

make -C build/reference
cc build/reference/transient.c -o build/reference/transient -lX11

These are future commands after creating the build copy. Do not install the baseline or run it on the desktop display. A runner owns a dedicated nested display. Xvfb and Xephyr were not found on PATH in this planning pass; no C build or nested-X suite was run. Missing environment support must be reported, not counted as passing.

2. Port the intent of transient.c

Leave the original intact. Create a controlled client in tests/support/xclient.c reproducing these operations:

1. Create a parent titled floating, size 400×400, with min/max size hints fixed at 400×400.
2. Wait for mapping and observed expected geometry.
3. Move its tag/monitor through normal bindings, then create a 100×100 child with WM_TRANSIENT_FOR=parent.
4. Wait for mapping and settled lifecycle behavior; assert floating placement and inherited tag/monitor behavior through visible outcomes.
5. Switch tags away and back; verify parent and child leave/return to the visible area without recreation.
6. Destroy child and parent; verify managed-list/focus cleanup and bounded exit.

Use a pipe/socket command protocol with acknowledgements and logical window names. Replace the original five-second sleep with event-driven conditions and deadlines. The tags are internal: do not infer them from _NET_WM_DESKTOP, which is not the baseline's tagging model. Use a policy hook for exact internal assertions when necessary.

Run the scenario against C first and review its observations, then run unchanged against Rust. Add cases for an unmanaged parent, parent destruction during metadata lookup, a non-fixed parent, and a transient hint changed after mapping. Follow actual C handler behavior instead of assuming all property changes reapply rules.

The test client can stay in C. Keeping an independent Xlib driver avoids testing the Rust backend solely through itself.

3. Characterize and port policy tests

Target view, toggleview, setlayout, rule precedence, fullscreen, size hints and tiling first. Use actual C functions as the oracle, not a second rewritten algorithm.

A test-only harness can rename main, include the copied dwm.c in its translation unit, restore main, construct Client/Monitor globals, call static functions and serialize results. This alone does not make the functions pure: they may issue X requests. Use a nested display or narrow documented hooks to suppress unrelated drawing and capture requests. Keep real hint application and cursor advancement. Check harness results against external C scenarios to ensure hooks preserve behavior.

Feed the same fixture schema to C and Rust:

{
  "case": "view-toggle-keeps-other-slot",
  "tag_count": 9,
  "initial_slots": [1, 1],
  "operations": [{"view": 2}, {"toggle_view": 1}, {"previous_view": true}],
  "expected_current": 1,
  "expected_previous": 3
}

Fixtures retain both view/layout slots, selected slot, ordering, geometry, hints and relevant flags. Compare logical values, not raw memory or pointer addresses. Translate stable pure assertions to Rust #[test] functions while retaining fixture IDs and expected outputs.

If later patches include real C tests: inventory inputs/assertions/dependencies/licenses, run them on C before translation, port pure assertions, keep black-box tests shared, and translate pointer identity to logical IDs. Existing failures must be distinguished from new migration failures.

4. Required comparison matrix

Match geometry exactly under equal configuration. The C layout uses actual size-hint-constrained height to place the next client and truncates float-derived master width; a general pixel tolerance can hide real defects. Use a fixed bar height for policy tests if font metrics differ, and validate typography separately. Intended differences require explicit approval and specific expectations.

5. Deterministic X11 execution

Use fresh separate servers for C and Rust with identical screen, extensions, locale, fonts and keyboard settings. Wait for WM readiness through ownership/root-property observations rather than fixed sleeps.

Normalize server-specific XIDs to logical names and remove irrelevant timestamps. Preserve geometry, borders, map state, logical stacking, focus and protocol contents. Map state alone cannot prove visibility: C hides clients by moving them offscreen while keeping them mapped.

Drive bindings with real input injection such as XTEST where supported; synthetic XSendEvent is not universally equivalent. Script metadata/protocol changes through the support client. Observer-side XSync does not guarantee the WM processed another connection's events. Use condition-based waits with deadlines, stable observations and, when required, a narrow test-only acknowledgement. Retain traces on timeout.

Verify the server actually supports the multi-monitor topology under test. Xvfb screen configuration is not automatically equivalent to Xinerama monitor changes. Use a verified Xephyr/Xorg environment for real topology tests and a protocol fixture backend for policy tests. Report unsupported cases explicitly; required scenarios cannot silently skip.

6. Check that the tests detect regressions

On a disposable implementation copy, inject these defects and require the relevant test to fail:

• Toggle overwrites previous view.
• Layout order is substituted for focus history.
• Hints are applied only after computing all rectangles.
• Repeated fullscreen entry overwrites restore state.
• Hidden windows are unmapped.
• Removal leaves a stale ID in one list.

A passing test after its intended defect means its assertions need strengthening. Add a permanent fixture for every bug fixed during migration.

After deterministic tests pass, use seeded random lifecycle/action sequences. Compare defined policy outcomes to C and assert independent Rust invariants. Save seeds and minimize failures into short fixtures. C is a compatibility oracle, not a correctness proof: inherited defects or undefined behavior need a reviewed compatibility decision, not blind reproduction.

7. Milestones and release gate

1. Build C and automate the transient scenario before implementing complex Rust behavior.
2. Establish fixtures for views, layouts/hints, rules and fullscreen.
3. Port policy incrementally and run fixtures/invariants with each change.
4. Add shared lifecycle/input/protocol integration once the Rust vertical slice runs.
5. Add real application trials and verified multi-monitor cases.
6. Require formatting/lint checks, all required differential scenarios, race cases and recorded real-session trials before release.

Future Cargo gates: cargo fmt --check, cargo clippy --all-targets -- -D warnings, and cargo test. The standalone sketch is not a Cargo WM project yet. Implement a runner with explicit executable/scenario arguments so the same scenarios select C or Rust.

Publish pass/fail/skip per scenario, baseline identity, environment, intended differences and failure artifacts. Failures block promotion until fixed or explicitly reviewed. Never automatically accept new golden output.

Checks completed now

Both archives have identical SHA-256; every extracted regular file matches its archive bytes; all 13 reference file checksums pass. Four standalone Rust tests compile and pass on Rust 1.82.0. No automated C tests existed to port. No C build, X11 differential validation or WM regression suite has run.