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.