@floless/app 0.7.1 → 0.9.0

package/dist/web/aware.js

@@ -1585,11 +1585,194 @@
     _handleMenuAction(action);
   };
 
+  // ── Release notes: shared state + popover ─────────────────────────────────────
+  // The channel-correct public site base (e.g. https://floless.io), captured from
+  // /api/health in the health poll. The changelog deep-link is omitted entirely when
+  // this is empty — never hardcode floless.io (it would be wrong on stage/dev).
+  let webBase = '';
+  // The what's-new panel reveals at most once per session (guard against the 5s
+  // health poll re-triggering it after the user expands/dismisses).
+  let whatsNewShown = false;
+
+  const $notesPopover = document.getElementById('notes-popover');
+
+  // ONE renderer for typed change bullets — used by BOTH the popover body and the
+  // what's-new panel detail. Groups bullets by change type (first-seen order); each
+  // group is a typeset label + a bullet list. Only `.added` borrows --accent (CSS).
+  function renderTypedChanges(container, changes) {
+    if (!container) return;
+    const groups = [];
+    const byType = new Map();
+    for (const c of (Array.isArray(changes) ? changes : [])) {
+      const type = String((c && c.type) || '').trim() || 'changed';
+      const desc = String((c && c.description) || '').trim();
+      if (!desc) continue;
+      if (!byType.has(type)) { byType.set(type, []); groups.push(type); }
+      byType.get(type).push(desc);
+    }
+    if (!groups.length) { container.innerHTML = '<p class="relnotes-unavailable">No itemised changes</p>'; return; }
+    container.innerHTML = groups.map((type) => {
+      const items = byType.get(type).map((d) => `<li class="relnotes-item">${escapeHtml(d)}</li>`).join('');
+      return `<div class="relnotes-group">`
+        + `<div class="relnotes-type ${escapeAttr(type)}">${escapeHtml(type)}</div>`
+        + `<ul class="relnotes-list">${items}</ul></div>`;
+    }).join('');
+  }
+
+  // Open the shared release-notes popover for an update pill (or the AWARE version
+  // label). The action row — Update now + the changelog deep-link — renders FIRST,
+  // so "Update now" is live before (and regardless of whether) the notes arrive.
+  // `onUpdate` is optional: the post-AWARE-upgrade label reopen passes none (read-only).
+  let _notesEscHandler = null, _notesOutsideHandler = null, _notesOriginEl = null;
+  function closeNotesPopover() {
+    if (!$notesPopover || $notesPopover.hidden) return;
+    $notesPopover.hidden = true;
+    $notesPopover.innerHTML = '';
+    if (_notesEscHandler) { document.removeEventListener('keydown', _notesEscHandler, true); _notesEscHandler = null; }
+    if (_notesOutsideHandler) { document.removeEventListener('mousedown', _notesOutsideHandler, true); _notesOutsideHandler = null; }
+    const origin = _notesOriginEl; _notesOriginEl = null;
+    if (origin) {
+      origin.setAttribute('aria-expanded', 'false');
+      origin.removeAttribute('aria-controls');
+      try { origin.focus(); } catch { /* origin may have hidden (pill → relaunch) */ }
+    }
+  }
+  function openNotesPopover({ component, version, anchorEl, onUpdate }) {
+    if (!$notesPopover || !version) return;
+    // Clean up a prior open instance's document listeners (reopening from a different
+    // pill) without the focus-restore — the new anchor takes over below.
+    if (_notesEscHandler) { document.removeEventListener('keydown', _notesEscHandler, true); _notesEscHandler = null; }
+    if (_notesOutsideHandler) { document.removeEventListener('mousedown', _notesOutsideHandler, true); _notesOutsideHandler = null; }
+    if (_notesOriginEl && _notesOriginEl !== anchorEl) { _notesOriginEl.setAttribute('aria-expanded', 'false'); _notesOriginEl.removeAttribute('aria-controls'); }
+    const compLabel = component === 'aware' ? 'AWARE' : 'floless.app';
+    $notesPopover.setAttribute('aria-label', compLabel + ' v' + version + ' release notes');
+
+    // Build the "full notes" link, component-aware:
+    //  - app   → the floless.io changelog (floless.app-only by design). Omit when webBase is empty.
+    //  - aware → the PUBLIC AWARE GitHub release. A stable URL built straight from `version`
+    //            (no webBase, no dependency on the notes fetch) — AWARE is NOT on floless.io.
+    const changelogHtml = component === 'aware'
+      ? `<a class="relnotes-changelog" target="_blank" rel="noopener" href="${escapeAttr('https://github.com/aware-aeco/aware/releases/tag/v' + version)}">Full release notes ↗</a>`
+      : (webBase
+        ? `<a class="relnotes-changelog" target="_blank" rel="noopener" href="${escapeAttr(webBase + '/changelog#v' + version)}">Full changelog ↗</a>`
+        : '');
+    const updateHtml = onUpdate ? `<button type="button" class="relnotes-update">Update now</button>` : '';
+
+    // Render the shell: header (skeleton title), body (skeleton bars), action row (LIVE).
+    $notesPopover.innerHTML =
+      `<div class="relnotes-header"><div class="relnotes-title">${compLabel} v${escapeHtml(version)}</div></div>`
+      + `<div class="relnotes-body" aria-busy="true">`
+      +   `<div class="relnotes-skel"><div class="relnotes-skel-line"></div><div class="relnotes-skel-line"></div><div class="relnotes-skel-line"></div></div>`
+      + `</div>`
+      + `<div class="relnotes-actions">${updateHtml}${changelogHtml}</div>`;
+    $notesPopover.hidden = false;
+
+    // Wire Update now — it never waits on the notes fetch.
+    const $update = $notesPopover.querySelector('.relnotes-update');
+    if ($update && onUpdate) {
+      $update.onclick = () => { closeNotesPopover(); onUpdate(version); };
+    }
+
+    // Position relative to the anchor: hang above it (footer is at the bottom), and
+    // clamp the right edge so a wide pill near the left can't push it off-screen.
+    if (anchorEl) {
+      const rect = anchorEl.getBoundingClientRect();
+      $notesPopover.style.bottom = (window.innerHeight - rect.top + 8) + 'px';
+      $notesPopover.style.right = Math.max(8, window.innerWidth - rect.right) + 'px';
+    }
+
+    // a11y: mark the originating control expanded; move focus into the dialog.
+    _notesOriginEl = anchorEl || null;
+    if (anchorEl) { anchorEl.setAttribute('aria-expanded', 'true'); anchorEl.setAttribute('aria-controls', 'notes-popover'); }
+    try { $notesPopover.focus(); } catch { /* container is tabindex=-1 */ }
+
+    // Tab cycles only the (up to 2) action controls; Escape closes + restores focus.
+    const focusables = () => Array.from($notesPopover.querySelectorAll('.relnotes-update, .relnotes-changelog'));
+    _notesEscHandler = (e) => {
+      if (e.key === 'Escape') { e.preventDefault(); closeNotesPopover(); return; }
+      if (e.key === 'Tab') {
+        const f = focusables();
+        if (!f.length) return;
+        const first = f[0], last = f[f.length - 1];
+        const active = document.activeElement;
+        if (e.shiftKey && (active === first || active === $notesPopover)) { e.preventDefault(); last.focus(); }
+        else if (!e.shiftKey && active === last) { e.preventDefault(); first.focus(); }
+      }
+    };
+    document.addEventListener('keydown', _notesEscHandler, true);
+    // Click outside closes — but ignore the opening click on the anchor itself.
+    _notesOutsideHandler = (e) => {
+      if ($notesPopover.contains(e.target) || (anchorEl && anchorEl.contains(e.target))) return;
+      closeNotesPopover();
+    };
+    document.addEventListener('mousedown', _notesOutsideHandler, true);
+
+    // Fetch the notes and fill the body (or the unavailable state). The action row
+    // is untouched — Update now and the changelog link stay live throughout.
+    (async () => {
+      const $body = $notesPopover.querySelector('.relnotes-body');
+      let notes = null;
+      try {
+        const r = await fetch('/api/release-notes?component=' + encodeURIComponent(component) + '&version=' + encodeURIComponent(version));
+        notes = await r.json();
+      } catch { notes = null; }
+      // The popover may have been closed/reopened while the fetch was in flight.
+      if ($notesPopover.hidden || !$body || !$body.isConnected) return;
+      $body.removeAttribute('aria-busy');
+      if (notes && notes.ok) {
+        const title = $notesPopover.querySelector('.relnotes-title');
+        if (title && notes.title) title.textContent = notes.title;
+        const summaryHtml = notes.summary ? `<div class="relnotes-summary">${escapeHtml(notes.summary)}</div>` : '';
+        const header = $notesPopover.querySelector('.relnotes-header');
+        if (header && summaryHtml && !header.querySelector('.relnotes-summary')) header.insertAdjacentHTML('beforeend', summaryHtml);
+        $body.innerHTML = '<div class="relnotes-changes"></div>';
+        renderTypedChanges($body.querySelector('.relnotes-changes'), notes.changes);
+      } else {
+        $body.innerHTML = '<p class="relnotes-unavailable">Release notes unavailable</p>';
+      }
+    })();
+  }
+
   // ── App self-update tag ───────────────────────────────────────────────────────
   // Surface updater.ts: poll GET /api/update (on load + every 6h); when a newer
