fix: keep tree hierarchies whole when filters or pagination split pages (WI-1317)

The tree built its hierarchy client-side from a flat server-paginated
page, so any item whose parent fell outside the loaded page rendered as
a stray root row. Toggling the completed filter reshuffled page
composition and flipped items between nested and detached rendering.

The tree now detects orphaned children and fills the gaps from a new
POST /v2/items/batch-ancestors endpoint that resolves many ancestor
chains in one recursive CTE under the /items/batch permission and
dedupe contract. Fetched chains are merged and expanded so previously
visible children stay visible, and pruned once a reload loads the
parent itself. Tree page size drops from 250 to 100 to bound the worst
case to a single batched request per page change.

Author: stefan-ernst

api/openapi-v2.json

@@ -270,6 +270,30 @@ export const items = {
     fetchV2Data(`/items/${itemId}/children`, requestOptions),
   getAncestors: (itemId, requestOptions = {}) =>
     fetchV2Data(`/items/${itemId}/ancestors`, requestOptions),
+  /**
+   * Fetch ancestor chains for many items in one (or a few) batch requests.
+   * Returns an array of { item_id, ancestors } entries — ancestors ordered
+   * root -> parent and excluding the item itself. Ids the caller can't view or
+   * that don't exist are silently omitted, matching getMany. Chunked under
+   * the server's 500-id cap.
+   */
+  getManyAncestors: async (ids = []) => {
+    const unique = [...new Set(ids)].filter((id) => id != null);
+    if (unique.length === 0) return [];
+    const chunks = [];
+    for (let i = 0; i < unique.length; i += ITEM_BATCH_CHUNK) {
+      chunks.push(unique.slice(i, i + ITEM_BATCH_CHUNK));
+    }
+    const results = await Promise.all(
+      chunks.map((chunk) =>
+        fetchV2Data('/items/batch-ancestors', {
+          method: 'POST',
+          body: JSON.stringify({ ids: chunk }),
+        })
+      )
+    );
+    return results.flat();
+  },
   getDescendants: (itemId, maxDepth = null) => {
     const params = maxDepth ? `?max_depth=${maxDepth}` : '';
     return fetchV2Data(`/items/${itemId}/descendants${params}`);

frontend/src/lib/api/items.js

@@ -19,19 +19,34 @@
   import { formatDate } from '../../utils/dateFormatter.js';
   import { moduleSettings } from '../../stores/moduleSettings.js';
   import { itemTestCaseLinksStore, workspaceDataStore } from '../../stores/index.js';
-  import { indexCollectionHierarchy } from './collectionHierarchy.js';
+  import {
+    findOrphansByMissingParent,
+    indexCollectionHierarchy,
+    mergeAncestorContext,
+  } from './collectionHierarchy.js';
 
   let { workspaceId, collectionId = null } = $props();
 
   let workspace = $derived(workspaceDataStore.workspace);
-  let allItems = $state([]);
+  // Items as loaded from the collection store, plus fetched ancestor context.
+  let storeItems = $state([]);
+  // Missing parent id -> ancestor chain (root -> parent). Fills gaps left by
+  // pagination and the completed filter so hierarchies stay whole.
+  let ancestorsByParent = $state({});
+  let ancestorsRequestInFlight = false;
+  let ancestorsRerunPending = false;
   let itemTypes = $derived(workspaceDataStore.itemTypes);
   let statuses = $derived(workspaceDataStore.statuses);
   let statusCategories = $derived(workspaceDataStore.statusCategories);
   let priorities = $derived(workspaceDataStore.priorities);
   let loading = $state(true);
   let currentCollectionName = $state('Default');
   let expandedItems = $state(new Set()); // Track which items are expanded
+  let allItems = $derived(
+    [...mergeAncestorContext(storeItems, ancestorsByParent)].sort(
+      (a, b) => a.level - b.level || a.id - b.id
+    )
+  );
   let hierarchyIndex = $derived(indexCollectionHierarchy(allItems));
   
   // Pagination state
@@ -63,20 +78,82 @@
     await loadData();
   });
 
-  // Sync items from central store
+  // Sync items from central store, then reset expansion to the all-roots
+  // default for the new page. Ancestors fetched later expand themselves in
+  // syncAncestorContext so their children stay visible.
   $effect(() => {
     if (!collectionStore.loading && collectionStore.items.length >= 0) {
       currentCollectionName = collectionStore.collectionName;
-      const sorted = [...collectionStore.items].sort((a, b) => a.level - b.level || a.id - b.id);
-      // untrack to avoid tracking reads of allItems/expandedItems via getRootItems/hasChildren
+      storeItems = [...collectionStore.items].sort((a, b) => a.level - b.level || a.id - b.id);
       untrack(() => {
-        allItems = sorted;
         const rootItems = getRootItems();
         expandedItems = new Set(rootItems.filter(i => hasChildren(i.id)).map(i => i.id));
       });
     }
   });
 
