/* Brain of Reese — RAG view (the knowledge base catalog; phase 76 * task 02: shell view module — formerly the standalone sources.html). * * Wires the real `GET /api/docs` endpoint (import phase): stat cards + * full-width document table, or the designed empty state when nothing * is indexed yet. Cells are built with DOM APIs (textContent) — never * innerHTML with document-derived data (XSS-safe by construction). * * Phase 76 (task 02) — shell view module (the "RAG" view of the * ONE-document shell; /sources.html now serves the shell, and * assets/router.js lazy-imports THIS module on first show): * * • the top-level boot is now `export async function mount(root)` — * root is the view's
, and every DOM lookup * scopes to root (the view ids stay unique across the shell — * scoped lookups keep the module honest and testable). The router * mounts a view ONCE (mount-once, hide-forever), so the bindings, * the sync state machine, and the in-flight poll survive every * switch. * • the initSharedHeader() call is DROPPED: in the shell the shared * header boots exactly once, via the chat module (app.js) at shell * boot — the view never re-boots it. The admin gate (sync button * reveal + the anonymous catalog gate) keeps fetchIsAdmin() — the * SAME cached /api/whoami promise header.js exports (zero extra * requests). * • the document modal needs NO wiring change: the shell keeps * EXACTLY ONE #doc-modal-* skeleton (the chat's, body level), and * both app.js (chat chips) and this module (RAG row links) open * documents through the shared openDocumentModal(...) against that * single instance (assets/document-modal.js, resolved by * document-level querySelector at import). * * The sync button (phase 32) + the live two-job progress contract * (phase 64 task 04) and the table rows (phase 26: same-page modal * links) are unchanged in content — only the boot shape moved. * * Phase 77 (task 02) — the re-show refresh: the shell router * dispatches `bor:view-refresh` on the view's section when the user * RE-SHOWS an already-mounted view (a switch back onto it, a re-click * of the RAG nav link, or back/forward) — the first show (mount) and * boot never (the mount's own load is the first fetch). This module * listens on root and re-runs the catalog load, which is re-entrant: * a re-load clears the row containers' rows BEFORE filling them (the * History pattern from task 01 — phase 97 moved the clear from the * fetch top into the render, and from the one tbody to both), so a * refresh from a populated level into a sparser one replaces the rows * (no ghost rows). #sources-empty lives OUTSIDE the tbody (a * .empty-state div, not a row), so the clear is a bare * replaceChildren(). The listener is armed only in the ADMIN * branch, after the whoami gate passes: anonymous shows the gate and * never fetches the catalog (the phase-16 soft rule). * * Phase 97 (task 04) — the catalog becomes the DRILL-DOWN TREE the * agent's `ls` sees (the phase-94 concept, one end to end). The load * is `loadTree()` (sources → folders → files, each folder carrying * its STORED description — the rows the agent reads), and the view * drills level by level with no URL change (the navigation is a * re-render). PHASE 167 SUPERSEDED the single-payload model here * (TODO L5 — the 2 MB first load, LOCKED A3): ONE * `GET /api/docs/tree?depth=1` plus ONE node fetch per not-yet-loaded * level — see the Phase 167 (task 04) section; the drill UX itself * (breadcrumb, scroll panel, editing) is unchanged. * * • the drill state is module-scoped: `current` — * { source: null, folder: null } = the top level (the rows ARE the * sources themselves — the ls() equivalence: name, recursive count, * the (source, "") description), `folder: ""` = the source root, * `folder: "one/two"` = the nested folder. The last fetched tree * lives in the module-scoped `kbTree`. * • `renderLevel()` from `current` + `kbTree`: #kb-crumb (hidden at * the top — one link per ancestor: the top level, the source, then * the folder chain, the last segment an aria-current span), #kb-level * (the current level's STORED description — title = the full * source-relative path; HIDDEN when none is stored — the ls rule: * count only, no placeholder), #folders-table = the level's direct * subfolders (top level: the sources), #docs-table = the level's * DIRECT files only — makeRow UNCHANGED (the path link still opens * the same-page modal; the no-JS href escape hatch intact), hidden * when the level has none (at the top level it is ALWAYS hidden — * files are seen per source, as with ls(source)). * • the stat cards show the KB-wide numbers (document count, chunks * sum, max indexed_at) — identical to the former flat walk. Since * phase 167 they read the server's `totals` (a depth-limited tree * cannot be summed client-side); the whole-tree walk stays only as * the defensive no-`totals` fallback. * • the empty state (#sources-empty) is now the "zero SOURCES" * semantic (nothing registered, nothing indexed) — the deliberate * phase-97 change: a registered 0-document source renders its row * (`0` documents) instead (the ls invariant — the agent lists it * too). A failed tree fetch renders that same no-data state (the * former flat-load failure behavior, unchanged in kind). * • Phase 77/79 carry over: the monotonic loadSeq race token (only * the newest load may touch the DOM after its await) and the * re-entrant render — renderLevel() clears BOTH row containers * BEFORE filling them, so a refresh from a populated level into a * sparser one leaves no ghost rows. NEVER-STALE (PLAN §7.4): after * a re-fetch (re-show, sync success, upload success), if the current * location no longer exists in the NEW tree (source unregistered/ * pruned, folder vanished), `current` RESETS to the top level BEFORE * rendering — no stale breadcrumb, no stale block. * • the refresh wirings move with the rename: `loadTree()` at the * boot load, the bor:view-refresh listener, applySyncSuccess, and * the upload-success branch of startSyncPolling — the anonymous * branch still NEVER fetches (no /api/docs/tree request at all). * • the sync button / poll / label / banner / error-modal machinery * and the document-modal wiring are UNTOUCHED (the sync section * above is byte-identical save its two catalog-refresh call * sites, which now call loadTree() — the phase-97 rename). * * Phase 97 (task 05) — the folder-description EDITOR (the phase-57 * affordance, mirrored). The owner edits (or clears) any directory's * stored description with the EXACT file-summary interaction: Edit → * inline textarea (prefilled via .value) → Save / Cancel → a * role=status live-region status. * * • ONE shared function, wireDescriptionEdit(), drives BOTH * surfaces: the static #kb-level Edit button (the current level's * description — the block ships the

+ a .kb-level-body holding * the

+ the Edit button) and the ALWAYS-present Edit button in * every source/folder row's Description cell (makeDescCell builds * it inside makeSourceRow / makeFolderRow — a description can be * CREATED where none is stored: a < 2-document folder, the * generator's fail-soft miss — the editor opens prefilled with the * empty string). NO whoami gate in the view: the RAG view is * admin-only already (the phase-16 gate) and the endpoint's * require_admin is the API-level gate. * • Save → PATCH /api/folders/summary with { source, folder_path, * summary } — folder_path "" for the source root, the * source-relative folder path otherwise (both known from the * target: the row's node, or `current` for the level). 200 → * re-render the description text (textContent ONLY — the XSS * contract) in the surface where the edit happened + status * "Description updated."; an empty save (the server echoes * summary null) → the text goes away (level block hidden / row * cell emptied) + "Description cleared."; the in-memory kbTree * node's summary is updated IN PLACE (no re-fetch — the tree state * stays coherent; the re-fetch is the safety net) — and, since * Phase 98 (task 04), its summary_pending flag is cleared IN * PLACE on the same success path (a created/updated description * is no longer pending — the D4 marker clears where the edit * happened, no re-fetch). Failure * (non-2xx / network) → neutral retry copy (the phase-55 * convention), the editor stays open with the user's text, the * stored text untouched. Cancel → restore the text node. * • the level block is PERSISTENT (reused across levels as you * drill), so wireDescriptionEdit takes a getTarget() getter (a * row's is a constant) and returns a handle whose reset() tears * down an open editor before every re-render (PLAN §7.4 — a * navigate-away or refresh never leaves a stale open editor). * • every editor part is static createElement; the description text * is a text node (textContent / .value) — this module never builds * HTML from document-derived data (the house rule, unchanged). * * Phase 98 (task 02) — the sync button's phase-aware labels: the * post-import span of a sync (the KB overview + the long * folder-summary span) no longer reads as a stuck file count. The * SYNC job's running label is now phase-aware (fmtSyncPhaseLabel — * the section header below carries the decision tree): "overview" → * "Writing KB overview…", "summaries" → "Summarizing folders… * (n/m)" (the folder part omitted while * current_summary is null — the phase's first poll), anything else * (the null prelude, "import") → today's "Syncing… (n/m)" * byte-identical (the count part's TEXT is `N remaining` — the distance * to the end — since phase 193). The UPLOAD job (its status has no phase) keeps the * bare label. The untruncated label rides the button title (now set * for EVERY running label, not just file labels) + #sync-progress as * before (A4). * * Phase 98 (task 04) — the "Summary pending" markers: the catalog * tells the owner a summary is WAITING instead of showing an empty * cell that reads as "missed". A source/folder node is * summary_pending when its summary is due (recursive count >= 2 — * the D3 rule, exactly the next sync's gap-fill set) but no stored * description exists yet. The marker has TWO surfaces, both driven * by the same node flag: * * • the row's Description cell (makeDescCell) — when the stored * summary is empty AND node.summary_pending, the text span * carries the class kb-summary-pending (the muted ink-soft pair, * AA on --surface — text + color, never color alone; the row * cell's font-size/line-height apply — no row-height change) + * the text "Summary pending" + the D4 title, verbatim: * "No stored description yet — the next sync will generate one." * A stored summary * shows the stored text (NEVER the marker); neither stored nor * pending shows the empty cell (the ls rule, unchanged). The * Edit button is UNCHANGED — always present (a manual save * creates the row). * • the level block (renderLevel) — #kb-level shows when the * current level has a stored description (as today) OR is * pending: title as today (the full source-relative path), and * #kb-level-summary shows the stored text, or — when pending — * the D4 pending note, verbatim: * "No description stored yet — the next sync will generate one. (You can write one yourself.)" * Neither stored nor pending stays hidden (the ls rule, * unchanged). The block's * Edit button (write one manually now) already ships in the * static markup (phase 97, task 05). * • the in-place clear: wireDescriptionEdit's success path sets * node.summary_pending = false right after * node.summary = data.summary — a created/updated description is * no longer pending; the marker clears IN PLACE in the surface * where the edit happened, no re-fetch (the re-fetch stays the * safety net). closeEditor re-renders the display state from the * node with the SAME three-state rule the surfaces use: the * pending marker's muted class + tooltip CANNOT survive a save * (a stale "next sync" tooltip under a just-created description), * and a cancel restores the surface's pending display (each * surface passes its pending copy via pendingText — the row's * "Summary pending" marker, the level's D4 note — and its * tooltip via pendingTitle, the row only). * * Phase 99 (task 01, D1) — the ONE-LINE Description clamp: the * owner's long stored descriptions no longer stretch the catalog * rows. A row's Description cell is now ONE flex wrapper * (`.kb-desc-cell` — inside the , which gains no new class) holding * the text span (`.kb-desc-text` — flex: 1 1 auto + min-width: 0 (the * flex item may shrink), overflow: hidden + text-overflow: ellipsis + * white-space: nowrap: the first line that fits, ellipsized — the row * height is ONE line, independent of the description's length) and the * ALWAYS-present Edit button (`.kb-summary-edit`, flex: 0 0 auto — it * never wraps to a second line; its spacing comes from the wrapper's * gap, its old margin-left is gone). The clamp is VISUAL only: the * full text stays in the DOM (the accessible name is unchanged) and * rides the span's title (the hover escape hatch, the house pattern) — * set for real description text whenever non-empty; the phase-98 * marker keeps its OWN D4 title (never overridden), the empty cell * carries none. The editor's open/close swaps happen INSIDE the * wrapper (wireDescriptionEdit's row container IS the wrapper — the * always keeps it; the level block's container stays * .kb-level-body), and closeEditor toggles ONLY the * kb-summary-pending class (the base classes survive) while re-deriving * the clamped span's title from the stored text (a stale pre-edit * title cannot survive a save). The level block (`.kb-level p`) keeps * the FULL unclamped description — the escape hatch at the top when * you click in. * * Phase 99 (task 02, D2) — the browser back/forward walks the * breadcrumb: the drill state IS the history state. Every user- * initiated drill (source-row click, folder-link click, breadcrumb- * segment click — all through goTo) goes through applyTarget(target, * true): when the target DIFFERS from the current level, it FIRST * pushes a STATE-ONLY entry — history.pushState({ view: "rag", kb: * target }, "") — then sets current + re-renders. The push is the * STATE only: the second arg is "" and there is no third — the URL * STAYS PUT (no new route, the phase-76 deep-link surface is * untouched; the shell's pathname is the only route contract). A * re-click of the current level pushes NOTHING (no duplicate history * entries). Back/forward: the window popstate (armed ONCE at mount, * admin branch only — the anonymous gate installs no listeners) ADOPTS * the popped entry's state.kb via the no-push variant (applyTarget(kb, * false) — the browser owns its own entries, so adopt/reset never * push); an entry WITHOUT a kb (the boot entry, the router's view * entries, any foreign state) RESETS the drill to the TOP level * (applyTarget({ source: null, folder: null }, false)). Back at the * top level pops the router's view entry — the view leaves, exactly * as today (the router's pathname-based switch, UNCHANGED). The * re-show (bor:view-refresh) aligns the same way BEFORE the re-fetch: * a kb-carrying top entry (the active-link re-click pushed NOTHING — * the drilled entry is still on top) KEEPS the drill; a kb-less entry * (a fresh nav visit) starts at the top level. Boot pushes NOTHING * (the browser's own entry is the base — the phase-76 boot contract), * and the never-stale resetVanishedLocation is UNCHANGED (it resets * current WITHOUT pushing when a re-fetch finds the level gone — it * follows whatever the history state says; no new entry). The router * module is UNTOUCHED: its popstate reads the pathname only, and a * state-only push never changes it (so rag-internal entries never * trigger a view switch; for a foreign entry the router has already * switched views, and this listener's render of the now-hidden view * is harmless). * * Phase 106 (task 08, D8) — the date COLUMNS (display only — the * admin date EDITOR is task 09): * * • the file table gains the Created column BEFORE Indexed (the * owner's verbatim position, D8): makeRow builds the date cells * explicitly (the plain-td loop can't carry per-cell titles) — * textContent = the locale date (fmtDate, the Indexed idiom), and * the Created cell's title = the FULL ISO value (hover precision — * the path-cell idiom; the E2E asserts on the locale-stable * title, not on the toLocaleString output). The row object fed * from the tree's file nodes carries created_at (task 05's tree * shape — the flat GET /api/docs shape has the field too). * • the folder/source table gains the Updated column BETWEEN * Documents and Description (the owner's verbatim position): the * subtree's MAX document created_at — the tree API DERIVES it * (D9, never stored); makeSourceRow / makeFolderRow render * fmtDate(updated_at) with the ISO value on the cell's title and * the "–" null idiom (the statLast shape) for a 0-document * source. * • the stat cards are UNTOUCHED — they keep their indexed_at * "last indexed" semantics (the owner asked for the column, not * the cards). * * Phase 122 (task 04) — the image-doc thumbnail: a file node of the * tree carries the image affordance (is_image / image_url / summary — * OMITTED on text nodes, the wire-additive rule) when it is an image * document. makeRow's Path cell then renders a FIXED 48px thumbnail * box (object-fit: cover, loading="lazy", alt = the summary — the * vision description; a NULL summary falls back to the title) BEFORE * the path link (the .kb-doc-path flex wrapper — the link keeps its * ellipsis). Progressive enhancement: a failed fetch (or the lazy * first paint) swaps in the document glyph INSIDE the same fixed box * (no layout shift beyond the box, no broken-image placeholder). Text * rows never get a box (the pre-phase bare-link cell, byte-identical). * The glyph is static SVG (aria-hidden — the alt text is the * accessible content); the box + img are properties only, never * innerHTML with document-derived data (the house rule). * * Phase 128 (task 01) — the sync label becomes PARTS: the running * label's string is split into a shrinks-to-fit MAIN part (prefix + * the file/folder path — the part CSS may ellipsize) and a pinned * COUNT part ("(n/m)" — the position, NEVER clipped — the text is * `N remaining` since phase 193), so on a phone * the file path ellipsizes to fit while the count stays on-screen * (the phase-64 bug: with max-width lifted, the inline-block sized to * its full content and the count ran off-screen). #sync-label now * ships TWO child spans — .sync-label-main (the initial idle text * lives there so the pre-JS label renders) + .sync-label-count * (hidden + empty by default) — and the label builders no longer * return one string: fmtSyncLabel / fmtSyncPhaseLabel return the * PARTS ({ main, count } — the same decision tree, the same byte- * identical copy), and ONE writer — setSyncLabel(mainText, * countText) — lands them: mainText → the main part's textContent, * countText → the count part's textContent with the hidden toggle * (absent count → hidden + empty), then the UNTRUNCATED full label * — mainText + (countText ? " " + countText : "") — onto the button * title + #sync-progress (A4 — the screen reader hears the whole * thing; the visible span carries main + count, the space between * them is the CSS gap). Every other #sync-label writer — the idle / * settle labels ("Sync sources", "Synced " — the date- * qualified stamp from fmtSyncTime, phase 154: `HH:MM` on the same * local day, the dated form otherwise), the 202/409 click, * the initSyncButton re-attach — goes through setSyncLabel(main) * (count hidden). The full-string shapes are byte-identical to the * pre-task labels ("Syncing…", "Syncing… ", * "Syncing… (n/m)" — `N remaining` since phase 193, "Importing", * "Writing KB overview…", * "Summarizing folders… (n/m)"); textContent only — no HTML * strings (the house rule). * * Phase 134 (task 02) — the Cancel control + the cancelled terminal: * the owner can stop a running sync. #sync-cancel-btn (the static * markup next to #sync-btn — ship-hidden, the same convention) is * visible + enabled ONLY while a SYNC run is in flight: * enterSyncRunningState shows it for kind "sync" (the live click, the * load-time re-attach, and every running poll tick) and hides it for * kind "upload" (the upload job is NOT cancellable in this phase — * its run keeps the control hidden); settleSyncButton hides it on * EVERY settle (every terminal + both idles — one choke point). A * click runs requestCancel() under the same never-stale contract as * the main button: the control disables IMMEDIATELY (one request at * a time — no double fire) BEFORE the POST /api/sync/cancel — * 403 → the whoami-backstop hide-everything branch (the same depth as * every other 403 in this module), 409 → SILENT (the run ended * between the tick and the click — the poll settles on the next tick, * which hides the control; no error copy), 202 → the control stays * disabled until the terminal (the poll's new cancelled branch settles * everything — the status object, not the request, is authoritative), * any other non-2xx / network failure → the phase-55 neutral retry * copy ("Couldn't cancel the sync — try again.") + re-enable (the * run is still going — the owner can retry). The poll tree gains its * 5th branch (the 7-branch tree becomes 8): state "cancelled" — after * the failed branch, before the upload branches — stops the poll and * runs applySyncCancelled: the NEUTRAL result (A1 — cancel is intent, * not failure): settle the main button retry-ready (which also hides * the Cancel control), "Sync cancelled" on the aria-live result line, * the error banner hidden, the status frame emitted — no modal, no * error styling. The initSyncButton re-attach renders the same result * for a reload during/right after a cancel (a page reload shows * "Sync cancelled", never a stuck running state). The bor:sync-status * event shape is unchanged — the cancelled status object flows through * emitSyncStatus exactly like every other state. * * Phase 149 (task 01) — the sync detail box + the icon-only running * button: the owner's report was that the full live label (a long * source/relative/path + the counts + the chunk part + the phase-152 * image part) is clipped in * the pill even on desktop — the mobile solution (stuffing the parts * in the button) had become the permanent surface. The fix: while a * sync/upload run is in flight, the button shows ONLY the spinning * icon (the `is-running` class — task 02's CSS hides the label parts; * the button IS the loading spinner, exactly the owner's ask), and a * NEW bordered text box under the button row (#sync-progress) shows * the SAME full untruncated live label — wrapping, never clipped, * breathing room. Phase 150 (task 02) folded the announcer into the * box — the previous live-region span was retired and the box is now * the SOLE sync text surface and the sole aria-live region (one live * region, no double announce). The wiring rides the SINGLE writer: * setSyncLabel gains the `running` flag (true on the running entry — * the poll ticks, the 202/409 click, both re-attach entries; the * settle default false) and writes the full label into the box + * reveals/hides it, and owns the button's accessible name (full live * label while running, the ship value "Sync sources" restored on * every settle). The `is-running` * class travels with the spin: added in enterSyncRunningState, removed * in settleSyncButton (every terminal + both idles pass through it). * The settle rendering ("Synced " — the date-qualified stamp, * phase 154 — + the counts line), the Cancel * control, the 409 double-trigger, the error banner/modal, and the * sync status API are all UNCHANGED. * * Phase 150 (task 02) — one box, one writer: the phase-149 * live-region span that sat beside the box is retired — * #sync-progress is the SOLE sync text surface AND the sole * aria-live region (role="status" aria-live="polite", task 01). * setSyncProgress(text) is the ONLY function that writes the box: * the text lands on the inner #sync-progress-text span (textContent * only — the house rule, never HTML) and the box's visibility is * owned by this writer alone (hidden IFF the text is empty — the * global [hidden] rule does the display). Two content modes, decided * at the callsites (the phase-149 "the callsites are the only * decision sites" rule): * • running mode — setSyncLabel(main, count, chunk, running, image) * writes * the SAME untruncated full label through setSyncProgress, ONLY * while running (the idle / settle button labels — "Sync sources", * "Synced " (the date-qualified stamp, phase 154) — must * not fill the panel; they stay on the * button, A2); * • result mode — the settle paths write the result line through * setSyncProgress: the counts line (fmtSyncResult — "N added · * …"), "Sync cancelled", the cancel-failure copy ("Couldn't * cancel the sync — try again."); "" hides the box (the true * idle, the two upload settles — the upload's result line lives * on the Sources page, A3 — and the sync failure, whose banner + * modal carry the error). * requestCancel's pre-fetch clear is a NO-OP on the box (the run is * still in flight — blanking would hide the running surface for up * to one 2 s poll; the poll's `cancelled` branch settles it, and the * control's immediate disable keeps the never-stale contract). The * running label, the button title, and the button aria-label are * byte-identical to pre-phase; no copy changed. * * Phase 167 (task 04, D4/A3 — TODO L5) — the LAZY DRILL: the 2 MB * first payload is gone. The catalog load is ONE * `fetch("/api/docs/tree?depth=1")` (the sources plus one level plus * the server's `totals`), and a folder the payload only NAMES * (`node.truncated === true`, not yet in `levelCache`) fetches * `GET /api/docs/tree/node?source=…&path=…` the FIRST time it opens — * the merged children ride the node (Object.assign, so * `currentLevelNode()`/`renderLevel()` keep their pre-phase semantics * for every loaded level), the level is cached (key * `source + "/" + folder`), and re-opening it is free (zero network). * A NEW tree load clears the cache — the sync/upload/re-show refresh * call sites keep working unchanged — and rehydrates the user's OWN * level when the fresh payload truncates it (a refresh never paints a * half-empty level). §7.4 never-stale, in full: while the node fetch * runs the level the user is LEAVING stays rendered, the clicked link * carries aria-busy + aria-disabled (drillPending — a second click * cannot start a parallel fetch; adopted popstate navigations * rehydrate their level the same way, via ensureCurrentLevel) and * ONE role="status" * "Loading …" row sits in the folders panel; a failure shows * a role="alert" line with a real Retry ' + ""; document.body.appendChild(backdrop); backdrop.querySelector(".sync-modal-close").addEventListener("click", closeSyncModal); backdrop.addEventListener("click", (e) => { if (e.target === backdrop) closeSyncModal(); }); document.addEventListener("keydown", (e) => { if (e.key === "Escape" && backdrop.classList.contains("is-open")) closeSyncModal(); }); return backdrop; } function showSyncModal(error) { if (!syncBtn || !document.body) return; if (!syncModal) syncModal = createSyncModal(); syncModal.querySelector("#sync-modal-error").textContent = error; if (syncModal.classList.contains("is-open")) return; const active = document.activeElement; syncModalReturnFocus = active && active !== document.body ? active : syncBtn; syncModal.classList.add("is-open"); syncModal.querySelector(".sync-modal-close").focus(); } function closeSyncModal() { if (!syncModal || !syncModal.classList.contains("is-open")) return; syncModal.classList.remove("is-open"); const target = syncModalReturnFocus; syncModalReturnFocus = null; if (target && document.contains(target)) target.focus(); } function applySyncSuccess(status) { const time = fmtSyncTime(status.finished_at); settleSyncButton(time ? `Synced ${time}` : "Synced"); // Phase 150 (task 02): the settle's counts line IS the box's // result line (the sole live region) — the string builder is // unchanged (A2: the "Synced " label stays on the button; // the stamp is date-qualified, phase 154). Phase 187 (task 03) // APPENDS the peak-memory clause to that same string — the counts // line keeps its exact wording, the clause trails it, and a null // peak contributes nothing (fmtSyncPeakClause). setSyncProgress(fmtSyncResult(status.detail) + fmtSyncPeakClause(status)); hideSyncError(); emitSyncStatus(status); // Refresh the catalog live — the KB just changed. loadTree(); } function applySyncFailure(status) { const error = sanitizeSyncError(status.error); settleSyncButton("Sync sources"); if (syncBtn) { syncBtn.title = error; syncBtn.setAttribute("aria-label", error); syncBtn.classList.add("is-error"); } // Phase 150 (task 02): the error goes to the banner + the modal — // the box hides, empty (nothing to announce in the live region). setSyncProgress(""); showSyncError(error); emitSyncStatus(status); showSyncModal(error); } /* Phase 134 (task 02): the cancelled terminal — the NEUTRAL result * (A1: cancel is intent, not failure — no error banner, no modal, * no error styling): settle the main button retry-ready (which also * hides the Cancel control), announce "Sync cancelled" on the * aria-live box (#sync-progress — the sole live region, phase * 150), hide the error banner (a failed run's banner must not * survive the cancel), and emit the status frame (the * bor:sync-status detail is the status object, as for every * state). Phase 150 (task 02): the settle's "Sync sources" label * stays on the button only (the non-running setSyncLabel call no * longer writes the box) — the box shows the result line, nothing * else. */ function applySyncCancelled(status) { settleSyncButton("Sync sources"); // The box's result line (phase 150) + the phase-187 peak clause — // a cancelled run's memory is still the number the operator asked // for ("Sync cancelled · peak 512 MB", nothing when it is null). setSyncProgress("Sync cancelled" + fmtSyncPeakClause(status)); hideSyncError(); emitSyncStatus(status); } function applySyncIdle(status) { settleSyncButton("Sync sources"); // Phase 150 (task 02): the true idle — retry-ready, nothing to // announce: the box (the sole live region) hides, empty. setSyncProgress(""); emitSyncStatus(status || { state: "idle" }); } /* The 2 s poll (phase 64 task 04): each tick fetches BOTH jobs — the * sync AND the background upload run (phase 90: unpack + register, * no scan) — and applies the two-job decision tree in order (see the * section header). The 403 on the SYNC fetch hides the button (the * whoami backstop); a 403 on the UPLOAD fetch is simply "no upload" * (never a hide), and a network blip on either fetch retries next * tick. */ function startSyncPolling() { if (syncPollTimer !== null) return; const tick = async () => { let syncStatus = null; let uploadStatus = null; let notAdmin = false; try { const r = await fetch("/api/sync/status"); if (r.status === 403) notAdmin = true; else if (r.ok) syncStatus = await r.json(); } catch { /* network blip — retry next tick */ } if (notAdmin) { stopSyncPolling(); if (syncBtn) syncBtn.hidden = true; applySyncIdle(); return; } // The SECOND job: the background upload run (phase 90: unpack + // register only — no scan; admin-only surface). try { const ur = await fetch("/api/git-sources/upload/status"); if (ur.ok) uploadStatus = await ur.json(); } catch { /* network blip — retry next tick */ } if (!syncStatus) { syncPollTimer = setTimeout(tick, SYNC_POLL_MS); return; } // 1. sync running: the phase-aware label (phase 98 task 02 — the // null prelude + "import" keep the byte-identical file label, // "overview" / "summaries" name themselves; the WHOLE status // goes in for the phase fields). if (syncStatus.state === "running") { enterSyncRunningState( "sync", syncStatus.current_file, syncStatus.files_done, syncStatus.files_total, syncStatus ); syncPollTimer = setTimeout(tick, SYNC_POLL_MS); return; } // 2. upload running: the same animation, the upload's file (A3). if (uploadStatus && uploadStatus.state === "running") { enterSyncRunningState( "upload", uploadStatus.current_file, uploadStatus.files_done, uploadStatus.files_total ); syncPollTimer = setTimeout(tick, SYNC_POLL_MS); return; } if (syncStatus.state === "success") { stopSyncPolling(); applySyncSuccess(syncStatus); return; } if (syncStatus.state === "failed") { stopSyncPolling(); applySyncFailure(syncStatus); return; } // 5. sync cancelled: the NEUTRAL terminal (phase 134 task 02 — // A1: cancel is intent, not failure — no banner, no modal): // the "Sync cancelled" result line + the retry-ready main // button; the settle also hides the Cancel control. if (syncStatus.state === "cancelled") { stopSyncPolling(); applySyncCancelled(syncStatus); return; } // 6. upload success: settle + catalog refresh (A3 — the upload's // counts live on the Sources page; #sync-progress stays // empty + hidden). if (uploadStatus && uploadStatus.state === "success") { stopSyncPolling(); settleSyncButton("Sync sources"); setSyncProgress(""); // the upload settle: the box hides (phase 150) hideSyncError(); emitSyncStatus({ state: "idle" }); loadTree(); return; } // 7. upload failed: settle only — the failure is the Sources page's // error banner, never this page's (A3). if (uploadStatus && uploadStatus.state === "failed") { stopSyncPolling(); settleSyncButton("Sync sources"); setSyncProgress(""); // the upload settle: the box hides (phase 150) hideSyncError(); emitSyncStatus({ state: "idle" }); return; } // 8. both idle: settle retry-ready. stopSyncPolling(); applySyncIdle(syncStatus); }; syncPollTimer = setTimeout(tick, SYNC_POLL_MS); } async function startSync() { let r; try { r = await fetch("/api/sync", { method: "POST" }); } catch { applySyncFailure({ state: "failed", error: "Could not reach the server to start the sync — try again.", }); return; } if (r.status === 403) { stopSyncPolling(); if (syncBtn) syncBtn.hidden = true; applySyncIdle(); return; } if (r.status === 202 || r.status === 409) { // Phase 64: the run is just starting (model check / clone-pull) — // bare "Syncing…" until the first polled file (A4); entering the // running state reveals #sync-progress with the same label // (phase 150: the box IS the announcer). enterSyncRunningState("sync", null, 0, 0); hideSyncError(); if (lastSyncState !== "running") emitSyncStatus({ state: "running" }); startSyncPolling(); return; } let detail = ""; try { detail = (await r.json()).detail || ""; } catch { /* non-JSON */ } applySyncFailure({ state: "failed", error: detail || `The server refused to start the sync (${r.status}).`, }); } /* Phase 134 (task 02): the cancel request — the §7.4 never-stale * contract applies exactly as to the main button: the control * disables IMMEDIATELY (one request at a time — no double fire) * BEFORE the fetch. Phase 150 (task 02): there is no pre-fetch box * clear — the run is still in flight at that moment, so blanking * would hide the running surface for up to one 2 s poll; the * poll's `cancelled` branch settles the box, and the control's * immediate disable keeps the never-stale contract. * • 403 → the whoami-backstop branch (stop polling, hide the * main button, settle idle) — the same depth as every * other 403 in this module; * • 409 → NO-OP: the run ended between the tick and the click — * the poll settles on the next tick (its settle hides * the control); no error copy, no state change; * • 202 → nothing: the control stays disabled — the poll's * `cancelled` branch settles everything (the run may * already be terminal by the next tick — the status * object, not the request, is authoritative); * • any other non-2xx / network failure → the phase-55 neutral * retry copy on #sync-progress (the box) + the control * re-enables (the run is still going — the owner can retry). */ async function requestCancel() { if (!syncCancelBtn) return; syncCancelBtn.disabled = true; // FIRST — never stale, one request at a time // Phase 150 (task 02): the pre-fetch clear is dropped — a NO-OP on // the box. The run is still in flight at this moment, so blanking // would hide the running surface for up to one 2 s poll; the // poll's `cancelled` branch settles it. The never-stale contract // is kept by the control's immediate disable above. let r; try { r = await fetch("/api/sync/cancel", { method: "POST" }); } catch { // Network failure: the run is still going — the phase-55 // neutral retry copy + the control re-enables (retryable). setSyncProgress("Couldn't cancel the sync — try again."); syncCancelBtn.disabled = false; return; } if (r.status === 403) { stopSyncPolling(); if (syncBtn) syncBtn.hidden = true; applySyncIdle(); return; } if (r.status === 409) return; // race: the run ended — the poll settles if (r.ok) return; // 202: the poll's cancelled branch settles everything setSyncProgress("Couldn't cancel the sync — try again."); syncCancelBtn.disabled = false; // the run is still going — retry } /* Load-time re-attach (ADMIN ONLY): a running run re-enters running * state, a terminal run renders its last result. Phase 64 (A3): with * the sync IDLE, an in-flight background upload RUN (phase 90: unpack * + register — the bare "Importing…" label) adopts the button the * same way — the "user clicked upload, then opened sources" case; a * terminal upload is a no-op (the boot-time loadTree() already shows * the current catalog). Phase 98 (task 02): a RUNNING sync re-enters * with the WHOLE status — the label is phase-aware, so a mid- * summaries reload re-enters with the summaries label (the * never-stale contract); a RUNNING upload re-attach stays on the * bare label (its status has no phase — D2). */ async function initSyncButton() { if (!syncBtn) return; if (!(await fetchIsAdmin())) return; let status; try { const r = await fetch("/api/sync/status"); if (r.status === 403) { syncBtn.hidden = true; return; } if (!r.ok) return; status = await r.json(); } catch { return; } if (status.state === "running") { enterSyncRunningState( "sync", status.current_file, status.files_done, status.files_total, status ); emitSyncStatus(status); startSyncPolling(); return; } if (status.state === "success") { applySyncSuccess(status); return; } if (status.state === "failed") { applySyncFailure(status); return; } // Phase 134 (task 02): a reload during/right after a cancel shows // the neutral result — never a stuck running state. if (status.state === "cancelled") { applySyncCancelled(status); return; } // Sync idle: check the SECOND job — an in-flight upload run // re-attaches (the bare "Importing…" label — phase 90: unpack + // register only). let upload; try { const ur = await fetch("/api/git-sources/upload/status"); if (ur.ok) upload = await ur.json(); } catch { /* network blip — the idle settle below is still honest */ } if (upload && upload.state === "running") { enterSyncRunningState( "upload", upload.current_file, upload.files_done, upload.files_total ); emitSyncStatus({ state: "running" }); startSyncPolling(); return; } applySyncIdle(status); } if (syncBtn) { syncBtn.addEventListener("click", startSync); initSyncButton(); } // Phase 134 (task 02): the Cancel control — armed next to the main // button (the control is visible only while a sync run is in // flight, so it can never be reached in any other state). if (syncCancelBtn) { syncCancelBtn.addEventListener("click", requestCancel); } const tbody = root.querySelector("#docs-tbody"); const emptyEl = root.querySelector("#sources-empty"); /* Phase 97 (task 04): the new #folders-wrap ALSO carries the shared * .table-wrap card class — the FILE table's wrap is therefore looked * up through its own table, not the class (a class lookup would hit * #folders-wrap first in document order). */ const tableWrap = root.querySelector("#docs-table").parentElement; const statCards = root.querySelector("#stat-cards"); const gateEl = root.querySelector("#sources-gate"); const statDocs = root.querySelector("#stat-docs"); const statChunks = root.querySelector("#stat-chunks"); const statLast = root.querySelector("#stat-last"); const crumbEl = root.querySelector("#kb-crumb"); const levelEl = root.querySelector("#kb-level"); const levelTitleEl = root.querySelector("#kb-level-title"); const levelSummaryEl = root.querySelector("#kb-level-summary"); const foldersWrap = root.querySelector("#folders-wrap"); const foldersTbody = root.querySelector("#folders-tbody"); /* Phase 97 (task 05): the level block's static Edit button + the * .kb-level-body that holds the description UI (the

+ the * button) — the shared editor swaps INSIDE the body, leaving the * block's

