DeskClaw/refactor.md

# Refactor Summary

## Scope
This branch captures local refactors focused on frontend UX polish, IPC call consolidation, transport abstraction, and channel page responsiveness.

## Key Changes

### 1. Frontend IPC consolidation
- Replaced scattered direct `window.electron.ipcRenderer.invoke(...)` calls with unified `invokeIpc(...)` usage.
- Added lint guard to prevent new direct renderer IPC invokes outside the API layer.
- Introduced a centralized API client with:
  - error normalization (`AppError`)
  - unified `app:request` support + compatibility fallback
  - retry helper for timeout/network errors

### 2. Transport abstraction (extensible protocol layer)
- Added transport routing abstraction inside `src/lib/api-client.ts`:
  - `ipc`, `ws`, `http`
  - rule-based channel routing
  - transport registration/unregistration
  - failure backoff and fallback behavior
- Added default transport initialization in app entry.
- Added gateway-specific transport adapters for WS/HTTP.

### 3. HTTP path moved to Electron main-process proxy
- Added `gateway:httpProxy` IPC handler in main process to avoid renderer-side CORS issues.
- Preload allowlist updated for `gateway:httpProxy`.
- Gateway HTTP transport now uses IPC proxy instead of browser `fetch` direct-to-gateway.

### 4. Settings improvements (Developer-focused transport control)
- Added persisted setting `gatewayTransportPreference`.
- Added runtime application of transport preference in app bootstrap.
- Added UI option (Developer section) to choose routing strategy:
  - WS First / HTTP First / WS Only / HTTP Only / IPC Only
- Added i18n strings for EN/ZH/JA.

### 5. Channel page performance optimization
- `fetchChannels` now supports options:
  - `probe` (manual refresh can force probe)
  - `silent` (background refresh without full-page loading lock)
- Channel status event refresh now debounced (300ms) to reduce refresh storms.
- Initial loading spinner only shown when no existing data.
- Manual refresh uses local spinner state and non-blocking update.

### 6. UX and component enhancements
- Added shared feedback state component for consistent empty/loading/error states.
- Added telemetry helpers and quick-action/dashboard refinements.
- Setup/settings/providers/chat/skills/cron pages received targeted UX and reliability fixes.

### 7. IPC main handler compatibility improvements
- Expanded `app:request` coverage for provider/update/settings/cron/usage actions.
- Unsupported app requests now return structured error response instead of throwing, reducing noisy handler exceptions.

### 8. Tests
- Added unit tests for API client behavior and feedback state rendering.
- Added transport fallback/backoff coverage in API client tests.

## Files Added
- `src/lib/api-client.ts`
- `src/lib/telemetry.ts`
- `src/components/common/FeedbackState.tsx`
- `tests/unit/api-client.test.ts`
- `tests/unit/feedback-state.test.tsx`
- `refactor.md`

## Notes
- Navigation order in sidebar is kept aligned with `main` ordering.
- This commit snapshots current local refactor state for follow-up cleanup/cherry-pick work.

## Incremental Updates (2026-03-08)

### 9. Channel i18n fixes
- Added missing `channels` locale keys in EN/ZH/JA to prevent raw key fallback:
  - `configured`, `configuredDesc`, `configuredBadge`, `deleteConfirm`
- Fixed confirm dialog namespace usage on Channels page:
  - `common:actions.confirm`, `common:actions.delete`, `common:actions.cancel`

### 10. Channel save/delete behavior aligned to reload-first strategy
- Added Gateway reload capability in `GatewayManager`:
  - `reload()` (SIGUSR1 on macOS/Linux, restart fallback on failure/unsupported platforms)
  - `debouncedReload()` for coalesced config-change reloads
- Wired channel config operations to reload pipeline:
  - `channel:saveConfig`
  - `channel:deleteConfig`
  - `channel:setEnabled`
- Removed redundant renderer-side forced restart call after WhatsApp configuration.

### 11. OpenClaw config compatibility for graceful reload
- Ensured `commands.restart = true` is persisted in OpenClaw config write paths:
  - `electron/utils/channel-config.ts`
  - `electron/utils/openclaw-auth.ts`
- Added sanitize fallback that auto-enables `commands.restart` before Gateway start.

### 12. Channels page data consistency fixes
- Unified configured state derivation so the following sections share one source:
  - stats cards
  - configured channels list
  - available channel configured badge
- Fixed post-delete refresh by explicitly refetching both:
  - configured channel types
  - channel status list

