From 68d51b341bccc72c7b01f547e43ce90a76729244 Mon Sep 17 00:00:00 2001
From: Craig Jennings <c@cjennings.net>
Date: Tue, 2 Jun 2026 23:38:30 -0500
Subject: feat(render): collapse the #+ preamble to a styled summary line
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The ~9-line #+ keyword block atop every Linear file is now hidden behind a display overlay showing one line: "Pearl - <view> · <count> · <time>", styled large and goldenrod via the new pearl-preamble-summary face. It leads with "Pearl" so it doubles as the buffer's identity marker, the thing that tells you you're in a Pearl buffer and not just another org file. A pearl-hide-preamble defcustom (default t) turns it off for the raw keywords.

The overlay only governs display: the #+ text stays in the buffer, so #+LINEAR-SOURCE parsing, the merge rewrites of the RUN-AT / COUNT / TRUNCATED lines, and refresh all keep working untouched. The summary is composed from those same #+ values, so it stays accurate across merges. It re-applies idempotently on pearl-mode enable and after every render, refresh, and merge, so reopening a file hides it the same way a fresh fetch does.

With the summary now carrying identity, the folded help heading reverts from "* Pearl" back to the descriptive "* Pearl Help".
---
 tests/test-pearl-output.el | 63 +++++++++++++++++++++++++++++++++++++++++++---
 1 file changed, 60 insertions(+), 3 deletions(-)

(limited to 'tests')

diff --git a/tests/test-pearl-output.el b/tests/test-pearl-output.el
index 7edc29d..8b02fcb 100644
--- a/tests/test-pearl-output.el
+++ b/tests/test-pearl-output.el
@@ -53,7 +53,7 @@
     (should (string-match-p "^#\\+LINEAR-COUNT: 0$" out))
     ;; the help header (default on) carries the cues now; the raw `#' affordance
     ;; comments are gone
-    (should (string-match-p "^\\* Pearl$" out))
+    (should (string-match-p "^\\* Pearl Help$" out))
     (should-not (string-match-p "^# " out))))
 
 (ert-deftest test-pearl-build-org-content-source-roundtrips ()
@@ -89,7 +89,7 @@ independent of `pearl-title-case-headings' (which governs issue headings only)."
 edit-then-save reminder, key cues, the priority legend, and how to hide it.
 It has no LINEAR-ID, so save and merge skip it."
   (let ((s (pearl--help-header-string)))
-    (should (string-match-p "^\\* Pearl$" s))
+    (should (string-match-p "^\\* Pearl Help$" s))
     (should (string-match-p "^:VISIBILITY: folded$" s))
     (should (string-match-p "save" s))                ; edit-then-save / key cue
     (should (string-match-p "\\[#A\\] Urgent" s))     ; priority legend ends...
@@ -113,7 +113,7 @@ instead of printing a bogus chord."
 raw `#' affordance comments are not."
   (let* ((pearl-help-header t)
          (out (pearl--build-org-content '() '(:type filter :name "X" :filter nil))))
-    (should (string-match-p "^\\* Pearl$" out))
+    (should (string-match-p "^\\* Pearl Help$" out))
     (should (string-match-p "^:VISIBILITY: folded$" out))
     (should-not (string-match-p "^# " out))))
 
@@ -126,6 +126,63 @@ appear -- a minimal preamble of just the machine keywords."
     (should-not (string-match-p "^# " out))
     (should (string-match-p "^#\\+title:" out))))
 
+;;; --hide-preamble overlay (`pearl-hide-preamble')
+
+(defun test-pearl-output--sample-content ()
+  "Render a sample Linear buffer string for the overlay tests."
+  (pearl--build-org-content
+   '((:id "i1" :identifier "ENG-1" :title "one" :priority 1
+      :state (:name "In Progress") :team (:id "t1")))
+   '(:type filter :name "My open work" :filter (:assignee :me :open t))))
+
+(ert-deftest test-pearl-preamble-summary-face-defined ()
+  "The summary face exists for styling the collapsed preamble."
+  (should (facep 'pearl-preamble-summary)))
+
+(ert-deftest test-pearl-preamble-region-spans-keywords ()
+  "`pearl--preamble-region' covers point-min through the first heading."
+  (with-temp-buffer
+    (insert (test-pearl-output--sample-content))
+    (org-mode)
+    (let ((region (pearl--preamble-region)))
+      (should region)
+      (should (= (car region) (point-min)))
+      (should (string-prefix-p "* " (buffer-substring-no-properties
+                                     (cdr region) (+ (cdr region) 2)))))))
+
+(ert-deftest test-pearl-preamble-summary-composes-fields ()
+  "The summary reads the view name, count, and run-at time from the buffer."
+  (with-temp-buffer
+    (insert (test-pearl-output--sample-content))
+    (org-mode)
+    (goto-char (point-min))
+    (let ((s (pearl--preamble-summary)))
+      (should (string-prefix-p "Pearl - My open work" s))
+      (should (string-match-p " · 1" s))          ; one rendered issue
+      (should (string-match-p "·" s)))))
+
+(ert-deftest test-pearl-hide-preamble-lays-one-tagged-overlay ()
+  "With the option on, one tagged display overlay covers the preamble; applying
+twice keeps exactly one (idempotent); off removes it.  Buffer text is untouched."
+  (cl-flet ((pearl-ovs () (seq-filter (lambda (o) (overlay-get o 'pearl-preamble))
+                                      (overlays-in (point-min) (point-max)))))
+    (let ((pearl-hide-preamble t))
+      (with-temp-buffer
+        (insert (test-pearl-output--sample-content))
+        (org-mode)
+        (let ((text-before (buffer-string)))
+          (pearl--hide-preamble)
+          (should (= 1 (length (pearl-ovs))))
+          (let ((ov (car (pearl-ovs))))
+            (should (overlay-get ov 'display))
+            (should (string-match-p "Pearl - My open work" (overlay-get ov 'display))))
+          (pearl--hide-preamble)                   ; idempotent
+          (should (= 1 (length (pearl-ovs))))
+          (should (string-equal text-before (buffer-string)))  ; text untouched
+          (let ((pearl-hide-preamble nil))         ; off removes it
+            (pearl--hide-preamble)
+            (should (= 0 (length (pearl-ovs))))))))))
+
 ;;; --read-active-source
 
 (ert-deftest test-pearl-read-active-source-absent ()
-- 
cgit v1.2.3