dat-thang/docs/ddat-gui.md

# `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.