From 4bb0e85612b4edf4e209fca592cb9544fde95d86 Mon Sep 17 00:00:00 2001 From: Factor Date: Thu, 19 Nov 2026 15:56:20 +0100 Subject: [PATCH] docs: composer dock design, mockup and plan Co-Authored-By: Claude Opus 5.5 --- .../mockups/herdr-composer-dock.html | 325 ++++++++++++++++++ .../plans/2026-11-19-composer-dock.md | 123 +++++++ .../specs/2026-11-19-composer-dock-design.md | 39 +++ 3 files changed, 487 insertions(+) create mode 100644 docs/superpowers/mockups/herdr-composer-dock.html create mode 100644 docs/superpowers/plans/2026-11-19-composer-dock.md create mode 100644 docs/superpowers/specs/2026-11-19-composer-dock-design.md diff --git a/docs/superpowers/mockups/herdr-composer-dock.html b/docs/superpowers/mockups/herdr-composer-dock.html new file mode 100644 index 0000000..1b53712 --- /dev/null +++ b/docs/superpowers/mockups/herdr-composer-dock.html @@ -0,0 +1,325 @@ +Composer Dock + + + + +
+

Composer Dock

+

Makieta paska przycisków na środku belki composera. Kliknij przycisk w docku, kliknij go prawym przyciskiem albo otwórz 🕘 i przypnij wpis z Ulubionych. Wszystko poniżej to przykładowe dane.

+ +
+
+
+
Ovis OpusOvis Fastshell
+
+
╭─ Claude Code · herdrMario
+
› dodaj test migracji kluczy dock
+
● Dodałem tests/dock.test.mjs, 6 przypadków, wszystkie zielone.
+
155 → 161 pass · 0 fail
+
+
+ +
+ +
+ + + + + + Ovis Fast · idle + +
+
+ +
+
+
+ +
+
+

Tryby przycisku

+
+
wysyła od razu (jak Enter)
+
tylko wstawia w miejsce kursora
+
+
+
+

Co się stało

+
Kliknij przycisk w docku.
+
+ Stan agenta: + +
+
+
+

Zasady

+
    +
  • Wysyłanie idzie tą samą drogą co Enter: agent pracuje → kolejka z odliczaniem 3 s, blocked → od razu.
  • +
  • Tekst w polu zostaje nietknięty przy przycisku „wysyła od razu”.
  • +
  • Dock jest wspólny dla wszystkich agentów, zapis w shared.json pod herdr-composer.dock.
  • +
  • Nazwa domyślnie to początek tekstu, do 16 znaków.
  • +
  • Za dużo przycisków: dock przewija się poziomo, chip i Wyślij stoją w miejscu.
  • +
+
+
+
+ +

Stany do porównania

+
+
+
+ +
Prawy klik w Ulubionych → Przypnij do docka
+ idle +
+

Pusty dock: szara podpowiedź zamiast przycisków.

+
+
+
+ +
+ idle +
+

Dużo przycisków: dock przewija się poziomo (kółkiem lub Shift+kółkiem).

+
+
+
+ +
+ idle +
+

Zmiana nazwy w miejscu: Enter zapisuje, Esc anuluje. Tekst wysyłany się nie zmienia.

