CmdPal: Icons (12/n) - Share Shell icons by identity and display file-type previews

[Jiří Polášek (jiripolasek)]

Summary of the Pull Request

Part 12 of 12 in the CmdPal icon-loading series. Depends on #50191.

This PR resolves Shell identity before materialization so different item paths can share one cached icon, and adds a quick file-type preview before exact refinement.

• Routes explicit Shell requests and eligible legacy paths through shared location aliases and canonical cache/in-flight entries.
• Adds generation-safe invalidation, bounded retries, safe fallbacks, and direct HICON conversion without a PNG round trip.
• Keeps resolution/extraction and cold arbitration off the STA, coalesces preview updates, and skips misleading shortcut previews.
• Integrates Indexer, Bookmarks, and Shell requests and adds diagnostics plus separate System32 semantic/legacy samples.

Motivation: thousands of files often share a small set of icons. Avoid repeating extraction/materialization, while giving the user a useful preview during per-item resolution.

Note: A dear reviewer will observe that both System32 samples are still slow as a drunk crippled squirrel and icons are loading slowly anyway. The reason for that is that the list items are initialized in order, and before it is initialized, list item view model doesn't know anything about its icon at all. There's a follow-up PR that tackles this issue.

Examples

Using Microsoft.CommandPalette.Extensions.Toolkit:

new IconInfo(ShellItemIconProtocol.Create(@"C:\Docs\a.txt"));
new IconInfo(ShellItemIconProtocol.CreateJumbo(@"C:\Docs\a.txt"));
new IconInfo(ShellItemIconProtocol.Create(@"C:\Windows\System32\shell32.dll"));

The first two serialize as:

|ShellItemIcon|v1;13:C:\Docs\a.txt
|JumboShellItemIcon|v1;13:C:\Docs\a.txt

The last example requests the DLL file's Shell icon. It does not mean “extract icon resource 1,” which remains a different request:

new IconInfo(@"C:\Windows\System32\shell32.dll,1");

Evidence

These are Shell-specific characterizations, not an accepted comparison with the preceding PR.

• Historical System32 cold runs: 8565, 8564, and 8564 Shell requests; exactly 174 extractions and 4769 location resolutions in each run. Many requests share materialized icons, but per-path resolution still costs work.
• The three warm passes performed 0, 0, and 171 extractions; location resolutions were 0, 0, and 4769. A zero median must not be presented as guaranteed warm reuse.
• A later two-phase smoke run recorded 171 extractions for 8565 requests. Its workload gate passed, but there was only one run per side.
• The earlier legacy-page versus semantic-page comparison failed its cross-page workload gate. Its headline latency percentages are not accepted comparative evidence.
• Provider/resolver tests cover canonical joins, invalidation races, fallback poisoning, progressive replacement, and off-caller-thread cold arbitration.

The counts demonstrate sharing, not instantaneous visible icons. Repeat a matched-page cold/warm comparison on the final build and explain the warm re-extraction run before claiming a reliable latency improvement. All apps/Home scenarios do not substitute for a Shell workload.

Technical notes

• Path aliases remain case-sensitive; canonical Shell identity is where different paths converge. Index generations participate in the key. After bounded invalidation retries, resolution falls back to a path-specific identity instead of relabeling a possibly stale image-list index.
• SHGFI_USEFILEATTRIBUTES supplies only the provisional type icon, not proof of the exact item's identity. Exact lookup still corrects custom icons. Extensionless items and shortcuts skip this phase; a dotted directory can briefly receive a file-type preview rather than forcing a filesystem check on the STA.
• Requests joining a canonical load keep their original request binding. The shared load is conservatively held demanded rather than reattaching an already-bound requester. Actual worker release is measured separately from the later shared-task completion.
• Null extraction results/shared generic fallbacks must not poison a canonical type-wide cache entry. Fallback and real extraction success are distinct outcomes.
• Thread-local Shell error-mode suppression prevents modal error boxes; it does not impose a timeout on Shell handlers. Direct image paths retain their image behavior, and explicit Shell-file requests remain distinct from embedded binary-icon references.
• Canonical caching reduces extraction/materialization, not every per-path Shell query or earlier view-model initialization. Realized-item initializer priority is outside these 12 PRs.

Implementation: src/modules/cmdpal/Microsoft.CmdPal.UI/Helpers/Icons/ShellIconLocationResolver.cs.

PR Checklist

• Closes: CmdPal: Icon loading (12/n) - Separate icon resolution and icon loading #50131

• Communication: I've discussed this with core contributors already. If the work hasn't been agreed, this work might be rejected
• Tests: Added/updated and all pass
• Localization: All end-user-facing strings can be localized
• Dev docs: Added/updated
• New binaries: Added on the required places
  • JSON for signing for new binaries
  • WXS for installer for new binaries and localization folder
  • YML for CI pipeline for new test projects
  • YML for signed pipeline
• Documentation updated: If checked, please file a pull request on our docs repo and link it here: #xxx

Detailed Description of the Pull Request / Additional comments

Validation Steps Performed

[github-actions]

🧭 PR intake

Visual evidence: Required — The pull request changes product UI files, so reviewers need to see the visible result. Visual evidence is currently missing.

Author action

Jiří Polášek (@jiripolasek), please update the following before review:

• Add a screenshot, GIF, or video to the PR description so reviewers can validate the visible change.

See the contribution guide for the full checklist.

If there is no author response within 7 days, this PR will be automatically closed.

Automated PR intake; PowerToys maintainers make final decisions.