card-layouts/docs/api.md

API aplikacji kart

Wspólna aplikacja Fastify wystawia stan dowolnej karty, nawigację UML, checkpointy oraz Neovim wybrany przez MCP. Domyślny adres lokalnej instancji to http://127.0.0.1:8080. Kontrakt nie zależy od serii ani konkretnej karty; dane i recepty pochodzą z jej card_source.json.

API nie zarządza cyklem życia kontenera i nie podpina pane tmuxa. Za operacje start/reset/refresh/attach/detach odpowiada stemctl session. API korzysta z kontenera wskazanego przez bieżący wybór MCP i steruje zawartością jego sesji: Neovimem, Termdebugiem/GDB i checkpointami maszyny.

Tożsamość i stan

Metoda i endpoint	Znaczenie
GET /api/identity	id, UUID, wersja i SHA-256 źródłowego JSON-a karty.
GET /api/card-revision	Rewizja plików używana do automatycznego odświeżania strony.
GET /api/state	Złożony stan nawigacji, widoku, checkpointu i dostępności Neovima.
GET /api/control/state	Lekki stan synchronizacji strony z klientem sterującym.

Serwer jest przeznaczony do pracy lokalnej. Nie ma warstwy uwierzytelnienia, dlatego nie należy wystawiać go bezpośrednio poza zaufany host.

Nawigacja UML

Hierarchia nawigacji jest stała:

task → block → phase → step → snapshot

Metoda i endpoint	Znaczenie
GET /api/keyboard	Skróty i obsługiwane poziomy nawigacji.
GET /api/navigation/catalog	Wszystkie prawidłowe pozycje i ich indeksy.
GET /api/navigation/current	Bieżąca pozycja oraz status checkpointu.
PUT /api/navigation/current	Ustawia dokładną pozycję i poziom fokusu.
POST /api/navigation/move	Przesuwa kursor o delta na wybranym poziomie.

Przykład ustawienia kroku — identyfikatory są danymi konkretnej karty:

{
  "task_id": "<task-id>",
  "block_id": "<block-id>",
  "phase_id": "<phase-id>",
  "step_id": "<step-id>",
  "snapshot_ref": "<snapshot-ref>",
  "focus_level": "step",
  "sync_requested": true,
  "actor": "stemctl"
}

Checkpointy

Metoda i endpoint	Znaczenie
GET /api/checkpoint/status	Aktywna operacja, ostatni wynik i generacja.
POST /api/checkpoint/activate	Odtwarza stan GDB przypisany do snapshotu.

Wywołanie orkiestratora przypina zarówno kontener, jak i rewizję karty:

{
  "snapshot_ref": "<snapshot-ref>",
  "generation": 1784280000000,
  "expected_binding": {
    "container_id": "<container-id>",
    "instance": "<instance-id>",
    "profile": "hazard3-sim",
    "target": "hazard3-baremetal"
  },
  "expected_identity": {
    "id": "<card-id>",
    "uuid": "<card-uuid>",
    "version": "<card-version>",
    "source_sha256": "<sha256>"
  }
}

Replay kończy się powodzeniem wyłącznie ze statusem ready. Zmiana kontenera, socketu MCP albo źródłowego JSON-a podczas operacji powoduje odrzucenie wyniku; pozycja strony i SYNC ON nie są wtedy publikowane.

Widok i Neovim

Metoda i endpoint	Znaczenie
GET/PUT /api/viewer/state	Skala, scroll oraz visible/sync/control/expanded/fit.
GET /api/nvim/state	Bieżący bufor, okno, kursor i tryb Neovima.
PUT /api/nvim/cursor	Ustawia row, column i opcjonalnie window.
POST /api/nvim/input	Przekazuje do 256 znaków przez nvim_input.
WS /api/nvim-ui	Strumień zewnętrznego UI Neovima do panelu WWW.

Wyłączenie viewer.nvim.sync automatycznie wyłącza również viewer.nvim.control. Samo ponowne włączenie synchronizacji nie uzbraja sterowania klawiaturą bez jawnego control: true.

Podział odpowiedzialności widoków

Interaktywny diagram UML pokazuje przepływ i służy do wyboru kroku. Nie renderuje pod SVG osobnych paneli kodu, terminala, rejestrów, pamięci ani ramki stosu. Te dane prezentuje Nvim view, ustawiany przez snapshot wybranego kroku. Snapshoty pozostają w JSON/API, mimo że nie są powielane wizualnie pod diagramem.

Postęp zajęć i raport

Metoda i endpoint	Znaczenie
GET /api/progress	Katalog, statusy i podsumowanie wykonania.
PUT /api/progress/:itemId	Ustawia pending albo approved, notatkę i aktora.
GET /api/report/teams.md	Generuje bieżący raport Markdown do Teams.

Planowane strategie i adnotacje

Strategie debugowania będą przypinane do pełnego klucza task/block/phase/step/snapshot. Adnotacja pozostanie osobnym rekordem:

strategy: id, label, commands, expected_observations
annotation: id, strategy_id, target, geometry, style, text, visible

Planowane operacje show/hide/toggle zmienią wyłącznie visible. add/remove będą osobnymi, audytowalnymi operacjami. Dzięki temu ukrycie warstwy objaśnień nie usuwa przygotowanych oznaczeń.