-  // installed build exists, show a footer tag → confirm → POST /api/update/apply,
-  // which downloads + relaunches into the new version. Hidden in dev/npm (supported:false).
+  // installed build exists, show a footer pill → click opens the release-notes
+  // popover → Update now → POST /api/update/apply, which downloads + relaunches into
+  // the new version. Hidden in dev/npm (supported:false).
   const $appUpdate = document.getElementById('app-update');
+  // The apply body, extracted so the popover's "Update now" can drive it with the
+  // polled target version (no textContent scrape). Preserves the npm-vs-desktop
+  // branch verbatim: npm copies the command; desktop confirms → relaunch.
+  async function applyAppUpdate(version) {
+    if (!$appUpdate) return;
+    // npm channel can't self-apply (no Update.exe) — copy the command for the user's terminal.
+    if ($appUpdate.dataset.channel === 'npm') {
+      const cmd = $appUpdate.dataset.command || 'npm i -g @floless/app@latest';
+      // Best-effort copy — fire-and-forget so the toast never blocks on clipboard permission.
+      if (navigator.clipboard) navigator.clipboard.writeText(cmd).catch(() => {});
+      showToast('Update in your terminal — ' + cmd, 'info');
+      return;
+    }
+    // desktop (Velopack): one-click download + relaunch
+    const v = version || '';
+    if (!window.confirm('Download v' + v + ' and relaunch floless.app now?')) return;
+    // Record the pending version so the new build's first paint can reveal the
+    // what's-new panel (survives the relaunch via localStorage; cleared once shown).
+    try { localStorage.setItem('floless.whatsNew.pending', v); } catch { /* private mode */ }
+    $appUpdate.disabled = true;
+    $appUpdate.textContent = '↑ Updating…';
+    try {
+      const r = await fetch('/api/update/apply', { method: 'POST', headers: { 'content-type': 'application/json' } });
+      const d = await r.json().catch(() => ({}));
+      if (!r.ok || !d.ok) throw new Error(d.error || 'update failed');
+      // Success: the server is exiting + Update.exe relaunches the new build. The health
+      // poll flips to offline (R1 overlay), then the new version reconnects on its own.
+    } catch (e) {
+      $appUpdate.disabled = false;
+      try { localStorage.removeItem('floless.whatsNew.pending'); } catch { /* private mode */ }
+      showToast('Update failed — ' + String((e && e.message) || e).slice(0, 80), 'warn');
+      refreshUpdate();
+    }
+  }
   async function refreshUpdate() {
     if (!$appUpdate) return;
     try {
@@ -1600,57 +1783,99 @@
         $appUpdate.textContent = '↑ Update to v' + d.targetVersion;
         $appUpdate.dataset.channel = d.channel || 'desktop';
         $appUpdate.dataset.command = (npm && d.command) ? d.command : '';
-        $appUpdate.dataset.tip = npm
-          ? 'A newer floless.app (v' + d.targetVersion + ') is on npm — click to copy the update command'
-          : 'A newer floless.app is available — click to download and relaunch into v' + d.targetVersion;
+        $appUpdate.dataset.target = d.targetVersion;
+        $appUpdate.dataset.tip = "What's new in v" + d.targetVersion;
+        $appUpdate.setAttribute('aria-haspopup', 'dialog');
         $appUpdate.hidden = false;
       } else {
-        $appUpdate.hidden = true; // up-to-date / dev / registry-or-feed error → no tag
+        // Dev-override (ships inert): an E2E can force the pill visible deterministically
+        // by setting localStorage['floless.dev.forceUpdate'] = {"component":"app","version":"x.y.z"}.
+        // Read on every poll; absent by default → no behaviour change.
+        if (!applyDevForcedUpdate('app', $appUpdate)) $appUpdate.hidden = true; // up-to-date / dev / registry-or-feed error → no tag
       }
-    } catch { $appUpdate.hidden = true; }
+    } catch {
+      if (!applyDevForcedUpdate('app', $appUpdate)) $appUpdate.hidden = true;
+    }
   }
   if ($appUpdate) {
-    $appUpdate.onclick = async () => {
-      // npm channel can't self-apply (no Update.exe) — copy the command for the user's terminal.
-      if ($appUpdate.dataset.channel === 'npm') {
-        const cmd = $appUpdate.dataset.command || 'npm i -g @floless/app@latest';
-        // Best-effort copy — fire-and-forget so the toast never blocks on clipboard permission.
-        if (navigator.clipboard) navigator.clipboard.writeText(cmd).catch(() => {});
-        showToast('Update in your terminal — ' + cmd, 'info');
-        return;
-      }
-      // desktop (Velopack): one-click download + relaunch
-      const v = $appUpdate.textContent.replace(/^[^0-9]*/, ''); // "↑ Update to v0.5.2" → "0.5.2"
-      if (!window.confirm('Download v' + v + ' and relaunch floless.app now?')) return;
-      $appUpdate.disabled = true;
-      $appUpdate.textContent = '↑ Updating…';
-      try {
-        const r = await fetch('/api/update/apply', { method: 'POST', headers: { 'content-type': 'application/json' } });
-        const d = await r.json().catch(() => ({}));
-        if (!r.ok || !d.ok) throw new Error(d.error || 'update failed');
-        // Success: the server is exiting + Update.exe relaunches the new build. The health
-        // poll flips to offline (R1 overlay), then the new version reconnects on its own.
-      } catch (e) {
-        $appUpdate.disabled = false;
-        showToast('Update failed — ' + String((e && e.message) || e).slice(0, 80), 'warn');
-        refreshUpdate();
-      }
+    $appUpdate.onclick = () => {
+      const version = $appUpdate.dataset.target || '';
+      openNotesPopover({ component: 'app', version, anchorEl: $appUpdate, onUpdate: applyAppUpdate });
     };
     refreshUpdate();
     setInterval(refreshUpdate, 6 * 60 * 60 * 1000); // re-check every 6h so a long-running window notices
   }
 
+  // Dev-override helper — the ONLY forced-visible path. Reveals a pill with a fixed
+  // version when localStorage['floless.dev.forceUpdate'] matches the component, so an
+  // E2E can exercise the popover without a real pending update. Returns true if forced.
+  function applyDevForcedUpdate(component, pillEl) {
+    if (!pillEl) return false;
+    let forced = null;
+    try { forced = JSON.parse(localStorage.getItem('floless.dev.forceUpdate') || 'null'); } catch { forced = null; }
+    if (!forced || forced.component !== component || !forced.version) return false;
+    const v = String(forced.version);
+    pillEl.dataset.target = v;
+    pillEl.dataset.tip = "What's new in v" + v;
+    pillEl.setAttribute('aria-haspopup', 'dialog');
+    if (component === 'aware') { pillEl.textContent = '↑ Upgrade AWARE to v' + v; }
+    else { pillEl.textContent = '↑ Update to v' + v; pillEl.dataset.channel = pillEl.dataset.channel || 'desktop'; }
+    pillEl.hidden = false;
+    return true;
+  }
+
   // ── AWARE runtime upgrade tag ─────────────────────────────────────────────────
   // Surface aware-update.ts: poll GET /api/aware/update (on load + every 6h); when a
-  // newer @aware-aeco/cli exists, show a footer pill → confirm → POST apply, which
-  // reinstalls AWARE in place (no relaunch — the app stays open) and re-stamps the
-  // version live. Mirrors the app self-update pill; differs in that success is silent
-  // (the live version re-stamp IS the confirmation) and there is no relaunch.
+  // newer @aware-aeco/cli exists, show a footer pill → click opens the release-notes
+  // popover → Update now → POST apply, which reinstalls AWARE in place (no relaunch —
+  // the app stays open) and re-stamps the version live. Mirrors the app self-update
+  // pill; differs in that success is silent (the live version re-stamp IS the
+  // confirmation) and there is no relaunch.
   const $awareUpdate = document.getElementById('aware-update');
   // After a successful upgrade, briefly trust the upgraded version: a /api/health request that
   // was in flight before the reinstall finished could resolve with the OLD version and momentarily
   // revert the footer. The live re-stamp (health poll) honors this short settle window.
   let awareUpgradeFloor = null, awareUpgradeFloorUntil = 0;
+  // Extracted apply body — driven by the popover's "Update now" with the polled
+  // target version. Preserves the awareUpgradeFloor settle window + the live
+  // #aware-version re-stamp verbatim; additionally makes the version label a notes
+  // affordance and shows a brief "installed" confirmation before the pill hides.
+  async function applyAwareUpdate(version) {
+    if (!$awareUpdate) return;
+    const v = version || '';
+    if (!window.confirm('Upgrade AWARE runtime to v' + v + '? This reinstalls the npm package in place — the app stays open and the version restamps automatically.')) return;
+    $awareUpdate.disabled = true;
+    $awareUpdate.textContent = '↑ Upgrading…';
+    try {
+      // Cap the wait so the pill never sticks disabled if the global npm install wedges.
+      const r = await fetch('/api/aware/update/apply', { method: 'POST', headers: { 'content-type': 'application/json' }, signal: AbortSignal.timeout(120000) });
+      const d = await r.json().catch(() => ({}));
+      if (!r.ok || !d.ok) throw new Error(d.error || 'aware upgrade failed');
+      // Success is silent: the pill disappears and the AWARE version re-stamps live.
+      $awareUpdate.disabled = false;
+      const wv = document.getElementById('aware-version');
+      if (wv && d.version) {
+        wv.textContent = 'AWARE ' + d.version;
+        awareUpgradeFloor = d.version; awareUpgradeFloorUntil = Date.now() + 10000;
+        // The version label becomes a notes affordance — click to reopen what changed.
+        wv.classList.add('relnotes-reopen');
+        wv.setAttribute('role', 'button');
+        wv.setAttribute('tabindex', '0');
+        wv.dataset.tip = "What's new in v" + d.version + ' — click for notes';
+        wv.dataset.notesVersion = d.version;
+      }
+      // Brief confirmation (~2s) before the pill hides.
+      $awareUpdate.textContent = 'AWARE v' + (d.version || v) + ' installed';
+      setTimeout(() => { $awareUpdate.hidden = true; refreshAwareUpdate(); }, 2000);
+    } catch (e) {
+      $awareUpdate.disabled = false;
+      const msg = (e && e.name === 'TimeoutError')
+        ? 'AWARE upgrade is taking a while — it may still be installing; the version updates when it finishes'
+        : 'AWARE upgrade failed — ' + String((e && e.message) || e).slice(0, 80);
+      showToast(msg, 'warn');
+      refreshAwareUpdate(); // restore the pill text for retry
+    }
+  }
   async function refreshAwareUpdate() {
     if (!$awareUpdate) return;
     try {
@@ -1659,42 +1884,109 @@
       if (r.ok && d.updateAvailable && d.targetVersion) {
         $awareUpdate.textContent = '↑ Upgrade AWARE to v' + d.targetVersion;
         $awareUpdate.dataset.target = d.targetVersion;
-        $awareUpdate.dataset.tip = 'A newer AWARE runtime (v' + d.targetVersion + ') is available — click to install it in place (no relaunch)';
+        $awareUpdate.dataset.tip = "What's new in v" + d.targetVersion;
+        $awareUpdate.setAttribute('aria-haspopup', 'dialog');
         $awareUpdate.hidden = false;
       } else {
-        $awareUpdate.hidden = true; // up-to-date / absent / registry error → no pill
+        // Dev-override (ships inert) — see applyDevForcedUpdate. Read on every poll.
+        if (!applyDevForcedUpdate('aware', $awareUpdate)) $awareUpdate.hidden = true; // up-to-date / absent / registry error → no pill
       }
-    } catch { $awareUpdate.hidden = true; }
+    } catch {
+      if (!applyDevForcedUpdate('aware', $awareUpdate)) $awareUpdate.hidden = true;
+    }
   }
   if ($awareUpdate) {
-    $awareUpdate.onclick = async () => {
-      const v = $awareUpdate.dataset.target || '';
-      if (!window.confirm('Upgrade AWARE runtime to v' + v + '? This reinstalls the npm package in place — the app stays open and the version restamps automatically.')) return;
-      $awareUpdate.disabled = true;
-      $awareUpdate.textContent = '↑ Upgrading…';
-      try {
-        // Cap the wait so the pill never sticks disabled if the global npm install wedges.
-        const r = await fetch('/api/aware/update/apply', { method: 'POST', headers: { 'content-type': 'application/json' }, signal: AbortSignal.timeout(120000) });
-        const d = await r.json().catch(() => ({}));
-        if (!r.ok || !d.ok) throw new Error(d.error || 'aware upgrade failed');
-        // Success is silent: the pill disappears and the AWARE version re-stamps live.
-        $awareUpdate.hidden = true;
-        $awareUpdate.disabled = false;
-        const wv = document.getElementById('aware-version');
-        if (wv && d.version) { wv.textContent = 'AWARE ' + d.version; awareUpgradeFloor = d.version; awareUpgradeFloorUntil = Date.now() + 10000; }
-      } catch (e) {
-        $awareUpdate.disabled = false;
-        const msg = (e && e.name === 'TimeoutError')
-          ? 'AWARE upgrade is taking a while — it may still be installing; the version updates when it finishes'
-          : 'AWARE upgrade failed — ' + String((e && e.message) || e).slice(0, 80);
-        showToast(msg, 'warn');
-        refreshAwareUpdate(); // restore the pill text for retry
-      }
+    $awareUpdate.onclick = () => {
+      const version = $awareUpdate.dataset.target || '';
+      openNotesPopover({ component: 'aware', version, anchorEl: $awareUpdate, onUpdate: applyAwareUpdate });
     };
     refreshAwareUpdate();
     setInterval(refreshAwareUpdate, 6 * 60 * 60 * 1000); // re-check every 6h
   }
 
+  // The AWARE version label, once it's a notes affordance (post in-place upgrade),
+  // reopens the popover on click or Enter/Space.
+  {
+    const $awareVersion = document.getElementById('aware-version');
+    if ($awareVersion) {
+      const reopen = () => {
+        const v = $awareVersion.dataset.notesVersion;
+        if (v) openNotesPopover({ component: 'aware', version: v, anchorEl: $awareVersion });
+      };
+      $awareVersion.addEventListener('click', () => { if ($awareVersion.classList.contains('relnotes-reopen')) reopen(); });
+      $awareVersion.addEventListener('keydown', (e) => {
+        if (!$awareVersion.classList.contains('relnotes-reopen')) return;
+        if (e.key === 'Enter' || e.key === ' ') { e.preventDefault(); reopen(); }
+      });
+    }
+  }
+
+  // ── What's-new panel (floless.app post-update, relaunch-surviving) ────────────
+  // Called from the health poll AFTER #app-version is stamped (so the version
+  // compare has a real value). Reveals once: if a pending self-update version was
+  // recorded before the relaunch AND the now-running build matches it AND the user
+  // hasn't already dismissed that version, fetch its notes and show the panel.
+  function maybeShowWhatsNew() {
+    if (whatsNewShown) return;
+    let pending, seen;
+    try { pending = localStorage.getItem('floless.whatsNew.pending'); seen = localStorage.getItem('floless.whatsNew.seen'); } catch { return; }
+    if (!pending) return;
+    const appVer = (document.getElementById('app-version')?.textContent || '').replace(/[^0-9.]/g, '');
+    if (appVer !== pending || seen === pending) { try { localStorage.removeItem('floless.whatsNew.pending'); } catch { /* private mode */ } return; }
+
+    const panel = document.getElementById('whats-new-panel');
+    if (!panel) return;
+    whatsNewShown = true; // guard: reveal at most once per session
+
+    const $summaryText = panel.querySelector('.whats-new-summary-text');
+    const $toggle = panel.querySelector('.whats-new-toggle');
+    const $detail = panel.querySelector('.whats-new-detail');
+    const $detailInner = panel.querySelector('.whats-new-detail-inner');
+    const $link = panel.querySelector('.whats-new-link');
+    const $dismiss = panel.querySelector('.whats-new-dismiss');
+
+    // Changelog deep-link — channel-correct base only; omit (hide) when unknown.
+    if ($link) {
+      if (webBase) { $link.href = webBase + '/changelog#v' + pending; $link.hidden = false; }
+      else { $link.removeAttribute('href'); $link.hidden = true; }
+    }
+    if ($summaryText) $summaryText.textContent = 'floless.app v' + pending + ' is now running.';
+
+    // Toggle expands/collapses the detail (grid-rows transition); label + aria flip.
+    if ($toggle && $detail) {
+      $toggle.onclick = () => {
+        const open = $detail.classList.toggle('open');
+        $toggle.setAttribute('aria-expanded', open ? 'true' : 'false');
+        $toggle.textContent = open ? 'Hide' : "What's new";
+      };
+    }
+    // Dismiss — no confirm; persist the seen version so it never re-reveals.
+    if ($dismiss) {
+      $dismiss.onclick = () => {
+        try { localStorage.setItem('floless.whatsNew.seen', pending); localStorage.removeItem('floless.whatsNew.pending'); } catch { /* private mode */ }
+        panel.hidden = true;
+        document.getElementById('app')?.classList.remove('has-whats-new');
+      };
+    }
+
+    // Reveal the panel (adds the 4th grid row), then fill the detail with shared bullets.
+    document.getElementById('app')?.classList.add('has-whats-new');
+    panel.hidden = false;
+    (async () => {
+      let notes = null;
+      try {
+        const r = await fetch('/api/release-notes?component=app&version=' + encodeURIComponent(pending));
+        notes = await r.json();
+      } catch { notes = null; }
+      if (notes && notes.ok) {
+        if ($summaryText && notes.summary) $summaryText.textContent = notes.summary;
+        renderTypedChanges($detailInner, notes.changes);
+      } else if ($detailInner) {
+        $detailInner.innerHTML = '<p class="relnotes-unavailable">Release notes unavailable</p>';
+      }
+    })();
+  }
+
   // ONE Run (the approved single-Run model). "▶ Run workflow" does a REAL run against
   // the live host, using the app inputs. If the app has a report node, it drives
   // the in-app HTML Viewer (renders + caches the returned HTML); otherwise it
@@ -2245,8 +2537,14 @@
           // version CAN change (an out-of-band `npm i -g`, or the in-app upgrade), so
           // re-stamp it whenever /api/health reports a different value — never show a
           // stale runtime version in the footer.
+          // Capture the channel-correct public site base for the changelog deep-links
+          // (popover + what's-new). Empty until /api/health reports it → links omitted.
+          if (h && h.webBase) webBase = h.webBase;
           const av = document.getElementById('app-version');
           if (av && h && h.appVersion && !shownVersion) { av.textContent = 'v' + h.appVersion; shownVersion = true; }
+          // After the build version is stamped, reveal the relaunch-surviving what's-new
+          // panel iff this is the build we just self-updated into (guarded to once).
+          maybeShowWhatsNew();
           const wv = document.getElementById('aware-version');
           if (wv && h && h.awareVersion) {
             const next = 'AWARE ' + h.awareVersion;
@@ -3266,6 +3564,188 @@
     else if ($routinesModal.classList.contains('show')) hideModal($routinesModal);
   });
 
