From 184b94538cdcc807aa382f2766beb0b615776e43 Mon Sep 17 00:00:00 2001
From: Craig Jennings <c@cjennings.net>
Date: Sat, 6 Jun 2026 15:17:51 -0500
Subject: feat(views): route grouping consumers through the effective-grouping
 resolver

Phase 4 of the interactive-grouping spec: the integration that makes an interactive grouping survive a refresh. The full render (pearl--build-org-content) and both merge-refresh paths (the dirty-merge branch and pearl--merge-query-result) read the source's grouping straight from :group. I pointed all three at pearl--effective-grouping instead, so a buffer the user grouped by hand redraws the same way rather than snapping back to the view's server grouping.

The swap is backward-compatible: with no :client-group set, the resolver returns :group, so a server-grouped view renders exactly as before. 2 render tests lock both directions: a :client-group overrides the server :group, and a server-only view still groups by :group.
---
 pearl.el                     |  6 +++---
 tests/test-pearl-grouping.el | 27 +++++++++++++++++++++++++++
 2 files changed, 30 insertions(+), 3 deletions(-)

diff --git a/pearl.el b/pearl.el
index 3c9e7d0..ed183dd 100644
--- a/pearl.el
+++ b/pearl.el
@@ -4250,7 +4250,7 @@ no side effects."
   (let* ((src (or source '(:type filter :name "Linear issues" :filter nil)))
          (name (pearl--source-name src))
          (filter (plist-get src :filter))
-         (grouping (plist-get src :group))
+         (grouping (pearl--effective-grouping src))
          (groups (pearl--group-issues issues grouping)))
     (with-temp-buffer
       ;; The view name renders verbatim, matching Linear's own capitalization;
@@ -4390,7 +4390,7 @@ just writing the file and leaving it off-screen."
         (?m                             ; merge by LINEAR-ID, keeping edits
          (with-current-buffer existing-buf
            (let ((counts (pearl--merge-issues-into-buffer
-                          issues (plist-get source :group))))
+                          issues (pearl--effective-grouping source))))
              (pearl--update-source-header (length issues) truncated)
              (pearl--update-derived-todo-header (pearl--gather-header-states issues))
              (pearl-highlight-comments)
@@ -6822,7 +6822,7 @@ of the replace path."
                      (cdr eff)))
             (truncated (pearl--query-result-truncated-p result))
             (counts (pearl--merge-issues-into-buffer
-                     issues (plist-get source :group))))
+                     issues (pearl--effective-grouping source))))
        (pearl--update-source-header (length issues) truncated)
        (pearl--update-derived-todo-header (pearl--gather-header-states issues))
        (pearl-highlight-comments)
diff --git a/tests/test-pearl-grouping.el b/tests/test-pearl-grouping.el
index 13a84d5..a30bcc1 100644
--- a/tests/test-pearl-grouping.el
+++ b/tests/test-pearl-grouping.el
@@ -327,5 +327,32 @@ SE-1 has a comment subtree; SE-2 has no assignee.")
                   'no-issues)))
     (should-not (plist-get (pearl--read-active-source) :client-group))))
 
+;;; render integration — consumers read pearl--effective-grouping (phase 4)
+
+(defconst test-pearl-grouping--issues
+  (list (list :id "i1" :identifier "SE-1" :title "Alpha"
+              :state '(:name "In Progress") :project '(:name "Apollo") :priority 2)
+        (list :id "i2" :identifier "SE-2" :title "Beta"
+              :state '(:name "Todo") :project '(:name "Apollo") :priority 1))
+  "Two normalized issues with distinct states, one shared project.")
+
+(ert-deftest test-pearl-build-org-content-client-group-overrides-server ()
+  "The full render groups by :client-group, overriding a view's server :group."
+  (let ((out (pearl--build-org-content
+              test-pearl-grouping--issues
+              '(:type view :name "V" :id "vid" :group "project"
+                :client-group "workflowState"))))
+    (should (string-match-p "^\\*\\* In Progress$" out))
+    (should (string-match-p "^\\*\\* Todo$" out))
+    (should-not (string-match-p "^\\*\\* Apollo$" out))))
+
+(ert-deftest test-pearl-build-org-content-server-group-when-no-client ()
+  "With no :client-group, the full render still honors the view's server :group."
+  (let ((out (pearl--build-org-content
+              test-pearl-grouping--issues
+              '(:type view :name "V" :id "vid" :group "project"))))
+    (should (string-match-p "^\\*\\* Apollo$" out))
+    (should-not (string-match-p "^\\*\\* In Progress$" out))))
+
 (provide 'test-pearl-grouping)
 ;;; test-pearl-grouping.el ends here
-- 
cgit v1.2.3