chore: tier-A CLAUDE.md cleanup pass (12 surgical fixes) + 138-item deferred backlog

[Timidan]

Origin

10 zone-scoped subagents audited every nook and cranny of HexKit against the four CLAUDE.md principles:

1. Think Before Coding — surface confusion / parallel implementations
2. Simplicity First — speculative configurability / dead abstractions / impossible-case defenses
3. Surgical Changes — stranded TODOs / dead "backwards compat" stamps / inconsistent style
4. Goal-Driven Execution (workflow; not statically auditable)

Aggregate: ~103 high-confidence findings, ~47 lower-confidence findings across configs, styles, simple-grid, simulation-results, lifi-earn integrations, explorer, debug, other components, utils + types, contexts + services + hooks, api/, scripts/.

What this PR applies (12 files, -65 net lines)

Only the Tier-A subset — items that:

• Have zero behavior change
• Don't conflict with PR Implement LI.FI intents API integration and enhance composer route handling #20 (lifi-intents) / feat: Mezo Lens integration (Stack / Borrow / Save / Lock / Swap / Liquidity) + chain-aware EDB bridge #21 (mezo) / chore: codebase cleanup — remove legacy CSS, stubs, and unused components #22 (cleanup)
• Are unambiguous dead-code or trivial surface-confusion fixes
• Pass tsc --noEmit and vite build (verified: ✓ built in 17.24s)

Surface confusion (P1)

• src/contexts/debug/structStorageDecoding.ts:484 — const elementSize = elementType === 'address' ? 1 : 1 → const elementSize = 1. Result correct for both branches; the ternary signaled an intent that was never delivered.
• src/utils/storageSlotCalculator.ts:86 — parseSlotInput collapsed: both the 0x-branch and the default branch called BigInt(trimmed).
• src/utils/edbTraceConverter.ts:55 — same redundant-hex pattern in parseTraceValue.

Speculative API surface (P2)

• src/components/explorer/SolidityViewer.tsx — removed highlightLine, scrollToLine, theme props + their two useEffects. The sole caller ContractExplorer.tsx:536 never passes any of the three.
• src/components/explorer/storage-viewer/PackingVisualizer.tsx — removed unused rawHex prop + caller's rawHex={slot.value} at SlotRow.tsx:242.
• api/lifi-composer.ts:11, api/lifi-earn.ts:11, api/edb-proxy.ts:11 — dropped "HEAD" from ALLOWED_METHODS (no caller issues HEAD).

Dead exports / config (P3)

