Your laptop, from across the room.

It is for the times the laptop is across the room rather than under your hands: plugged into a television, docked on a desk you are not sitting at, parked somewhere a mouse dongle will not reach.

The alternatives are a remote app that only sends media keys, or a remote-desktop app that streams the whole screen and wants an account and a network round trip to change the volume. Edgepad is neither. The phone and the laptop pair once, the way a headset does, and after that they talk directly: no account, no Wi-Fi, no service in between that can be slow or down.

The cost is Bluetooth's own. Both ends need it, and it does not reach another room or the internet.

What it does

Pairing and first connection

1. Pair the phone with the laptop once, in Windows Settings > Bluetooth & devices. Edgepad has no pairing step of its own.
2. Keep Edgepad running in the laptop's tray. It must already be running before the phone tries to connect: there is no discovery or retry on the laptop side.
3. Open Edgepad on the phone and tap the laptop. The first phone to connect becomes the laptop's trusted phone; any other paired phone is refused until you choose Forget trusted phone in the tray menu.
4. The phone remembers the laptop and reconnects when the app opens. If the link drops after a completed handshake, the phone retries ten times, two seconds apart, and says so. Disconnecting on purpose does not retry.

The control surface

Default three- and four-finger gestures

Swapped from Windows' own defaults on purpose. Every one of these is changed under Settings > Gestures.

The corner dials

A dial is a ruler lying along the screen's edge, bending round the corner along the display's own rounding. The finger slides the ruler under a fixed indicator; clockwise raises the value everywhere, like turning a knob. Sliding past a small slop arms it — there is no hold — the ticks lengthen while armed, and one haptic tick fires per notch that passes. A tap without a slide runs the dial's action instead.

Seven kinds compete for four places: volume, brightness, media scrub, zoom, app switcher, microphone level and refresh rate. A corner may also hold nothing. A dial shows the laptop's real value from STATE frames, and dragging sends absolute SET frames.

Macro buttons

Fifteen buttons in a 5x3 grid, named from the laptop's tray menu. Fifteen is what one frame can name, so a full grid always arrives labelled rather than trailing off into blank buttons. A macro added while the phone is connected appears at once.

The theme is the system's own per-app night mode, set through UiModeManager.setApplicationNightMode, so Edgepad stores no preference of its own for it. Orientation is a toggle — upright or sideways — not free rotation. Media-piece positions are stored as fractions of the surface's width and height, so a layout made in portrait keeps its shape in landscape.

Where the laptop keeps things

%APPDATA%\Edgepad\trusted-phone.txt   the trusted phone's Bluetooth address
%LOCALAPPDATA%\Edgepad\edgepad.log    connections, refusals, dropped frames,
                                      and input batches Windows refused

Every touch is turned into a semantic frame on the phone — pointer moved, button pressed, scroll, zoom, run action 3, set control 0 to 55, type “hi” — and the laptop carries it out with the Windows input, audio, display and media APIs. The laptop owns the table of what each action id does. The phone can name an action; it cannot invent one.

The laptop reports back. After the handshake it sends a snapshot of volume, microphone and brightness, then what is playing and where, then the display's available refresh rates and the macro names, and thereafter every change as it happens. The phone keeps the last report in LaptopState, which outlives the control surface, so a surface rebuilt after a rotation or a theme change starts from real values and never shows 0 for a level it has not heard. A level never reported shows an ellipsis, not a zero.

Why Windows gestures are emulated by their results

Windows only runs its native multi-finger gestures for certified Precision Touchpad hardware. Two ways round that were rejected: a virtual PTP driver, which needs a kernel driver and test-signing mode and so weakens the laptop's security, and making the phone a Bluetooth HID touchpad, which needs a PTP certification blob and depends on Android OEM support for BluetoothHidDevice. So Edgepad produces the result instead: Win+Ctrl+Left rather than a finger-following desktop slide. The cost is the animation. Alt+Tab stays interactive because Alt is genuinely held while the fingers are down.

758bb618-7b72-4cd3-9aa2-c9b88e54d555

The socket is bound at BluetoothEncryptionWithAuthentication. That means only a device already paired with the laptop can connect at all, and the stream is encrypted by the link layer rather than by anything Edgepad wrote.

What was rejected

The phone's surface

ControlSurface is a single custom View that draws everything and receives every touch. There is no view hierarchy between the finger and the recogniser. Geometry is computed once in onSizeChanged; nothing is allocated while drawing.

Perimeter models the screen's edge as one clockwise path — a rounded rectangle whose corner radius is the display's own, from WindowInsets.getRoundedCorner — so a ruler bends round a corner instead of being clipped by it. A dial's finger position is projected onto that path and its movement measured along it. Perimeter is the single place that says a screen has four corners; three files each used to carry their own copy.

