@theia/scm 1.75.0-next.3 → 1.75.0-next.35

package/src/browser/scm-history-graph-contribution.ts

@@ -0,0 +1,222 @@
+// *****************************************************************************
+// Copyright (C) 2026 Safi Seid-Ahmad, K2view and others.
+//
+// This program and the accompanying materials are made available under the
+// terms of the Eclipse Public License v. 2.0 which is available at
+// http://www.eclipse.org/legal/epl-2.0.
+//
+// This Source Code may also be made available under the following Secondary
+// Licenses when the conditions for such availability set forth in the Eclipse
+// Public License v. 2.0 are satisfied: GNU General Public License, version 2
+// with the GNU Classpath Exception which is available at
+// https://www.gnu.org/software/classpath/license.html.
+//
+// SPDX-License-Identifier: EPL-2.0 OR GPL-2.0-only WITH Classpath-exception-2.0
+// *****************************************************************************
+
+import { injectable, inject, named, optional } from '@theia/core/shared/inversify';
+import { ILogger } from '@theia/core';
+import { Command, CommandContribution, CommandRegistry } from '@theia/core/lib/common/command';
+import { MenuContribution, MenuModelRegistry } from '@theia/core/lib/common/menu';
+import { nls } from '@theia/core/lib/common/nls';
+import { CancellationTokenSource } from '@theia/core/lib/common/cancellation';
+import { QuickInputService } from '@theia/core/lib/browser';
+import { QuickPickItem, QuickPickSeparator } from '@theia/core/lib/common/quick-pick-service';
+import { codicon } from '@theia/core/lib/browser/widgets/widget';
+import { ScmHistoryGraphModel, ScmHistoryGraphModelProvider } from './scm-history-graph-model';
+import { ScmService } from './scm-service';
+import { ScmHistoryItemRef, ScmHistoryProvider } from './scm-provider';
+import { SCM_HISTORY_TITLE_MENU } from './scm-history-graph-widget';
+import { getRefBadgeClass } from './scm-history-graph-helpers';
+
+export namespace ScmHistoryGraphCommands {
+    export const REFRESH = Command.toDefaultLocalizedCommand({
+        id: 'scmHistoryGraph.refresh',
+        category: 'Source Control',
+        label: 'Refresh',
+        iconClass: codicon('refresh')
+    });
+    export const PICK_HISTORY_ITEM_REFS = Command.toLocalizedCommand({
+        id: 'scmHistoryGraph.pickHistoryItemRefs',
+        category: 'Source Control',
+        label: 'Pick History Item Reference...',
+        iconClass: codicon('git-branch')
+    }, 'theia/scm/pickHistoryItemRefs');
+}
+
+type RefPickItem = QuickPickItem & { refId?: string; auto?: boolean };
+
+/**
+ * Contributes the native toolbar actions of the SCM history graph: the
+ * history item reference filter picker (VS Code's "Auto" dropdown) and the
+ * refresh action. Extension actions (e.g. fetch/pull/push from vscode.git)
+ * are contributed separately via the `scm/history/title` menu.
+ */
+@injectable()
+export class ScmHistoryGraphContribution implements CommandContribution, MenuContribution {
+
+    @inject(ScmService) protected readonly scmService: ScmService;
+    @inject(ScmHistoryGraphModelProvider) protected readonly modelProvider: ScmHistoryGraphModelProvider;
+    @inject(QuickInputService) @optional() protected readonly quickInputService: QuickInputService;
+    @inject(ILogger) @named('scm:ScmHistoryGraphContribution') protected readonly logger: ILogger;
+
+    /**
+     * The graph model, resolved lazily: instantiating it starts loading
+     * history, so it must only be resolved when a graph command actually
+     * runs or the graph toolbar renders (the widget has created the model
+     * by then). In particular, `isEnabled`/`isVisible` are also queried by
+     * the command palette and therefore consult the `ScmService` instead.
+     */
+    protected get model(): ScmHistoryGraphModel {
+        return this.modelProvider();
+    }
+
+    protected get historyProvider(): ScmHistoryProvider | undefined {
+        return this.scmService.selectedRepository?.provider.historyProvider;
+    }
+
+    registerCommands(commands: CommandRegistry): void {
+        commands.registerCommand(ScmHistoryGraphCommands.REFRESH, {
+            isEnabled: () => !!this.historyProvider,
+            isVisible: () => !!this.historyProvider,
+            execute: () => this.model.refresh()
+        });
+        commands.registerCommand(ScmHistoryGraphCommands.PICK_HISTORY_ITEM_REFS, {
+            isEnabled: () => !!this.historyProvider && !!this.quickInputService,
+            isVisible: () => !!this.historyProvider,
+            isToggled: () => !!this.model.historyItemRefFilter,
+            execute: () => this.pickHistoryItemRefs()
+        });
+    }
+
+    registerMenus(menus: MenuModelRegistry): void {
+        // Extension actions from vscode.git sit at order 900-902; the picker
+        // goes before them and refresh last, matching VS Code's graph toolbar.
+        menus.registerMenuAction([...SCM_HISTORY_TITLE_MENU, 'navigation'], {
+            commandId: ScmHistoryGraphCommands.PICK_HISTORY_ITEM_REFS.id,
+            order: '100'
+        });
+        menus.registerMenuAction([...SCM_HISTORY_TITLE_MENU, 'navigation'], {
+            commandId: ScmHistoryGraphCommands.REFRESH.id,
+            order: '999'
+        });
+    }
+
+    protected async pickHistoryItemRefs(): Promise<void> {
+        if (!this.quickInputService) {
+            return;
+        }
+        const model = this.model;
+        const provider = model.provider;
+        if (!provider) {
+            return;
+        }
+        const picker = this.quickInputService.createQuickPick<RefPickItem>();
+        const cts = new CancellationTokenSource();
+        try {
+            picker.placeholder = nls.localize('theia/scm/pickHistoryItemRefsPlaceholder', 'Select one or more history item references');
+            picker.canSelectMany = true;
+            picker.matchOnDescription = true;
+            // Show the picker right away and populate it once the refs arrive,
+            // so that a slow ref lookup surfaces as a busy picker instead of a
+            // command that appears to do nothing.
+            picker.busy = true;
+
+            const selection = await new Promise<readonly RefPickItem[] | undefined>(resolve => {
+                picker.onDidAccept(() => {
+                    resolve(picker.selectedItems);
+                    picker.hide();
+                });
+                // Also cancels a still-running ref lookup when the picker is dismissed.
+                picker.onDidHide(() => {
+                    cts.cancel();
+                    resolve(undefined);
+                });
+                picker.show();
+
+                provider.provideHistoryItemRefs(undefined, cts.token).then(refs => {
+                    if (cts.token.isCancellationRequested) {
+                        return;
+                    }
+                    const currentFilter = model.historyItemRefFilter;
+                    const items = this.createRefPickItems(refs ?? [], provider);
+                    picker.items = items;
+                    picker.selectedItems = items.filter((item): item is RefPickItem => !QuickPickSeparator.is(item)
+                        && (currentFilter ? !!item.refId && currentFilter.includes(item.refId) : item.auto === true));
+
+                    // "Auto" is exclusive: checking it unchecks everything else and vice versa
+                    let lastSelection: readonly RefPickItem[] = picker.selectedItems;
+                    picker.onDidChangeSelection(newSelection => {
+                        const autoNow = newSelection.some(item => item.auto);
+                        if (autoNow && newSelection.length > 1) {
+                            const autoBefore = lastSelection.some(item => item.auto);
+                            picker.selectedItems = autoBefore ? newSelection.filter(item => !item.auto) : newSelection.filter(item => item.auto);
+                        }
+                        lastSelection = picker.selectedItems;
+                    });
+                    picker.busy = false;
+                }, err => {
+                    if (!cts.token.isCancellationRequested) {
+                        this.logger.error('Failed to load history item refs', err);
+                    }
+                    picker.hide();
+                });
+            });
+
+            if (!selection) {
+                return;
+            }
+            // The selected repository may have changed while the picker was open;
+            // the picked refs belong to the old provider and must not be applied
+            // to the new one.
+            if (model.provider !== provider) {
+                return;
+            }
+            const refIds = selection.filter(item => item.refId !== undefined).map(item => item.refId!);
+            const auto = selection.some(item => item.auto) || refIds.length === 0;
+            model.setHistoryItemRefFilter(auto ? undefined : refIds);
+        } finally {
+            picker.dispose();
+            cts.dispose();
+        }
+    }
+
+    protected createRefPickItems(refs: readonly ScmHistoryItemRef[], provider: ScmHistoryProvider): (RefPickItem | QuickPickSeparator)[] {
+        const autoRefs = [provider.currentHistoryItemRef, provider.currentHistoryItemRemoteRef, provider.currentHistoryItemBaseRef]
+            .filter((ref): ref is ScmHistoryItemRef => !!ref);
+        const items: (RefPickItem | QuickPickSeparator)[] = [{
+            label: nls.localizeByDefault('Auto'),
+            description: autoRefs.map(ref => ref.name).join(', '),
+            auto: true
+        }];
+
+        const groups: { label: string; badgeClass: string }[] = [
+            { label: nls.localize('theia/scm/refPickerBranches', 'branches'), badgeClass: 'head' },
+            { label: nls.localize('theia/scm/refPickerRemoteBranches', 'remote branches'), badgeClass: 'remote' },
+            { label: nls.localize('theia/scm/refPickerTags', 'tags'), badgeClass: 'tag' }
+        ];
+        const grouped = new Set<ScmHistoryItemRef>();
+        for (const group of groups) {
+            const groupRefs = refs.filter(ref => getRefBadgeClass(ref) === group.badgeClass);
+            if (groupRefs.length > 0) {
+                groupRefs.forEach(ref => grouped.add(ref));
+                items.push({ type: 'separator', label: group.label });
+                items.push(...groupRefs.map(ref => this.toRefPickItem(ref)));
+            }
+        }
+        const remaining = refs.filter(ref => !grouped.has(ref));
+        if (remaining.length > 0) {
+            items.push({ type: 'separator' });
+            items.push(...remaining.map(ref => this.toRefPickItem(ref)));
+        }
+        return items;
+    }
+
+    protected toRefPickItem(ref: ScmHistoryItemRef): RefPickItem {
+        return {
+            label: ref.name,
+            description: ref.description,
+            refId: ref.id
+        };
+    }
+}

