Side Projects on Man-You

25 years to a complete machine

Mon, 04 May 2026 00:08:13 +0200

Since around the year 2000 I have been piling features into a French Final Fantasy IV translation patch. Variable-width fonts in dialog, in battle messages, in menu descriptions. Redrawn battle, load/save, main, and two-column magic menus. An expanded inventory of 0x48 slots rendered through a paged window instead of the static grid the original engine assumed. Most of these were features the SNES ROM hacking scene of the era said could not be done on real hardware. Other hackers eventually pulled off equivalents on other titles, fair enough; modifying a compiled ROM is more convoluted than editing source code, but not impossible. Twenty-five years on, “impossible” reads as a fair approximation of how hard, not of whether.

The bugs that come with hard features are also recent, introduced by my own patches. The field-menu item list eventually crashed: open inventory, swap items around, and after enough operations the stack pointer drifted until the next interrupt landed on a brk¹ instruction and the emulator stopped cold.

The cause was one wrong return mnemonic². swap_redraw_trampoline lives in bank $01³. Its real body, swap_redraw_hook_impl, lives in bank $21. The field menu calls the trampoline with jsr.l⁴, which pushes a 24-bit return. The bank-$21 body returns via rtl, which is correct. The trampoline itself ended in rts, which is not. One byte of the long-return address stayed on the stack every time an item was swapped. Run the swap path enough times and the underflow cascaded, the next NMI⁵ hit garbage, and the BRK trap I had wired into the vector table⁶ caught the offending PC.

The fix is one mnemonic. Getting to the point where I could see the wrong mnemonic took infrastructure.

Why a rolling inventory at all

The rolling inventory was not strictly necessary. Two columns of items were getting tight on screen as the inventory grew, and I knew FF6 had solved a similar layout problem more elegantly with a paged renderer. FF4 and FF6 share engine roots, which made porting the technique tractable instead of ground-up work. So I lifted the approach.

The memory side effect is real but secondary. The rolling render only keeps the visible slice in RAM and VRAM⁷, paging new ones in as the cursor scrolls. 0x48 slots at roughly 0x40 bytes of tile data each would have cost 0x48 * 0x40 = 0x1200 bytes per buffer in a static layout. The rolling layout drops that to one window’s worth. If saving memory had been the only goal there were cheaper fixes than this one.

The bug above was the price of pulling FF6 ergonomics into FF4: the trampoline that moves tile data between RAM and VRAM forgot to return with the right mnemonic, leaked one byte per swap, and the stack caught up with the player when they were having too much fun rearranging.

What made the bug reachable

For most of the 25 years I have been doing this, I would not have caught it.

The original ff4 source, like every long-running ROM hack, was a single textual .include chain compiled in one pass. Every label was global. There were no module boundaries. There was no way to ask the assembler “where does this symbol come from” except by grepping the file system. The trampoline-with-the-wrong-rts looked exactly like the trampoline-with-the-right-rtl two screens up. Lost in the noise.

The ff4 source recently finished its migration to a816’s .import system. Each module declares its own externs, compiles to its own .o, links through relocations. The LSP earns its keep on top of that. When you suspect swap_redraw_trampoline ends in rts where it should end in rtl, you do not grep for “swap_redraw” across hundreds of files. You click. The symbol resolves through the import graph, the trampoline opens in the right module, and the wrong mnemonic is on the screen.

Without modules the bug was unreachable. Without the BRK trap in the vector table the symptom was “crashes sometimes” instead of a PC value. The rest of the chain (LSP for navigation, kintsuki for deterministic reproduction) only mattered once those two existed.

Why these tools exist

I have been hacking on Final Fantasy IV, on and off, since around the year 2000. The earliest public trace is the ff4fr repo from 2011, itself a snapshot of older work. The reason the project keeps surviving long gaps is simple: it interests me. I come back, I poke at it for a few weekends, I drift, I come back. A hobby that happened to last.

None of the tools were built as long-game preparation for the rolling inventory bug.

a816 replaced x816.exe, the DOS assembler the FF4 scene had used for years. x816 is painful on Windows, dead on Linux and macOS. Building the ROM on GitHub Actions through dosbox was not going to happen. asar exists and is a fine alternative (and may not have been around when I started; I do not remember the timeline clearly). I went my own way because I wanted tight integration with the ff4 source: modules I controlled, a formatter I could shape, an LSP that understood bank annotations and docstring conventions, an object format that handled multi-region modules cleanly. Easier to build that end-to-end than to lobby someone else’s project for ergonomics specific to one ROM hack. The GitHub Actions side became its own win. Messing with workflows on a personal repo translated directly into knowledge I now apply at work.

kintsuki exists because I like automated tests. Running the ROM deterministically against pinned inputs needs primitives ares does not expose by default: mid-frame yield, PC override across scheduler entries, stp and wai flag preservation through external state-set. kintsuki adds the shim around the ares core and ships it as a Python wheel.

The honest reason underneath both: knowing enough to be dangerous has been the constant of my career. At fifteen, in 2000, I was dangerous with a hex editor and someone else’s assembler. That was already enough to start a translation patch. The version writing now is dangerous with a homemade assembler, an LSP, an emulator harness wrapped as a Python wheel, and a multi-region object format. The disposition has not moved. The capability has. Every year of doing software for a living added new ways of being dangerous, and the FF4 patch is the one personal project that stuck around long enough to absorb all of them. The tools and the patch grew up together. The features the fifteen-year-old wanted are now sitting on infrastructure he could not have built, but would absolutely have used.

The thing actually pacing the work right now is a self-imposed release date: December 26, 2026, for a packaged build of the patch. That deadline turned the loose interest into a backlog. The deadline is recent. The hobby is old.

Seven and a bit months until the release date. The patch will ship with bugs that came after it on top of an assembler and a harness that came before. The ROM hack will still have open issues, untranslated NPCs, and design decisions I will second-guess. None of that bothers me. It is the project I keep coming back to because it keeps being interesting, and right now the interesting thing is finishing it.

Not everything I write is meant to stick it up to the man. This one is not. Hobby code, on a console nobody ships for, against a deadline I made up because I felt like one. No thesis. A release on December 26.

brk is a one-byte instruction that triggers a software interrupt. The CPU pushes its state and jumps to a fixed handler address. Useful as a trap when that handler is wired to halt the emulator on an unexpected fall-through. ↩︎
A mnemonic is the short text name for a CPU instruction (rts, jsr, lda). The assembler turns each one into the matching machine-code byte. ↩︎
The 65C816 addresses 24-bit memory split into 256 banks of 64KB. $01:FF34 reads “address $FF34 in bank $01”. Code in different banks is reached with long-call instructions instead of short ones. ↩︎
jsr.l is a long jump to subroutine: it pushes a 24-bit return address (bank + 16-bit) before jumping. The matching return is rtl. The short pair is jsr + rts (16-bit return). Mismatching them leaks or eats bytes off the stack. ↩︎
Non-maskable interrupt. On the SNES it fires once per video frame, in the brief moment when the screen is between drawing two frames, and runs whatever handler the CPU is told to run for it. ↩︎
The vector table is a fixed block at $00FFE0-$00FFFF listing handler addresses for reset, NMI, BRK, and others. Wiring a BRK trap means setting the BRK handler to halt the emulator and record where the bad instruction came from, so an unexpected brk produces a debuggable crash instead of silent corruption. ↩︎
The SNES CPU’s main RAM is 128KB. VRAM is the graphics chip’s video RAM (64KB), holding the tile data and the screen layout. Anything visible has to be in VRAM. Tile data is usually staged in main RAM and copied across in bulk between two drawn frames. ↩︎

Higgins: a neurosymbolic menubar buddy

Mon, 20 Apr 2026 10:00:00 +0200

Higgins is a local assistant that lives in the menubar. A Qwen 2.5 7B model runs on-device via MLX, a SQLite triple store remembers things across sessions, and a small collection of tools — AppleScript runners, EventKit bridges, gh CLI wrappers — lets him actually do work on the Mac. No cloud, no subscription, no data leaving the machine.

The name is a nod to Magnum P.I.’s reserved English major-domo. The vibe was aspirational; most of the engineering effort went into making sure he doesn’t cheerfully hallucinate your dentist appointment into 2023.

Why not just a chat wrapper

The starting pitch was neuro-symbolic: “LLMs are great at vibes and terrible at strict logic; symbolic systems are the opposite; put a logic engine inside a neural one.” Nice in a blog post, vague as a project.

What it actually means in code: the neural side (Qwen) handles language, intent, paraphrasing. The symbolic side (SQLite facts table, typed tool schemas, EventKit queries) handles everything where being wrong is worse than being silent — dates, names, calendar events, PR numbers. The LLM never gets to compute a date from priors; it forwards your words to a parser. The LLM never claims to remember your dog’s name; the fact comes from a SQL row, or it doesn’t answer.

That split is the whole project. Everything else is plumbing.

The Qwen brain

Qwen 2.5 7B Instruct, 4-bit quantized, ~4.5 GB on disk. Loaded via mlx-swift-lm with progress reported through a NSKeyValueObservation on the download’s Progress object — since swift-huggingface fires the handler once then mutates in place, not on every byte.

Picking Qwen over Gemma was almost incidental. Gemma 3 4B worked but wouldn’t accept a system role, forcing a hacky primer-pair trick. Gemma 4 26B-a4b is MoE, which mlx-swift-lm’s Gemma4Model doesn’t implement yet. Qwen accepts system prompts cleanly and, crucially, was trained to emit native tool calls — which matters a lot more than benchmark scores.

The old path was prompt-engineered: TOOL_CALL toolname {...} in the output, parsed with regex. Fragile. Qwen wants to emit something like:

<tool_call>
{"name": "reminder_add", "arguments": {"text": "…", "datetime": "…"}}
</tool_call>

mlx-swift-lm surfaces this as .toolCall(ToolCall) events in the generation stream, if you pass structured tool specs into UserInput(chat:, tools:). Once wired up, the model stops inventing its own format and starts using the one it was RL’d on.

Generation loop excerpt

for await gen in try MLXLMCommon.generate(input: input, parameters: params, context: context) {
 switch gen {
 case .chunk(let s): output += s
 case .toolCall(let c): call = c
 case .info: break
 }
}

The text parser stuck around as a fallback for edge cases.

The symbolic side

A SQLite file at ~/Library/Application Support/Symbolic/memory.db with two tables:

CREATE TABLE episodes(
 id INTEGER PRIMARY KEY,
 user_msg TEXT, assistant_reply TEXT,
 signal INTEGER, ts REAL
);
CREATE TABLE facts(
 id INTEGER PRIMARY KEY,
 subject TEXT, predicate TEXT, object TEXT,
 confidence REAL, last_seen REAL,
 UNIQUE(subject, predicate, object)
);

Episodes are the raw log: every chat turn lands here. Facts are the distilled, queryable form — subject/predicate/object triples with a confidence score. The interesting work happens in the pipe between the two.

Sleep

The consolidation metaphor is cribbed directly from human memory: episodic hippocampal traces don’t become semantic knowledge until you sleep. Higgins does the same. After 15 minutes of chat silence, or when you tap the 🌙 button, he runs a pass:

