refactor(desktop): move Settings → Usage into a renderer feature slice

[liuxiaocs7]

Summary

Refactor: move Settings → Usage out of the frozen legacy renderer zone into a feature slice src/renderer/features/usage/, following the #3439 reference boundary (ports + services-context + ui). No product, visual, IPC, or copy changes — the Usage tabs (Activity / Providers / Models / Tools), the request-target tooltip, and the current read-only Pricing tab behave exactly as on main, including snapshot retention across section switches and Host-change fencing.

Refs #4425, #4582 (extraction only — the editable pricing editor and the composition adapter stay follow-ups, so this does not close the full #4425 scope) · Foundation: #4088 (R1 of #3439, whose remaining work now continues in #4582) · Unblocks #2015 / #4164.

Why

Since the renderer-architecture ratchet landed (#4088, R1 of #3439), the legacy AppShell closure is frozen — no new file may enter it and no legacy file's dependency count may grow. This blocks net-new Usage functionality (most immediately the editable pricing tab from #2015 / #4164, which #2015 requires to live inside the Usage tabs). Moving the surface into a feature (exempt from closure debt) unblocks it and shrinks legacy debt.

What changed

• New features/usage/:
  • ports.ts — UsageServices, narrow inward-facing: loadUsageStats(range) and updateUsageSettings(patch) take/return only UsageSettings / UsageStats, never the whole AppSettings.
  • services-context.tsx — UsageFeatureScope, the persistent state owner: a single tagged { range, value } snapshot, the reload ticket, unmount isolation, Host-generation invalidation, and the load-failure toast; plus useUsageServices() and useUsageStats(range). It also exposes an imperative fenceTarget() handle.
  • ui/usage-settings-view.tsx — the surface (overview + tabs + panels), now a disposable view: it reads the snapshot from the scope via useUsageStats and reloads on [range, targetKey].
  • ui/{usage-stats-table,metric-card}.tsx, controller/{action-guard,optimistic-settings-draft}.ts, index.ts, README.md.
• settings/usage-settings-page.tsx → thin legacy shim, split by mount level: UsageScopeMount (a re-export of UsageFeatureScope) and UsageSettingsPage (the disposable view). It binds only describeError (copy is a direct import of the validated locale catalog by the view) and touches no window.maka.
• settings/settings-surface.tsx: removed the usageStats state, reloadUsage, its reload effect, and the usageStats / onReloadUsage / runtimeHostEpoch prop threading. It now builds a host-bound loadUsageStats (same window.maka.settings.usageStats bridge path) plus an updateUsageSettings that projects the result to UsageSettings, mounts UsageScopeMount above the loading/error gate (so the snapshot survives a Skeleton/Banner state or a section change) with a host:epoch targetKey prop, renders the view in the section content slot, and calls the scope's fenceTarget() synchronously on a Host change (alongside the other Host-scoped resources). Its hook/state debt decreased (useEffect/useRef/useState); its dependency set is unchanged — the dependency-count reduction lands on the usage-settings-page.tsx shim (7 → 6).
• Regenerated renderer-architecture.json + docs/astryx-surface-file-inventory.{md,paths}.

Behavior parity with main

The lifecycle matches main's original surface:

• The loaded snapshot lives above the loading/error gate, so leaving/returning to Usage (or a Skeleton/Banner state) re-displays it immediately (stale-while-revalidate), not a blank re-fetch.
• A range switch shows loading, never the previous range's numbers (single tagged snapshot; a late or failed load can't fall back).
• A Host/generation change clears the snapshot and fences the in-flight load — synchronously at the Host event (fenceTarget()), before the re-render — so an old-Host load can't land. targetKey is a prop (not a React key), so a Host change resets the scope in place without remounting the rest of Settings.

One deviation from the composition-feature pattern (forced by the ratchet)

