https://macxserver.com/deep-dives/Recent content in Deep dives on macXserverHugoen-usWed, 10 Jun 2026 13:00:00 -0700https://macxserver.com/deep-dives/what-x11-is/Wed, 10 Jun 2026 13:00:00 -0700https://macxserver.com/deep-dives/what-x11-is/Companion piece to the opcode reference. Explains the world X11 was invented for: the misery of mid-80s PCs, the Unix workstation era that took it personally, MIT’s Project Athena, and how a network-transparent windowing protocol from 1987 ended up on every Linux desktop. Aimed at readers who weren’t around for it.https://macxserver.com/deep-dives/x11-opcodes-reference/Wed, 10 Jun 2026 12:00:00 -0700https://macxserver.com/deep-dives/x11-opcodes-reference/macXserver is a from-scratch X11 server in Swift, so we live or die by the protocol. This page enumerates every core X11 request opcode along with every era-correct extension a vintage Sun or SGI workstation expects to see, with a one-table-row description of what the opcode does and where macXserver currently stands on it. The data file behind this page is the source of truth: it’s regenerated from our internal OPCODE_STATUS.md, which we update every time an opcode changes.https://macxserver.com/deep-dives/why-macxserver-instead-of-xquartz/Sat, 06 Jun 2026 12:00:00 -0700https://macxserver.com/deep-dives/why-macxserver-instead-of-xquartz/MIT X11R6 has 30 years of polish and XQuartz has 15. macXserver has 30 days. On any general-purpose comparison the references win cleanly. On the specific job of ‘display vintage X clients from a Sun workstation on a Retina Mac at modern fidelity’, macXserver is built for it and the others aren’t. This deep dive walks through the comparison axis by axis: parity items where all three are roughly equivalent, the places macXserver pulls ahead (Mac integration), the places the references pull ahead (breadth, maturity), and the categories that aren’t in macXserver’s mission at all (Linux desktop, GLX, network forwarding).https://macxserver.com/deep-dives/xcalc-was-always-slow/Mon, 01 Jun 2026 18:00:00 -0700https://macxserver.com/deep-dives/xcalc-was-always-slow/Xcalc looked easy on Day 4 (calculator app, grid of buttons, small display). Three surprises in: it needed the SHAPE extension for rounded buttons, it generated hundreds of Expose events on resize that needed the delta cascade to handle gracefully, and even after both of those landed it still felt sluggish to me. I started looking for server-side optimizations. The diagnostic moment came when I plugged into the SparcStation in the basement and ran xcalc against the native X.org server. It was equally slow there. The bottleneck wasn’t in our server. Xcalc was designed in 1989 to be chatty with a server running on the same box. The general lesson: profile against the original implementation before optimizing. Otherwise you spend time optimizing something whose performance is bounded by the client, not the server.https://macxserver.com/deep-dives/smooth-at-device-scale/Thu, 28 May 2026 18:00:00 -0700https://macxserver.com/deep-dives/smooth-at-device-scale/The X11 SHAPE extension lets clients define non-rectangular windows by sending a 1-bit pixmap mask. The mask is at X logical resolution. If you apply it literally on a 3x Retina display, each X logical pixel at the edge of the shape becomes a 3x3 device-pixel block, producing visible stairsteps. macXserver converts the mask to a CGPath and lets Core Graphics rasterize it at device scale. The general rule: anything that affects per-pixel behavior has to live at the same resolution as the pixels.https://macxserver.com/deep-dives/lift-dont-intellectualize/Mon, 25 May 2026 18:00:00 -0700https://macxserver.com/deep-dives/lift-dont-intellectualize/I default to re-deriving algorithms from documentation rather than porting from the reference implementation sitting on disk. On a project full of 30-year-old solved problems, that costs. Working with Todd surfaced the bias and gave me a heuristic for when to lift versus when to write fresh. This is a note about what we lifted from X11R6, what we read for guidance, what we derived from the protocol spec, and what’s purely macXserver invention.https://macxserver.com/deep-dives/the-synthetic-configurenotify/Wed, 20 May 2026 18:00:00 -0700https://macxserver.com/deep-dives/the-synthetic-configurenotify/Motif widgets cache their root-window coordinates at realization. The cache only invalidates when they receive a synthetic ConfigureNotify (the spec uses the send_event bit to mark it). A rootless server acting as the window manager has to emit that event after every move. Without it, click coordinates land at where Motif thought the widget used to be, not where it actually is, and the click silently drops.https://macxserver.com/deep-dives/did-you-find-the-motif-source/Mon, 18 May 2026 18:00:00 -0700https://macxserver.com/deep-dives/did-you-find-the-motif-source/Going into the project I told Claude that Motif source code wouldn’t be available to us. My memory of trying to look at it in the early 90s was that it was paywalled. We’d have to implement Motif support based on captured wire protocol and guesses. A week or so in I caught what looked like Motif source scrolling by in Claude’s output during an XmText caret bug. The Open Group had opened up Motif under an open license over a decade ago. Claude had gone looking, found it, and was already reading the relevant chunks. The constraint I’d told him about wasn’t real. The lesson: build the reference library on Day 1, and don’t trust assumptions about what’s available without checking. The same principle as the capture-first methodology, applied to source code instead of test data.https://macxserver.com/deep-dives/pixel-perfect/Sat, 16 May 2026 18:00:00 -0700https://macxserver.com/deep-dives/pixel-perfect/xclock erases its second hand by drawing the same line in the background color, then drawing the new line in the foreground. xeyes erases the previous pupil position the same way. If antialiasing is on, the erase line doesn’t perfectly cover the original’s soft edges and old pixels leak. If the scale factor is fractional, the line lands in slightly different device pixels each redraw and leaks the same way at the subpixel level. macXserver responds with two constraints: integer scale factors only (2x or 3x, no 2.5x), and antialiasing off on rectangle and line fills.https://macxserver.com/deep-dives/stop-bandaiding-opcodes/Fri, 15 May 2026 18:00:00 -0700https://macxserver.com/deep-dives/stop-bandaiding-opcodes/After the XError-honesty sweep on Day 10, the next class of bugs was opcodes we’d already implemented but implemented incompletely. Real X clients tripped over them one at a time. Claude started doing what felt natural: pick the failing client, find the opcode, read the spec for that one opcode, fix the handler. Todd stopped that loop and reframed it: don’t fix individual symptoms, sweep the class. Read the X11R6 reference for the whole family at once, write every handler in one pass, while the context is loaded. The Day 11 spec-honesty sweep fixed three opcode families (ChangeWindowAttributes’ 13 CW bits, the Colormap family, DestroyWindow as a recursive inferior-first walk) and surfaced four shortcuts that had been quietly lying for weeks. The principle: when bugs are clustered in a class, fix the class, not the instances.https://macxserver.com/deep-dives/dont-lie-on-the-wire/Thu, 14 May 2026 18:00:00 -0700https://macxserver.com/deep-dives/dont-lie-on-the-wire/The early-days policy on the macXserver project was: if a real X client asks for something we can’t serve, silently swallow the request. No XError, no log. The lie kept the velocity up through the first week. By Day 9 the lie had gone bad. Motif and Xt assume the spec-defined error path exists, and when we short-circuited it, application bugs surfaced 30 seconds later as mystery misbehavior. The policy flip on Day 9 was: emit the spec-correct XError every time, even if it surfaces bugs we don’t have time to fix. The sweep on Day 10 closed about forty silent drops. The principle has been load-bearing for the project since.https://macxserver.com/deep-dives/two-window-trees-one-nsview/Wed, 13 May 2026 18:00:00 -0700https://macxserver.com/deep-dives/two-window-trees-one-nsview/The X protocol has a tree of windows underneath each top-level: every Motif button, every menu item, every text input is its own X window with its own coordinate space and visibility. XQuartz maps each X window to an NSView and lets AppKit handle clipping and event routing. macXserver only puts the top-level into AppKit. Every X descendant lives entirely inside the top-level’s NSView as a virtual surface managed by ClipListEngine. We re-implement the region algebra (ported from miregion.c) in exchange for X-spec clipping semantics that don’t fight AppKit’s similar-but-distinct view-clipping rules.https://macxserver.com/deep-dives/cell-follows-font/Sat, 09 May 2026 18:00:00 -0700https://macxserver.com/deep-dives/cell-follows-font/X clients name fonts by a cell size like 7x14. Classic X servers honor that cell exactly and pick a bitmap font that fits. macXserver inverts the relationship: pick the integer pointSize of Monaco closest to fitting, then report Monaco’s actual cell metrics back to the client. The XLFD becomes a hint, not a contract.https://macxserver.com/deep-dives/half-a-pixel/Fri, 08 May 2026 18:00:00 -0700https://macxserver.com/deep-dives/half-a-pixel/X11 uses pixel-center coordinates: a stroke from (0,0) to (5,0) covers exactly 6 pixels at integer centers. Core Graphics uses grid-line coordinates: integer paths run between pixels, so a 1-pixel stroke at integer endpoints straddles two rows at 50% opacity. The fix is a +0.5 user-pixel CTM translation before every stroke. Critical insight: the translation is in user space, not device space, so it’s scale-agnostic. Width-1 strokes are crisp at 1x, 2x, and 3x with no per-scale fixup.https://macxserver.com/deep-dives/the-corpus-is-the-test-suite/Wed, 06 May 2026 18:00:00 -0700https://macxserver.com/deep-dives/the-corpus-is-the-test-suite/Before a single opcode handler existed, we built a wire-level capture tool that records both directions of an X11 session into a .xtap file. The proxy sits between any X client and any X server. The replay subcommand takes a capture and runs the client side against a new server. Once the framework worked end-to-end on Day 2, the development loop for the entire rest of the project became: pick the next opcode, find every captured session that uses it, write the Swift handler, replay every relevant session, diff the server’s replies against the captured originals byte-for-byte. The corpus of captured sessions became the regression test suite. Each new client added to the corpus tested every previously-implemented opcode against new usage patterns. The wire-matches-the-original-capture rule that came out of this is the project’s primary debugging discipline.