package/src/browser/scm-history-graph-helpers.spec.ts

@@ -0,0 +1,118 @@
+// *****************************************************************************
+// Copyright (C) 2026 Safi Seid-Ahmad, K2view and others.
+//
+// This program and the accompanying materials are made available under the
+// terms of the Eclipse Public License v. 2.0 which is available at
+// http://www.eclipse.org/legal/epl-2.0.
+//
+// This Source Code may also be made available under the following Secondary
+// Licenses when the conditions for such availability set forth in the Eclipse
+// Public License v. 2.0 are satisfied: GNU General Public License, version 2
+// with the GNU Classpath Exception which is available at
+// https://www.gnu.org/software/classpath/license.html.
+//
+// SPDX-License-Identifier: EPL-2.0 OR GPL-2.0-only WITH Classpath-exception-2.0
+// *****************************************************************************
+
+import { expect } from 'chai';
+import { filterRefsForBadges, getRefBadgePresentation, getRefColorIndex } from './scm-history-graph-helpers';
+import { ScmHistoryItemRef, ScmHistoryProvider } from './scm-provider';
+
+describe('getRefColorIndex', () => {
+
+    const mainRef: ScmHistoryItemRef = { id: 'refs/heads/main', name: 'main' };
+    const remoteRef: ScmHistoryItemRef = { id: 'refs/remotes/origin/main', name: 'origin/main' };
+    const baseRef: ScmHistoryItemRef = { id: 'refs/remotes/origin/develop', name: 'origin/develop' };
+    const otherRef: ScmHistoryItemRef = { id: 'refs/heads/feature', name: 'feature' };
+
+    const provider = {
+        currentHistoryItemRef: mainRef,
+        currentHistoryItemRemoteRef: remoteRef,
+        currentHistoryItemBaseRef: baseRef,
+    } as ScmHistoryProvider;
+
+    it('returns 0 for the current history item ref', () => {
+        expect(getRefColorIndex(mainRef, provider)).to.equal(0);
+    });
+
+    it('returns 1 for the current remote ref', () => {
+        expect(getRefColorIndex(remoteRef, provider)).to.equal(1);
+    });
+
+    it('returns 2 for the current base ref', () => {
+        expect(getRefColorIndex(baseRef, provider)).to.equal(2);
+    });
+
+    it('returns undefined for any other ref', () => {
+        expect(getRefColorIndex(otherRef, provider)).to.be.undefined;
+    });
+
+    it('returns undefined without a provider', () => {
+        expect(getRefColorIndex(mainRef, undefined)).to.be.undefined;
+    });
+});
+
+describe('getRefBadgePresentation', () => {
+
+    const mainRef: ScmHistoryItemRef = { id: 'refs/heads/main', name: 'main' };
+    const remoteRef: ScmHistoryItemRef = { id: 'refs/remotes/origin/main', name: 'origin/main' };
+
+    const provider = {
+        currentHistoryItemRef: mainRef,
+        currentHistoryItemRemoteRef: remoteRef,
+    } as ScmHistoryProvider;
+
+    it('prefers the codicon icon transferred from the provider', () => {
+        const ref: ScmHistoryItemRef = { ...mainRef, icon: 'codicon codicon-target' };
+        expect(getRefBadgePresentation(ref, undefined).iconClass).to.equal('codicon-target');
+    });
+
+    it('falls back to the target icon for the current ref', () => {
+        expect(getRefBadgePresentation(mainRef, provider).iconClass).to.equal('codicon-target');
+    });
+
+    it('falls back to category icons for remote, tag, and other local refs', () => {
+        expect(getRefBadgePresentation(remoteRef, provider).iconClass).to.equal('codicon-cloud');
+        expect(getRefBadgePresentation({ id: 'refs/tags/v1', name: 'v1' }, provider).iconClass).to.equal('codicon-tag');
+        expect(getRefBadgePresentation({ id: 'refs/heads/feature', name: 'feature' }, provider).iconClass).to.equal('codicon-git-branch');
+    });
+
+    it('carries the ref color index', () => {
+        expect(getRefBadgePresentation(mainRef, provider).colorIndex).to.equal(0);
+        expect(getRefBadgePresentation(remoteRef, provider).colorIndex).to.equal(1);
+        expect(getRefBadgePresentation({ id: 'refs/heads/feature', name: 'feature' }, provider).colorIndex).to.be.undefined;
+    });
+});
+
+describe('filterRefsForBadges', () => {
+
+    const mainRef: ScmHistoryItemRef = { id: 'refs/heads/main', name: 'main' };
+    const remoteRef: ScmHistoryItemRef = { id: 'refs/remotes/origin/main', name: 'origin/main' };
+    const featureRef: ScmHistoryItemRef = { id: 'refs/heads/feature', name: 'feature' };
+    const refs = [mainRef, remoteRef, featureRef];
+
+    const provider = {
+        currentHistoryItemRef: mainRef,
+        currentHistoryItemRemoteRef: remoteRef,
+    } as ScmHistoryProvider;
+
+    it("returns all refs in 'all' mode", () => {
+        expect(filterRefsForBadges(refs, provider, 'all')).to.deep.equal(refs);
+    });
+
+    it("keeps only the refs used as a filter in 'filter' mode", () => {
+        expect(filterRefsForBadges(refs, provider, 'filter')).to.deep.equal([mainRef, remoteRef]);
+    });
+
+    it("returns all refs in 'filter' mode when no provider is available", () => {
+        expect(filterRefsForBadges(refs, undefined, 'filter')).to.deep.equal(refs);
+    });
+
+    it("keeps only the explicitly picked refs in 'filter' mode with an explicit filter", () => {
+        expect(filterRefsForBadges(refs, provider, 'filter', ['refs/heads/feature'])).to.deep.equal([featureRef]);
+    });
+
+    it("ignores an explicit filter in 'all' mode", () => {
+        expect(filterRefsForBadges(refs, provider, 'all', ['refs/heads/feature'])).to.deep.equal(refs);
+    });
+});

