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