browser DOM support

interfaces/Crafter.Graphics-Router.cppm

@@ -0,0 +1,50 @@
+/*
+Crafter®.Graphics
+Copyright (C) 2026 Catcrafts®
+catcrafts.net
+
+This library is free software; you can redistribute it and/or
+modify it under the terms of the GNU Lesser General Public
+License version 3.0 as published by the Free Software Foundation;
+
+This library 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
+Lesser General Public License for more details.
+
+You should have received a copy of the GNU Lesser General Public
+License along with this library; if not, write to the Free Software
+Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301 USA
+*/
+
+// History / SPA routing. Thin C++ wrapper over the browser's
+// `history.pushState` / `popstate` and `window.location.pathname` —
+// exists so a single-page app written against this library can manage
+// its own URL without going through the DOM partition. Re-homed under
+// the `Crafter::Router` namespace (cleaner than CppDOM's bare free
+// functions; symmetric with `Crafter::Gamepad`).
+
+export module Crafter.Graphics:Router;
+#ifdef CRAFTER_GRAPHICS_WINDOW_DOM
+import std;
+
+export namespace Crafter::Router {
+
+    // Push a new history entry. `data` is a JSON string serialized by
+    // the caller — the browser stores it on the entry but the popstate
+    // listener in V1 receives no payload (matches CppDOM's surface).
+    // `url` is browser-relative, e.g. "/blog/post-1".
+    void PushState(std::string_view data, std::string_view title, std::string_view url);
+
+    // Subscribe to the browser's `popstate` event (back/forward button,
+    // programmatic history.go). Returns an opaque id usable with
+    // `RemovePopStateListener`. Multiple subscribers OK.
+    std::int32_t AddPopStateListener(std::function<void()> callback);
+    void         RemovePopStateListener(std::int32_t id);
+
+    // Current `window.location.pathname` as a freshly-allocated string.
+    // Allocates per call — cache the result in the caller if used in
+    // hot paths.
+    std::string GetPath();
+}
+#endif // CRAFTER_GRAPHICS_WINDOW_DOM