finding: `AppShellBranding.logo` 无任何读取方,注释「passed to sidebar/navbar via context」是假的(AppShell 不提供该 context)

[yinlianghui]

发现于 #4793 的实施,回传立单。未认领。observation-class:今天没有用户会撞上,因为真正渲染 logo 的是另一条路径(见下),所以打 finding 标、不挂 pm:queue,严重度交 PM 分诊。

事实(基线 d44279598 实测)

packages/layout/src/AppShell.tsx:12-23 声明:

export interface AppShellBranding {
 primaryColor?: string;
 accentColor?: string;
 favicon?: string;
 /** Logo URL — passed to sidebar/navbar via context */
 logo?: string;
 title?: string;
}

useAppShellBranding(:122-231)是唯一消费 AppShellBranding 的地方,它实际读的只有 primaryColor / accentColor / favicon / title —— 连 effect 的依赖数组(:230)都写成 [branding?.primaryColor, branding?.accentColor, branding?.favicon, title],logo 不在其中。AppShell 本体(:233-265)也没有任何 context provider,所以注释里那句 「passed to sidebar/navbar via context」在代码里不存在。

且已经有调用方在喂它:apps/console/src/hooks/useBranding.ts:27 明确传了 logo: app.branding.logo 进 useAppShellBranding —— 那个值今天被静默丢弃。

为什么说「今天没人撞上」

侧栏里那个 logo 确实会显示,但它走的是另一条完全独立的路:packages/app-shell/src/layout/AppSidebar.tsx:194 直接从 app schema 读 activeApp?.branding?.logo,不经过 AppShellBranding。所以现象上「logo 正常」,坏掉的只是 AppShellBranding.logo 这个声明面和它的注释 —— 典型的 declared-but-unenforced 漂移。

可选修法(不预设,两条都不是本单要做的)

1. 删(ADR-0049 enforce-or-remove 的 remove 侧):AppShellBranding 去掉 logo,顺带清掉 useBranding.ts:27 那行喂值;真实入口是 app schema 的 branding.logo。
2. 兑现:给 AppShell 真加一个 branding context,让 sidebar/navbar 插槽能读到 —— 那是产品增强,得单独判。

无论走哪条,那行注释都必须跟着改:它现在描述的是一个不存在的机制,比缺注释更坏。

参考

• packages/layout/src/AppShell.tsx:12-23(声明)、:122-231(唯一消费方)、:230(依赖数组)、:233-265(无 provider)
• apps/console/src/hooks/useBranding.ts:27(喂值的调用方)
• packages/app-shell/src/layout/AppSidebar.tsx:194(真正渲染 logo 的那条路)
• app-shell.mdx 的导航示例 2/3 键错(label/icon 字符串)+ 教了一个被整个丢弃的 header prop + searchEnabled 下必抛 TypeError 的隐患 #4793(发现出处)、finding: app-shell.mdx 的 AppShellProps 声明块漏了 2 个真实 props(branding、rightRail/ADR-0057 P3a),读者从文档看不到它们存在 #4808 / packages/layout/README.md 的 AppShell 示例传了一个 header prop,而 AppShellProps 没有它 —— 照抄示例头部区永不渲染 #4817(同族的 AppShell 声明面漂移)

---

Generated by Claude Code

[os-support-ai]

Triage — first-touch grading (triage seat, session session_01KTguWpd7WNGYTGmSNY31RL): escalated to needs-user-decision, type Bug (the declared surface and its comment describe a mechanism that does not exist, and a real feeder's value is silently dropped).

Why this is the inbox and not the queue: the two fixes genuinely fork — (1) remove logo from AppShellBranding (+ the useBranding.ts:27 feed line, + the false comment) vs (2) actually build the branding context so sidebar/navbar can read it. Option 1 shrinks a published interface; option 2 is a product enhancement — both sides sit on the manual floor, and #4830 (app-shell.mdx prose) is explicitly waiting on this ruling.

Four-prong analysis:

• Platform long-term coherence: two independent logo paths (AppShellBranding vs app-schema branding.logo read directly by AppSidebar) is one path too many; removal converges on the single real one.
• Measured business pull: zero — the sidebar logo renders correctly today via AppSidebar.tsx:194; no user-visible defect, no consumer of the declared key.
• AI-agent error-resistance: a key that types cleanly, is fed by real code, and silently does nothing is exactly the declare-without-enforce trap; removal makes the false affordance unwritable.
• Startup scope discipline: remove beats declare-and-maintain; option 2 creates a permanent context-provider obligation with no demand behind it.

Recommendation: option 1 (remove), all four prongs align — but the published-surface deletion is yours to call. Ruling here also unblocks #4830.

---

Generated by Claude Code

[os-elon]

Maintainer ruling — recorded by the maintainer-directed PM session (session_01KspKtTajJmy3J37UhH8tcH, 2026-08-19). The 27-card objectui decision-inbox review (per-card four-axis analysis) was presented to the maintainer in that session's chat; the maintainer's verbatim reply: 「全部接受」. Adopted ruling, restated in full:

Ruling: Option 1 — remove logo from AppShellBranding

• Delete the key, the false "passed to sidebar/navbar via context" comment, and the dead feed line (apps/console/src/hooks/useBranding.ts:27). The single real entry point remains the app schema's branding.logo (read directly by AppSidebar.tsx:194) — one logo path, not two.
• Option 2 (build a real branding context) is rejected: a permanent context-provider obligation with zero demand; the logo already renders correctly today via the real path.
• This ruling unblocks finding: app-shell.mdx 的 Features/Styling 散文完全不提 branding 与 rightRail —— 键表已补齐(#4808/PR4829),散文半截待 #4818 裁定 logo 后写 #4830 (app-shell.mdx prose), which was explicitly waiting on it.

State: needs-user-decision → pm:queue.

---

Generated by Claude Code