fix(amuleapi): align web frontend with backend, fix doc drift

The static web frontend and the docs/api reference had both drifted from
the JSON the amuleapi backend actually emits. Verified each field against
src/webapi/Api.cpp and src/webapi/EventDiff.cpp.

Frontend (src/webapi/static):
- downloads.js: register the clients resource under id "client_ecid"
  (was "ecid"). The backend keys clients by client_ecid, so the old id
  collapsed the whole uploads/clients list to a single "undefined" row.
- events.js: buffer-then-replay on seed() so a delta (especially a
  *_removed) arriving while a snapshot fetch is in flight is no longer
  clobbered by the snapshot replacing the collection, per EVENTS.md.
- events.js + search.js: wire the SSE search channel
  (search_result_added / search_finished), reconciling live upserts with
  the existing poll by hash; poll stays as the full-set reconciler and
  fallback when the stream isn't live.

Docs (docs/api), corrected to match the backend:
- REFERENCE.md: /status now shows kad.network; /clients and /servers
  examples completed; /kad lists firewalled_udp, ip, indexed, buddy;
  /logs/amule returns {lines,...} not {log}; /logs/serverinfo returns a
  text string (not a lines array); /stats/tree is {nodes:[{label,
  children}]} not {tree}; /stats/graphs points are objects
  {t,t_unix,value} with a full envelope; /search/results items use
  sources{total,complete}+already_have+rating and progress gains active.
- EVENTS.md: log_appended payload is {lines} (no buffer; amule log only);
  search_result_added carries no ecid and flattens sources to an int.

Author: ngosang

docs/api/EVENTS.md

@@ -214,7 +214,7 @@ Both `since_id` and `newest_id` are uint64. The client never has to compute them
 
 ## Event catalog
 