+
+
+
+ + diff --git a/docs/superpowers/plans/2026-11-19-composer-dock.md b/docs/superpowers/plans/2026-11-19-composer-dock.md new file mode 100644 index 0000000..0168eac --- /dev/null +++ b/docs/superpowers/plans/2026-11-19-composer-dock.md @@ -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` diff --git a/docs/superpowers/specs/2026-11-19-composer-dock-design.md b/docs/superpowers/specs/2026-11-19-composer-dock-design.md new file mode 100644 index 0000000..dedaec8 --- /dev/null +++ b/docs/superpowers/specs/2026-11-19-composer-dock-design.md @@ -0,0 +1,39 @@ +# Composer Dock — projekt (krótki) + +Data: 2026-11-19 · Makieta: `docs/superpowers/mockups/herdr-composer-dock.html` (zaakceptowana przez użytkownika) + +## Cel i powód +Jednym kliknięciem wysłać do agenta często używaną komendę (np. `/handoff`, `/clear`) albo wstawić szablon promptu. Przyciski ma ustawiać sam użytkownik, z poziomu composera, bez edycji plików. + +## Zakres +- Dock: rząd przycisków w belce composera między ☆ a chipem statusu, w miejscu obecnego `div().flex_1()` (`main.js`, `renderCard`). Za ☆ jest separator. +- Przycisk = `{ id, label, text, mode }`, gdzie `mode`: `"send"` (domyślnie) lub `"insert"`. + - `send`: ta sama droga co Enter (kolejka, gdy agent pracuje; odliczanie; `--force` przy `blocked`; strażnik tożsamości agenta). Tekst w polu pozostaje nietknięty. + - `insert`: wstawia `text` w miejscu kursora (jak Enter w panelu Historii), nic nie wysyła. + - Wygląd: `send` ma pełne tło, `insert` przerywaną ramkę i znak ✎. +- Nazwa domyślna: `text` skrócony do najwyżej 16 znaków (15 + „…”), białe znaki zwinięte do jednej spacji. Pełny tekst pokazuje tooltip. +- **Dodawanie:** + 1. w panelu Ulubione: prawy klik na wpis otwiera menu z opcjami Wstaw, Przypnij do docka / Odepnij z docka oraz Usuń z ulubionych; + 2. prawy klik na ☆ otwiera menu „Przypnij bieżący tekst do docka” (nieaktywne przy pustym polu). + - Nowy przycisk trafia na koniec docka. Tekst już przypięty nie jest dodawany drugi raz; menu pokazuje wtedy „Odepnij”. +- **Prawy klik na przycisk w docku:** Zmień nazwę (edycja w miejscu: Enter zapisuje, Esc lub utrata fokusu anuluje, pusta nazwa wraca do domyślnej), Tylko wstawiaj / Wysyłaj od razu, Przesuń w lewo, Przesuń w prawo, Usuń z docka. +- **Pusty dock:** szara podpowiedź „Prawy klik w Ulubionych → Przypnij do docka”. +- **Przepełnienie:** dock przewija się poziomo (`overflow_x_scroll`). Chip i Wyślij nie są ruchome. +- **Brak agenta** (fokus na zwykłym terminalu): przyciski są wyszarzone i nieaktywne, tak jak 🕘/☆. +- **Zapis:** `shared.json`, klucz `herdr-composer.dock`. Dock jest jeden, wspólny dla wszystkich agentów. Limit 30 przycisków. Uszkodzone wpisy są pomijane, tak jak w historii i ulubionych. Nie dotyczy migracji z `ovis-composer` (nowy klucz). + +## Zmiana istniejącego zachowania +Dziś prawy klik na wiersz w panelu Historia/Ulubione od razu przełącza ulubione. Po zmianie otwiera menu. `Ctrl+D` nadal przełącza od razu. W zakładce Historia menu ma Wstaw i Dodaj do ulubionych / Usuń z ulubionych. + +## Podejścia (rozważone) +- Konfiguracja: plik JSON / edycja w composerze / oba. **Wybrane: w composerze** (decyzja użytkownika). +- Klik: zawsze wysyła / zawsze wstawia / tryb per przycisk. **Wybrane: per przycisk, domyślnie wysyła** (makieta zaakceptowana). + +## Poza zakresem +Ikony lub emoji jako przyciski, skróty klawiszowe do przycisków, przeciąganie myszą do zmiany kolejności, osobne docki per agent lub per projekt, import i eksport. + +## Dla wykonawcy +- Czysta logika (`dock.js`: dodaj, usuń, przesuń, zmień nazwę, przełącz tryb, `isPinned`, `defaultLabel`, `normalize` z limitem) z testami w `tests/dock.test.mjs`. Odczyt i zapis w `storage.js` (`KEYS.dock`, `loadDock`, `saveDock`). +- Menu: `Popover` z `gpui-kit`, otwierany prawym przyciskiem (`MouseButton "right"`). Jeśli nie da się go użyć w wierszach panelu (`on_item_secondary_click`), dopuszczalny jest własny popup pozycjonowany w miejscu kliknięcia. +- Akcja `send` korzysta z istniejącej ścieżki wysyłania (bez duplikowania logiki kolejki). Wymagany test, że tekst w polu i draft nie zmieniają się. +- Wysokość bloku (auto-fit) nie może rosnąć przez dock: dock ma stałą wysokość 28 px.