docs: composer dock design, mockup and plan

Co-Authored-By: Claude Opus 5.5 <[email protected]>
This commit is contained in:
FactorandClaude Opus 5.5 committed 2026-11-19 15:56:20 +01:00
1 parent 7fc7d0202c
commit 4bb0e85612
3 files changed
+487

No files matched your search

@@ -0,0 +1,123 @@
# Composer Dock Implementation Plan
> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
**Goal:** Konfigurowalny dock przycisków w belce herdr-composer: klik wysyła lub wstawia zapisany tekst, a zarządzanie odbywa się z menu pod prawym klikiem.
**Architecture:** Czysta logika docka i menu w nowym `dock.js`, zapis w `storage.js` (`herdr-composer.dock`). `main.js` rysuje dock i menu, a wysyłanie przekazuje do istniejącego `finish()` (kolejka, `--force`, strażnik agenta), z pominięciem pola tekstowego.
**Tech Stack:** mod Herdr (ES modules, `gpui-kit`), `node --test`.
**Spec:** `docs/superpowers/specs/2026-11-19-composer-dock-design.md` · makieta `docs/superpowers/mockups/herdr-composer-dock.html`
## Global Constraints
- Bez rekompilacji Herdr i bez zmian w plikach dostarczanych z Herdr. Zmiany tylko w `herdr/herdr-composer/`, `tests/`, `README.md` i `docs/`.
- Kod modu: `herdr/herdr-composer/mods/herdr-composer/`. Moduły czyste (`dock.js`, `storage.js`) nie importują `gpui-kit`, `gpui-base` ani `herdr`.
- Klucz zapisu `herdr-composer.dock`, bez odczytu `ovis-composer.*` (nowa funkcja, brak migracji).
- Limit 30 przycisków. Nazwa domyślna ma najwyżej 16 znaków (15 + `…`), białe znaki są zwinięte do jednej spacji.
- Teksty UI po polsku, dosłownie: „Przypnij do docka”, „Odepnij z docka”, „Przypnij bieżący tekst do docka”, „Odepnij bieżący tekst z docka”, „Zmień nazwę”, „Tylko wstawiaj”, „Wysyłaj od razu”, „Przesuń w lewo”, „Przesuń w prawo”, „Usuń z docka”, „Wstaw”, „Dodaj do ulubionych”, „Usuń z ulubionych”, „Prawy klik w Ulubionych → Przypnij do docka”.
- Dock ma wysokość 28 px i nie może zwiększać wysokości bloku composera (auto-fit).
- Skróty klawiszowe modu zostają w kontekście `herdr-composer > Input`. Nie dodajemy nowych globalnych.
- Testy: `npm test` (dziś 155 pass) musi być zielone po każdym zadaniu.
- Po zmianie modu: `install.cmd` (kopia do `~/.config/herdr-app/mods/herdr-composer`), `herdr-app status` → `"errors": []`.
## Review Focus
- Klik przycisku `send`, gdy w polu jest niewysłany szkic: szkic i załączniki zostają nietknięte, a wysyła się tylko tekst przycisku.
- Klik `send`, gdy agent `working` albo kolejka niepusta: wiadomość trafia do kolejki, a nie wychodzi od razu. Agent `blocked` dostaje ją od razu z `--force`.
- Klik tuż po przełączeniu agenta (okno 500 ms): `syncOk` blokuje wysyłkę i pokazuje komunikat, bez wysłania do złego agenta.
- Uszkodzony albo ręcznie zmieniony `herdr-composer.dock` w `shared.json` (nie-tablica, brak pól, duplikaty, ponad 30): dock ładuje to, co poprawne, i nie wywraca modu.
- Edycja nazwy w miejscu: Esc anuluje tylko edycję i nie przerywa agenta. Enter zapisuje i niczego nie wysyła.
---
### Task 1: `dock.js` + zapis w `storage.js`
**Files:**
- Create: `herdr/herdr-composer/mods/herdr-composer/dock.js`
- Modify: `herdr/herdr-composer/mods/herdr-composer/storage.js` (`KEYS`, nowe `loadDock`/`saveDock`)
- Test: `tests/dock.test.mjs`, `tests/storage.test.mjs`
**Interfaces — Produces:**
- `DockButton = { id: string, label: string, text: string, mode: "send" | "insert" }`
- `MenuItem = { command: string, label: string, disabled?: boolean, danger?: boolean }`
- `DOCK_LIMIT = 30`, `LABEL_MAX = 16`
- `defaultLabel(text: string): string`
- `normalize(raw: unknown): DockButton[]`: przepuszcza tylko poprawne wpisy (`id` i `text` niepuste, `mode` z listy). Pusty `label` zamienia na `defaultLabel(text)`. Odrzuca duplikaty `text` (porównanie po `trim()`, pierwszy wygrywa) i obcina do 30.
- `isPinned(dock, text): boolean` (porównanie po `trim()`).
- `pin(dock, text, id): DockButton[]`: dodaje na końcu `{id, label: defaultLabel(text), text: text.trim(), mode: "send"}`. Zwraca ten sam dock, gdy tekst jest pusty, już przypięty albo osiągnięto limit.
- `unpin(dock, text)`, `remove(dock, id)`, `move(dock, id, step: -1 | 1)` (na krawędzi bez zmian), `rename(dock, id, label)` (pusty po `trim()` → `defaultLabel(text)`), `toggleMode(dock, id)`: każda zwraca nową tablicę i nie mutuje wejścia.
- `dockAction(button, { hasAgent: boolean }): "send" | "insert" | "none"`
- `dockMenu(dock, id): MenuItem[]`: komendy po kolei: `rename`, `mode` (etykieta „Tylko wstawiaj” przy `send`, „Wysyłaj od razu” przy `insert`), `left` (disabled na pierwszym), `right` (disabled na ostatnim), `remove` (`danger: true`).
- `rowMenu({ tab: "history" | "favorites", favorite: boolean, pinned: boolean }): MenuItem[]`: `insert` „Wstaw”. Potem w zakładce `favorites` `pin` („Przypnij do docka” / „Odepnij z docka”). Na końcu `favorite` („Dodaj do ulubionych” / „Usuń z ulubionych”, `danger` przy usuwaniu).
- `starMenu({ text: string, pinned: boolean }): MenuItem[]`: jedna pozycja `pin` („Przypnij bieżący tekst do docka” / „Odepnij bieżący tekst z docka”), `disabled`, gdy `text.trim()` jest pusty.
- `storage.js`: `KEYS.dock = "herdr-composer.dock"`, `loadDock(store): DockButton[]` (przez `normalize`, bez fallbacku `ovis-composer.`), `saveDock(store, items): void` (zapisuje `normalize(items)`).
- [ ] **Step 1: Napisz testy, które padają** w `tests/dock.test.mjs`. Przypadki z wartościami:
- `defaultLabel("/handoff") === "/handoff"`
- `defaultLabel("npm test i raport po polsku") === "npm test i rapo…"` (15 + `…`)
- `defaultLabel(" a\n b ") === "a b"`
- `normalize("x")` daje `[]`
- `normalize([{id:"1",text:"a",mode:"send",label:""}, {id:"2",text:" a ",mode:"send",label:"x"}, {id:"3",text:"b",mode:"zly"}])` → jeden wpis `{id:"1",label:"a",text:"a",mode:"send"}`
- `normalize` z 35 poprawnymi wpisami → długość 30
- `pin([], " /clear ", "9")` → `[{id:"9",label:"/clear",text:"/clear",mode:"send"}]`; `pin` tego samego tekstu drugi raz → bez zmian; `pin(d, " ", "x")` → bez zmian; `pin` przy 30 → bez zmian
- `move(d, firstId, -1)` → bez zmian; `move(d, firstId, 1)` zamienia pierwszy z drugim; wejście nie jest zmutowane (`Object.isFrozen`-owa kopia albo porównanie z kopią)
- `rename(d, id, " ")` → `label === defaultLabel(text)`; `toggleMode` dwa razy → `"send"`
- `dockAction({mode:"insert"}, {hasAgent:true}) === "insert"`; `dockAction({mode:"send"}, {hasAgent:false}) === "none"`
- `dockMenu`: komendy `["rename","mode","left","right","remove"]`; dla pierwszego `left.disabled === true`; etykiety trybu jak wyżej
- `rowMenu({tab:"history",favorite:false,pinned:false})` → komendy `["insert","favorite"]`; `rowMenu({tab:"favorites",favorite:true,pinned:true})` → `["insert","pin","favorite"]` z etykietą „Odepnij z docka”
- `starMenu({text:"",pinned:false})[0].disabled === true`
W `tests/storage.test.mjs`: `saveDock` → `loadDock` daje to samo; `loadDock` przy wartości pod `ovis-composer.dock` i braku nowej → `[]`; śmieci pod kluczem → `[]`.
- [ ] **Step 2:** `npm test`: nowe testy padają (brak modułu lub funkcji).
- [ ] **Step 3:** Zaimplementuj `dock.js` i zmiany w `storage.js` (dla odczytu wzoruj się na `readList`, ale bez `loadMigrating`).
- [ ] **Step 4:** `npm test`: wszystko zielone.
- [ ] **Step 5: Commit** `feat: dock model and storage (herdr-composer.dock)`
### Task 2: Dock w belce: rysowanie i klik
**Files:**
- Modify: `herdr/herdr-composer/mods/herdr-composer/main.js` (`init`: `this.dock = loadDock(store)`; `renderCard`; nowe `renderDock`, `dockPress`)
**Interfaces — Consumes:** Task 1 (`loadDock`, `saveDock`, `dockAction`, `DockButton`), istniejące `syncOk`, `target`, `finish(agent, message, cx, mode)`, `overLimit`, `textarea.replace`, `syncFieldAfterReplace`, `notice`.
- [ ] **Step 1:** W `renderCard` wstaw za ☆ separator (1×18 px, `t.border`). Zamiast `div().flex_1()` wstaw `renderDock(t, active)`: `h_flex().flex_1().min_w(0).h(28).gap(6).overflow_x_scroll()` (`id("composer-dock")`). Pusty dock pokazuje podpowiedź w kolorze `t.dim`, rozmiar 12.
- [ ] **Step 2:** Przycisk `id("dock-"+b.id)`, wysokość 28, `px(11)`, `rounded(8)`, tekst 12, `flex_none`, maks. szerokość 150 z ucięciem. `send`: `bg(t.chrome)`, `text_color(t.foreground)`. `insert`: brak tła, ramka 1 px `t.border` (przerywana, jeśli API pozwala; jeśli nie, pełna) i prefiks `✎ ` w `t.dim`. Gdy `!active`: `text_color(t.dim)`, bez `cursor_pointer` i bez akcji. Tooltip z pełnym `text`, jeśli `gpui-kit` ma `tooltip`; jeśli nie, pomiń.
- [ ] **Step 3:** `dockPress(button, cx)`:
- `insert`: `this.textarea.replace(button.text)`, `syncFieldAfterReplace()`, notice „Wstawiono w miejscu kursora — nic nie zostało wysłane.”
- `send`: `syncOk` (przy błędzie ten sam komunikat co w `submit`, bez „Zostaje w szkicu”), potem `target()`, `overLimit(button.text)`, a na końcu `this.finish(agent, button.text.trim(), cx)`. Nie wolno wołać `clearField`, `submit` ani ruszać załączników.
- [ ] **Step 4:** `npm test` zielone, `install.cmd`, `herdr-app check` i `herdr-app status` bez błędów. Testu w GUI wykonawca nie robi (Task 4, Opus).
- [ ] **Step 5: Commit** `feat: composer dock in the bar (send / insert)`
### Task 3: Menu pod prawym klikiem (dock, ☆, wiersze panelu)
**Files:**
- Modify: `main.js` (menu i obsługa komend), `panel.js` (secondary click woła `on.rowMenu(key, event, cx)` zamiast `on.toggle`)
**Interfaces — Consumes:** `dockMenu`, `rowMenu`, `starMenu`, `pin`, `unpin`, `remove`, `move`, `rename`, `toggleMode`, `isPinned`, `saveDock`, istniejące `toggleFavoriteText`, `panelPickKey`, `isFavorite`, `newId`.
- [ ] **Step 1: Jeden renderer menu** `renderContextMenu(t, items, onCommand)`: `v_flex`, min. szerokość 210, `bg(t.raised)`, ramka `t.border`, `rounded(8)`, `p(4)`. Pozycja `danger` w kolorze błędu z motywu, `disabled` przygaszona i bez akcji. Stan `this.contextMenu = { kind: "dock" | "row" | "star", id | key, items } | null`. Esc z fokusem w polu zamyka najpierw menu (dopisz w `runAction("escape")` przed panelem i przerwaniem agenta). Klik poza menu zamyka (`on_mouse_down_out`).
- [ ] **Step 2: Kotwiczenie.** Przycisk docka i ☆: `Popover` z `.mouse_button("right")`, kontrolowany (`open(this.contextMenu?.kind===... && id===...)`, `on_open_change`). Wiersz panelu (lista wirtualna, `on_item_secondary_click`): menu jako `Popup` zakotwiczony do kontenera panelu (`anchor("top_right")`). Ruling: jeśli `Popover` nie zadziała z prawym przyciskiem w GUI, użyj `Popup` zakotwiczonego do całego docka, z tym samym rendererem.
- [ ] **Step 3: Komendy.**
- dock: `rename` ustawia `this.renaming = id` i rysuje przycisk jako mały `Input` (osobny stan input, szer. 110, wstępnie pełna nazwa). Enter wywołuje `rename` + `saveDock`. Esc i blur anulują. Kontekst `herdr-composer > Input` obejmuje też ten input, więc w `runAction` przy `this.renaming` klawisze `escape`, `up`, `down` i `tab` są obsługiwane jako edycja nazwy, a nie composera.
- dock: `mode` wywołuje `toggleMode`, `left`/`right` wywołują `move`, `remove` wywołuje `remove`. Każda kończy się `saveDock` i `cx.notify()`.
- wiersz: `insert` woła `panelPickKey`, `favorite` woła `toggleFavoriteText`, `pin` woła `pin(dock, text, this.newId())` albo `unpin`.
- ☆: `pin`/`unpin` bieżącego `this.value`.
- Lewy klik ☆ bez zmian.
- [ ] **Step 4: `Ctrl+D` w panelu** dalej przełącza ulubione od razu (sprawdź, że `panelKey` tego nie zmienia).
- [ ] **Step 5:** `npm test`, `install.cmd`, `herdr-app check` i `status` bez błędów.
- [ ] **Step 6: Commit** `feat: right-click menus for dock, star and panel rows`
### Task 4 (Opus): weryfikacja w GUI, dokumentacja
- [ ] Test GUI (SendKeys i `herdr-app shot`, wykonuje Opus):
- przypięcie z Ulubionych oraz z ☆;
- klik `send` przy `idle`: dociera do agenta, a szkic zostaje;
- klik przy `working`: trafia do kolejki;
- tryb `insert`: tekst w miejscu kursora;
- zmiana nazwy Enter/Esc;
- przesuwanie i usuwanie;
- przepełnienie (ponad 8 przycisków), przewijanie;
- brak agenta: wyszarzone;
- restart modu (`install.cmd`): dock przetrwał.
- [ ] README: wiersz w tabeli Użycie („dock”) i akapit w „Dane” (`herdr-composer.dock`). RECIPE.md: punkt w „How it behaves”. `preview.png`: nowy zrzut z dockiem.
- [ ] Commit `docs: composer dock in README, RECIPE and preview`