TrackpadRecognizer and Dial are pure Kotlin with no Android types. That is what lets the whole gesture table run as plain JVM unit tests with no emulator.

Why the laptop half is a tray app, not a service

Windows services run in session 0 and can neither inject input into the desktop nor reach the user's audio session. So Edgepad is a per-user tray app that starts at login through the HKCU Run key. It is single-instance, held by a named mutex, and a newer copy signals the running one to quit and waits for the lock rather than killing the process.

On the phone

LaptopLink.open blocks for the life of the connection on its own thread and reads there. A second thread drains the outbox and writes. send never blocks, so touch handling never waits on the link. Every callback into the activity is posted to the main thread. The link is kept across configuration changes through onRetainNonConfigurationInstance with its listener swapped to the new activity, and closed when the app leaves the foreground.

On the laptop

RfcommServer accepts on WinRT's thread and hands each socket to a Session on a dedicated above-normal-priority thread, where the read loop turns frames straight into input. There is no queue between the socket and SendInput.

A new connection replaces the old one rather than being refused, because after a dropped link the phone reconnects before the laptop's old socket has noticed it is dead. Audio-change notifications arrive on COM threads and brightness events on a WMI thread, so Session.Send is locked and they interleave safely with the read loop's PONGs.

The four things that make it feel immediate

1. Unbuffered touch. View.requestUnbufferedDispatch, with every historical sample read from each MotionEvent, so events arrive as they happen rather than batched to vsync.
2. One write per batch. The writer thread sends everything already queued in a single write.
3. Coalescing. A backlog of MOVE, SCROLL and ZOOM frames still waiting in the outbox is summed into one before it goes out, and only the last SET per control survives. A slow link catches up in a single packet instead of replaying every sample it missed.
4. Brightness off the hot path. A WMI call is far slower than a frame, so brightness writes go to their own thread with latest-value-wins. Queueing them would make a dial drag lag further behind the finger the longer it moved.

Errors, and what is merely ignored

An unknown type byte, a wrong length, a bad magic or a flag byte other than 0 or 1 is a protocol error and closes the connection. A well-formed frame naming an action, a control or a text kind this side does not know is dropped and counted, never treated as an error. That is what lets a newer app talk to an older one until the version check says otherwise — and why new ids do not need a version bump.

Frames

Golden bytes

Each line of the fixture is a frame's fields and its exact bytes. Both test suites encode the fields and must get exactly those bytes, then decode the bytes and must get exactly those fields. Because one file drives assertions in two codebases, changing one side's codec without the other fails that side's test immediately. The fixture is what stops the two apps from drifting apart — not code review.

TEXT kinds

What the laptop sends, and when

STATE  volume, microphone, brightness
TEXT   0 now playing, 1 the app, 2 the timeline
STATE  media position
TEXT   4 the display's refresh rates
STATE  the current refresh rate
TEXT   5 the laptop's macro names

then every change as it happens.
Media position is refreshed once a second while playing.

Versioning

Only a new frame type forces a version, because an unknown type closes the connection. The refresh-rate dial and the macro buttons both arrived without a bump, which is the rule working rather than being broken. From 1.0 this number moves only in a major release, and any change to what a frame means bumps it on both sides in the same commit and adds a fixture line.

Actions

Controls

The two layers

The handshake also carries the protocol version. A mismatch is refused with the laptop's version in the reply, so the phone can say which side needs updating instead of misreading frames. A refusal before HELLO_ACK names both possible causes: a laptop app older than the phone's, or a laptop that trusts a different phone.

What the action table is, and is not

The line Windows draws

SendInput is silently refused when an elevated window, a UAC prompt or the secure desktop has focus. This is Windows protecting them and the app cannot cross it. The laptop counts those refusals and logs them once per session, so a gesture that appears to do nothing has a recorded reason.

Known limits

• The trusted phone's Bluetooth address is stored in plain text under %APPDATA%\Edgepad. Anyone who can write that file can change which phone is trusted — and that person can already run programs as you.
• Edgepad.exe is not code-signed, so SmartScreen warns on first run. Verify the download came from the project's own Releases page.
• Text typed from the phone goes wherever the laptop's focus is, exactly as a keyboard would.
• Nothing leaves the two devices: no network, no server, no account, no telemetry. The laptop writes a local log of connections and errors and nothing else.
• Release builds are signed, and every release is signed with the same key, so a phone will refuse an update that was not built by this project.

Inside the phone app

