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.