-Every event the bus publishes. The `_added` and `_updated` payloads are BYTE-FOR-BYTE identical to the matching REST resource's list-item shape — clients receiving a `*_updated` event get the full new state and never need to re-GET. `_removed` carries only the identity field — `hash` for files (`download_removed`, `shared_removed`), `client_ecid` for `client_removed`, `ecid` for `server_removed` — so the client can drop the cache entry without needing the old object. Two events don't fit the collection-delta model: `status_changed` ships a full status envelope (replace, not merge) and `log_appended` is an append operation (`{buffer, lines}` — push the lines onto the named buffer, don't replace). Branch on the event type in your dispatcher accordingly.
+Every event the bus publishes. The `_added` and `_updated` payloads are BYTE-FOR-BYTE identical to the matching REST resource's list-item shape — clients receiving a `*_updated` event get the full new state and never need to re-GET. `_removed` carries only the identity field — `hash` for files (`download_removed`, `shared_removed`), `client_ecid` for `client_removed`, `ecid` for `server_removed` — so the client can drop the cache entry without needing the old object. Two events don't fit the collection-delta model: `status_changed` ships a full status envelope (replace, not merge) and `log_appended` is an append operation (`{lines}` — push the lines onto the amule log buffer, don't replace). Branch on the event type in your dispatcher accordingly.
 
 ### `downloads` channel
 
@@ -384,25 +384,24 @@ Subscribe to this channel alone for a thin "header bar" client that just wants c
 
 #### `log_appended`
 
-Emitted when amuled or the serverinfo buffer appends new lines.
+Emitted when the amuled log buffer appends new lines.
 
 ```json
-{ "buffer": "amule", "lines": ["2026-06-19 11:00:00: line one", "2026-06-19 11:00:01: line two"] }
+{ "lines": ["2026-06-19 11:00:00: line one", "2026-06-19 11:00:01: line two"] }
 ```
 
-`buffer` is `"amule"` or `"serverinfo"`. Multiple lines may be batched into a single event when the underlying buffer landed several lines between refresher ticks. The [Bootstrap example](#bootstrap-snapshot--stream) doesn't pull `/logs/amule` or `/logs/serverinfo` — fetch them in step 2 if your UI shows historical log lines, otherwise treat `log_appended` as a live-only feed.
+Only the amuled log has a live channel; the serverinfo buffer has no SSE feed and is fetched by polling [`GET /logs/serverinfo`](REFERENCE.md#get-apiv0logsserverinfo--delete-apiv0logsserverinfo). Multiple lines may be batched into a single event when the buffer landed several lines between refresher ticks. The [Bootstrap example](#bootstrap-snapshot--stream) doesn't pull `/logs/amule` — fetch it in step 2 if your UI shows historical log lines, otherwise treat `log_appended` as a live-only feed.
 
 ### `search` channel
 
 Driven by the refresher state machine that owns the `POST /search` → completion lifecycle (see [REFERENCE.md](REFERENCE.md#search-results)). Events only fire while a search is active; the channel is silent at idle. The [Bootstrap example](#bootstrap-snapshot--stream) omits `/search/results` because searches are normally client-initiated post-boot; if your UI persists a "search-in-progress" state across reloads, fetch `/search/results` and `/search/progress` in step 2 too.
 
 #### `search_result_added`
 
-Emitted per new ECID that appears in the results map between refresher ticks.
+Emitted per new result that appears in the results map between refresher ticks.
 
 ```json
 {
-  "ecid": 42,
   "hash": "0123456789abcdef0123456789abcdef",
   "name": "ubuntu-24.04-desktop-amd64.iso",
   "size": 5765873664,
@@ -413,7 +412,7 @@ Emitted per new ECID that appears in the results map between refresher ticks.
 }
 ```
 
-Payload mirrors a single `/search/results` array entry. ECIDs are amuled-allocated and unique per amuled session, but **not** stable across `POST /search` calls — amuled wipes its searchlist on every new query and re-allocates from the same pool, so subscribers must treat each search as a fresh result space.
+Key results by `hash`. The payload carries the same data as a `/search/results` array entry but in a flatter shape: the source counts arrive as a top-level `sources` (total) integer plus a sibling `complete_sources`, whereas the REST endpoint nests them as `sources: {total, complete}`. amuled wipes its searchlist on every new `POST /search`, so subscribers must treat each search as a fresh result space — clear prior results when you start a new query.
 
 #### `search_finished`
 

docs/api/REFERENCE.md

@@ -233,13 +233,16 @@ curl -s -H "Authorization: Bearer $TOKEN" http://$HOST/api/v0/status
   },
   "kad": {
     "state": "connected",
-    "firewalled": false
+    "firewalled": false,
+    "network": { "users": 5400000, "files": 1400000000, "nodes": 2400 }
   },
   "speeds": { "download_bps": 4500000, "upload_bps": 50000 },
   "queue": { "upload_queue_length": 12, "total_source_count": 1843 }
 }
 ```
 
+`kad.network` is the same `{users, files, nodes}` rollup [`GET /kad`](#get-apiv0kad) serves, surfaced here so `/status` is a one-call dashboard view.
+
 `ec_connected` is `false` while amuleapi can't reach the underlying amuled. Most other endpoints return `503 ec_unavailable` in that state.
 
 **Errors:** `503 ec_unavailable` if amuleapi hasn't received its first EC snapshot yet.
@@ -542,13 +545,22 @@ curl -s -H "Authorization: Bearer $TOKEN" \
       "ip": "203.0.113.42",
       "port": 4662,
       "software": "eMule",
+      "software_version": "0.50a",
+      "os_info": "Linux",
       "upload_state": "uploading",
       "download_state": "idle",
+      "ident_state": "verified",
+      "download_file_name": "",
       "upload_file_hash": "8b54a3c20fae9e4b9f7e0c2c8c01b6b1",
       "download_file_hash": "",
-      "download_file_name": "",
+      "xfer": { "up_session": 22000000, "down_session": 0, "up_total": 452000000, "down_total": 189000000 },
       "upload_speed_bps": 22000,
-      "download_speed_bps": 0
+      "download_speed_bps": 0,
+      "queue_waiting_position": 0,
+      "remote_queue_rank": 0,
+      "score": 150,
+      "obfuscation_status": "obfuscated",
+      "friend_slot": false
     }
   ]
 }
@@ -645,11 +657,16 @@ Changes the upload priority of a single shared file. `{hash}` is the 32-char MD4
     {
       "ecid": 1,
       "name": "eMule Server",
+      "description": "Public server",
+      "version": "17.15",
       "address": "203.0.113.5:4242",
       "port": 4242,
       "users": 312000,
+      "max_users": 500000,
       "files": 75000000,
       "priority": "normal",
+      "ping_ms": 42,
+      "failed": 0,
       "static": false
     }
   ]
@@ -884,13 +901,20 @@ curl -s -X POST -H "Authorization: Bearer $TOKEN" \
 
 **Auth:** `GUEST`
 
-Standalone view of the Kad subtree from `/status`.
+Standalone view of the Kad subtree from `/status`, plus the detail fields the
+status rollup omits (`firewalled_udp`, `in_lan_mode`, your external `ip`, the
+`indexed` Kad-store counters, and `buddy` contact info for low-ID peers).
 
 ```json
 {
   "state": "connected",
   "firewalled": false,
-  "network": { "users": 5400000, "files": 1.4e9, "nodes": 2400 }
+  "firewalled_udp": false,
+  "in_lan_mode": false,
+  "ip": "203.0.113.5",
+  "network": { "users": 5400000, "files": 1400000000, "nodes": 2400 },
+  "indexed": { "sources": 12000, "keywords": 8500, "notes": 0, "load": 14 },
+  "buddy": { "status": "connected", "ip": "203.0.113.9", "port": 4672 }
 }
 ```
 
@@ -907,9 +931,15 @@ amuled's general log buffer.
 **Query parameters:** `tail=N` — return only the last N lines (default: full buffer).
 
 ```json
-{ "log": ["2026-06-19 11:00:00: line one", "...line two"] }
+{
+  "lines": ["2026-06-19 11:00:00: line one", "...line two"],
+  "total_cached": 1024,
+  "returned": 2
+}
 ```
 
+`lines` is the array of log lines; `total_cached` is how many lines are held in the buffer and `returned` how many this response carried (≤ `tail`).
+
 #### `DELETE /api/v0/logs/amule`
 
 **Auth:** `ADMIN`
@@ -924,7 +954,20 @@ Clears the buffer.
 
 **Auth:** `GUEST` / `ADMIN`
 
-Same shape; the ed2k server-info log buffer instead of the general log.
+The ed2k server-info log buffer. Unlike `/logs/amule`, amuled ships this one as a
+single accumulated text blob (it rotates it server-side), so the GET returns a
+`text` **string** rather than a `lines` array. `?tail=N` here clamps the number
+of trailing **bytes**, not lines.
+
+```json
+{
+  "text": "Connecting to eMule Server (203.0.113.5:4242)\nConnection established\n",
+  "total_bytes": 4096,
+  "returned_bytes": 68
+}
+```
+
+`DELETE` clears the buffer and returns `{ "ok": true }`.
 
 ---
 
@@ -934,11 +977,25 @@ Same shape; the ed2k server-info log buffer instead of the general log.
 
 **Auth:** `GUEST`
 
-A nested object mirroring amuled's "Statistics" tree (transfers, connections, clients, servers, downloads). Cached with a 1 s TTL.
+A tree mirroring amuled's "Statistics" tree (transfers, connections, clients, servers, downloads). Cached with a 1 s TTL.
+
+The envelope is `{ "nodes": [...] }`. Each node is `{ "label": "<text>", "children": [...] }`; a leaf is a node whose `children` array is empty, with its value baked into the `label` string (e.g. `"Total uploaded: 12.4 GB"`).
 
 ```json
 {
-  "tree": { "Transfers": { "Uploads": { "Total uploaded": "12.4 GB", "..." : "..." } } }
+  "nodes": [
+    {
+      "label": "Transfers",
+      "children": [
+        {
+          "label": "Uploads",
+          "children": [
+            { "label": "Total uploaded: 12.4 GB", "children": [] }
+          ]
+        }
+      ]
+    }
+  ]
 }
 ```
 
@@ -952,11 +1009,22 @@ Time-series points behind the desktop Statistics graphs.
 
 `{graph}` is one of `download`, `upload`, `connections`, `kad`.
 
+**Query parameters:** `width=N` — clamp the response to the last `N` samples (default/`0` returns the full ~1800-sample window).
+
 ```json
-{ "points": [[1781430000, 4500000], [1781430010, 4800000]] }
+{
+  "graph": "download",
+  "unit": "bps",
+  "interval_seconds": 1,
+  "points": [
+    { "t": "2026-06-19T11:00:00Z", "t_unix": 1781430000, "value": 4500000 },
+    { "t": "2026-06-19T11:00:10Z", "t_unix": 1781430010, "value": 4800000 }
+  ],
+  "session": { "download_bytes": 12400000000, "upload_bytes": 980000000, "kad_bytes": 5400000 }
+}
 ```
 
-Each entry is `[unix_timestamp, value]`.
+Each point is an object with `t` (ISO8601 UTC), `t_unix` (unix seconds), and `value`. `unit` is `"bps"` for download/upload and `"count"` for connections/kad. `session` carries this-session byte totals so a client doesn't need a separate roundtrip.
 
 **Errors:** `404 not_found` (unknown graph name), `503 ec_unavailable`.
 
@@ -1002,21 +1070,25 @@ This endpoint does NOT busy-wait — it returns whatever amuled has in its resul
 {
   "results": [
     {
-      "hash":          "8b54a3c2...",
-      "name":          "example-distribution-26.04-amd64.iso",
-      "size":          3825205248,
-      "sources_count": 217,
-      "file_type":     "iso"
+      "hash":         "8b54a3c2...",
+      "name":         "example-distribution-26.04-amd64.iso",
+      "size":         3825205248,
+      "sources":      { "total": 217, "complete": 142 },
+      "already_have": false,
+      "rating":       0
     }
   ],
   "progress": {
     "percent":  67,
-    "complete": false
+    "complete": false,
+    "active":   true
   }
 }
 ```
 
-`progress.percent` is in the `[0, 100]` range. `progress.complete` is `true` whenever amuled reports the search has finished (matches the raw amuled sentinel values `100`, `0xfffe` Kad-done, and `0xffff` local-done — all surface here as `percent: 100, complete: true`).
+`sources.total` is the swarm size amuled reports for the result; `sources.complete` is how many of those hold the file complete. `already_have` is `true` when the hash is already in your downloads/shared. `rating` is the amuled-aggregated quality rating (`0` when unrated).
+
+`progress.percent` is in the `[0, 100]` range. `progress.complete` is `true` whenever amuled reports the search has finished (matches the raw amuled sentinel values `100`, `0xfffe` Kad-done, and `0xffff` local-done — all surface here as `percent: 100, complete: true`). `progress.active` is `true` while a `POST /search` is in flight (the refresher is polling amuled) and `false` once it stops or finishes — use it to tell "no search started" (`active: false`) apart from "search running, no hits yet" (`active: true`).
 
 `progress.percent: 0, progress.complete: false` can mean either "no search has been started" OR "Kad search just kicked off but hasn't reached any peers yet" — Kad search progress is not measurable mid-flight, only "started" and "finished". Clients that started the search themselves can treat the second tick onwards as "in progress".
 

src/webapi/static/js/events.js

@@ -16,6 +16,7 @@ const SSE_FAIL_THRESHOLD = 3;
 const resources = new Map();   // key -> spec
 const collections = new Map(); // key -> Map(id -> item)
 const active = new Set();       // keys currently seeded/streamed
+const seedBuffers = new Map();  // key -> array of deltas that arrived mid-seed
 
 let es = null;
 let sseFails = 0;
@@ -54,14 +55,26 @@ export const data = {
 async function seed(key) {
   const spec = resources.get(key);
   if (!spec) return;
+  // Buffer-then-replay (EVENTS.md §Bootstrap): start buffering deltas
+  // *before* awaiting the snapshot, so a delta (esp. a _removed) that lands
+  // during the fetch isn't clobbered by the snapshot replacing the map.
+  const buf = [];
+  seedBuffers.set(key, buf);
   try {
     const arr = (await spec.list()) || [];
     const m = new Map();
     for (const it of arr) m.set(String(it[spec.id]), it);
+    // Drain buffered deltas over the fresh snapshot, in arrival order.
+    for (const { op, payload } of buf) {
+      const idv = String(payload[spec.id]);
+      if (op === "del") m.delete(idv); else m.set(idv, payload);
+    }
     collections.set(key, m);
     publish(key);
   } catch (e) {
     console.error("seed " + key + " failed", e);
+  } finally {
+    seedBuffers.delete(key); // flip to direct-apply
   }
 }
 
@@ -102,6 +115,18 @@ function openSse() {
     try { store.set("log:appended", JSON.parse(ev.data)); } catch (_) {}
   });
 
+  // Search has its own channel (search_result_added / search_finished) but
+  // doesn't fit the added/updated/removed resource model (no _removed, the
+  // payload is keyed by hash and carries `sources` as a flat int), so it's
+  // surfaced via store keys the search view consumes directly. Inert unless
+  // a search is active.
+  es.addEventListener("search_result_added", (ev) => {
+    try { store.set("search:result", JSON.parse(ev.data)); } catch (_) {}
+  });
+  es.addEventListener("search_finished", (ev) => {
+    try { store.set("search:finished", JSON.parse(ev.data)); } catch (_) {}
+  });
+
   es.addEventListener("resync", () => {
     if (statusActive) refreshStatus();
     for (const k of active) seed(k);
@@ -122,6 +147,10 @@ function attachResourceListeners(spec) {
 function applyDelta(spec, op, ev) {
   let payload;
   try { payload = JSON.parse(ev.data); } catch (_) { return; }
+  // Still seeding this key — buffer instead of applying so seed() can drain
+  // these over the snapshot once it lands.
+  const buf = seedBuffers.get(spec.key);
+  if (buf) { buf.push({ op, payload }); return; }
   let m = collections.get(spec.key);
   if (!m) { m = new Map(); collections.set(spec.key, m); }
   const idv = String(payload[spec.id]);

src/webapi/static/js/views/downloads.js

@@ -35,7 +35,7 @@ export default function Downloads({ isGuest }) {
   useEffect(() => {
     data.register({ key: "downloads", eventPrefix: "download", id: "hash",
       list: () => api.get("downloads?include_completed=1").then((r) => r.downloads || []) });
-    data.register({ key: "clients", eventPrefix: "client", id: "ecid",
+    data.register({ key: "clients", eventPrefix: "client", id: "client_ecid",
       list: () => api.get("clients").then((r) => r.clients || []) });
     api.get("categories").then((r) => setCategories(r.categories || [])).catch(() => {});
     data.ensure("downloads");