Crafter.Graphics/interfaces/Crafter.Graphics-Router.cppm

//SPDX-License-Identifier: LGPL-3.0-only
//SPDX-FileCopyrightText: Copyright (C) 2026 Catcrafts®

// 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