untouched. */ const levelEditBtn = root.querySelector("#kb-level-edit"); const levelBody = levelEl ? levelEl.querySelector(".kb-level-body") : null; /* Phase 16: whoami BEFORE the docs fetch. Anonymous visitors get the * sign-in gate (stat cards + table hidden) and NO /api/docs call — the * catalog is admin-only. The document viewer itself stays public (the * soft rule), so the gate copy points at what keeps working. * Phase 76 (task 02): the whoami request is the shared header module's * cached promise — fetchIsAdmin(), the same single request the shell's * header boots (zero extra requests). */ function fmtDate(iso) { try { return new Date(iso).toLocaleString(); } catch { return iso; } } /* Phase 97 (task 04): the drill-down tree (the module docstring carries the full contract). `kbTree` = the last fetched tree; `current` = the drill state ({ null, null } = top, `folder: ""` = the source root). Phase 79 carries over: the monotonic loadSeq race token invalidates an in-flight load the moment a newer one starts — only the newest load may touch the DOM after its await (the boot re-attach (applySyncSuccess → loadTree) and the boot-time loadTree interleave exactly as the flat load once did). Re-entrancy moves from the fetch top into the render: renderLevel() clears BOTH row containers BEFORE filling them (the phase-77 History pattern, extended to the second container), so a refresh from a populated level into a sparser one leaves no ghost rows. */ let kbTree = { sources: [] }; let current = { source: null, folder: null }; let loadSeq = 0; let levelEditor = null; // phase 97 (task 05): the level editor handle /* Phase 167 (task 04, D4/A3 — the TODO L5 2 MB fix): the client no longer holds the whole tree. `levelCache` marks the folder levels the drill has already fetched (key: source + "/" + the source-relative folder path); the merged children live ON THE NODES (Object.assign in fetchLevel), so currentLevelNode() and renderLevel() keep their pre-phase semantics for every loaded level. `drillPending` is the in-flight drill { source, folder } — a second drill click is a no-op while a node fetch runs (§7.4: every settle path re-enables the controls). `navSeq` bumps on every applyTarget so a navigation invalidates an in-flight drill exactly like a newer load does. A NEW tree load clears the cache (the sync/refresh call sites keep working unchanged) and any in-flight drill with it. */ const levelCache = new Map(); let drillPending = null; let drillRowEl = null; // the ONE in-flight row (loading OR alert) let navSeq = 0; async function loadTree() { const my = ++loadSeq; drillPending = null; // any in-flight drill is invalidated by this load let r; try { r = await fetch("/api/docs/tree?depth=1"); } catch { if (my === loadSeq) renderEmpty(); return; } if (!r.ok) { if (my === loadSeq) renderEmpty(); return; } const tree = await r.json(); if (my !== loadSeq) return; // a newer load owns the DOM now kbTree = tree && Array.isArray(tree.sources) ? tree : { sources: [] }; levelCache.clear(); // a fresh tree invalidates every drilled level resetVanishedLocation(); // Phase 167: the user's own level may be one the fresh depth-1 // payload only NAMES (truncated, cache just cleared) — rehydrate // it through the node route BEFORE it paints, so a refresh never // shows a half-empty level. if (needsLevelFetch(currentLevelNode(), current.source)) { enterFolder({ source: current.source, folder: current.folder }, null, false); return; } renderLevel(); } /* Never-stale (PLAN §7.4, phase 97): after a re-fetch, the drilled * location may no longer exist in the NEW tree (the source was * unregistered/pruned, the folder vanished) — reset to the top level * BEFORE rendering: no stale breadcrumb, no stale block. Since * phase 167 the check is folderKnownIn (what the HELD levels prove) * — the fetch path's own vanished-signal is the node route's 404. */ function resetVanishedLocation() { if (current.source === null) return; const src = kbTree.sources.find((s) => s.name === current.source); if (!src) { current = { source: null, folder: null }; return; } if (current.folder !== null && !folderKnownIn(src, current.folder)) { current = { source: null, folder: null }; } } /* Phase 167 (task 04, D4): the client no longer holds the whole * tree, so the phase-97 full-tree existence walk becomes KNOWN-ness: * a folder is known iff every node of its ancestor chain exists in * what the client holds (the depth-1 tree + the drilled levels — * merged children ride the nodes, so one walk over the held children * answers). A broken chain means the folder is gone OR simply not * loaded that deep — for the never-stale RESET both are honestly * "back to the top level". The drill path does not guess: the node * route's 404 IS the "the folder vanished" signal (fetchLevel). */ function folderKnownIn(src, folderPath) { if (folderPath === "") return true; // the source root always exists let node = src; let acc = ""; for (const part of folderPath.split("/")) { acc = acc ? acc + "/" + part : part; const next = (node.children || []).find( (c) => c.kind === "folder" && c.path === acc ); if (!next) return false; node = next; } return true; } /* The node for a drill target (phase 97, phase 167-generalized): * the source node at the root, or the folder node found by walking * the HELD levels with the folder's cumulative source-relative path * (the builder's folder paths are source-relative, so `one/two` * resolves one level at a time; a truncated node simply has no * children to walk into). */ function nodeForTarget(target) { const src = kbTree.sources.find((s) => s.name === target.source); if (!src) return null; if (target.folder === null || target.folder === "") return src; let node = src; let acc = ""; for (const part of target.folder.split("/")) { acc = acc ? acc + "/" + part : part; const next = (node.children || []).find( (c) => c.kind === "folder" && c.path === acc ); if (!next) return null; node = next; } return node; } function currentLevelNode() { return nodeForTarget(current); } /* The KB-wide stat cards. Phase 167 (task 04, D2/D4): the server's * `totals` (computed from the FULL catalogue rows beside any depth * of tree) are the source of truth — a depth-limited tree CANNOT be * summed client-side. The phase-97 recursive walk (document count, * chunks sum, max indexed_at — the values identical to the former * flat /api/docs walk) stays ONLY as the defensive fallback for a * tree served without `totals` (a pre-phase-167 process) — the * no-crash path. fmtDate reuse for the max (renderLevel). */ function treeStats() { const totals = kbTree.totals; if (totals && typeof totals === "object") { return { docs: totals.documents, totalChunks: totals.chunks, last: totals.last_indexed || "", }; } let docs = 0; let totalChunks = 0; let last = ""; const walk = (node) => { for (const child of node.children || []) { if (child.kind === "file") { docs += 1; totalChunks += child.chunks; if (child.indexed_at > last) last = child.indexed_at; } else { walk(child); } } }; for (const s of kbTree.sources) walk(s); return { docs, totalChunks, last }; } /* The breadcrumb (phase 97): hidden at the top level; when drilled * in, one link per ancestor — the top level (back to the sources * list), the source, then the folder chain — the LAST segment a * span with aria-current="page". No URL change (the navigation is a * re-render); phase 167: an ancestor is already loaded (you cannot * drill past it without holding it), so a breadcrumb step costs no * fetch in practice — goTo stays the ONE drill code either way. */ function renderCrumb() { if (!crumbEl) return; crumbEl.replaceChildren(); if (current.source === null) { crumbEl.hidden = true; return; } crumbEl.hidden = false; let appended = false; const append = (el) => { if (appended) { const sep = document.createElement("span"); sep.className = "kb-crumb-sep"; sep.setAttribute("aria-hidden", "true"); sep.textContent = "/"; crumbEl.appendChild(sep); } crumbEl.appendChild(el); appended = true; }; append(crumbSegment("Knowledge base", { source: null, folder: null })); if (current.folder === null || current.folder === "") { append(crumbCurrent(current.source)); } else { append(crumbSegment(current.source, { source: current.source, folder: "" })); let acc = ""; const parts = current.folder.split("/"); parts.forEach((part, i) => { acc = acc ? acc + "/" + part : part; if (i === parts.length - 1) append(crumbCurrent(part)); else append(crumbSegment(part, { source: current.source, folder: acc })); }); } } function crumbSegment(label, target) { const a = document.createElement("a"); a.className = "kb-crumb-link"; a.href = "#"; // client-side navigation only — no URL change a.textContent = label; // document-derived text — never innerHTML a.addEventListener("click", (e) => { e.preventDefault(); goTo(target, a); }); return a; } function crumbCurrent(label) { const span = document.createElement("span"); span.className = "kb-crumb-current"; span.setAttribute("aria-current", "page"); span.textContent = label; // document-derived text — never innerHTML return span; } /* The drill navigation (phase 99, task 02, D2 — the drill state IS * the history state; since phase 167 a user drill may FIRST fetch * the level — see enterFolder). `applyTarget(target, push)`: when `push` is true the target DIFFERS from the current * level (a re-click of the current row/segment pushes NO duplicate * entry), it FIRST records a STATE-ONLY entry — history.pushState( * { view: "rag", kb: target }, "") — the second arg "" + no third: * the URL stays the shell's pathname (no new route, the phase-76 * deep-link surface is untouched) — then sets `current` + * re-renders. Back/forward (popstate) and the re-show alignment * (bor:view-refresh) adopt with push=false: they never push (the * browser owns those entries). */ function applyTarget(target, push) { if (push && (target.source !== current.source || target.folder !== current.folder)) { history.pushState({ view: "rag", kb: target }, ""); } current = { source: target.source, folder: target.folder }; navSeq++; // phase 167: any navigation invalidates an in-flight drill renderLevel(); } /* Every user-initiated drill (source row, folder link, breadcrumb * segment) — push a history entry, then drill (D2, phase 99 task * 02). Since phase 167 (task 04, A3) the drill may FIRST fetch the * level (enterFolder); the push lands when the level is in hand, so * a failed drill records nothing. `link` is the clicked link — it * carries the in-flight aria-busy/aria-disabled state. */ function goTo(target, link) { enterFolder(target, link, true); } /* Phase 167 (task 04, D4/A3) — the lazy drill. The depth-1 tree * NAMES deeper folders (truncated: true, children not built); the * FIRST open of one fetches its level through the node route, merges * the children into the node, and caches the level — a re-open is * free (zero network). A level the client already holds (or a node * the payload fully built) drills with NO fetch, exactly as before: * applyTarget + render, nothing else. One drill at a time — * drillPending is the §7.4 double-click guard, and every settle * path (success, failure, 404, superseded) releases it. */ function needsLevelFetch(node, source) { return ( !!node && node.truncated === true && !levelCache.has(source + "/" + node.path) ); } async function enterFolder(target, link, push) { if (drillPending) return; // one drill at a time (§7.4 double-click guard) const node = nodeForTarget(target); if (needsLevelFetch(node, target.source)) { drillPending = { source: target.source, folder: target.folder }; const loaded = await fetchLevel(target, node, link); if (!loaded) return; // failed / vanished / superseded — handled inside } applyTarget(target, push); } /* ONE node fetch + its full §7.4 lifecycle. The fetch URL is * /api/docs/tree/node?source=…&path=… (path source-relative; the * route is documented in app/api/docs.py — one catalogue query per * drill, no N+1). The race convention EXTENDS from loadTree: the * response may only paint while NO newer load (loadSeq, phase 79) * and NO navigation (navSeq) have happened — a stale response never * touches the DOM. Success: Object.assign merges the node (children, * counts, dates, summary, pending flags — the wire shape the full * tree produces) and levelCache marks the level; only a 200 caches. * A 404 IS the vanished-folder signal — honest reset to the top * level, nothing cached. Any other failure: the alert + Retry row, * the current level staying rendered. */ async function fetchLevel(target, targetNode, link) { const my = loadSeq; const nav = navSeq; if (link) { link.setAttribute("aria-busy", "true"); link.setAttribute("aria-disabled", "true"); // a double click cannot refetch } showDrillLoading(target.folder.split("/").pop()); let response = null; let vanished = false; try { response = await fetch("/api/docs/tree/node?source=" + encodeURIComponent(target.source) + "&path=" + encodeURIComponent(target.folder)); if (response.status === 404) vanished = true; } catch { response = null; // network failure — the alert path below } // Every settle path re-enables the controls (§7.4) — the link is // only ours to clear while this drill is still THE pending one (a // newer load owns the flags the moment it starts). if (drillPending && drillPending.source === target.source && drillPending.folder === target.folder) { drillPending = null; } if (link) { link.removeAttribute("aria-busy"); link.removeAttribute("aria-disabled"); } if (my !== loadSeq || nav !== navSeq) return false; // superseded — never paints clearDrillRow(); if (vanished) { // The folder vanished under us (pruned/unregistered since the // level was listed) — the phase-97 never-stale contract: reset // to the top level, no stale breadcrumb, nothing cached. current = { source: null, folder: null }; renderLevel(); return false; } if (response === null || !response.ok) { showDrillFailure(target, link); // the current level stays rendered return false; } const merged = await response.json(); if (my !== loadSeq || nav !== navSeq) return false; // stale — never paints Object.assign(targetNode, merged); levelCache.set(target.source + "/" + target.folder, true); return true; } /* The ONE in-flight row of the folders panel — appended to the * level the user is LEAVING (renderLevel's tbody clear owns it: a * re-render always drops the row). Tokens-only .kb-level-loading * (styles.css); textContent only, the house rule. */ function clearDrillRow() { if (drillRowEl) { drillRowEl.remove(); drillRowEl = null; } } function showDrillLoading(name) { clearDrillRow(); const row = document.createElement("tr"); row.className = "kb-level-loading"; const td = document.createElement("td"); td.colSpan = 4; const note = document.createElement("span"); note.setAttribute("role", "status"); note.textContent = "Loading " + name + "…"; // never innerHTML td.appendChild(note); row.appendChild(td); drillRowEl = row; if (foldersWrap) foldersWrap.hidden = false; // the row needs its panel if (foldersTbody) foldersTbody.appendChild(row); } /* Phase 167: rehydrate the CURRENT level when the held tree only * names it — used by the ADOPTED navigations (popstate: the popped * entry can point at a level the client has not fetched since the * last load; the bor:view-refresh alignment is covered by loadTree's * own rehydration). A no-op for held levels and at the top. */ function ensureCurrentLevel() { if (drillPending) return; if (needsLevelFetch(currentLevelNode(), current.source)) { enterFolder({ source: current.source, folder: current.folder }, null, false); } } function showDrillFailure(target, link) { clearDrillRow(); const row = document.createElement("tr"); row.className = "kb-level-loading"; const td = document.createElement("td"); td.colSpan = 4; const note = document.createElement("span"); note.setAttribute("role", "alert"); note.textContent = "Couldn't load " + target.folder.split("/").pop() + " — "; // never innerHTML const retry = document.createElement("button"); retry.type = "button"; // a REAL button (the phase-49 .retry-btn pill) retry.className = "retry-btn"; retry.textContent = "Retry"; retry.addEventListener("click", () => enterFolder(target, link, true)); td.append(note, retry); row.appendChild(td); drillRowEl = row; if (foldersWrap) foldersWrap.hidden = false; if (foldersTbody) foldersTbody.appendChild(row); } /* ONE table for every level (phase 97): at the TOP level the rows * are the SOURCES themselves (the ls() equivalence — name, recursive * count, the stored (source, "") description). textContent only. */ function makeSourceRow(s) { const tr = document.createElement("tr"); const nameTd = document.createElement("td"); const link = document.createElement("a"); link.className = "folder-link"; link.href = "#"; // client-side drill — no URL change link.title = s.name; // hover name (the cell may ellipsize) link.textContent = s.name; // document-derived text — never innerHTML link.addEventListener("click", (e) => { e.preventDefault(); goTo({ source: s.name, folder: "" }, link); }); nameTd.appendChild(link); tr.appendChild(nameTd); const countTd = document.createElement("td"); countTd.textContent = String(s.documents); tr.appendChild(countTd); // Phase 106 (task 08, D8/D9): the Updated cell — the source's // subtree MAX document created_at (the tree API derives it), // BETWEEN the count and the Description (the owner's verbatim // position). A 0-document source has none → the statLast "–" null // idiom; the ISO value rides the title (hover precision — the // makeRow path-cell idiom). const updatedTd = document.createElement("td"); updatedTd.textContent = s.updated_at ? fmtDate(s.updated_at) : "–"; if (s.updated_at) updatedTd.title = s.updated_at; // full ISO on hover tr.appendChild(updatedTd); tr.appendChild(makeDescCell(s, s.name, "", s.name)); // Description + ALWAYS-present Edit (task 05) return tr; } /* A level's subfolder row: the folder's LAST path segment as the * label (the full source-relative path rides the title — the cell * ellipsizes), the recursive count, the stored description (AI or * manual — any row) or an empty cell. textContent only. */ function makeFolderRow(f) { const tr = document.createElement("tr"); const nameTd = document.createElement("td"); const link = document.createElement("a"); link.className = "folder-link"; link.href = "#"; // client-side drill — no URL change link.title = current.source + "/" + f.path; // full path on hover link.textContent = f.path.split("/").pop(); // never innerHTML link.addEventListener("click", (e) => { e.preventDefault(); goTo({ source: current.source, folder: f.path }, link); }); nameTd.appendChild(link); tr.appendChild(nameTd); const countTd = document.createElement("td"); countTd.textContent = String(f.documents); tr.appendChild(countTd); // Phase 106 (task 08, D8/D9): the Updated cell — the folder's // subtree MAX document created_at (the tree API derives it), // BETWEEN the count and the Description (the owner's verbatim // position); the ISO value rides the title (hover precision — the // makeRow path-cell idiom). The "–" branch is defensive: a folder // node always has ≥1 document, so its max is never null (a // 0-document source IS the null case, makeSourceRow). const updatedTd = document.createElement("td"); updatedTd.textContent = f.updated_at ? fmtDate(f.updated_at) : "–"; if (f.updated_at) updatedTd.title = f.updated_at; // full ISO on hover tr.appendChild(updatedTd); tr.appendChild( makeDescCell(f, current.source, f.path, current.source + "/" + f.path) ); // Description + ALWAYS-present Edit (task 05) return tr; } /* Render the CURRENT level from `current` + `kbTree` (phase 97). * Clears BOTH row containers FIRST (re-entrancy — no ghost rows), * then: zero sources → the no-data state; top level → the source * rows (level block + file table hidden); inside a source/folder → * the breadcrumb, the level block (the level's stored description — * hidden when none is stored, the ls rule), the direct subfolders, * and the direct files (makeRow, unchanged — the file node carries * no source, the row object restores the flat shape makeRow reads). */ function renderLevel() { if (foldersTbody) foldersTbody.replaceChildren(); if (tbody) tbody.replaceChildren(); if (levelEditor) levelEditor.reset(); // a re-render never keeps a stale open editor (§7.4) if (!kbTree.sources.length) { renderEmpty(); return; } emptyEl.hidden = true; const st = treeStats(); statDocs.textContent = String(st.docs); statChunks.textContent = String(st.totalChunks); statLast.textContent = st.last ? fmtDate(st.last) : "–"; renderCrumb(); if (current.source === null) { // Top level: the level block is hidden (nothing above the // sources); the folders table lists the SOURCES themselves and // the file table is ALWAYS hidden (files are seen per source, // as with ls(source)). levelEl.hidden = true; for (const s of kbTree.sources) foldersTbody.appendChild(makeSourceRow(s)); foldersWrap.hidden = false; if (tableWrap) tableWrap.hidden = true; return; } const node = currentLevelNode(); if (node === null) { // Defensive: the reset above guarantees the level exists in the // tree this render reads — a null means the tree changed under // us, in which case the top level is the honest view. current = { source: null, folder: null }; renderLevel(); return; } // The level block: the current level's STORED description (source: // the (source, "") row; folder: its row) — OR, since Phase 98 // (task 04, D4), the PENDING note when the level is summary_pending // (the summary is due but not stored yet — the next sync's gap-fill // will generate it, or the owner can write one now via the block's // Edit button). Hidden only when NEITHER is stored nor pending // (the ls rule: count only, no placeholder). Title = the full // source-relative path (e.g. `alpha/two`). if (node.summary || node.summary_pending) { levelTitleEl.textContent = current.folder ? current.source + "/" + current.folder : current.source; levelSummaryEl.textContent = node.summary || "No description stored yet — the next sync will generate one. (You can write one yourself.)"; // Phase 98 (D4): the pending text is the muted marker style — // and the block is REUSED across levels, so a stored level must // clear a previous pending level's class (the same state // closeEditor manages on the editor's close). levelSummaryEl.className = node.summary ? "" : "kb-summary-pending"; levelEl.hidden = false; } else { levelEl.hidden = true; } const children = node.children || []; const subfolders = children.filter((c) => c.kind === "folder"); const files = children.filter((c) => c.kind === "file"); for (const f of subfolders) foldersTbody.appendChild(makeFolderRow(f)); foldersWrap.hidden = subfolders.length === 0; for (const f of files) { tbody.appendChild( makeRow({ source: current.source, path: f.path, title: f.title, chunks: f.chunks, created_at: f.created_at, // phase 106 (task 08, D8): the tree's file date indexed_at: f.indexed_at, // Phase 122 (task 04): the image affordance — the tree's // file node carries is_image / image_url / summary on an // image doc (the omission rule: a TEXT node's wire shape // carries none, so these stay undefined there and makeRow // keeps the bare-link cell, byte-identical to pre-phase). is_image: f.is_image, image_url: f.image_url, summary: f.summary, }) ); } if (tableWrap) tableWrap.hidden = files.length === 0; } /* Phase 122 (task 04): the document glyph — the fallback INSIDE the * fixed thumbnail box (a failed fetch, or a node with no servable * image_url). Static SVG, aria-hidden (the img's alt is the * accessible content; this is decoration for the box). Built with * createElementNS — the module keeps its ONE innerHTML (the static * sync-modal skeleton, the test_kb_tree_ui pin). */ function docThumbGlyph() { const span = document.createElement("span"); span.className = "kb-doc-thumb-glyph"; span.setAttribute("aria-hidden", "true"); const NS = "http://www.w3.org/2000/svg"; const svg = document.createElementNS(NS, "svg"); svg.setAttribute("viewBox", "0 0 48 48"); svg.setAttribute("fill", "none"); svg.setAttribute("stroke", "currentColor"); svg.setAttribute("stroke-width", "2.4"); svg.setAttribute("stroke-linecap", "round"); svg.setAttribute("stroke-linejoin", "round"); const sheet = document.createElementNS(NS, "path"); sheet.setAttribute( "d", "M12 4h16l8 8v28a4 4 0 0 1-4 4H12a4 4 0 0 1-4-4V8a4 4 0 0 1 4-4Z" ); const fold = document.createElementNS(NS, "path"); fold.setAttribute("d", "M28 4v8h8"); svg.append(sheet, fold); span.appendChild(svg); return span; } /* Phase 122 (task 04): the image-doc thumbnail — the FIXED 48px box * (object-fit: cover via CSS, loading="lazy", alt = the summary — * the vision description; a NULL/blank summary falls back to the * title, then the path). A failed fetch swaps in the document * glyph in the SAME box (progressive enhancement — no layout shift * beyond the fixed box, no broken-image placeholder). Called only * for image rows (makeRow gates on d.is_image). */ function docThumb(d) { const box = document.createElement("span"); box.className = "kb-doc-thumb"; const alt = typeof d.summary === "string" && d.summary.trim() !== "" ? d.summary : d.title || d.path; if (d.image_url) { const img = document.createElement("img"); img.className = "kb-doc-thumb-img"; img.loading = "lazy"; img.src = d.image_url; img.alt = alt; img.addEventListener("error", () => box.replaceChildren(docThumbGlyph())); box.appendChild(img); } else { box.appendChild(docThumbGlyph()); } return box; } /* The no-data state (phase 97): zero sources (nothing registered, * nothing indexed) OR a failed tree fetch (the former showEmpty * failure behavior, unchanged in kind) — every catalog surface * hidden, the stat cards read zero. A registered 0-document source * does NOT land here: it renders its `0 documents` row (the ls * invariant — the deliberate semantic change, module docstring). */ function renderEmpty() { if (levelEditor) levelEditor.reset(); // a re-render never keeps a stale open editor (§7.4) statDocs.textContent = "0"; statChunks.textContent = "0"; statLast.textContent = "–"; if (crumbEl) crumbEl.hidden = true; levelEl.hidden = true; if (foldersTbody) foldersTbody.replaceChildren(); if (tbody) tbody.replaceChildren(); if (foldersWrap) foldersWrap.hidden = true; if (tableWrap) tableWrap.hidden = true; emptyEl.hidden = false; } function makeRow(d) { const tr = document.createElement("tr"); const sourceTd = document.createElement("td"); sourceTd.textContent = d.source; // document-derived text — never innerHTML tr.appendChild(sourceTd); // Path cell: a link to the document (phase 10), full path as the // accessible/hover name (the column is ellipsized). Phase 26: the // left-click opens the same-page modal — no new tab (document-modal.js); // the href stays as the no-JS / context-menu escape hatch. const pathTd = document.createElement("td"); pathTd.title = d.path; // full path on hover (column is ellipsized) const link = document.createElement("a"); link.className = "doc-link"; link.href = documentUrl(d.source, d.path); link.addEventListener("click", (e) => { e.preventDefault(); // no new tab (phase 26) — the modal takes over e.stopPropagation(); openDocumentModal(d.source, d.path, link); }); link.title = d.path; // full path as the link's hover/accessible name link.textContent = d.path; // Phase 122 (task 04): an image row gets the FIXED 48px thumbnail // box before the path link (the .kb-doc-path flex wrapper — the // link keeps its ellipsis). Text rows keep the bare-link cell, // byte-identical to pre-phase (no box at all). Phase 181 (task // 04, design D7): verified NON-CHANGE for SVG rows — the thumb // loads the same extension-less image_url and .kb-doc-thumb-img // pins the img to the fixed 48px box (width/height 100% + // object-fit: cover), so a size-less viewBox-only vector fills // the box like a raster; no format sniffing needed here either. if (d.is_image) { const pathWrap = document.createElement("div"); pathWrap.className = "kb-doc-path"; pathWrap.append(docThumb(d), link); pathTd.appendChild(pathWrap); } else { pathTd.appendChild(link); } tr.appendChild(pathTd); // Phase 106 (task 08, D8): the cell order is [title, chunks, // created, indexed] — the Created cell lands BEFORE Indexed (the // owner's verbatim position). The date cells are built EXPLICITLY // (the plain-td loop can't carry per-cell titles): textContent is // the locale date (fmtDate — the Indexed idiom), and the Created // cell carries the FULL ISO value as its title (hover precision — // the path-cell idiom; the E2E asserts on the locale-stable title, // not on the toLocaleString output). for (const value of [d.title, String(d.chunks)]) { const td = document.createElement("td"); td.textContent = value; tr.appendChild(td); } const createdTd = document.createElement("td"); createdTd.textContent = fmtDate(d.created_at); createdTd.title = d.created_at; // full ISO on hover (locale-stable) tr.appendChild(createdTd); const indexedTd = document.createElement("td"); indexedTd.textContent = fmtDate(d.indexed_at); tr.appendChild(indexedTd); return tr; } /* Phase 97 (task 05): wire the LEVEL block's editor (the static * #kb-level-edit button). The level block is PERSISTENT — reused for * whichever level is current — so the target is a GETTER (a row's is * a constant): it reads `current` + currentLevelNode() at open/save * time. onCleared hides the whole block (the ls rule: no description * → no block). The handle's reset() runs on every re-render so a * navigate-away / refresh never leaves a stale open editor (§7.4). */ if (levelEditBtn && levelBody) { levelEditor = wireDescriptionEdit({ editBtn: levelEditBtn, textEl: levelSummaryEl, container: levelBody, getTarget: () => { const node = currentLevelNode(); return node ? { node, source: current.source, folder: current.folder } : null; }, // Phase 98 (D4): the level's pending display (the D4 note — no // tooltip on the level's

