Commit Graph
7 Commits
Author SHA1 Message Date
LGUG2Z dcadd9aa84 docs(seam): the seven consequences, restated and corrected, and the unverified list
Adds section 7 (the seven consequences of plan step 7, each with its supporting citations and a status: CONFIRMED, CORRECTED or TARGET; plus three findings the plan did not list: a batch/transaction scope, the workspace methods that exist only on KDE, and error-type differences) and section 8 (everything not confirmed, with how to confirm it on a Mac, a Windows guest or by reading). Verified against the citations of sections 2 to 6 on wip-main aa52fdc4d9e5. Not verified: see section 8.
2026-10-31 01:37:53 -07:00
LGUG2Z 2f8f839b4f docs(seam): events and the set_rect contract
Adds section 6: event sources per platform and how they reach the window manager (references the step 5 prep entries rather than redoing them) and the evidence for the 'set_rect returns once requested, the frame is observed later' contract: KDE queued commands with an optimistic table write, macOS arrival.rs, settle.rs and animator verification, Windows live_resize settling. Verified against wip-main aa52fdc4d9e5: K/kwin/mod.rs, K/kwin/state.rs, K/window_manager_event_listener.rs, K/backend/mod.rs, M/arrival.rs, M/settle.rs, M/animation/animator.rs, M/window.rs, M/window_manager_event_listener.rs, W/winevent_listener.rs, W/windows_callbacks.rs, W/live_resize.rs. Not verified: any runtime ordering of events.
2026-10-31 01:37:53 -07:00
LGUG2Z 2f1fb7826c docs(seam): window identity and coordinate conventions
Adds sections 4 (identity: id types per platform, what acting on a macOS window from a bare id would need, where each tree keeps per-window platform data, HWND width including an observation of 440 distinct HWNDs from the Windows guest logs) and 5 (coordinates: Rect convention, origin and y direction, DPI and scale handling, shadow and frame compensation, and where each conversion lives). Closes two plan items: Windows HWND width and macOS Retina points versus pixels. Verified against wip-main aa52fdc4d9e5: komorebi-layouts/src/rect.rs, W/window.rs, W/windows_api.rs, W/lib.rs, K/kwin/state.rs, K/kwin/bridge.js, M/window.rs, M/application.rs, M/macos_api.rs, M/core_graphics/mod.rs, M/core/rect_ext.rs, M/border_manager/border.rs, M/animation/ghost.rs, M/animation/capture.rs, and ~/e2e-w0 logs read-only for the HWND range. Not verified: HWND width as a Microsoft guarantee, AX values on scaled-resolution or mixed-DPI displays, negative monitor origins on Windows.
2026-10-31 01:37:53 -07:00
LGUG2Z ebf9679b95 docs(seam): macOS thread table, main-queue dispatches and the possible deadlock
Adds section 3.3: the macOS main thread (AppKit and CFRunLoop loop, what runs there), every other thread with its locks, every DispatchQueue::main exec_sync/exec_async/blocking-channel site with file:line and whether the main-side closure takes the window-manager lock, and a precise statement of the possible event-thread/main-thread deadlock, marked by reading, not reproduced. Verified against wip-main aa52fdc4d9e5: M/main.rs, M/macos_api.rs, M/monitor_reconciliator.rs, M/border_manager/{mod,border,ns_window}.rs, M/animation/{animator,ghost}.rs, M/process_event.rs, M/process_command.rs, M/reaper.rs, M/settle.rs, M/workspace_reconciliator.rs, M/window.rs, M/application.rs, dispatch2-0.3.1/src/queue.rs. Not verified: that NSWorkspace and CG display callbacks arrive on main (Apple behaviour), that CFRunLoopAddSource from a non-main thread is safe, that AXUIElement is thread-safe (the code asserts Send+Sync), and the deadlock itself (needs a Mac).
2026-10-31 01:37:53 -07:00
LGUG2Z 568881a955 docs(seam): thread tables for KDE and Windows
Adds sections 3.1 (KDE) and 3.2 (Windows): every thread that exists, what it locks, and which threads call the platform API. Closes two items the plan listed as unverified: which threads call backend() in KDE (traced: main at start-up and stop, the event thread, command threads, the monitor reconciliator and its settle thread, and tests through with_backend; never the KWin bridge or the hotkey threads) and which threads call WindowsApi, with the thread-affine subset. Verified against wip-main aa52fdc4d9e5: K/main.rs, K/kwin/mod.rs, K/kwin/hotkeys.rs, K/process_event.rs, K/process_command.rs, K/monitor_reconciliator.rs, K/backend/mod.rs, W/main.rs, W/winevent_listener.rs, W/windows_callbacks.rs, W/border_manager, W/stackbar_manager, W/animation, W/live_resize.rs, W/reaper.rs. Not verified: Microsoft's documented behaviour of WINEVENT_OUTOFCONTEXT and cross-thread SetWindowPos, and every Windows call chain (the table lists thread entry points and the API each reaches, not every path).
2026-10-31 01:37:53 -07:00
LGUG2Z 0108f8edac docs(seam): operation table and platform-subsystem table
Adds section 2: the operation table (one row per operation present on at least two platforms: KDE Backend method | Windows | macOS | semantic differences), the platform-subsystem table, and the re-measured counts with the exact method. Verified against wip-main aa52fdc4d9e5: K/backend/mod.rs, K/kwin/mod.rs, W/windows_api.rs, W/window.rs, M/macos_api.rs, M/window.rs, M/core_graphics/mod.rs, M/lib.rs. Not verified: how each AX call behaves against real applications (needs a Mac), and the counts are of source text, not of executed calls.
2026-10-31 01:37:53 -07:00
LGUG2Z 22c814e1b6 docs(seam): purpose, how to read it, and corrections to earlier claims
Creates docs/dev/seam.md with sections 1 (purpose and how to read) and the corrections list. Verified against wip-main aa52fdc4d9e5 by reading K/backend/mod.rs, K/kwin/mod.rs, K/kwin/state.rs, M/macos_api.rs, M/window.rs, M/arrival.rs, M/process_event.rs, M/process_command.rs, W/windows_api.rs. Counts quoted here are measured in the next revision. Not verified: any runtime behaviour (the document is reading-only).
2026-10-31 01:37:53 -07:00