0.0.002

ddat interop with dat js
cable interop with cabal js
ddat's frontend = dat-thang
cable fe = cable-thang
dillo support based on cel's dillo-dat
bootstrap node
xplatform support

Signed-off-by: divo <418@cryspace.space>

docs/ddat-gui.md

@@ -0,0 +1,126 @@
+# `dat-thang` v0.0.002
+
+This release is a prototype in pre-alpha.
+
+Build with `make ENABLE_SDL2=1` (requires SDL2 and SDL2_ttf development files); the Dat GUI is `build/linux/dat-thang` and the
+separate Cable room chat client is `build/linux/cable-thang`. `make
+ENABLE_SDL2=1 install` installs both clients and their manuals. Run
+`build/linux/dat-thang --archive DIRECTORY --site HOSTNAME` to begin in a local
+directory. The initial directory defaults to `.`.
+
+The GNU/Linux default build path is `build/linux`; the native Windows target
+uses `build/windows`. Set `BUILD=...` only when you intentionally need another
+isolated build tree.
+
+Both interfaces are painted with SDL2 and intentionally resemble terminal
+clients: fixed-width labels, high-contrast panes, keyboard shortcuts, and
+terminal-style status text. They do not use Notcurses. For the existing
+JavaScript Cabal terminal client, run `cabal-cli <room-address>`; `cable` is
+only the C address and identity utility.
+
+Both clients load the bundled `assets/fonts/MorePerfectDOSVGA.ttf`, verify its
+family name is `More Perfect DOS VGA`, and render hard edged glyphs at 14 px
+with SDL2_ttf. Installed clients load that same font from
+`$(PREFIX)/share/datgpt/fonts/`; there is no alternate font setting.
+
+The dat-thang speaker graphic is the original 84 by 84 pixel crop from the
+provided mockup, stored as `assets/datthang-speaker.bmp`. Green pixels from the
+mockup background are transparent in the GUI. Installed clients load it from
+`$(PREFIX)/share/datgpt/icons/`.
+
+The top-left OFF/ON switch controls the client network. OFF leaves every joined
+topic, unannounces when possible, closes the Cesspool socket, and clears peer
+state. ON connects and announces only archives already loaded in the archive
+list; navigating the filesystem never creates or loads an archive. The status
+indicator turns green after a Cesspool response or connected peer. F9 loads an
+existing archive or imports the entered remote link. `--offline` starts with
+network discovery disabled.
+
+Run `build/linux/cesspool-bootstrap --port 3282 --advertise HOST:3282` on the
+rendezvous host. It prints the endpoint you supplied and a Windows firewall
+rule; it does not query an outside IP lookup service. Forward UDP 3282 through
+the edge router or cloud firewall. In each GUI, open Escape > Settings
+> Cesspool Node and enter that reachable `host:port`; saving it restarts
+discovery. Terminal users can use `dat bootstrap set host:port` or `cable
+bootstrap set host:port`. `CESSPOOL_BOOTSTRAP` and `DDAT_BOOTSTRAP` accept comma- or
+semicolon-separated endpoints. `DDAT_PORT` selects each client's local UDP
+port. With no explicit `DDAT_PORT`, dat-thang listens on UDP 3282 and
+cable-thang on UDP 3000 so same-LAN discovery can reach both clients on their
+stable ports. If the preferred port is busy, a client chooses another known
+Cesspool port; set `DDAT_PORT` to pin a specific local port. The node keeps short-lived peer announcements and returns endpoints
+announcing the same topic. This is Cesspool rendezvous for the C clients, not
+the historical JavaScript Dat/Bittorrent DHT.
+
+The pane to the right of the Merkle graph is a local filesystem browser. Click
+a directory to navigate into and select it as the local directory. Click a file
+to select its name. The bottom bar reports that filename and selected local
+directory. `CREATE NEW DAT` opens or creates that directory's archive and begins
+discovery when online. With no remote address entered, `IMPORT DAT` opens and
+syncs the archive already present in the selected directory. To share an archive,
+copy its address with the `COPY` control beside the local ARCHIVE field.
+Double-click a peer in the buddy list to open private chat, paste the address
+with Ctrl+V, and press Enter to send it. The recipient clicks the received
+`dat://` message to copy its address, selects an empty destination directory,
+clicks the right-hand ARCHIVE field, presses Ctrl+V, then Enter. Enter starts the remote import; an incoming
+archive row appears in the transfer table as peer discovery and metadata download
+begin. The mirrored SITE, ARCHIVE, and VERSION fields show its hostname, key,
+path, and selected version. Received metadata and content blocks are
+proof-verified and cached under that directory's `.dat` folder. The client
+learns the content-feed key from the authenticated, verified metadata header.
+The status beside the remote fields reports address, discovery, and feed state.
+Escape opens the vertical Settings, Return, Exit menu. Settings persists the
+default address format, sonar audio, and online-at-startup preferences; use
+Up/Down and Enter or click a row.
+The table columns can be resized by dragging their header dividers;
+the wheel scrolls horizontally over the transfer table. Its bottom track shows
+the current horizontal position. The ARCHIVES control above the filesystem pane
+switches among remembered shared directories; the list persists in
+`$HOME/.dat/dat-thang-shares`. Right-click a transfer for pause/resume, cancel,
+reveal destination, or copy address. Right-click elsewhere for load/share,
+create, and copy-address actions.
+For each locally shared archive, the table's TITLE and DESCRIPTION come from
+the archive root's `dat.scm` S-expression, for example
+`((title "dat-thang") (description "dat:// implemented over c & scheme"))`.
+The client reads this file as Scheme data; missing fields fall back to the
+directory name and archive address.
+
+The client passes discovered Cesspool peers to the archive session, opens uTP,
+authenticates each connection with a signed nonce exchange bound to the peer
+key, then passes session frames through the feed handshake and replication
+code. The peer pane distinguishes discovered announcements from authenticated
+connections. The lower table lists authenticated archive sessions and their
+replication state. Upload/download readouts count session frames, and the top
+diamonds pulse on payload activity. The center hexagon is red offline, amber
+online without a connected peer, and green when connected. Awkward Moments,
+Share Guy, and Rank remain planned placeholders. Received blocks are verified
+against their SLEEP proofs and stored in per-feed `.remote` caches, then
+reloaded when the next session starts.
+
+The original dolphin-in-a-porthole and radar/speaker art from the mockup are
+embedded in the client. The dolphin sits at the upper right and sends a
+one-second arpeggiated chiptune sonar cue to authenticated connected peers. The
+speaker sits at the lower right of the YOU panel and plays a two-second low
+square-wave cue; while online on an archive topic, it refreshes discovery and
+sends the cue to discovered peers as their authenticated sessions come up. A
+receiving peer plays the speaker cue and returns one dolphin chirp; the sender
+plays that echo and marks the peer found. The waveform panel plots samples
+captured from SDL's audio output ring, so it shows the actual waveform being
+played. Cues travel as a small Dat-thang UI record over the authenticated
+Cesspool/uTP connection and never enter archive feeds.
+
+F1 opens the client manual from the source tree or installed manpage. Up/Down
+and the mouse wheel scroll it; Escape closes it. Escape toggles the menu when
+the manual is closed. The source can be selected with `DAT_THANG_MANPAGE`.
+
+The site field shows the explicit hostname supplied at launch or a local
+`dat dns set` alias associated with the selected archive. Beaker's legacy
+`dat:` handler resolves hostnames to keys before opening an archive, and its
+`dat-dns` supports DNS-over-HTTPS TXT and `/.well-known/dat`; the bundled
+Dillo plugin disables the first option and uses HTTPS `/.well-known/dat`.
+The C resolver follows that Dillo behavior after checking local aliases; it
+does not call the operating system DNS TXT resolver. The archive field defaults
+to the historical 64-digit hexadecimal address; its format control switches to
+compact Base32768, and COPY produces the selected format.
+The build date uses the Discordian `ddate` calendar.
+The Merkle panel is a shape preview driven by metadata entry count, not hashes
+or proofs.