feat(kb): edit + re-embed document summaries from the viewer (admin)

frontend/assets/document.js

@@ -51,6 +51,15 @@
  * doc.summary renders as a labeled .doc-summary section above the
  * original content on BOTH surfaces (page + modal) through this one
  * core; the summary text is a text node (XSS contract unchanged).
+ *
+ * Phase 57 (task 02, D4): the panel gains an ADMIN-ONLY edit
+ * affordance (docAdminReady() gate on the module-cached whoami): an
+ * Edit button in the panel's header row opens an inline editor
+ * (prefilled textarea + Save/Cancel + a role=status live region), and
+ * Save PATCHes /api/documents/summary. The section is built for
+ * everyone exactly as phase 36 — the public viewer stays
+ * byte-for-byte identical (no button, no wiring, no admin-only
+ * network call) until the admin gate resolves true.
  */
 
 import { fetchIsAdmin, initSharedHeader } from "./header.js";
@@ -125,6 +134,14 @@ export function renderDocument(doc, { titleEl, metaEl, contentEl }) {
     body.textContent = doc.summary; // text node — XSS contract unchanged
     section.append(title, body);
     contentEl.appendChild(section);
+    // Phase 57 (task 02, D4): the section above is the phase-36 shape
+    // for EVERYONE — only an authenticated admin (docAdminReady(), the
+    // module-cached whoami promise) then gains the header row + Edit
+    // button + editor wiring. Anonymous / fetch failure: the panel is
+    // exactly what phase 36 built (byte-for-byte unchanged).
+    void docAdminReady().then((admin) => {
+      if (admin) wireSummaryEdit(section, doc);
+    });
   }
   if (doc.format === "md" || doc.format === "markdown") {
     const wrap = document.createElement("div");
@@ -139,6 +156,146 @@ export function renderDocument(doc, { titleEl, metaEl, contentEl }) {
   }
 }
 