### 13. Channels UX resilience during Gateway restart/reconnect
- Added delayed gateway warning display to reduce transient false alarms.
- Added "running snapshot" rendering strategy:
  - keep previous channels/configured view during `starting/reconnecting` when live response is temporarily empty
  - avoids UI flashing to zero counts / empty configured state
- Added automatic refresh once Gateway transitions back to `running`.

### 14. Channel enable/disable UX rollback
- Rolled back renderer-side channel enable/disable controls due to multi-channel state mixing risk.
- Removed channel-card toggle entry point and setup-dialog enable switch.
- Restored stable channel configuration flow (save/delete + refresh consistency).

### 15. Cron i18n completion and consistency
- Replaced remaining hardcoded Cron UI strings with i18n keys:
  - dialog actions (`Cancel`, `Saving...`)
  - card actions (`Edit`, `Delete`)
  - trigger failure message
  - confirm dialog namespace usage (`common:actions.*`)
- Refactored cron schedule display parser to return localized strings instead of hardcoded English.
- Added new locale keys in EN/ZH/JA:
  - `toast.failedTrigger`
  - `schedule.everySeconds/everyMinutes/everyHours/everyDays/onceAt/weeklyAt/monthlyAtDay/dailyAt/unknown`

### 16. Gateway log noise reduction
- Added stderr classification downgrade for expected loopback websocket transient logs:
  - `[ws] handshake timeout ... remote=127.0.0.1`
  - `[ws] closed before connect ... remote=127.0.0.1`
- These lines now log at debug level instead of warn during reload/reconnect windows.

### 17. External gateway shutdown compatibility
- Added capability cache for externally managed Gateway shutdown RPC.
- If `shutdown` is unsupported (`unknown method: shutdown`), mark it unsupported and skip future shutdown RPC attempts to avoid repeated warnings.

### 18. Chat history sidebar grouping (ChatGPT-style buckets)
- Updated chat session history display in sidebar to time buckets:
  - Today / Yesterday / Within 1 Week / Within 2 Weeks / Within 1 Month / Older than 1 Month
- Added `historyBuckets` locale keys in EN/ZH/JA (`chat` namespace).
- Fixed i18n namespace usage for bucket labels in sidebar:
  - explicitly resolves via `chat:historyBuckets.*` to avoid raw key fallback.
- Removed forced uppercase rendering for bucket headers to preserve localized casing.
- Grouping now applies to all sessions (including `:main`) for consistent bucket visibility and behavior.

### 19. `refactor_clawx_1` × `main` merge outcome (main-first baseline)
- Performed a dedicated merge line with `origin/main` as the conflict-resolution baseline for high-risk files.
- Resolved wide conflict surface in gateway/store/page layers by prioritizing compile-safe `main` implementations, then selectively re-applying compatible refactor behavior.
- Merge result focus:
  - keep app runnable and type-safe first
  - avoid partial hybrid states that mix incompatible host-api/ipc patterns in a single module
  - retain low-risk UX/flow improvements only when behavior parity is clear

### 20. Post-merge compile recovery
- Fixed merge-induced breakages causing `tsc`/build failures:
  - malformed blocks in settings/channels/chat/store files
  - duplicated variable declarations in `electron/gateway/manager.ts`
  - mismatched transport helper usage introduced by partial conflict picks
- Re-aligned broken modules to `origin/main` where necessary to restore a stable build baseline.
- Current status after cleanup:
  - `pnpm run typecheck` passes
  - app-side Vite/Electron compile succeeds; packaging step may still fail under restricted proxy/network environments (non-code issue)

### 21. IPC event compatibility fix after merge
- Fixed runtime error `Invalid IPC channel: gateway:channel-status` by restoring preload allowlist compatibility with renderer subscriptions.
- Reconciled `electron/preload/index.ts` event channel whitelist with active gateway event usage:
  - `gateway:status-changed`
  - `gateway:message`
  - `gateway:notification`
  - `gateway:channel-status`
  - `gateway:chat-message`
  - `gateway:exit`
  - `gateway:error`

### 22. Transport strategy consolidation (no user toggle)
- Removed manual transport selection UI from Settings/Developer to reduce operator complexity and avoid invalid combinations.
- Kept transport abstraction in code, but locked runtime policy to a single fixed chain:
  - `WS first -> HTTP fallback -> IPC fallback`
- Applied this as bootstrap default in app initialization rather than user preference switching.