Add a bookmarks feature for the decompiled C# view

[christophwille]

Summary

Adds a flat (no folders, no labels) bookmarks feature for the decompiled C# view:

• Toggle a bookmark on a line from the right-click menu, the icon gutter, Ctrl+B, or the pane toolbar.
• A new left-margin gutter shows a bookmark glyph per line and greys it out when disabled; clicking the gutter toggles.
• A dockable Bookmarks pane (auto-listed in the Window menu) with an enable checkbox, an editable Name, and Location / Module columns; double-click a row to jump to it.
• Bookmarks persist across restarts and survive re-decompilation and decompiler-setting changes that reflow the C# text.
• Export / import (replace or merge), and a prompt to remove a bookmark whose assembly file is gone from disk.

How the parts interact

flowchart TD
    WC["CSharpLanguage.WriteCode<br/>captures sequence points"] --> DI["DecompiledDebugInfo<br/>line to/from token + IL offset"]
    TRIG["Toggle: context menu / Ctrl+B /<br/>gutter click / pane toolbar"] --> AN["BookmarkAnchoring<br/>clicked line to anchor"]
    DI --> AN
    AN --> MGR["BookmarkManager<br/>the list + JSON I/O"]
    MGR --> JSON[("ILSpy.Bookmarks.json")]
    MGR --> MARGIN["BookmarkMargin<br/>gutter icons + click"]
    MGR --> PANE["BookmarksPane<br/>grid + toolbar"]
    PANE --> NAV["BookmarkNavigator<br/>load asm, resolve, select, scroll"]
    DI --> MARGIN
    DI --> NAV
    NAV --> DOC["decompiled document<br/>centre line + flash + pulse"]

Loading

