| Split the tree three ways, and let the phone be Flutter's 7070931 nandi 7d ago | 1 | # The ClojureDart half |
| 2 | |
| 3 | Nothing here builds yet. This is the boundary, drawn before the port rather |
| 4 | than after it, so that the question "can this file go on the phone?" has a |
| 5 | filesystem answer. |
| 6 | |
| 7 | ## The three trees |
| 8 | |
| 9 | ``` |
| 10 | common/ .cljc both compilers. No jolt, no glimmer, no dart. |
| 11 | src/ .clj jolt: glimmer, jolt.ffi, the cosmic and tui backends. |
| 12 | flutter/ .cljd ClojureDart: Flutter widgets, dart:io, dart:ffi. |
| 13 | ``` |
| 14 | |
| 15 | The extension is the boundary and the compilers enforce it. ClojureDart reads |
| 16 | `.cljd` and `.cljc` and never `.clj`, so a namespace that reaches for |
| 17 | `jolt.host` cannot accidentally end up in the APK — it is a `.clj` and the Dart |
| 18 | compiler cannot see it. jolt reads all three, which is why `common/` works at |
| 19 | all: one copy of `frq.clock`, compiled twice. |
| 20 | |
| 21 | Where both need a namespace but the answer differs, `.cljd` wins over `.cljc` |
| 22 | in ClojureDart's own resolution, so a file here shadows a shared one without |
| 23 | either side knowing. Reader conditionals work too, with one trap from |
| 24 | ClojureDart's FAQ: the `:clj` feature is always on under cljd, so `:clj` goes |
| 25 | **last** in a conditional, and macro code that wants the Clojure path during |
| 26 | host evaluation asks for `:cljd/clj-host`. |
| 27 | |
| 28 | ## What has crossed |
| 29 | |
| 30 | `frq.io` is the seam — the host's job named once, with `frq.io.jolt` answering |
| 31 | it on the desktop and `frq.io.dart` here. It carries the filesystem, the |
| 32 | environment, the config directory and the clock. |
| 33 | |
| 34 | Moved to `common/` and running under jolt today: |
| 35 | |
| 36 | | namespace | lines | note | |
| 37 | |---------------|-------|-------------------------------------------------| |
| 38 | | `frq.emoji` | 1,914 | data; nothing to port | |
| 39 | | `frq.glyphs` | 84 | data | |
| 40 | | `frq.av.dial` | 117 | already touched neither jolt nor glimmer | |
| 41 | | `frq.clock` | 93 | zone-hunting moved into the backends | |
| 42 | | `frq.store` | 122 | `install -m 600` became `write-private-file!` | |
| 43 | |
| 44 | `frq.clock` is the shape the rest should follow. It used to open with four |
| 45 | guesses at the reader's zone — `TZ`, the target of `/etc/localtime`, the file |
| 46 | itself by path, then Android's `persist.sys.timezone` — and then convert days |
| 47 | to a date by printing one with `jolt.time.local` and taking a `subs` of the |
| 48 | result. Both are gone: the guessing is a libc question and lives in |
| 49 | `frq.io.jolt`, where Dart answers it in one call instead; the conversion is |
| 50 | eleven lines of Hinnant's algorithm, checked against `java.time.LocalDate` for |
| 51 | every day from 1901 to 2052. |
| 52 | |
| 53 | ## What has not |
| 54 | |
| 55 | Roughly 4,000 lines are portable in substance and still `.clj` because the seam |
| 56 | does not reach far enough yet. In the order worth doing them: |
| 57 | |
| 58 | 1. **`frq.wire`, `frq.msgsig`** — need a crypto seam beside the io one. |
| 59 | 2. **`frq.irc`** (433) — the parser is pure; the reader is a blocking thread in |
| 60 | a `future`, and Dart has no threads. It becomes a `Stream` over |
| 61 | `SecureSocket`, which is also what makes TLS work on the phone at all. |
| 62 | 3. **`frq.atproto`** (209), **`frq.oauth`** (182) — hand-rolled HTTPS over |
| 63 | `jolt.mvn-http`'s OpenSSL bindings, which is why sign-in is desktop-only |
| 64 | today. `dart:io` has TLS in the runtime; this is the single biggest thing |
| 65 | the port buys. |
| 66 | 4. **`frq.state`** (1,930) — mostly portable logic, but its ratoms are |
| 67 | glimmer's. Needs the reactive layer decided first. |
| 68 | 5. **`frq.app`** (1,834) — not a port. Flutter brings its own reconciler, so |
| 69 | the screens are rewritten against `cljd.flutter`. |
| 70 | |
| 71 | Not coming: `frq.tui` (no terminal Flutter), `frq.cosmic` (libcosmic is |
| 72 | desktop-only), and the media plane — `moq/`, `codec/`, `capture/`, `av/`, about |
| 73 | 3,800 lines of FFI against C libraries that do not exist on Android either way. |
| 74 | `dart:ffi` does not conjure V4L2; that half wants Flutter's camera and audio |
| 75 | plugins and is its own project. |
| 76 | |
| Build the APK, out of ClojureDart and Flutter e2b0e6b nandi 7d ago | 77 | ## Building it |
| 78 | |
| 79 | ```bash |
| 80 | just apk # the debug APK |
| 81 | just apk install # and onto a connected device |
| 82 | just apk run # and launched |
| 83 | just apk log # logcat |
| 84 | ``` |
| 85 | |
| 86 | Impure on purpose. Gradle resolves its own dependencies over the network and |
| 87 | installs build-tools and a platform into `ANDROID_HOME` as it goes, so it can |
| 88 | neither run in a sandbox nor write to the store. What nix gives is the |
| 89 | toolchain — clojure, a JDK, Flutter, and an SDK composed by androidenv — and |
| 90 | the recipe copies that SDK to `flutter/.home` for Gradle to finish off. That |
| 91 | copy and everything Gradle leaves behind are gitignored. |
| 92 | |
| 93 | Two things the Flutter template wanted that are deliberately not here. There is |
| 94 | no `ndkVersion` in `android/app/build.gradle.kts`: setting it makes Gradle |
| 95 | fetch that exact NDK, and there is no native code to need one — the app is |
| 96 | Dart, and path_provider is platform channels rather than JNI. And `ios/`, |
| 97 | `macos/`, `windows/`, `web/` are deleted; `android/` and `linux/` are the |
| 98 | targets. |
| 99 | |
| 100 | It is signed with `~/.android/debug.keystore`, through the template's |
| 101 | `signingConfig = signingConfigs.getByName("debug")` — which release builds also |
| 102 | use, so `flutter build apk --release` is not shippable until a real |
| 103 | `signingConfigs.release` is wired up. The jolt APK's key was generated inside |
| 104 | its own nix derivation and never written anywhere, which is why the first |
| 105 | install over it needed an uninstall: Android will not update a package across a |
| 106 | signature change. |
| 107 | |
| Paint glimmer's hiccup with Flutter, rather than porting the screens bc877e5 nandi 7d ago | 108 | ## The screens are not rewritten |
| 109 | |
| 110 | `frq.hiccup` is a glimmer backend, the same way glimmer-cosmic and glimmer-tui |
| 111 | are. It walks the hiccup `frq.app` already produces and emits Flutter widgets, |
| 112 | so the screens are shared rather than forked. |
| 113 | |
| 114 | This is worth being precise about, because the first read of the port said |
| 115 | otherwise. Measured against the source: |
| 116 | |
| 117 | * `frq.state` is 1,930 lines and makes **zero** glimmer calls. Its whole |
| 118 | dependency on glimmer is `:refer [atom]` — it shadows core's `atom` with a |
| 119 | ratom, and everything after that is `swap!`, `reset!` and `deref`. |
| 120 | * `frq.app` is 1,834 lines and makes **one**: `r/reaction`. The rest is data — |
| 121 | `[:vbox {:spacing 6} ...]` over about twenty tags, naming no toolkit. |
| 122 | |
| 123 | So what a Flutter port needs is an interpreter for that data, not a rewrite of |
| 124 | it. What genuinely has to be ported is the other end: `frq.irc`, `frq.atproto`, |
| 125 | `frq.oauth`, `frq.avatars`, `frq.media`, `frq.profile`, `frq.platform` — the |
| 126 | namespaces that touch the host. Which is what `frq.io` is for, and where |
| 127 | `dart:io` pays for the whole exercise. |
| 128 | |
| 129 | What `frq.hiccup` does not do is glimmer's reconciliation: Flutter rebuilds |
| 130 | from the top and diffs its own element tree, so a cell firing rebuilds the |
| 131 | screen rather than the subtree that read it. Fine at this size. |
| 132 | |
| Draw frq.app's own connect screen on the phone 0bc64b5 nandi 7d ago | 133 | `frq.main` paints `frq.app`'s own connect screen, out of |
| 134 | `common/frq/screens/connect.cljc` — the same file the desktop renders. What it |
| 135 | reads is `frq.cells` and what it calls is `frq.actions`, and each platform |
| 136 | fills those in: `frq.state`'s reducers on the desktop, dart:io here. |
| Paint glimmer's hiccup with Flutter, rather than porting the screens bc877e5 nandi 7d ago | 137 | |
| Share the root, and with it the last of the screens 433c3c8 nandi 7d ago | 138 | ## Every screen shared, and the root that picks between them |
| Draw the conversation on the phone c0121fe nandi 7d ago | 139 | |
| Share the root, and with it the last of the screens 433c3c8 nandi 7d ago | 140 | All of them are in `common/frq/screens/` now — `connect`, `chats`, `chat`, |
| 141 | `settings` (with Discover and the tab frame) and `app`, which carries the |
| 142 | split view, the three dialogs and the decision about which screen is showing. |
| 143 | The phone renders `[screens/app]` and nothing else; it was switching by hand |
| 144 | until that moved. With the cells under them in `frq.cells`, with the cells under them in `frq.cells`, the derivations in |
| Draw the conversation on the phone c0121fe nandi 7d ago | 145 | `frq.rooms`, the backend metrics in `frq.metrics` and everything a screen |
| Share the root, and with it the last of the screens 433c3c8 nandi 7d ago | 146 | cannot do itself behind `frq.actions`. `frq.app` is 226 lines and was 1,744. What is left in it is the part that |
| 147 | cannot move: `derived` and the two asset lookups, which are a glimmer reaction |
| 148 | over a fetch-and-cache, the metrics aliases `frq.tui` writes, and `start!`. |
| Draw the conversation on the phone c0121fe nandi 7d ago | 149 | |
| 150 | What `Length::Fill` means took four goes to get right, and the rule it ended |
| 151 | at is worth stating once: a child that fills is Flutter's `Expanded`, the |
| 152 | question is recursive — a plain `:vbox` holding a `:scroll` fills too — a Row |
| 153 | holding a filling column must `stretch` and be given a height, and a pane that |
| 154 | fills a column takes the row's width as well, or it is as wide as its longest |
| 155 | line. Prose in a row is `Flexible` rather than `Expanded`, because Expanded |
| 156 | hands out equal shares and a button label then wraps down the middle of a |
| 157 | word. |
| 158 | |
| 159 | And `:width-request 0` means no request. Every number is truthy in Clojure, so |
| 160 | taking it at face value gave the message list a `SizedBox` of zero width and |
| 161 | an empty screen. |
| 162 | |
| 163 | ## The older note, kept because the lesson is general |
| Share the chats screen, and the four things under it 1f55e68 nandi 7d ago | 164 | |
| 165 | `frq.screens.connect` and `frq.screens.chats` are in `common/` now, with the |
| 166 | cells under them in `frq.cells`, the derivations in `frq.rooms`, the backend |
| 167 | metrics in `frq.metrics` and the things a screen cannot do itself behind |
| 168 | `frq.actions`. `frq.app` requires both and the desktop draws them — verified in |
| 169 | the TUI, including the conversation list with its rooms and previews. |
| 170 | |
| Take what is left: fill-height, and the chats screen on the phone ff774d1 nandi 7d ago | 171 | The phone draws both. |
| 172 | |
| 173 | `Length::Fill` is the whole of what the renderer was missing, in two |
| 174 | directions. `:fill-height` down a column and a width-less `:entry` across a |
| 175 | row are the same instruction — *take what is left* — and that is Flutter's |
| 176 | `Expanded`, not a bigger `mainAxisSize`. A band that says only `max` is handed |
| 177 | loose constraints by its parent, asks for infinity, and takes the screen with |
| 178 | it. |
| 179 | |
| 180 | So `flexed` wraps whichever children fill, with `fills-column?` for a column |
| 181 | and `fills-row?` for a row, and a Row holding one is `max` so it has width to |
| 182 | divide. A `:page` scrolls itself and a `:vbox :fill-height` takes the bounded |
| 183 | height the Scaffold gives it — which is why nothing wraps the screen any more: |
| 184 | a scroll view around the tree is exactly what takes that bound away. |
| 185 | |
| 186 | What made this expensive was looking for it as an exception. A layout error |
| 187 | happens after the build: no `try` sees it, `(catch Object ...)` sees it, the |
| 188 | red error box does not appear, and the log stays empty. `FlutterError.onError` |
| 189 | is where they go, and installing that handler in `frq.main` should have been |
| 190 | the first move rather than the tenth. |
| Share the chats screen, and the four things under it 1f55e68 nandi 7d ago | 191 | |
| Paint glimmer's hiccup with Flutter, rather than porting the screens bc877e5 nandi 7d ago | 192 | ## The order to do the rest in |
| 193 | |
| Reach irc.freeq.at over TLS from the phone e80514e nandi 7d ago | 194 | 1. ~~**`frq.irc`**~~ — started. The parser is `common/frq/irc/parse.cljc` now, |
| 195 | shared, with `frq.irc` re-exporting it so the twenty-three `irc/tag-value` |
| 196 | and `irc/nick-of` call sites in `frq.state` and `frq.av` did not move. The |
| 197 | transport is `frq.net.dart`: `SecureSocket`, a `Stream`, no thread and no |
| 198 | outbox. **TLS reaches irc.freeq.at:6697 from the phone** — registration and |
| 199 | MOTD, which is the thing the jolt APK could never do. What is left of this |
| 200 | one is the protocol half: CAP, SASL and the idle-ping logic still live in |
| 201 | `src/frq/irc.clj` and want `frq.msgsig` and `frq.atproto` under them first. |
| Resolve an identity from the phone, over the shared AT Protocol core f735240 nandi 7d ago | 202 | 2. ~~**`frq.atproto`**~~ — done. `common/frq/atproto/core.cljc` is the JSON, |
| 203 | the base64url, the SASL payloads, and a `-req`/`-parse` pair per step of the |
| 204 | flow; `frq.atproto` and `frq.atproto.dart` supply the middle. **handle → DID |
| 205 | → PDS resolves on the phone**, over `HttpClient`. |
| 206 | |
| 207 | **`frq.oauth`** — half done. `common/frq/oauth/core.cljc` has the URL, the |
| 208 | handoff payload and the session refresh. What has no Android answer yet is |
| 209 | the capture: the desktop binds a loopback socket and serves a page the |
| 210 | browser redirects to, and an Android app cannot listen on localhost for a |
| 211 | browser it does not own. That wants an app link or a custom scheme, an |
| 212 | intent filter, and a redirect URI the broker will accept — a decision about |
| 213 | freeq's broker, not a porting problem. |
| Sign on the phone: msgsig shared, crypto seamed d8fadee nandi 7d ago | 214 | 3. ~~**`frq.msgsig`**~~ — done. The signing is shared; the four primitives |
| 215 | under it are `frq.crypto`, which the desktop answers with the same OpenSSL |
| 216 | it loads for TLS and the phone with `package:ed25519_edwards` and |
| 217 | `package:crypto`, both pure Dart and both synchronous — a signature is |
| 218 | minted in the middle of sending a reaction and there is nothing to await |
| 219 | on. Verified on both against RFC 8032 test 1: same public key, same |
| 220 | signature, byte for byte. |
| 221 | |
| 222 | **`frq.wire`** (81) still wants the seam extended. |
| Paint glimmer's hiccup with Flutter, rather than porting the screens bc877e5 nandi 7d ago | 223 | 4. **`frq.avatars`**, **`frq.media`**, **`frq.profile`**, **`frq.platform`** — |
| 224 | small, and mostly fetch-and-cache. |
| 225 | 5. **`frq.state`** moves to `common/` as `.cljc`, with `atom` resolved per |
| 226 | platform by reader conditional. |
| 227 | 6. **`frq.app`** follows it, and the tags it uses that `frq.hiccup` does not |
| 228 | cover yet paint as an orange `?tag` until they do. |
| Draw frq.app's own connect screen on the phone 0bc64b5 nandi 7d ago | 229 | |
| 230 | ## What a missing tag property looks like |
| 231 | |
| 232 | Worth writing down, because it cost an evening. `frq.hiccup` ignored |
| 233 | `:width-request`, and the connect screen puts two entries side by side in an |
| 234 | `:hbox` with one. A TextField takes its width from its parent and a Row offers |
| 235 | unbounded width, so that is a hard layout error — and a layout error happens |
| 236 | after the build, so it is not an exception anything can catch, paints nothing |
| 237 | at all rather than Flutter's red box, and takes every sibling in the same |
| 238 | `children` vector down with it. The screen was blank and the log was empty. |
| 239 | |
| 240 | The way through was a harness that renders each candidate in turn with a |
| 241 | labelled marker between them, so the last label standing says where it died. |
| 242 | Not guesswork: four wrong theories went past before that — `Center` in an |
| 243 | unbounded height, `fn*` as a binding name, qualified symbols in `:watch`, a |
| 244 | `Builder` boundary — each one a three-minute deploy. |
| 245 | |
| 246 | It also found that two `:entry` nodes with no `:key` shared one |
| 247 | TextEditingController, so the host field showed the port. glimmer matches |
| 248 | children by position when there is no key; a backend holding a controller per |
| 249 | field needs a name for it. |