@flame0510/project-aether 1.1.9

package/docs/CONTAINER-TERMINAL.md

@@ -0,0 +1,280 @@
+# Container Terminal — WebSocket PTY
+
+> **Status:** Active — `main` branch
+> **Last updated:** 2026-06-30
+
+---
+
+## Overview
+
+Rev4a provides an interactive web-based terminal for Docker containers.
+It connects to any container with `AGENT_ID` label, spawning a real PTY session
+via `node-pty` and streaming I/O over a dedicated WebSocket server.
+
+```
+Browser (xterm-compatible DOM terminal)
+  │  WebSocket wss://rev4a/containers/terminal/{id}
+  ▼
+terminal-ws-server.js (port 3741, proxied by Traefik)
+  │  node-pty
+  ▼
+docker exec -it {containerId} env TERM=xterm-256color bash
+  │
+  ▼
+Container Shell (bash, interactive, full PTY)
+```
+
+## Architecture
+
+### Two-process model
+
+| Process          | Port  | Role |
+|------------------|-------|------|
+| `rev4a-next`   | 3740  | Next.js app (pages, API routes, auth) |
+| `rev4a-terminal-ws` | 3741 | Standalone WebSocket server for terminal sessions |
+
+The terminal server is a separate systemd service (rev4a-terminal-ws). It was isolated from
+the Next.js app to avoid event-loop contention during high-throughput I/O (fast
+`seq`, `cat` on large files, interactive shell sessions).
+
+### Traefik routing
+
+```
+/containers/terminal/{id}          → Next.js (page serving TerminalClient)
+/api/terminal-ws?id={containerId}  → WebSocket proxy → ws://127.0.0.1:3741
+```
+
+### Data flow
+
+1. User opens `/containers/terminal/openclaw-atlas`
+2. `page.tsx` renders `<TerminalClient containerId="openclaw-atlas" />`
+3. `TerminalClient` opens a WebSocket to `/api/terminal-ws?id=openclaw-atlas`
+4. `terminal-ws-server.js` receives connection, spawns a PTY via node-pty:
+   ```
+   docker exec -it openclaw-atlas env TERM=xterm-256color bash
+   ```
+5. PTY output streams → WebSocket → browser (DOM terminal)
+6. User keystrokes → WebSocket → PTY stdin
+
+## Terminal Client (Browser)
+
+### Why not xterm.js?
+
+The first implementation used **xterm.js** (v5.3.0) with both **canvas** and
+**DOM** renderers. Both suffered from:
+
+- **Black screen on large output** — the canvas renderer went blank when
+  hundreds of lines were received in a single burst. The DOM renderer
+  (xterm.addons.dom) had the same issue under load.
+- **Broken scrolling** — xterm.js manages its own scrollback buffer internally,
+  but the canvas never grew, so native browser scrolling didn't exist. Mouse
+  wheel scrolling often failed or produced visual artifacts.
+- **CSS conflicts** — the parent app sets `html, body { overflow: hidden }`,
+  which interfered with xterm.js viewport calculation. Multiple workarounds
+  (`position: fixed`, `minHeight: 0`, `height: 100dvh`) didn't fully resolve
+  layout instability.
+- **Selection issues** — xterm.js intercepts mouse events for its own
+  selection system, making it hard to copy text natively.
+
+### Custom DOM terminal (current)
+
+The current terminal replaces xterm.js entirely with a plain HTML structure:
+
+```
+┌─────────────────────────────────┐
+│  Top bar (44px, container info) │
+├─────────────────────────────────┤
+│                                 │
+│  Output area (div, overflow:auto│
+│  white-space: pre-wrap)         │
+│                                 │
+│  root@hostname:~# ls -la        │
+│  total 12                       │
+│  drwxr-xr-x ...                 │
+│  -rw-r--r-- ...                 │
+│                                 │
+│  root@hostname:~# █             │
+├─────────────────────────────────┤
+│  (hidden <textarea> for input)  │
+└─────────────────────────────────┘
+```
+
+Key design decisions:
+
+| Decision | Rationale |
+|---|---|
+| **`<textarea>` hidden off-screen** | Captures all keystrokes including Tab, Arrows, Ctrl+letter. No focus/IME issues. Single-line only (no Enter for newlines). |
+| **`<div>` output area** | Native browser scrolling (`overflow: auto`). Normal text selection (copy/paste with Cmd+C). Render millions of lines without black screen. |
+| **`white-space: pre-wrap`** | Preserves ANSI-visible indentation and spacing while wrapping long lines. |
+| **Last output line + input inline** | The cursor and text being typed appear on the same line as the last prompt from the server, simulating a real terminal feel. |
+| **`requestAnimationFrame` auto-scroll** | After every buffer update, scrolls to bottom. Smooth, native scroll behavior. |
+
+### Input handling
+
+- **Hidden `<textarea>`** captures all keyboard input
+- `value` + `onChange` → React state `currentInput`
+- On `Enter` → command sent to WebSocket, input cleared
+- `Arrows` → local command history (client-side array)
+- `Tab` → `\t` sent to server (bash autocomplete)
+- `Ctrl+C/L/D/U` → respective control characters sent to server
+- **Multi-line paste** → split by `\n`, each line sent as a separate command
+
+### Pending command flash fix
+
+When the user presses Enter, `currentInput` is immediately cleared.
+However, the server echoes the command back with a newline + new prompt.
+Between the clear and the server echo, there is a visible frame where the
+input line appears blank.
+
+**Fix:** A `pendingCmdRef` ref holds the last submitted command string.
+The rendering logic uses:
+
+```ts
+const showInput = pendingCmdRef.current ? pendingCmdRef.current : currentInput;
+```
+
+`pendingCmdRef` is reset as soon as any server output arrives (the echo),
+so the command text stays visible without flicker.
+
+### ANSI parsing (color rendering)
+
+The terminal now includes a real ANSI parser (`parseAnsi()`) that converts
+SGR (Select Graphic Rendition) escape sequences into styled `<span>`
+elements:
+
+| Feature | Supported |
+|---|---|
+| Foreground colors 30-37 (normal) | ✅ |
+| Foreground colors 90-97 (bright) | ✅ |
+| Background colors 40-47 | ✅ |
+| Background colors 100-107 (bright) | ✅ |
+| Bold (1) | ✅ `fontWeight: 700` |
+| Dim (2) | ✅ `opacity: 0.6` |
+| Italic (3) | ✅ |
+| Underline (4) | ✅ |
+| Reset (0) | ✅ clears all styles |
+| Bracketed paste `[?2004h/l` | 🚫 stripped |
+| Non-SGR CSI (cursor, erase) | 🚫 stripped |
+| OSC sequences (title, clipboard) | 🚫 stripped |
+
+**Implementation:**
+
+```ts
+type AnsiStyle = {
+  fg?: string;          // CSS color
+  bg?: string;          // CSS background-color
+  bold?: boolean;
+  dim?: boolean;
+  italic?: boolean;
+  underline?: boolean;
+};
+type Segment = { text: string; style: AnsiStyle };
+```
+
+The parser walks the raw ANSI string character by character. When it
+encounters `\x1b[`, it reads until `m` to get SGR parameters. Each
+parameter (e.g. `31` for red foreground) is translated into a color
+from the ANSI color map. All non-SGR escape sequences (cursor movement,
+erase display, bracketed paste) are silently stripped.
+
+The raw PTY output is kept in state as-is (with ANSI), split by `\n`,
+and each line is passed through `RenderAnsi` which uses `useMemo` to
+avoid re-parsing on every render.
+
+**Color palette** follows the One Dark theme used by the UI:
+
+| Code | Color | Hex |
+|---|---|---|
+| 30/90 (black) | Dark gray | `#1d1d1d` / `#5c6370` |
+| 31/91 (red) | Soft red | `#e06c75` |
+| 32/92 (green) | Soft green | `#98c379` |
+| 33/93 (yellow) | Amber | `#d19a66` |
+| 34/94 (blue) | Soft blue | `#61afef` |
+| 35/95 (magenta) | Purple | `#c678dd` |
+| 36/96 (cyan) | Teal | `#56b6c2` |
+| 37/97 (white) | Light gray / white | `#abb2bf` / `#ffffff` |
+
+### Legacy: ANSI stripping (pre-color support)
+
+The original implementation stripped all ANSI sequences, keeping only
+visible text. This was replaced by the parser above on 2026-06-25.
+
+## Terminal Server (`terminal-ws-server.js`)
+
+### Dependencies
+
+- **ws** (WebSocket server)
+- **node-pty** (pseudo-terminal for child processes)
+
+### Session lifecycle
+
+1. WebSocket connection established with `?id=openclaw-atlas`
+2. `node-pty` spawns `docker exec -it {containerId} bash` with:
+   - `name: 'xterm-256color'`
+   - `cols: 80, rows: 30` (initial, resized on client fit)
+3. PTY `onData` → WebSocket `send`
+4. WebSocket `message` → PTY `write`
+5. Idle timeout: 30 minutes (reset on any client input)
+6. On disconnect or `exit` command → cleanup child process, close socket
+
+### Resize handling
+
+The client sends a JSON message when the terminal dimensions change:
+
+```json
+{ "type": "resize", "cols": 120, "rows": 40 }
+```
+
+The server calls `term.resize(cols, rows)` to update the PTY dimensions.
+This ensures commands like `top`, `less`, `vim` use the correct viewport.
+
+### Chunked output
+
+PTY output is buffered and flushed every 10ms to avoid overwhelming the
+browser's DOM renderer with a single giant chunk. If the buffer exceeds
+2000 characters, it is flushed immediately in sub-chunks.
+
+This was added because `seq 1 10000` or `cat` on a large file would
+send 100KB+ in one frame, causing the browser to freeze.
+
+### Why node-pty over `spawn('script')` or `unbuffer`?
+
+Earlier attempts used:
+
+- `spawn('docker exec -i ...')` — no PTY, commands had no echo, no history,
+  no tab completion
+- `spawn('script', ['-q', '-c', 'docker exec -i ...'])` — created a PTY but
+  output was fully buffered and never appeared until the process exited
+- `spawn('unbuffer', ['-p', 'docker exec -i ...'])` — same buffering issue
+
+`node-pty` is the only reliable way to create a real PTY and get
+line-buffered or character-buffered I/O in real-time.
+
+## File Structure
+
+```
+app/containers/terminal/
+├── [id]/
+│   ├── page.tsx               # Next.js page (auth-protected)
+│   └── TerminalClient.tsx     # Client-side terminal component
+terminal-ws-server.js           # WebSocket PTY server (rev4a-terminal-ws.service)
+rev4a.service                  # Systemd target for all three services
+```
+
+## Known Limitations
+
+- **No full-screen TUI support** — `vim`, `top`, `nano`, `htop` will
+  not render correctly because cursor positioning sequences are stripped.
+  These tools require a proper xterm-compatible terminal.
+- **Single session per connection** — no multiplexing, no tabs.
+  Each WebSocket connection spawns one PTY.
+- **No WebGL renderer** — DOM rendering is CPU-bound for very fast output.
+  In practice, up to ~500 lines/sec is smooth.
+
+## Future Improvements
+
+- [ ] Detect TUI applications and fall back to xterm.js WebGL renderer
+- [ ] Terminal multiplexer (multiple tabs, split panes)
+- [ ] Download session log as text file
+- [ ] Paste confirmation dialog for multi-line pastes
+- [ ] Dark/light theme toggle

