v1.10.4: expandable 'Why this suggestion?' on Assistant cards (P)

Each Assistant suggestion can now expose the signals behind it.
Clicking 'Why this suggestion?' expands a collapsible table showing:

- For gap-based suggestions: the top 5 of N gaps with track name,
  start → end timecode, and duration.
- For other suggestions: the flat stats dict (total_gaps,
  min_threshold_sec, etc.).

Turns the assistant from AI-black-box into an explainable editor —
users can see why OpenCut is recommending an action before deciding.

Backend:
- core/assistant.py: _count_gaps now returns (count, [top_5_details])
  so the sample gaps ride along in the suggestion payload.
  silence-dead-air suggestions get a 'details' dict.

Frontend:
- _assistantDetailView(sug) renders the details as either a three-
  column row-table (track | time range | duration) or a generic
  key/value list. Plain <details>/<summary> with CSS-replaced
  disclosure triangle — zero JS for the expand/collapse behavior.

Author: SysAdminDoc

extension/com.opencut.panel/client/main.js

@@ -6793,6 +6793,56 @@
         el.assistantBody.appendChild(frag);
     }
 
+    function _assistantDetailView(sug) {
+        var det = sug.details || {};
+        var wrap = document.createElement("div");
+        wrap.className = "assistant-detail-body";
+
+        // Gap-based suggestion: render a small table of the top few gaps.
+        if (Array.isArray(det.gaps) && det.gaps.length) {
+            var intro = document.createElement("div");
+            intro.className = "assistant-detail-intro";
+            intro.textContent = "Top " + det.gaps.length + " of " +
+                (det.total_gaps || det.gaps.length) + " gaps above " +
+                (det.min_threshold_sec || 0.8) + "s:";
+            wrap.appendChild(intro);
+
+            var tbl = document.createElement("div");
+            tbl.className = "assistant-detail-table";
+            for (var i = 0; i < det.gaps.length; i++) {
+                var g = det.gaps[i];
+                var row = document.createElement("div");
+                row.className = "assistant-detail-row";
+                row.innerHTML =
+                    '<span class="assistant-detail-cell">' +
+                        esc(g.track || "audio") + '</span>' +
+                    '<span class="assistant-detail-cell assistant-detail-time">' +
+                        fmtDur(g.start) + " → " + fmtDur(g.end) + '</span>' +
+                    '<span class="assistant-detail-cell assistant-detail-metric">' +
+                        (g.duration || 0).toFixed(2) + 's' + '</span>';
+                tbl.appendChild(row);
+            }
+            wrap.appendChild(tbl);
+            return wrap;
+        }
+
+        // Generic dict: render key/value pairs.
+        var keys = Object.keys(det);
+        if (!keys.length) return null;
+        for (var k = 0; k < keys.length; k++) {
+            var key = keys[k];
+            var val = det[key];
+            if (typeof val === "object") continue;
+            var line = document.createElement("div");
+            line.className = "assistant-detail-row";
+            line.innerHTML =
+                '<span class="assistant-detail-cell">' + esc(key.replace(/_/g, " ")) + '</span>' +
+                '<span class="assistant-detail-cell assistant-detail-metric">' + esc(String(val)) + '</span>';
+            wrap.appendChild(line);
+        }
+        return wrap.children.length ? wrap : null;
+    }
+
     function _assistantCard(sug) {
         var card = document.createElement("div");
         card.className = "assistant-suggestion";
@@ -6808,6 +6858,20 @@
         why.textContent = sug.why;
         card.appendChild(why);
 
+        // v1.10.4 (P): expandable details with the actual signals so the
+        // assistant is explainable instead of opaque.
+        if (sug.details && typeof sug.details === "object") {
+            var detailsBlock = document.createElement("details");
+            detailsBlock.className = "assistant-suggestion-details";
+            var summary = document.createElement("summary");
+            summary.className = "assistant-suggestion-details-summary";
+            summary.textContent = "Why this suggestion?";
+            detailsBlock.appendChild(summary);
+            var inner = _assistantDetailView(sug);
+            if (inner) detailsBlock.appendChild(inner);
+            card.appendChild(detailsBlock);
+        }
+
         var actions = document.createElement("div");
         actions.className = "assistant-suggestion-actions";
 

extension/com.opencut.panel/client/style.css

@@ -13115,3 +13115,85 @@ body:not(.has-clip) .media-sidecar .file-info {
     gap: 6px;
     margin-top: 4px;
 }
+
+/* ============================================================
+   ASSISTANT CARD DETAILS (v1.10.4, feature P)
+   ============================================================ */
+.assistant-suggestion-details {
+    border-top: 1px dashed rgba(236, 230, 218, 0.08);
+    padding-top: 6px;
+    margin-top: 4px;
+}
+
+.assistant-suggestion-details-summary {
+    font-size: 11px;
+    font-weight: 600;
+    color: var(--neon-cyan, #88b2ff);
+    cursor: pointer;
+    list-style: none;
+    padding: 4px 0;
+    user-select: none;
+}
+
+.assistant-suggestion-details-summary::-webkit-details-marker { display: none; }
+.assistant-suggestion-details-summary::marker { content: ""; }
+
+.assistant-suggestion-details-summary::before {
+    content: "▸ ";
+    display: inline-block;
+    transition: transform 0.15s ease;
+    color: rgba(136, 178, 255, 0.7);
+}
+
+.assistant-suggestion-details[open] .assistant-suggestion-details-summary::before {
+    transform: rotate(90deg);
+}
+
+.assistant-detail-body {
+    margin-top: 8px;
+    display: flex;
+    flex-direction: column;
+    gap: 4px;
+}
+
+.assistant-detail-intro {
+    font-size: 10px;
+    color: var(--text-secondary);
+    opacity: 0.8;
+    margin-bottom: 4px;
+}
+
+.assistant-detail-table {
+    display: flex;
+    flex-direction: column;
+    gap: 2px;
+}
+
+.assistant-detail-row {
+    display: grid;
+    grid-template-columns: auto 1fr auto;
+    gap: 10px;
+    align-items: center;
+    padding: 4px 8px;
+    border-radius: 6px;
+    background: rgba(255, 255, 255, 0.02);
+    font-size: 11px;
+    color: var(--text-primary);
+}
+
+.assistant-detail-cell {
+    white-space: nowrap;
+    overflow: hidden;
+    text-overflow: ellipsis;
+}
+
+.assistant-detail-time {
+    color: var(--text-secondary);
+    font-variant-numeric: tabular-nums;
+}
+
+.assistant-detail-metric {
+    font-weight: 600;
+    font-variant-numeric: tabular-nums;
+    color: var(--neon-cyan, #88b2ff);
+}

opencut/core/assistant.py

@@ -63,29 +63,38 @@ def _pick_clip_path(seq_info: Dict[str, Any]) -> str:
     return best_path
 
 
-def _count_gaps(seq_info: Dict[str, Any], min_sec: float = 0.8) -> int:
-    """Count inter-clip gaps on audio tracks > *min_sec* seconds.
-
-    Signal for "run silence removal on this sequence".
+def _count_gaps(seq_info: Dict[str, Any],
+                min_sec: float = 0.8) -> "tuple[int, list]":
+    """Count inter-clip gaps on audio tracks > *min_sec* seconds and
+    return both the count and up to 5 representative gap details
+    (``{track_name, start, end, duration}``).
     """
     gaps = 0
+    details: list = []
     for track in seq_info.get("tracks") or []:
         if track.get("media_type") and track["media_type"].lower() != "audio":
             continue
         clips = track.get("clips") or []
         if len(clips) < 2:
             continue
-        # Sort by start, accepting either seconds or ticks-as-string
         def _s(c): return _num(c.get("start", c.get("in", 0)))
         sorted_clips = sorted(clips, key=_s)
         for i in range(1, len(sorted_clips)):
             prev_end = _num(sorted_clips[i - 1].get("end",
                             _s(sorted_clips[i - 1]) +
                             _num(sorted_clips[i - 1].get("duration"))))
             next_start = _s(sorted_clips[i])
-            if next_start - prev_end > min_sec:
+            gap_len = next_start - prev_end
+            if gap_len > min_sec:
                 gaps += 1
-    return gaps
+                if len(details) < 5:
+                    details.append({
+                        "track": track.get("name") or "",
+                        "start": round(prev_end, 2),
+                        "end": round(next_start, 2),
+                        "duration": round(gap_len, 2),
+                    })
+    return gaps, details
 
 
 def _has_captions_track(seq_info: Dict[str, Any]) -> bool:
@@ -139,7 +148,7 @@ def analyze_sequence(seq_info: Dict[str, Any],
     tracks = seq_info.get("tracks") or []
 
     # 1. Dead air — silence removal
-    gaps = _count_gaps(seq_info, min_sec=0.8)
+    gaps, gap_details = _count_gaps(seq_info, min_sec=0.8)
     if gaps >= 3 and "silence-dead-air" not in dismissed and clip_path:
         out.append({
             "id": "silence-dead-air",
@@ -151,6 +160,12 @@ def analyze_sequence(seq_info: Dict[str, Any],
                 "endpoint": "/silence",
                 "payload": {"filepath": clip_path},
             },
+            "details": {
+                "total_gaps": gaps,
+                "shown": len(gap_details),
+                "gaps": gap_details,
+                "min_threshold_sec": 0.8,
+            },
         })
 
     # 2. No captions track present -> suggest Generate Captions