12 KiB
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.mdidocs/. - Kod modu:
herdr/herdr-composer/mods/herdr-composer/. Moduły czyste (dock.js,storage.js) nie importujągpui-kit,gpui-baseaniherdr. - Klucz zapisu
herdr-composer.dock, bez odczytuovis-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 agentworkingalbo kolejka niepusta: wiadomość trafia do kolejki, a nie wychodzi od razu. Agentblockeddostaje ją od razu z--force. - Klik tuż po przełączeniu agenta (okno 500 ms):
syncOkblokuje wysyłkę i pokazuje komunikat, bez wysłania do złego agenta. - Uszkodzony albo ręcznie zmieniony
herdr-composer.dockwshared.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, noweloadDock/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 (iditextniepuste,modez listy). Pustylabelzamienia nadefaultLabel(text). Odrzuca duplikatytext(porównanie potrim(), pierwszy wygrywa) i obcina do 30. -
isPinned(dock, text): boolean(porównanie potrim()). -
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 potrim()→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” przysend, „Wysyłaj od razu” przyinsert),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ładcefavoritespin(„Przypnij do docka” / „Odepnij z docka”). Na końcufavorite(„Dodaj do ulubionych” / „Usuń z ulubionych”,dangerprzy usuwaniu). -
starMenu({ text: string, pinned: boolean }): MenuItem[]: jedna pozycjapin(„Przypnij bieżący tekst do docka” / „Odepnij bieżący tekst z docka”),disabled, gdytext.trim()jest pusty. -
storage.js:KEYS.dock = "herdr-composer.dock",loadDock(store): DockButton[](przeznormalize, bez fallbackuovis-composer.),saveDock(store, items): void(zapisujenormalize(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"}normalizez 35 poprawnymi wpisami → długość 30pin([], " /clear ", "9")→[{id:"9",label:"/clear",text:"/clear",mode:"send"}];pintego samego tekstu drugi raz → bez zmian;pin(d, " ", "x")→ bez zmian;pinprzy 30 → bez zmianmove(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);toggleModedwa razy →"send"dockAction({mode:"insert"}, {hasAgent:true}) === "insert";dockAction({mode:"send"}, {hasAgent:false}) === "none"dockMenu: komendy["rename","mode","left","right","remove"]; dla pierwszegoleft.disabled === true; etykiety trybu jak wyżejrowMenu({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→loadDockdaje to samo;loadDockprzy wartości podovis-composer.docki braku nowej →[]; śmieci pod kluczem →[]. -
Step 2:
npm test: nowe testy padają (brak modułu lub funkcji). -
Step 3: Zaimplementuj
dock.jsi zmiany wstorage.js(dla odczytu wzoruj się nareadList, ale bezloadMigrating). -
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; nowerenderDock,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
renderCardwstaw za ☆ separator (1×18 px,t.border). Zamiastdiv().flex_1()wstawrenderDock(t, active):h_flex().flex_1().min_w(0).h(28).gap(6).overflow_x_scroll()(id("composer-dock")). Pusty dock pokazuje podpowiedź w kolorzet.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 pxt.border(przerywana, jeśli API pozwala; jeśli nie, pełna) i prefiks✎wt.dim. Gdy!active:text_color(t.dim), bezcursor_pointeri bez akcji. Tooltip z pełnymtext, jeśligpui-kitmatooltip; 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 wsubmit, bez „Zostaje w szkicu”), potemtarget(),overLimit(button.text), a na końcuthis.finish(agent, button.text.trim(), cx). Nie wolno wołaćclearField,submitani ruszać załączników.
- Step 4:
npm testzielone,install.cmd,herdr-app checkiherdr-app statusbez 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łaon.rowMenu(key, event, cx)zamiaston.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), ramkat.border,rounded(8),p(4). Pozycjadangerw kolorze błędu z motywu,disabledprzygaszona i bez akcji. Stanthis.contextMenu = { kind: "dock" | "row" | "star", id | key, items } | null. Esc z fokusem w polu zamyka najpierw menu (dopisz wrunAction("escape")przed panelem i przerwaniem agenta). Klik poza menu zamyka (on_mouse_down_out). - Step 2: Kotwiczenie. Przycisk docka i ☆:
Popoverz.mouse_button("right"), kontrolowany (open(this.contextMenu?.kind===... && id===...),on_open_change). Wiersz panelu (lista wirtualna,on_item_secondary_click): menu jakoPopupzakotwiczony do kontenera panelu (anchor("top_right")). Ruling: jeśliPopovernie zadziała z prawym przyciskiem w GUI, użyjPopupzakotwiczonego do całego docka, z tym samym rendererem. - Step 3: Komendy.
- dock:
renameustawiathis.renaming = idi rysuje przycisk jako małyInput(osobny stan input, szer. 110, wstępnie pełna nazwa). Enter wywołujerename+saveDock. Esc i blur anulują. Kontekstherdr-composer > Inputobejmuje też ten input, więc wrunActionprzythis.renamingklawiszeescape,up,downitabsą obsługiwane jako edycja nazwy, a nie composera. - dock:
modewywołujetoggleMode,left/rightwywołująmove,removewywołujeremove. Każda kończy sięsaveDockicx.notify(). - wiersz:
insertwołapanelPickKey,favoritewołatoggleFavoriteText,pinwołapin(dock, text, this.newId())albounpin. - ☆:
pin/unpinbieżącegothis.value. - Lewy klik ☆ bez zmian.
- dock:
- Step 4:
Ctrl+Dw panelu dalej przełącza ulubione od razu (sprawdź, żepanelKeytego nie zmienia). - Step 5:
npm test,install.cmd,herdr-app checkistatusbez 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
sendprzyidle: 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