terminalShop-old/REFACTOR_PLAN.md

Refactor: Extract Flat Model State into Nested Page Structs

Context

The TUI's Model struct has 40+ flat fields for page-specific state (cursors, viewports, form pointers, booleans). The reference implementation (terminal-shop-source) uses nested per-page state structs, which keeps related state grouped, simplifies page transitions, and makes it easier to add new pages. The shopState struct already follows this pattern — this refactor extends it to all other pages.

This is a pure refactoring — no new features, no behavior changes. It unblocks future work (product variants, profile editing) by making the Model manageable.

---

New Struct Definitions (all in model.go)

splashState (3 fields, from Model)

Old Field	New Field
splashDataReady	splash.dataReady
splashDelayDone	splash.delayDone
splashCursor	splash.cursor

cartState (3 fields, new struct)

Old Field	New Field
CartCursor	cart.cursor
cartVP	cart.viewport
cartVPReady	cart.viewportReady

shippingState (5 fields, new struct)

Old Field	New Field
ShippingForm	shipping.form
ShippingView	shipping.view
AddressCursor	shipping.addressCursor
shippingVP	shipping.viewport
shippingVPReady	shipping.viewportReady

paymentState (7 fields, new struct)

Old Field	New Field
PaymentForm	payment.form
PaymentView	payment.view
CardCursor	payment.cardCursor
CollectURL	payment.collectURL
CollectCardCount	payment.collectCardCount
paymentVP	payment.viewport
paymentVPReady	payment.viewportReady

accountState (14 fields, new struct)

Old Field	New Field
AccountCursor	account.cursor
ScrollOffset	account.scrollOffset
OrderViewState	account.orderViewState
OrderCursor	account.orderCursor
FaqFocused	account.faqFocused
AddressListFocused	account.addressListFocused
CardListFocused	account.cardListFocused
AccountAddressCursor	account.addressCursor
AccountCardCursor	account.cardCursor
AccountAddressDeleting	account.addressDeleting
AccountCardDeleting	account.cardDeleting
SSHKeyListFocused	account.sshKeyListFocused
AccountSSHKeyCursor	account.sshKeyCursor
AccountSSHKeyDeleting	account.sshKeyDeleting

reviewState (2 fields, new struct)

Old Field	New Field
CardJustAdded	review.cardJustAdded
ReviewSuccess	review.success

confirmState (5 fields, new struct)

Old Field	New Field
ConfirmTotal	confirm.total
ConfirmItems	confirm.items
ConfirmShipping	confirm.shipping
confirmVP	confirm.viewport
confirmVPReady	confirm.viewportReady

Fields that STAY on Model (shared across pages)

Cart, Coffees, SavedAddresses, SavedCards, SSHKeys, Orders, OrdersLoaded, SSHKeysLoaded, FAQs, ShippingInfo, SelectedCard, CheckingOut, lastCartUpdateID, User, AccessToken, APIClient, ErrorMsg, Loading, all layout/resize/auth/rendering fields.

---

Execution Order (one struct at a time, compile+test after each)

Phase 1: splashState (simplest — 3 fields, 3 files)

• Files: model.go, update.go, splash.go

Phase 2: cartState (3 fields, 3 files)

• Files: model.go, cart.go, confirmation.go (resets cart cursor after checkout)

Phase 3: confirmState (5 fields, 1 file)

• Files: model.go, confirmation.go

Phase 4: reviewState (2 fields, 2 files)

• Files: model.go, confirmation.go, payment_form.go

Phase 5: shippingState (5 fields, 4 files)

• Files: model.go, shipping_form.go, update.go, footer.go

Phase 6: paymentState (7 fields, 4 files)

• Files: model.go, payment_form.go, update.go, footer.go

Phase 7: accountState (14 fields, 5 files — largest change)

• Files: model.go, account.go, views.go, footer.go, update.go
• Note: ScrollOffset moves here. All other pages use viewports, so the generic scroll block in views.go becomes account-only.

Phase 8: Add *Switch() methods + remove resetPageState()

• Add ShopSwitch(), CartSwitch(), AccountSwitch(), ShippingSwitch(), PaymentSwitch(), ReviewSwitch() to model.go
• Each calls SwitchPage(), zero-initializes its page state (m.cart = cartState{}), updates viewport
• Replace SwitchPage(X).resetPageState() calls in update.go, menu.go, confirmation.go
• Delete resetPageState()

---

Files Modified (summary)

File	Scope of Changes
pkg/tui/model.go	Define structs, remove flat fields, add Switch methods, delete resetPageState()
pkg/tui/update.go	Rename all field accesses, replace SwitchPage().resetPageState() with *Switch()
pkg/tui/cart.go	m.CartCursor -> m.cart.cursor, viewport fields
pkg/tui/account.go	14 field renames to m.account.*
pkg/tui/shipping_form.go	m.ShippingForm -> m.shipping.form, viewport/cursor fields
pkg/tui/payment_form.go	m.PaymentForm -> m.payment.form, viewport/cursor fields
pkg/tui/confirmation.go	confirm + review + cart cursor field renames
pkg/tui/views.go	m.ScrollOffset -> m.account.scrollOffset, account field refs
pkg/tui/footer.go	Multiple field renames for page-state reads
pkg/tui/menu.go	Replace SwitchPage().resetPageState() with *Switch()
pkg/tui/splash.go	m.splashCursor -> m.splash.cursor
pkg/tui/header.go	No changes
pkg/tui/breadcrumbs.go	No changes
pkg/tui/help.go	No changes
pkg/tui/faq.go	No changes

---

Verification

After each phase:

1. go build ./... — must compile
2. go test ./pkg/tui/... — existing tests pass
3. After all phases complete, manual test:
   • SSH in, verify splash -> shop transition
   • Browse shop, add items to cart
   • Full checkout: shipping -> payment -> review -> confirm
   • Account page: orders, addresses, cards, SSH keys, FAQ tabs
   • Menu (m) and help (?) modals
   • Terminal resize during each page