+  // ── Report an issue ──────────────────────────────────────────────────────────
+  // The hamburger "Report an issue" item files into the PRIVATE product log via
+  // POST /api/report-issue (the floless.io relay; report-relay.ts). The user gets a
+  // confirmation ref, not a public link (private repo). The /floless-app-report-issue
+  // skill is the richer terminal path (it reads run traces + the .flo to file a
+  // diagnosed report). Modal elements are static in index.html, present when this runs.
+  const $riModal = document.getElementById('report-issue-modal');
+  const $riForm = document.getElementById('ri-form');
+  const $riState = document.getElementById('ri-state');
+  const $riTitle = document.getElementById('ri-title');
+  const $riDesc = document.getElementById('ri-desc');
+  const $riContext = document.getElementById('ri-context');
+  const $riSend = document.getElementById('ri-send');
+  const $riCancel = document.getElementById('ri-cancel');
+  let riCategory = 'bug';
+  let riSubmitting = false;
+  let riAppVersion = ''; // captured from /api/health on open so the report actually carries
+  let riAwareVersion = ''; // the versions the modal promises ("sent automatically: …")
+
+  const riSyncSend = () => { $riSend.disabled = !($riTitle.value.trim() && $riDesc.value.trim()); };
+  const riClose = () => { if (!riSubmitting) hideModal($riModal); };
+  const riSetCategory = (cat) => {
+    riCategory = cat;
+    $riModal.querySelectorAll('#ri-category .rtn-mode-btn').forEach((b) => {
+      const on = b.dataset.cat === cat;
+      b.classList.toggle('active', on);
+      b.setAttribute('aria-pressed', String(on));
+    });
+  };
+  // Build the post-submit states with safe DOM methods (textContent, not innerHTML).
+  const riButton = (id, label, primary, onclick) => {
+    const b = document.createElement('button');
+    b.id = id;
+    if (primary) b.className = 'primary';
+    b.textContent = label;
+    b.onclick = onclick;
+    return b;
+  };
+  // A Lucide-style circle-check (stroke SVG, matching the menu icons) for the success state —
+  // it actually means "received/done", vs an ad-hoc glyph. Inherits var(--ok) via currentColor.
+  const riCheckIcon = () => {
+    const NS = 'http://www.w3.org/2000/svg';
+    const svg = document.createElementNS(NS, 'svg');
+    svg.setAttribute('viewBox', '0 0 24 24');
+    svg.setAttribute('width', '34');
+    svg.setAttribute('height', '34');
+    svg.setAttribute('fill', 'none');
+    svg.setAttribute('stroke', 'currentColor');
+    svg.setAttribute('stroke-width', '1.75');
+    svg.setAttribute('stroke-linecap', 'round');
+    svg.setAttribute('stroke-linejoin', 'round');
+    svg.style.display = 'block';
+    svg.style.margin = '0 auto';
+    const circle = document.createElementNS(NS, 'circle');
+    circle.setAttribute('cx', '12');
+    circle.setAttribute('cy', '12');
+    circle.setAttribute('r', '10');
+    const check = document.createElementNS(NS, 'path');
+    check.setAttribute('d', 'm9 12 2 2 4-4');
+    svg.append(circle, check);
+    return svg;
+  };
+  const riShowState = (...nodes) => {
+    while ($riState.firstChild) $riState.removeChild($riState.firstChild);
+    for (const n of nodes) $riState.appendChild(n);
+    $riState.hidden = false;
+    $riForm.hidden = true;
+  };
+
+  openReportIssue = function openReportIssueReal() {
+    riSubmitting = false;
+    $riForm.hidden = false;
+    $riState.hidden = true;
+    while ($riState.firstChild) $riState.removeChild($riState.firstChild);
+    $riTitle.value = '';
+    $riDesc.value = '';
+    riSetCategory('bug');
+    riAppVersion = '';
+    riAwareVersion = '';
+    $riSend.disabled = true;
+    $riSend.textContent = 'Send report';
+    // Auto-attached diagnostics line — versions + the open workflow, read fresh from health.
+    $riContext.textContent = 'Also sent automatically: app + AWARE version, and the open workflow.';
+    api('/api/health').then((h) => {
+      riAppVersion = h.appVersion || '';
+      riAwareVersion = h.awareVersion || '';
+      const app = currentId && apps.get(currentId);
+      const wf = app ? ` · workflow "${app.displayName || currentId}"` : '';
+      $riContext.textContent = `Also sent automatically: FloLess v${h.appVersion || '?'}, AWARE v${h.awareVersion || '?'}${wf}`;
+    }).catch(() => { /* keep the generic line on a health blip */ });
+    showModal($riModal);
+    setTimeout(() => $riTitle.focus(), 0);
+  };
+
+  function riRenderSuccess(ref) {
+    const wrap = document.createElement('div');
+    wrap.className = 'graft-success';
+    const icon = document.createElement('div');
+    icon.className = 'gs-icon';
+    icon.setAttribute('aria-hidden', 'true');
+    icon.appendChild(riCheckIcon());
+    const msg = document.createElement('div');
+    msg.className = 'gs-msg';
+    msg.textContent = ref
+      ? `Received — logged as ${ref} · We'll follow up privately.`
+      : "Received · We'll follow up privately.";
+    wrap.append(icon, msg);
+    const actions = document.createElement('div');
+    actions.className = 'modal-actions';
+    const done = riButton('ri-done', 'Done', true, () => hideModal($riModal));
+    actions.append(done);
+    riShowState(wrap, actions);
+    done.focus();
+  }
+
+  function riRenderSignIn() {
+    const sub = document.createElement('div');
+    sub.className = 'modal-sub';
+    sub.textContent = 'Sign in to send a report — your session has expired.';
+    const actions = document.createElement('div');
+    actions.className = 'modal-actions';
+    const close = riButton('ri-signin-close', 'Close', false, () => hideModal($riModal));
+    const signin = riButton('ri-signin-btn', 'Sign in', true, async () => {
+      try { await api('/api/license/start', { method: 'POST' }); } catch { /* surfaced via license polling */ }
+      hideModal($riModal);
+    });
+    actions.append(close, signin);
+    riShowState(sub, actions);
+  }
+
+  async function riSubmit() {
+    if (riSubmitting) return;
+    const title = $riTitle.value.trim();
+    const body = $riDesc.value.trim();
+    if (!title || !body) return;
+    riSubmitting = true;
+    $riSend.disabled = true;
+    $riSend.textContent = 'Sending…';
+    // Versions are filled by the health fetch on open; if a fast submit beat it, fetch them
+    // now so the report carries the versions the modal promised ("sent automatically: …").
+    if (!riAppVersion || !riAwareVersion) {
+      try {
+        const h = await api('/api/health');
+        riAppVersion = riAppVersion || h.appVersion || '';
+        riAwareVersion = riAwareVersion || h.awareVersion || '';
+      } catch { /* best-effort — send with whatever we have */ }
+    }
+    const app = currentId && apps.get(currentId);
+    const context = {
+      source: 'web',
+      appId: currentId || null,
+      workflow: app ? (app.displayName || currentId) : null,
+      appVersion: riAppVersion || null,
+      awareVersion: riAwareVersion || null,
+    };
+    try {
+      const r = await api('/api/report-issue', { method: 'POST', body: JSON.stringify({ category: riCategory, title, body, context }) });
+      riSubmitting = false; // response in hand — Done / Escape / backdrop may close
+      riRenderSuccess(r.ref || '');
+    } catch (e) {
+      riSubmitting = false;
+      const err = (e && e.body && e.body.error) || '';
+      if (err === 'signed_out') {
+        riRenderSignIn(); // the action isn't possible until signed in — hide the form, don't grey it out
+      } else if (err === 'rate_limited') {
+        showToast('Too many reports just now — please wait a moment and try again', 'warn');
+        $riSend.disabled = false; $riSend.textContent = 'Send report';
+      } else {
+        showToast("Couldn't send — check your connection and try again", 'err');
+        $riSend.disabled = false; $riSend.textContent = 'Send report';
+      }
+    }
+  }
+
+  $riTitle.addEventListener('input', riSyncSend);
+  $riDesc.addEventListener('input', riSyncSend);
+  $riSend.onclick = () => riSubmit();
+  $riCancel.onclick = () => riClose();
+  $riModal.onclick = (e) => { if (e.target === $riModal) riClose(); };
+  $riModal.querySelectorAll('#ri-category .rtn-mode-btn').forEach((b) => { b.onclick = () => riSetCategory(b.dataset.cat); });
+  document.addEventListener('keydown', (e) => { if (e.key === 'Escape' && $riModal.classList.contains('show')) riClose(); });
+
   // ── init (after app.js bootstrap) ────────────────────────────────────────────
   // app.js already stored the ORIGINAL functions as .onclick/.oninput before we
   // reassigned the globals; rebind via arrows so they resolve our versions at