2 files changed, 229 insertions, 0 deletions
diff --git a/include/ricochet/tui/input.hh b/include/ricochet/tui/input.hh
new file mode 100644
index 0000000..df5b458
--- /dev/null
+++ b/include/ricochet/tui/input.hh
@@ -0,0 +1,119 @@
+/*
+ * Ricochet - A minimalist CLI web browser for fast, distraction-free navigation.
+ * Copyright (C) 2026  Richard Qin
+ *
+ * This program is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU General Public License as published by
+ * the Free Software Foundation, either version 3 of the License, or
+ * (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU General Public License for more details.
+ *
+ * You should have received a copy of the GNU General Public License
+ * along with this program.  If not, see <https://www.gnu.org/licenses/>.
+ */
+
+#pragma once
+
+#include <chrono>
+#include <cstdint>
+#include <string>
+#include <variant>
+
+namespace ricochet::tui {
+
+struct ScreenSize
+{
+  int rows { 0 };
+  int columns { 0 };
+  bool operator==( const ScreenSize& ) const = default;
+};
+
+struct CellPoint
+{
+  int row { 0 };
+  int column { 0 };
+};
+
+struct Modifiers
+{
+  bool shift { false };
+  bool control { false };
+  bool alt { false };
+  bool operator==( const Modifiers& ) const = default;
+};
+
+enum class KeyCode : std::uint8_t
+{
+  Character,
+  Escape,
+  Enter,
+  Tab,
+  Backspace,
+  Delete,
+  Insert,
+  Left,
+  Right,
+  Up,
+  Down,
+  Home,
+  End,
+  PageUp,
+  PageDown,
+  Function,
+  Unsupported
+};
+
+struct Key
+{
+  KeyCode code { KeyCode::Unsupported };
+  Modifiers modifiers {};
+  char32_t character { 0 };
+  unsigned int function { 0 };
+};
+
+struct TextInput
+{ char32_t character { 0 }; };
+
+struct Paste
+{ std::u32string text {}; };
+
+struct MouseButtons
+{
+  bool left { false };
+  bool middle { false };
+  bool right { false };
+};
+
+struct Mouse
+{
+  // Screen coordinates; the view router converts these to region-local coordinates.
+  CellPoint position {};
+  Modifiers modifiers {};
+  MouseButtons pressed {};
+  MouseButtons released {};
+  bool motion { false };
+  int wheel_steps { 0 }; // Positive scrolls down.
+};
+
+struct Resize
+{ ScreenSize size {}; };
+
+struct Tick
+{ std::chrono::steady_clock::time_point now {}; };
+
+enum class TerminalCloseReason : std::uint8_t
+{
+  Disconnected,
+  TerminationSignal
+};
+
+struct TerminalClosed
+{ TerminalCloseReason reason { TerminalCloseReason::Disconnected }; };
+
+using InputEvent = std::variant<Key, TextInput, Paste, Mouse, Resize, Tick, TerminalClosed>;
+
+} // namespace ricochet::tui
diff --git a/include/ricochet/tui/session.hh b/include/ricochet/tui/session.hh
new file mode 100644
index 0000000..9968178
--- /dev/null
+++ b/include/ricochet/tui/session.hh
@@ -0,0 +1,110 @@
+/*
+ * Ricochet - A minimalist CLI web browser for fast, distraction-free navigation.
+ * Copyright (C) 2026  Richard Qin
+ *
+ * This program is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU General Public License as published by
+ * the Free Software Foundation, either version 3 of the License, or
+ * (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU General Public License for more details.
+ *
+ * You should have received a copy of the GNU General Public License
+ * along with this program.  If not, see <https://www.gnu.org/licenses/>.
+ */
+
+#pragma once
+
+#include "ricochet/tui/input.hh"
+#include "ricochet/tui/messages.hh"
+
+#include <chrono>
+#include <cstdio>
+#include <memory>
+#include <optional>
+#include <string>
+#include <vector>
+
+namespace ricochet::tui {
+
+namespace detail {
+class Mailbox;
+}
+
+struct TerminalOptions
+{
+  bool capture_mouse { true };
+  // Explicit host opt-in: terminfo does not establish bracketed-paste support.
+  bool bracketed_paste { false };
+  std::chrono::milliseconds escape_delay { 25 };
+};
+
+struct TerminalCapabilities
+{
+  bool colors { false };
+  bool mouse_buttons { false };
+  bool mouse_motion { false };
+  bool bracketed_paste { false };
+};
+
+enum class PostResult : std::uint8_t
+{
+  Queued,
+  Closed
+};
+
+// A sender can outlive the UI session. Posting is thread-safe; it never calls curses.
+class UpdateSender
+{
+public:
+  PostResult post_update( HostUpdate update ) const;
+
+private:
+  friend class Session;
+  explicit UpdateSender( std::shared_ptr<detail::Mailbox> mailbox );
+  std::shared_ptr<detail::Mailbox> mailbox_;
+};
+
+struct StepResult
+{
+  bool running { true };
+  // Content editing/layout handlers are subsequent milestones. Until they exist,
+  // unsupported updates are returned intact rather than silently acknowledged.
+  std::vector<HostUpdate> unhandled_updates {};
+  std::optional<TerminalClosed> terminal_closed {};
+  std::optional<std::string> error {};
+};
+
+class Session
+{
+public:
+  explicit Session( TerminalOptions options = {} );
+  // Streams must remain open until destruction. Construction, step, close and
+  // destruction run on the same UI thread; only one terminal session may exist.
+  Session( std::FILE& input, std::FILE& output, TerminalOptions options = {} );
+  ~Session();
+
+  Session( const Session& ) = delete;
+  Session& operator=( const Session& ) = delete;
+  Session( Session&& ) = delete;
+  Session& operator=( Session&& ) = delete;
+
+  UpdateSender sender() const;
+  PostResult post_update( HostUpdate update );
+  // max_wait bounds idle waiting. Decoding a partial terminal key sequence can
+  // additionally wait for escape_delay; processing batches is bounded separately.
+  StepResult step( std::chrono::milliseconds max_wait );
+  std::vector<UserAction> take_actions();
+  std::optional<ViewSnapshot> snapshot( TabId tab ) const;
+  TerminalCapabilities capabilities() const;
+  void close() noexcept;
+
+private:
+  class Impl;
+  std::unique_ptr<Impl> impl_;
+};
+
+} // namespace ricochet::tui