package/docs/DESIGN-SYSTEM.md

@@ -0,0 +1,99 @@
+# Rev4a Design System
+
+Source of truth: `app/design-system.ts` + CSS tokens in `app/globals.css`.
+
+> **Last updated:** 2026-07-03
+
+---
+
+## Responsive breakpoints
+
+Centralized in `app/design-system.ts` as `Breakpoint` object and exposed via the `useResponsive(key)` hook.
+
+| Token | Value | Used by |
+|-------|-------|---------|
+| `Breakpoint.sm` | 576px | Mobile bottom nav centering |
+| `Breakpoint.md` | 768px | Dashboard, Lineage, SessionDrawer, Providers |
+| `Breakpoint.lg` | 992px | Agents (dense/fold devices), Crons, Plugins/Skills |
+| `Breakpoint.xl` | 1200px | Reserved |
+| `Breakpoint.xxl` | 1400px | Reserved |
+
+### CSS tokens (globals.css)
+
+```css
+--bp-sm: 576px;
+--bp-md: 768px;
+--bp-lg: 992px;
+--bp-xl: 1200px;
+--bp-xxl: 1400px;
+```
+
+Use the CSS custom property in `@media` queries, not raw pixel values.
+
+## Visual language
+
+### Shape
+
+Rev4a uses a **square/sharp** visual language:
+- Buttons, inputs, modals, cards — **0 border-radius by default** (no rounding).
+- `Pill` uses inline rounded shapes where appropriate (status badges).
+- No shadows, no gradients (except the login page background).
+
+### Color tokens
+
+Defined in `app/globals.css` as CSS custom properties:
+
+```css
+--bg:           #0a0a0a      /* Page background */
+--bg2:          #111         /* Slightly lighter surface */
+--border:       #222         /* Default border */
+--text:         #e0e0e0      /* Primary text */
+--text-dim:     #888         /* Muted/secondary text */
+--violet:       #a78bfa      /* Brand accent */
+--violet-bg:    #1a1030     /* Violet-tinted hover/active background */
+--green:        #22c55e      /* Success */
+--red:          #ef4444      /* Error */
+--yellow:       #eab308      /* Warning */
+--blue:         #60a5fa      /* Info / links */
+```
+
+### Typography
+
+- Monospace by default: `var(--font-mono-stack)`
+- Serif (logotype): `var(--font-serif-stack)`
+- UI buttons use `monospace` via CSS class or inline `fontFamily`
+- No variable fonts — system monospace stack for consistency
+
+## Component design rules
+
+1. **Border radius: 0 everywhere.** `border-radius: 0` or sharp corners. Exceptions: `Pill`, avatar circles, status dots.
+2. **No shadows.** Flat design. Use `border: 1px solid var(--border)` to define surfaces.
+3. **Violet is the only accent.** `var(--violet)` for active states, primary actions, headings. `var(--violet-bg)` for hover/active backgrounds.
+4. **Mono font on buttons and inputs.** All interactive text uses `var(--font-mono-stack)`.
+5. **CSS vars over hardcoded colors.** Never inline `#22c55e`, `#ef4444`, `#888` — use the CSS token.
+6. **Loading feedback.** Use `loading` prop on `Button` (shows inline spinner). Do not render separate loader elements.
+7. **Minimal animation.** Transitions on hover/active (0.1s–0.12s), spin on loading spinner. No bounce, shake, or decorative animations.
+
+### React hook
+
+```ts
+import { useResponsive, Breakpoint } from '../design-system';
+
+const isNarrow = useResponsive('md');  // true when ≤767px
+const isFoldable = useResponsive('lg'); // true when ≤991px
+```
+
+The hook uses `matchMedia` (passive, zero-CPU) and returns `boolean`.
+
+---
+
+## Current page behaviors
+
+| Page | Breakpoint | Behaviour when active |
+|------|-----------|----------------------|
+| Agents | `lg` (992px) | Single-column stacked: AGENTS → FILES+CONFIG → EDITOR |
+| Crons | `lg` (992px) | Tab navigation: jobs / runs |
+| Plugins/Skills | `lg` (992px) | Sidebar → Detail step |
+| Dashboard | `md` (768px) | Mobile header nav |
+| Lineage | `md` (768px) | Mobile tab: graph / feed |
+| SessionDrawer | `md` (768px) | Full-width drawer / compact |