NREM: the model reads the day’s recent episodes and emits one JSON object per line — extracted stable facts about you, your world, your preferences. Ephemeral conversational filler (greetings, acknowledgments, weather chat) is skipped.
Synaptic downscaling: every fact’s confidence is multiplied by 0.95. Unused memories decay. Recalled ones get re-bumped above 1.0 and capped.
Purge: facts below 0.05 confidence are dropped.
Dream log: a human-readable markdown summary lands in ~/Library/Application Support/Symbolic/dreams/YYYY-MM-DD.md.

Sleeper entrypoint

func nightCycle(episodeLimit: Int = 100) async throws -> Report {
 let episodes = try await store.recentEpisodes(limit: episodeLimit)
 let facts = await extractFacts(from: episodes)
 for f in facts {
 try await store.addFact(subject: f.subject, predicate: f.predicate, object: f.object)
 }
 try await store.decayFacts(multiplier: 0.95)
 let purged = try await store.purgeWeakFacts(threshold: 0.05)
 // ...
}

There’s no remember command to learn. Facts accumulate while you use the thing.

Per-turn recall: closing the loop

Sleep would be useless if the facts just piled up. Before each generation, the user’s query is keyword-matched against the facts table (top 5 hits, LIKE on subject/predicate/object). Matching facts are injected into that turn’s system context as a bracketed prefix:

[Known facts from memory:
- dog / name / Rex (confidence 0.95)
- manz / employer / Woosmap (confidence 0.87)
]
what's my dog's name?

History stays clean — the decoration only exists for the single inference call. No tool call needed for the model to answer “Rex”. The symbolic substrate grounds the neural output on the way past.

At low scale (hundreds of facts) LIKE matching is good enough. Embedding-backed similarity search is the upgrade when it isn’t.

Tools

The tool layer is where the project actually earns its keep. Three surfaces:

AppleScript library. Curated scripts live in ~/Library/Application Support/Symbolic/scripts/, each with frontmatter metadata (-- name:, -- description:, -- args:). Seed scripts ship with the app; the user can edit or add more. The model calls them by name — calendar_today, note_quick, etc. — as if they were first-class tools.

EventKit bridge. AppleScript against Calendar.app is infamously slow — iterating every event on every calendar through the bridge takes 30+ seconds for a busy calendar. EventKit queries the same data in milliseconds. The catch: it needs NSCalendarsFullAccessUsageDescription in a real Info.plist. The SPM executable embeds one via a linker trick:

Package.swift

linkerSettings: [
 .unsafeFlags([
 "-Xlinker", "-sectcreate",
 "-Xlinker", "__TEXT",
 "-Xlinker", "__info_plist",
 "-Xlinker", "Resources/Info.plist",
 ]),
]

-sectcreate __TEXT __info_plist injects the plist into a section TCC reads when deciding whether to prompt for permission. Works without wrapping the binary in a .app bundle.

gh CLI wrappers. gh_my_prs, gh_review_queue, gh_notifications, gh_recent_merged. Subprocess calls to the user’s existing gh session — no OAuth dance, no token storage. A ProcessRunner actor handles timeouts and respects Task.isCancelled so a stuck subprocess doesn’t freeze the UI when you hit the red stop button.

Tool results render as folded cards with a wrench icon, tool name, and a one-line summary. Click to expand. Errors auto-expand. #123 · PR title · owner/repo links are real anchors thanks to MarkdownUI on the assistant-side rendering.

Dates, or: why the model doesn’t do arithmetic

7B models are bad at date math. “Remind me tomorrow at 8:15” reliably produced ISO strings from 2023, 2024, anywhere but actually tomorrow.

The fix is to not let the model do arithmetic at all. Any tool argument named datetime, when, due_date, etc. gets intercepted in Swift before dispatch. A tiny table handles English and French relative words (tomorrow, today, demain, hier) — NSDataDetector isn’t locale-parameterizable and picks up the system locale, which fails on English keywords under a French macOS. Anything the table doesn’t catch falls through to NSDataDetector, which anchors relative phrasing against Date().

Critically, the user’s raw message is the source of truth, not the model’s output. If you typed “tomorrow”, “tomorrow” is what gets parsed — even if the model hallucinates an ISO. The model’s job is intent extraction, not date reasoning.

The AppleScript Run button

When the model writes code in an assistant reply, the code block renders with a language tag and a copy button. When the language is applescript, a Run button appears:

CodeBlock with conditional run action

MarkdownUI.Markdown(turn.text)
 .markdownBlockStyle(\.codeBlock) { config in
 CodeBlock(
 code: config.content,
 language: config.language ?? "",
 onRun: runAction(for: config.language ?? "", code: config.content)
 )
 }

The action shells out to osascript -e <script>, captures stdout, appends the result as a tool turn. The user stays in charge — nothing runs without the click. Safer than giving the model unrestricted automation tools, more flexible than the curated script library.

What grew out of it

The original plan was to fine-tune a custom voice — a “genius caveman” Grug, all short fragments. Hours of LoRA experiments on Gemma 2 2B, Gemma 3 4B, Gemma 4 E4B later, the honest conclusion: voice tuning on small models produces caricature or collapse, and nobody cares about voice when the tools don’t work. The pivot was embracing stock Qwen and pouring the effort into the symbolic substrate instead.

What’s there now:

On-device Qwen 2.5 7B with native tool calling, loading with proper progress feedback
Conversation persistence as JSONL (machine) + Markdown sidecar (human), auto-saved per turn, restored on launch if recent
Tool calls through Qwen’s native format, fallback text parser, per-tool timeouts, cancel button, pending spinner
Sleep/nap consolidation turning episodes into facts, confidence decay, dream logs
Per-turn recall grounding generation on stored facts without touching history
EventKit for calendar/reminders in milliseconds, gh CLI for GitHub, NSDataDetector for natural-language dates
Right-click menu: new conversation, sleep now, open dreams/conversations/memory in Finder
Markdown-rendered assistant replies via MarkdownUI, plain monospaced tool output
AppleScript Run button on any applescript code block in a reply

The fine-tune loop (REM-derived training candidates → periodic LoRA refresh of stable voice and high-confidence facts) is designed but deferred. Retrieval has a faster iteration loop; weights-baking earns its keep when retrieval stops being enough. Given Higgins has had exactly zero users for three days, that threshold is a while off.

Meanwhile he tells me what’s due tomorrow, doesn’t make up dates, remembers the cat’s name is Charlie, and opens PR review queues when I ask. Good enough for now.

The most useless way to port a macOS app

Tue, 24 Mar 2026 09:30:00 +0100

I grew up fascinated by projects like GNUStep, Haiku, Etoile, Wine, and ReactOS. Engineering feats, all of them. They reverse-engineer or reimplement entire operating system APIs so that software written for one platform can run on another. And they almost always end up in the same place: impressive technically, starved for contributors, forever chasing a moving target they can never quite catch.

I never liked the state of the Linux desktop either. Not because it’s bad per se, but because it’s fragmented. A KDE app on GNOME looks alien. Firefox rolls its own everything. GTK and Qt will never agree on anything. Every toolkit draws its own widgets, manages its own text rendering, handles its own accessibility story. The result is a desktop that feels like a coalition of independent projects rather than a coherent system.

This project is not going to fix any of that. But it’s an interesting story about how a combination of prior work, Apple open-sourcing key components, and an AI pair programmer led me down a rabbit hole I didn’t plan to enter.

The prior art that made this possible

I’ve been working with wgpu (Rust’s WebGPU implementation) for a while now, building a map renderer for Woosmap. That project taught me the fundamentals: how to manage GPU pipelines, how to do instanced rendering, how to deal with text atlases and glyph rasterization, how to bridge Rust and Swift through UniFFI.

On the Swift side, I had two apps: Tunes, a music player, and Leela, an internal management tool for Woosmap services. Both are SwiftUI apps, both depend on Apple’s frameworks in the usual way.

So one evening, half-curious and half-joking, I fed Claude the source of those projects alongside some context about GNUStep and friends, and typed:

“What would it take to make Tunes build and run on Linux?”

And then things got out of control.

What Claude came back with

The answer was, predictably, “a lot.” But the interesting part was the breakdown. SwiftUI is the main dependency, and SwiftUI is closed-source. But Swift itself is open-source. Swift Foundation is open-source. The Swift Package Manager works on Linux. So the gap is really:

A SwiftUI implementation (the view hierarchy, state management, layout engine, modifiers)
Some AppKit shims (NSColor, NSAppearance, the bits that SwiftUI still leans on)
A rendering backend that isn’t Core Animation or Metal
A compositor to manage windows, menus, and the desktop chrome

Instead of stopping at “that’s insane, don’t do it,” I kept going. Claude kept going. We started building.

Architecture

The project (codenamed Clone) splits pretty naturally along a language boundary.

Rust does what Rust is good at: GPU work. A wgpu renderer with pipelines for rectangles, rounded rects (SDF-based, because I can’t stop using SDFs apparently), shadows, text via a glyph atlas, and wallpapers. It also runs the window compositor through winit.

Swift does what Swift is good at: UI. A from-scratch SwiftUI implementation (about 50 View types, @State/@Binding/@Environment, ViewBuilder, layout, modifiers), the whole declarative stack. Plus enough AppKit shims to keep real apps happy, a SwiftData reimplementation backed by SQLite, and an IPC protocol over Unix sockets.

UniFFI bridges the two. Each frame, Rust asks Swift for render commands, Swift resolves the view tree into a flat list of positioned primitives, and Rust batches them into instanced GPU draws. It’s the same bridge I use in the map renderer, so at least that part wasn’t new territory.

