mirror of
https://github.com/clash-verge-rev/clash-verge-rev.git
synced 2026-11-07 01:22:15 +08:00
Tunglies
40fd1d5012
* docs(agents): add frontend liveness constraints Add six liveness rules to the frontend guardrails covering dead state, unused exposed surface, unreachable fallback paths, duplicate side effects per interaction, unreachable mounts and unbounded resource lifecycles. These target defect classes that the existing CI gates (knip, eslint, arch:check) cannot detect mechanically. * refactor(frontend): remove dead states, refs and unreachable branches Drop state that can only hold its initial value (profiles page disabled flag, traffic graph currentFPS), a write-only window controls ref with its unconsumed imperative handle, a no-op appendData ref method, an unreachable gradient branch, an invisible fadeIn shell, constant-true subexpressions in the system info card, an empty click handler and a pointless useMemo. * refactor(frontend): drop unused params, props and api surface Remove the never-read _revalidate argument of mutateVerge and its 16 call-site placeholders, seven never-passed props of the split chip editor, the unconsumed refreshDecorated context member, the now-orphaned toggleFullscreen control, the unused translate argument of the notice message handler, the reserved-but-unset ServiceConfig.timeout field and unreachable branches in parseNoticeExtras. * refactor(types): remove dead provider view types superseded by bindings Drop the handwritten IProxyProviderItem and IRuleProviderItem interfaces: IProxyProviderItem is a stale duplicate of the generated ProxyProviderView contract, and neither has any references left in the tree. Keep IProxyItem and IProxyGroupItem: IConfigData still declares 'proxy-groups'?: IProxyGroupItem[], which builds on IProxyItem. * fix(rules): refresh once per visibility trigger The mount effect fired refreshRules and refreshRuleProviders unconditionally and again under the page-visible flag, double-firing both queries on mount and on every hide-to-show transition. Gate the refresh on visibility once so each trigger performs exactly one revalidation. * fix(setting): write auto launch patch once per toggle GuardState applies the optimistic onChange write before onGuard runs, so repeating the same onChangeData patch inside the guard handler duplicated every cache write and subscriber notification for the auto launch switch. * fix(setting): build viewer form defaults from a single source sysproxy, misc and tunnels viewers duplicated their form default literals in useState and open(), and the two copies in misc-viewer had already diverged (app log max size, app log max count, auto log clean). Extract a buildInitialValues factory per viewer and unify on the open() values, which are the only ones users could ever see. * fix(setting): mount only reachable proxy control viewers ProxyControlSwitches unconditionally mounted both SysproxyViewer and TunViewer while its switch rows are mutually exclusive, so every instance carried a dialog that could never open, each firing getEmbeddedServerPort or a clash query subscription on mount. Mount each viewer under the same condition as the switch row that opens it. SettingSystem also mounted its own SysproxyViewer and TunViewer whose refs were never opened there; the reachable entries are the ProxyControlSwitches rows, so the dead pair is removed. Viewer mounts across the app drop from eight (setting-system: two own + two per instance, proxy-tun-card: two) to three (one per rendered switch variant). * fix(delay): write pending state once per node in batch checks checkListDelay pre-marked every node as checking, help() re-marked it when picked up and measureDelay marked it a third time on entry, so each batch run queued three identical pending updates per node. Keep the pre-mark (immediate feedback for queued nodes) and drop the redundant marks along the chain. * fix(services): make retries viable and align polling freshness window Share no abort signal across retry attempts: after a timeout abort the old signal stays dead and every later fetch rejects immediately, so retries only burned backoff time. Also drop the system state query's staleTime: the wrapper maps it to SWR's dedupingInterval, which swallowed every other 3s poll tick while it exceeded the interval. * refactor(traffic): drop unreachable inline monitor fallback The inline traffic monitor duplicated the worker's message loop, snapshot throttling and aging logic but only runs when Worker is undefined or its constructor throws, which no supported Tauri webview or browser hits. Keep the worker as the single implementation and remove the mode switch and the pending-message queue that could only ever buffer the init message. * refactor(shared): replace the traffic error boundary with ErrorBoundary TrafficErrorBoundary maintained a second boundary system beside BaseErrorBoundary: a report builder that only console.logged constants in the Tauri webview, an onError that re-logged what componentDidCatch already logged, and a fallback wrapper with a single consumer. Fold both mount points into react-error-boundary (the primitive behind BaseErrorBoundary) with local fallbacks that keep the panel styling, message text and retry reset, log each error once, and drop the retry attempt cap and the stack-details collapse along with it. * refactor(hooks): drop the write-only error channel and key-rotating refresh The mihomo ws subscription's next callback accepted an error half that baseNext silently discarded while traffic, memory and log consumers kept constructing fallback payloads for it. Refresh minted a fresh SWR key per call via a localStorage timestamp, abandoning old keys in the cache forever. Reduce next to its data half and reset the snapshot under a stable key instead. * refactor(hooks): trim dead surface from proxy selection Drop the connection-cleanup option nobody ever disabled (behavior now unconditional), the returned changeProxy no consumer called and the two one-caller argument adapters; both call sites use the shared select entry directly. * refactor(services): drop the bespoke retry engine from the query wrapper The custom onErrorRetry existed only to honor a function-form retryDelay, which exactly one caller (the app data provider) used for exponential backoff. Fall back to SWR's built-in error retry and express that caller's cadence with constant options.
3.0 KiB
3.0 KiB
Frontend Architecture Guardrails
These rules supplement the repository's root AGENTS.md.
- Contract ownership. Generated event and notice contracts are owned by the backend wire contract. Handwritten payload types are acceptable when they match their producers. Event names, payloads and the typed notice table stay aligned across backend and frontend.
- Event ownership.
services/busowns event subscriptions, emissions and their lifetime. Components and pages consume the bus rather than subscribing independently; window lifecycle remains with its owning component. - State ownership.
storeowns shared event state and the snapshot reads that reconcile it through pure reducer actions. Query caches retain ordinary configuration and profile reads. Reads and live events share an ordering boundary so an older reply cannot replace newer authoritative state. Components keep local UI state. - Intent ownership. Mutating commands pass through the shared intent funnel. Resource ownership determines serialization; distinct requests are preserved, and success effects follow actual command success. Bespoke error flows retain their handling without duplicate or suppressed errors.
- Command ownership.
servicesowns backend command invocation and transport wrappers. Components and hooks use those boundaries; plugin mutations follow the same intent ownership as backend commands. - State liveness. Every
useState/useRefmember has a reachable write that differs from its initial value and a read that observes the difference. A value that can only ever hold its initial value is a constant: declare the constant and delete the state. A ref nothing reads is deleted, not kept. - Surface liveness. Anything a module exposes — props, parameters, context
members, imperative-handle methods — ships with at least one external caller
in the same change. "Reserved for future use" fields,
_-prefixed params that callers still pass, and error or callback channels that every receiver ignores are removed, not maintained. - Path liveness. A fallback or branch names the concrete runtime condition that reaches it. If no supported runtime can reach it, the branch is not added — or it replaces the primary path. Constant subexpressions and cleanup of resources that cannot exist yet are simplified away.
- Effect economy. One user interaction produces one state write and one command. A handler does not re-apply a value its wrapper already applied, and an effect does not re-run a refresh another branch of the same effect just ran.
- Mount economy. Components that issue commands or subscriptions on mount are mounted only where their UI is reachable. A dialog no rendered control can open stays unmounted, not mounted-and-idle.
- Resource bounds. Every cache key, timer and subscription a feature allocates is reused or released on refresh; refresh never allocates an unbounded sequence of new keys. Retries re-create per-attempt resources so a retry can actually succeed.