nandi/frq · README.md

nandi/frqpublic⑂ Fork 0

⑂ b372e17d8499f3aca6f14defaca8fc100b6b0e6e

README.md · 265 lines · 13.5 KBmarkdown    Blame HistoryRaw
A freeq client in jolt, as glimmer components on Vidya   1
3A **[freeq](https://github.com/codegod100/freeq)** client written in
4**[jolt](https://github.com/jolt-lang/jolt)**, as
5[glimmer](https://github.com/jolt-lang/glimmer) components painted by
6**[Vidya](https://tangled.org/nandi.uk/vidya)**/egui.
8It is a proof of concept port of [sleek](../sleek), which is the same client in
9Rust against egui directly. The screens are sleek's — connect, chats, chat,
10discover, settings, under a tab bar — but each is hiccup over glimmer's widget
11tags rather than immediate-mode drawing code, and state lives in ratoms instead
12of an `AppState` struct.
Sign in with Bluesky OAuth, through freeq's broker   15src/frq/atproto.jolt handle → DID → PDS → session, and the SASL payloads
16src/frq/oauth.jolt   the broker flow: login URL, loopback capture, /session
Remember an OAuth sign-in across restarts   17src/frq/store.jolt   the saved sign-in, mode 600 in the config directory
Show who is talking, with their Bluesky picture   18src/frq/avatars.jolt profile pictures, by DID or handle
Copy sleek's profiles   19src/frq/profile.jolt who someone is: the Bluesky profile behind a nick
Show the pictures people paste   20src/frq/media.jolt   image links: spot them, fetch them once, cache on disk
Send a picture by pasting it   21src/frq/upload.jolt  a pasted picture to freeq's media endpoint, as multipart
   22src/frq/av.jolt      calls: the signaling, and a handle on the media plane
Say when each thing was said   23src/frq/clock.jolt   the reader's own zone, twelve-hour times, day headings
Pick any emoji, in colour   24src/frq/emoji.jolt   the picker's catalog: every drawable emoji and its name
Sign in with a Bluesky identity   25src/frq/irc.jolt     IRC over TLS or TCP: parser, reader thread, SASL, PRIVMSG
A freeq client in jolt, as glimmer components on Vidya   26src/frq/state.jolt   the ratoms every screen reads, and `apply-msg!`
27src/frq/app.jolt     the screens
Stop mistaking a quiet connection for a closed one   30
32`FRQ_TRACE=1` prints every IRC line sent and received to stderr, which on
33Android is logcat.
A freeq client in jolt, as glimmer components on Vidya   35
Take both native libraries from one place   37Both native libraries, then the app:
A freeq client in jolt, as glimmer components on Vidya   38
Take bb from the flake, so a checkout needs nix and nothing else   44The scripts under `scripts/` are babashka, reached through `scripts/bb`: a bb
45on `PATH` if there is one — the dev shell puts one there — and otherwise the
46flake's `.#bb`, built once and kept under `build/`. Nothing has to be installed
47for that but Nix.
Take every jolt-native half from the release, and only from there   49`just lib` fetches both shared objects this client loads —
50[jolt-native](https://gitlab.com/nandithebull/jolt-native)'s `libvidya`, the
51retained-tree ABI glimmer paints through, and `libjoltmoq`, the AV media plane
52— out of that project's release, by the digests in `scripts/*.dotslash`, and
53links them into `build/lib`. Nothing is compiled: no Rust toolchain, and no
54jolt-native checkout beside this one. It needs `patchelf`, and only to name
55libasound in `libjoltmoq.so`, which v0.1.3 does not — see the comment in
56`scripts/lib.bb`; that goes away with the release that links it. `just bump` moves every pin to the
57latest release at once, and `just bump v0.1.2` to a named one.
59`just run` is `jolt -M:frq` with `LD_LIBRARY_PATH` pointed at `build/lib`. It
60connects to `irc.freeq.at:6697` over TLS and joins `#test`. Untick TLS on the
61connect screen (or point it at `127.0.0.1`) for a local server's
A freeq client in jolt, as glimmer components on Vidya   62plain listener:
65cargo run --release --bin freeq-server        # in the freeq checkout
Paint the same screens into a terminal   68## In a terminal
70The screens are hiccup over glimmer's reconciler, and the reconciler does not
71know what is under it — so the same tree paints into a terminal through
72jolt-native's `libjolttui`, which exports libvidya's retained-tree ABI over a
Start the terminal client the way a launch starts the window one   73grid of cells instead of a GPU window.
75It is the client, not a preview of it. `frq.app/start!` is what a launch does —
76the saved settings, the rooms this client has been in, the sign-in that
77connects itself — and `src/frq/tui.jolt` hands it the terminal's timers instead
78of the window's. Nothing in `frq.app` changed.
Paint the same screens into a terminal   79
Start the terminal client the way a launch starts the window one   81nix run .#tui                             # or: just tui
Paint the same screens into a terminal   82just tui --headless --cols=90 --rows=60   # one screenshot on stdout
Start the terminal client the way a launch starts the window one   83just tui --headless --demo                # a buffer of its own, no server
84just tui --headless --wait=9000           # long enough to have connected
Fit a conversation on the screen, not two messages of one   85just tui --headless --dump                # and the tree the library holds
Paint the same screens into a terminal   86
88The headless one is `tui_headless` — the same layout and the same painting with
89the writer taken off the end — which is what a screenshot in a bug report or a
Start the terminal client the way a launch starts the window one   90CI check should be. It paints once and prints, so `--wait=` is how long the
91client is given first: the default is a picture of the connect screen, because
92that is where a client is a moment after launch, and `--demo` fills a `#tui`
93buffer for a screenshot that is not waiting on a server at all.
95Logs go to stderr, which in a terminal session is the screen frq is painting.
96Send them somewhere: `nix run .#tui 2>/tmp/frq.log`.
98What a terminal has not got, frq does without: pictures, avatars and the
99lightbox draw nothing, and calls are off — the media plane paints frames into
Fit a conversation on the screen, not two messages of one   100a texture, and there is no texture here.
102The spacing is written in points, for a window, and a cell is about eight of
103them across and sixteen down — so the backend is handed both numbers and each
104prop is divided by the axis it measures. A gap of half a cell rounds to
105nothing, which is what `:spacing 8` against a 16-point row is: thirteen
106messages fit where rounding it up left room for two.
108The two reserves in `src/frq/app.jolt` are the one thing a scale cannot
109answer, because they are counted in rows of chrome rather than in lengths: a
110window's row is 34 points and a terminal's is one cell. `chrome-row` is where
111that is said, and `frq.tui` sets it.
Start the terminal client the way a launch starts the window one   112
Merge origin/main, and let one jolt-native answer for both backends   113`just tui` is `just run`'s two halves with the other backend under them: this
114tree's source on the flake's everything-else, in the dev shell. jolt-native
115carries both native libraries and both Jolt sides — glimmer-vidya for the
116window, glimmer-tui for the terminal — so one input answers for either, and
117nothing here needs a checkout beside the tree.
Paint the same screens into a terminal   118
Sign in with a Bluesky identity   119## Signing in
Sign in with Bluesky OAuth, through freeq's broker   121Three modes on the connect screen.
Sign in with a Bluesky identity   122
Sign in with Bluesky OAuth, through freeq's broker   123**Bluesky** (OAuth, the default way in) follows sleek's flow: frq binds a
124loopback port, puts it in `return_to`, and opens
125`auth.freeq.at/auth/login?handle=…`. The broker runs the OAuth dance with the
126PDS and redirects back to that port with the handoff in the URL *fragment*, so
127it never reaches a server as a query string. The page frq serves there has one
128job: POST the fragment back to itself. What comes back is a single-use SASL
129`web-token` and a durable `broker_token`; later connections mint a fresh token
130from the durable one at `/session` and skip the browser.
Sign in with a Bluesky identity   131
Remember an OAuth sign-in across restarts   132The durable token is saved to `$XDG_CONFIG_HOME/frq/session.edn` (mode 600) so
Connect on launch when an account is remembered   133a restart resumes without one, along with the handle and nick it belongs to —
134and it connects on its own at launch when one is there.
Remember an OAuth sign-in across restarts   135The web-token beside it is single-use and deliberately not saved. A token the
136broker no longer honours is dropped — from disk and memory — and the browser
137flow runs once more, rather than failing the same way on every Connect.
Sign in with Bluesky OAuth, through freeq's broker   139**App password** signs in without a browser, straight to the user's own PDS:
140`resolveHandle` → DID → PDS from the DID document → `createSession`. The
141password goes to that PDS and nowhere else, is never written to disk, and is
142dropped once the session exists.
Sign in with a Bluesky identity   143
Sign in with Bluesky OAuth, through freeq's broker   144Either way freeq sees only a token. The SASL mechanism is
145`ATPROTO-CHALLENGE` in both cases — `method: "web-token"`, which the server
146resolves through its own token store, or `method: "pds-session"` with the
147server's nonce echoed back so the token cannot be replayed elsewhere.
149A refused sign-in is reported and the connection carries on as a guest.
Sign in with a Bluesky identity   150
A freeq client in jolt, as glimmer components on Vidya   151
Take every jolt-native half from the release, and only from there   153An APK whose native halves come from jolt-native's release and whose Jolt half
154is frq's: `libvidya.so` (the Rust/egui C ABI, which owns the event loop as the
155NativeActivity's own library), `libjoltmoq.so` (the media plane) and
156`libjoltapp.so` (frq compiled to a Chez boot image, linked against both).
A freeq client in jolt, as glimmer components on Vidya   157
Build the APK as derivations only, and retire the buck2 graph   159just apk run                    # build, install, launch on a connected device
160just apk log                    # logcat, filtered
A freeq client in jolt, as glimmer components on Vidya   161
Build the APK as derivations only, and retire the buck2 graph   163Needs nothing on the machine but Nix and an `adb`: the build is
164[`nix/android.nix`](nix/android.nix), and the SDK, the NDK, the arm64 Chez
165cross target and the OpenSSL the app carries are all built or fetched there.
166`nix build .#apk` is the same thing without adb; on a machine with a remote
167builder, hand it the store rather than a `builders` entry —
168`FRQ_NIX_STORE=ssh-ng://eu.nixbuild.net just apk`, and see the header of
169`nix/android.nix` for why.
A freeq client in jolt, as glimmer components on Vidya   170
171TLS does not work there: jolt reaches OpenSSL through the dynamic loader, and
172Android has no public `libssl` to load. The connect screen falls back to the
173plain `:6667` listener on its own, which is why the plain transport is the raw
174`socket`/`connect`/`send`/`recv` calls rather than jolt's `java.net.Socket`
175surface — that surface does not work on Android either, while the syscalls do.
177## What the PoC covers
179* TLS (`:6697`, via jolt.mvn-http's OpenSSL bindings) or plain TCP (`:6667`)
180* Guest connect (`NICK`/`USER`), `001` welcome, `PING`/`PONG` keepalive
181* Auto-joins `#test` on `irc.freeq.at`
182* Join channels, channel buffers with unread counts, send and receive `PRIVMSG`
Ask for the backlog freeq restores channels without   183* Backlog on join, and `CHATHISTORY` for the channels freeq restores instead
Say when each thing was said   184* Twelve-hour timestamps from the server's own clock, with a heading wherever
185  the day changes
Answer a message, not just read that one was answered   186* A chip above a reply quoting what it answers, and a click that goes there;
187  ↩ beside a sender to answer them, with `+draft/reply` on the way out
Pick any emoji, in colour   188* Emoji reactions: colour pills under a message, ☺ beside the sender to open a
189  picker over every emoji Vidya can draw (popular first, then Unicode's own
190  groups, searchable by name), and a second click on a pill to take yours off
191  — sent as `TAGMSG`, and restored from the server's own tally when the
192  backlog comes back
Show the pictures people paste   193* Inline previews for PNG links, fetched once and cached under
Click a picture to see it full size   194  `$XDG_CACHE_HOME/frq/media`; click one to see it full size
Send a picture by pasting it   195* Ctrl+V in the draft attaches the picture on the clipboard: it is previewed
196  under the box and uploaded to freeq's media endpoint while you write the line
197  it goes with, and only on the way out does it become the link — which is the
198  whole of what sending an image over IRC means. The draft itself is never
199  written into. Text pastes as text, as it always did: the picture path is the
200  keystroke the field had no text to answer with
A freeq client in jolt, as glimmer components on Vidya   201* Join/part notices, DMs bucketed under the sender's nick
202* Discover list, search over buffers, disconnect
Remember which rooms this client has been in   203* The rooms you have opened, remembered across runs and listed in the order
204  you last used them (`$XDG_CONFIG_HOME/frq/channels.edn`)
Order the chat list by what you were last in   205* Conversations listed most recently opened first
Show who is talking, with their Bluesky picture   206* Bluesky avatars beside the sender, resolved from the DID freeq tags each
207  message with
   208* Calls: a Call button opens one in a channel, a banner offers Join where
209  somebody already has, and in one there is mute, deafen, video and leave. Mute
210  and deafen are separate — a deafened microphone still carries your voice.
211  Whoever turns a camera on appears as a tile; the self-view is labelled You
212  and sits last, where it cannot push a face you are talking to off the row
214
216Signaling is IRC and lives here: `+freeq.at/av-start`, `av-join` and `av-leave`
217go out as TAGMSGs and the server broadcasts `+freeq.at/av-state` back, which is
218what actually moves this client's state — a press is optimistic, and the server
219settles it. Losing a race to open a call (`start-collision`) is answered by
220joining the call that won rather than by reporting an error, since the person
221asked to be in a call in that room and there is one.
223Media is not IRC and is not here. Audio and video ride MoQ — Media over QUIC —
224through freeq's SFU, and that is `libjoltmoq`: Opus, H.264, capture and
225transport, lifted out of sleek rather than written a second time in jolt.
226`src/frq/av.jolt` is the whole of what frq says to it, and two of its rules
227shape this side:
229* **Nothing calls back.** Status and video are polled, drained by a timer that
230  glimmer runs on the loop thread — the only thread allowed to touch a node.
231* **A frame is borrowed.** The decoder's own buffer is handed to Vidya as a
232  pointer and painted by an `:image` with a `:feed`. The pixels never become a
233  jolt value and are never copied on this side, which is the only way thirty
234  frames a second is affordable here.
236The SFU is dialled once the server has minted a token, not when we ask to join:
237a remote SFU refuses a connection without one, and the MoQ client then retries
238in a loop that looks exactly like a hang.
A freeq client in jolt, as glimmer components on Vidya   239
240
242* **TLS and plain TCP only** — no WebSocket, no iroh. On Android, plain only.
Sign in with Bluesky OAuth, through freeq's broker   243* **No `did:key` signing, no credential gates, no E2EE.** Sign-in of either
244  kind needs TLS, so it is desktop-only — the Android build connects as a
245
Remember an OAuth sign-in across restarts   246* **Only the broker token is persisted**, and only for OAuth. An app-password
247  sign-in is not remembered.
Show the pictures people paste   248* **Previews are PNG only** — the tree backend's decoder reads no other
249  format, and a fetch needs TLS, so the phone shows links. The link is left in
250  place either way.
251* **Nothing evicts the media cache.**
   252* **Calls are desktop-only.** `libjoltmoq` is not built for Android here, and
253  the camera and microphone paths that are would still need the runtime
254  permissions the APK does not ask for.
255* **One call at a time**, which is the media plane's rule and the microphone's.
256* **No call is offered in a DM** — freeq's AV signaling is a channel's.
Send a picture by pasting it   257* **Pasting a picture needs a sign-in and a desktop.** The upload is filed
258  under the DID of a live session, so a guest cannot make one; and it is read
259  off the clipboard through the ABI's `vidya_clipboard_image_png`, which
260  arboard backs on desktop and nothing backs on Android. It also shares
261  nothing to your PDS and posts nothing to Bluesky — those fields are opt-in
262  and this client does not send them.
   263* **No scrollback trimming or threads.**
Stop mistaking a quiet connection for a closed one   264* A sent line waits up to 200ms for the reader thread to flush it.
A freeq client in jolt, as glimmer components on Vidya   265* Message lists are keyed vboxes; glimmer-vidya has no `:listbox` yet.

A freeq client in jolt, as glimmer components on Vidya 4719d6f nandi 20d ago	1	# frq
	2
	3	A [freeq](https://github.com/codegod100/freeq) client written in
	4	[jolt](https://github.com/jolt-lang/jolt), as
	5	[glimmer](https://github.com/jolt-lang/glimmer) components painted by
	6	[Vidya](https://tangled.org/nandi.uk/vidya)/egui.
	7
	8	It is a proof of concept port of [sleek](../sleek), which is the same client in
	9	Rust against egui directly. The screens are sleek's — connect, chats, chat,
	10	discover, settings, under a tab bar — but each is hiccup over glimmer's widget
	11	tags rather than immediate-mode drawing code, and state lives in ratoms instead
	12	of an `AppState` struct.
	13
	14	```
Sign in with Bluesky OAuth, through freeq's broker 2d4a377 nandi 20d ago	15	src/frq/atproto.jolt handle → DID → PDS → session, and the SASL payloads
	16	src/frq/oauth.jolt the broker flow: login URL, loopback capture, /session
Remember an OAuth sign-in across restarts 4aa71e7 nandi 20d ago	17	src/frq/store.jolt the saved sign-in, mode 600 in the config directory
Show who is talking, with their Bluesky picture f5548bd nandi 20d ago	18	src/frq/avatars.jolt profile pictures, by DID or handle
Copy sleek's profiles b79ebc4 nandi 19d ago	19	src/frq/profile.jolt who someone is: the Bluesky profile behind a nick
Show the pictures people paste 56cdac3 nandi 20d ago	20	src/frq/media.jolt image links: spot them, fetch them once, cache on disk
Send a picture by pasting it 8a491ba nandi 19d ago	21	src/frq/upload.jolt a pasted picture to freeq's media endpoint, as multipart
Calls f31ad3d nandi 19d ago	22	src/frq/av.jolt calls: the signaling, and a handle on the media plane
Say when each thing was said dbf3b86 nandi 20d ago	23	src/frq/clock.jolt the reader's own zone, twelve-hour times, day headings
Pick any emoji, in colour 18c5ccd nandi 19d ago	24	src/frq/emoji.jolt the picker's catalog: every drawable emoji and its name
Sign in with a Bluesky identity 5192124 nandi 20d ago	25	src/frq/irc.jolt IRC over TLS or TCP: parser, reader thread, SASL, PRIVMSG
A freeq client in jolt, as glimmer components on Vidya 4719d6f nandi 20d ago	26	src/frq/state.jolt the ratoms every screen reads, and `apply-msg!`
	27	src/frq/app.jolt the screens
	28	```
	29
Stop mistaking a quiet connection for a closed one a225fb1 nandi 20d ago	30	## Tracing
	31
	32	`FRQ_TRACE=1` prints every IRC line sent and received to stderr, which on
	33	Android is logcat.
	34
A freeq client in jolt, as glimmer components on Vidya 4719d6f nandi 20d ago	35	## Running
	36
Take both native libraries from one place a66d1c1 nandi 19d ago	37	Both native libraries, then the app:
A freeq client in jolt, as glimmer components on Vidya 4719d6f nandi 20d ago	38
	39	```bash
	40	just lib
	41	just run
	42	```
	43
Take bb from the flake, so a checkout needs nix and nothing else 270bee0 nandi 16d ago	44	The scripts under `scripts/` are babashka, reached through `scripts/bb`: a bb
	45	on `PATH` if there is one — the dev shell puts one there — and otherwise the
	46	flake's `.#bb`, built once and kept under `build/`. Nothing has to be installed
	47	for that but Nix.
	48
Take every jolt-native half from the release, and only from there a008d3b nandi 18d ago	49	`just lib` fetches both shared objects this client loads —
	50	[jolt-native](https://gitlab.com/nandithebull/jolt-native)'s `libvidya`, the
	51	retained-tree ABI glimmer paints through, and `libjoltmoq`, the AV media plane
	52	— out of that project's release, by the digests in `scripts/*.dotslash`, and
	53	links them into `build/lib`. Nothing is compiled: no Rust toolchain, and no
	54	jolt-native checkout beside this one. It needs `patchelf`, and only to name
	55	libasound in `libjoltmoq.so`, which v0.1.3 does not — see the comment in
	56	`scripts/lib.bb`; that goes away with the release that links it. `just bump` moves every pin to the
	57	latest release at once, and `just bump v0.1.2` to a named one.
	58
	59	`just run` is `jolt -M:frq` with `LD_LIBRARY_PATH` pointed at `build/lib`. It
	60	connects to `irc.freeq.at:6697` over TLS and joins `#test`. Untick TLS on the
	61	connect screen (or point it at `127.0.0.1`) for a local server's
A freeq client in jolt, as glimmer components on Vidya 4719d6f nandi 20d ago	62	plain listener:
	63
	64	```bash
	65	cargo run --release --bin freeq-server # in the freeq checkout
	66	```
	67
Paint the same screens into a terminal ab83b42 nandi 17d ago	68	## In a terminal
	69
	70	The screens are hiccup over glimmer's reconciler, and the reconciler does not
	71	know what is under it — so the same tree paints into a terminal through
	72	jolt-native's `libjolttui`, which exports libvidya's retained-tree ABI over a
Start the terminal client the way a launch starts the window one 4f04b91 nandi 17d ago	73	grid of cells instead of a GPU window.
	74
	75	It is the client, not a preview of it. `frq.app/start!` is what a launch does —
	76	the saved settings, the rooms this client has been in, the sign-in that
	77	connects itself — and `src/frq/tui.jolt` hands it the terminal's timers instead
	78	of the window's. Nothing in `frq.app` changed.
Paint the same screens into a terminal ab83b42 nandi 17d ago	79
	80	```bash
Start the terminal client the way a launch starts the window one 4f04b91 nandi 17d ago	81	nix run .#tui # or: just tui
Paint the same screens into a terminal ab83b42 nandi 17d ago	82	just tui --headless --cols=90 --rows=60 # one screenshot on stdout
Start the terminal client the way a launch starts the window one 4f04b91 nandi 17d ago	83	just tui --headless --demo # a buffer of its own, no server
	84	just tui --headless --wait=9000 # long enough to have connected
Fit a conversation on the screen, not two messages of one 8a86eb3 nandi 17d ago	85	just tui --headless --dump # and the tree the library holds
Paint the same screens into a terminal ab83b42 nandi 17d ago	86	```
	87
	88	The headless one is `tui_headless` — the same layout and the same painting with
	89	the writer taken off the end — which is what a screenshot in a bug report or a
Start the terminal client the way a launch starts the window one 4f04b91 nandi 17d ago	90	CI check should be. It paints once and prints, so `--wait=` is how long the
	91	client is given first: the default is a picture of the connect screen, because
	92	that is where a client is a moment after launch, and `--demo` fills a `#tui`
	93	buffer for a screenshot that is not waiting on a server at all.
	94
	95	Logs go to stderr, which in a terminal session is the screen frq is painting.
	96	Send them somewhere: `nix run .#tui 2>/tmp/frq.log`.
	97
	98	What a terminal has not got, frq does without: pictures, avatars and the
	99	lightbox draw nothing, and calls are off — the media plane paints frames into
Fit a conversation on the screen, not two messages of one 8a86eb3 nandi 17d ago	100	a texture, and there is no texture here.
	101
	102	The spacing is written in points, for a window, and a cell is about eight of
	103	them across and sixteen down — so the backend is handed both numbers and each
	104	prop is divided by the axis it measures. A gap of half a cell rounds to
	105	nothing, which is what `:spacing 8` against a 16-point row is: thirteen
	106	messages fit where rounding it up left room for two.
	107
	108	The two reserves in `src/frq/app.jolt` are the one thing a scale cannot
	109	answer, because they are counted in rows of chrome rather than in lengths: a
	110	window's row is 34 points and a terminal's is one cell. `chrome-row` is where
	111	that is said, and `frq.tui` sets it.
Start the terminal client the way a launch starts the window one 4f04b91 nandi 17d ago	112
Merge origin/main, and let one jolt-native answer for both backends 1e8b590 nandi 16d ago	113	`just tui` is `just run`'s two halves with the other backend under them: this
	114	tree's source on the flake's everything-else, in the dev shell. jolt-native
	115	carries both native libraries and both Jolt sides — glimmer-vidya for the
	116	window, glimmer-tui for the terminal — so one input answers for either, and
	117	nothing here needs a checkout beside the tree.
Paint the same screens into a terminal ab83b42 nandi 17d ago	118
Sign in with a Bluesky identity 5192124 nandi 20d ago	119	## Signing in
Sign in with a Bluesky identity 5192124 nandi 20d ago	120
Sign in with Bluesky OAuth, through freeq's broker 2d4a377 nandi 20d ago	121	Three modes on the connect screen.
Sign in with a Bluesky identity 5192124 nandi 20d ago	122
Sign in with Bluesky OAuth, through freeq's broker 2d4a377 nandi 20d ago	123	Bluesky (OAuth, the default way in) follows sleek's flow: frq binds a
	124	loopback port, puts it in `return_to`, and opens
	125	`auth.freeq.at/auth/login?handle=…`. The broker runs the OAuth dance with the
	126	PDS and redirects back to that port with the handoff in the URL fragment, so
	127	it never reaches a server as a query string. The page frq serves there has one
	128	job: POST the fragment back to itself. What comes back is a single-use SASL
	129	`web-token` and a durable `broker_token`; later connections mint a fresh token
	130	from the durable one at `/session` and skip the browser.
Sign in with a Bluesky identity 5192124 nandi 20d ago	131
Remember an OAuth sign-in across restarts 4aa71e7 nandi 20d ago	132	The durable token is saved to `$XDG_CONFIG_HOME/frq/session.edn` (mode 600) so
Connect on launch when an account is remembered 9237cf4 nandi 20d ago	133	a restart resumes without one, along with the handle and nick it belongs to —
	134	and it connects on its own at launch when one is there.
Remember an OAuth sign-in across restarts 4aa71e7 nandi 20d ago	135	The web-token beside it is single-use and deliberately not saved. A token the
	136	broker no longer honours is dropped — from disk and memory — and the browser
	137	flow runs once more, rather than failing the same way on every Connect.
	138
Sign in with Bluesky OAuth, through freeq's broker 2d4a377 nandi 20d ago	139	App password signs in without a browser, straight to the user's own PDS:
	140	`resolveHandle` → DID → PDS from the DID document → `createSession`. The
	141	password goes to that PDS and nowhere else, is never written to disk, and is
	142	dropped once the session exists.
Sign in with a Bluesky identity 5192124 nandi 20d ago	143
Sign in with Bluesky OAuth, through freeq's broker 2d4a377 nandi 20d ago	144	Either way freeq sees only a token. The SASL mechanism is
	145	`ATPROTO-CHALLENGE` in both cases — `method: "web-token"`, which the server
	146	resolves through its own token store, or `method: "pds-session"` with the
	147	server's nonce echoed back so the token cannot be replayed elsewhere.
	148
	149	A refused sign-in is reported and the connection carries on as a guest.
Sign in with a Bluesky identity 5192124 nandi 20d ago	150
A freeq client in jolt, as glimmer components on Vidya 4719d6f nandi 20d ago	151	## Android
	152
Take every jolt-native half from the release, and only from there a008d3b nandi 18d ago	153	An APK whose native halves come from jolt-native's release and whose Jolt half
	154	is frq's: `libvidya.so` (the Rust/egui C ABI, which owns the event loop as the
	155	NativeActivity's own library), `libjoltmoq.so` (the media plane) and
	156	`libjoltapp.so` (frq compiled to a Chez boot image, linked against both).
A freeq client in jolt, as glimmer components on Vidya 4719d6f nandi 20d ago	157
	158	```bash
Build the APK as derivations only, and retire the buck2 graph 3bc3aaa nandi 16d ago	159	just apk run # build, install, launch on a connected device
	160	just apk log # logcat, filtered
A freeq client in jolt, as glimmer components on Vidya 4719d6f nandi 20d ago	161	```
	162
Build the APK as derivations only, and retire the buck2 graph 3bc3aaa nandi 16d ago	163	Needs nothing on the machine but Nix and an `adb`: the build is
	164	[`nix/android.nix`](nix/android.nix), and the SDK, the NDK, the arm64 Chez
	165	cross target and the OpenSSL the app carries are all built or fetched there.
	166	`nix build .#apk` is the same thing without adb; on a machine with a remote
	167	builder, hand it the store rather than a `builders` entry —
	168	`FRQ_NIX_STORE=ssh-ng://eu.nixbuild.net just apk`, and see the header of
	169	`nix/android.nix` for why.
A freeq client in jolt, as glimmer components on Vidya 4719d6f nandi 20d ago	170
	171	TLS does not work there: jolt reaches OpenSSL through the dynamic loader, and
	172	Android has no public `libssl` to load. The connect screen falls back to the
	173	plain `:6667` listener on its own, which is why the plain transport is the raw
	174	`socket`/`connect`/`send`/`recv` calls rather than jolt's `java.net.Socket`
	175	surface — that surface does not work on Android either, while the syscalls do.
	176
	177	## What the PoC covers
	178
	179	* TLS (`:6697`, via jolt.mvn-http's OpenSSL bindings) or plain TCP (`:6667`)
	180	* Guest connect (`NICK`/`USER`), `001` welcome, `PING`/`PONG` keepalive
	181	* Auto-joins `#test` on `irc.freeq.at`
	182	* Join channels, channel buffers with unread counts, send and receive `PRIVMSG`
Ask for the backlog freeq restores channels without 94e59a2 nandi 20d ago	183	* Backlog on join, and `CHATHISTORY` for the channels freeq restores instead
Say when each thing was said dbf3b86 nandi 20d ago	184	* Twelve-hour timestamps from the server's own clock, with a heading wherever
Say when each thing was said dbf3b86 nandi 20d ago	185	the day changes
Answer a message, not just read that one was answered 4876db8 nandi 20d ago	186	* A chip above a reply quoting what it answers, and a click that goes there;
	187	↩ beside a sender to answer them, with `+draft/reply` on the way out
Pick any emoji, in colour 18c5ccd nandi 19d ago	188	* Emoji reactions: colour pills under a message, ☺ beside the sender to open a
	189	picker over every emoji Vidya can draw (popular first, then Unicode's own
	190	groups, searchable by name), and a second click on a pill to take yours off
	191	— sent as `TAGMSG`, and restored from the server's own tally when the
	192	backlog comes back
Show the pictures people paste 56cdac3 nandi 20d ago	193	* Inline previews for PNG links, fetched once and cached under
Click a picture to see it full size 563ada3 nandi 20d ago	194	`$XDG_CACHE_HOME/frq/media`; click one to see it full size
Send a picture by pasting it 8a491ba nandi 19d ago	195	* Ctrl+V in the draft attaches the picture on the clipboard: it is previewed
	196	under the box and uploaded to freeq's media endpoint while you write the line
	197	it goes with, and only on the way out does it become the link — which is the
	198	whole of what sending an image over IRC means. The draft itself is never
	199	written into. Text pastes as text, as it always did: the picture path is the
	200	keystroke the field had no text to answer with
A freeq client in jolt, as glimmer components on Vidya 4719d6f nandi 20d ago	201	* Join/part notices, DMs bucketed under the sender's nick
	202	* Discover list, search over buffers, disconnect
Remember which rooms this client has been in 1d062fd nandi 20d ago	203	* The rooms you have opened, remembered across runs and listed in the order
	204	you last used them (`$XDG_CONFIG_HOME/frq/channels.edn`)
Order the chat list by what you were last in 75e557e nandi 20d ago	205	* Conversations listed most recently opened first
Show who is talking, with their Bluesky picture f5548bd nandi 20d ago	206	* Bluesky avatars beside the sender, resolved from the DID freeq tags each
	207	message with
Calls f31ad3d nandi 19d ago	208	* Calls: a Call button opens one in a channel, a banner offers Join where
	209	somebody already has, and in one there is mute, deafen, video and leave. Mute
	210	and deafen are separate — a deafened microphone still carries your voice.
	211	Whoever turns a camera on appears as a tile; the self-view is labelled You
	212	and sits last, where it cannot push a face you are talking to off the row
	213
	214	## Calls
	215
	216	Signaling is IRC and lives here: `+freeq.at/av-start`, `av-join` and `av-leave`
	217	go out as TAGMSGs and the server broadcasts `+freeq.at/av-state` back, which is
	218	what actually moves this client's state — a press is optimistic, and the server
	219	settles it. Losing a race to open a call (`start-collision`) is answered by
	220	joining the call that won rather than by reporting an error, since the person
	221	asked to be in a call in that room and there is one.
	222
	223	Media is not IRC and is not here. Audio and video ride MoQ — Media over QUIC —
	224	through freeq's SFU, and that is `libjoltmoq`: Opus, H.264, capture and
	225	transport, lifted out of sleek rather than written a second time in jolt.
	226	`src/frq/av.jolt` is the whole of what frq says to it, and two of its rules
	227	shape this side:
	228
	229	* Nothing calls back. Status and video are polled, drained by a timer that
	230	glimmer runs on the loop thread — the only thread allowed to touch a node.
	231	* A frame is borrowed. The decoder's own buffer is handed to Vidya as a
	232	pointer and painted by an `:image` with a `:feed`. The pixels never become a
	233	jolt value and are never copied on this side, which is the only way thirty
	234	frames a second is affordable here.
	235
	236	The SFU is dialled once the server has minted a token, not when we ask to join:
	237	a remote SFU refuses a connection without one, and the MoQ client then retries
	238	in a loop that looks exactly like a hang.
A freeq client in jolt, as glimmer components on Vidya 4719d6f nandi 20d ago	239
	240	## Limits
	241
	242	* TLS and plain TCP only — no WebSocket, no iroh. On Android, plain only.
Sign in with Bluesky OAuth, through freeq's broker 2d4a377 nandi 20d ago	243	* No `did:key` signing, no credential gates, no E2EE. Sign-in of either
	244	kind needs TLS, so it is desktop-only — the Android build connects as a
	245	guest.
Remember an OAuth sign-in across restarts 4aa71e7 nandi 20d ago	246	* Only the broker token is persisted, and only for OAuth. An app-password
	247	sign-in is not remembered.
Show the pictures people paste 56cdac3 nandi 20d ago	248	* Previews are PNG only — the tree backend's decoder reads no other
	249	format, and a fetch needs TLS, so the phone shows links. The link is left in
	250	place either way.
	251	* Nothing evicts the media cache.
Calls f31ad3d nandi 19d ago	252	* Calls are desktop-only. `libjoltmoq` is not built for Android here, and
	253	the camera and microphone paths that are would still need the runtime
	254	permissions the APK does not ask for.
	255	* One call at a time, which is the media plane's rule and the microphone's.
	256	* No call is offered in a DM — freeq's AV signaling is a channel's.
Send a picture by pasting it 8a491ba nandi 19d ago	257	* Pasting a picture needs a sign-in and a desktop. The upload is filed
	258	under the DID of a live session, so a guest cannot make one; and it is read
	259	off the clipboard through the ABI's `vidya_clipboard_image_png`, which
	260	arboard backs on desktop and nothing backs on Android. It also shares
	261	nothing to your PDS and posts nothing to Bluesky — those fields are opt-in
	262	and this client does not send them.
Calls f31ad3d nandi 19d ago	263	* No scrollback trimming or threads.
Stop mistaking a quiet connection for a closed one a225fb1 nandi 20d ago	264	* A sent line waits up to 200ms for the reader thread to flush it.
A freeq client in jolt, as glimmer components on Vidya 4719d6f nandi 20d ago	265	* Message lists are keyed vboxes; glimmer-vidya has no `:listbox` yet.