docs: rewrite the README around what it is and what we learned - #66
Merged
Merged
Conversation
The old one had drifted from the code in ways that would catch a new user immediately, and was arranged to be read start to finish rather than skimmed for the one thing someone came for. Corrected, because these were wrong rather than merely dated: * Fullscreen is F, not F11, and had been documented wrong in two places. * "50 unit tests" is now 201 Swift, 53 Rust and 33 frontend checks. * HDCP was described as protected video not playing on the virtual display. It does not play on ANY display while that one exists, which is a different problem with a different answer — and there is now a Release the screen control for it, which the README did not mention. * A dated status banner and a "Phases 0-7" reference that now collides with the latency phases; both replaced with things that do not go stale. * The latency figure was a browser measurement of a path the shipping receiver does not take. Replaced with the honest position: per-stage numbers are on the HUD and nobody has recorded them on real hardware. Added: * Badges, a contents list, and a contributing section. Ordinary furniture, all of it missing. * How it compares — Sidecar, Duet, Luna, Deskreen, spacedesk. Written to be useful rather than flattering, including where each of them is the better choice. Nobody in this category publishes one, and the honest version is more persuasive than a feature grid. * What we measured — the findings, promoted out of footnotes. Chrome's hardware H.264 decoder carrying 22x the latency of software decoding the same stream; CGVirtualDisplay silently getting large geometries wrong; protected playback evaluating the whole output topology; EnableLowLatencyRateControl being a specification rather than a property; .idempotent installing no completion handler; an idle desktop breaking anything that measures health in encoded frames. These cost real time to find and are useful to anyone working nearby. The agent setup prompt survives, collapsed, with its keys corrected. Every internal anchor and file link is checked to resolve. Still missing, and worth saying: there is no screenshot or recording. For an app whose entire pitch is visual, that is the single biggest remaining gap in this file, and it needs someone with both machines to produce. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
The README had no image at all, which for an app whose whole pitch is visual was the largest thing missing from it. This one is genuine rather than a mock-up: a live session on a real Mac, captured from the receiver's own canvas at 1920x810 as it arrived over H.264. The macOS menu bar in it is the part that matters — it is the evidence that macOS is drawing a whole second screen rather than copying the first, which is the one claim the project rests on and the hardest to believe from prose. Nothing in it is anyone's data. The window on that display was put there for the photograph and says what it is; everything else is wallpaper. Also splits the connect walkthrough by machine, because the single five-step list ran the two halves together and the two halves happen in different places. The Bonjour step now says what to do when mDNS is blocked, since guest and AP-isolated Wi-Fi routinely block it and that is the most common way the first connection fails. The one-receiver-at-a-time message is called out, because it reads as a fault and is a design choice. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
The old README had drifted from the code in ways that would catch a new user immediately, and was arranged to be read start-to-finish rather than skimmed for the one thing someone came for.
Corrected — wrong, not merely dated
F, notF11— documented wrong in two places. First thing a new user would try.Added
Badges, a contents list, a contributing section. Ordinary furniture, all of it missing.
How it compares — Sidecar, Duet, Luna, Deskreen, spacedesk. Written to be useful rather than flattering, including where each of them is the better choice (Sidecar if you own an iPad; spacedesk when Windows is the source; Deskreen for one screen on many devices). Nobody in this category publishes one, and the honest version is more persuasive than a feature grid. The comparison sticks to architecture — extends vs. mirrors, needs a driver, direction — because that's stable and verifiable, rather than pricing that goes stale.
What we measured — the findings, promoted out of footnotes:
CGVirtualDisplaysilently gets geometries above ~1920×1200 wrong, and reports successEnableLowLatencyRateControlis a specification, not a property — setting it afterwards does nothing, silently.idempotentinstalls no completion handler, so there's no back-pressure signalThese cost real time to find and are useful to anyone working nearby. They're also the most linkable thing in the repo.
The agent setup prompt survives, collapsed in a
<details>, with its keys corrected.Verification
Every internal anchor and every local file link is checked to resolve — 18 internal links against 28 headings, no breaks. Badge URLs return 200. Copy passes
check-user-strings.py.Still missing
There is no screenshot or recording. For an app whose entire pitch is visual, that's the single biggest remaining gap in this file — and it needs someone with both machines in front of them to produce.
🤖 Generated with Claude Code