refactor: decompose ChatPanel into focused modules

[SweetSophia]

Summary

Extract the monolithic ChatPanel/index.tsx into focused, maintainable modules. This reduces the file from ~1200 lines to a slim orchestrator with delegated concerns.

Changes

New modules extracted from ChatPanel/index.tsx:

• useConversationEngine.ts — LLM tool-calling loop, message streaming, and conversation state management
• toolDefinitions.ts — Agent tool schemas and hasUsableLLMConfig validation
• ChatSubComponents.tsx — UI sub-components (message list, input area, etc.)
• SettingsModal.tsx — Configuration UI with server-side key persistence

Bug fixes included:

• Stabilize runConversation identity to prevent listener churn
• Flush debounced saves on cleanup; fix write amplification
• useLayoutEffect for setSessionPath to avoid stale renders
• Only break tool loop when respond_to_user is the sole tool call
• Redact sensitive args from warning logs
• Extract PendingSaveSnapshot type from inline ref

Guide improvements:

• Updated guide.md across 10+ apps (Chess, Diary, Email, MusicApp, Gomoku, CyberNews, Twitter, Album, etc.) for clearer AI instructions and standardized formatting.

Dependencies

⚠️ Note: This PR should preferably be applied after #33 (fix(security): server-side API key management and SSRF hardening), as it builds on the error boundary and config infrastructure introduced there.

Testing

• Lint passes
• Build passes
• Self-reviewed

Checklist

• pnpm run lint passes
• pnpm build passes
• Self-reviewed the code changes

[Copilot]

Pull request overview

This PR refactors the previously monolithic ChatPanel/index.tsx into smaller, focused modules (conversation/tool loop, tool definitions/system prompt, UI subcomponents, settings modal), while also adjusting session-path synchronization and debounced persistence behavior to reduce churn and avoid dropped saves.

Changes:

• Extracted the LLM tool-call loop into useConversationEngine.ts and tool/system-prompt helpers into toolDefinitions.ts.
• Extracted UI helpers (CharacterAvatar, StageIndicator, etc.) into ChatSubComponents.tsx and config UI into SettingsModal.tsx.
• Updated ChatPanel/index.tsx to become a “thin shell” wiring state/effects to the extracted modules, including useLayoutEffect session-path syncing and improved debounced-save flushing.

Reviewed changes

Copilot reviewed 5 out of 5 changed files in this pull request and generated 6 comments.

Show a summary per file

File	Description
apps/webuiapps/src/components/ChatPanel/useConversationEngine.ts	New hook encapsulating the tool-call loop and tool dispatch logic.
apps/webuiapps/src/components/ChatPanel/toolDefinitions.ts	New module for tool schemas, system prompt building, and config guard.
apps/webuiapps/src/components/ChatPanel/SettingsModal.tsx	New extracted settings modal for LLM + image-gen configuration.
apps/webuiapps/src/components/ChatPanel/ChatSubComponents.tsx	New extracted UI subcomponents (avatar, stage indicator, actions, content rendering).
apps/webuiapps/src/components/ChatPanel/index.tsx	Refactored orchestrator wiring state/effects to extracted modules and updated persistence/session syncing.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

This effect’s dependency array is [sessionPath], but the effect body reads modCollection (via getActiveModEntry(modCollection) when restoring opening replies). If the active mod’s config changes without changing sessionPath (e.g. editing opening suggested replies for the same mod), the closure can become stale and the UI won’t recompute the replies. Consider either adding modCollection/seedPrologue as dependencies or splitting out a separate effect that updates opening replies when modCollection changes and the conversation is still at the prologue state.

[Copilot]

The Save handler persists baseUrl, model, and API keys exactly as typed. Because hasUsableLLMConfig() only checks trimmed values (it doesn’t normalize them) and downstream clients don’t consistently trim, leading/trailing whitespace can result in invalid target URLs or auth headers (especially for image-gen where config.apiKey is used verbatim). Consider normalizing user inputs on save (e.g., trim() baseUrl/model/apiKey and optionally collapse internal whitespace where appropriate) before calling onSave.