Under android/app/src/main/java/me/akshitbansal/edgepad. The packages marked pure have no Android platform types and run as plain JVM unit tests.

Inside the laptop app

Under windows/src/Edgepad.

pwsh scripts/check.ps1                  # formats in place, then checks everything
pwsh scripts/check.ps1 -Only android    # ktlint, Android lint, unit tests
pwsh scripts/check.ps1 -Only windows    # dotnet format, build, tests
pwsh scripts/check.ps1 -Ci              # what CI runs: fails on unformatted code

What it actually runs

What CI does on top

.github/workflows/ci.yml runs on every push to main and every pull request, in two jobs: Android on ubuntu-latest with Temurin 17 and Gradle wrapper validation, Windows on windows-latest with the SDK from global.json. Each runs the gate in -Ci mode and then uploads an artifact — a debug APK and the self-contained exe.

Laptop

dotnet run --project windows/src/Edgepad

dotnet publish windows/src/Edgepad -c Release -r win-x64 --self-contained \
  -p:PublishSingleFile=true \
  -p:IncludeNativeLibrariesForSelfExtract=true \
  -p:EnableCompressionInSingleFile=true

cd windows && dotnet build Edgepad.slnx -c Release

Phone

cd android && ./gradlew installDebug

cd android && ./gradlew assembleDebug

Together

1. Pair the phone and the laptop in Windows Settings.
2. Start the tray app with dotnet run.
3. Install and open the phone app, then tap the laptop.
4. Read %LOCALAPPDATA%\Edgepad\edgepad.log for dropped frames or refused input batches.

This site

cd site
npm install
npm run dev        # http://localhost:3000
npm run check      # Biome -> ESLint -> tsc, the site's own gate
npm run check:ci   # the same, non-mutating

cd android && ./gradlew testDebugUnitTest
cd windows && dotnet test --solution Edgepad.slnx

The fixture layer

protocol/frames.txt holds every frame type as golden bytes, and protocol/actions.txt the action, control and text-kind ids. FrameFixtureTest and IdsFixtureTest on the phone, and FrameFixtureTests and IdsFixtureTests on the laptop, parse those same files at run time rather than copying them into either codebase.

A protocol change therefore always touches a fixture file and both codecs in the same commit. Change one side's codec without the other and that side's test fails immediately.

Above the fixtures

1. Branch from main.
2. Keep the two apps in step. A protocol change edits protocol/frames.txt or protocol/actions.txt, both codecs or both enums, and bumps the protocol version on both sides — all in one commit.
3. Add or change a test when you add logic or a branch, or fix a bug. Prefer the pure layers over anything that needs a device.
4. Run pwsh scripts/check.ps1 until it is clean.
5. Commit with a Conventional Commits subject and a body saying what changed and why, including what you rejected.
6. Add a line under Unreleased in CHANGELOG.md.
7. Open a pull request.

Style

• No UI libraries on the phone. No third-party packages on the laptop beyond NAudio and System.Management. A new dependency needs a reason in the pull request.
• Constants are named. A number that appears twice is a constant.
• Doc comments say why, not what the next line already says.
• Nothing runs on the input path that could block: no logging, no allocation while drawing, no I/O on the session thread beyond the socket.

Bug reports and feature requests use the issue templates in .github/ISSUE_TEMPLATE. Open an issue for anything bigger than a fix, so the design can be talked through before code exists. Report anything exploitable through a security advisory, not a public issue.

# 1. Update the version table in docs/PROTOCOL.md if the protocol changed.
# 2. Move Unreleased in CHANGELOG.md under the new version.
git tag v2.0.0
git push origin v2.0.0

.github/workflows/release.yml runs both quality gates, builds a signed release APK and a compressed self-contained exe, and attaches them to a GitHub Release under the stable names Edgepad.apk and Edgepad.exe, so releases/latest/download/<file> always resolves to the newest build.

Versioned file names were rejected because they break that permanent link, and CI artifacts were rejected as a distribution channel because they expire and need a GitHub login. versionName comes from the tag; versionCode comes from the workflow run number, which only increases, so an update always installs over the previous one.

Not goals

No account, no server, no telemetry, and no web deployment: Edgepad ships as two native binaries from GitHub Releases and there is nothing to host. The link does not reach another room or the internet, and it is not meant to.

• Icons are Lucide, ISC licence.
• The typeface is JetBrains Mono, SIL Open Font License 1.1. Its licence ships inside the APK under assets/licenses.
• Player logos belong to their owners and are drawn as supplied.
• The laptop app depends on NAudio (for volume) and System.Management (for WMI brightness), and nothing else. The phone app depends on JUnit, and nothing else.