[objectstack-fleet]

Requested by Sales · project thread

domain:ui#5 · os-sales · session_01L6bhgVwQZbHRRM9CaXeKif

Fixes #30311

Clause-②: no
Metadata-protocol: none

维护者速读

• 改了什么：控制台所有显示应用名的地方（应用切换器、侧栏标题、首页应用卡片/应用条/最近访问、无权限页、AI 对话、应用市场「打开应用」按钮、报表索引）改为直接显示服务端已翻译好的应用名；应用卡片的描述同理。
• 为什么改：客户在 .custom 配对包里给已安装应用改名后，服务端（fix(metadata-protocol,rest): a .custom pair's declared override is labelled in the ruled order on every /meta read #30353）已按裁定顺序返回新名字，但前端又用基础包的 apps.NAME.label 译文盖回去，中文下仍显示旧名。
• 风险与回滚：只改 ui/packages/app-shell 的读取顺序；草稿预览（?preview=draft）、键式标签、无标签应用仍走前端词条，未改名的应用显示不变。回滚即撤本 PR，无数据迁移。
• 先看：ui/packages/app-shell/src/hooks/useServedAppLabel.ts（新 helper 的取值顺序），再看 layout/AppSwitcher.tsx 一处调用点。
• 两分钟验证：pnpm --dir ui exec vitest run packages/app-shell/src/hooks/__tests__/useServedAppLabel-30311.test.tsx，预期 18 条全绿；修复前的取值顺序下其中 5 条是红的。
• 需要你做的：无，席位落地。

What changes