No platform/desktop adapter / no composition wiring — a transitional seam. settings-surface (a frozen closure file) can't import the feature or platform/, and usage stats are scoped to the settings-selected Runtime Host (a settings concept the app-global composition root does not have). So it assembles UsageServices and mounts the feature's UsageScopeMount + view via the thin shim; the ports + services-context structure matches the pattern, only the mounting seam adapts to the frozen boundary. When #4425's composition step lands, only this seam moves to composition/desktop-feature-services.tsx + a stateless platform/desktop adapter — the scope stays feature-owned.

(Copy is not a deviation: the view imports the validated locale catalog locales/settings-usage-copy.ts directly, which the ratchet exempts via isValidatedCopyCatalog — the same way workbar / goals / task-entry / session-navigation import their locales/*. Only the legacy describeError helper is injected by the shim.)

Verification

Against latest main: check-renderer-architecture --base origin/main passed; npm run typecheck (4 desktop projects + all @maka/*) 0 errors; check:asf-headers, astryx:surface-inventory, biome lint / format clean; Knip (apps/desktop + packages/ui) clean; the feature's usage-settings-view.test.ts (7 tests) passes — covering round-trip snapshot retention, range-scoping, Host-generation invalidation, load-completes-while-unmounted, late-load fencing, loading-gate survival, and synchronous fence-at-Host-event. Recommend a quick in-app smoke of the Usage tabs + a Host switch during review.

Review follow-up (addressed in this PR)

• Fixed a section round-trip snapshot loss by moving the scope above the loading/error gate (persistent UsageFeatureScope).
• Narrowed the UsageServices port to UsageSettings.
• Restored synchronous Host-change fencing (fenceTarget()), matching main.
• README/comments corrected to describe the current wiring; commit carries the Generated-by: Claude Code trailer.
• Deferred (non-blocking): a full SettingsSurface integration test, and de-duplicating the feature-local action-guard / optimistic-settings-draft copies.

AI use

• No generative tool made a substantive contribution
• Generative tooling made a substantive contribution

Tool(s) and scope: Claude Code (Claude Opus 4.8) — the dependency analysis, the extraction, and verification. Reviewed and submitted by the human contributor of record.

Checklist

• Tests cover the change and fail without it (feature lifecycle covered by usage-settings-view.test.ts; the rest is a behavior-preserving refactor)
• Lint, format, typecheck and the affected suites pass locally

Does this PR entail a change in behavior?

• Yes
• No — renderer-ownership refactor; behavior matches main

[Astro-Han]

I had a review ready for cfc12d9b and you force-pushed 32a08471 before I posted it, so this is against the new head. Build, the usage test file, all four typecheck projects, the architecture check, Biome, format and the surface-inventory regeneration are green locally.

The move itself is still faithful: the UI files match the old page line for line, class names and usage.css are untouched, the DOM is the same, so no before/after image is needed. The ratchet reason is real. But the new head undoes three things the body still claims, and the body was not updated, so right now a reviewer reading the description reviews a design that is no longer in the diff.

Behaviour vs main, two regressions.

• Leaving Usage and coming back no longer redisplays the snapshot. On main the stats live at the top of SettingsSurfaceContent and survive a section change; here they live in usage-settings-view.tsx:64, and the view is rendered only inside case 'usage' at settings-surface.tsx:1099, so a section switch unmounts it and the user comes back to four dashes until the reload lands. The body's "Review follow-up: fixed a section round-trip snapshot loss" describes the previous head, not this one.
• The two synchronous fences from main are gone with no replacement. commitSelectedRuntimeHostProfile at :391 no longer bumps the ticket and clears the snapshot, and the generation-change handler at :705 no longer clears Usage alongside the other three Host-scoped resources, the case main's comment there says must be fenced before the catalog refresh resolves. Clearing now waits for selectedRuntimeHostEpoch to change, which waits for the async reloadRuntimeHosts in the same handler; in that window Usage shows the previous generation's numbers and refetches with the old host. providerKey as a React key on UsageServicesProvider (usage-settings-page.tsx:56) covers the remount, not the window. selectedRuntimeHostKeyRef and selectedRuntimeHostEpochRef are now written and never read.

Range switching is still right: the tagged snapshot at view:109 is the same guard main had.

Tests. The body says seven tests covering round-trip retention, Host-generation invalidation, late-load fencing and the synchronous fence. The file has one (usage-settings-view.test.ts:95), and it covers range scoping, the one obligation that did not change. The three lifecycle obligations that did change have no test, and nothing runs through settings-surface, which is the seam this PR actually moves.

Still to shrink, unchanged from the previous head.

• features/usage/copy.ts duplicates locales/settings-usage-copy.ts. The README's reason (a shared import would be closure debt) is not what the checker does: isValidatedCopyCatalog exempts feature imports of a validated catalog, copyCatalogFailure returns undefined for that file, and workbar, goals, task-entry and session-navigation already import locales/* from feature code. Import it in the view and drop the file and the prop. With that, usage-settings-page.tsx can go too and settings-surface imports the feature directly; allowsMigrationDependency accepts a legacy edge swapped for a feature public path at equal count, and the closure loses one more file.
• controller/optimistic-settings-draft.ts and controller/action-guard.ts are copies of settings/optimistic-settings-draft-controller.ts and oauth-login-flow-guard.ts + use-action-guard.ts; only the originals have tests, and the originals keep nine consumers. Put the pure cores under src/shared/ (the checker treats it as external; the view already imports shared/runtime-host-identity) with a React shell on each side, or say in the body that the copies sit outside the existing tests.
• New on this head: settings/settings-metric-card.tsx is back with zero consumers while features/usage/ui/metric-card.tsx is its copy; knip reports it as an unused file and useUsageServices as an unused export. The previous head had this right. ports.ts:28 also cites a platform/desktop/create-usage-services.ts that does not exist and that the README says was deliberately not added.

So the ask: decide which design this PR ships. If it is this one, restore the two fences (a fenceTarget-style handle or the ticket bump at both Host sites), put the snapshot somewhere that survives a section change, rewrite the body to match, and add the tests the body already promises. If it is the previous one, the description and the deletions on cfc12d9b were closer. Either way the copy and controller duplication above should go in the same PR.

Evidence boundary: static read of 32a08471 against main 72eb982d; desktop main build, the usage test file, typecheck, architecture check, knip, Biome, format and inventory regeneration run locally; Storybook and Playwright not run.

AI-assisted review: drafted with Maka; I verified the snapshot location, the two removed fences against main, the test count and the copy-catalog exemption myself.

简体中文

评审写好时你 force-push 了新 head，这是对 32a08471 的。搬家本身仍忠实，DOM 不变。但新 head 撤销了正文仍在声称的三件事，正文没更新。相对 main 两处回归：离开 Usage 再回来快照不再重显（state 搬进了只在 case 'usage' 里渲染的 view）；Host 切换和 generation 变更时的两处同步 fence 被删且无替代，那段窗口里显示旧一代的数字并用旧 host 重取。测试只剩一条，覆盖的恰是唯一没变的义务。仍要收的：copy.ts 重复权威（checker 有豁免，四个 feature 已直接 import locales）；两个 controller 复制品无测试；新 head 又恢复了零消费者的 settings-metric-card.tsx，knip 报 unused。请先定这个 PR 发哪个设计，再改正文补测试；重复项同 PR 清掉。

[liuxiaocs7]

Thanks for the careful review, and sorry for the churn — your review landed on 32a08471, which a parallel checkout force-pushed over the cfc12d9b you were reading. I've restored the intended head and it's now at 7d8d67844. Every regression you flagged on 32a08471 was present only on that stale head; here's the mapping against the current one, plus your two "still to shrink" items.

The three things the body claimed but 32a08471 had undone — all present on 7d8d67844

• Snapshot survives a section round-trip. The snapshot no longer lives in the view. UsageFeatureScope (feature-owned) is mounted by settings-surface.tsx via UsageScopeMount above the loading/error gate; the disposable view reads it through useUsageStats. Leaving Usage (or a Skeleton/Banner state) keeps the snapshot and re-displays it immediately.
• Both synchronous fences restored. The scope exposes an imperative fenceTarget() (bumps the reload ticket + clears the snapshot). settings-surface calls it synchronously at both sites — commitSelectedRuntimeHostProfile and the generation-change handler — alongside the other Host-scoped resources, before the re-render. targetKey is a prop (not a React key): it clears/fences in place, so a Host change doesn't remount the rest of Settings. The now-dead selectedRuntimeHostKeyRef / selectedRuntimeHostEpochRef are removed.
• Tests. usage-settings-view.test.ts now has 7: round-trip retention, range-scoping, Host-generation invalidation, load-completes-while-view-unmounted, late-load fencing, loading-gate survival, and the synchronous fence-at-Host-event. Honest caveat: these mount the scope directly; a full SettingsSurface integration test (the seam this PR moves) is not here — I've left it as a follow-up and flagged it in the README.

Also on this head: settings/settings-metric-card.tsx is deleted, useUsageServices is no longer re-exported from the barrel (knip clean), the port is narrowed to UsageSettings, and ports.ts no longer cites the nonexistent platform/desktop adapter.

Your "still to shrink" items

• copy.ts duplication — fixed, and you were right about the exemption. I verified isValidatedCopyCatalog exempts a feature import of a validated catalog, and that goals / workbar / task-entry / session-navigation already import locales/* from feature code. So features/usage/copy.ts and the copy prop are gone; the view imports getUsageSettingsCopy from locales/settings-usage-copy.ts directly (architecture check green). I kept the thin shim only because it still injects describeError (settings-error-copy is not a copy catalog); dropping the shim entirely + a direct settings-surface → feature edge is a clean next step but I left it out of this pass to keep the diff contained — happy to do it if you'd prefer.
• Controller duplication — documented as a follow-up. controller/action-guard.ts and controller/optimistic-settings-draft.ts are feature-local copies covered here only indirectly (not by the legacy controller tests). The proper fix (pure cores under src/shared/ with a React shell each side) touches the legacy originals and their ~9 consumers, so per your "or say it in the body" option I documented it in the README Follow-up rather than widening this extraction PR.

I've also rewritten the PR description to match 7d8d67844 (it was describing the old design). The move itself is unchanged and still faithful line-for-line. Would appreciate a re-review against the current head when you have a moment.

[chihumyum]

Heads-up: #3439 is closed, and its remaining work now lives in #4582, which also tracks the Usage slice (#4425 / this PR). Could you add Refs #4582 to the description so this PR shows up in the new tracking issue's timeline? No change to the review itself.

[liuxiaocs7]

Hi, @chihumyum, thanks for the reminder!

[Astro-Han]

Approving 972ba8c9. Both regressions from last round are closed at the right places.

The snapshot now survives a section change: UsageScopeMount sits in LayoutContent above the loading gate, so switching sections unmounts only the view. Both synchronous fences are back, fenceTarget() at settings-surface.tsx:410 in commitSelectedRuntimeHostProfile and at :730 alongside the other three Host-scoped resources before reloadRuntimeHosts, and the two write-only refs are gone. copy.ts is deleted and the view imports the locale catalog directly, which the architecture check accepts. settings-metric-card.tsx moved rather than being copied, useUsageServices is no longer exported from the barrel, and ports.ts no longer cites a file that does not exist. knip is clean against main.

I compared the moved UI against the old page tag by tag and class by class. The only differences are the two wrappers that went to the shim and the type narrowing; no CSS changed and the DOM is identical, so this needs no before/after images.

Typecheck across all four projects, the architecture check against origin/main, 7/7 usage tests, format, lint and the surface-inventory regeneration all pass locally.

Two things before merge, then four small ones inline.

The body still describes copy.ts. "What changed" lists it and the first of the "two deviations" is a paragraph about it, while features/usage/README.md says one deviation and states that copy is not one. The squash message comes from the body, so this ends up in the permanent history.

Nothing tests the seam this PR moves. The seven tests are real and they pass, but usage-settings-view.test.ts:126 reconstructs the mount shape by hand and never loads settings-surface. The three lifecycle obligations are exactly what broke on 32a08471, and they broke with every test green. Move UsageScopeMount below the gate today, or delete the fenceTarget() call at :730, and all seven still pass. I am fine with deferring this, but say so in the README's Follow-up as well as the body; right now only the body mentions it.

The two controller copies stay deferred as we discussed. They are about 212 lines and the main source of the net addition, so keeping that note in the body matters.

Evidence boundary: static read of 972ba8c9 against main 8ea3c4f0; typecheck, architecture check, usage tests, format, lint, inventory and knip run locally; no Storybook or Playwright.

AI-assisted review: drafted with Maka; I verified the fence sites, the mount position, the tag-level UI comparison and the knip result myself.

简体中文

批准合并。上轮两条回归都在正确的位置关掉了。

快照现在能扛住断面切换：UsageScopeMount 挂在 LayoutContent 里、loading gate 之上，切断面只卸载 view。两道同步栅栏都回来了，settings-surface.tsx:410 在 commitSelectedRuntimeHostProfile 里、:730 与另外三个 Host 资源并列且在 reloadRuntimeHosts 之前，两个只写不读的 ref 也删了。copy.ts 删掉，view 直接 import locale 目录，架构检查放行。settings-metric-card.tsx 是 rename 不是复制，useUsageServices 不再从 barrel 导出，ports.ts 也不再提那个不存在的文件。knip 对着 main 干净。

我把搬过去的 UI 和原页面逐个标签、逐个 class 比对过，差异只有挪到 shim 的两个外层容器和类型收窄，CSS 一行没动，DOM 完全一致，所以不需要前后对比图。

本地四个 project 的 typecheck、对 origin/main 的架构检查、7/7 usage 测试、format、lint 和 inventory 重新生成全部通过。

合并前两件事，另有四条小的在行内。

正文还在描述 copy.ts。 "What changed" 列着它，"two deviations" 的第一条整段在讲它，而 features/usage/README.md 写的是 one deviation，并且明说 copy 不算 deviation。squash message 从正文取材，这段会留进永久历史。

没有任何测试穿过这次搬家真正动到的接缝。 七条测试是真的、也确实通过，但 usage-settings-view.test.ts:126 是手工复刻挂载形状，从不加载 settings-surface。那三条生命周期义务恰恰就是 32a08471 上坏掉的，而且坏的时候测试全绿。今天把 UsageScopeMount 挪到 gate 之下，或者删掉 :730 那行 fenceTarget()，七条依然全过。延后我没意见，但请在 README 的 Follow-up 里也写上，现在只有正文提到。

两个 controller 副本按我们说好的延后。它们大约 212 行，是净增行数的主要来源，正文里那段说明要留着。

[liuxiaocs7]

Thanks for the careful pass — addressed on top of 972ba8c9 in fb6f289f3.

Both "before merge" items

• PR body no longer describes copy.ts. Dropped it from "What changed", and the copy-as-prop "deviation Add Rive workflow Maka tool #1" is gone — there's one deviation now (the composition adapter). Copy is a direct import of the validated locale catalog (isValidatedCopyCatalog-exempt), matching the README. I also corrected the settings-surface line: its hook/state debt dropped, its dependency set is unchanged, and the dependency-count reduction (7 → 6) is on the shim.
• README Follow-up now records the deferred SettingsSurface integration test for the mount seam (it was only in the body before).

Inline

• usage-settings-page.tsx:52 — done. Replaced the pass-through forwardRef with export { UsageFeatureScope as UsageScopeMount } (−24 lines); the scope's props already were the mount contract.
• settings-surface.tsx:398 — done. usageTargetKey now builds on selectedRuntimeHostKey (runtimeHostSettingsKey = profileId:hostId) + epoch, one authority for the key shape.
• settings-surface.tsx:386 (useMemo) — I left this one, deliberately. A correct memo has to also stabilize updateSettings, which is a non-memoized async function closing over ~8 volatile values (selectedRuntimeHost, copy/locale, both request authorities, the client-settings ticket, and several props.* callbacks that are themselves non-memoized). A partial memo on usageServices would capture a stale updateSettings (e.g. an old-locale copy for the error toast) — a genuine behavior change I don't want to slip into a behavior-preserving extraction. You're right the eslint-disable is inert under Biome (preset: none), but it's the repo-wide convention for intentional exclusions (10 renderer files, including the use-optimistic-settings-draft / use-action-guard / use-oauth-login-flow originals these copies came from), so I kept it consistent rather than diverging in one feature file. No bug today (the effect deliberately excludes reload). Happy to do the updateSettings useCallback + memo as a focused follow-up if you'd prefer it in-tree.

Controller de-duplication stays deferred (noted in the body + README).

Verified locally against origin/main: check-renderer-architecture --base origin/main, astryx surface-inventory (unchanged), typecheck (renderer + main), Biome, knip (apps/desktop), and 7/7 usage-settings-view.test.ts.

简体中文

已在 fb6f289f3 处理:

• 正文不再提 copy.ts:从 "What changed" 去掉,copy-as-prop 的 "deviation Add Rive workflow Maka tool #1" 删除(现在只剩一处偏差,即 composition adapter);copy 是直接 import 已验证的 locale 目录(isValidatedCopyCatalog 豁免),与 README 一致。并修正了 settings-surface 那句:降的是 hook/state 债,依赖集合不变,依赖数下降(7 → 6)发生在 shim 上。
• README Follow-up 补上了 mount 接缝的 SettingsSurface 集成测试延后说明(之前只在正文里)。
• usage-settings-page.tsx:52:改成 export { UsageFeatureScope as UsageScopeMount }(少 24 行)。
• settings-surface.tsx:398:usageTargetKey 改用 selectedRuntimeHostKey + epoch,键形只有一处权威。
• settings-surface.tsx:386(useMemo)刻意保留:要做对必须连 updateSettings 一起 useCallback 稳定,而它闭包里抓了约 8 个易变值,只 memo usageServices 会抓到过期的 updateSettings(如错误提示用旧 locale 文案)——这属于"行为不变"重构不该引入的偏差。那句 eslint-disable 在 Biome(preset: none)下确实不生效,但它是全仓 10 个 renderer 文件的统一约定(含这些拷贝的源头 use-* 文件),故保持一致。当前无 bug。若你希望本 PR 内直接做,我可以把 updateSettings 也 useCallback 稳定掉。

controller 去重仍按约定延后(正文 + README 已注明)。本地对着 origin/main 全绿:架构 check、astryx inventory(无变化)、typecheck、Biome、knip、7/7 usage 测试。

[Astro-Han]

Re-approving on fb6f289f, since my previous approval was anchored to 972ba8c9. Both pre-merge items are closed and two of the inline notes with them.

The body now says one deviation and states that copy is not one, so it agrees with the README. The README's Follow-up carries the missing surface test, and it explains the gap better than my comment did. usageTargetKey builds on selectedRuntimeHostKey, so runtimeHostSettingsKey stays the only definition of that shape, and the shim collapsed to a re-export.

One note left over, not blocking: usageServices and describeError are still rebuilt every render, and the line suppressing the effect's dependency warning is an eslint-disable in a Biome-only repo, so it suppresses nothing. Whoever adds reload to those deps gets an infinite refetch. Worth a useMemo whenever you next touch the file.

Merging once CI is green on this head.

简体中文

在 fb6f289f 上重新批准，上一个绿勾锚在 972ba8c9。合并前那两件都关了，顺带带走两条行内。正文改成 one deviation 并说明 copy 不算，和 README 一致；README 的 Follow-up 把缺的 surface 测试写进去了，说得比我的评论还清楚；usageTargetKey 基于 selectedRuntimeHostKey，runtimeHostSettingsKey 仍是那个形状的唯一定义；shim 也塌成了 re-export。

剩一条不阻塞的：usageServices 和 describeError 每次 render 还是重建，而那行压制依赖告警的注释是 eslint-disable，这个仓库只有 Biome，等于没写。谁把 reload 加进依赖就会无限重取。下次动这个文件时顺手 useMemo 一下。

CI 在这个 head 上绿了就合。