[Medium] Extend QR/URL format to carry both LAN URL and mesh room code

[bitflicker64]

filedrop-mesh epic

This is a sub-issue of the umbrella epic: #155.

---

Description

The current QR encodes a single LAN URL: http://192.168.x.x:port/<token>#<key>. With mesh, a single QR needs to carry both the LAN URL and the mesh room code, because the receiver's phone doesn't know in advance which path will work.

This sub-issue defines and implements the QR + URL format that handles both cases transparently.

Goals

• One QR works in both same-network and cross-network scenarios.
• A phone scanning the QR never has to choose which transport to use — the receiver page figures it out.
• Backward-compatible: an old receiver client scanning a new QR can still hit the LAN URL if it's reachable.

Proposed URL format

The QR encodes a deep link on the signaling host:

https://<signal-host>/r/<ROOM>#<LAN_URL>?<key>

Where:

• <signal-host> — the configured signaling server (sub-issue test: CI Auto-Fix Loop with Greptile and Jules #3).
• <ROOM> — the 6-char mesh room code (sub-issue test: Jules-Greptile V2 Loop Test #4).
• <LAN_URL> — the local URL the sender is currently bound to. URL-encoded. Optional — omit if the sender has no LAN address.
• <key> — the AES key fragment, in the URL fragment so it never goes over the network in plaintext.

When the receiver opens the deep link, the receiver page:

1. Reads key from the fragment.
2. Reads LAN_URL from the fragment.
3. Tries LAN_URL first (cheap, fast, no signaling roundtrip).
4. If the LAN URL is unreachable (timeout, connection refused), falls back to the signaling room <ROOM> and switches to MeshTransport.

Why fragment for both LAN URL and key?

The fragment is never sent to the server. Both the LAN URL and the key ride in the fragment so neither leaks through any HTTP request — including the initial GET to the signaling host's landing page. The signaling host only ever sees the room code in the path.

Fallback for old clients

For receivers running an older filedrop web client that doesn't understand the new format, the QR can also embed the plain LAN URL as a fallback path (e.g., via a tiny JavaScript shim that detects old clients and redirects). Decide the exact mechanism in the PR; the simplest is to encode both URLs in the fragment separated by a sentinel character.

Expected vs Actual

Expected: One QR. Two transport paths. The receiver picks the working one.

Actual: One QR. One path. LAN-only.

Steps to land

1. Define the URL schema above in docs/mesh-url-format.md (small spec doc).
2. Sender: build the QR string in src/qr.js from (signalUrl, roomCode, lanUrl, keyHex).
3. Receiver: update the landing page to parse the new format, try the LAN URL with a short timeout, fall back to mesh.
4. Backward compatibility: detect an old client (User-Agent or version marker) and redirect to the LAN URL only.
5. Terminal UI: show the mesh code alongside the LAN URL in the metadata box, with a clear visual indicator that mesh is active.
6. Tests:
   • QR string roundtrips through the parser.
   • LAN-URL-first-then-mesh fallback: unit-test the decision logic with mocked timeouts.
   • Old-client detection redirects correctly.

Location

• modified: src/qr.js — renderMeshQR(signalUrl, roomCode, lanUrl, keyHex, options)
• modified: the receiver-side HTML served at the LAN URL — add the format-detection + fallback logic
• new doc: docs/mesh-url-format.md

Difficulty

Medium — the format itself is simple; the receiver-side fallback timer and old-client detection need real device testing.

Dependencies

• Blocked by [Medium] Build @dreamstick/filedrop-signal companion package (WebSocket signaling server) #148, [Easy] Add 6-character mesh room code generator and receiver-side entry page #149.
• Blocked by [Medium] Implement pickTransport() policy: prefer mDNS, fall back to WebRTC + signaling #150 (transport selection must know which QR to render).

Notes

Pick a sentinel character for the fragment that won't appear in URL-encoded payloads. Newline is safe since fragments are URL-encoded by the browser before the page reads them. Document the choice in the spec doc.

Part of the filedrop-mesh epic (#155).

[git-miku]

miku

Tip

👋 Thanks for opening this issue, @bitflicker64!

Want to work on it? Comment :miku /claim and I'll assign it to you.

Not ready to code? Ask :miku /ask how do I get started?

[git-miku]

miku

Note

🔍 This issue looks similar to existing ones. Could it be a duplicate?

• #149 — Description (score: 0.493, title-jaccard=1.00)
• #150 — Description (score: 0.339, title-jaccard=1.00)
• #147 — Description (score: 0.302, title-jaccard=1.00)

Maintainers: :miku /mark-dup #N to confirm or :miku /not-dup to dismiss.
This is advisory only — the issue stays open until a human decides.

[Spirit019]

:miku /claim

[git-miku]

miku /claim

✅ Claimed this issue for @Spirit019.

---

Assignment Brief for @Spirit019

What needs to be done

You need to extend the QR/URL format to encode both the LAN URL and mesh room code in a single QR code, enabling the receiver to automatically try the LAN path first and fall back to mesh transport if needed. This involves creating a new URL schema, updating the QR rendering logic, and modifying the receiver-side HTML to implement the fallback mechanism while maintaining backward compatibility with older clients.

Acceptance criteria

• New URL format https://<signal-host>/r/<ROOM>#<LAN_URL>?<key> is implemented and documented in docs/mesh-url-format.md
• src/qr.js exports a new renderMeshQR(signalUrl, roomCode, lanUrl, keyHex, options) function that builds the QR string correctly
• Receiver-side HTML in src/server.js parses the new format, attempts LAN URL first with a short timeout, and falls back to mesh on failure
• Backward compatibility mechanism works: old clients scanning new QRs can still access the LAN URL
• Terminal UI metadata box displays the mesh code alongside the LAN URL with a visual indicator when mesh is active
• Unit tests cover QR string parsing, LAN-to-mesh fallback logic with mocked timeouts, and old-client detection

Where to start

Key files to examine first:

• src/qr.js — Study the existing renderQR() function to understand the current QR generation pattern and the renderMetadataBox() function for UI updates
• src/index.js — See how the current URL is constructed (http://${ip}:${port}/#${keyHex}) and passed to qr.renderQR()
• src/server.js — Examine the HTML payload template (lines 104-333) to understand where to add the new format parsing and fallback logic

Relevant patterns:

• The current fragment-based crypto model keeps the key in the URL fragment (#key) for security
• The receiver page already reads the fragment key via window.location.hash.slice(1)

Potential pitfalls:

• Choose a sentinel character for separating LAN URL and key in the fragment that won't appear in URL-encoded payloads (newline is suggested)
• The fallback timeout needs careful tuning — too short and false positives, too long and poor UX
• Old-client detection via User-Agent parsing can be fragile; consider a version marker approach
• Ensure the signaling host URL is properly configured before calling renderMeshQR()

PR checklist

• Add unit tests for the new QR string parser and fallback logic
• Create docs/mesh-url-format.md with the complete URL schema specification
• Update comments in src/qr.js to document the new mesh QR format
• No breaking changes for existing LAN-only usage

Notes

This issue is part of the filedrop-mesh epic (#155) and is blocked by issues #148, #149, and #150. The mesh transport selection logic must be implemented before this QR format can be fully integrated. The current codebase uses a simple LAN URL format, so this is a significant extension that requires careful attention to the security implications of the new URL structure.

---

When you open a PR, add Closes #151 in the description to auto-close this issue.

[muditagrawal2007]

I'd like to work on this

[git-miku]

miku 🙋

Hey @muditagrawal2007! I've assigned this issue to you. 🎉

Assignment Brief for @muditagrawal2007

---

The mesh infrastructure this issue depends on (renderMeshQR, signaling server, room codes, MeshTransport) does not exist yet in the current codebase — only the LAN-only QR/URL flow is implemented today.

What needs to be done

You're extending the QR/URL scheme so a single QR can carry both the existing LAN URL and a (future) mesh room code, letting the receiver try LAN first and fall back to mesh. Today, renderQR in src/qr.js only encodes a plain LAN URL string , and the receiver HTML embedded in src/server.js only reads the AES key from window.location.hash and fetches the download path directly — there is no fallback/transport-selection logic . You'll need to build on top of this, adding a new renderMeshQR function alongside the existing renderQR.

Acceptance criteria

• New renderMeshQR(signalUrl, roomCode, lanUrl, keyHex, options) in src/qr.js producing https://<signal-host>/r/<ROOM>#<LAN_URL>?<key>.
• Receiver page (the inline HTML in src/server.js, e.g. htmlPayload) updated to parse the new fragment format, try LAN_URL with a short timeout, and fall back to the mesh room.
• Old-client fallback: if the receiver doesn't understand the new format, it redirects to the plain LAN URL.
• Terminal metadata box (renderMetadataBox in src/qr.js) updated to show the mesh code alongside the LAN URL .
• New spec doc docs/mesh-url-format.md.

Where to start

• src/qr.js — see how renderQR builds/encodes the QR string today , and how renderMetadataBox lays out the box lines (filename, URL, mDNS name) that you'll extend with a mesh-code line .
• src/server.js — the htmlPayload template string is the receiver-side client; the key-reading and fetch logic starts here , and keyHex/downloadPath are returned from createServer for the terminal UI to build the URL .
• src/index.js orchestrates calling into qr.js/server.js from the CLI flow — check where url/keyHex/mdnsName are wired together .
• Pitfall: since mesh signaling/room-code generation and MeshTransport (sub-issues [Medium] Build @dreamstick/filedrop-signal companion package (WebSocket signaling server) #148, [Easy] Add 6-character mesh room code generator and receiver-side entry page #149, [Medium] Implement pickTransport() policy: prefer mDNS, fall back to WebRTC + signaling #150) don't appear to exist in the codebase yet, you may be blocked or need to stub these out — confirm with maintainers whether those PRs have landed before starting the receiver-side fallback logic.

PR checklist

• Unit test: QR string built by renderMeshQR roundtrips through a parser (encode → decode LAN URL, room, key).
• Unit test: LAN-first-then-mesh fallback decision logic with mocked timeouts.
• Unit test: old-client detection redirects to LAN URL only.
• Update/extend integration test similar to test/integration/full-transfer.test.js, which currently asserts on the plain #<keyHex> fragment format — this will need updating once the fragment format changes.
• Add docs/mesh-url-format.md documenting the URL schema and sentinel character choice.
• Note: this is a breaking change to the fragment format — flag backward-compatibility behavior clearly in the PR description.

---

Add Closes #151 in your PR description to auto-close this issue. Use :miku /review on the PR for a detailed code review.