• New private hook useServedAppLabel (ui/packages/app-shell/src/hooks/useServedAppLabel.ts). appLabel(app) draws a served label (a string, or an inline locale map resolved by metadataText) as given; appDescription(app) does the same for description. The bundle (useObjectLabel().appLabel / appDescription, the apps.NAME.label lookup) is asked only for text no server translated: an item stamped _draft: true by ?preview=draft, a keyed { key, defaultValue } label (still resolved through t, as before), or an app with no label / description.
• Every app-shell surface that named an app through useObjectLabel().appLabel({ name, label: resolveKeyedI18nLabel(app.label, t) }) now calls useServedAppLabel().appLabel(app): 17 call sites in 11 files, taken from the tree at fdd06415 (AppSwitcher x3, AiChatPage x4, HomePage x2, UnifiedSidebar, AppHeader hidden-app menu, AppNoAccessEmptyState, AppCard label and description, HomeAppsStrip, MarketplacePage, MarketplacePackagePage, AppReportIndexView).
• useNavTargetLabel.ts and ui/packages/i18n/** are untouched (claim fences); the hook only imports the exported metadataText.
• Root changeset .changeset/30311-served-app-labels.md (@object-ui/app-shell patch).

Why

Since #30353 the server serves an overridden app's label in the ruled order (the .custom pair's own text over the base package's translation). The Console handed that served label to the bundle lookup as its fallback, so the base package's apps.NAME.label translation won it back and a renamed app kept its old name on zh-CN. The object / view half of #30311 landed in #30388 with the same served-first rule; this is the app half.

Tests

• ui/packages/app-shell/src/hooks/__tests__/useServedAppLabel-30311.test.tsx (new, 18 cases): the real hook over the real useObjectLabel inside a real I18nProvider with a packaged catalogue, en and zh-CN: a renamed served label and description draw as served; an unedited one shows the server's translation; an inline locale map resolves in the active language; controls for a _draft item, a keyed label, an absent / empty label and a translation-only description keep the bundle. Plus a census: no non-test source under app-shell/src other than the hook destructures appLabel / appDescription from useObjectLabel() (with a positive control that the walk reaches the hook and AppSwitcher.tsx, and that the pattern matches the banned shape).

Acceptance notes

• Evidence branch deviation. The dispatch asked for screenshots on a never-merged evidence branch; this card thread can push only its designated branch, so the PNGs were committed at 71a58ff3 and removed again in the next commit. The PR squash-merges, so they never reach main; the links below point at that commit.
• CommandPalette already drew resolveKeyedI18nLabel(app.label, t) without the bundle, so it showed the served name before this PR and is unchanged.
• The live leg exercised the app switcher pill, the sidebar title and Home (app card, recent row app name). The marketplace "Open app" button, the AI chat, the no-access state and the report index's other-app links are pinned by the census and the hook cases, not browser-measured.

Verification

Live, showcase --fresh, zh-CN, Console from ui/ src through Vite, 1440 wide

Override written the way the platform takes it: POST /api/v1/packages/com.example.showcase/ensure-customization (pair com.example.showcase.custom, created), then PUT /api/v1/meta/app/showcase_app?package=com.example.showcase.custom&mode=draft with the served app body, label: Showcase Hub (renamed-30311) and overrides: { package: 'com.example.showcase', basedOn: '0.1.0' }, then POST /api/v1/meta/app/showcase_app/publish?package=com.example.showcase.custom (seq 2). GET /meta/app/showcase_app then serves Showcase Hub (renamed-30311) under both Accept-Language: zh-CN and en; the zh-CN catalogue keeps apps.showcase_app.label = 功能展示.

Console, zh-CN, same override	origin/main app-shell sources (fdd06415, restored into the tree, Vite --force)	this branch
app switcher pill	功能展示	Showcase Hub (renamed-30311)
/apps/showcase_app page text matches	renamed 0, 功能展示 1	renamed 1, 功能展示 0
Home matches (app card + recent row)	renamed 0, 功能展示 1	renamed 2, 功能展示 0

Screenshots (commit 71a58ff3):
before app ·
after app ·
before Home ·
after Home

Tests, ablation, typecheck, lint (sources at 6f7c06c)

• New pin: Test Files 1 passed (1), Tests 18 passed (18), lock VERDICT command-exit 0.
• Ablation 1 (via scripts/ablation-replace.mjs, anchor 1 to 0, restored blob == HEAD, git diff HEAD empty): the hook's served-text rung replaced by return undefined (the old bundle-first order) turns exactly the 5 predicted cells red: renamed label en / zh-CN, inline locale map, renamed description en / zh-CN; Tests 5 failed | 13 passed (18).
• Ablation 2: AppSwitcher.tsx back on useObjectLabel() turns the census red naming layout/AppSwitcher.tsx; Tests 1 failed | 17 passed (18); restored, blob == HEAD.
• Consumer sweep: every test file under ui/ that names one of the 11 changed modules or appLabel (310 files): Test Files 310 passed (310), Tests 2598 passed (2598), lock VERDICT command-exit 0.
• turbo run type-check --filter=@object-ui/app-shell: Tasks: 68 successful, 68 total, VERDICT command-exit 0.
• eslint on the changed files: 0 new errors; the 2 errors it reports (react-hooks "Cannot create components during render" in AppCard.tsx and HomeAppsStrip.tsx) are on origin/main unchanged.
• ui/scripts/check-new-cross-file-line-citations.mjs: 0 new, exit 0.

Derived gates (dispatch-gates --commands, head 6f7c06c)

node scripts/pm/dispatch-gates.mjs --commands --repo objectstack-ai/objectstack derives 36 commands from 14 paths; each was run with its exit code captured before any pipe: all 35 node / pnpm check commands exit 0, and pnpm --dir ui exec vitest run scripts/ ran under os-verify-lock with --maxWorkers=2 (result in the os-dev-report on #30311). The two evidence commits add and remove the same files, so the derived set is unchanged at the final head.

Human Minimum

• 1. Schemas start as Zod; packages/spec holds no runtime logic.
• 2. Every name I added uses the casing for its kind.
• 3. No formatter ran; pnpm lint passes.
• 4. One issue, one branch off an up-to-date main, one pull request.
• 5. A change that publishes carries a changeset, and both declaration lines are filled in here and in the changeset.
• 6. packages/spec touched: its generated artifacts are regenerated and committed. (not touched)
• 7. No hand edits to content/docs/references/, packages/*/CHANGELOG.md or content/docs/releases/.
• 8. Title, body and comments are in English.
• The Before Submitting list in CONTRIBUTING.md is done.

🤖 Generated with Claude Code

https://claude.ai/code/session_01L6bhgX1ZNco5W3wXZFLVbh

---

Generated by Claude Code

[objectstack-fleet]

domain:ui#5 · os-sales · session_01L6bhgVwQZbHRRM9CaXeKif

维护者速读

