Files
maka/docs/archive/frontend-simplification-map-2026-07-13.md
T
agent-radar 7be535059e
Dependency audit / audit (push) Canceled after 0s
CI / plan (push) Canceled after 0s
Gitoxide helper admission / macos-latest (push) Canceled after 0s
Gitoxide helper admission / ubuntu-latest (push) Canceled after 0s
Gitoxide helper admission / windows-latest (push) Canceled after 0s
Runtime Host peer admission / quality (push) Canceled after 0s
Windows recovery / windows_recovery (push) Canceled after 0s
CI / heavy (push) Canceled after 0s
CI / test (push) Canceled after 0s
源码快照 @ 2026-09-01 (source-only, 剔除非源码素材)
2026-09-01 19:05:14 +08:00

182 lines
14 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
<!--
Licensed to the Apache Software Foundation (ASF) under one
or more contributor license agreements. See the NOTICE file
distributed with this work for additional information
regarding copyright ownership. The ASF licenses this file
to you under the Apache License, Version 2.0 (the
"License"); you may not use this file except in compliance
with the License. You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing,
software distributed under the License is distributed on an
"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
KIND, either express or implied. See the License for the
specific language governing permissions and limitations
under the License.
-->
# Frontend Simplification Map (2026-07-13)
Maintainer goal: the project has run long; prune redundant/messy frontend code at
architecture level. Method: measure first (knip + wc + grep), stage rounds, gate each
on the full suite + typecheck + dead-css + alignment auditor.
Baseline (this tip, 1301404d): 45.5K lines TS/TSX (non-test) + 22.0K lines CSS.
Hotspots: app-shell.tsx 1733 · chat-turn 970 · bot-chat 961 · OnboardingHero 955 ·
provider-oauth 870 · composer 866 · scheduled-task 865 · connection-detail 861.
CSS: maka-tokens 1509 · onboarding 916 · scheduled-tasks 864 · skills 833.
Knip verification notes: storybook stories + ui .test.tsx flagged "unused" are FALSE
positives (apps/desktop/.storybook globs both story roots; ui test runner executes
dist/**/*.test.js). Real finds verified by hand before acting.
## Rounds
- [x] **A — SHIPPED (b2a1afd6): knip governance + dead code + dep hygiene.** 6 symbols deleted, 1 demoted, dev-hmr.mjs removed; @base-ui/react→deps, streamdown→devDeps (test-only; deviation on correctness), overlayscrollbars NOT declared (overlay-scrollbars contract forbids it — knip ignoreDependencies instead); scroll-area.tsx retained (a contract reads its content — follow-up: remove file+test together); knip.json (entries per workspace, ignoreExportsUsedInFile, -knipignore tag) + 2 CI steps in the typecheck job; ignore reasons documented below. Gates: desktop 2397/2397, ui 125/125, typecheck, 4 static checks, auditor — all identical before/after.
- Delete packages/ui/src/primitives/scroll-area.tsx (orphaned by overlay-scroll-area)
- ~40 unused exports/types across desktop main+renderer and packages/ui — for each:
grep __tests__ first (contract tests read source text; some pins assert the export
form) — demote `export` or delete the symbol per-site, never break a pin silently
- Declare real deps: apps/desktop needs streamdown, @base-ui/react, overlayscrollbars
(currently resolving via hoisting — fragile)
- Add knip.json (workspaces, storybook entry globs, test entry globs) + CI step so
dead code cannot re-accumulate
- [~] **B — app-shell.tsx decomposition (flagship) — 4/5 blades SHIPPED (branch
refactor/app-shell-decomposition), 1733 → 1666 lines, zero behavior change.**
Gates identical each commit: desktop 2397/2397, ui 125/125, typecheck, dead-css,
knip (desktop+ui); final alignment auditor (AUDIT_PORT_BASE=19300) clean on all 9
fixtures + branch-vs-baseline CDP pixel captures identical (turn-narrative,
module-skills, settings-general).
1. use-pending-action-registry — SHIPPED first (only blade that removes dup). ONE
generic useKeyedPendingRegistry replaces the four hand-rolled keyed sets
(turnActions state+timers, sessionRow, permissionMode, sessionModel). keysRef
stays a stable Set so factories + unmount cleanup are byte-identical. Re-pinned
sticky-model / status-presentation / row-actions-fail-soft contracts.
3. use-project-context — SHIPPED. appInfo, branchList/pending, recentProjectPaths,
projectPicker pending+refs + createAppShellProjectActions wiring.
4. use-module-data — SHIPPED. skills/managedSkillSources/bundledSkillCatalog/
scheduledTasks + both skill/plan action factories; surface-active predicates
injected.
5. use-shell-connections — SHIPPED (partial). connections/defaultConnection +
connectionsEqual + refreshConnections + handleConnectionEvent. theme/userLabel/
defaultPermissionMode stayed: default-permission-mode contract pins the
defaultPermissionMode useState + refreshShellSettings + closeSettings mirror to
app-shell.tsx specifically, and the theme setters have multiple app-shell writers
(visual-smoke, settings-overlay onChange) — moving them needs setter injection
with no net simplification.
2. use-shell-navigation — SKIPPED (disproportionately risky, per the "ship what's
done" rule). Its two anchors — openSessionInChat and closeSettings — are pinned
to app-shell.tsx by source-slice contracts, so they cannot move. Its highest-value
movable code (the stable bridge callbacks searchModalOnNavigate /
paletteOnSelectSession / paletteOnOpenSearchModal / useSkillInChat) carries
PR-FE-BUG-HUNT-0 runtime identity-stability semantics that have ZERO source-pin or
e2e coverage — a subtle extraction error would silently regress search-during-
stream with no gate to catch it. A state-only move nets ≈0 app-shell lines because
every setter (setNavSelection ×15 sites, setSearchScrollTarget via the pinned
openSessionInChat/createSession, setSettingsOpen via the pinned closeSettings) must
be threaded straight back out. Left in place with this note.
Note: the map's < 900 target is not reachable through the five state-cluster blades
alone — app-shell's bulk is the derived-value block (~210 lines of model/thinking/
alert memos) and the JSX return (~340 lines), neither of which the blade definitions
cover; reaching < 900 would require extracting those + splitting the JSX into
sub-components (out of scope, separate risk).
- [x] **C — SHIPPED (refactor/css-token-consolidation): CSS strata consolidation.**
Census (machine-generated, var() consumers across all CSS+TSX): reference-shell.css
23 defined → 16 dead (removed), 3 live color-aliases moved to maka-tokens
(--color-bg-container/--color-border-tertiary/--color-text-quaternary), 4 live
layout-locals kept in-file (--agents-layout-bg/--agents-content-area-bg/-gap,
--sidebar-width). theme-glass.css 2 token overrides (darwin --color-bg-container light+dark,
--color-text-quaternary) relocated to maka-tokens; glass-material + text/label RULES stay.
maka-tokens.css: added token-authority README (authoritative --background family vs
compatibility --color-* aliases, alias policy) + condensed the superseded hue-80 archaeology
(it named deleted tokens). Both themes migrated (light :root + .dark + darwin light/dark).
NO computed value changed — pure reorg; the shipped `--color-bg-container: var(--background)`
exception kept as-is. maka-tokens internal 0-consumer tokens are all governance-contract
scale members (z-index/control-height/spacing/radius/406) — re-pinned, NOT deleted.
Gates: desktop 2397/2397, ui 125/125, typecheck 0, check-dead-css clean, knip desktop+ui 0,
auditor exit 0. CDP light+dark captures (turn-narrative/module-skills/settings-general/first-run)
before/after — no visual diff.
- [x] **D-1 — SHIPPED: shared useMountedRef + last formatBytes fork.** Case-insensitive
re-census found the mounted-guard boilerplate at ×38 (not ×6 — the first grep missed
`fooMountedRef` casings). Shipped: `useMountedRef` lives in @maka/ui (exported from
index) so both workspaces reach it; converted the 6 canonical `mountedRef/
onboardingMountedRef` sites (OnboardingHero ×2, password-input, daily-review/
general/permission-center settings pages) and re-pinned 5 contracts to the
shared-hook form; voice formatVoiceBytes (last formatBytes fork) deleted in favor
of the @maka/ui helper. Deliberately NOT converted: use-workspace-instructions-
controller (lifecycle-counter variant, not boilerplate) and app-shell.tsx
rendererMountedRef (Round B owns that file).
- [x] **A follow-up — orphan scroll-area.tsx removed.** primitives/scroll-area.tsx
(34 lines, zero consumers, never exported from the ui index) deleted together with
its knip ignore; the overlay-scrollbars contract's per-file assertion upgraded to a
repo-wide ban on @base-ui react scroll-area imports (stronger invariant, no
coverage lost).
- [x] **D-2 — SHIPPED: mounted-guard long tail.** Converted 34 of the 35 census
`*MountedRef` sites to `useMountedRef` — 20 renderer settings sites, 4 other
renderer sites (OnboardingHero readyHero, FirstRunChecklist, artifact-pane,
browser-panel), 10 packages/ui panels (chat-turn, chat-model-switcher, search-modal,
scheduled-task-panel, clipboard-feedback, skills-panel, composer, permission-dialog,
session-history-list, daily-review-panel). Kept each site's companion-ref cleanup
effect and its ref name; deleted the whole effect only where it did nothing but the
mounted flag (browser-panel, permission-dialog). packages/ui sites import the hook
from `./use-mounted-ref.js` per house style. Re-pinned ~30 contract assertions across
~20 test files to the shared-hook shape (definition lines + effect blocks). The
useRef(false) variants all read the flag only inside async handlers — no pre-effect
reads — so flipping to true-initial semantics is behavior-preserving. Deliberately
NOT converted: use-memory-settings-controller (lifecycle-counter variant — cleanup
reset is guarded by a lifecycle counter and reads combine mounted with lifecycle
equality, same shape as use-workspace-instructions-controller) and app-shell.tsx
rendererMountedRef (Round B owns that file).
- [~] **E — app-shell derived-value extraction (Round B follow-on) — blade 1 SHIPPED,
blade 2 SKIPPED. branch refactor/app-shell-view-split. app-shell.tsx 1680 → 1562.**
1. **Derived-value extraction — SHIPPED (2 commits).** The whole ~210-line derived
block moved into two pure-derivation hooks following the use-shell-connections /
use-project-context house style, zero behavior change, every memo keeping its exact
dep array + referential stability:
- `use-shell-chat-model.ts` (195 lines): model/thinking selection (chatModelChoices,
active/new-chat model+label, thinking-variant lists, sticky-pick validation, both
pending new-chat states) + the two chat-header alert memos. openSettingsSection is
injected so chatConnectionAlert keeps its identical exhaustive-deps-excluded memo.
- `use-shell-live-turn.ts` (112 lines): live-turn projection (activeShellRunUpdates,
streaming/thinking slices, streamingSessionIds pulse set, liveTools/
hasInFlightLiveTools) + the #646 turn-wait cues. `activeLiveTurn` stays pinned in
app-shell.tsx (streaming-timeline source-slice contract) and is passed in.
Re-pinned: added both files to renderer-shell-source-helpers combined allowlist;
added use-shell-chat-model.ts to the composer-new-chat model-picker contract's two
subset reads (pendingNewChatModel / validPendingNewChatModel / newChatThinkingLevel
declarations moved into the hook). All other model/live-turn contracts read combined
source and auto-followed via the allowlist.
2. **JSX return split — SKIPPED (disproportionately risky + net-negative, per the
ship-what's-done rule; Round B skip note is the model).** The ~340-line return's
content area is irreducibly coupled to ~110 AppShell locals, and every meaningful
chunk is pinned to app-shell.tsx by a DIRECT-read (non-combined) contract: ChatView
`liveTurn={activeLiveTurn}` (streaming-timeline), Composer `onPickAttachments`/
`onAttachFilePaths` (attachment-frontend) + `onPickNewChatModel` (composer-new-chat),
SessionListPanel `statusGroups={sessionListGroups}` (session-project-view), the
DailyReviewPage `onCopyMarkdown` (daily-review-copy-feedback), and the onboarding
`onSkip` handler (onboarding-one-time-regression). Extracting any of them into a
layout sub-component (a) forces ~50–110 props of straight-through drilling that ADDS
net interface/destructure boilerplate rather than pruning it (counter to the round's
goal), (b) requires structurally re-pinning 5+ behavioral contracts that specifically
assert "the shell orchestrator wires handler X into element Y", and (c) still lands
app-shell.tsx ≈ 1300 — the ≤1100 target is not safely reachable without over-
extraction under the zero-behavior mandate. Left in place with this note; the
derived-value extraction (blade 1) captures the genuine simplification.
Gates (each commit): desktop 2399/2399, ui 125/125, full typecheck 0, check-dead-css
clean, knip desktop+ui 0. Final: alignment auditor (AUDIT_PORT_BASE=19900) exit 0, all
9 fixtures clean. CDP branch-vs-baseline captures (real Electron, light+dark 1280) of
turn-narrative / module-skills / settings-general / first-run: module-skills + first-run
byte-identical; settings-general independently non-deterministic (baseline itself yields
two hashes across repeated passes — pre-existing capture flake, unrelated); turn-narrative
differs ONLY in a 311×24px region at the very bottom of the frame — the composer footer
git-branch chip, which renders the worktree's real HEAD (the baseline had to be captured
in DETACHED-HEAD state since the `main` branch ref is held by the concurrent worktree, so
the chip shows `—` vs the feature-branch name). Pixel-diff bbox confirmed x:[1106-1417]
y:[1570-1594]; every other pixel identical, and the chip-less fixtures are byte-identical
— i.e. the derivation extraction is a proven render no-op.
Update checkboxes as rounds ship. Every round: suite + typecheck + dead-css +
alignment auditor + CDP spot captures, exit-code gated.