claw/docs/plans/2026-03-27-sgclaw-chat-first-ui-refactor-plan.md

sgClaw Chat-First UI Refactor Implementation Plan

For Claude: REQUIRED SUB-SKILL: Use superpowers:executing-plans to implement this plan task-by-task.

Goal: Rebuild the sgClaw floating chat UI into a chat-first plugin-style product where the message timeline is primary, 执行摘要 is folded into the conversation, and 调试 opens as a full-window overlay instead of occupying persistent space.

Architecture: Keep chrome://superrpa-functions/sgclaw-chat as the first verified host because it already has Lit-based unit tests, then mirror the same information architecture and visual hierarchy into the ordinary-page injected sgclaw_overlay.js. Do not introduce a new backend contract; only rearrange presentation, panel semantics, and message/result composition around the existing runtime state.

Tech Stack: Chromium WebUI, Lit templates/components, injected Shadow DOM overlay JavaScript, existing SuperRPA bridge/runtime callbacks, mainline TS unit tests.

Task 1: Lock The New Information Architecture In Tests

Files:

• Modify: /home/zyl/projects/superRpa/src/chrome/browser/resources/superrpa/devtools/functions/sgclaw-chat/sgclaw-chat_mainline_unittest.ts
• Modify: /home/zyl/projects/superRpa/src/chrome/browser/resources/superrpa/devtools/functions/sgclaw-chat/sgclaw-chat_settings_state_mainline_unittest.ts

Step 1: Write the failing test

Add assertions for these exact product rules:

• getHtml() must no longer emit the legacy debug-note.
• the main chat template must define a dedicated overlay/sheet container for history, settings, and debug.
• the debug panel must be described as a full-window overlay rather than a side drawer/log block.
• the result presentation must be part of the message stream, not a standalone persistent secondary panel.

Step 2: Run test to verify it fails

Run:

node --test /home/zyl/projects/superRpa/src/chrome/browser/resources/superrpa/devtools/functions/sgclaw-chat/sgclaw-chat_mainline_unittest.ts

Expected: FAIL because current template still includes debug-note, side-by-side panel layout, and standalone result panel semantics.

Step 3: Write minimal implementation

Change only template/component strings and assertions needed to express the new structure, without touching styling yet.

Step 4: Run test to verify it passes

Run the same command.

Expected: PASS.

Task 2: Refactor chrome:// sgClaw Into Chat-First Structure

Files:

• Modify: /home/zyl/projects/superRpa/src/chrome/browser/resources/superrpa/devtools/functions/sgclaw-chat/sgclaw-chat.html.ts
• Modify: /home/zyl/projects/superRpa/src/chrome/browser/resources/superrpa/devtools/functions/sgclaw-chat/sgclaw-chat.css.ts
• Modify: /home/zyl/projects/superRpa/src/chrome/browser/resources/superrpa/devtools/functions/sgclaw-chat/components/sgclaw-chat-header.ts
• Modify: /home/zyl/projects/superRpa/src/chrome/browser/resources/superrpa/devtools/functions/sgclaw-chat/components/sgclaw-chat-composer.ts
• Modify: /home/zyl/projects/superRpa/src/chrome/browser/resources/superrpa/devtools/functions/sgclaw-chat/components/sgclaw-debug-drawer.ts
• Modify: /home/zyl/projects/superRpa/src/chrome/browser/resources/superrpa/devtools/functions/sgclaw-chat/components/sgclaw-history-panel.ts
• Modify: /home/zyl/projects/superRpa/src/chrome/browser/resources/superrpa/devtools/functions/sgclaw-chat/components/sgclaw-settings-panel.ts
• Modify: /home/zyl/projects/superRpa/src/chrome/browser/resources/superrpa/devtools/functions/sgclaw-chat/components/sgclaw-message-list.ts
• Modify: /home/zyl/projects/superRpa/src/chrome/browser/resources/superrpa/devtools/functions/sgclaw-chat/components/sgclaw-message-card-result.ts

Step 1: Keep the header narrow

Make the header carry only:

• brand
• current page label
• compact runtime status
• actions for 新对话 / 历史 / 设置 / 调试 / 收起

Remove the large subtitle/debug framing and the separate heavy runtime action row feel.

Step 2: Make the message timeline primary

Turn the main shell body into:

• a single timeline container
• optional empty-state presets
• no persistent secondary summary card

finalResult should render as a folded result card appended in the stream.

Step 3: Convert secondary panels into full overlays

Render history, settings, and debug inside a full-window overlay/sheet that covers the chat content area instead of sitting above or beside it.

Step 4: Re-skin toward the approved direction

Use:

• soft neutral surfaces
• restrained accent usage
• thinner borders
• calmer shadows
• clearer assistant/user card contrast

Avoid:

• debug-workbench feeling
• large gradient blocks
• heavy explanatory copy in the main flow

Step 5: Run the unit tests

Run:

node --test /home/zyl/projects/superRpa/src/chrome/browser/resources/superrpa/devtools/functions/sgclaw-chat/sgclaw-chat_mainline_unittest.ts

Expected: PASS.

Task 3: Mirror The Same Structure Into Ordinary-Page Overlay

Files:

• Modify: /home/zyl/projects/superRpa/src/chrome/browser/resources/superrpa/sgclaw_overlay.js

Step 1: Remove the standalone result panel

Delete the always-visible 执行摘要 block from the main window body.

Step 2: Introduce overlay panels

Change panel rendering so history, settings, and debug appear in a dedicated full-window overlay layer within the floating window instead of as sibling blocks consuming vertical space.

Step 3: Rebuild the shell

Match the chrome:// layout:

• compact header
• primary message timeline
• folded result card inside conversation
• sticky composer

Step 4: Preserve behavior

Do not break:

• sgclaw.newConversation
• sgclaw.restoreConversation
• runtime polling
• config save/load
• unread badge behavior

Step 5: Run a syntax sanity check

Run:

node --check /home/zyl/projects/superRpa/src/chrome/browser/resources/superrpa/sgclaw_overlay.js

Expected: PASS.

Task 4: Verify Browser Resource Integration

Files:

• No new source files; verification only

Step 1: Run TS / mainline tests

Run:

bash -lc "autoninja -C /home/zyl/projects/superRpa/src/out/KylinRelease functions_ui_mainline_unittests"

Expected: build succeeds.

Step 2: Run targeted mainline unit tests

Run:

/home/zyl/projects/superRpa/src/out/KylinRelease/functions_ui_mainline_unittests --gtest_filter='FunctionsUiMainlineTest.*sgclaw*'

If filter finds no test names, run the full binary and confirm it exits 0.

Step 3: Rebuild browser resources if needed

Run:

bash -lc "autoninja -C /home/zyl/projects/superRpa/src/out/KylinRelease chrome"

Step 4: Manually verify product behavior

Check:

• ordinary webpage floating window
• chrome://superrpa-functions/sgclaw-chat
• 调试 opens as full overlay
• 执行摘要 no longer blocks the main conversation
• 历史 and 设置 do not consume persistent layout space