initial commit

native/include/lua/runtime.h

@@ -0,0 +1,162 @@
+#pragma once
+
+#include <map>
+#include <string>
+#include <vector>
+
+#include <lua/layout.h>
+#include <lua/providers.h>
+
+struct lua_State;
+
+namespace esp32lua {
+
+// The version sys.getAPIVersion() reports: this contract, not the firmware's build.
+constexpr int32_t API_VERSION = 1;
+
+// Where the runtime looks for apps, their data, and shared modules.
+struct Paths {
+  std::string apps = "/.lua/apps";
+  std::string data = "/.lua/data";
+  std::string lib = "/.lua/lib";
+  // Where sys.back() lands once history is empty. It is an app like any other.
+  std::string home = "Home";
+};
+
+// Firmware supplies every core provider; a null feature provider is how sys.hasFeature()
+// answers false, and its namespace additions are simply never registered.
+struct Providers {
+  LogProvider* log = nullptr;
+  SettingsProvider* settings = nullptr;
+  SysProvider* sys = nullptr;
+  FsProvider* fs = nullptr;
+  GuiProvider* gui = nullptr;
+  HttpProvider* http = nullptr;
+  TimerProvider* timer = nullptr;
+  WifiProvider* wifi = nullptr;
+  BleProvider* ble = nullptr;
+
+  TouchProvider* touch = nullptr;
+  ButtonsProvider* buttons = nullptr;
+};
+
+class Runtime {
+ public:
+  explicit Runtime(const Providers& providers, const Paths& paths = Paths());
+  ~Runtime();
+
+  Runtime(const Runtime&) = delete;
+  Runtime& operator=(const Runtime&) = delete;
+
+  // Fails when a core provider is missing, leaving no Lua state behind.
+  bool open();
+  void close();
+  lua_State* state() const { return state_; }
+
+  // Replaces the running app with a fresh lua_State, loads <apps>/<path>/main.lua, and calls
+  // init(arg). A failure leaves no app running rather than a half-built one.
+  bool startApp(const std::string& path, const std::string& arg = std::string());
+  bool hasApp() const { return !appPath_.empty(); }
+  // The app-relative route, its immutable first component, and the title the app chose.
+  const std::string& appPath() const { return appPath_; }
+  std::string appId() const;
+  std::string appDataPath() const;
+  const std::string& appTitle() const { return appTitle_; }
+  void setAppTitle(const std::string& title) { appTitle_ = title; }
+  bool hasFeature(const std::string& feature) const;
+
+  // sys.launch/replace/back record intent and return; swapping the lua_State inside a callback
+  // would free the VM that is still executing. The firmware applies it between batches.
+  void requestLaunch(const std::string& path, const std::string& arg, bool replace);
+  void requestBack();
+  bool hasPendingNavigation() const { return pending_.kind != Pending::None; }
+  // Loads whatever was requested. False means the app failed to start or history ran out at the
+  // launcher, in which case no app is running.
+  bool applyPendingNavigation();
+
+  LogProvider& log() const { return *providers_.log; }
+  SettingsProvider& settings() const { return *providers_.settings; }
+  SysProvider& sys() const { return *providers_.sys; }
+  FsProvider& fs() const { return *providers_.fs; }
+  GuiProvider& gui() const { return *providers_.gui; }
+  HttpProvider& http() const { return *providers_.http; }
+  TimerProvider& timer() const { return *providers_.timer; }
+  WifiProvider& wifi() const { return *providers_.wifi; }
+  BleProvider& ble() const { return *providers_.ble; }
+  TouchProvider& touch() const { return *providers_.touch; }
+  ButtonsProvider& buttons() const { return *providers_.buttons; }
+
+  ui::Tree& tree() { return tree_; }
+
+  // Entry points into the app. The firmware decides whether an event reaches the app at all --
+  // jitter, chrome and debouncing are its business -- and the runtime decides what the app sees.
+  // Only a failed init() stops an app; every other callback logs and carries on.
+  bool callInit(const std::string& arg);
+  void callDraw(int32_t deltaMs);
+  // An Up phase also fires the on_touch tap alias, in that order.
+  void callTouch(TouchPhase phase, int32_t x, int32_t y);
+  // A release also fires the on_button tap alias, in that order.
+  void callButton(const std::string& button, bool pressed);
+
+  // Timer identity and callback retention are the runtime's; deadlines are the firmware's.
+  TimerId addTimer(int callbackRef, int32_t intervalMs, bool repeating);
+  bool cancelTimer(TimerId id);
+  // Called on the Lua thread when a scheduled deadline elapses.
+  void callTimer(TimerId id);
+
+  static Runtime* from(lua_State* state);
+
+ private:
+  struct Timer {
+    int callbackRef;
+    bool repeating;
+  };
+
+  struct Route {
+    std::string path;
+    std::string arg;
+  };
+
+  struct Pending {
+    enum Kind { None, Launch, Replace, Back } kind = None;
+    Route route;
+  };
+
+  bool loadScript(const std::string& path);
+  void installLoader(const std::string& appDir);
+  static int searchModule(lua_State* state);
+  static int loadFile(lua_State* state);
+
+  // A batch is one visit to the app, however many callbacks it fans out into: a tap fires
+  // on_touch_up and then the on_touch alias, and a timer can fire inside draw. Committing per
+  // callback would refresh an e-ink panel twice for one visible change, so the display is
+  // committed when the outermost call returns.
+  class Batch {
+   public:
+    explicit Batch(Runtime& runtime);
+    ~Batch();
+
+   private:
+    Runtime& runtime_;
+  };
+
+  // Pushes the named global, or returns false when the app does not define it.
+  bool beginCall(const char* name);
+  bool finishCall(const char* name, int argc);
+  void cancelAllTimers();
+
+  Providers providers_;
+  lua_State* state_ = nullptr;
+  ui::Tree tree_;
+  std::map<TimerId, Timer> timers_;
+  TimerId nextTimerId_ = 1;
+  int batchDepth_ = 0;
+
+  Paths paths_;
+  std::string appPath_;
+  std::string appTitle_;
+  std::vector<Route> history_;
+  Pending pending_;
+};
+
+}  // namespace esp32lua