@lamemind/loom-deck 0.14.0 → 0.16.0

package/README.md

@@ -4,12 +4,16 @@ Deck TUI (Ink) **per-progetto** della famiglia [loom](https://github.com/lamemin
 
 Legge il `tasks.md` del progetto e, con un tasto (poi un click), **spawna** una tab
 [Ptyxis](https://gitlab.gnome.org/chergert/ptyxis) che avvia una sessione Claude Code
-già bound alla task via `LOOM_TASK`, dritta su `/loom-works:run-task <Txx>`.
+già bound alla task via `LOOM_TASK`, con un prompt di recap sullo stato della task.
 
 ```
-↑↓ scegli la task  →  ⏎  →  tab CC di fianco  →  parte già su /loom-works:run-task <Txx>
+↑↓ scegli la task  →  ⏎  →  tab CC di fianco  →  LOOM_TASK bound + recap stato task
 ```
 
+Entrambi i prefissi del contratto loom entrano in lista: **`T`** (code task) e
+**`D`** (doc task). Nessuna differenza di trattamento — il prompt iniziale è un
+recap, non l'invocazione di una skill, quindi vale identico sulle due famiglie.
+
 ## Ruolo nella famiglia loom
 
 `loom-deck` è un **client** con runtime proprio (TUI Ink) che **consuma** il contratto
@@ -148,7 +152,19 @@ che non può mai produrre un risultato.
 
 Con l'hash vuoto la lista è **raggruppata per conversazione**; `⏎` è contestuale
 alla riga selezionata — su una riga-conversazione **riprende** la sessione
-(come dal pane Sessions), su una riga-occorrenza apre il **reader**.
+(come dal pane Sessions), su una riga-occorrenza apre il **reader**. La selezione
+parte dalla prima *occorrenza*, non dalla riga di gruppo: quella è un segnaposto
+di navigazione, raggiungibile con le frecce ma non una destinazione.
+
+L'estratto attorno al match **si allarga col terminale**: a 190 colonne sono
+~170 caratteri di contesto, non i 50 di un valore fisso — ed è il contesto la
+ragione per cui si legge la riga invece di aprire il reader.
+
+Sotto la lista, un **pannello di anteprima** mostra il contesto attorno
+all'occorrenza selezionata e si aggiorna navigando con le frecce. Prende solo le
+righe che la lista non usa: con pochi risultati riempie il terminale, con molti
+sparisce e la lista se le riprende — quando c'è tanto da scorrere la priorità è
+vedere più occorrenze, il contesto è il premio per una ricerca già stretta.
 
 Il reader mostra il messaggio intero, aperto già **posizionato sull'occorrenza**
 col match evidenziato: `↑↓` riga, `PgUp`/`PgDn` pagina, `g`/`G` estremi, `esc`
@@ -181,6 +197,11 @@ p  priorità     s  stato     i  id
 
 Partendo da catena vuota, digitare `ppi` produce `[pri ↓, id ↑]`. Il ciclo parte
 sempre **dallo stato corrente**, che il modale mostra dal vivo mentre digiti.
+
+Sull'**id** il confronto è numerico (`T9` prima di `T10`, non lessicografico) e i
+due prefissi sono blocchi distinti — le `D` in coda alle `T`: i counter `T` e `D`
+sono separati nel contratto loom, quindi `T01` e `D01` non sono confrontabili
+come numeri soli.
 A parità su tutte le chiavi decide sempre l'`id` (confronto **numerico**: `T9`
 prima di `T10`) → l'ordine è deterministico, mai instabile fra un refresh e l'altro.
 
@@ -222,7 +243,8 @@ npx @lamemind/loom-deck
 scripts/deck-run T18
 ```
 
-Apre una tab Ptyxis nella window attiva con `LOOM_TASK=T18 claude '/loom-works:run-task T18'`.
+Apre una tab Ptyxis nella window attiva con `LOOM_TASK=T18 claude 'recap stato task T18'`
+(prompt override-abile via `LOOM_DECK_ENTER_PROMPT`, placeholder `{TASK}`).
 
 ## Sviluppo (TUI Ink)
 

package/dist/cli.js

@@ -13,7 +13,7 @@ import { buildRows, firstRowKey, moveRowSelection, rowIndexOfKey, searchSessions
 import { appendPin, appendSessionRecord, appendTaskBinding, loadSessionIndex, } from './task-index.js';
 import { assembleSessionList, firstSelectableId, moveSelection, rowIndexOf, selectedSession, } from './session-list.js';
 import { launchLegend, loadIdentity, loadLaunch } from './config.js';
-import { isCompact, layoutBudget, normalizeEmoji, readerCapacity, searchListCapacity, windowRange, wrapLines, wrapWithOffsets, } from './viewport.js';
+import { isCompact, layoutBudget, normalizeEmoji, readerCapacity, searchListCapacity, searchPreviewCapacity, windowRange, wrapLines, wrapWithOffsets, } from './viewport.js';
 import { applyView, cycleSort, describeSort, priName, progName, toggleHidden, PRI_ENTRIES, PROG_ENTRIES, } from './view.js';
 import { initialDetail, progressText, writeTaskEdit, PRI_GLYPH, PRI_LABEL, PROG_GLYPH, } from './task-edit.js';
 import { loadView, saveView, viewFilePath } from './view-store.js';
@@ -497,11 +497,19 @@ function Deck({ cwd, tasksPath, tasksDir }) {
     // ≤9 ms su tutti i tipi — sotto il tempo fra due battute. Il memo evita di
     // rifarla sui re-render che non toccano né query né opzioni (il poll delle
     // sessioni ogni 1,5s è già filtrato dalla signature in `useSessions`).
-    const searchResult = useMemo(() => searchSessions(sessions, searchHash, searchQuery, searchOpts), [sessions, searchHash, searchQuery, searchOpts]);
+    const searchResult = useMemo(() => searchSessions(sessions, searchHash, searchQuery, searchOpts, searchExcerptWidth(columns)), [sessions, searchHash, searchQuery, searchOpts, columns]);
     // Con l'hash valorizzato la conversazione è una sola e già nominata nel campo:
     // la riga-sessione ripeterebbe un dato costante rubando una riga per gruppo.
     const searchFlat = searchHash.trim().length > 0;
     const searchRows = useMemo(() => buildRows(searchResult, searchFlat), [searchResult, searchFlat]);
+    // T52 — riga selezionata e, se è un'occorrenza, il suo corpo wrappato per
+    // l'anteprima sotto la lista. Memoizzato per (testo, larghezza): navigando
+    // con le frecce si ri-wrappa solo quando cambia davvero l'occorrenza.
+    const searchSelRow = useMemo(() => selectedRow(searchRows, searchSelKey), [searchRows, searchSelKey]);
+    const searchPreviewWidth = Math.max(20, (columns || 80) - 8);
+    const searchPreviewBody = useMemo(() => searchSelRow?.kind === 'hit'
+        ? wrapWithOffsets(searchSelRow.hit.text, searchPreviewWidth)
+        : [], [searchSelRow, searchPreviewWidth]);
     // T52 — corpo del messaggio aperto nel reader, wrappato UNA volta per (testo,
     // larghezza). Senza memo ogni pressione di freccia rifarebbe l'a-capo di un
     // messaggio che nella coda lunga arriva a 150k char.
@@ -673,22 +681,52 @@ function Deck({ cwd, tasksPath, tasksDir }) {
         setSearchOpts((o) => ({ ...o, kinds: { ...o.kinds, [kind]: !o.kinds[kind] } }));
     }
     function editSearchField(fn) {
+        // La nota racconta l'esito di un'AZIONE su una lista che, con l'eager, si
+        // ricostruisce a ogni carattere: appena la query cambia è già scaduta.
+        // Lasciarla lì la fa leggere come se descrivesse lo stato corrente — nello
+        // specifico «nessuna occorrenza selezionata» sopra una lista con una riga
+        // visibilmente selezionata, cioè una contraddizione a schermo.
+        setNote('');
         if (searchField === 'hash')
             setSearchHash(fn);
         else
             setSearchQuery(fn);
     }
     // `useInput` consegna il CHUNK letto da stdin, non un tasto: un incollaggio —
-    // o una raffica di tasti più veloce di una read — arriva come stringa unica,
-    // byte di controllo compresi. Senza filtro finiscono DENTRO la query: non si
-    // vedono, ma Ink li conta nella larghezza della riga e nessun match li
-    // soddisfa, quindi la ricerca smette di trovare senza dire perché.
-    // Le newline diventano spazio invece di sparire: incollare due righe deve
-    // separare le parole, non fonderle.
+    // o una raffica di tasti piu' veloce di una read — arriva come stringa unica,
+    // byte di controllo compresi. Due conseguenze, entrambe verificate su pty:
+    //
+    //  1. I byte di controllo finiscono DENTRO il campo se non li si filtra. Non
+    //     si vedono, ma Ink li conta nella larghezza della riga e nessun match li
+    //     soddisfa -> la ricerca smette di trovare senza dire perche'. Le newline
+    //     diventano spazio invece di sparire: incollare due righe deve separare
+    //     le parole, non fonderle.
+    //
+    //  2. Un TAB digitato subito dopo una lettera (~60 ms, cioe' battitura veloce
+    //     normale) arriva incollato ad essa: `key.tab` resta falso e il ramo del
+    //     cambio campo non scatta mai. Trattarlo come testo lo renderebbe uno
+    //     spazio, per giunta nel campo sbagliato — e' cosi' che `70897aff` + Tab
+    //     + `congelat` finiva tutto quanto nel campo hash.
+    //
+    // Si spezza quindi il chunk SUL TAB applicando il cambio campo in mezzo: il
+    // risultato e' identico alla battitura lenta. Stessa lezione del modale sort
+    // (T39), che cicla sui caratteri del chunk invece di leggerlo intero.
     function typeIntoField(chunk) {
-        const clean = chunk.replace(/[\r\n\t]/g, ' ').replace(/[\u0000-\u001f\u007f]/g, '');
-        if (clean)
-            editSearchField((s) => s + clean);
+        setNote('');
+        const clean = (s) => s.replace(/[\r\n]/g, ' ').replace(/[\u0000-\u001f\u007f]/g, '');
+        const parts = chunk.split('\t');
+        let field = searchField;
+        const add = { hash: '', query: '' };
+        for (let k = 0; k < parts.length; k++) {
+            if (k > 0)
+                field = field === 'hash' ? 'query' : 'hash';
+            add[field] += clean(parts[k]);
+        }
+        if (add.hash)
+            setSearchHash((v) => v + add.hash);
+        if (add.query)
+            setSearchQuery((v) => v + add.query);
+        setSearchField(field);
     }
     const searchCap = searchListCapacity(rows, Boolean(note));
     useInput((input, key) => {
@@ -1095,7 +1133,26 @@ function Deck({ cwd, tasksPath, tasksDir }) {
         }
         const selIdx = rowIndexOfKey(searchRows, searchSelKey);
         const win = windowRange(searchRows.length, selIdx, searchCap);
-        return (_jsx(SearchScreen, { hash: searchHash, query: searchQuery, field: searchField, opts: searchOpts, result: searchResult, rows: searchRows.slice(win.start, win.end), selectedKey: searchSelKey, selectedKind: selectedRow(searchRows, searchSelKey)?.kind ?? null, above: win.start, below: searchRows.length - win.end, capacity: searchCap, bindings: bindings, pinned: pinned, projectCore: identity ? `${identity.owner} ${identity.name}` : null, note: note }));
+        // Anteprima dell'occorrenza selezionata: prende le righe che la lista non
+        // usa. Con molti risultati `spare` è 0 e il pannello non esiste — la lista
+        // se le riprende tutte, che è la priorità giusta quando c'è molto da
+        // scorrere. La finestra si CENTRA sul match (`windowRange`), così il
+        // contesto arriva da entrambi i lati.
+        const spare = searchPreviewCapacity(searchCap, win.end - win.start);
+        let preview = null;
+        if (spare >= 1 && searchSelRow?.kind === 'hit') {
+            const h = searchSelRow.hit;
+            const mline = Math.max(0, searchPreviewBody.findIndex((l) => l.end > h.matchStart));
+            const pw = windowRange(searchPreviewBody.length, mline, spare);
+            preview = {
+                hit: h,
+                lines: searchPreviewBody.slice(pw.start, pw.end),
+                from: pw.start,
+                total: searchPreviewBody.length,
+                ts: sessions.find((s) => s.sessionId === h.sessionId)?.ts ?? 0,
+            };
+        }
+        return (_jsx(SearchScreen, { preview: preview, hash: searchHash, query: searchQuery, field: searchField, opts: searchOpts, result: searchResult, rows: searchRows.slice(win.start, win.end), selectedKey: searchSelKey, selectedKind: selectedRow(searchRows, searchSelKey)?.kind ?? null, above: win.start, below: searchRows.length - win.end, capacity: searchCap, bindings: bindings, pinned: pinned, projectCore: identity ? `${identity.owner} ${identity.name}` : null, columns: columns, note: note }));
     }
     // ── Budget d'altezza ────────────────────────────────────────────────────
     // Il frame deve restare sotto `rows`, sempre: oltre quella soglia Ink smette
@@ -1171,6 +1228,31 @@ function EditModal({ id, draft, row }) {
 // terminale misurano diversamente (vedi normalizeEmoji).
 const KIND_TAG = { ai: 'ai', tool: 'tl', human: 'hu' };
 const KIND_COLOR = { ai: 'cyan', tool: 'gray', human: 'green' };
+/**
+ * Larghezza dell'estratto, DERIVATA dalle colonne del terminale.
+ *
+ * Una costante qui è spazio buttato a ogni riga: su un terminale a 190 colonne
+ * un estratto fisso a 50 lascia il match con ~20 caratteri di contesto per lato
+ * quando potrebbe averne 80 — e il contesto attorno al match è l'unica ragione
+ * per cui si legge la riga invece di aprire il reader.
+ *
+ * Scomposizione delle colonne consumate dalla cornice e dal prefisso di riga:
+ *   4  box esterno (2 bordi + 2 padding)
+ *   4  box lista   (2 bordi + 2 padding)
+ *   2  caret
+ *   4  indice del record
+ *   3  spazio + tag del kind + spazio
+ * Prudente per costruzione: sottostimare tronca un carattere in più,
+ * sovrastimare manderebbe la riga a capo e sfonderebbe il budget d'altezza.
+ */
+function searchExcerptWidth(columns) {
+    return Math.max(30, (columns || 80) - 17);
+}
+/** Titolo della conversazione sulla riga-gruppo: prende ciò che avanza dopo le
+ *  colonne a larghezza fissa (caret, pin, hash, task, conteggio, data). */
+function searchTitleWidth(columns) {
+    return Math.max(24, (columns || 80) - 56);
+}
 /**
  * Cosa scrivere sulla riga-gruppo per distinguere una conversazione dall'altra.
  *
@@ -1227,27 +1309,34 @@ function SearchListHeader({ result, query, above, below, }) {
     }
     return (_jsxs(Text, { bold: true, wrap: "truncate-end", children: [result.shown, " occorrenze in ", result.sessionCount, " conversazioni", result.hidden > 0 ? _jsxs(Text, { color: "yellow", children: [" \u00B7 +", result.hidden, " oltre il cap"] }) : null, above > 0 ? _jsxs(Text, { dimColor: true, children: [" \u00B7 \u2191", above] }) : null, below > 0 ? _jsxs(Text, { dimColor: true, children: [" \u00B7 \u2193", below] }) : null] }));
 }
-/**
- * Schermata di ricerca full-text (T52).
- *
- * Due campi + toggle + lista di occorrenze. Con l'hash vuoto la lista è
- * raggruppata per conversazione: la riga-gruppo NON ripete il nome del progetto
- * (D3: sono tutte dello stesso progetto, sarebbe una colonna costante) e usa lo
- * spazio per ciò che distingue davvero una conversazione — hash, task legata,
- * titolo, data.
- */
-function SearchScreen({ hash, query, field, opts, result, rows, selectedKey, selectedKind, above, below, capacity, bindings, pinned, projectCore, note, }) {
+function SearchScreen({ preview, hash, query, field, opts, result, rows, selectedKey, selectedKind, above, below, capacity, bindings, pinned, projectCore, columns, note, }) {
     const enter = selectedKind === 'session' ? 'resume' : selectedKind === 'hit' ? 'leggi' : '—';
     return (_jsxs(Box, { flexDirection: "column", borderStyle: "round", borderColor: "cyan", paddingX: 1, children: [_jsx(Text, { bold: true, color: "cyan", children: "loom-deck" }), _jsxs(Text, { dimColor: true, wrap: "truncate-end", children: ["ricerca \u00B7 ", _jsx(Text, { color: "yellow", children: "tab" }), " campo \u00B7 ", _jsx(Text, { color: "yellow", children: "\u2191\u2193" }), " naviga \u00B7", ' ', _jsx(Text, { color: "yellow", children: "\u23CE" }), " ", enter, " \u00B7 ", _jsx(Text, { color: "yellow", children: "esc" }), " chiudi"] }), _jsxs(Box, { flexDirection: "column", borderStyle: "round", borderColor: "yellow", paddingX: 1, marginTop: 1, children: [_jsxs(Text, { wrap: "truncate-end", children: [_jsx(Text, { dimColor: true, children: "hash   " }), _jsx(Text, { color: field === 'hash' ? 'yellow' : undefined, children: hash }), field === 'hash' ? _jsx(Text, { inverse: true, children: " " }) : null, !hash ? _jsx(Text, { dimColor: true, children: "  (vuoto = tutte le conversazioni)" }) : null] }), _jsxs(Text, { wrap: "truncate-end", children: [_jsx(Text, { dimColor: true, children: "chiave " }), _jsx(Text, { color: field === 'query' ? 'yellow' : undefined, children: query }), field === 'query' ? _jsx(Text, { inverse: true, children: " " }) : null] }), _jsx(ToggleHint, { opts: opts })] }), _jsxs(Box, { flexDirection: "column", borderStyle: "single", borderColor: "gray", paddingX: 1, marginTop: 1, children: [_jsx(SearchListHeader, { result: result, query: query, above: above, below: below }), rows.slice(0, Math.max(0, capacity)).map((row) => {
                         const sel = row.key === selectedKey;
                         if (row.kind === 'session') {
                             const s = row.session;
                             const bound = bindings.get(s.sessionId);
-                            return (_jsxs(Text, { inverse: sel, wrap: "truncate-end", children: [sel ? CARET : CARET_OFF, pinned.has(s.sessionId) ? _jsx(Text, { color: "yellow", children: "\uD83D\uDCCC" }) : _jsx(Text, { dimColor: true, children: "\u25CB" }), ' ', _jsx(Text, { color: "cyan", children: s.sessionId.slice(0, 8) }), _jsx(Text, { dimColor: true, children: " \u00B7 " }), bound ?? _jsx(Text, { dimColor: true, children: "spot" }), _jsx(Text, { dimColor: true, children: " \u00B7 " }), truncate(conversationLabel(s, projectCore, bound), 44), _jsxs(Text, { dimColor: true, children: ['  ', "(", row.hitCount, row.hidden > 0 ? `+${row.hidden}` : '', ") ", fmtDateTime(s.ts)] })] }, row.key));
+                            return (_jsxs(Text, { inverse: sel, wrap: "truncate-end", children: [sel ? CARET : CARET_OFF, pinned.has(s.sessionId) ? _jsx(Text, { color: "yellow", children: "\uD83D\uDCCC" }) : _jsx(Text, { dimColor: true, children: "\u25CB" }), ' ', _jsx(Text, { color: "cyan", children: s.sessionId.slice(0, 8) }), _jsx(Text, { dimColor: true, children: " \u00B7 " }), bound ?? _jsx(Text, { dimColor: true, children: "spot" }), _jsx(Text, { dimColor: true, children: " \u00B7 " }), truncate(conversationLabel(s, projectCore, bound), searchTitleWidth(columns)), _jsxs(Text, { dimColor: true, children: ['  ', "(", row.hitCount, row.hidden > 0 ? `+${row.hidden}` : '', ") ", fmtDateTime(s.ts)] })] }, row.key));
                         }
                         const h = row.hit;
                         return (_jsxs(Text, { inverse: sel, wrap: "truncate-end", children: [sel ? CARET : CARET_OFF, _jsx(Text, { dimColor: true, children: String(h.idx).padStart(4) }), ' ', _jsx(Text, { color: KIND_COLOR[h.kind], children: KIND_TAG[h.kind] }), " ", h.excerpt] }, row.key));
-                    })] }), note ? _jsx(Text, { color: "green", wrap: "truncate-end", children: normalizeEmoji(note) }) : null] }));
+                    })] }), preview ? _jsx(SearchPreviewPane, { p: preview }) : null, note ? _jsx(Text, { color: "green", wrap: "truncate-end", children: normalizeEmoji(note) }) : null] }));
+}
+/**
+ * Anteprima dell'occorrenza selezionata, sotto la lista.
+ *
+ * Riempie le righe che la lista non usa: con pochi risultati il terminale
+ * resterebbe vuoto per tre quarti, e il contesto attorno al match è proprio
+ * ciò che serve per decidere se è l'occorrenza giusta. Nel caso comune evita
+ * del tutto di aprire il reader.
+ *
+ * Si aggiorna navigando con le frecce, e la finestra è centrata sul match:
+ * stessa `windowRange` della lista, stessa evidenziazione del reader
+ * (`ReaderLine`) — nessuna primitiva nuova.
+ */
+function SearchPreviewPane({ p }) {
+    const last = Math.min(p.total, p.from + p.lines.length);
+    return (_jsxs(Box, { flexDirection: "column", borderStyle: "single", borderColor: "gray", paddingX: 1, marginTop: 1, children: [_jsxs(Text, { dimColor: true, wrap: "truncate-end", children: ["record ", p.hit.idx, " \u00B7 ", KIND_LABEL[p.hit.kind], p.ts ? ` · ${fmtDateTime(p.ts)}` : '', " \u00B7 righe ", p.from + 1, "-", last, " di ", p.total, " \u00B7", ' ', _jsx(Text, { color: "yellow", children: "\u23CE" }), " apre il reader"] }), p.lines.map((l, i) => (_jsx(ReaderLine, { line: l, from: p.hit.matchStart, to: p.hit.matchEnd }, p.from + i)))] }));
 }
 /**
  * Reader fullscreen (T52 · D8).

package/dist/search.js

@@ -19,7 +19,10 @@
 /** Sotto questa soglia non si cerca: 1-2 char matchano ovunque e la lista
  *  sarebbe rumore. Stato lecito, non un errore. */
 export const MIN_QUERY = 3;
-/** Larghezza nominale dell'estratto attorno al match. */
+/** Larghezza di ripiego dell'estratto, usata solo quando il chiamante non
+ *  conosce le colonne del terminale (test, uso non-TUI). In UI la larghezza
+ *  arriva SEMPRE da `columns`: inchiodarla qui sprecherebbe tutto lo spazio di
+ *  un terminale largo — su 190 colonne significa ~140 buttate per riga. */
 export const EXCERPT_WIDTH = 50;
 /** Cap per singola conversazione. Serve a tenere leggibile un gruppo, non a
  *  proteggere la memoria: una query corta può matchare centinaia di volte nello
@@ -121,7 +124,7 @@ export function excerptAround(text, start, end, width = EXCERPT_WIDTH) {
  *
  * `re` deve avere il flag `g` (lo garantisce buildMatcher).
  */
-function scanBody(sessionId, body, re, need) {
+function scanBody(sessionId, body, re, need, excerptWidth) {
     const hits = [];
     let count = 0;
     re.lastIndex = 0;
@@ -135,7 +138,7 @@ function scanBody(sessionId, body, re, need) {
                 sessionId,
                 idx: body.idx,
                 kind: body.kind,
-                excerpt: excerptAround(body.text, start, end),
+                excerpt: excerptAround(body.text, start, end, excerptWidth),
                 matchStart: start,
                 matchEnd: end,
                 text: body.text,
@@ -155,7 +158,7 @@ function scanBody(sessionId, body, re, need) {
  * uguaglianza: gli 8 char che la statusline mostra bastano a individuarla, e
  * nessuno copia un uuid intero a mano.
  */
-export function searchSessions(sessions, hashPrefix, query, opts) {
+export function searchSessions(sessions, hashPrefix, query, opts, excerptWidth = EXCERPT_WIDTH) {
     const prefix = hashPrefix.trim().toLowerCase();
     const scoped = prefix
         ? sessions.filter((s) => s.sessionId.toLowerCase().startsWith(prefix))
@@ -178,7 +181,7 @@ export function searchSessions(sessions, hashPrefix, query, opts) {
             // spazio nella lista. A zero la scansione prosegue lo stesso — serve il
             // conteggio, che è ciò che alimenta «+N occorrenze».
             const need = Math.max(0, Math.min(MAX_HITS_PER_SESSION - hits.length, MAX_TOTAL_HITS - shown - hits.length));
-            const r = scanBody(session.sessionId, body, re, need);
+            const r = scanBody(session.sessionId, body, re, need, excerptWidth);
             found += r.count;
             hits.push(...r.hits);
         }
@@ -221,10 +224,19 @@ export function buildRows(result, flat) {
     }
     return rows;
 }
-/** Prima riga selezionabile; null = lista vuota. Ogni riga è selezionabile —
- *  non esiste un separatore, a differenza di `session-list.ts`. */
+/**
+ * Riga su cui atterrare quando la selezione va ricostruita.
+ *
+ * Preferisce la prima **occorrenza**, non la prima riga in assoluto. In modalità
+ * raggruppata la lista si apre sempre con una riga-sessione, che è un
+ * segnaposto di navigazione e non una destinazione: atterrarci lascerebbe
+ * l'anteprima vuota all'apertura di ogni ricerca, e `⏎` prometterebbe un resume
+ * quando l'utente ha appena cercato delle occorrenze.
+ *
+ * Le righe-sessione restano raggiungibili con le frecce. null = lista vuota.
+ */
 export function firstRowKey(rows) {
-    return rows[0]?.key ?? null;
+    return (rows.find((r) => r.kind === 'hit') ?? rows[0])?.key ?? null;
 }
 /** Indice della riga con quella chiave; -1 se assente. */
 export function rowIndexOfKey(rows, key) {

package/dist/task-edit.js

@@ -3,7 +3,7 @@
 // isolata in `writeTaskEdit`, così la grammatica delle sostituzioni è testabile
 // senza toccare il filesystem.
 import { readFileSync, writeFileSync } from 'node:fs';
-import { findTaskFile } from './tasks.js';
+import { TASK_ID_RE, findTaskFile } from './tasks.js';
 // Il task file scrive la priorità per NOME (`- **Priority**: Med`), tasks.md la
 // scrive come GLIFO (colonna Pri). Due rappresentazioni dello stesso valore →
 // due mappe, entrambe keyed sul nome canonico di view.ts (unica fonte del rango).
@@ -81,11 +81,11 @@ export function initialDetail(current, prog, date = today()) {
  * restano i token grezzi originali: nessun re-flow della tabella, il diff resta
  * di una riga. `ok:false` = id assente → il chiamante non scrive nulla.
  *
- * L'id deve rispettare `^T\d+$`, stesso gate di `parseTasks`: senza, un id
- * arbitrario matcherebbe la riga di HEADER (`| ID | Pri | K | Prog |`) o quella
- * di separatore, riscrivendone le celle e sfondando la tabella.
+ * L'id deve rispettare `TASK_ID_RE` (importato da tasks.ts — stesso gate di
+ * `parseTasks`, non una copia): senza, un id arbitrario matcherebbe la riga di
+ * HEADER (`| ID | Pri | K | Prog |`) o quella di separatore, riscrivendone le
+ * celle e sfondando la tabella.
  */
-const TASK_ID_RE = /^T\d+$/;
 export function updateTasksMdRow(content, id, priGlyph, progGlyph) {
     if (!TASK_ID_RE.test(id))
         return { content, ok: false };

package/dist/tasks.js

@@ -1,6 +1,13 @@
 import { readFileSync, readdirSync } from 'node:fs';
 import { dirname, join } from 'node:path';
 import { normalizeEmoji } from './viewport.js';
+/**
+ * Forma di un ID task: `T` (code) o `D` (doc) + numero. FONTE UNICA del gate —
+ * `parseTasks` lo usa per scartare header/separatore della tabella, `task-edit`
+ * per non riscrivere per sbaglio quelle stesse righe. Tenerlo in un posto solo
+ * evita che i due gate divergano (uno accetterebbe righe che l'altro rifiuta).
+ */
+export const TASK_ID_RE = /^[TD]\d+$/;
 // D1 (preflight T20): default docs/tasks.md, override della docs-root via env
 // LOOM_DECK_DOCS_ROOT (es. questo progetto usa `runtime`). No auto-detect.
 export function resolveTasksPath(cwd = process.cwd()) {
@@ -13,9 +20,11 @@ export function resolveTasksDir(cwd = process.cwd()) {
     return join(dirname(resolveTasksPath(cwd)), 'tasks');
 }
 // Estrae le righe `| Tnn | Pri | K | Prog | Task |` della Tasks Overview.
-// Il prefisso task è `T` (contratto plugin); le doc-task `D{N}` e le righe
-// header/separatore non matchano `^T\d+$` → scartate. deck-run agisce solo
-// su task T (run-task), quindi le D non hanno azione qui.
+// Due prefissi ammessi (contratto plugin, counter separati): `T` = code task,
+// `D` = doc task. Le D entrano in lista come le T perché `deck-run` NON inietta
+// `run-task`: il prompt iniziale è un recap diretto ("recap stato task <id>"),
+// valido identico su una doc task. Righe header/separatore non matchano `^[TD]\d+$`
+// → scartate.
 export function parseTasks(content) {
     const tasks = [];
     for (const line of content.split('\n')) {
@@ -25,7 +34,7 @@ export function parseTasks(content) {
         const cells = t.split('|').map((c) => c.trim());
         // cells[0] = '' (prima del primo |), cells[last] = '' (dopo l'ultimo |)
         const id = cells[1];
-        if (!/^T\d+$/.test(id))
+        if (!TASK_ID_RE.test(id))
             continue;
         // Colonne overview: | ID | Pri | K | Prog | Task | → cells[2]=Pri (icona
         // priorità), cells[4]=Prog. K (Kind, cells[3]) non serve al deck.
@@ -77,7 +86,10 @@ export function parseTaskDetail(id, content) {
     let inDesc = false;
     for (const line of content.split('\n')) {
         if (!title && line.startsWith('# ')) {
-            title = line.replace(/^#\s+/, '').replace(/^Task:\s*/, '').trim();
+            // I due template scrivono H1 diversi — `# Task: …` (code) e
+            // `# Doc Task: …` (doc): entrambi i cappelli vanno via, il titolo mostrato
+            // è la descrizione, non la sua categoria (già data dall'id).
+            title = line.replace(/^#\s+/, '').replace(/^(?:Doc\s+)?Task:\s*/, '').trim();
             continue;
         }
         if (line.startsWith('## ')) {

package/dist/view.js

@@ -53,11 +53,16 @@ export function progRank(glyph) {
     return PROG_TABLE.find((e) => e.glyph === g)?.rank ?? UNKNOWN_RANK;
 }
 // `T10`.localeCompare(`T9`) mette T10 prima: l'ID va confrontato NUMERICO.
-// parseTasks ammette solo /^T\d+$/, ma un id fuori forma non deve far esplodere
-// il comparator → finisce in coda con Number.MAX_SAFE_INTEGER.
+// parseTasks ammette due prefissi con counter SEPARATI (`T` code, `D` doc) →
+// il solo numero non basta, T01 e D01 collidono. Il prefisso pesa quindi come
+// cifra più significativa (T prima di D, blocco doc in coda), il numero come
+// meno significativa: il rango resta un intero singolo, quindi il comparator
+// della chain non cambia forma. Il gap 1e6 è oltre qualunque counter reale.
+// Un id fuori forma non deve far esplodere il comparator → coda con MAX_SAFE.
+const ID_PREFIX_RANK = { T: 0, D: 1 };
 export function idNum(id) {
-    const m = /^T(\d+)$/.exec(id);
-    return m ? Number(m[1]) : Number.MAX_SAFE_INTEGER;
+    const m = /^([TD])(\d+)$/.exec(id);
+    return m ? ID_PREFIX_RANK[m[1]] * 1_000_000 + Number(m[2]) : Number.MAX_SAFE_INTEGER;
 }
 function rankOf(task, key) {
     if (key === 'pri')

package/dist/viewport.js

@@ -202,6 +202,24 @@ const READER_CHROME = 8;
 export function readerCapacity(rows) {
     return Math.max(0, (rows || 24) - SLACK - READER_CHROME);
 }
+// T52 — cornice del pannello di anteprima sotto la lista occorrenze:
+// marginTop + 2 bordi + riga meta.
+const SEARCH_PREVIEW_CHROME = 4;
+/**
+ * Righe di contesto concesse all'anteprima dell'occorrenza selezionata.
+ *
+ * Prende SOLO ciò che avanza: la lista si dimensiona sul contenuto e, quando i
+ * risultati sono pochi, il resto del terminale resterebbe vuoto. Con molti
+ * risultati lo spazio torna alla lista e il pannello sparisce da sé — la
+ * priorità è vedere quante più occorrenze possibile, il contesto è il premio
+ * per una ricerca già stretta.
+ *
+ * Restituisce 0 quando non c'è spazio nemmeno per una riga utile: un pannello
+ * di sola cornice ruberebbe 4 righe per non mostrare nulla.
+ */
+export function searchPreviewCapacity(capacity, listRows) {
+    return Math.max(0, capacity - listRows - SEARCH_PREVIEW_CHROME);
+}
 /**
  * Il terminale non ospita nemmeno la cornice della schermata: va sostituita da
  * una riga singola, come fa `Budget.compact` per il deck.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lamemind/loom-deck",
-  "version": "0.14.0",
+  "version": "0.16.0",
   "description": "Deck TUI Ink per-progetto della famiglia loom: legge tasks.md e spawna sessioni Claude Code bound via LOOM_TASK",
   "type": "module",
   "bin": {