The DecompiledDebugInfo map (a line/offset table built from the decompiler's sequence points) is the keystone: it turns a clicked line into an anchor on save, and an anchor back into a line for the gutter and for navigation. The BookmarkManager is the single source of truth for the list and persists on every change. The margin, pane, and navigator are independent consumers wired only to the manager and the per-document map.

Anchoring model

A bookmark never stores a raw line number (those move when settings reflow the C#). It stores a metadata token, with two kinds:

• Token anchor -- a definition line (type / method / field / property / event): module + token.
• Body anchor -- a line inside a method body: module + method token + IL offset. The IL offset is stable across re-decompilation and is mapped back to the current line on display.

Recovering an IL offset needs the decompiler's sequence points, which the normal C# output did not carry. They are captured once at the WriteCode chokepoint and stored as a per-document map; the displayed text is unchanged.

flowchart LR
    A["clicked line"] --> B{"starts a statement?"}
    B -- yes --> C["Body anchor: token + IL offset"]
    B -- no --> D{"definition on line?"}
    D -- yes --> E["Token anchor"]
    D -- no --> F["not bookmarkable"]
    C --> G["BookmarkManager.Toggle"]
    E --> G
    G --> H{"same anchor exists?"}
    H -- yes --> I["remove"]
    H -- no --> J["add + default name"]

Loading

Navigation

flowchart TD
    A["double-click / next / previous"] --> B["find assembly in list"]
    B -- "not loaded" --> C["open from disk"]
    C -- "file gone" --> D["offer to remove bookmark"]
    B -- found --> E["resolve token to entity"]
    C -- loaded --> E
    E -- "token gone" --> F["abort quietly (no dialog)"]
    E -- ok --> G["find tree node, or nearest enclosing type"]
    G --> H["select node -> decompile"]
    H --> I["once document ready:<br/>centre line + line flash + gutter pulse"]

Loading

The removal dialog fires only when the assembly file is genuinely missing or unreadable. A token that no longer resolves (e.g. a rebuilt assembly) or a compiler-generated member without its own tree node aborts quietly rather than nagging. Disabled bookmarks stay visible in the gutter and list but are skipped by next/previous (both global and in-file).

Notable files

Area	File
Shared sidecar path	ILSpy/AppEnv/ConfigurationFiles.cs (the dock layout now uses it too)
Model + list + JSON	ILSpy/Bookmarks/Bookmark.cs, BookmarkManager.cs
Line/offset map	ILSpy/Bookmarks/MethodDebugInfo.cs
Sequence-point capture	ILSpy/Languages/CSharpLanguage.cs (WriteCode)
Anchoring	ILSpy/Bookmarks/BookmarkAnchoring.cs
Gutter	ILSpy/Bookmarks/BookmarkMargin.cs
Pane	ILSpy/Bookmarks/BookmarksPane*.{axaml,cs}
Navigation + dialogs	ILSpy/Bookmarks/BookmarkNavigator.cs, BookmarkDialogs.cs
Navigation feedback	ILSpy/TextView/LineHighlightAdorner.cs
Text-view glue	ILSpy/TextView/DecompilerTextView.axaml.cs

Testing

Added unit and integration tests (headless Avalonia) covering the config-file path, the manager (toggle / merge-import / JSON round-trip / drop-empty-on-load), the line/offset map and its capture against real decompiled output, both anchor branches end-to-end, the next/previous skip-disabled stepping, and the highlight adorner lifecycle. The full UI suite passes.

Notes

• Only the bookmark icons the feature actually uses are committed; the unused folder/window/group variants are left out.
• The anchoring approach (token plus IL offset) draws on prior art in other decompiler bookmark implementations; no third-party code was used.

Review updates

Applied while addressing review feedback (branch history was rewritten, so a force-push updated this PR):

• Single-pass sequence-point capture. The IL-offset/line map is now harvested during the existing C# formatting pass by a token-writer decorator (BookmarkDebugInfoCollector) that reads each AST node's ILInstruction annotation, instead of re-running the formatter through a throwaway writer and calling CreateSequencePoints. This drops a full second formatting pass (~5x cheaper capture on large types, measured) and removes the cross-pass "both writers must break lines identically" assumption — the line numbers come from the very output being displayed.
• Reconcile the live list on save instead of Clear()+rebuild of the ObservableCollection, so editing a name or toggling the enabled checkbox in the pane no longer drops the pane's selection, resets its scroll, or re-enters the grid mid-edit; existing instances are kept (the cross-instance read-modify-write under the named mutex is unchanged).
• Navigate to the re-anchored line, not the saved offset. A decompiler-setting change reflows the text and re-anchors a bookmark by IL offset; navigation no longer restores the bookmark's stale saved scroll/caret over the centered line, which had left it off-screen.
• Gutter painting: the line→glyph map is cached (no per-frame reference rescans on scroll/hover/pulse), keyed on the document's content version so it rebuilds on navigation even though the editor reuses one TextDocument; the hover-anchorability check no longer builds a full bookmark + view-state snapshot.
• Gutter UX: a removal click hides that line's hover preview until the pointer leaves the line, and the preview glyph is drawn translucent.
• Cleanups: shared MutexProtector between the settings and bookmark sidecars, a MatchesBookmark helper for the token+assembly identity, a FoldingSection overload of FoldingsViewState.Restore, HandleExceptions() on the pane's navigation, and the corrected Bookmark.Disable.svg asset name.

Review fixes applied with Claude Code.

🤖 Generated with Claude Code

[Copilot]

Pull request overview

Adds a persistent bookmarks feature to ILSpy’s decompiled C# text view, including anchoring bookmarks via metadata token + IL offset (using captured sequence points) so bookmarks survive re-decompilation and formatting reflow.

Changes:

• Introduces bookmark model/persistence (JSON sidecar), navigation, context-menu entry, and a dockable Bookmarks pane (with import/export).
• Captures per-method IL-offset ↔ line maps during C# decompilation to support stable “body” anchors and gutter placement.
• Adds UI affordances: bookmark gutter margin, Ctrl+B toggle, and a one-shot line highlight adorner on navigation; plus new icons/resources and tests.

Reviewed changes

Copilot reviewed 30 out of 42 changed files in this pull request and generated 6 comments.

Show a summary per file

File	Description
ILSpy/ViewLocator.cs	Registers the new Bookmarks pane for view resolution.
ILSpy/TextView/LineHighlightAdorner.cs	Adds a one-shot line highlight renderer used after bookmark navigation.
ILSpy/TextView/DecompilerTextView.axaml.cs	Wires bookmark toggling (Ctrl+B / context menu), in-file navigation, scrolling + highlight/pulse, and line resolution for bookmarks.
ILSpy/TextView/DecompilerTabPageModel.cs	Stores per-document debug info maps and a pending bookmark for deferred navigation positioning.
ILSpy/TextView/AvaloniaEditTextOutput.cs	Exposes current output line and collects per-method debug maps during decompile output.
ILSpy/Properties/Resources.resx	Adds localized strings for bookmark UI, commands, and prompts.
ILSpy/Properties/Resources.Designer.cs	Regenerates strongly-typed resource accessors for new bookmark strings.
ILSpy/Languages/CSharpLanguage.cs	Captures sequence points and builds per-method IL-offset ↔ line maps during C# WriteCode.
ILSpy/Images.cs	Adds bookmark-related icon loads for UI toolbars and gutter.
ILSpy/Docking/DockWorkspace.cs	Uses a shared sidecar-path helper for dock layout JSON path resolution.
ILSpy/Commands/FilePickers.cs	Adds a single-file OpenAsync picker used by bookmark import.
ILSpy/Bookmarks/ToggleBookmarkContextMenuEntry.cs	Adds “Toggle Bookmark” editor context menu entry gated by bookmarkable line.
ILSpy/Bookmarks/MethodDebugInfo.cs	Implements MethodDebugInfo and DecompiledDebugInfo (IL-offset ↔ line mapping + anchor resolution).
ILSpy/Bookmarks/BookmarksPaneModel.cs	Implements Bookmarks tool pane VM: list binding, navigation, enable/disable/delete, import/export.
ILSpy/Bookmarks/BookmarksPane.axaml.cs	Handles double-click activation to navigate to a bookmark.
ILSpy/Bookmarks/BookmarksPane.axaml	Defines Bookmarks pane UI: toolbar + DataGrid with editable Name and Enabled checkbox.
ILSpy/Bookmarks/BookmarkNavigator.cs	Implements bookmark navigation: ensure assembly loaded, resolve token, select tree node, set pending bookmark.
ILSpy/Bookmarks/BookmarkMargin.cs	Adds left gutter margin rendering bookmark glyphs and handling click-to-toggle + pulse animation.
ILSpy/Bookmarks/BookmarkManager.cs	Implements bookmark list, persistence, import/export, and change notifications.
ILSpy/Bookmarks/BookmarkDialogs.cs	Adds simple modal prompts for missing-assembly removal and import replace/merge choice.
ILSpy/Bookmarks/BookmarkAnchoring.cs	Creates bookmark anchors from a clicked line (body anchor via IL offset or token anchor via definition).
ILSpy/Bookmarks/Bookmark.cs	Defines bookmark model (anchor fields + editable Name/Enabled) and dedupe key.
ILSpy/Assets/Icons/Boomark.Disable.svg	Adds disabled-bookmark icon asset (note: filename is misspelled by design).
ILSpy/Assets/Icons/Bookmark.Window.svg	Adds bookmark icon variant asset (currently appears unused).
ILSpy/Assets/Icons/Bookmark.svg	Adds bookmark icon asset.
ILSpy/Assets/Icons/Bookmark.Previous.svg	Adds “previous bookmark” icon asset.
ILSpy/Assets/Icons/Bookmark.Previous.Folder.svg	Adds “previous bookmark (folder)” icon variant (currently appears unused).
ILSpy/Assets/Icons/Bookmark.Previous.File.svg	Adds “previous bookmark in file” icon asset.
ILSpy/Assets/Icons/Bookmark.Next.svg	Adds “next bookmark” icon asset.
ILSpy/Assets/Icons/Bookmark.Next.Folder.svg	Adds “next bookmark (folder)” icon variant (currently appears unused).
ILSpy/Assets/Icons/Bookmark.Next.File.svg	Adds “next bookmark in file” icon asset.
ILSpy/Assets/Icons/Bookmark.GroupDisable.svg	Adds grouped/disabled icon variant (currently appears unused).
ILSpy/Assets/Icons/Bookmark.Clear.svg	Adds “clear/delete bookmark” icon asset.
ILSpy/AppEnv/ConfigurationFiles.cs	Adds shared helper for resolving JSON sidecar config file paths next to ILSpy.xml.
ILSpy.Tests/Editor/LineHighlightAdornerTests.cs	Tests highlight adorner registration/unregistration lifecycle.
ILSpy.Tests/Docking/DockWorkspaceTests.cs	Updates tool-pane count expectations to include Bookmarks pane.
ILSpy.Tests/Bookmarks/MethodDebugInfoTests.cs	Unit tests for line↔offset mapping and document-level anchor resolution.
ILSpy.Tests/Bookmarks/BookmarkNavigationStepTests.cs	Tests next/previous stepping skips disabled bookmarks and wraps correctly.
ILSpy.Tests/Bookmarks/BookmarkManagerTests.cs	Tests toggle behavior, default naming, persistence, and merge/replace import rules.
ILSpy.Tests/Bookmarks/BookmarkDebugInfoCaptureTests.cs	Integration test proving sequence-point capture produces usable method maps.
ILSpy.Tests/Bookmarks/BookmarkAnchoringTests.cs	Integration test for body vs token anchor creation against real decompiled output.
ILSpy.Tests/AppEnv/ConfigurationFilesTests.cs	Tests sidecar path resolution and headless fallback behavior.

Files not reviewed (1)

• ILSpy/Properties/Resources.Designer.cs: Generated file

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.