• scripts/bridge-security.mjs — removed sanitizeForLogging export (zero callers).
• scripts/bridge-config.mjs:25 — removed TRACE_DETAIL_COMPACT_ARTIFACTS env-derived constant (zero readers anywhere).
• eslint.config.js — trimmed ignores globs for nonexistent directories (current_bundle/**, test-results/**, test-*/**, **/test-*.js, test-app-*/**).

Verification

Check	Result
tsc --noEmit	0 errors
vite build	✓ built in 17.24s (exit 0)
Touches PR #20/#21/#22 areas?	No — explicitly skipped lifi-earn integrations, simulation-results, debug contexts beyond the L484 ternary, and anything PR #22 already deletes

---

Deferred backlog (138 findings)

The full audit output landed ~150 findings. The remainder are deferred because they fall into one of:

• Touches active-work areas (PR Implement LI.FI intents API integration and enhance composer route handling #20 lifi-intents, PR feat: Mezo Lens integration (Stack / Borrow / Save / Lock / Swap / Liquidity) + chain-aware EDB bridge #21 mezo, or PR chore: codebase cleanup — remove legacy CSS, stubs, and unused components #22 cleanup)
• Risky refactors (>50 LOC, requires judgment, design-intent unclear)
• Cross-cutting type changes that ripple across many files
• Overlaps with PR chore: codebase cleanup — remove legacy CSS, stubs, and unused components #22 (already in flight)

Backlog by zone

Zone 1: src/components/simple-grid — 17 findings

• tokenDetection/{functionDetection,erc165,diamond}.ts — 622 LOC of dead modules. functionDetection.ts imports the other two but its own export detectTokenType has zero call sites; live path is tokenDetection/universal.ts.
• types.ts:13-23, 86-302 — 4 dead prop interfaces (ContractCardProps, FunctionPanelProps, RawCalldataPanelProps, DiamondProgressProps) + SavedContractEntry duplicate + dead FACET_STATUS_COLORS/LABELS (re-declared in hooks/useDiamondState.ts). ~245 LOC.
• hooks/useContractState.ts:336-432 — Two parallel token-detection paths back-to-back (detectAndFetchTokenInfo then detectTokenType) with race-prone setTokenDetection writes.
• layout/ContractInfoCard.tsx:362-480 — IIFE has "Use universal detection" + "Fallback to old detection logic" branches that both classify ERC type. Leftover transitional code.
• tokenDetection.ts:21-23 — eventsParam: string[] = [] declared, threaded through 3 call sites, never destructured in the body. Pure speculative param.
• tokenDetection.ts:72 — const rpcUrl = … computed, never read.
• hooks/useSimulationState.tsx:78 — filters state initialized as {gas,full,storage,events} but GridContext.tsx:173 types it as {showOnlyErrors}. Type contract mismatch + zero reads.
• hooks/useFunctionState.ts — enhancedParameters/setEnhancedParameters, useEnhancedUI/setUseEnhancedUI, lookupFunctionSignatures import, generateCallData — all plumbed through context but never consumed.
• GridLayout.tsx:27-32 vs types.ts:25 vs useDiamondState.ts:12 — three parallel FacetDetailStatus/FacetDetail definitions.
• GridContext.tsx:265 vs hooks/useWalletHelpers.ts:19-33 vs types.ts:220 — three conflicting getWalletChainId signatures (sync vs async), masked by any everywhere.
• layout/FunctionParamsSection.tsx:51-488 — 437-line inline <style>{…}</style> re-injected on every render, targeting markup rendered by an external component. Belongs in a CSS file.
• layout/FunctionParamsSection.tsx:499-509 — Unreachable if inputs.length === 0 branch (top-of-function guard at 20-26 already returns null).
• layout/ExecutionSection.tsx:25-668 — 600+ line inline onClick handler holds full read+write+simulation control flow.
• buildGridContextValue.ts:111 — Returns any despite GridContextValue being fully typed. The typed interface is decorative; all consumers destructure as any.
• hooks/useContractState.ts:151-171 vs 286-305 — Two parallel "reset derived state" implementations that have drifted (inline omits setIsLoadingImplementation(false)).
• (2 lower-confidence)

Zone 2: src/components/simulation-results — 15 findings

• useSimulationPageHelpers.ts:29-51 vs gasHelpers.ts:3-28 — ContractContextExtras and SimulationResultExtras defined in both with overlapping fields.
• useSimulationPageHelpers.ts:9-25 — InternalInfoRow type + hasInternalInfo helper, zero external consumers.
• types.ts:8 — SimulatorTab union has assets | gas | debug values with no corresponding TabsTrigger (UI renders summary | contracts | events | state).
• useSimulationPageState.ts:39, 165, 193 — onReSimulate prop threaded through but no caller passes it (App.tsx:74 renders <SimulationResultsPage /> propless).
• StateTab.tsx:33-39 — normalizeHex single-use abstraction for one equality check.
• StateTab.tsx:252-255 — formatHex adds nothing over value ?? '0x0'.
• gasHelpers.ts:118-185 — Magic constants 30_000_000, 1_000_000, 100_000_000 + hardcoded txFee = "0 ETH" literal returned alongside computed gasUsed.
• useTraceRows.ts:27-493 — 466-line useMemo with 3 nearly-identical opcode-row builders (parallel implementations).
• useSimulationPageState.ts:154-156 — Separate effect just resets hasAttemptedLoad.current on id change; previous effect already handles via deps.
• useSimulationPageState.ts:430-561 — handleOpenDebug is 130 lines with 5 disjoint code paths.
• (5 lower-confidence)

Zone 3: src/components/integrations — 12 findings

⚠️ Defer — heavy overlap with active PR #20 lifi-intents.

• 4 parallel *ALIAS_GROUPS definitions across useVaultsByIntent / fallback / useIntentRecommendation / VaultRecommendations (silent divergence).
• 6 formatApy declarations + 3 formatTvl declarations across VaultList / VaultDrawer / IdleYieldBanner / simulator/formatters / fallback / useIntentRecommendation.
• IntentPanel.tsx:160-216 useMultiAssetVaults redundant 1-rank returning N identical objects.
• types.ts VaultFilters — 5 of 7 fields dead.
• ConciergeConfig.perChainTimeoutMs declared but useIdleBalances ignores it.
• 21+ unguarded console.log/warn in concierge hooks (production noise).
• DepositFlow.tsx (1856 LOC) — quote+simulate+approve+swap+deposit all in one file.
• (5 lower-confidence)

Zone 4: src/components/explorer — 11 findings (5 already applied above)

Applied: SolidityViewer props × 3, PackingVisualizer rawHex.

Deferred:

• useSlotResolution.ts:251 — knownKeys: string[] = [] param + dead L401-418 mapping-resolution branch (sole caller always passes []).
• useStorageEvidence.ts:741-754, 765-772 — addTraceSlots and clearEvidence exported with zero callers.
• fetchStorageLayout.ts:185-191 — Back-compat signalOrOptions instanceof AbortSignal overload; sole caller passes the options object.
• SourceTools.tsx:3,6 — 6 unused icon/tabs imports left over from URL-driven nav refactor.
• useAutoDiscovery.ts:309-314 — getKeysForSlot exported in controls interface, zero callers.
• useStorageViewerState.ts (737 lines, 52 hook calls, 60+ returned props) — kitchen-sink hook; candidates to split: slot probing (L66-72, L164-194, L467-544), CSS export (L671-698).
• (5 lower-confidence)

Zone 5: src/components/debug + contexts/debug — 14 findings (1 applied above)

Applied: structStorageDecoding.ts:484 ternary collapse.

Deferred:

• debugHelpers.ts:1-46 — 25-LOC dead "// for backward compatibility" re-export block; every consumer already imports solidityStructLayout directly.
• types.ts:100 + useDebugSession.ts:270 + useDebugPrep.ts:123 — rpcPort: number required by the type but never read; all call-sites pass 0 as stub.
• DebugWindow.tsx:395-403 — Dead DebugWindow export (wraps in DebugProvider); sole consumer uses DebugWindowWithContext.
• StackTracePanel.tsx:12-17, 59-64, 83-107 — Speculative isCollapsed, onToggleCollapse, onClose props; sole caller passes only className.
• useDebugSession.ts:157, 182, 190 + evalSnapshotResolver.ts:128-136, 217, 383 — Magic 500 snapshot-eviction inlined 7 times; existing setLimitedCacheEntry helper available.
• useDebugNavigation.ts:237-264 vs 366-389 — navigateTo = async (row) => defined identically (≈28 lines) in both stepUp and stepOver.
• useDebugEvaluation.ts + evalSnapshotResolver.ts — 21 inline if (import.meta.env.DEV) console.log(…) calls; existing debugLog helper does this gate already.
• evalSnapshotResolver.ts:28-34 — Stale comment cites "outer withTimeout … (15s)" but the real outer timeouts are 120s + 45s.
• DebugProvider.tsx:98-109 — decodedTraceRowsRef + traceRowsRef parallel refs to the same data with differing types; the any slippage in useDebugNavigation flows from this.
• (5 lower-confidence)

Zone 6: other src/components — 20 findings

• icons/IconLibrary.tsx — 69 hand-rolled SVG icon components alongside @phosphor-icons/react (imported in 81 places). Parallel implementations.
• HomePage.tsx:16 + TopBar.tsx:193-200 + MobileDrawer.tsx:73-75 — Three places synthesize a fake KeyboardEvent("Ctrl+K") to open UniversalSearchBar. Fragile pattern; replace with a useSearchToggle context.
• icons/ChainIcon.tsx:3-13,98-108 — ChainKey type + KEY_TO_ID lookup labeled "Legacy ... kept for backwards compatibility" but actively imported by NetworkSelector.tsx.
• TransactionBuilderHub.tsx:14 — TXHASH_REPLAY_KEY redeclared (also at transaction-builder/types.ts:30, useUniversalSearch.ts:94). Three copies of one storage key.
• execution-trace/useTraceState.ts — tokenMovementsExpanded, listRef: null, listHeight: 0, ROW_HEIGHT — dead virtualization scaffolding.
• transaction-builder/renderModeToggle.tsx — Single-use factory abstraction.
• MobileDrawer.tsx + Navigation.tsx + PersistentTools.tsx — Three independent TOOLS/TOOL_ROUTES arrays describing the same routes.
• shared/PageMeta.tsx:17 — description prop accepted then discarded as _description. Either drop the prop or actually emit <meta name="description">.
• transaction-builder/TransactionReplayView.tsx:97,106 — typeof window === "undefined" guards in a Vite SPA (no SSR path exists).
• signature-database/types.ts:44-69 — SIGNATURE_TAB_OPTIONS + TOOL_SUB_TABS dead.
• SignatureDatabase.tsx:30-104 — Extreme prop-drill (50 props split across 5 tabs).
• icons/IconMap.tsx:35-70 — Dual export Icon + UIIcons; only UIIcons is used.
• NotificationManager.tsx — Context wrapper around sonner whose 4 methods just forward to toast.success/error/warning/info.
• (6 lower-confidence)

Zone 7: src/utils + src/types — 24 findings (some overlap with PR #22)

• utils/transactionSimulation.ts — Stacked barrel over transaction-simulation/index.ts; 2 callers can import directly.
• utils/comprehensiveContractFetcher.ts + utils/multiSourceAbiFetcher.ts — Both are @deprecated compatibility shims with 1 in-repo caller each.
• types/abi.ts + types/index.ts — ABIFetchResult base never used standalone; only ExtendedABIFetchResult extends.
• utils/safe/tests/ — Orphan test files importing source modules that don't exist (../riskScorer, ../types, ../recoverSigners, etc.).
• utils/storageLayoutResolver.ts:135-184 — resolveSlotLabel + tryResolveMappingSlot exported but only called within the file.
• utils/resolver/index.ts:74-87 — 7 dead re-exports.
• utils/simulationArtifacts.ts:12-45 — Near-duplicate import+export of types from sibling file.
• utils/traceDecoder.ts — Stacked barrel over traceDecoder/index.ts.
• utils/resultFormatter.ts — 741-line class doing HTML+tooltip styling for one consumer.
• utils/tokenMovements.ts:9-12 — ERC20_TRANSFER_ABI, ERC721_TRANSFER_ABI declared, never referenced.
• utils/errorParser.ts:20-142 — parseError + ParsedError exported, zero external callers.
• utils/chains.ts — 19-line @deprecated re-export per its own header comment.
• types/debug.ts:556 — initFromTraceData types traceRows: any[] then comments // DecodedTraceRow[].
• (7 lower-confidence + cross-file findings)

Zone 8: contexts + services + hooks + config + chains + lib — 15 findings

• SimulationHistoryService.ts:765-798 — exportToJson/importFromJson zero callers.
• NetworkConfigContext.tsx:27-218 — 5 exposed fields (getRpcMode, isFallbackAllowed, isAlchemyAvailable, isInfuraAvailable, reset) consumed by no caller.
• networkConfig.ts:689-712 — Manager methods (getRpcMode, isAlchemyAvailable, etc.) only feed unused context wrappers.
• chains/registry.ts:512-513 — @deprecated export const SUPPORTED_CHAINS = CHAIN_REGISTRY is the dominant import across 13+ files.
• ToolkitContext.tsx — Entire context exists for one consumer (SmartDecoder).
• TraceVaultService.ts:127-154 — splitDecodedTraceRows exported, internal-only.
• services/debugBridgeProtocol.ts:37-340 — 9 of 12 exports consumed only internally.
• lib/monaco/index.ts:13-17 — 3 of 4 barrel re-exports unused externally.
• hooks/useDecodedTrace.ts:46-85 vs workers/traceDecoderWorker.ts:15-55 — parseJson + normalizeRawTrace duplicated byte-for-byte.
• (4 lower-confidence)

Zone 9: api/ — 11 findings (1 applied above)

Applied: dropped "HEAD" from ALLOWED_METHODS × 3 files.

Deferred:

• api/vertexAuth.ts — Entire 122-LOC file orphaned; LLM path is Gemini, not Vertex. (Already deleted by PR chore: codebase cleanup — remove legacy CSS, stubs, and unused components #22.)
• api/lifi-composer.ts + api/lifi-earn.ts + api/llm-recommend.ts — PROXY_SECRET + hasValidSecret dead defensive branch in all 3 (no caller sets the header; if env var ever set in prod, every browser request 403s).
• api/lifi-composer.ts vs api/lifi-earn.ts — Two nearly-identical 113/119-line proxies; extract createLifiProxy(base, tag) factory.
• api/llm-recommend.ts:75-78 — JSON.stringify(body) re-serializes to measure size; post-hoc size-gate runs after Vercel body parser already accepted.
• api/edb-proxy.ts:93-100 — Comment overstates security property of "no Origin header → allow".
• (5 lower-confidence)

Zone 10: scripts/ + root config — 10 findings (2 applied above)

Applied: sanitizeForLogging export removal + TRACE_DETAIL_COMPACT_ARTIFACTS removal + eslint ignore globs.

Deferred:

• package.json:14-16 — 3 npm scripts reference deleted files (scripts/perf/debug-stress-matrix.mjs, scripts/perf/live-qa-matrix.mjs, scripts/testnet-probe.js). (Already removed by PR chore: codebase cleanup — remove legacy CSS, stubs, and unused components #22.)
• vite.config.ts:173-178 — manualChunks.walletconnect + manualChunks.wagmi reference packages not in package.json dependencies. (Already cleaned by PR chore: codebase cleanup — remove legacy CSS, stubs, and unused components #22.)
• package.json:79-80 — Both happy-dom and jsdom in devDeps; no vitest config exists. At least one is dead.
• tsconfig.json:1-13 — Root tsconfig redeclares baseUrl + paths despite files: [] and only acting as a solution file. (Skipped due to IDE-resolution risk.)
• vite.config.ts:159-163 — define: { "process.env": "{}", "process.env.NODE_ENV": ... } sets the same key twice; order-dependent and fragile.
• (3 lower-confidence)

---

Recommended order of operations

1. Merge this PR (cleanup-v3) — surgical, low-risk, no conflicts.
2. Merge PR chore: codebase cleanup — remove legacy CSS, stubs, and unused components #22 (cleanup-v2) — already audited via 6 read-only agents + Codex CLI + Copilot + Codex GH bot. Mostly removes thin-stubs, dead CSS, dead exports.
3. Active PRs first — let Implement LI.FI intents API integration and enhance composer route handling #20 (lifi-intents) and feat: Mezo Lens integration (Stack / Borrow / Save / Lock / Swap / Liquidity) + chain-aware EDB bridge #21 (mezo) merge before tackling Zone 3 (integrations) backlog.
4. Pick a zone per follow-up PR — Zone 1 (simple-grid) or Zone 5 (debug) are biggest deferred wins; Zone 7 (utils barrels) is mostly mechanical.

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
web3-toolkit	Ready	Preview, Comment	May 28, 2026 1:35pm

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 3061f421e7

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[chatgpt-codex-connector]

Keep HEAD support consistent in EDB proxy

When a client uses HEAD against /api/edb (for example an availability check or metadata probe), this new allowlist rejects it with 405 even though the same handler still advertises HEAD in Access-Control-Allow-Methods and keeps special bodyless handling for HEAD before forwarding. This makes the CORS contract in api/edb-proxy.ts inconsistent with the actual method gate; either keep HEAD here or remove the remaining HEAD handling/header.

Useful? React with 👍 / 👎.

[Copilot]

Copilot encountered an error and was unable to review this pull request. You can try again by re-requesting a review.