High-Level API (DX Layer)

The previous chapters covered Tako's core subsystems — the Stack, the Router, the Hook Registry, and the EventBus. They are powerful, but coordinating them manually to display a simple overlay requires several steps:

// ❌ Old way — 4 manual steps just to show an overlay
ctx.Stack().Push("search")
ctx.Router().Focus(1, "search")
ctx.Hooks().Set("app.overlay.search", renderFunc)
ctx.Keys().Zone("search", 1).Bind("esc", closeFunc)

The High-Level API wraps all of that into a single, coherent facade on top of the core subsystems. These services are purely additive — every existing API still works unchanged.

The Single Entry Point: app.Overlay()

All high-level layer management goes through one accessor:

app.Overlay()                     → OverlayManager
├── .Show(id, fn)                 → basic overlay (render fn)
├── .ShowComponent(c)             → component overlay (render + keys bundled)
├── .Close()                      → pop topmost overlay
├── .CloseAll()                   → pop all overlays
├── .Top() string                 → current top layer ID
├── .IsActive() bool              → any overlay active?
└── .Dialog()                     → DialogService (sub-namespace)
    ├── .Confirm(msg, cb)
    └── ...                       ← future: Alert, Prompt, Select

Inside a plugin, the same API is available on the context:

ctx.Overlay().Show("id", fn)
ctx.Overlay().ShowComponent(c)
ctx.Overlay().Dialog().Confirm("Sure?", cb)

Why Dialog() as a sub-namespace?

Dialogs are overlays — they push onto the same stack, and are dismissed the same way. Grouping them under Overlay().Dialog() makes that relationship explicit, while also keeping OverlayManager's surface clean: new dialog types (Alert, Prompt, Select) are added to DialogService without modifying the OverlayManager interface.

// ✅ Clear hierarchy: "I'm managing an overlay → specifically a dialog"
app.Overlay().Dialog().Confirm("Delete?", func(yes bool) { ... })

// Cache it for multiple calls in the same function
d := ctx.Overlay().Dialog()
d.Confirm("Step 1?", cb1)

What's in This Section

Chapter	Topic
04.01 — Auto-Routing	How the Stack and Router now stay in sync automatically
04.02 — OverlayManager	Show/close overlays and components; access dialog sub-namespace
04.03 — Component Interface	Self-contained components that declare their own keys
04.04 — DialogService	Built-in event-driven interaction primitives

---

Prerequisites: Read 03.04 — Keybindings & the Focus Stack and 03.03 — Hooks first. The High-Level API is an abstraction over those systems — understanding them makes the DX improvements obvious.