From c3f8abd87ed58ba3b21bd190bf753e7af4a33879 Mon Sep 17 00:00:00 2001
From: Bobby Quantum <bobby@quantum.observer>
Date: Thu, 3 Sep 2026 23:11:59 +0100
Subject: [PATCH 1/4] feat(home): sort projects by updated, created, or title

Add a sort menu to the home header so writers can order the project
grid by recently updated (default), recently created, or title. Shared
projects are now interleaved with owned projects instead of appended.
The choice is persisted in localStorage.
---
 frontend/public/assets/i18n/en/home.json      |  6 ++
 .../src/app/pages/home/home.component.html    | 28 ++++++
 .../src/app/pages/home/home.component.scss    |  8 ++
 .../src/app/pages/home/home.component.spec.ts | 86 ++++++++++++++++++-
 frontend/src/app/pages/home/home.component.ts | 74 +++++++++++++++-
 5 files changed, 199 insertions(+), 3 deletions(-)

diff --git a/frontend/public/assets/i18n/en/home.json b/frontend/public/assets/i18n/en/home.json
index f1dfbf2f3..4f9c3a1f2 100644
--- a/frontend/public/assets/i18n/en/home.json
+++ b/frontend/public/assets/i18n/en/home.json
@@ -30,6 +30,12 @@
   "activateAction": "Download to this device",
   "deleteAction": "Delete project",
   "cancelSyncTooltip": "Cancel sync ({{progress}}% complete)",
+  "sort": {
+    "tooltip": "Sort projects",
+    "updated": "Recently updated",
+    "created": "Recently created",
+    "title": "Title (A–Z)"
+  },
   "tooltips": {
     "onlineOnly": "Only available in online mode",
     "offline": "Cannot sync while offline",
diff --git a/frontend/src/app/pages/home/home.component.html b/frontend/src/app/pages/home/home.component.html
index 495e66b4b..b24c6dac5 100644
--- a/frontend/src/app/pages/home/home.component.html
+++ b/frontend/src/app/pages/home/home.component.html
@@ -152,6 +152,34 @@
               }
 
               @if (isAuthenticated()) {
+                <button
+                  mat-icon-button
+                  [matMenuTriggerFor]="sortMenu"
+                  [matTooltip]="'home.sort.tooltip' | transloco"
+                  [attr.aria-label]="'home.sort.tooltip' | transloco"
+                  data-testid="sort-projects-button"
+                  class="sort-btn">
+                  <mat-icon>sort</mat-icon>
+                </button>
+                <mat-menu #sortMenu="matMenu">
+                  @for (order of sortOrders; track order) {
+                    <button
+                      mat-menu-item
+                      (click)="setSortOrder(order)"
+                      [class.active]="sortOrder() === order"
+                      [attr.aria-checked]="sortOrder() === order"
+                      role="menuitemradio"
+                      [attr.data-testid]="'sort-projects-' + order">
+                      <mat-icon>{{
+                        sortOrder() === order
+                          ? 'radio_button_checked'
+                          : 'radio_button_unchecked'
+                      }}</mat-icon>
+                      <span>{{ 'home.sort.' + order | transloco }}</span>
+                    </button>
+                  }
+                </mat-menu>
+
                 <button
                   mat-button
                   [matMenuTriggerFor]="createMenu"
diff --git a/frontend/src/app/pages/home/home.component.scss b/frontend/src/app/pages/home/home.component.scss
index 1e5f18f24..3660c5025 100644
--- a/frontend/src/app/pages/home/home.component.scss
+++ b/frontend/src/app/pages/home/home.component.scss
@@ -282,6 +282,14 @@
     }
   }
 