+/* ---------- summary editing (phase 57, task 02 — D4, admin-only) ----------
+ * The .doc-summary panel is the ONE place the stored summary is edited
+ * (page + modal through this core). Only an admin (docAdminReady) ever
+ * gets the affordance; the public viewer is byte-for-byte unchanged. */
+
+/* The admin gate (D4 — the viewer stays public): the module-cached
+ * /api/whoami promise (header.js's fetchIsAdmin — the SAME single
+ * request per page the shared header already makes on every surface,
+ * so this adds no request of its own). A non-admin or any fetch
+ * failure resolves false → the anonymous viewer. */
+async function docAdminReady() {
+  try {
+    return (await fetchIsAdmin()) === true;
+  } catch {
+    return false;
+  }
+}
+
+/* The edit affordance on one rendered .doc-summary section. The bare
+ * h2 becomes a header row (label left, Edit button right). Edit swaps
+ * the .doc-summary-text node for the inline editor — a prefilled
+ * textarea (value, never innerHTML — XSS contract), Save / Cancel,
+ * and a role=status live region. Save PATCHes /api/documents/summary
+ * with { source, path, summary } — the pair comes from the doc object
+ * (the same values the modal core carries, document-modal.js). Success
+ * re-renders the text node via textContent and announces "Summary
+ * updated."; an empty save that clears announces "Summary cleared."
+ * and removes the panel a short beat later — the confirmation stays
+ * readable, and the renderer only draws the panel for non-empty
+ * summaries. Cancel restores the text node. A failure keeps the
+ * editor open with the user's text and shows neutral retry copy
+ * (phase-55 convention). */
+function wireSummaryEdit(section, doc) {
+  const title = section.querySelector(".doc-summary-title");
+  const body = section.querySelector(".doc-summary-text");
+  if (!title || !body) return;
+
+  /* Header row: label left, Edit button right (admin-only — the
+   * anonymous section keeps its bare h2). */
+  const head = document.createElement("div");
+  head.className = "doc-summary-head";
+  const editBtn = document.createElement("button");
+  editBtn.type = "button";
+  editBtn.className = "doc-summary-edit";
+  editBtn.textContent = "Edit";
+  head.append(title, editBtn);
+  section.replaceChildren(head, body);
+
+  /* Editor parts (built once; the textarea is rebuilt on every open so
+   * it always starts from the CURRENT stored summary). */
+  let editor = null;
+  const actions = document.createElement("div");
+  actions.className = "doc-summary-actions";
+  const saveBtn = document.createElement("button");
+  saveBtn.type = "button";
+  saveBtn.className = "doc-summary-save";
+  saveBtn.textContent = "Save";
+  const cancelBtn = document.createElement("button");
+  cancelBtn.type = "button";
+  cancelBtn.className = "doc-summary-cancel";
+  cancelBtn.textContent = "Cancel";
+  actions.append(saveBtn, cancelBtn);
+  const status = document.createElement("p");
+  status.className = "doc-summary-status";
+  status.setAttribute("role", "status");
+  status.setAttribute("aria-live", "polite");
+
+  /* Back to the display state: the text node re-rendered from the
+   * doc object (the CURRENT stored summary), the live region (the
+   * announced message), the Edit button available again. If the
+   * summary is gone (a clear landed while the editor was open — e.g.
+   * Cancel right after a successful empty save) the panel is gone
+   * too: the renderer only draws it for non-empty summaries. */
+  function closeEditor(message) {
+    status.textContent = message;
+    editBtn.hidden = false;
+    if (typeof doc.summary !== "string" || doc.summary.trim() === "") {
+      section.remove();
+      return;
+    }
+    body.textContent = doc.summary; // text node — the CURRENT stored summary
+    section.replaceChildren(head, body, status);
+    editBtn.focus();
+  }
+
+  async function saveSummary() {
+    const value = editor.value;
+    saveBtn.disabled = true; // one PATCH at a time (never stale)
+    status.textContent = "";
+    try {
+      const res = await fetch("/api/documents/summary", {
+        method: "PATCH",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({ source: doc.source, path: doc.path, summary: value }),
+      });
+      if (!res.ok) {
+        // Neutral retry copy (phase-55 convention) — the user's text
+        // stays in the editor (the editor stays open on failure).
+        status.textContent = "Couldn't update the summary — try again.";
+        return;
+      }
+      const data = await res.json();
+      if (data.summary === null) {
+        // Cleared (D4): the panel disappears — the renderer only draws
+        // it for non-empty summaries. The live-region confirmation
+        // stays visible for a short beat before the panel leaves the
+        // DOM (a screen reader must be able to read it; the removal
+        // is a no-op if the surface re-rendered or closed meanwhile).
+        doc.summary = null;
+        status.textContent = "Summary cleared.";
+        setTimeout(() => section.remove(), 2000);
+        return;
+      }
+      doc.summary = data.summary;
+      closeEditor("Summary updated.");
+    } catch {
+      // Network failure: same neutral shape, the reachable? copy.
+      status.textContent = "Couldn't update the summary — is the app reachable?";
+    } finally {
+      saveBtn.disabled = false;
+    }
+  }
+
+  function openEditor() {
+    editor = document.createElement("textarea");
+    editor.className = "doc-summary-editor";
+    editor.value = typeof doc.summary === "string" ? doc.summary : ""; // value, never innerHTML
+    status.textContent = "";
+    editBtn.hidden = true;
+    section.replaceChildren(head, editor, actions, status);
+    editor.focus();
+  }
+
+  editBtn.addEventListener("click", openEditor);
+  saveBtn.addEventListener("click", () => {
+    void saveSummary();
+  });
+  cancelBtn.addEventListener("click", () => closeEditor(""));
+}
+
 /* ---------- /document.html page (phases 10/13/19) ----------
  * Phase 26: viewer-page-specific — see the import-safety note in the
  * header. The guard is #doc-title: it exists only on this page, so the