Node-based terminal manager for AI coding agents — tmux-backed terminals and parallel agent sessions as draggable nodes on an infinite pan/zoom canvas. macOS, Linux, and a browser Server Edition.
TypeScript adhdagent-orchestrationai-agentscanvasclaude-codecodexcoding-agentsdeveloper-toolselectrongeminilinuxmacosmultiplexeropencodeparallel-agentsterminalterminal-emulatorterminal-multiplexertmuxworkspace-manager
feat(pair): offer the pairing QR in the app's URL scheme so the iPhone Camera can open it
enes3833ac80a55e
diff --git a/src/main/pairing-core.test.ts b/src/main/pairing-core.test.tsindex 128635a7e..69e02b665 100644--- a/src/main/pairing-core.test.ts+++ b/src/main/pairing-core.test.ts@@ -1,4 +1,5 @@import { describe, it, expect } from 'vitest'+import { encodePairQr, PAIR_URL_PREFIX } from '@shared/pair-qr'import {buildPairingPayload,deviceCommentFor,@@ -370,3 +371,34 @@ describe('pickLanIPv4', () => {).toBe(null)})})++// The QR ENVELOPE (src/shared/pair-qr.ts) composed with the real payload builder. The encoder's+// own edge cases are covered there; this pins the one thing only this project can check — that+// what the builder emits survives the URL wrapping byte-for-byte (eneskirca/nodeterm#745).+describe('encodePairQr over a built payload', () => {+ const payload = buildPairingPayload({+ host: '192.168.1.5',+ port: 22,+ user: 'enes',+ token: 'tok',+ pairPort: 5,+ name: 'Mac',+ hostKey: 'AAAAhostpub',+ relay: {+ hostId: 'abcABC012_-def012ghij',+ hostPublicKeyB64: 'AAAAhostpub',+ relayEndpoint: 'wss://relay.nodeterm.dev'+ }+ })++ it('leaves the payload untouched in the default (json) form', () => {+ expect(encodePairQr(payload)).toBe(payload)+ })++ it('round-trips the built payload through the url form', () => {+ const url = encodePairQr(payload, 'url')+ expect(url.startsWith(PAIR_URL_PREFIX)).toBe(true)+ const code = url.slice(PAIR_URL_PREFIX.length)+ expect(Buffer.from(code, 'base64url').toString('utf-8')).toBe(payload)+ })+})diff --git a/src/renderer/components/settings/sections/PhoneSection.tsx b/src/renderer/components/settings/sections/PhoneSection.tsxindex ad72b58c4..10e5616c2 100644--- a/src/renderer/components/settings/sections/PhoneSection.tsx+++ b/src/renderer/components/settings/sections/PhoneSection.tsx@@ -63,7 +63,21 @@ export function PhoneSection({ isActive }: { isActive: boolean }): React.JSX.Ele// The shared pairing machine (also behind the top-right quick-pair popover); a completed// pairing refreshes the device list below — and drops the last revoke note, which names a device// by name and would otherwise outlive the very phone it warns about being re-paired.- const { phase, qr, sshOpen, sshHealed, relayResult, relayPlan, error, busy, start, stop, reset } = usePhonePairing(+ const {+ phase,+ qr,+ qrForm,+ setQrForm,+ sshOpen,+ sshHealed,+ relayResult,+ relayPlan,+ error,+ busy,+ start,+ stop,+ reset+ } = usePhonePairing(() => {setRevokeNote(null)void refreshDevices()@@ -232,6 +246,30 @@ export function PhoneSection({ isActive }: { isActive: boolean }): React.JSX.EleclassName="rounded-lg bg-white p-2"/><p className="text-sm text-muted">Waiting for your phone… (10 min)</p>+ {/* eneskirca/nodeterm#745: the default QR encodes the payload as raw JSON,+ which the iPhone's Camera app can only show as text — there is nothing in+ it to open. This switches the SAME live token to the app's URL scheme so+ Camera can hand it to nodeterm. Opt-in, because a phone on an app version+ without URL support reads only the JSON form. */}+ <div className="space-y-1">+ <button+ type="button"+ className="text-xs text-muted underline"+ onClick={() => setQrForm(qrForm === 'url' ? 'json' : 'url')}+ >+ {qrForm === 'url'+ ? 'Show the in-app code instead'+ : 'Scan with the iPhone Camera app instead'}+ </button>+ {qrForm === 'url' ? (+ <p className="text-xs text-muted">+ Point the iPhone's own Camera at this and tap the nodeterm banner.+ Needs a recent version of the iOS app — if your phone doesn't+ recognise it, switch back and scan from inside nodeterm. Same code+ either way; switching doesn't restart pairing.+ </p>+ ) : null}+ </div>{relayPlan === 'dev' ? (<p className="text-sm" style={{ color: '#ff9f0a' }}>Dev build: the relay is off regardless of the toggle, so this code pairsdiff --git a/src/renderer/components/settings/usePhonePairing.ts b/src/renderer/components/settings/usePhonePairing.tsindex c6f5c03c2..3164e03e1 100644--- a/src/renderer/components/settings/usePhonePairing.ts+++ b/src/renderer/components/settings/usePhonePairing.ts@@ -1,5 +1,6 @@import { useEffect, useRef, useState } from 'react'import { toDataURL } from 'qrcode'+import { DEFAULT_PAIR_QR_FORM, encodePairQr, type PairQrForm } from '@shared/pair-qr'export type PairingPhase = 'idle' | 'waiting' | 'paired' | 'timeout'@@ -16,6 +17,10 @@ const SSH_RECHECK_MS = 2000export function usePhonePairing(onPaired?: () => void): {phase: PairingPhaseqr: string+ /** Which envelope the QR on screen encodes. Switching it re-renders the SAME live token —+ * it never restarts pairing (eneskirca/nodeterm#745). */+ qrForm: PairQrForm+ setQrForm: (form: PairQrForm) => voidsshOpen: booleansshHealed: boolean/** On phase 'paired': whether the pairing came with a relay leg ('off' = toggle disabled,@@ -33,6 +38,10 @@ export function usePhonePairing(onPaired?: () => void): {} {const [phase, setPhase] = useState<PairingPhase>('idle')const [qr, setQr] = useState('')+ // The built payload JSON, kept so the QR can be re-encoded in the other envelope without+ // minting a new token — the listener on the other end is keyed to THIS one.+ const [payload, setPayload] = useState('')+ const [qrForm, setQrForm] = useState<PairQrForm>(DEFAULT_PAIR_QR_FORM)const [sshOpen, setSshOpen] = useState(true)// Went from unreachable → reachable while the warning was showing: show a green confirmation// instead of silently dropping the warning (the user just flipped a toggle; acknowledge it).@@ -74,10 +83,11 @@ export function usePhonePairing(onPaired?: () => void): {setError('')setBusy(true)try {- const { payload, sshOpen: open, relayPlan: plan } = await window.nodeTerminal.pairing.start()+ const { payload: built, sshOpen: open, relayPlan: plan } = await window.nodeTerminal.pairing.start()setRelayPlan(plan ?? null)- const dataUrl = await toDataURL(payload, { margin: 1, width: 240 })- setQr(dataUrl)+ // The image itself is rendered by the effect below, which also handles a later switch+ // between the JSON and URL envelopes.+ setPayload(built)setSshOpen(open)setSshHealed(false)setRelayResult(null)@@ -90,12 +100,35 @@ export function usePhonePairing(onPaired?: () => void): {}}+ // Render the QR for whatever payload + envelope is current. Re-runs when the user switches+ // envelope, which is deliberately NOT a restart: same token, same listener, different+ // encoding of the same bytes.+ useEffect(() => {+ if (!payload) {+ setQr('')+ return+ }+ let cancelled = false+ void toDataURL(encodePairQr(payload, qrForm), { margin: 1, width: 240 })+ .then((dataUrl) => {+ if (!cancelled) setQr(dataUrl)+ })+ .catch(() => {+ // Keep whatever image is already up; the pairing listener is unaffected by a render+ // failure, and a blank QR with no explanation is the failure mode #745 was about.+ })+ return () => {+ cancelled = true+ }+ }, [payload, qrForm])+const stop = (): void => {if (runningRef.current) {runningRef.current = falsevoid window.nodeTerminal.pairing.stop()}setPhase('idle')+ setPayload('')setQr('')}@@ -106,6 +139,7 @@ export function usePhonePairing(onPaired?: () => void): {useEffect(() => {return window.nodeTerminal.pairing.onDone((result) => {runningRef.current = false+ setPayload('')setQr('')setPhase(result.ok ? 'paired' : 'timeout')setRelayResult(result.ok ? (result.relay ?? null) : null)@@ -123,5 +157,19 @@ export function usePhonePairing(onPaired?: () => void): {}}, [])- return { phase, qr, sshOpen, sshHealed, relayResult, relayPlan, error, busy, start, stop, reset: () => setPhase('idle') }+ return {+ phase,+ qr,+ qrForm,+ setQrForm,+ sshOpen,+ sshHealed,+ relayResult,+ relayPlan,+ error,+ busy,+ start,+ stop,+ reset: () => setPhase('idle')+ }}diff --git a/src/shared/pair-qr.test.ts b/src/shared/pair-qr.test.tsnew file mode 100644index 000000000..25df8d070--- /dev/null+++ b/src/shared/pair-qr.test.ts@@ -0,0 +1,49 @@+import { describe, it, expect } from 'vitest'+import { encodePairQr, PAIR_URL_PREFIX, DEFAULT_PAIR_QR_FORM } from './pair-qr'++// The exact string `buildPairingPayload` emits, as a literal: this file belongs to the web+// tsconfig project and cannot import from src/main. The composition with the real builder is+// asserted in `src/main/pairing-core.test.ts` instead.+const payload =+ '{"v":1,"host":"192.168.1.5","port":22,"user":"enes","token":"tok123","pairPort":54321,"nodeterm":true,"name":"MacBook"}'++describe('encodePairQr', () => {+ it('defaults to the raw JSON every shipped iOS version can read', () => {+ expect(DEFAULT_PAIR_QR_FORM).toBe('json')+ expect(encodePairQr(payload)).toBe(payload)+ expect(encodePairQr(payload, 'json')).toBe(payload)+ })++ it('wraps the SAME bytes in the app URL scheme for the url form', () => {+ const url = encodePairQr(payload, 'url')+ expect(url.startsWith(PAIR_URL_PREFIX)).toBe(true)+ const code = url.slice(PAIR_URL_PREFIX.length)+ expect(Buffer.from(code, 'base64url').toString('utf-8')).toBe(payload)+ })++ it('emits base64url, not base64 — the code rides in a query parameter', () => {+ // A payload whose base64 is guaranteed to contain + and / unless base64url is used.+ const awkward = JSON.stringify({ v: 1, name: 'ÿÿÿþ>?>?', host: 'a'.repeat(3) })+ const code = encodePairQr(awkward, 'url').slice(PAIR_URL_PREFIX.length)+ expect(code).not.toMatch(/[+/=]/)+ expect(Buffer.from(code, 'base64url').toString('utf-8')).toBe(awkward)+ })++ it('round-trips a payload carrying the relay block and host key', () => {+ const full =+ '{"v":1,"host":"10.0.0.2","port":22,"user":"enes","token":"tok","pairPort":5,' ++ '"nodeterm":true,"name":"Mac","hostKey":"AAAAhostpub","relay":' ++ '{"hostId":"abcABC012_-def012ghij","hostPublicKeyB64":"AAAAhostpub",' ++ '"relayEndpoint":"wss://relay.nodeterm.dev"}}'+ const code = encodePairQr(full, 'url').slice(PAIR_URL_PREFIX.length)+ expect(Buffer.from(code, 'base64url').toString('utf-8')).toBe(full)+ })++ it('produces a URL the phone-side parse rules accept (scheme, host, code param)', () => {+ const url = new URL(encodePairQr(payload, 'url'))+ expect(url.protocol).toBe('nodeterm:')+ expect(url.hostname).toBe('pair')+ expect(url.pathname === '' || url.pathname === '/').toBe(true)+ expect(url.searchParams.get('code')).toBeTruthy()+ })+})diff --git a/src/shared/pair-qr.ts b/src/shared/pair-qr.tsnew file mode 100644index 000000000..c5c038439--- /dev/null+++ b/src/shared/pair-qr.ts@@ -0,0 +1,46 @@+// What the phone-pairing QR actually encodes.+//+// The payload is built by `pairing-core.buildPairingPayload`, and its JSON shape is a fixed+// contract with the nodeterm iOS app. This module is only about the ENVELOPE that JSON is+// wrapped in on its way to becoming a QR:+//+// 'json' — the raw payload JSON. What every release so far has encoded, and the only shape+// an older iOS app can read.+// 'url' — `nodeterm://pair?code=<base64url(json)>`. The same bytes, wrapped in the app's+// registered URL scheme.+//+// Why 'url' exists (eneskirca/nodeterm#745): a QR carrying raw JSON is just *text* to the+// iPhone's system Camera app — there is nothing in it to open, which is why scanning the+// pairing QR with Camera does nothing. A URL is the only shape Camera can act on.+//+// Mirrors `PairURL` + `PairingService.decode` on the phone (nodeterm-ios#23), which accept the+// URL form, the raw JSON, and a bare base64url code. 'json' stays the DEFAULT until that phone+// build has shipped widely — see the note on `DEFAULT_PAIR_QR_FORM`.++export type PairQrForm = 'json' | 'url'++/** The scheme + host + parameter the phone matches on. Same envelope as the relay offer. */+export const PAIR_URL_PREFIX = 'nodeterm://pair?code='++/**+ * The form used unless the user asks for the other one.+ *+ * Deliberately 'json': a phone running an app version that predates URL support decodes the QR+ * as payload JSON and nothing else, so emitting URLs by default would silently break pairing+ * for everyone who has not updated — the exact failure #745 reported, re-created for a+ * different group. Flip this only once the URL-accepting iOS build is out and adopted.+ */+export const DEFAULT_PAIR_QR_FORM: PairQrForm = 'json'++/** base64url, no padding. Uses `btoa`, a global in both the renderer and Node ≥ 16. */+function base64url(input: string): string {+ const bytes = new TextEncoder().encode(input)+ let binary = ''+ for (const b of bytes) binary += String.fromCharCode(b)+ return btoa(binary).replace(/\+/g, '-').replace(/\//g, '_').replace(/=+$/, '')+}++/** Wrap a built pairing payload in the requested envelope. Pure; never throws. */+export function encodePairQr(payloadJson: string, form: PairQrForm = DEFAULT_PAIR_QR_FORM): string {+ return form === 'url' ? `${PAIR_URL_PREFIX}${base64url(payloadJson)}` : payloadJson+}