+  .sort-btn {
+    color: var(--link-color) !important;
+
+    &:hover {
+      color: var(--link-hover-color) !important;
+    }
+  }
+
   .sync-btn {
     font-weight: 500;
     color: var(--link-color) !important;
diff --git a/frontend/src/app/pages/home/home.component.spec.ts b/frontend/src/app/pages/home/home.component.spec.ts
index 924c3f962..4dda92ce2 100644
--- a/frontend/src/app/pages/home/home.component.spec.ts
+++ b/frontend/src/app/pages/home/home.component.spec.ts
@@ -47,7 +47,7 @@ import {
 } from 'vitest';
 
 import { translocoTestProvider } from '../../../testing/transloco-test-provider';
-import { HomeComponent } from './home.component';
+import { HomeComponent, PROJECT_SORT_STORAGE_KEY } from './home.component';
 
 describe('HomeComponent', () => {
   let component: HomeComponent;
@@ -332,6 +332,7 @@ describe('HomeComponent', () => {
     fixture.destroy();
     vi.restoreAllMocks();
     vi.useRealTimers();
+    localStorage.removeItem(PROJECT_SORT_STORAGE_KEY);
   });
 
   it('should create', () => {
@@ -558,6 +559,89 @@ describe('HomeComponent', () => {
     });
   });
 
+  describe('project sort order', () => {
+    const sortableProjects: Project[] = [
+      {
+        id: 'a',
+        title: 'Zeta',
+        slug: 'zeta',
+        username: 'testuser',
+        createdDate: '2024-03-01T00:00:00.000Z',
+        updatedDate: '2024-01-10T00:00:00.000Z',
+      },
+      {
+        id: 'b',
+        title: 'alpha',
+        slug: 'alpha',
+        username: 'testuser',
+        createdDate: '2024-01-01T00:00:00.000Z',
+        updatedDate: '2024-02-10T00:00:00.000Z',
+      },
+      {
+        id: 'c',
+        title: 'Mid',
+        slug: 'mid',
+        username: 'testuser',
+        createdDate: '2024-02-01T00:00:00.000Z',
+        updatedDate: '2024-03-10T00:00:00.000Z',
+      },
+    ];
+
+    const ids = () => component['allProjects']().map(i => i.project.id);
+
+    it('should default to most recently updated first', () => {
+      mockProjectsSignal.set(sortableProjects);
+      expect(component.sortOrder()).toBe('updated');
+      expect(ids()).toEqual(['c', 'b', 'a']);
+    });
+
+    it('should sort by created date descending', () => {
+      mockProjectsSignal.set(sortableProjects);
+      component.setSortOrder('created');
+      expect(ids()).toEqual(['a', 'c', 'b']);
+    });
+
+    it('should sort by title case-insensitively', () => {
+      mockProjectsSignal.set(sortableProjects);
+      component.setSortOrder('title');
+      expect(ids()).toEqual(['b', 'c', 'a']);
+    });
+
+    it('should interleave shared projects according to the sort order', () => {
+      mockProjectsSignal.set(sortableProjects);
+      component.collaboratedProjects.set([
+        {
+          projectId: 'shared',
+          projectSlug: 'shared',
+          projectTitle: 'Shared Story',
+          ownerUsername: 'owner',
+          role: 'editor',
+          acceptedAt: '2024-02-20T00:00:00.000Z',
+        } as unknown as CollaboratedProject,
+      ]);
+      expect(ids()).toEqual(['c', 'shared', 'b', 'a']);
+    });
+
+    it('should persist the chosen order to localStorage', () => {
+      component.setSortOrder('title');
+      expect(localStorage.getItem(PROJECT_SORT_STORAGE_KEY)).toBe('title');
+    });
+
+    it('should restore a stored order on creation', () => {
+      localStorage.setItem(PROJECT_SORT_STORAGE_KEY, 'created');
+      const freshFixture = TestBed.createComponent(HomeComponent);
+      expect(freshFixture.componentInstance.sortOrder()).toBe('created');
+      freshFixture.destroy();
+    });
+
+    it('should ignore an unknown stored order', () => {
+      localStorage.setItem(PROJECT_SORT_STORAGE_KEY, 'bogus');
+      const freshFixture = TestBed.createComponent(HomeComponent);
+      expect(freshFixture.componentInstance.sortOrder()).toBe('updated');
+      freshFixture.destroy();
+    });
+  });
+
   describe('login and register dialogs', () => {
     it('should open login dialog', () => {
       // openLoginDialog is now available instead of navigateToLogin
diff --git a/frontend/src/app/pages/home/home.component.ts b/frontend/src/app/pages/home/home.component.ts
index e3cec80ee..bbcf6281a 100644
--- a/frontend/src/app/pages/home/home.component.ts
+++ b/frontend/src/app/pages/home/home.component.ts
@@ -65,6 +65,18 @@ interface HomeSearchFormValue {
   search: string;
 }
 
+/** Orderings available for the home page project grid. */
+export type ProjectSortOrder = 'updated' | 'created' | 'title';
+
+const PROJECT_SORT_ORDERS: readonly ProjectSortOrder[] = [
+  'updated',
+  'created',
+  'title',
+];
+
+/** localStorage key holding the user's preferred project ordering. */
+export const PROJECT_SORT_STORAGE_KEY = 'inkweld-home-project-sort';
+
 @Component({
   selector: 'app-home',
   imports: [
@@ -127,6 +139,12 @@ export class HomeComponent implements OnInit, OnDestroy {
 
   readonly searchModel = signal<HomeSearchFormValue>({ search: '' });
 
+  /** Sort orders offered in the header menu, in display order. */
+  readonly sortOrders = PROJECT_SORT_ORDERS;
+
+  /** Current project ordering, restored from localStorage on creation. */
+  readonly sortOrder = signal<ProjectSortOrder>(readStoredSortOrder());
+
   readonly searchForm = form(this.searchModel, schemaPath => {
     debounce(schemaPath.search, 300);
   });
@@ -209,8 +227,11 @@ export class HomeComponent implements OnInit, OnDestroy {
       sharedByUsername: cp.ownerUsername,
     }));
 
-    // Combine both lists
-    const combined = [...unifiedOwn, ...unifiedShared];
+    // Combine both lists and apply the user's preferred ordering
+    const combined = sortProjectItems(
+      [...unifiedOwn, ...unifiedShared],
+      this.sortOrder()
+    );
 
     // Apply search filter if there's a search term
     if (!term) {
@@ -228,6 +249,17 @@ export class HomeComponent implements OnInit, OnDestroy {
     });
   });
 
+  /** Change the project ordering and remember it for future visits. */
+  setSortOrder(order: ProjectSortOrder): void {
+    this.sortOrder.set(order);
+    try {
+      localStorage.setItem(PROJECT_SORT_STORAGE_KEY, order);
+    } catch {
+      // Storage may be unavailable (private mode, quota); the in-memory
+      // signal still applies for this session.
+    }
+  }
+
   // Keep filteredProjects for side-nav compatibility (owned projects only)
   protected filteredProjects = computed(() => {
     const term = this.searchTerm().toLowerCase();
@@ -976,3 +1008,41 @@ export class HomeComponent implements OnInit, OnDestroy {
     this.destroy$.complete();
   }
 }
+
+function readStoredSortOrder(): ProjectSortOrder {
+  try {
+    const stored = localStorage.getItem(PROJECT_SORT_STORAGE_KEY);
+    if (stored && (PROJECT_SORT_ORDERS as readonly string[]).includes(stored)) {
+      return stored as ProjectSortOrder;
+    }
+  } catch {
+    // Fall through to the default when storage is unavailable
+  }
+  return 'updated';
+}
+
+function toTimestamp(value: string | null | undefined): number {
+  if (!value) return 0;
+  const ms = new Date(value).getTime();
+  return Number.isNaN(ms) ? 0 : ms;
+}
+
+/**
+ * Return a new array of project items ordered per `order`. Ties fall back to
+ * title so the result is stable and predictable regardless of input order.
+ */
+function sortProjectItems<T extends { project: Project }>(
+  items: T[],
+  order: ProjectSortOrder
+): T[] {
+  const byTitle = (a: T, b: T) =>
+    a.project.title.localeCompare(b.project.title, undefined, {
+      sensitivity: 'base',
+    });
+  return [...items].sort((a, b) => {
+    if (order === 'title') return byTitle(a, b);
+    const key = order === 'created' ? 'createdDate' : 'updatedDate';
+    const diff = toTimestamp(b.project[key]) - toTimestamp(a.project[key]);
+    return diff !== 0 ? diff : byTitle(a, b);
+  });
+}

From d5afba159c1b2b7b02d7109ba0aced3f50bc8925 Mon Sep 17 00:00:00 2001
From: Bobby Quantum <bobby@quantum.observer>
Date: Thu, 3 Sep 2026 23:30:37 +0100
Subject: [PATCH 2/4] test(home): cover sort storage failures and invalid dates

---
 .../src/app/pages/home/home.component.spec.ts | 50 +++++++++++++++++++
 1 file changed, 50 insertions(+)

diff --git a/frontend/src/app/pages/home/home.component.spec.ts b/frontend/src/app/pages/home/home.component.spec.ts
index 4dda92ce2..61fa7783f 100644
--- a/frontend/src/app/pages/home/home.component.spec.ts
+++ b/frontend/src/app/pages/home/home.component.spec.ts
@@ -640,6 +640,56 @@ describe('HomeComponent', () => {
       expect(freshFixture.componentInstance.sortOrder()).toBe('updated');
       freshFixture.destroy();
     });
+
+    it('should fall back to the default when reading storage throws', () => {
+      vi.spyOn(Storage.prototype, 'getItem').mockImplementation(() => {
+        throw new Error('storage unavailable');
+      });
+      const freshFixture = TestBed.createComponent(HomeComponent);
+      expect(freshFixture.componentInstance.sortOrder()).toBe('updated');
+      freshFixture.destroy();
+    });
+
+    it('should still apply the order in memory when writing storage throws', () => {
+      vi.spyOn(Storage.prototype, 'setItem').mockImplementation(() => {
+        throw new Error('quota exceeded');
+      });
+      expect(() => component.setSortOrder('title')).not.toThrow();
+      expect(component.sortOrder()).toBe('title');
+    });
+
+    it('should treat missing or invalid dates as oldest', () => {
+      mockProjectsSignal.set([
+        {
+          id: 'valid',
+          title: 'Valid',
+          slug: 'valid',
+          username: 'testuser',
+          createdDate: '2024-01-01T00:00:00.000Z',
+          updatedDate: '2024-01-01T00:00:00.000Z',
+        },
+        {
+          id: 'invalid',
+          title: 'Invalid',
+          slug: 'invalid',
+          username: 'testuser',
+          createdDate: 'not-a-date',
+          updatedDate: 'not-a-date',
+        },
+        {
+          id: 'missing',
+          title: 'Missing',
+          slug: 'missing',
+          username: 'testuser',
+          createdDate: undefined as unknown as string,
+          updatedDate: undefined as unknown as string,
+        },
+      ]);
+      // Valid date first; the two zero-timestamp entries tie and fall back to title
+      expect(ids()).toEqual(['valid', 'invalid', 'missing']);
+      component.setSortOrder('created');
+      expect(ids()).toEqual(['valid', 'invalid', 'missing']);
+    });
   });
 
   describe('login and register dialogs', () => {

From 56ed261e260dc04789119d24758d23539d18a0be Mon Sep 17 00:00:00 2001
From: Bobby Quantum <bobby@quantum.observer>
Date: Thu, 3 Sep 2026 23:48:08 +0100
Subject: [PATCH 3/4] fix(ci): drop phantom branch records when merging sharded
 lcov

V8 numbers branch blocks per process, so shards that never executed a
file report its branches under different block ids than the shard that
did. Summing them invented zero-hit branches and halved SonarCloud's
new-code condition coverage. Skip BRDA entries from records with no
line hits.
---
 frontend/scripts/merge-lcov.mjs | 35 ++++++++++++++++++++++++++++++---
 1 file changed, 32 insertions(+), 3 deletions(-)

diff --git a/frontend/scripts/merge-lcov.mjs b/frontend/scripts/merge-lcov.mjs
index 6b1c0cd26..ec8865530 100644
--- a/frontend/scripts/merge-lcov.mjs
+++ b/frontend/scripts/merge-lcov.mjs
@@ -9,6 +9,13 @@
  * by line, function name and branch id. Thresholds mirror
  * `coverageThresholds` in angular.json and are checked on the merged totals,
  * which is what the unsharded `ng test` run would have enforced.
+ *
+ * Branch records need one caveat: V8 numbers branch blocks per process, so a
+ * shard that never executed a file reports that file's branches under
+ * different block ids than the shard that did. Summing those naively invents
+ * phantom zero-hit branches (SonarCloud then sees twice the conditions, half
+ * uncovered). A shard that recorded no line hits for a file cannot have
+ * covered any of its branches either, so its BRDA entries are dropped.
  */
 import { readFileSync, writeFileSync, mkdirSync } from 'node:fs';
 import { dirname } from 'node:path';
@@ -49,13 +56,33 @@ function fileRecord(name) {
 
 const num = value => (value === '-' ? 0 : Number(value));
 
+/** Fold one file record's pending branch entries into the merged record. */
+function flushBranches(current, pending, executed) {
+  if (!executed) return;
+  for (const [id, entry] of pending) {
+    const existing = current.branches.get(id);
+    if (existing) {
+      existing.hits += entry.hits;
+    } else {
+      current.branches.set(id, entry);
+    }
+  }
+}
+
 for (const input of inputs) {
   let current = null;
+  /** BRDA entries for the record being read, applied at end_of_record. */
+  let pendingBranches = new Map();
+  /** Whether the record being read had any line hits. */
+  let executed = false;
   for (const raw of readFileSync(input, 'utf8').split('\n')) {
     const line = raw.trim();
     if (!line) continue;
     if (line === 'end_of_record') {
+      if (current) flushBranches(current, pendingBranches, executed);
       current = null;
+      pendingBranches = new Map();
+      executed = false;
       continue;
     }
     const sep = line.indexOf(':');
@@ -85,17 +112,19 @@ for (const input of inputs) {
       case 'DA': {
         const [lineNo, hits] = value.split(',');
         const n = Number(lineNo);
-        current.lines.set(n, (current.lines.get(n) ?? 0) + num(hits));
+        const h = num(hits);
+        if (h > 0) executed = true;
+        current.lines.set(n, (current.lines.get(n) ?? 0) + h);
         break;
       }
       case 'BRDA': {
         const [lineNo, block, branch, hits] = value.split(',');
         const id = `${lineNo},${block},${branch}`;
-        const existing = current.branches.get(id);
+        const existing = pendingBranches.get(id);
         if (existing) {
           existing.hits += num(hits);
         } else {
-          current.branches.set(id, {
+          pendingBranches.set(id, {
             line: Number(lineNo),
             block,
             branch,

From 8003d5547712de7a98187cc2101ac56e6d498031 Mon Sep 17 00:00:00 2001
From: Bobby Quantum <bobby@quantum.observer>
Date: Fri, 4 Sep 2026 00:07:11 +0100
Subject: [PATCH 4/4] fix(ci): merge sharded lcov branches positionally per
 line

Shards that only import a file still record module-level line hits, so
skipping branch records from zero-hit shards was not enough. Match
branch entries on the same line by sorted position instead of by V8
block id, which differs between processes.
---
 frontend/scripts/merge-lcov.mjs | 87 ++++++++++++++++++---------------
 1 file changed, 48 insertions(+), 39 deletions(-)

diff --git a/frontend/scripts/merge-lcov.mjs b/frontend/scripts/merge-lcov.mjs
index ec8865530..279d34a2d 100644
--- a/frontend/scripts/merge-lcov.mjs
+++ b/frontend/scripts/merge-lcov.mjs
@@ -11,11 +11,12 @@
  * which is what the unsharded `ng test` run would have enforced.
  *
  * Branch records need one caveat: V8 numbers branch blocks per process, so a
- * shard that never executed a file reports that file's branches under
- * different block ids than the shard that did. Summing those naively invents
- * phantom zero-hit branches (SonarCloud then sees twice the conditions, half
- * uncovered). A shard that recorded no line hits for a file cannot have
- * covered any of its branches either, so its BRDA entries are dropped.
+ * shard that merely imported a file reports its branches under different
+ * block ids than the shard that exercised it. Keying on block id would then
+ * invent phantom zero-hit branches (SonarCloud sees twice the conditions,
+ * half uncovered). Branches are therefore merged positionally per source
+ * line: each record's entries for a line are sorted by (block, branch) and
+ * summed index-by-index, which is stable across processes.
  */
 import { readFileSync, writeFileSync, mkdirSync } from 'node:fs';
 import { dirname } from 'node:path';
@@ -37,7 +38,7 @@ if (inputs.length === 0) {
   process.exit(2);
 }
 
-/** @type {Map<string, {fnLines: Map<string, number>, fnHits: Map<string, number>, lines: Map<number, number>, branches: Map<string, {line: number, block: string, branch: string, hits: number}>}>} */
+/** @type {Map<string, {fnLines: Map<string, number>, fnHits: Map<string, number>, lines: Map<number, number>, branches: Map<number, {block: string, branch: string, hits: number}[]>}>} */
 const files = new Map();
 
 function fileRecord(name) {
@@ -56,33 +57,42 @@ function fileRecord(name) {
 
 const num = value => (value === '-' ? 0 : Number(value));
 
-/** Fold one file record's pending branch entries into the merged record. */
-function flushBranches(current, pending, executed) {
-  if (!executed) return;
-  for (const [id, entry] of pending) {
-    const existing = current.branches.get(id);
-    if (existing) {
-      existing.hits += entry.hits;
-    } else {
-      current.branches.set(id, entry);
+const byBlockThenBranch = (a, b) =>
+  Number(a.block) - Number(b.block) || Number(a.branch) - Number(b.branch);
+
+/**
+ * Fold one file record's branch entries into the merged record, matching
+ * entries on the same line by position rather than by V8 block id.
+ */
+function flushBranches(current, pending) {
+  for (const [lineNo, entries] of pending) {
+    entries.sort(byBlockThenBranch);
+    const merged = current.branches.get(lineNo);
+    if (!merged) {
+      current.branches.set(lineNo, entries);
+      continue;
     }
+    entries.forEach((entry, i) => {
+      if (i < merged.length) {
+        merged[i].hits += entry.hits;
+      } else {
+        merged.push(entry);
+      }
+    });
   }
 }
 
 for (const input of inputs) {
   let current = null;
-  /** BRDA entries for the record being read, applied at end_of_record. */
+  /** BRDA entries for the record being read, grouped by line. */
   let pendingBranches = new Map();
-  /** Whether the record being read had any line hits. */
-  let executed = false;
   for (const raw of readFileSync(input, 'utf8').split('\n')) {
     const line = raw.trim();
     if (!line) continue;
     if (line === 'end_of_record') {
-      if (current) flushBranches(current, pendingBranches, executed);
+      if (current) flushBranches(current, pendingBranches);
       current = null;
       pendingBranches = new Map();
-      executed = false;
       continue;
     }
     const sep = line.indexOf(':');
@@ -112,25 +122,18 @@ for (const input of inputs) {
       case 'DA': {
         const [lineNo, hits] = value.split(',');
         const n = Number(lineNo);
-        const h = num(hits);
-        if (h > 0) executed = true;
-        current.lines.set(n, (current.lines.get(n) ?? 0) + h);
+        current.lines.set(n, (current.lines.get(n) ?? 0) + num(hits));
         break;
       }
       case 'BRDA': {
         const [lineNo, block, branch, hits] = value.split(',');
-        const id = `${lineNo},${block},${branch}`;
-        const existing = pendingBranches.get(id);
-        if (existing) {
-          existing.hits += num(hits);
-        } else {
-          pendingBranches.set(id, {
-            line: Number(lineNo),
-            block,
-            branch,
-            hits: num(hits),
-          });
+        const n = Number(lineNo);
+        let entries = pendingBranches.get(n);
+        if (!entries) {
+          entries = [];
+          pendingBranches.set(n, entries);
         }
+        entries.push({ block, branch, hits: num(hits) });
         break;
       }
       default:
@@ -169,13 +172,19 @@ for (const [name, rec] of [...files.entries()].sort(([a], [b]) =>
   totals.lines[0] += rec.lines.size;
   totals.lines[1] += lineHit;
 
+  let brFound = 0;
   let brHit = 0;
-  for (const br of rec.branches.values()) {
-    if (br.hits > 0) brHit++;
-    out.push(`BRDA:${br.line},${br.block},${br.branch},${br.hits}`);
+  for (const [lineNo, entries] of [...rec.branches.entries()].sort(
+    (a, b) => a[0] - b[0]
+  )) {
+    for (const br of entries) {
+      brFound++;
+      if (br.hits > 0) brHit++;
+      out.push(`BRDA:${lineNo},${br.block},${br.branch},${br.hits}`);
+    }
   }
-  out.push(`BRF:${rec.branches.size}`, `BRH:${brHit}`);
-  totals.branches[0] += rec.branches.size;
+  out.push(`BRF:${brFound}`, `BRH:${brHit}`);
+  totals.branches[0] += brFound;
   totals.branches[1] += brHit;
 
   out.push('end_of_record');