graph LR
A["App.body"] --> B["ViewBuilder"] --> C["_resolve()"] --> D["Layout"]
D --> E["CommandFlattener"] --> F["IPC
CGFloat → Float"] --> G["Rust batcher"] --> H["wgpu draws"]
style A fill:#c4a7e7,stroke:#6e6a86,color:#191724
style B fill:#c4a7e7,stroke:#6e6a86,color:#191724
style C fill:#c4a7e7,stroke:#6e6a86,color:#191724
style D fill:#c4a7e7,stroke:#6e6a86,color:#191724
style E fill:#f6c177,stroke:#6e6a86,color:#191724
style F fill:#f6c177,stroke:#6e6a86,color:#191724
style G fill:#9ccfd8,stroke:#6e6a86,color:#191724
style H fill:#9ccfd8,stroke:#6e6a86,color:#191724

First signs of life

The moment I’ll remember is the grey rectangle. “Clone Desktop” in the center, a dock at the bottom with colored squares. I’d been at it for hours, wrestling with UniFFI bindings and layout math, and suddenly there it was: pixels on screen, drawn by Swift code, pushed through a Rust GPU backend, on something that was decidedly not macOS.

Day one: a grey box, a label, and a dock. It's not much, but it compiles and renders.

Settings and Finder

Once the basic views worked (stacks, text, lists, navigation), I needed something real to throw at them. Settings was a natural first target: sidebars, forms, toggles, text fields, the kind of layout variety that breaks things fast. Finder came next because browsing a directory with List and ForEach is such a fundamental SwiftUI pattern that if it didn’t work, nothing would.

Settings showing Wi-Fi preferences alongside Finder browsing the home directory. Both are SwiftUI apps running through Clone's stack.

Dark mode just kind of happened. Once I shimmed NSAppearance and implemented the semantic color system (Color.primary, .secondary, the system grays), flipping between light and dark was a toggle. A small thing, but unreasonably satisfying: it made the whole experiment feel like a real desktop for the first time.

The same Settings app in light mode. Appearance switching works through the reimplemented NSAppearance and Color system.

Tunes

This was the whole point, remember? “What would it take to make Tunes build and run on Linux?” Well, it builds. The login sheet renders inside the app window rather than as a separate NSPanel (a compromise, but not a terrible one), and the SwiftUI code is essentially unchanged. TextField, SecureField, Toggle, Button, Link: they all resolve and render. Same source, different universe.

Tunes running its login flow through Clone. The sheet renders in-window rather than as a separate panel, one of many compromises.

Leela

Leela is a management dashboard for Woosmap services: tabs, lists, nested navigation, version selectors, deploy queues. Most of the UI is driven by API responses, so it hammers ForEach with dynamic data, @StateObject, and conditional rendering. If Settings was a stroll through the park, Leela was a stress test.

Leela's services view running through Clone. Tabs, lists, version badges, sidebar navigation, all SwiftUI, all reimplemented.

I won’t pretend it was smooth. Getting here meant implementing a surprising amount of SwiftUI’s surface area. The state management system alone (StateGraph, scoped identity for ForEach, call-index disambiguation) went through several iterations where everything would render once and then silently stop updating. The kind of bug where you stare at a diff for an hour before realizing a closure captured a copy instead of a reference.

Under the hood

Text rendering

Text goes through cosmic-text for shaping, then gets rasterized into a 4096x4096 glyph atlas (single-channel, R8). Each glyph is cached and rendered as an instanced GPU quad. Fonts are bundled: Inter for UI text, Phosphor for icons.

This is almost certainly not how Apple does it. A real system would share GPU textures between the compositor and app, or pull from a system font cache. But it works, and there’s a special joy in watching a glyph atlas fill up character by character as the UI renders for the first time.

Layout

I reverse-engineered SwiftUI’s layout by reading objc.io’s thinking-in-swiftui and a lot of trial and error. The model: parents propose a size to children, children report back what they need, parents position them. Sounds simple until ZStack enters the picture: nil-sized views from .background() modifiers would expand to fill constraints and eat space from real siblings. That one took a while.

ScrollView was another head-scratcher: it fills its proposed size but lays out content unbounded in the scroll axis. Getting that inversion right, where the container constrains in one direction and is infinite in the other, broke my mental model twice before clicking.

IPC

Each app is a separate process. The compositor (CloneDesktop) runs the Rust event loop and manages surfaces. Apps connect over a Unix socket at /tmp/clone-compositor.sock and exchange length-prefixed JSON messages. There’s an annoying CGFloat-to-Float conversion at the wire boundary: Swift thinks in 64-bit coordinates, the GPU thinks in f32, and someone has to reconcile that at the border.

The `ycodebuild` trick

This is probably my favorite hack in the project. To compile an existing macOS app against Clone instead of Apple’s frameworks, ycodebuild generates a shadow SPM package that maps import SwiftUI to Clone’s SwiftUI, import AppKit to Clone’s shims, and so on. The app source code doesn’t change at all: you just build against a different package graph, and the compiled binary talks to the compositor over the socket. The same .swift file, two completely different platforms.

Honest assessment

I should be upfront about the gap between “it renders” and “it works.”

Animations are mostly stubbed. Accessibility is nonexistent. The compositor redraws every surface every frame like it’s 1997. There are // TODO: implement scattered across the codebase where AppKit APIs return no-ops and hope nobody notices. Sheets render in-window because I never built the panel system. The glyph atlas will fall over the moment someone opens a CJK document.

And (this is the awkward part) it doesn’t actually run on Linux yet. The whole premise was “what would it take,” and the answer turned out to include some Apple framework dependencies I haven’t replaced with their open-source equivalents. It’s doable. It’s just not done.

But here’s the thing that caught me off guard. The time from that initial Claude prompt to a state where Tunes and Leela compile and render recognizable UI was hours, not weeks. Not autonomous AI magic (plenty of manual fixes and architectural decisions along the way) but Claude carried an enormous amount of boilerplate: generating 50 View type stubs, wiring up modifier chains, implementing the state graph, setting up IPC. The kind of work that would’ve taken me days of tedious typing, compressed into a conversation.

Why this matters (a little)

Apple open-sourcing Swift and Foundation was a bigger deal than most people realize. Not because anyone’s going to ship a SwiftUI app on Linux tomorrow, but because it lowered the floor for experiments like this from “completely impossible” to “merely impractical.”

The projects I admired growing up (GNUStep, Haiku, Wine) were built by small teams reverse-engineering closed systems over years. The combination of open-source language infrastructure and AI assistance compresses that timeline dramatically. Not to a point where it’s practical or production-ready, but to a point where a single person can explore the shape of the problem in a weekend.

That’s the real takeaway. Not “I ported macOS to Linux.” I didn’t. But I went from a throwaway prompt to colored boxes on screen running real SwiftUI app code, and that felt like something worth writing about.

What’s next

Honestly? Probably nothing. The project scratched a twenty-year itch. But I know myself, and I know there’s a Kawase blur pipeline sitting unused in the renderer that’s going to call my name at 11pm some Tuesday. If I do keep going:

Per-window offscreen textures: the compositor shouldn’t redraw everything every frame, that’s embarrassing
Glassmorphism / backdrop blur: because what’s the point of reimplementing macOS if you can’t have the frosted glass
Actually running on Linux: the whole original premise, still unfinished
Shared GPU textures: how a real compositor would work, instead of copying pixels through a socket like an animal

Or maybe it stays as a weekend experiment and a blog post. Either way, the kid who thought GNUStep was the coolest thing ever is pretty happy right now.

Full-text search and lyrics in a Go music server

Wed, 18 Feb 2026 18:00:00 +0200

The Tunes server started as a way to stream my music library from a Raspberry Pi. It’s accumulated features since then. Two recent additions changed how I interact with it day-to-day: accent-insensitive full-text search across the entire library, and lyrics, both embedded from audio files and fetched from LRClib.

The search problem

Searching a music library is harder than it sounds. You want “bjork” to match “Björk”. You want “cafe” to match “Café”. You want “creme” to match “Crème Brûlée” in an album title. And you want it fast enough that results appear as you type.

The previous search was a LIKE query with wildcards. It worked, but it couldn’t handle diacritics and got slow on a 15,000-track library with multi-column matches.

FTS5 with unicode61

SQLite’s FTS5 extension does exactly what we need. The unicode61 tokenizer with remove_diacritics 2 strips all Unicode diacritical marks during indexing and querying:

tunes/search_fts.go: FTS5 table creation

func (s *SearchFTS) InitializeFTS() error {
 createSQL := `
 CREATE VIRTUAL TABLE IF NOT EXISTS tracks_fts USING fts5(
 track_id UNINDEXED,
 name,
 artist,
 album_artist,
 album,
 composer,
 genre,
 tokenize='unicode61 remove_diacritics 2'
 )`
 if err := s.db.Exec(createSQL).Error; err != nil {
 if strings.Contains(err.Error(), "no such module: fts5") {
 Sugar.Warn("FTS5 module not available - search will be disabled.")
 s.fts5Available = false
 return nil
 }
 return fmt.Errorf("failed to create FTS5 table: %w", err)
 }
 s.fts5Available = true
 return nil
}

track_id UNINDEXED stores the ID in the FTS table for joins but doesn’t tokenize it. If FTS5 isn’t compiled into the SQLite build, search degrades gracefully instead of crashing.

The index rebuilds atomically in a transaction: delete all FTS data, repopulate from the tracks table using COALESCE for NULL safety:

tunes/search_fts.go: index rebuild

func (s *SearchFTS) RebuildIndex(ctx context.Context) error {
 return s.db.WithContext(ctx).Transaction(func(tx *gorm.DB) error {
 if err := tx.Exec("DELETE FROM tracks_fts").Error; err != nil {
 return fmt.Errorf("failed to clear FTS table: %w", err)
 }
 populateSQL := `
 INSERT INTO tracks_fts (track_id, name, artist, album_artist,
 album, composer, genre)
 SELECT track_id, COALESCE(name, ''), COALESCE(artist, ''),
 COALESCE(album_artist, ''), COALESCE(album, ''),
 COALESCE(composer, ''), COALESCE(genre, '')
 FROM i_tunes_tracks WHERE deleted_at IS NULL`
 return tx.Exec(populateSQL).Error
 })
}

Query building

User queries are split into words, each gets a * suffix for prefix matching, and they’re joined with implicit AND. FTS5 special characters are stripped to prevent injection:

tunes/search_fts.go: query sanitization

func buildFTSQuery(query string) string {
 words := strings.Fields(strings.TrimSpace(query))
 var parts []string
 for _, word := range words {
 escaped := escapeFTSToken(word)
 if escaped != "" {
 parts = append(parts, escaped+"*")
 }
 }
 return strings.Join(parts, " ")
}

func escapeFTSToken(token string) string {
 var result strings.Builder
 for _, r := range token {
 switch r {
 case '"', '*', '^', '(', ')', '{', '}', '[', ']', ':', '-':
 continue
 default:
 result.WriteRune(r)
 }
 }
 return result.String()
}

Typing “aphex win” becomes aphex* win*, which matches “Aphex Twin” via prefix expansion. Typing “cafe del” matches “Café Del Mar” because the tokenizer already stripped the accent at index time.

Unified search endpoint

The /search?q= endpoint returns artists, albums, and tracks in a single response, each ranked independently by BM25:

tunes/search_handler.go

type UnifiedSearchResponse struct {
 Artists []ArtistInfo `json:"artists"`
 Albums []AlbumInfo `json:"albums"`
 Tracks []ITunesTrack `json:"tracks"`
}

func (ls *LibraryService) HandleSearch(w http.ResponseWriter, r *http.Request) {
 query := strings.TrimSpace(r.URL.Query().Get("q"))
 artists := ls.searchArtistsFTS(ctx, repo, query, 5)
 albums := ls.searchAlbumsFTS(ctx, repo, query, 10)
 tracks := ls.searchTracksFTS(ctx, repo, query, 30)
 // ...
}

Each section queries specific FTS5 columns. Artist search hits both artist and album_artist, then merges and aggregates. The BM25 scoring comes from FTS5’s built-in function:

SELECT track_id, bm25(tracks_fts) as rank
FROM tracks_fts
WHERE tracks_fts MATCH ?
ORDER BY rank
LIMIT ?

BM25 order is preserved through joins by building a track map and reordering after the GORM query:

tunes/search_handler.go: preserving BM25 order

trackMap := make(map[int]ITunesTrack, len(tracks))
for _, t := range tracks {
 if t.TrackID != nil {
 trackMap[*t.TrackID] = t
 }
}
ordered := make([]ITunesTrack, 0, len(trackIDs))
for _, id := range trackIDs {
 if t, ok := trackMap[id]; ok {
 ordered = append(ordered, t)
 }
}

Album search uses a two-stage approach: FTS returns track IDs, those map to album_key, then the album_cache table provides pre-aggregated album metadata. This avoids re-aggregating album info on every search.

Lyrics from audio files

The music scanner already walks the filesystem to index tracks using github.com/dhowden/tag. Adding lyrics extraction was a matter of probing the right metadata keys:

tunes/music_scanner.go: lyrics extraction

func (ms *MusicScanner) extractLyricsFromMetadata(rawMetadata any) *ExtractedLyrics {
 var lyrics ExtractedLyrics
 switch raw := rawMetadata.(type) {
 case map[string]any:
 for _, key := range []string{
 "lyrics", "USLT", "unsynchronised_lyrics",
 "unsynced_lyrics", "LYRICS", "\xa9lyr",
 } {
 if val, ok := raw[key]; ok {
 switch v := val.(type) {
 case string:
 if v != "" { lyrics.PlainLyrics = v }
 case []byte:
 if len(v) > 0 { lyrics.PlainLyrics = string(v) }
 }
 }
 }
 // Also check SYLT for synchronized lyrics
 for _, key := range []string{"SYLT", "synchronised_lyrics", "synced_lyrics"} {
 // ... same pattern
 }
 }
 return &lyrics
}

USLT is the ID3v2 unsynchronized lyrics frame, "\xa9lyr" is the M4A/AAC lyrics atom, SYLT is synchronized (timestamped) lyrics. The scanner handles both plain text and timestamped LRC format.

LRClib integration

For tracks without embedded lyrics, the server fetches from LRClib, a free, open lyrics database with synced timestamps.

The lyrics service uses golang.org/x/time/rate to respect API limits:

tunes/lyrics_service.go

const (
 lrcLibBaseURL = "https://lrclib.net/api"
 lrcLibUserAgent = "Tunes/1.0 (https://github.com/manz/tunes-server)"
 lrcLibRateLimit = 2
)

func NewLyricsService(db *gorm.DB) *LyricsService {
 return &LyricsService{
 repo: NewLyricsRepository(db),
 httpClient: &http.Client{Timeout: 15 * time.Second},
 rateLimiter: rate.NewLimiter(rate.Limit(lrcLibRateLimit), 1),
 }
}

When fetching, the service validates that the returned lyrics match the track’s duration within 5 seconds. This prevents mismatches: same song title by different artists, live vs studio versions:

tunes/lyrics_service.go: duration tolerance

if duration > 0 && lrcResponse.Duration > 0 {
 if math.Abs(float64(duration)-lrcResponse.Duration) > durationTolerance {
 return nil, ErrLyricsNotFound
 }
}

The handler implements fetch-through caching: check the database first, if miss then fetch from LRClib, save, and return. No external call on subsequent requests for the same track.

Lyrics are stored with GORM’s FirstOrCreate + Assign for clean upserts:

tunes/lyrics_repository.go

func (r *LyricsRepository) SaveLyrics(ctx context.Context, lyrics *TrackLyrics) error {
 return r.db.WithContext(ctx).
 Where(TrackLyrics{TrackID: lyrics.TrackID}).
 Assign(TrackLyrics{
 LRCLibID: lyrics.LRCLibID,
 Instrumental: lyrics.Instrumental,
 PlainLyrics: lyrics.PlainLyrics,
 SyncedLyrics: lyrics.SyncedLyrics,
 Source: lyrics.Source,
 }).
 FirstOrCreate(lyrics).Error
}

Background enrichment

A POST /lyrics/enrich endpoint triggers a goroutine that processes tracks without lyrics in batches of 50. It finds un-enriched tracks with a LEFT JOIN:

tunes/lyrics_repository.go: finding tracks without lyrics

err := r.db.Joins(
 "LEFT JOIN track_lyrics ON i_tunes_tracks.track_id = track_lyrics.track_id",
).Where("track_lyrics.id IS NULL").
 Where("i_tunes_tracks.deleted_at IS NULL").
 Limit(limit).
 Find(&tracks).Error

Rate-limited at 2 requests per second, a 15,000-track library takes a few hours to fully enrich. The mutex prevents concurrent enrichment runs:

tunes/lyrics_service.go: single-flight enrichment

func (s *LyricsService) StartBackgroundEnrichment(ctx context.Context, ...) {
 s.mu.Lock()
 if s.isEnriching {
 s.mu.Unlock()
 return
 }
 s.isEnriching = true
 s.mu.Unlock()

 go func() {
 defer func() { s.mu.Lock(); s.isEnriching = false; s.mu.Unlock() }()
 tracks, _ := s.repo.GetTracksWithoutLyrics(ctx, 50)
 // ... process batch, respect rate limiter
 }()
}

Admin via sudoers

The authorization model is Unix-inspired. Instead of a boolean is_admin on the User model, there’s a dedicated sudoers table with audit trail:

tunes/models.go

type Sudoer struct {
 ID int `gorm:"primaryKey;autoIncrement"`
 UserID int `gorm:"column:user_id;uniqueIndex;not null"`
 GrantedBy int `gorm:"column:granted_by;not null"`
 GrantedAt time.Time `gorm:"autoCreateTime"`
 ExpiresAt *time.Time `gorm:"column:expires_at"`
 Active bool `gorm:"column:active;default:true"`
}

Destructive operations (deleting tracks, managing users) additionally require a sudo token, obtained by re-authenticating via WebAuthn passkey. Two-step elevation: request a challenge, prove you’re you, get a time-limited token. This prevents a stolen session from doing real damage.

Routes use higher-order functions for auth gating:

cmd/tunes-server/main.go

func sudoerRoute(authMiddleware func(http.Handler) http.Handler,
 authService *AuthService) func(http.HandlerFunc) http.Handler {
 return func(handler http.HandlerFunc) http.Handler {
 return authMiddleware(requireSudoerMiddleware(authService)(handler))
 }
}

The first user must be created via CLI before the server starts: tunes-server users add <username> --sudoer. No web-based registration for the initial admin. You need shell access.

What changed

The server went from “stream my library” to “actually find what I want to play.” FTS5 with accent stripping makes search work the way you’d expect: type a rough approximation of the artist name, get the right results. Lyrics with synced timestamps let the iOS app show karaoke-style scrolling text. Background enrichment means I didn’t have to manually tag anything. It just filled in over a couple of evenings.

Still no replacement for Apple Music’s catalog. But for my 15,000 tracks, it works better than iTunes Match ever did.

Calculon part 2: costing profiles, performance, and maneuvers

Wed, 18 Feb 2026 10:00:00 +0200

Why can't I move on?

Part 1 covered the basics: six crates, Valhalla’s tile format, a driving cost model, bidirectional A*, many-to-many matrix, and an Axum HTTP server. Everything worked for the driving case on the Monaco dataset.

Since then, the engine gained bicycle and pedestrian costing, memory-mapped tiles, a comparison webapp, turn-by-turn directions in 34 languages, and enough performance work to make it usable on France-scale data. This is what changed.

Bicycle and pedestrian costing

Two new cost models implement the DynamicCost trait alongside the existing AutoCost.

Bicycle defaults to 18 kph (hybrid bike). The model factors in grade, road stress, surface quality, and turn costs, all lighter than auto because a cyclist doesn’t mind a left turn as much as a driver crossing oncoming traffic.

Grade uses a Tobler-style speed table. Flat terrain is 1.0x; steep downhill goes up to 2.2x; steep uphill drops to 0.3x. Hill avoidance is a separate preference (use_hills) that applies an additional penalty on grades regardless of the speed adjustment.

The interesting part is road stress, how comfortable a road is to cycle on:

crates/calculon-costing/src/bicycle_cost.rs

fn accommodation_factor(&self, edge: &DirectedEdge) -> f32 {
 let use_type = edge.use_type();
 if use_type == Use::Cycleway as u32 || use_type == Use::MountainBike as u32 {
 return 0.0;
 }
 match edge.cycle_lane() {
 CycleLane::Separated => 0.0,
 CycleLane::Dedicated => 0.1,
 CycleLane::Shared => 0.3,
 CycleLane::None => {
 if edge.bike_network() { 0.2 }
 else if edge.shoulder() { 0.5 }
 else { 1.0 }
 }
 }
}

A separated cycle lane costs nothing extra. A shared lane adds 0.3. No accommodation at all on a road that’s not part of any bike network costs 1.0, scaled by the use_roads preference. Combined with ROAD_CLASS_FACTOR that penalizes trunk roads (0.8) vs residential (0.0), the engine steers cyclists toward quieter streets with bike infrastructure.

Pedestrian defaults to 5.1 kph. It adds SAC hiking scale (7-tier trail difficulty), a step penalty for stairs, lighting preference, and use-type bonuses for footways and sidewalks:

crates/calculon-costing/src/pedestrian_cost.rs

const GRADE_SPEED_FACTOR: [f32; 16] = [
 1.5, 1.4, 1.3, 1.15, 1.05, 1.0, // downhill: slightly faster
 1.0, 1.0, // flat
 0.95, 0.85, 0.75, 0.65, 0.55, 0.45, 0.4, 0.35, // uphill: slower
];

Both profiles make a critical architectural decision: they disable hierarchy entirely. The A* hierarchy transitions work by “jumping up” to highways as the search moves away from endpoints. That makes sense for driving: a 200km route shouldn’t expand residential streets in the middle. But for cycling and walking, the shortcut edges that power hierarchy are built for driving and would produce wrong routes. So bicycle and pedestrian stay on level 2 where all edges are accessible, trading search speed for correctness.

Memory-mapped tiles

The tile reader now uses mmap(2) instead of heap-allocated reads:

crates/calculon-tiles/src/graph_tile.rs

enum TileData {
 Owned(Vec<u8>), // Tests
 Mapped(Mmap), // Production
}

pub fn from_mmap(mmap: Mmap) -> Result<Self, TileError> {
 let base_ll = Self::validate(&mmap)?;
 Ok(GraphTile { data: TileData::Mapped(mmap), base_ll })
}

In the graph reader:

crates/calculon-tiles/src/graph_reader.rs

let file = std::fs::File::open(&path).map_err(TileError::Io)?;
let mmap = unsafe { Mmap::map(&file) }.map_err(TileError::Io)?;
let tile = Arc::new(GraphTile::from_mmap(mmap)?);

No heap allocation, no copy. The OS page cache handles eviction. The old application-level LRU cache became unnecessary. Tiles are cheap Arc pointers to mapped pages.

Thread-local tile cache

Routing makes thousands of get_tile calls per search. Even a RwLock on a HashMap adds up. The solution is a three-level cache:

crates/calculon-tiles/src/graph_reader.rs

thread_local! {
 static TL_CACHE: RefCell<FxHashMap<u32, Arc<GraphTile>>> =
 RefCell::new(FxHashMap::default());
}

pub fn get_tile(&self, id: &GraphId) -> Result<Arc<GraphTile>, TileError> {
 let tile_key = id.tile_value();

 // Level 1: thread-local (no synchronization, ~20ns)
 let hit = TL_CACHE.with(|c| c.borrow().get(&tile_key).cloned());
 if let Some(tile) = hit { return Ok(tile); }

 // Level 2: shared cache (RwLock, parallel readers)
 // ... insert into thread-local on hit

 // Level 3: mmap from disk, populate both caches
 // ...
}

The hot path (thread-local hit) is a plain HashMap lookup in a RefCell. No lock, no contention, no Arc::clone from the shared cache. FxHash (from rustc_hash) replaces std::HashMap everywhere, optimized for integer keys that don’t need cryptographic hashing.

Distance approximator

Edge snapping calls distance computations in a tight loop, projecting a point onto every nearby road segment. Haversine uses sin, cos, asin, sqrt per call. For relative comparisons within a small area, that’s overkill.

The DistanceApproximator pre-computes cos(lat) once and then uses only multiplications:

crates/calculon-core/src/geo.rs

pub struct DistanceApproximator {
 lng_scale: f64,
 meters_per_lng_degree: f64,
}

impl DistanceApproximator {
 pub fn new(ll: &PointLL) -> Self {
 let lng_scale = Self::lng_scale_per_lat(ll.lat);
 Self {
 lng_scale,
 meters_per_lng_degree: lng_scale * METERS_PER_DEGREE_LAT,
 }
 }

 pub fn distance_squared(&self, ll: &PointLL) -> f64 {
 let lat_m = (ll.lat - self.center_lat) * METERS_PER_DEGREE_LAT;
 let lng_m = (ll.lng - self.center_lng) * self.meters_per_lng_degree;
 lat_m * lat_m + lng_m * lng_m
 }
}

Construct one for the search point, reuse it across all segment projections. 26% faster in edge snapping benchmarks. The accuracy loss is negligible within a few kilometers, well within the range of any snap search.

Distance-adaptive hierarchy

Short urban routes were sometimes jumping to highways unnecessarily. A 2km trip through a city shouldn’t consider the nearby motorway just because the hierarchy said “expand to level 0 after 5,000 meters.”

The fix scales hierarchy limits proportionally to route distance:

crates/calculon-route/src/bidirectional_astar.rs

fn adjust_limits_for_distance(limits: &mut [HierarchyLimits], distance: f32) {
 // 5km route: expand_within_dist = 2500m, max_up_transitions = 11
 // 1km route: expand_within_dist = 2000m, max_up_transitions = 5
 // 20km+ route: no adjustment
}

A 5km route caps level-2 expansion at 2,500m and allows only 11 upward transitions (from 100 default). A 1km route drops to 5 transitions with a 2,000m cap. Routes above 15km keep the defaults. The search still finds the optimal path, it just doesn’t waste time on irrelevant highway segments for short trips.

A* heuristics in the cost matrix

The matrix previously used pure Dijkstra for each source/target pair: expand uniformly in all directions. Now each gets an A* heuristic aimed at its closest counterpart:

crates/calculon-matrix/src/cost_matrix.rs

let closest = targets.iter()
 .min_by(|a, b| {
 let da = src.distance(a);
 let db = src.distance(b);
 da.partial_cmp(&db).unwrap_or(std::cmp::Ordering::Equal)
 })
 .unwrap_or(&targets[0]);
h.init(closest, cost_factor);
self.heuristics_forward.push(h);

This steers each search toward likely connection points rather than expanding uniformly. Combined with Valhalla-style hierarchy and a path_dist_threshold set to 2x the max source-target distance, the matrix handles 9x9 urban grids without exploring the entire region.

Turn-by-turn maneuvers

The first version returned routes with “Start” and “Arrive” stubs. Now there’s a proper maneuver builder that groups consecutive edges into instructions.

The builder triggers a new maneuver on name changes, significant turns, road type transitions (roundabouts, ramps, ferries):

crates/calculon/src/maneuver_builder.rs

fn should_start_new_maneuver(&self, in_roundabout: bool) -> bool {
 self.entering_roundabout
 || self.exiting_roundabout
 || self.entering_ramp
 || self.exiting_ramp
 || self.entering_ferry
 || self.exiting_ferry
 || self.turn_type == TurnType::Reverse
 || (self.name_changed && !in_roundabout)
 || (self.turn_type != TurnType::Straight && self.name_changed)
}

Narrative generation uses rust-i18n with 34 locale files. Each maneuver type maps to a template:

locales/en-US.yml

start.5: "Drive %{cardinal_direction} on %{street_names}."
turn.1: "Turn %{relative_direction} onto %{street_names}."
enter_roundabout.2: "Enter the roundabout and take the %{ordinal_value} exit onto %{roundabout_exit_street_names}."
destination.0: "You have arrived at your destination."

Roundabouts track exit counts. Cardinal directions derive from heading. Ordinals support up to the 10th exit. The locale files include French, German, Spanish, Italian, and (yes) pirate English.

Edge snapping improvements

Snapping a coordinate to the road network was one of the weaker points. Two fixes:

Multi-tile search. When a point falls near a tile boundary, the search now checks neighboring tiles in all 8 directions:

crates/calculon-route/src/bidirectional_astar.rs

let near_south = point.lat - bbox.min_pt.lat < TILE_BOUNDARY_MARGIN;
let near_north = bbox.max_pt.lat - point.lat < TILE_BOUNDARY_MARGIN;
// ... check all 8 directions
for (i, &(dlng, dlat)) in offsets.iter().enumerate() {
 if !flags[i] { continue; }
 let neighbor_id = TileHierarchy::get_graph_id(&neighbor_pt, level);
 if let Ok(tile) = reader.get_tile(&neighbor_id) {
 let candidates = tile.find_closest_edges(point, access_mask, ...);
 all.extend(candidates);
 }
}

Smarter candidate pruning. Post-collection, candidates beyond min_distance * 3.0 (minimum 25m threshold) are pruned, then select_nth_unstable_by does an O(N) partition instead of a full sort. Only the top K candidates get sorted.

All My Circuits

A Lit + TypeScript + MapLibre GL webapp for side-by-side comparison with Valhalla. Route and matrix modes, all three costing profiles, Valhalla comparison with percentage diffs on time and distance, resizable sidebar, URL state persistence, clickable matrix routes in verbose mode, and links to Google Maps and HERE for sanity checking.

The debug mode loads per-edge data (speed, density, road class, costs) so you can see exactly why the engine chose one road over another. The inspect endpoint visualizes tile-level node and edge data for when things really go wrong.

Criterion benchmarks

Benchmarks run against France tiles across four crates:

Tiles: cache hit (~20ns thread-local), cold load (mmap), edge traversal
Costing: single edge cost, transition cost, access check
Routing: 5km urban, 55km regional, 240km long-distance
Matrix: 1x1, 4x4 coastal, 9x9 urban

A separate bench runner does HTTP-level comparison against Valhalla, reporting p50/p95/p99 latencies and route cost/distance diffs. Useful for regression testing and for validating that the cost model matches Valhalla’s output within acceptable margins.

Where it stands

The engine handles France-scale data with three costing profiles. Routes match Valhalla on the scenarios I’ve tested. Turn-by-turn directions work in 34 languages. The matrix scales to 9x9 with A* heuristics. Performance is good enough for a single-server deployment.

What’s new since part 1:

Bicycle and pedestrian cost models
Memory-mapped tiles with thread-local cache
FxHash everywhere, DistanceApproximator for snapping (26% faster)
Distance-adaptive hierarchy limits
A* heuristics in the cost matrix
Turn-by-turn maneuvers with localized narrative in 34 languages
Multi-tile edge snapping
Criterion benchmarks and a Valhalla comparison webapp

What’s still ahead:

Isochrones: reachability polygons from a point within a time/distance budget
Contraction hierarchies: the hierarchy transitions help but true CH preprocessing would unlock cross-Europe routes at acceptable latency
Via points: multi-leg routes with intermediate stops

Building a routing engine in Rust

Sat, 14 Feb 2026 10:00:00 +0200

Why can't I move on?

A routing engine in Rust. Bidirectional A*, many-to-many distance matrices, Valhalla-compatible API. Six crates, about 8,000 lines.

Why

We use Valhalla for routing and distance matrices at Woosmap. It works most of the time. When it doesn’t, we’re stuck. We treat it as a black box: file an issue, upgrade, hope the next release fixes things. When the matrix returns wrong costs for certain edge cases or the engine routes you through someone’s driveway, there’s no realistic way for us to dig in. It’s a massive C++ codebase that assumes you’ve been living in it for years.

The goal is to replace Valhalla entirely for our use case: routing, distance matrices, and isochrones, with driving, cycling, and walking profiles. Not fork it, not wrap it. Rewrite the parts we need in Rust so we can actually own the thing.

Architecture

Six crates in a Cargo workspace:

calculon/
├── calculon-core # Foundation types: coordinates, graph IDs, constants
├── calculon-tiles # Binary tile reader: nodes, edges, transitions
├── calculon-costing # Cost models: auto/driving with turn penalties
├── calculon-route # Bidirectional A* pathfinding
├── calculon-matrix # Many-to-many distance matrix
└── calculon # HTTP server: Axum handlers, Valhalla-compatible API

The HTTP layer at the top is thin: parse JSON, call the algorithm, format the response. Everything interesting happens in the middle crates.

Tile-based graph

The road network lives in binary tiles, same format Valhalla uses. Nodes are intersections, directed edges are road segments, edge info holds geometry and names, node transitions connect tiles to each other.

crates/calculon-tiles/src/graph_tile.rs

pub fn from_bytes(data: Vec<u8>) -> Result<Self, TileError> {
 if data.len() < size_of::<GraphTileHeader>() {
 return Err(TileError::TooSmall {
 size: data.len(),
 min: size_of::<GraphTileHeader>(),
 });
 }

 let header = unsafe { &*(data.as_ptr() as *const GraphTileHeader) };

 if header.end_offset() as usize != data.len() {
 return Err(TileError::SizeMismatch {
 header_size: header.end_offset() as usize,
 actual_size: data.len(),
 });
 }

 let base_ll = header.base_ll();
 Ok(GraphTile { data, base_ll })
}

/// Get the node at a given index.
pub fn node(&self, index: u32) -> Option<&NodeInfo> {
 if index >= self.header().nodecount() {
 return None;
 }
 let offset = size_of::<GraphTileHeader>() + index as usize * size_of::<NodeInfo>();
 Some(unsafe { &*(self.data[offset..].as_ptr() as *const NodeInfo) })
}

No deserialization, just pointer casting into the raw bytes. The tile is a flat buffer with a header followed by fixed-size node and edge records at known offsets. Fast, but the crate refuses to compile on big-endian targets because the byte layout has to match.

GraphReader sits on top of an LRU cache. Algorithm needs an edge in some tile? Check the cache, load the file if it’s not there, hand back an Arc<GraphTile>. Default cache holds 200 tiles, which covers most regional queries without touching disk twice.

Reusing Valhalla’s tile format was a big shortcut. Designing a graph format from scratch would have been a project in itself.

Cost model

This is where routing gets interesting, and where most bugs hide. The cost model decides how expensive each road segment is to traverse. Not just distance. Time, comfort, how annoying a particular turn is. The values here are derived from Valhalla’s own cost model. No point reinventing what they’ve already calibrated.

crates/calculon-costing/src/auto_cost.rs

const RIGHT_SIDE_TURN_COSTS: [f32; 8] = [
 0.5, // Straight
 0.75, // SlightRight
 1.0, // Right (favorable)
 1.5, // SharpRight (favorable-sharp)
 9.5, // Reverse
 3.5, // SharpLeft (unfavorable-sharp)
 2.5, // Left (unfavorable, crosses oncoming traffic)
 0.75, // SlightLeft
];

const LEFT_SIDE_TURN_COSTS: [f32; 8] = [
 0.5, // Straight
 0.75, // SlightRight
 2.5, // Right (unfavorable)
 3.5, // SharpRight (unfavorable-sharp)
 9.5, // Reverse
 1.5, // SharpLeft (favorable-sharp)
 1.0, // Left (favorable)
 0.75, // SlightLeft
];

Two tables: one for right-side driving countries (France, US), one for left-side (UK, Japan). In France, a left turn crosses oncoming traffic so it costs more. In the UK, it’s the right turn. Get this wrong and the engine starts suggesting weird U-turn loops to avoid a simple left.

The rest of the cost model:

Speed factors: pre-computed 3.6 / speed_kph lookup table, seconds per meter at each speed
Highway preference: a slider from -1.0 to 1.0, push it high and the engine prefers motorways
Surface penalties: gravel costs more than asphalt
Intersection density: dense urban intersections add delay, factors range from 1.0 up to 3.5
Toll booths: flat time penalty per crossing
Traffic signals: extra delay at signalized intersections

All of this is pre-computed into lookup tables at startup. During search, computing the cost of an edge is just array indexing.

The algorithm finds a shortest path. The cost model decides whether that path makes any sense to a human driver. Same constants Valhalla uses, but now in code we can read and step through when something looks off.

Bidirectional A*

Two search trees grow at the same time: one forward from the origin, one backward from the destination. They meet somewhere in the middle.

crates/calculon-route/src/bidirectional_astar.rs

pub struct BidirectionalAStar {
 edgelabels_forward: Vec<BDEdgeLabel>,
 edgelabels_reverse: Vec<BDEdgeLabel>,

 adjacencylist_forward: DoubleBucketQueue,
 adjacencylist_reverse: DoubleBucketQueue,

 edgestatus_forward: EdgeStatus,
 edgestatus_reverse: EdgeStatus,

 heuristic_forward: AStarHeuristic,
 heuristic_reverse: AStarHeuristic,

 cost_diff: f32,
 cost_threshold: f32,
 best_connections: Vec<CandidateConnection>,
 // ...
}

Everything is doubled: edge labels, priority queues, edge status, heuristics. The heuristic is geographic distance to the opposite endpoint. Simple, admissible, good enough.

The priority queue is a double-bucket structure: coarse outer buckets, fine inner buckets. Turns out a binary heap isn’t great for routing because the cost values cluster in narrow ranges. Buckets handle that better.

The search stops when the best connection found so far, plus a 420-second buffer, exceeds the cheapest item in either queue. That buffer lets it keep looking for slightly better paths after the first connection without searching forever.

Hierarchy transitions help a lot. Near the endpoints, the search considers local roads. As it moves away, it “jumps up” to highways and trunk roads. In the middle of a long route, there’s no point expanding residential streets. This cuts the number of edges explored dramatically.

Many-to-many matrix

A 50x50 distance matrix done naively (individual route for each pair) means 2,500 searches. That’s not going to work.

The trick: expand all sources forward simultaneously, all targets backward simultaneously, and watch for collisions. When source i’s forward search reaches an edge that target j’s reverse search already touched, that’s a connection.

crates/calculon-matrix/src/cost_matrix.rs

pub struct CostMatrix {
 edgelabels_forward: Vec<Vec<BDEdgeLabel>>,
 queues_forward: Vec<DoubleBucketQueue>,
 edgestatus_forward: Vec<EdgeStatus>,

 edgelabels_reverse: Vec<Vec<BDEdgeLabel>>,
 // ...
}

Each source and target gets its own labels, queue, and status set, but they all walk the same graph. A ReachedMap (basically a HashMap<edge_id, Vec<location_index>>) tracks who’s been where. When a forward expansion hits an edge in the reverse map, we record the connection cost.

Result is an N*M grid of time/distance values. Some cells might be unreachable. The whole thing caps at 2 million iterations so it doesn’t run forever on disconnected graphs.

HTTP server

Three endpoints on Axum, matching Valhalla’s JSON format so existing clients can point at Calculon without code changes.

crates/calculon/src/server.rs

pub fn build_router(state: Arc<AppState>) -> Router {
 Router::new()
 .route("/route", post(handler_route::handle_route))
 .route("/sources_to_targets", post(handler_matrix::handle_matrix))
 .route("/status", get(handler_status::handle_status))
 .layer(CorsLayer::permissive())
 .with_state(state)
}

Route and matrix searches are CPU-bound: they can block for hundreds of milliseconds on a big query. They run on Tokio’s blocking thread pool via spawn_blocking so they don’t starve the async runtime.

Each request gets a CancelGuard backed by an AtomicBool. Client disconnects? The guard drops, sets the flag, and the algorithm checks it periodically and bails out. Seemed like overkill at first, but it matters when someone fires off a matrix request and immediately refreshes the page.

A route request:

{
 "locations": [
 {"lat": 43.731, "lon": 7.419},
 {"lat": 43.696, "lon": 7.271}
 ],
 "costing": "auto",
 "costing_options": {"auto": {"use_highways": 0.8}},
 "units": "kilometers"
}

Response comes back with a polyline6-encoded shape, total time, distance, bounding box, and some basic maneuvers (though the maneuvers are stubs for now, just “Start” and “Arrive”).

Where it stands

Driving works. Routes match Valhalla’s output on the Monaco dataset. The matrix handles concurrent requests with cancellation. The server drops in behind the same API.

What’s there:

Driving cost model with turns, highways, surface, density, tolls
Bidirectional A* with hierarchy transitions
Many-to-many matrix via simultaneous bidirectional Dijkstra
Valhalla-compatible REST API
LRU tile caching with memory-mapped I/O
Cooperative request cancellation
Tests against Monaco dataset

What’s left to reach parity:

Cycling and walking profiles: the cost model is structured for it, but only driving is implemented so far.
Isochrones: reachability polygons from a point within a time/distance budget. The search infrastructure is there, the polygon generation isn’t.
Turn-by-turn directions: maneuvers are stubs. Real maneuver generation needs street names, instruction templates, sign data.
Contraction hierarchies: the A* is fine for regional routes but CH would be needed for cross-country at acceptable latency.
Multi-leg routes: only origin to destination, no via points yet.

About 8,000 lines across six crates. The driving case works end to end. Cycling, walking, and isochrones are what’s between this and actually replacing Valhalla.

Tree: a browser that remembers where you came from

Tue, 10 Feb 2026 10:00:00 +0200

Every browser has tabs. Linear, flat, disposable. Open thirty of them researching one topic and they sit in a row with no indication that twelve of them came from the same Wikipedia article. Close the wrong one and the context is gone.

Tree is a macOS browser that replaces tabs with a tree. Every page knows its parent. Cmd+Click a link and it becomes a child node of the current page. The sidebar shows the full hierarchy: research paths branch naturally, and you can always trace back to where you started.

The data model

The core is a SwiftData model with a self-referential parent-child relationship:

Models/TreeNode.swift

@Model
final class TreeNode {
 #Unique<TreeNode>([\.nodeId])

 var nodeId: UUID
 var url: URL
 var title: String
 var faviconData: Data?
 var timestamp: Date
 var lastUsedAt: Date = Date()
 var weight: Int
 var isPinned: Bool
 var sortOrder: Int = 0

 @Relationship(inverse: \TreeNode.children)
 var parent: TreeNode?

 @Relationship(deleteRule: .cascade)
 var children: [TreeNode]
}

The cascade delete rule means pruning a node takes its entire subtree with it. No orphans. The parent/children relationship is bidirectional. SwiftData maintains both sides automatically through the inverse parameter.

Each node tracks a weight that increments on every visit, and an isPinned flag. These feed the search ranking:

var searchRank: Int {
 (weight * 2) + (isPinned ? 100 : 0)
}

Pinned nodes get a massive boost. Frequently visited pages float to the top. It’s a simple heuristic but it works: the pages you care about surface first.

Branching

The key interaction is branching: Cmd+Click a link and the browser creates a child node instead of navigating away. The parent shifts to the secondary panel, and the child becomes the primary:

State/NavigationState.swift

func selectFromBranch(_ child: TreeNode) {
 secondaryNode = primaryNode
 primaryNode = child

 child.incrementWeight()
 updateWebViewVisibility()
 saveLastSession()
}

This is where the tree structure pays off. You’re reading documentation, Cmd+Click a linked API reference, and now you see both side by side: the original page on the right, the reference on the left. The sidebar shows them as parent and child. Navigate back up the tree anytime with keyboard shortcuts.

Pinned nodes take this further. When a node is pinned, all navigation from it creates children, not just Cmd+Click. Pin your project’s docs landing page and every link you follow branches automatically, building a research tree without any extra effort.

WebView management

A browser can’t keep unlimited WebViews in memory. Tree uses an LRU cache that caps active WebViews at a configurable maximum (default 4):

WebKit/WebViewManager.swift

private func evictIfNeeded() {
 while activeWebViews.count >= maxActive {
 if let toEvict = accessOrder.first(where: { !visibleNodes.contains($0) }) {
 deallocate(toEvict)
 } else if let toEvict = accessOrder.first {
 deallocate(toEvict)
 } else {
 break
 }
 }
}

The eviction prefers invisible nodes. If both panels are showing WebViews, those are protected: the cache evicts the least recently accessed node that isn’t currently on screen. Only when everything is visible does it fall back to strict LRU order.

Before eviction, the WebView’s full browsing state gets persisted to disk.

State persistence

WebKit exposes interactionState, an opaque object that captures a WebView’s entire browsing state: history stack, scroll position, form data. Tree archives this to Application Support whenever a WebView is evicted, the app backgrounds, or the user closes a panel:

WebKit/WebViewStateManager.swift

func saveState(of webView: WKWebView, for nodeId: UUID) {
 guard let state = webView.interactionState else { return }

 let data = try NSKeyedArchiver.archivedData(
 withRootObject: state,
 requiringSecureCoding: false
 )
 let fileURL = stateFileURL(for: nodeId)
 try data.write(to: fileURL, options: .atomic)
}

When a node is revisited and needs a fresh WebView, the manager restores the archived state instead of loading the URL from scratch. The page appears exactly where the user left it: same scroll position, same back/forward history. The user never notices the WebView was recycled.

A cleanup pass on launch removes orphaned state files for nodes that no longer exist in the database.

The sidebar is a recursive SwiftUI tree. Session roots (nodes with no parent) appear at the top level. Each node with children renders as a DisclosureGroup with nested TreeNodeRow views:

Views/SidebarView.swift

@Query(filter: #Predicate<TreeNode> { $0.parent == nil })
private var sessionRoots: [TreeNode]

private var displayedNodes: [TreeNode] {
 let nodes = navigationState.contextualRoot?.children ?? sessionRoots
 return nodes.sorted { a, b in
 if a.isPinned != b.isPinned {
 return a.isPinned
 }
 return a.sortOrder < b.sortOrder
 }
}

Pinned nodes sort to the top. Below that, manual sort order (set via drag-and-drop reordering) controls the sequence.

Drag-and-drop also handles reparenting: drag a node onto another node and it becomes a child. The drop handler checks for cycles (you can’t drop a parent onto its own descendant) by walking up the target’s ancestry chain:

private func isDescendant(of ancestorId: UUID) -> Bool {
 var current: TreeNode? = node.parent
 while let parent = current {
 if parent.nodeId == ancestorId { return true }
 current = parent.parent
 }
 return false
}

Focus mode

A deep tree gets unwieldy. Focus mode lets you temporarily treat any node as the root: the sidebar shows only its children, and a breadcrumb bar at the top shows the path from the true root:

func focusBreadcrumbs() -> [TreeNode] {
 guard let root = contextualRoot else { return [] }
 var path: [TreeNode] = []
 var current: TreeNode? = root
 while let node = current {
 path.insert(node, at: 0)
 current = node.parent
 }
 return path
}

Click any breadcrumb to re-focus at that level, or click the home icon to unfocus entirely. The focus state persists across restarts via UserDefaults.

Ad blocking

Rather than building content blocking from scratch, Tree loads the full Ghostery browser extension via WebKit’s WKWebExtensionController API. Every WebView gets the extension controller attached to its configuration:

configuration.webExtensionController = WebExtensionManager.shared.controller

This gives you enterprise-grade tracker and ad blocking with zero maintenance. Ghostery handles its own filter list updates, UI (accessible via a toolbar popover), and persistent storage. The browser just loads the extension at startup and grants permissions.

Tree navigation is keyboard-driven. The tree structure maps to directional shortcuts:

Shortcut	Action
`Cmd+Shift+Up`	Go to parent node
`Cmd+Shift+Down`	Go to first child
`Cmd+Shift+Left`	Previous sibling
`Cmd+Shift+Right`	Next sibling
`Cmd+Shift+J`	Quick search overlay
`Cmd+T`	New session
`Cmd+W`	Close panel
`Cmd+Shift+W`	Prune node and subtree

The spatial metaphor works because the sidebar is a tree. Up means parent. Down means child. Left and right move between siblings. Once the mapping clicks, you rarely need the mouse for navigation.

Session restoration

On launch, the app restores the last active primary and secondary nodes, plus the focus state, from UserDefaults:

func restoreLastSession(from nodes: [TreeNode]) {
 let defaults = UserDefaults.standard
 let primaryIdString = defaults.string(forKey: Self.lastPrimaryKey)
 let secondaryIdString = defaults.string(forKey: Self.lastSecondaryKey)
 let contextualRootIdString = defaults.string(forKey: Self.contextualRootKey)

 // Match UUIDs to loaded TreeNodes and restore state...
}

Combined with WebView state persistence, a restart puts you back exactly where you were: same pages, same scroll positions, same split view layout, same focused subtree.

What it replaces

The thing it replaces isn’t another browser. It replaces the workflow of opening a dozen tabs, losing track of which ones are related, and eventually closing them all because you can’t remember what you were doing.

With Tree, the context is the structure. A research session about some API has the docs page as the root, the getting started guide as one branch, the API reference as another, and Stack Overflow answers as leaves. Close the app, come back tomorrow, and the tree is still there, with every page exactly where you left it.

Building a GPU map renderer from scratch

Tue, 10 Feb 2026 09:00:00 +0200

Building a vector map renderer in Rust with wgpu. From “everything renders as points” to a full style-driven renderer running on desktop, iOS, and the browser.

Why

We built our maps stack on top of Mapbox GL: the JS SDK, then native SDKs on the C++ core.

For static maps we wrapped the C++ SDK in a Python library (maparazzo). It worked but the C++ renderer leaked memory. OpenGL contexts kept state around after objects were destroyed. We tried pooling Map instances, reusing GL contexts. It helped but never fully solved it.

I wanted to understand every layer of the stack. What if we built a renderer from scratch, something we fully own, no inherited complexity from a massive C++ codebase?

Rust + wgpu seemed right. wgpu abstracts over Metal/Vulkan/DX12/WebGPU so you get native + browser from one codebase. Rust gives you memory safety without a GC. No more mystery leaks.

First pixels

Started from the wgpu-triangle example: a bare-bones triangle on screen. Built the stem by hand: tile fetching, MVT decoding, basic projection. From there I heavily leveraged Claude Code to help push through the harder parts and get it to where it is now.

Everything in one file. main.rs at 1,500 lines: MVT decoder, protobuf parser, renderer, tile fetching, all of it.

The MVT decoder is hand-rolled. No prost, no generated code. Protobuf is simple enough at the wire level: varints, length-delimited fields. The tile format uses a local coordinate grid (4096x4096 per tile) with delta-encoded geometry commands.

First render: every feature drawn as points. Polygons, lines, everything, just dots on screen. But dots in the right places.

Making it a real map

Extracted modules one by one. mvt.rs for tile decoding, renderer.rs for GPU work, tile_loader.rs for fetching, tile_coords.rs for slippy map math.

Added earcutr for polygon triangulation: it converts arbitrary polygons with holes into triangles the GPU can draw. First tessellation attempt produced spikes everywhere. The MVT spec requires rings to be closed but some tiles had implicit closure. Two-pass decode: first pass collects keys/values/feature ranges, second pass builds features with proper ring closing.

Background tile loading with worker threads and mpsc channels. Scroll zoom, mouse pan. Viewport buffer zone to pre-load surrounding tiles so panning feels instant.

Tessellation cache keyed by (TileCoord, layer_index, feature_index): earcut is expensive, no need to redo it when the camera moves.

Moving projection to the GPU

The big architectural decision. Originally the CPU converted every vertex from lon/lat to screen pixels. Camera move = rebuild all vertices = slow.

Flipped it: vertices store world lon/lat, the GPU shader does Web Mercator projection. Camera moves only update a 64-byte uniform buffer. Vertex data stays untouched.

center_mercator, scale, rotation, viewport_scale, aspect, viewport_size

This means mark_camera_dirty() for pan/zoom (cheap uniform upload), mark_geometry_dirty() only when tiles arrive or leave. Night and day difference for interactivity.

Style-driven rendering

A map renderer without style support is just a polygon viewer. Built an expression engine and style evaluator.

The expression engine handles the Mapbox style spec: get, has, match, case, interpolate, step, let/var, coalesce, arithmetic, string ops, comparisons. let/var was critical: Woosmap styles use variable bindings for i18n name resolution.

Filter compilation: both legacy ["==", "key", val] and modern ["==", ["get","key"], val] syntax.

The key insight for z-ordering: iterate style layers, not MVT layers. The style defines the draw order. For each style layer, find matching features across all tiles.

Background color comes straight from the style: just set the wgpu clear color.

Paris at different zoom levels, same style, same renderer, z4 to z16:



z4, country level	z8, region level

z12, city level	z16, street level

Lines

Lines in a GPU renderer are not trivial. A “line” on screen is actually a quad (two triangles) for each segment, with normals perpendicular to the direction. Line joins at vertices need special treatment.

Implemented miter, bevel, and round joins. Miter joins can spike to infinity at sharp angles, so clamp with a miter limit and fall back to bevel. Round joins emit a fan of triangles.

Line normals computed in Mercator space, not screen space, because of the GPU projection design. The shader transforms them correctly.

Icons and sprites

Sprite atlas: load {url}.json (metadata) + {url}.png (texture). Each icon is a region in the atlas with UV coordinates.

SDF (Signed Distance Field) rendering in the fragment shader. One shader handles both SDF sprites and regular RGBA sprites: the is_sdf field on each vertex switches behavior. SDF gives you clean scaling and halos at any size from a single texture.

Icon quads: 4 vertices + 6 indices per point. Screen-aligned: the anchor position projects through the map transform but pixel offsets stay fixed.

@2x sprite support for Retina: load the high-res atlas, halve the pixel sizes.

Text

Text was the biggest single feature. PBF glyph format (same as Mapbox), shelf-packed texture atlas, SDF rendering reusing the icon shader.

GlyphAtlas dynamically grows (1024x1024 initial, doubles when full). SDF distance stored in alpha channel. The glyph shader is literally the icon shader: is_sdf = 2.0 + halo_buff triggers PBF glyph mode with the correct SDF thresholds.

Text shaping is 1:1 codepoint-to-glyph. No GSUB/GPOS, no complex script support yet. Works for Latin, CJK, Cyrillic. Arabic and Thai would need a real shaper like rustybuzz.

Word wrapping, text-anchor (9 positions), text-offset, text-variable-anchor with collision retry, text-radial-offset, text-justify.

Collision detection

Without collision detection, labels pile on top of each other. Built a grid-based system.

Labels grouped by feature: icon + text for the same feature are placed together (all-or-nothing). Groups sorted by (layer_index, symbol-sort-key). Grid cells are checked, if occupied the label gets rejected and fades out.

Variable anchor retry: if a label’s primary anchor collides, try alternatives. Pre-compute screen positions for each anchor variant, test them in order. Phase 1: collect decisions. Phase 2: apply vertex shifts. Two phases to avoid borrow conflicts.

A tour of European cities, all rendered with the same pipeline:



Paris	London	Barcelona

Amsterdam	Berlin	Rome

Vienna	Prague	Budapest

Stockholm	Istanbul	Athens

Lisbon	Copenhagen	Helsinki

Oslo

Performance

Event-driven loop with ControlFlow::Wait. No busy polling. EventLoopProxy waker: worker threads signal the event loop when tiles arrive.

Extract debounce: during active zoom/pan (100ms window), skip full geometry extraction, just update camera uniforms. Once input stops, run the deferred extract. New tile arrivals always trigger extract immediately: you want to see them.

Zoom style patches: instead of re-extracting everything when zoom changes (colors and sizes are zoom-dependent), patch the extracted vertex data in-place. Rewrites only the color/opacity/width fields.

Time-sliced extraction: spread heavy work across multiple frames so the renderer doesn’t stall.

Dependencies optimized in debug builds: [profile.dev.package."*"] opt-level = 2.

Multi-platform

macOS / iOS with UniFFI

UniFFI generates Swift bindings from Rust. MapEngine wraps wgpu in a Mutex, exposes methods like draw_frame(), set_center(), set_zoom().

The Metal surface is created from a raw CAMetalLayer pointer. MSAA disabled in the FFI path because MTKView’s MSAA resolve triggers a size mismatch with wgpu. sRGB correction handled by a uniform flag: fragment shaders apply sRGB-to-linear when rendering to MTKView’s sRGB surface.

HttpClientDelegate callback interface: Swift injects a URLSession-backed implementation so network requests go through the platform’s native stack.

xcframework build: aarch64-apple-darwin, x86_64-apple-darwin, aarch64-apple-ios, aarch64-apple-ios-sim.

Browser with WASM

wasm32-unknown-unknown target, wasm-bindgen for the JS interface. Tile loading uses browser fetch() via web_sys. No threads in WASM so tile extraction is sequential (10-30 tiles is fine without parallelism).

Style/sprite loading is async in the WASM path (browser fetch) vs sync on native (ureq). The renderer has platform-agnostic setters: apply_style_data(), set_sprite_atlas().

web-time crate replaces std::time::Instant everywhere: re-exports std on native, performance.now() on WASM.

Globe

Optional 3D sphere projection at low zoom (toggle with G key). The shader branches on a globe_mix uniform: above 0.5 it projects lon/lat onto a unit sphere, rotated by center latitude and map rotation.

Back-face discard in the fragment shader: globe_rz < 0.0 hides the back of the sphere. No depth buffer needed.

Polygon subdivision for the globe: edges longer than 5 degrees get split recursively. Conforming subdivision: all edges of a triangle get split (not just the longest) so adjacent triangles agree on shared edge vertices. No T-junction cracks.

Google Maps Styler

A declarative styling engine that applies Google Maps-style JSON rules to modify layer colors. HSL transforms: hue, saturation, lightness, invert, gamma. Delta-based: rules shift colors rather than setting absolute values.

Hierarchical feature type matching with a tree structure. "all" walks the entire tree, "road.highway" matches just highway layers.

POI expansion: the styler takes a single POI layer with class metadata and expands enabled classes into individual layers, each with its own filter and icon.

Where it stands

This is not done. It’s not a replacement for Mapbox GL Native, not even close.

233 tests. The basics work: fill, line, background, symbol layers with icons and text. Expressions, collision detection, variable anchor, text wrapping, text justification. Runs on macOS, iOS, and the browser. Globe projection at low zoom.

What’s missing or broken:

Text shaping is naive 1:1 codepoint-to-glyph. Arabic, Thai, Burmese, anything that needs ligatures or reordering doesn’t work. Need rustybuzz or equivalent.
Line rendering has no dashes, no gradients, no line-cap styles beyond basic round.
Symbol placement along lines is basic. No label curving along the road, no smooth rotation interpolation.
Collision detection is coarse. The grid works but it’s not as smart as Mapbox’s: no cross-tile collision, no viewport-edge handling for partially visible labels.
Raster layers not supported at all. No hillshade, no satellite imagery compositing.
Performance is acceptable for interactive use but extraction is still heavier than it should be. Mapbox GL Native has had years of profiling and optimization. We haven’t.
Fill extrusion (3D buildings) not implemented.
Rotation mostly works but some label placement breaks at non-zero bearing.
Expression coverage is incomplete, missing format, image, number-format, to-color and several type conversion operators.

About 15,000 lines of Rust. No C++ dependency. No OpenGL. The foundation is there, the details are not.

Tunes

Tue, 01 Jul 2025 10:31:38 +0200

iTunes Match worked great for years: you uploaded your library, Apple matched what it could, and you had access to everything from any device. But Apple is clearly moving everyone toward Apple Music, and iTunes Match has been slowly rotting. The writing was on the wall.

I didn’t want to subscribe to Apple Music. I wanted to keep my library, my ratings, my play counts, my playlists, all the metadata accumulated over 20 years. So I built my own streaming setup: a Go backend that serves the library over HTTP, and SwiftUI apps that play it on iOS, macOS, and tvOS.

Exporting the library

Apple Music (formerly iTunes) can export the library as an XML plist file. It’s a flat dictionary of tracks keyed by ID, with every field you’d expect: name, artist, album, play count, rating, date added, file location, and about 60 more.

A track entry in the exported XML

<key>1234</key>
<dict>
 <key>Track ID</key><integer>1234</integer>
 <key>Name</key><string>Windowlicker</string>
 <key>Artist</key><string>Aphex Twin</string>
 <key>Album</key><string>Windowlicker</string>
 <key>Total Time</key><integer>381573</integer>
 <key>Location</key><string>file:///Music/Aphex%20Twin/Windowlicker/01%20Windowlicker.m4a</string>
</dict>

The Go struct that maps to this uses plist tags for XML parsing and gorm tags for database storage, with every optional field as a pointer for proper nil handling:

Track model (abbreviated)

type ITunesTrack struct {
 TrackID *int `plist:"Track ID" json:"track_id" gorm:"primaryKey"`
 Name *string `plist:"Name" json:"name" gorm:"index"`
 Artist *string `plist:"Artist" json:"artist" gorm:"index"`
 Album *string `plist:"Album" json:"album" gorm:"index"`
 TotalTime *int `plist:"Total Time" json:"total_time"`
 Location *string `plist:"Location" json:"location"`
 Rating *int `plist:"Rating" json:"rating" gorm:"index"`
 PlayCount *int `plist:"Play Count" json:"play_count"`
 DateAdded *time.Time `plist:"Date Added" json:"date_added" gorm:"index"`
 // ... 60+ more fields
}

The initial version parsed the XML on every startup using howett.net/plist. That worked fine for a 15,000-track library (about 2 seconds of parsing). But it eventually moved to SQLite with GORM for persistence, which also enabled FTS5 full-text search and pre-aggregated album caches.

The Go backend

The server is straightforward. A LibraryService holds the database, artwork cache, rate limiter, and various sub-services. Routes are plain net/http handlers with a JWT auth middleware:

Route setup (abbreviated)

// Auth routes (no middleware)
http.HandleFunc("/auth/login", authHandlers.HandleLogin)
http.HandleFunc("/auth/register", authHandlers.HandleRegister)

// Library routes (auth required)
http.Handle("/tracks", authMiddleware(http.HandlerFunc(service.HandleTracks)))
http.Handle("/artists", authMiddleware(http.HandlerFunc(service.HandleArtists)))
http.Handle("/albums", authMiddleware(http.HandlerFunc(service.HandleAlbums)))
http.Handle("/stream/", authMiddleware(http.HandlerFunc(service.HandleStream)))
http.Handle("/artwork/track/", authMiddleware(http.HandlerFunc(service.HandleTrackArtwork)))

The /stream/{id} endpoint serves audio files directly with http.ServeFile, which handles range requests and conditional caching automatically. No need to build a custom streaming protocol. HTTP does the job.

Authentication uses Argon2 for password hashing and session tokens stored in the database. It later grew WebAuthn support for passkey login, and a QR code flow for tvOS (where typing passwords with a remote is painful).

Album artwork

This was the most annoying part. The exported XML doesn’t include artwork. The actual cover images are either embedded in the audio files or live somewhere in Apple’s ecosystem that isn’t accessible after export.

The solution is a three-tier artwork system:

Embedded extraction: read the audio file metadata with github.com/dhowden/tag, pull out the cover image if present, cache it locally
iTunes Store lookup: search Apple’s public API for the album, download the highest resolution artwork available
Manual upload: for albums that don’t match either source

The iTunes Store lookup uses a scoring system to match results. Exact album + artist name match scores highest, partial matches score lower, and anything below a minimum threshold is rejected:

iTunes Store artwork search

func (ls *LibraryService) searchITunesStore(artist, album string, tracks []ITunesTrack) *ITunesSearchItem {
 searchTerm := fmt.Sprintf("%s %s", strings.TrimSpace(artist), strings.TrimSpace(album))

 params := url.Values{}
 params.Set("term", searchTerm)
 params.Set("entity", "album")
 params.Set("media", "music")
 params.Set("limit", "10")

 searchURL := fmt.Sprintf("https://itunes.apple.com/search?%s", params.Encode())
 // ... fetch, decode, find best match by score
}

Apple’s API returns 100x100 thumbnails by default. The URL pattern is predictable (replace 100x100 with 600x600), but not all resolutions exist for all albums. The server tries 600, 512, and 300 with HEAD requests before falling back to the original.

The real constraint is rate limiting. Apple’s Search API starts returning 403s if you hit it too hard. The server uses a channel-based rate limiter that caps requests to 2 per second by default, configurable via TOML config.

The gapless playback problem

This one took a while to figure out. Live albums, DJ mixes, classical recordings: any music that’s supposed to flow continuously between tracks gets a gap when played back on iOS.

The root cause: iOS AVFoundation ignores the iTunSMPB gapless metadata in MP3 files. This is the atom that tells the player how many encoder delay and padding samples to skip. Apple’s own Music app reads it. AVFoundation does not.

The fix is converting MP3s to AAC. The AAC container stores gapless information in a way that AVFoundation actually respects. The server has a built-in transcoder:

Startup conversion

transcoder := tunes.NewTranscoderService(service, tunes.TranscodeOptions{
 Concurrency: 4,
 DeleteSource: false, // Keep original MP3s
})
results, err := transcoder.ConvertAllMP3s(context.Background())

It uses ffmpeg under the hood, runs 4 workers in parallel, keeps the originals, and updates the database paths. A 15,000-track library takes a couple of hours. After that, gapless playback works perfectly.

SwiftUI clients

The app targets iOS, macOS, and tvOS from a single codebase, with platform-specific extensions for navigation and layout. iOS uses tab navigation with a mini-player overlay, macOS uses a split view with sidebar, and tvOS uses focus-based navigation for the remote.

The audio player is built on AVQueuePlayer for seamless track transitions. It pre-buffers the next track 10 seconds before the current one ends, maintaining up to 3 items in the queue at any time.

One hard-won lesson: @Published property updates in background cause iOS to terminate the app for excessive main-thread UI work. The fix is gating all published writes behind a foreground check:

Background-safe state management

struct PlaybackState: Equatable {
 var currentTime: TimeInterval = 0
 var duration: TimeInterval = 0
 var isPlaying = false
 var isLoading = false

 static func == (lhs: PlaybackState, rhs: PlaybackState) -> Bool {
 return Int(lhs.currentTime) == Int(rhs.currentTime) &&
 Int(lhs.duration) == Int(rhs.duration) &&
 lhs.isPlaying == rhs.isPlaying &&
 lhs.isLoading == rhs.isLoading
 }
}

Grouping related properties into structs (instead of individual @Published vars) and implementing coarse equality comparison reduced SwiftUI re-renders significantly. The player only triggers a view update when the second changes, not on every time observer tick.

The API layer uses Combine publishers with automatic 401 retry: if a request fails with an expired token, the service transparently refreshes it and replays the original request. Network monitoring via NWPathMonitor lets the app degrade gracefully when offline, falling back to Core Data for cached data.

What grew out of it

What started as “stream my library from a Raspberry Pi” has accumulated features over time:

Full-text search with SQLite FTS5 across all track metadata
Play history tracking: every play gets logged with duration and completion status, which feeds a yearly replay feature (like Spotify Wrapped)
Lyrics: embedded USLT frames from audio files, plus LRClib API integration for synced timestamps
Offline mode: Core Data persistence with background sync, download management for keeping albums locally
Discogs integration: artist biographies and metadata from a separate database
Vector similarity search: track embeddings for “genius playlists” based on audio features and metadata

It’s not a replacement for Apple Music. It doesn’t have a catalog of 100 million songs. But it plays my music, with my metadata, on all my devices, without a subscription. That was the goal.

Side Projects on Man-You

25 years to a complete machine

Why a rolling inventory at all

What made the bug reachable

Why these tools exist

Higgins: a neurosymbolic menubar buddy

Why not just a chat wrapper

The Qwen brain

The symbolic side

Sleep

Per-turn recall: closing the loop

Tools

Dates, or: why the model doesn’t do arithmetic

The AppleScript Run button

What grew out of it

The most useless way to port a macOS app

The prior art that made this possible

What Claude came back with

Architecture

First signs of life

Settings and Finder

Tunes

Leela

Under the hood

Text rendering

Layout

IPC

The ycodebuild trick

Honest assessment

Why this matters (a little)

What’s next

Full-text search and lyrics in a Go music server

The search problem

FTS5 with unicode61

Query building

Unified search endpoint

Lyrics from audio files

LRClib integration

Background enrichment

Admin via sudoers

What changed

Calculon part 2: costing profiles, performance, and maneuvers

Bicycle and pedestrian costing

Memory-mapped tiles

Thread-local tile cache

Distance approximator

Distance-adaptive hierarchy

A* heuristics in the cost matrix

Turn-by-turn maneuvers

Edge snapping improvements

All My Circuits

Criterion benchmarks

Where it stands

Building a routing engine in Rust

Why

Architecture

Tile-based graph

Cost model

Bidirectional A*

Many-to-many matrix

HTTP server

Where it stands

Tree: a browser that remembers where you came from

The data model

Branching

WebView management

State persistence

The sidebar

Focus mode

Ad blocking

Keyboard navigation

Session restoration

What it replaces

Building a GPU map renderer from scratch

Why

First pixels

Making it a real map

Moving projection to the GPU

Style-driven rendering

Lines

The `ycodebuild` trick