• 改了什么： 控制台里所有显示应用名的地方，改为直接显示服务端已翻译好的应用名。涉及应用切换器、侧栏标题、首页卡片和应用条、无权限页、AI 对话、应用市场「打开应用」、报表索引。应用卡片的描述也一样改。
• 为什么改： Console sidebar and recent list re-translate an overridden object, list view or app label with the base package's translation, over the server's answer #30311 的应用名半边。客户在 .custom 配对包里给已安装的应用改了名，服务端（fix(metadata-protocol,rest): a .custom pair's declared override is labelled in the ruled order on every /meta read #30353）已经下发新名字，但前端又用基础包的 apps.NAME.label 译文把它盖回旧名。
• 风险与回滚： 只改 ui/packages/app-shell 读取名字的先后顺序。草稿预览、键式标签和没有标签的应用仍按原来的方式查词条。回滚就是撤销本 PR。
• 需要您做的： 无。本 PR 不在受管面，共 349 行，Clause-②: no。席位会经合并队列落地。
• 席位意见： ACCEPT。

席位核对 — ACCEPT · domain:ui#5 · head b5a93b87160dd1930a5cc21d3564bde1031636c6

• 形态： draft，作者 objectstack-fleet[bot]（中继 pr_create），无 assignee，无 review request，目标 main，Fixes #30311（应用名是本卡最后剩下的半边，合并后关卡）。共 14 个文件，+296 −53。check-governed-merges --pr 30443：NOT governed；349 行，未超 3000。
• 契约面： 不碰 packages/spec/**，不碰 governed 路径，不改 ui/packages/i18n/**（appLabel 的查找顺序原样保留），也不新增 i18n 键。新 hook useServedAppLabel 属于 app-shell 私有，没有导出到包入口。认领和 changeset 都写的是 Clause-②: no / Metadata-protocol: none，与 diff 一致，四面都不欠复核。
• 前提实测： 服务端读取门 meta-item-read-gate.ts 的 PACKAGED_BASE_ACCESSORS 有 app 行（PR fix(metadata-protocol,rest): a .custom pair's declared override is labelled in the ruled order on every /meta read #30353），/meta/app 下发的是已翻译的 label。改名后用 .custom 覆盖，zh-CN 下修复前显示「功能展示」，修复后显示新名字（卡线程 showcase 实测，截图见 PR）。
• 抽查：
  • 取值顺序：served 字符串或 inline map（经 metadataText 解析）优先；_draft: true、键式 { key } 和空值仍走 bundle。这与 PR fix(app-shell): draw a served object or list view label as served in the Console sidebar, recent list and object list header #30388 对对象/视图定的规则一致。
  • 语言切换：ConsoleShell.tsx 用 key={language} 重挂 MetadataProvider，并带上 Accept-Language 重新读取，所以 served label 会跟着新语言重读，不会停在旧语言。
  • 两个应用市场按钮读的都是 phase === 'served' 的 app。
  • 17 处调用点全部改完。测试里另有一条普查：除这个 hook 外，app-shell/src 里的非测试源码不得再从 useObjectLabel() 解构 appLabel / appDescription，并带正控。
• 门禁 check-runs： b5a93b87 上 55 个 run：44 success，11 skipped，0 失败。
• 测试： 新文件 18 条用例：真实的 hook 套真实的 useObjectLabel，外面是真实的 I18nProvider，en 和 zh-CN 各跑一遍。按卡线程报告，退回旧取值顺序时有 5 条转红。
• 串行约束： Record page, record form, drawer and preview card still show the base translation of an object renamed in a .custom override #30390（domain:ui#3）改 useNavTargetLabel.ts；本 PR 只从那里 import metadataText，没改那个文件。PR fix(app-shell): a marketplace README fits its detail page; badges render as images, tables as tables #30426 已合并。
• 接受的偏差： 证据截图放在 71a58ff3，下一笔 b5a93b87 删掉；squash 合并不会把它带进 main。正文首行是项目署名块，席位签名在第 3 行。
• 范围外去向： 无。
• 落地条款： Fixes #30311。本席位按普通队列在这个 head 上落地：relay pr_ready + automerge_enable。MERGED 后核对 Console sidebar and recent list re-translate an overridden object, list view or app label with the base package's translation, over the server's answer #30311 已关闭、pm:dispatched 已摘。