: D4's title is the row cell's). pendingText: "No description stored yet — the next sync will generate one. (You can write one yourself.)", onCleared: () => { // The phase-57 announcement beat: keep the block visible a short // beat so the role=status "Description cleared." is still // readable, THEN hide it (the ls rule: no description → no // block) — GUARDED: if a newer level is current by then (a // navigate-away first) or its node has a description again (a // re-create within the beat), the hide is a no-op. setTimeout(() => { const n = currentLevelNode(); if (n && !n.summary) levelEl.hidden = true; }, 2000); }, }); } /* ---------- view boot (phase 76 task 02) ---------- * The shared header is NOT booted here — in the shell it runs * exactly once, via the chat module (app.js) at shell boot. The * admin gate reads fetchIsAdmin() — the SAME cached whoami promise * header.js exports (zero extra requests): the sync button joins * the admin reveal on that one whoami (no extra fetch), and the * anonymous branch gates the catalog in / out with NO * /api/docs/tree request at all (the phase-16 soft rule — the * tree IS the catalog; phase 97). */ const admin = await fetchIsAdmin(); if (syncBtn) syncBtn.hidden = !admin; // admin-only: ship-hidden, revealed on the same whoami if (!admin) { // Anonymous: gate in, catalog out, and no /api/docs/tree request // at all — the tree surfaces ship hidden and never fill. if (statCards) statCards.hidden = true; if (foldersWrap) foldersWrap.hidden = true; if (tableWrap) tableWrap.hidden = true; if (emptyEl) emptyEl.hidden = true; if (gateEl) gateEl.hidden = false; return; } if (gateEl) gateEl.hidden = true; /* Phase 77 (task 02) + phase 97 (task 04) + phase 99 (task 02, D2): a user-initiated re-show of this already-mounted view makes the router dispatch bor:view-refresh on the section — FIRST align the drill state with the history state (a kb-carrying entry KEEPS the drill — the active-link re-click pushed nothing, the drilled entry is still on top; a kb-less entry — a fresh nav visit — starts at the TOP level), THEN re-load the catalog tree (loadTree is race-tokened: only the newest load touches the DOM). Armed ONLY here, after the whoami gate passed: anonymous shows the gate and must never fetch /api/docs/tree (the phase-16 soft rule the story E2E pins). */ root.addEventListener("bor:view-refresh", () => { const kb = history.state && history.state.kb; if (kb) applyTarget(kb, false); else applyTarget({ source: null, folder: null }, false); loadTree(); }); /* Phase 99 (task 02, D2): the browser back/forward walks the breadcrumb — a popstate ADOPTS the popped entry's kb via the no-push variant (the browser owns its entries — adopt/reset never push) or, for a kb-LESS entry (the boot entry, the router's view entries, any foreign state), RESETS the drill to the TOP level. The router's own popstate (registered earlier, at shell boot) reads the pathname only: rag-internal entries never change it, so its listener stays a no-op and THIS listener's render is the visible one; for a foreign entry it has already switched the visible view, so this render is a harmless hidden one. Back at the top level pops the router's view entry — the view leaves, exactly as today. Armed ONCE here, admin branch only: the anonymous gate installs no listeners. */ window.addEventListener("popstate", (event) => { const kb = event.state && event.state.kb; if (kb) applyTarget(kb, false); else applyTarget({ source: null, folder: null }, false); // Phase 167 (task 04): a forward/back can adopt an entry whose // level the client has not fetched since — rehydrate it through // the node route (a no-op for held levels; a truly vanished one // takes the 404-reset / alert path inside). ensureCurrentLevel(); }); loadTree(); }