Suggested change

	const llmCfg: LLMConfig = {
	provider,
	apiKey,
	baseUrl,
	model,
	...(customHeaders.trim() ? { customHeaders } : {}),
	};
	const igCfg: ImageGenConfig | null = igApiKey.trim()
	? {
	provider: igProvider,
	apiKey: igApiKey,
	baseUrl: igBaseUrl,
	model: igModel,
	...(igCustomHeaders.trim() ? { customHeaders: igCustomHeaders } : {}),
	const normalizedApiKey = apiKey.trim();
	const normalizedBaseUrl = baseUrl.trim();
	const normalizedModel = model.trim();
	const normalizedCustomHeaders = customHeaders.trim();
	const normalizedIgApiKey = igApiKey.trim();
	const normalizedIgBaseUrl = igBaseUrl.trim();
	const normalizedIgModel = igModel.trim();
	const normalizedIgCustomHeaders = igCustomHeaders.trim();
	const llmCfg: LLMConfig = {
	provider,
	apiKey: normalizedApiKey,
	baseUrl: normalizedBaseUrl,
	model: normalizedModel,
	...(normalizedCustomHeaders ? { customHeaders: normalizedCustomHeaders } : {}),
	};
	const igCfg: ImageGenConfig | null = normalizedIgApiKey
	? {
	provider: igProvider,
	apiKey: normalizedIgApiKey,
	baseUrl: normalizedIgBaseUrl,
	model: normalizedIgModel,
	...(normalizedIgCustomHeaders
	? { customHeaders: normalizedIgCustomHeaders }
	: {}),

[Copilot]

hasImageGen is determined via !!imageGenConfigRef.current?.apiKey, which treats whitespace-only keys as enabled. That can cause the engine to register image tools and attempt image generation with an unusable key. Consider using a trimmed check (e.g. imageGenConfigRef.current?.apiKey.trim().length > 0) to match the UI’s intent.

Suggested change

	const hasImageGen = !!imageGenConfigRef.current?.apiKey;
	const hasImageGen = (imageGenConfigRef.current?.apiKey?.trim().length ?? 0) > 0;

[Copilot]

The pendingToolCallsRef summary for file tools includes JSON.stringify(params).slice(0, 60). For tools like file_write, params can contain user/app data (and potentially secrets) that will then be surfaced in the UI (“Actions taken”) and may be persisted as part of chat history. Consider redacting/omitting sensitive fields (e.g. content, apiKey, Authorization) or logging only the tool name + path to avoid accidental data exposure.

Suggested change

	// ---- File tools ----
	if (isFileTool(tc.function.name)) {
	ctx.pendingToolCallsRef.current.push(
	`${tc.function.name}(${JSON.stringify(params).slice(0, 60)})`,
	const summarizeFileToolCall = (
	toolName: string,
	toolParams: Record<string, unknown>,
	): string => {
	const pathKeys = ['path', 'filePath', 'sourcePath', 'targetPath', 'destinationPath'] as const;
	for (const key of pathKeys) {
	const value = toolParams[key];
	if (typeof value === 'string' && value.length > 0) {
	return `${toolName}(${key}: ${value})`;
	}
	}
	return toolName;
	};
	// ---- File tools ----
	if (isFileTool(tc.function.name)) {
	ctx.pendingToolCallsRef.current.push(
	summarizeFileToolCall(tc.function.name, params as Record<string, unknown>),

[Copilot]

handleMediaReady always activates the layer that finished loading (readyUrl). If the user switches emotions quickly, an old/inactive layer can finish loading later and incorrectly become active, causing the avatar to “jump back” to the wrong emotion. Consider tracking the latest desired media.url in a ref and ignoring readyUrl events that don’t match it (and/or storing a per-layer generation token) before promoting a layer to active.

[Copilot]

hasUsableLLMConfig() trims baseUrl/model only for the boolean check, but the returned config is still the original (potentially whitespace-padded) object. Call sites then pass this through to chat(), where baseUrl with leading/trailing spaces can produce invalid URLs. Consider either normalizing the config at the source (preferred) or introducing a normalizeLLMConfig() helper that returns a sanitized copy (trimmed fields) and using that for all requests.

Suggested change

	const baseUrl = typeof config?.baseUrl === 'string' ? config.baseUrl.trim() : '';
	const model = typeof config?.model === 'string' ? config.model.trim() : '';
	if (!config) {
	return false;
	}
	const baseUrl = typeof config.baseUrl === 'string' ? config.baseUrl.trim() : '';
	const model = typeof config.model === 'string' ? config.model.trim() : '';
	config.baseUrl = baseUrl;
	config.model = model;