feat request: public file-tree icon provider API / 功能请求：公开文件树图标 Provider API

[Nyzeep]

English

Summary

Please consider a public, capability-gated file-tree icon provider API for
community plugins.

Better Sidebar already provides extensibility points, but community file-icon
themes currently have no stable way to change the Files tree's root, folder,
and file glyphs. Without an API, a theme would need DOM mutation,
CSS-selector coupling, a component patch, or a maintained fork. Those paths
are fragile across UI changes and make HMR/disposal behavior difficult to get
right.

Proposed direction

A possible client-side seam could be:

betterSidebar.registerFileIconProvider(descriptor): () => void
betterSidebar.resolveFileIcon(target): ReactNode | undefined

The exact naming and shape should follow the maintainers' preferred API style.
One candidate descriptor could contain a stable provider id, an
optional priority, and a synchronous resolver. The target would
identify the entry without exposing tree internals: path, name, file versus
directory kind, root/open state where relevant, and display flags such as
symlink/hidden/broken.

Suggested behavior:

• resolve providers by descending priority, keeping registration order stable
  for equal priority;
• the first return value that is not undefined wins;
• undefined declines the target and preserves the native icon
  fallback;
• a resolver error is logged and lower-priority providers may still run;
• provider registration and disposal refresh mounted file trees, so HMR and
  removal restore the expected fallback immediately;
• scope the API to the root, folders, and files glyphs only; do not expose or
  require DOM/CSS/component implementation details.

Better Sidebar could advertise this through
features.includes('fileIconProvider'), allowing consumers to
feature-gate rather than infer support from a version number.

Why a separate provider seam

I found #343, which
explores resolving file-row and editor-tab icons from the existing
FileViewerDescriptor.icon registry. That is related and useful,
but a file-tree provider remains distinct: folders and the workspace root do
not have viewer descriptors, and independent icon themes need predictable
priority and lifecycle arbitration.

Proof of concept and release posture

I have published the source for an independent integration,
dsh-material-file-icons,
which uses Material Icon Theme-derived mappings. Its client code is already
capability-gated and intentionally stays a safe no-op with the current public
sidebar release. It has not been published to npm as a visually active plugin,
because public dsh-better-sidebar@0.16.1 does not advertise this
capability.

A local proof of concept validated root, directory, and file rendering,
provider priority/fallback semantics, disposal/HMR refresh behavior, and
focused service/tree tests. This issue is not asking maintainers to endorse
that theme; it asks whether a generic public extension seam is acceptable.

Questions for maintainers

1. Is this direction welcome upstream?
2. Would you prefer an extension of the existing viewer-icon registry, a new
   file-tree-specific registry, or a different abstraction?
3. Are there naming, ownership, priority, error-handling, capability, or
   lifecycle constraints a contribution should follow?
4. If the direction is accepted, would a focused follow-up PR be welcome after
   API alignment?

Non-goals

• No DOM/CSS workaround or component patch.
• No theme-specific settings or bundled icon data in Better Sidebar.
• No filesystem, network, or asynchronous work in the per-row resolver.

---

中文

摘要

希望讨论为社区插件提供一个公开、可通过 capability gate 检测的文件树图标
Provider API。

Better Sidebar 已有多个扩展点，但社区文件图标主题目前没有稳定方式替换 Files 树中的
工作区根目录、文件夹和文件 glyph。没有公开 API 时，主题只能依赖 DOM 修改、CSS selector
耦合、组件补丁或长期维护 fork。这些方案会随着 UI 变化而脆弱，也难以正确处理 HMR 和
卸载后的回退行为。

建议方向

一个可讨论的客户端 seam 形态如下：

betterSidebar.registerFileIconProvider(descriptor): () => void
betterSidebar.resolveFileIcon(target): ReactNode | undefined

具体名称与类型应以维护者偏好的 API 风格为准。一个候选 descriptor 可以包含稳定的
provider id、可选 priority 和同步 resolver。target 仅描述
条目而不暴露树内部实现：路径、名称、file/directory 种类、必要的 root/open 状态，以及
symlink/hidden/broken 等显示标记。

建议语义：

• 按 priority 从高到低解析；priority 相同时保持注册顺序稳定；
• 第一个返回值不为 undefined 的 provider 获胜；
• 返回 undefined 表示放弃该条目，继续保留原生图标 fallback；
• resolver 抛错时记录日志，并允许低优先级 provider 继续尝试；
• 注册或卸载 provider 时刷新已挂载的文件树，使 HMR 和移除后能立即恢复预期 fallback；
• API 范围只覆盖根目录、文件夹和文件 glyph，不暴露也不要求依赖 DOM/CSS/组件实现细节。

Better Sidebar 可以通过
features.includes('fileIconProvider') 声明该能力，使消费者按 capability
检测，而不是根据版本号猜测是否支持。

为什么需要独立的 provider seam

我注意到 #343 探索了从现有
FileViewerDescriptor.icon registry 解析文件行和编辑器 tab 图标。这是相关且
有价值的工作，但文件树 provider 仍是不同的问题：文件夹和工作区根目录没有 viewer
descriptor；独立图标主题也需要可预测的 priority 与生命周期仲裁。

验证原型与发布状态

我已公开一个独立集成项目
dsh-material-file-icons，
其使用 Material Icon Theme 衍生映射。它的 client 代码已使用 capability gate，因此面对
当前公开 sidebar 时会安全 no-op。由于公开
dsh-better-sidebar@0.16.1 尚未声明该 capability，项目没有作为可立即显示
效果的 npm 插件发布。

本地 proof of concept 已验证根目录、目录、文件渲染，provider priority/fallback 语义、
disposal/HMR 刷新行为，以及聚焦的 service/tree 测试。本 issue 并不是请求维护者认可某个
具体图标主题，而是希望确认通用公开扩展点是否可被接受。

想请维护者确认的问题

1. 这个方向是否适合上游？
2. 更倾向扩展现有 viewer-icon registry、增加文件树专用 registry，还是采用其他抽象？
3. 对命名、所有权、priority、错误处理、capability 或生命周期是否有明确约束？
4. 若方向获认可，在 API 对齐后是否欢迎提交一个聚焦的后续 PR？

非目标

• 不采用 DOM/CSS workaround 或组件补丁。
• 不要求 Better Sidebar 内置主题专属设置或图标数据。
• 不在逐行 resolver 中执行文件系统、网络或异步操作。