package/docs/FRONTEND-ARCHITECTURE.md

@@ -0,0 +1,119 @@
+# Rev4a Frontend Architecture
+
+> **Last updated:** 2026-07-19
+
+## Layering
+
+Rev4a UI should follow a layered architecture:
+
+1. `app/*/page.tsx` — routing only.
+2. `app/components/*Page*.tsx` — page composition and data orchestration.
+3. `app/components/ui/*` — shared design-system primitives.
+4. `lib/patterns/*` — domain/data patterns.
+5. `lib/*` — infrastructure helpers and pure utilities.
+
+Feature pages should not create new ad-hoc visual languages. Prefer `ui` primitives first.
+
+## UI primitives
+
+All shared UI primitives live in `app/components/ui/` and are exported from `app/components/ui/index.ts`.
+
+### Complete catalog
+
+| Component | File | Purpose |
+|-----------|------|---------|
+| `Button` | `Button.tsx` | Action button, 5 variants (`primary`, `secondary`, `danger`, `ghost`, `success`), 2 sizes (`sm`, `md`), loading spinner. |
+| `Input` | `Input.tsx` | Text input with label, error state, placeholder. |
+| `Select` | `Select.tsx` | Native select with typed options, label, error state. |
+| `Modal` | `Modal.tsx` | Overlay modal, Escape-to-close, maxWidth prop, `type="button"` on close. |
+| `Toast` | `Toast.tsx` | Lightweight toast notification with auto-dismiss (4s), `success` / `error` variants. |
+| `LoadingSpinner` | `LoadingSpinner.tsx` | Inline or fullscreen spinner. |
+| `Tabs` | `Tabs.tsx` | Tab navigation bar with optional count badges. |
+| `ItemList` / `ListContainer` / `ListItem` / `ListItemSeparator` | `ItemList.tsx` | List primitives for sidebar/panel item lists. |
+| `FilterBar` | `FilterBar.tsx` | Horizontal filter button group. |
+| `PropertyList` | `PropertyList.tsx` | 2-column grid for label/value pairs. Children rendered as `<Fragment>` — do not wrap in extra `<div>`. |
+| `TemplateOption` | `TemplateOption.tsx` | Agent template selection card with avatar, description, optional badge. Centralises create-agent card styling. |
+| `Pill` | `Pill.tsx` | Small status/attribute label. Variants: `default`, `accent`. |
+| `Metric` | `Metric.tsx` | Metric card with title, value, subtitle, tone. |
+| `StatusCard` | `StatusCard.tsx` | Health/status report card. |
+| `Surface` | `Surface.tsx` | Shared panel/card surface, variant prop. |
+| `Page` / `PageHeader` | `Page.tsx` | Full-page layout shell. |
+| `Icons` | `Icons.tsx` | SVG icons (`EyeIcon`, `EyeOffIcon`), 16/20px shared. |
+| `PasswordInput` | `PasswordInput.tsx` | Password input with inline show/hide toggle (`<button type="button">` with `aria-label`). |
+| `OnboardingPageClient` + step components | `app/onboarding/PageClient.tsx` | 4-step wizard (`WelcomeStep`, `ProvidersStep`, `AgentsStep`, `DoneStep`) + `WizardFrame` shell with mobile-first CSS. |
+| `useOnboarding` | `app/onboarding/useOnboarding.ts` | Shared hook: onboarding state, step transitions, provider save, restart. Receives server-side initial state to avoid loading flash. |
+| `OnboardingIcons` | `app/onboarding/icons.tsx` | Shared SVG icons (flyweight pattern): `ArrowRightIcon`, `CheckIcon`, `DockerIcon`, `GatewayIcon`, etc. |
+| `tokens` | `tokens.ts` | TypeScript types for `Tone` and related token values. |
+| `Badge` | `Badge.tsx` | Inline status tag with tone variants (success, danger, warning, neutral). Used for channel chips, pairing labels, error/success messages. |
+
+### Rules
+
+1. **Prefer existing primitives over new ad-hoc markup.** Every new component starts from the shared catalog.
+2. **No inline styles on interactive elements.** Buttons, inputs, selects use the `app/components/ui/*` component with component props. Only layout/wrapping containers use inline style.
+3. **No Italian in code, labels, or comments.** UI strings, error messages, aria-labels — all English.
+4. **Clickable/custom interactive elements must be `<button type="button">`.** Not `<span onClick>`, not `<div onClick>`. Always include `aria-label` for icon-only buttons.
+5. **Modals inside forms** — close button has `type="button"` to prevent accidental form submission.
+6. **Loading buttons** — set `loading={true}` on `Button`, do not render separate loaders next to the button. The spinner is built-in.
+7. **New UI component** — add it to `app/components/ui/`, export from `index.ts`, document it here. If it's specific to one page, keep it page-local unless another page needs it.
+
+## GoF pattern mapping
+
+Already used:
+
+- **Observer + Singleton**: `EventBus` owns one SSE stream and fan-outs updates.
+- **Factory**: `SessionFactory` / `EventFactory` normalize raw runtime data.
+- **Adapter**: `ApiAdapter` converts raw API payloads to domain types.
+- **Strategy + Composite**: `FilterStrategy` composes dashboard filtering.
+
+Added UI-side discipline:
+
+- **Factory-ish tone mapping**: `toneFromHealth()` maps domain health into UI tone.
+- **Strategy-ish variants**: `Surface` variant/tone classes choose presentation without inline restyling.
+- **Composition**: page-specific components compose primitives instead of duplicating card markup.
+
+## Responsive system
+
+Rev4a uses Bootstrap v5 breakpoint categories as project-wide tokens, declared in `app/globals.css`:
+
+- `--bp-sm: 576px`
+- `--bp-md: 768px`
+- `--bp-lg: 992px`
+- `--bp-xl: 1200px`
+- `--bp-xxl: 1400px`
+
+Rules:
+
+1. Prefer breakpoint tokens over raw pixel values.
+2. New responsive behavior should map to Bootstrap categories (`sm`, `md`, `lg`, ...), not ad-hoc thresholds.
+3. When an exception is needed, express it relative to a token and document why.
+
+## Current responsive behaviors
+
+- **Agents page**
+  - below `lg` (`< 992px`) switches to stacked/mobile mode
+  - shows one section at a time (`AGENTS` → `FILES + CONFIG` → `EDITOR`)
+  - avoids split-column clipping on narrow, fold, and small-tablet devices
+- **Mobile bottom nav**
+  - active below `md`
+  - item row centers from `sm` upward within the mobile range
+- **PDF preview in Agents**
+  - rendered in-page for mobile browsers instead of relying on the native iframe PDF viewer
+
+## Request orchestration rule
+
+For interactive pages that can change view/file/tab quickly:
+
+1. Abort obsolete fetches with `AbortController`.
+2. Guard against stale updates after `await` boundaries.
+3. On navigation/context switch, kill in-flight requests before starting new ones.
+4. Mobile layout changes must not wait on network completion.
+
+## Migration rule
+
+For every new/changed page:
+
+1. No new one-off card styles unless justified.
+2. Use `app/components/ui/*` primitives first — `Button`, `Input`, `Select`, `Modal`, `Toast`, `Surface`, `Metric`, `StatusCard`, `Pill`, `Page`, `Tabs`, `ItemList`, `FilterBar`, `PropertyList`, `TemplateOption`, `LoadingSpinner`.
+3. Async data must render skeleton, not fake zero values.
+4. Business logic stays in `lib`/API routes; UI consumes typed payloads.
+5. If a pattern is introduced, name it and keep it in `lib/patterns` or `app/components/ui`.