+  // Load ancestor chains for items whose parent is not on the loaded page so
+  // filtered or paginated children do not render as stray roots.
+  $effect(() => {
+    const items = storeItems;
+    untrack(() => void syncAncestorContext(items));
+  });
+
+  async function syncAncestorContext(items) {
+    const orphansByParent = findOrphansByMissingParent(items);
+    const neededParents = new Set(orphansByParent.keys());
+
+    // Drop cached chains whose gap the store has since filled itself.
+    const kept = {};
+    let pruned = false;
+    for (const [parentId, chain] of Object.entries(ancestorsByParent)) {
+      if (neededParents.has(Number(parentId))) {
+        kept[parentId] = chain;
+      } else {
+        pruned = true;
+      }
+    }
+    if (pruned) ancestorsByParent = kept;
+
+    const parentByOrphanId = new Map();
+    for (const [parentId, orphans] of orphansByParent) {
+      parentByOrphanId.set(orphans[0].id, parentId);
+    }
+    const orphanIds = [...parentByOrphanId.keys()].filter(
+      (orphanId) => !kept[String(parentByOrphanId.get(orphanId))]
+    );
+    if (orphanIds.length === 0) return;
+    if (ancestorsRequestInFlight) {
+      // A newer page may need different chains; rerun when the current
+      // request settles.
+      ancestorsRerunPending = true;
+      return;
+    }
+    ancestorsRequestInFlight = true;
+    try {
+      const entries = await api.items.getManyAncestors(orphanIds);
+      for (const { item_id: orphanId, ancestors } of entries) {
+        // The gap may have closed while the request was in flight.
+        const parentId = parentByOrphanId.get(orphanId);
+        if (!ancestors?.length || parentId == null || !neededParents.has(parentId)) continue;
+        ancestorsByParent = { ...ancestorsByParent, [String(parentId)]: ancestors };
+        // Keep previously visible children visible under their new parents.
+        for (const ancestor of ancestors) {
+          expandedItems.add(ancestor.id);
+        }
+      }
+      expandedItems = new Set(expandedItems);
+    } catch (error) {
+      console.error('[CollectionTree] Failed to load ancestor context:', error);
+    } finally {
+      ancestorsRequestInFlight = false;
+    }
+    if (ancestorsRerunPending) {
+      ancestorsRerunPending = false;
+      await syncAncestorContext(storeItems);
+    }
+  }
+
   async function loadData() {
     loading = true;
     if (workspaceId) {

frontend/src/lib/features/collections/CollectionTree.svelte

@@ -1,3 +1,44 @@
+/**
+ * Items whose parent is not part of the loaded set. Pagination and filters
+ * split hierarchies across pages, so a child can be loaded while its parent
+ * is not. Returns a map keyed by the missing parent id because one ancestor
+ * fetch per missing parent covers every orphan below it.
+ */
+export function findOrphansByMissingParent(items) {
+  const itemIds = new Set(items.map((item) => item.id));
+  const orphansByParent = new Map();
+  for (const item of items) {
+    if (item.parent_id == null || itemIds.has(item.parent_id)) continue;
+    const orphans = orphansByParent.get(item.parent_id);
+    if (orphans) {
+      orphans.push(item);
+    } else {
+      orphansByParent.set(item.parent_id, [item]);
+    }
+  }
+  return orphansByParent;
+}
+
+/**
+ * Adds fetched ancestor chains (root -> parent order) to the loaded items so
+ * hierarchies render intact. Entries whose parent has since been loaded by the
+ * regular query are ignored, and items already present are never duplicated.
+ */
+export function mergeAncestorContext(items, ancestorsByParent) {
+  if (!ancestorsByParent) return items;
+  const itemIds = new Set(items.map((item) => item.id));
+  const merged = [...items];
+  for (const [parentId, chain] of Object.entries(ancestorsByParent)) {
+    if (itemIds.has(Number(parentId))) continue;
+    for (const ancestor of chain ?? []) {
+      if (itemIds.has(ancestor.id)) continue;
+      itemIds.add(ancestor.id);
+      merged.push(ancestor);
+    }
+  }
+  return merged;
+}
+
 export function indexCollectionHierarchy(items) {
   const itemIds = new Set(items.map((item) => item.id));
   const childrenByParent = new Map();

frontend/src/lib/features/collections/collectionHierarchy.js

@@ -31,6 +31,9 @@ const BACKLOG_VIEWS = new Set(['workspace-backlog', 'collection-backlog']);
 
 const DEFAULT_PAGE_SIZE = 100;
 const LIST_INITIAL_PAGE_SIZE = 50;
+// Tree pages stay smaller than map/roadmap: every loaded item can require an
+// ancestors lookup, so the page bounds the hierarchy-repair fan-out.
+const TREE_PAGE_SIZE = 100;
 const LARGE_COLLECTION_PAGE_SIZE = 250;
 const BOARD_UNFINISHED_PAGE_SIZE = 1000;
 const BOARD_UNTHROTTLED_ITEM_COUNT = 1000;
@@ -48,9 +51,8 @@ function appendUniqueItems(existing, incoming) {
 
 function initialItemsPageSize(view) {
   if (view === 'workspace-list' || view === 'collection-list') return LIST_INITIAL_PAGE_SIZE;
+  if (view === 'workspace-tree' || view === 'collection-tree') return TREE_PAGE_SIZE;
   if (
-    view === 'workspace-tree' ||
-    view === 'collection-tree' ||
     view === 'workspace-map' ||
     view === 'collection-map' ||
     view === 'workspace-roadmap' ||

frontend/src/lib/stores/collectionContext.svelte.js

@@ -224,34 +224,119 @@ func (r *ItemRepository) GetAncestorsForHierarchyContext(ctx context.Context, it
 	var ancestors []models.Item
 	for rows.Next() {
 		var item models.Item
-		var itemTypeID, assigneeID, creatorID, parentID sql.NullInt64
-		var customFieldValuesJSON sql.NullString
-		var workspaceName, workspaceKey, itemTypeName, itemTypeColor, itemTypeIcon sql.NullString
-		var level int
-		if err := rows.Scan(
-			&item.ID, &item.WorkspaceID, &item.WorkspaceItemNumber, &itemTypeID, &item.Title, &item.Description, &item.IsTask,
-			&assigneeID, &creatorID, &customFieldValuesJSON, &parentID,
-			&item.CreatedAt, &item.UpdatedAt,
-			&workspaceName, &workspaceKey, &itemTypeName, &itemTypeColor, &itemTypeIcon, &level,
-		); err != nil {
+		if err := scanAncestorItem(rows, &item); err != nil {
 			return nil, fmt.Errorf("failed to scan ancestor: %w", err)
 		}
-		_ = level
-		_ = itemTypeColor
-		_ = itemTypeIcon
-		assignNullableInt(&item.ItemTypeID, itemTypeID)
-		assignNullableInt(&item.AssigneeID, assigneeID)
-		assignNullableInt(&item.CreatorID, creatorID)
-		assignNullableInt(&item.ParentID, parentID)
-		assignNullableString(&item.WorkspaceName, workspaceName)
-		assignNullableString(&item.WorkspaceKey, workspaceKey)
-		assignNullableString(&item.ItemTypeName, itemTypeName)
-		item.CustomFieldValues = parseCustomFieldsJSON(customFieldValuesJSON)
 		ancestors = append(ancestors, item)
 	}
 	return ancestors, rows.Err()
 }
 
+// scanAncestorItem reads one row of the shared ancestor SELECT column list:
+// id, workspace_id, workspace_item_number, item_type_id, title, description,
+// is_task, assignee_id, creator_id, custom_field_values, parent_id,
+// created_at, updated_at, workspace_name, workspace_key, item_type_name,
+// item_type_color, item_type_icon, level. Leading targets, when given, precede
+// the shared columns (the batch query prefixes each row with its start id).
+func scanAncestorItem(rows *sql.Rows, item *models.Item, leading ...any) error {
+	var itemTypeID, assigneeID, creatorID, parentID sql.NullInt64
+	var customFieldValuesJSON sql.NullString
+	var workspaceName, workspaceKey, itemTypeName, itemTypeColor, itemTypeIcon sql.NullString
+	var level int
+	dest := make([]any, 0, len(leading)+19)
+	dest = append(dest, leading...)
+	dest = append(dest,
+		&item.ID, &item.WorkspaceID, &item.WorkspaceItemNumber, &itemTypeID, &item.Title, &item.Description, &item.IsTask,
+		&assigneeID, &creatorID, &customFieldValuesJSON, &parentID,
+		&item.CreatedAt, &item.UpdatedAt,
+		&workspaceName, &workspaceKey, &itemTypeName, &itemTypeColor, &itemTypeIcon, &level,
+	)
+	if err := rows.Scan(dest...); err != nil {
+		return err
+	}
+	_ = level
+	_ = itemTypeColor
+	_ = itemTypeIcon
+	assignNullableInt(&item.ItemTypeID, itemTypeID)
+	assignNullableInt(&item.AssigneeID, assigneeID)
+	assignNullableInt(&item.CreatorID, creatorID)
+	assignNullableInt(&item.ParentID, parentID)
+	assignNullableString(&item.WorkspaceName, workspaceName)
+	assignNullableString(&item.WorkspaceKey, workspaceKey)
+	assignNullableString(&item.ItemTypeName, itemTypeName)
+	item.CustomFieldValues = parseCustomFieldsJSON(customFieldValuesJSON)
+	return nil
+}
+
+// GetAncestorsForItemsContext resolves ancestor chains for many items in one
+// recursive walk (maxDepth caps each chain). Chains exclude the items
+// themselves and are ordered root -> parent; every requested id gets an entry,
+// empty when the item has no ancestors.
+func (r *ItemRepository) GetAncestorsForItemsContext(ctx context.Context, itemIDs []int, maxDepth int) (map[int][]models.Item, error) {
+	result := make(map[int][]models.Item, len(itemIDs))
+	if len(itemIDs) == 0 {
+		return result, nil
+	}
+	if maxDepth <= 0 || maxDepth > maxItemHierarchyDepth {
+		maxDepth = maxItemHierarchyDepth
+	}
+	placeholders := strings.Repeat("?,", len(itemIDs))
+	placeholders = placeholders[:len(placeholders)-1]
+	args := make([]any, 0, len(itemIDs)+1)
+	for _, id := range itemIDs {
+		args = append(args, id)
+	}
+	args = append(args, maxDepth)
+	rows, err := r.db.QueryContext(ctx, `
+		WITH RECURSIVE ancestors AS (
+			SELECT i.id AS start_id, i.id, i.workspace_id, i.workspace_item_number, i.item_type_id, i.title, i.description, i.is_task,
+			       i.assignee_id, i.creator_id, i.custom_field_values, i.parent_id,
+			       i.created_at, i.updated_at,
+			       w.name as workspace_name, w.key as workspace_key, it.name as item_type_name, it.color as item_type_color, it.icon as item_type_icon,
+			       0 as level, it.hierarchy_level
+			FROM items i
+			JOIN workspaces w ON i.workspace_id = w.id
+			LEFT JOIN item_types it ON i.item_type_id = it.id
+			WHERE i.id IN (`+placeholders+`)
+
+			UNION ALL
+
+			SELECT a.start_id, p.id, p.workspace_id, p.workspace_item_number, p.item_type_id, p.title, p.description, p.is_task,
+			       p.assignee_id, p.creator_id, p.custom_field_values, p.parent_id,
+			       p.created_at, p.updated_at,
+			       w.name as workspace_name, w.key as workspace_key, it.name as item_type_name, it.color as item_type_color, it.icon as item_type_icon,
+			       a.level + 1 as level, it.hierarchy_level
+			FROM items p
+			JOIN workspaces w ON p.workspace_id = w.id
+			LEFT JOIN item_types it ON p.item_type_id = it.id
+			JOIN ancestors a ON p.id = a.parent_id
+			WHERE a.level < ?
+			  AND COALESCE(a.hierarchy_level, -999) != 0
+		)
+		SELECT start_id, id, workspace_id, workspace_item_number, item_type_id, title, description, is_task,
+		       assignee_id, creator_id, custom_field_values, parent_id,
+		       created_at, updated_at,
+		       workspace_name, workspace_key, item_type_name, item_type_color, item_type_icon, level
+		FROM ancestors
+		WHERE level > 0
+		ORDER BY start_id, level DESC
+	`, args...)
+	if err != nil {
+		return nil, fmt.Errorf("failed to query ancestors for items: %w", err)
+	}
+	defer func() { _ = rows.Close() }()
+
+	for rows.Next() {
+		var startID int
+		var item models.Item
+		if err := scanAncestorItem(rows, &item, &startID); err != nil {
+			return nil, fmt.Errorf("failed to scan ancestor: %w", err)
+		}
+		result[startID] = append(result[startID], item)
+	}
+	return result, rows.Err()
+}
+
 // GetRootItems returns all root items (no parent) for a workspace
 func (r *ItemRepository) GetRootItems(workspaceID int) ([]*models.Item, error) {
 	rows, err := r.db.Query(`

internal/repository/item_hierarchy.go

@@ -4413,6 +4413,25 @@
         ]
       }
     },
+    "/items/batch-ancestors": {
+      "post": {
+        "description": "Get item ancestors batch. The server validates resource ownership and command preconditions before persisting changes. Unknown JSON fields are rejected when the operation accepts a body.",
+        "parameters": [],
+        "responses": {
+          "400": {},
+          "401": {},
+          "403": {},
+          "413": {},
+          "415": {},
+          "429": {},
+          "500": {}
+        },
+        "summary": "Get item ancestors batch",
+        "tags": [
+          "Work items"
+        ]
+      }
+    },
     "/items/bulk-patch": {
       "post": {
         "description": "Bulk patch items. The server validates resource ownership and command preconditions before persisting changes. Unknown JSON fields are rejected when the operation accepts a body.",