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/dillo.md

@@ -0,0 +1,201 @@
+# Dillo integration
+
+Use the Dillo source maintained at <https://git.dillo-browser.org/dillo>.
+The project also lists <https://codeberg.org/dillo/dillo> as an up-to-date
+mirror; that mirror was used for the Linux run documented below.
+The latest published release is 3.2.0; the current source tree identifies its
+development version as 3.3.0. The old `dillo.org` host is not controlled by the
+Dillo developers.
+
+`make` builds `$(BUILD)/dat.dpi` (normally `build/linux/dat.dpi`), a native C Dillo
+Plugin Interface (DPI) helper.
+It uses Dillo's external DPIP protocol and does not link against Dillo internals
+or depend on a particular browser ABI. The helper authenticates each accepted
+DPIP connection with the `~/.dillo/dpid_comm_keys` value and handles `open_url`
+and `DpiBye`. It follows the historical plugin lifecycle: `dpid` passes its
+listening socket on stdin, the helper accepts a request connection, and closes
+that connection after the response body. DPIP responses do not use HTTP status
+lines or `Content-Length`; closing the request socket marks the end of the
+page. Current Dillo
+continues to load `.dpi` plugins and associate them with protocols in
+`~/.dillo/dpidrc`.
+
+Build and install the DPI with the same prefix used by Dillo. For the usual
+`/usr/local` installation:
+
+```sh
+make
+sudo make install
+```
+
+If Dillo uses a different plugin directory, set `PREFIX` and `DPIDIR` on both
+commands. The default plugin path is `/usr/local/lib/dillo/dpi/dat/dat.dpi`.
+The per-user `~/.dillo/dpidrc` must contain both the DPI root and this mapping
+(Dillo does not merge `dpi_dir` from the system config into the per-user file):
+
+```ini
+dpi_dir=/usr/local/lib/dillo/dpi
+proto.dat=dat/dat.dpi
+```
+
+Then restart Dillo (which restarts `dpid`). The plugin first checks Dillo's
+local archive cache. On a cache miss it can join the archive's Cesspool topic,
+authenticate a peer session, fetch the metadata and content feeds, and then
+serve the requested path. Both Dillo's DPI and the seeding Dat-thang client
+must use the same Cesspool bootstrap node. Configure that endpoint for the
+environment that launches each program:
+
+```sh
+build/linux/dat bootstrap set 127.0.0.1:3282
+```
+
+The command stores the node in `~/.config/dat-gpt/bootstrap`. For a public
+test, use the reachable `HOST:PORT` of the Cesspool node instead of the local
+loopback address. The Cygwin Dillo and native Windows Dat-thang configurations
+are separate when their `HOME` directories differ, so configure each using its
+own `dat` executable/environment. The helper does not use Hyperswarm or
+Hypercore; its remote feed transfer uses this project's Cesspool and SLEEP
+session protocol.
+
+Use the full key shown by Dat-thang, then enter `dat://<key>/` in Dillo. The
+helper caches fetched data at `~/.dillo/dat/archives/XX/<remaining-key>` and
+serves historical versions, `index.html`, `.html` fallback, explicit `//`
+directory listings, parent-directory navigation, stat queries, and the MIME
+rules used by the old `dillo-dat` plugin. Directory listings retain its
+up/directory/file icons and sort directories first, then names in descending
+order. The internal `dpi:/dat/` page lists archives opened by this DPI process,
+shows title, description, and version from `dat.scm` (read as an S-expression
+without evaluating archive contents), falls back to `CNAME`, and provides the
+unswarm/reload and quit controls. Status messages identify name resolution,
+archive retrieval, and file serving. If a fetch cannot complete, it returns a
+text error page that distinguishes an unconfigured or unreachable node, no
+peer announcing the archive key, and a peer transfer timeout.
+
+Version pins use the metadata-entry count shown by `dat status`:
+`dat://<key>+2/` reads the snapshot at version 2, while `dat://<key>/` follows
+the latest version. Root navigation looks for `index.html`. `make test` checks
+the archive behaviors and starts the helper with a real TCP listening socket,
+then verifies response bytes and EOF framing over an accepted connection.
+
+## Linux bootstrap, Dat-thang, and Dillo smoke run
+
+Run these steps from the repository root after installing the build
+dependencies in `INSTALL`. GNU/Linux objects and executables default to
+`build/linux`, separate from the Windows build in `build/windows`. The bundled `site/`
+archive already has an address and three recorded versions; this flow leaves it
+unchanged.
+
+Build and install the GUI plus the C Dillo helper:
+
+```sh
+./configure
+make ENABLE_SDL2=1
+sudo make ENABLE_SDL2=1 install
+```
+
+Merge these entries into `~/.dillo/dpidrc`, preserving any other DPI entries,
+then restart Dillo so `dpid` reloads the mapping:
+
+```ini
+dpi_dir=/usr/local/lib/dillo/dpi
+proto.dat=dat/dat.dpi
+```
+
+Use three terminals. Terminal 1 runs a local discovery node for this same-host
+smoke run. Start it before either client so it receives the initial announce:
+
+```sh
+build/linux/cesspool-bootstrap --bind 127.0.0.1 --port 3282 \
+  --state-dir "$HOME/.local/state/dat-gpt/cesspool-bootstrap" \
+  --advertise 127.0.0.1:3282
+```
+
+Terminal 2 configures the client and starts the SDL client with the bundled
+archive explicitly loaded. Leave its window open and online:
+
+```sh
+build/linux/dat bootstrap set 127.0.0.1:3282
+DDAT_BOOTSTRAP=127.0.0.1:3282 DDAT_PORT=3000 \
+  build/linux/dat-thang --archive "$PWD/site"
+```
+
+Terminal 3 starts Dillo with an empty per-run cache, so the page must arrive
+from the archive being announced by Dat-thang. The temporary home gives Dillo
+its own fresh cache and DPID keys without disturbing the normal profile:
+keep this shell open for the two `dilloc` version checks below.
+
+```sh
+dillo_home=$(mktemp -d)
+mkdir -p "$dillo_home/.dillo"
+cat > "$dillo_home/.dillo/dpidrc" <<'EOF'
+dpi_dir=/usr/local/lib/dillo/dpi
+proto.dat=dat/dat.dpi
+EOF
+archive=$(build/linux/dat url / "$PWD/site")
+HOME="$dillo_home" DDAT_BOOTSTRAP=127.0.0.1:3282 dillo "$archive/" &
+sleep 5
+HOME="$dillo_home" dilloc title
+HOME="$dillo_home" dilloc dump | grep -F 'The site is online'
+```
+
+The latest `site/` snapshot is version 3 and displays “Site is online.” Open
+the version-1 pin in the existing Dillo window to verify historical navigation;
+it predates `dat.scm` and `index.html` and shows the earlier archive listing:
+
+```sh
+historical=$(build/linux/dat url 1 / "$PWD/site")
+HOME="$dillo_home" dilloc open "$historical/"
+sleep 2
+HOME="$dillo_home" dilloc url
+HOME="$dillo_home" dilloc dump | grep -F 'dat-logo.png'
+```
+
+Return to the setup page at version 3:
+
+```sh
+latest=$(build/linux/dat url 3 / "$PWD/site")
+HOME="$dillo_home" dilloc open "$latest/"
+sleep 2
+HOME="$dillo_home" dilloc url
+HOME="$dillo_home" dilloc title
+HOME="$dillo_home" dilloc dump | grep -F 'The site is online'
+```
+
+For another archive, replace `site` with its loaded local archive directory,
+and choose a version from `build/linux/dat log DIRECTORY`. The same Cesspool node
+must be reachable by both the Dat-thang GUI and Dillo helper. The bootstrap
+process reports announced peer and topic counts. A successful run shows the
+GUI online, a cold Dillo cache populated with `.dat/metadata.remote` and
+`.dat/content.remote`, and the Dillo title `Site is online`. With this archive,
+Dillo loads both `+1` (historical listing) and `+3` (the current setup page).
+
+## Windows with Cygwin Dillo
+
+Build the helper from the repository root in Cygwin Bash. The DPI uses the
+normal Cygwin `gcc`, `make`, `libcurl-devel`, and `libsodium-devel` packages.
+The helper links the bundled S7 reader so `dat.scm` metadata is parsed using the
+project's Scheme representation; it never evaluates archive-supplied forms.
+
+```sh
+make build/linux/dat.dpi
+install -d /usr/local/lib/dillo/dpi/dat
+install -m 755 build/linux/dat.dpi /usr/local/lib/dillo/dpi/dat/dat.dpi.exe
+```
+
+Put both entries in `~/.dillo/dpidrc` (for this installation that is
+`C:\cygwin64\home\Home\.dillo\dpidrc`):
+
+```ini
+dpi_dir=/usr/local/lib/dillo/dpi
+proto.dat=dat/dat.dpi.exe
+```
+
+Restart Dillo so `dpid` reads the configuration. The `site/` folder in this
+repository is the archive source; Dillo's cache is separate at
+`~/.dillo/dat/archives/XX/<remaining-key>`. A seeded archive is browseable only
+after its feed data is present in that cache or a live Cesspool fetch completes.
+The setup page source is `site/index.html`. `tests/test_dpi.sh` checks the
+historical and latest snapshots, S-expression metadata, listing, stat, and
+dashboard output. The Windows end-to-end flow, including `+N` navigation across
+multiple archives, has been confirmed by the user. The Linux cold-cache flow
+above was also run against current Dillo source and the Cesspool bootstrap.