package/src/browser/scm-history-graph-helpers.ts

@@ -14,16 +14,16 @@
 // SPDX-License-Identifier: EPL-2.0 OR GPL-2.0-only WITH Classpath-exception-2.0
 // *****************************************************************************
 
-import { ScmHistoryItemRef, ScmHistoryItemChange } from './scm-provider';
+import { ScmHistoryItemRef, ScmHistoryItemChange, ScmHistoryProvider } from './scm-provider';
 
 /**
- * Returns the CSS color variable for the given lane index.
+ * Returns the CSS color variable for the given color index.
  * Uses Theia's `--theia-scmGraph-*` variables, mirroring the VS Code
  * scm graph color scheme:
- *   lane 0 (current ref)  → historyItemRefColor
- *   lane 1 (remote ref)   → historyItemRemoteRefColor
- *   lane 2 (base ref)     → historyItemBaseRefColor
- *   lane 3–7              → foreground1–5
+ *   0 (current ref)  → historyItemRefColor
+ *   1 (remote ref)   → historyItemRemoteRefColor
+ *   2 (base ref)     → historyItemBaseRefColor
+ *   3–7 (default rotation) → foreground1–5
  */
 export function laneColor(index: number): string {
     switch (index % 8) {
@@ -83,6 +83,81 @@ export function getRepoRelativePath(uri: string, rootUri: string | undefined): s
     return fullPath;
 }
 
+/**
+ * Returns the ref-based color index of the given ref (0 = current ref,
+ * 1 = remote ref, 2 = base ref), or `undefined` when the ref is none of
+ * the provider's current history item refs. Mirrors VS Code's scm graph
+ * color map.
+ */
+export function getRefColorIndex(ref: ScmHistoryItemRef, provider: ScmHistoryProvider | undefined): number | undefined {
+    if (!provider) {
+        return undefined;
+    }
+    if (ref.id === provider.currentHistoryItemRef?.id) {
+        return 0;
+    }
+    if (ref.id === provider.currentHistoryItemRemoteRef?.id) {
+        return 1;
+    }
+    if (ref.id === provider.currentHistoryItemBaseRef?.id) {
+        return 2;
+    }
+    return undefined;
+}
+
+/**
+ * Filters which refs get badges in the graph, following VS Code's
+ * `scm.graph.badges` setting: `'all'` shows every ref, `'filter'` shows only
+ * the refs used as the graph's filter — the explicitly picked ref ids, or,
+ * without an explicit filter (auto mode), the current, remote, and base refs.
+ * Without provider information all refs are kept.
+ */
+export function filterRefsForBadges(
+    refs: readonly ScmHistoryItemRef[],
+    provider: ScmHistoryProvider | undefined,
+    badges: 'all' | 'filter',
+    filter?: readonly string[]
+): readonly ScmHistoryItemRef[] {
+    if (badges === 'all') {
+        return refs;
+    }
+    if (filter) {
+        return refs.filter(ref => filter.includes(ref.id));
+    }
+    if (!provider) {
+        return refs;
+    }
+    return refs.filter(ref => getRefColorIndex(ref, provider) !== undefined);
+}
+
+export interface RefBadgePresentation {
+    /** Icon class for the badge icon, e.g. 'codicon-git-branch'. */
+    iconClass: string;
+    /** Ref-based color index (0-2), or `undefined` to use the row color. */
+    colorIndex?: number;
+}
+
+/**
+ * Resolves how a ref badge is presented: the provider-supplied codicon icon
+ * when available (VS Code renders `ref.icon` unconditionally), otherwise a
+ * category fallback with the `target` icon marking the current ref; plus the
+ * ref-based color index.
+ */
+export function getRefBadgePresentation(ref: ScmHistoryItemRef, provider: ScmHistoryProvider | undefined): RefBadgePresentation {
+    const colorIndex = getRefColorIndex(ref, provider);
+    let iconClass: string;
+    if (ref.icon && ref.icon.startsWith('codicon ')) {
+        iconClass = ref.icon.substring('codicon '.length);
+    } else if (isTagRef(ref)) {
+        iconClass = 'codicon-tag';
+    } else if (isRemoteRef(ref)) {
+        iconClass = 'codicon-cloud';
+    } else {
+        iconClass = colorIndex === 0 ? 'codicon-target' : 'codicon-git-branch';
+    }
+    return { iconClass, colorIndex };
+}
+
 export function getRefBadgeClass(ref: ScmHistoryItemRef): string {
     const cat = (ref.category ?? '').toLowerCase();
     if (cat === 'heads' || cat === 'head' || ref.id.startsWith('refs/heads/')) {

package/src/browser/scm-history-graph-lanes.spec.ts

@@ -37,9 +37,14 @@ describe('computeGraphRows', () => {
             expect(lanes(commits)).to.deep.equal([0, 0, 0]);
         });
 
-        it('colors are all 0', () => {
+        it('colors default to the first rotation color (foreground1 = index 3)', () => {
             const rows = computeGraphRows(commits);
-            expect(rows.map(r => r.color)).to.deep.equal([0, 0, 0]);
+            expect(rows.map(r => r.color)).to.deep.equal([3, 3, 3]);
+        });
+
+        it('topColor equals color when no ref color overrides the lane', () => {
+            const rows = computeGraphRows(commits);
+            rows.forEach(r => expect(r.topColor).to.equal(r.color));
         });
 
         it('first parent same-lane continuation emits no separate edge (handled by commit line)', () => {
@@ -201,9 +206,13 @@ describe('computeGraphRows', () => {
             expect(mergeIn.length).to.equal(0);
         });
 
-        it('lane colors are correct modulo 8', () => {
+        it('lane colors rotate through the default registry (indices 3-7)', () => {
             const rows = computeGraphRows(commits);
-            rows.forEach(r => expect(r.color).to.equal(r.lane % 8));
+            // O and P1 share lane 0 → first rotation color; P2/P3 opened new lanes
+            expect(rows[0].color).to.equal(3);
+            expect(rows[1].color).to.equal(3);
+            expect(rows[2].color).to.not.equal(rows[3].color);
+            rows.forEach(r => expect(r.color).to.be.within(3, 7));
         });
     });
 
@@ -387,25 +396,14 @@ describe('computeGraphRows', () => {
     });
 
     // -------------------------------------------------------------------------
-    // Lane color wraps at 8
+    // Default color rotation (VS Code cycles scmGraph.foreground1-5)
     // -------------------------------------------------------------------------
-    describe('color wrapping', () => {
-        it('lane color is always lane % 8', () => {
-            // 4 parallel chains so we have lanes 0, 1, 2, 3 occupied at once.
-            // Chain structure: X0→X1→X2, Y0→Y1→Y2, etc., interleaved.
-            const commits = [
-                { id: 'X0', parentIds: ['X1'] },
-                { id: 'Y0', parentIds: ['Y1'] },
-                { id: 'Z0', parentIds: ['Z1'] },
-                { id: 'W0', parentIds: ['W1'] },
-                { id: 'X1', parentIds: [] },
-                { id: 'Y1', parentIds: [] },
-                { id: 'Z1', parentIds: [] },
-                { id: 'W1', parentIds: [] },
-            ];
+    describe('default color rotation', () => {
+        it('cycles through indices 3-7 and wraps', () => {
+            // 6 independent tips → 6 lanes; the sixth wraps back to the first color
+            const commits = ['A', 'B', 'C', 'D', 'E', 'F'].map(id => ({ id, parentIds: [id.toLowerCase()] }));
             const rows = computeGraphRows(commits);
-            // Every row's color must equal lane % 8
-            rows.forEach(r => expect(r.color).to.equal(r.lane % 8));
+            expect(rows.map(r => r.color)).to.deep.equal([3, 4, 5, 6, 7, 3]);
         });
 
         it('assigns distinct lanes to 8 simultaneous branches', () => {
@@ -423,10 +421,57 @@ describe('computeGraphRows', () => {
             const rows = computeGraphRows(commits);
             const laneSet = new Set(rows.map(r => r.lane));
             expect(laneSet.size).to.equal(8); // all distinct lanes
-            // Color of lane 7 is 7, lane 0 is 0
-            const lane7 = rows.find(r => r.lane === 7);
-            expect(lane7).to.not.be.undefined;
-            expect(lane7!.color).to.equal(7);
+            // Default colors never use the reserved ref color indices 0-2
+            rows.forEach(r => expect(r.color).to.be.within(3, 7));
+        });
+    });
+
+    // -------------------------------------------------------------------------
+    // Ref-based colors (VS Code colorMap: current=0, remote=1, base=2)
+    // -------------------------------------------------------------------------
+    describe('ref-based colors', () => {
+        // Remote is one commit ahead: R (origin/main) → L (main = HEAD) → A
+        const behindCommits = [
+            { id: 'R', parentIds: ['L'], colorIndex: 1 },
+            { id: 'L', parentIds: ['A'], colorIndex: 0 },
+            { id: 'A', parentIds: [] },
+        ];
+
+        it('a tip with a color index colors its row', () => {
+            const rows = computeGraphRows(behindCommits);
+            expect(rows[0].color).to.equal(1);
+        });
+
+        it('an overriding commit recolors the chain from its row downward', () => {
+            const rows = computeGraphRows(behindCommits);
+            expect(rows[1].color).to.equal(0);
+            expect(rows[2].color).to.equal(0);
+        });
+
+        it('topColor keeps the inherited color for the segment above an overriding commit', () => {
+            const rows = computeGraphRows(behindCommits);
+            expect(rows[0].topColor).to.equal(1);
+            expect(rows[1].topColor).to.equal(1);
+            expect(rows[2].topColor).to.equal(0);
+        });
+
+        // Diverged: L (main = HEAD) and R (origin/main) both branched off A
+        const divergedCommits = [
+            { id: 'L', parentIds: ['A'], colorIndex: 0 },
+            { id: 'R', parentIds: ['A'], colorIndex: 1 },
+            { id: 'A', parentIds: [] },
+        ];
+
+        it('pass-through edges use the propagated ref color', () => {
+            const rows = computeGraphRows(divergedCommits);
+            const pass = rows[1].edges.find(e => e.type === 'pass-through');
+            expect(pass?.color).to.equal(0);
+        });
+
+        it('merge-in edges from a ref-colored lane keep that color', () => {
+            const rows = computeGraphRows(divergedCommits);
+            const mergeIn = rows[2].edges.find(e => e.type === 'merge-in');
+            expect(mergeIn?.color).to.equal(1);
         });
     });