@dusted/anqst 1.7.2 → 1.7.3

package/AnQstWebBase/AnQstWebBaseAbi.cmake

@@ -0,0 +1 @@
+set(ANQST_WEBBASE_ABI_HASH_STAMP "_da43ea0d526e8ac0a869ccc79976519d2566b40d8b97a12bddfa2aaaac5304f6")

package/AnQstWebBase/CMakeLists.txt

@@ -0,0 +1,116 @@
+cmake_minimum_required(VERSION 3.21)
+project(AnQstWebBase VERSION 0.1.0 LANGUAGES CXX)
+
+set(CMAKE_CXX_STANDARD 17)
+set(CMAKE_CXX_STANDARD_REQUIRED ON)
+set(CMAKE_AUTOMOC ON)
+set(CMAKE_AUTOUIC ON)
+set(CMAKE_AUTORCC ON)
+set(CMAKE_RUNTIME_OUTPUT_DIRECTORY "${CMAKE_BINARY_DIR}/bin")
+set(CMAKE_RUNTIME_OUTPUT_DIRECTORY_DEBUG "${CMAKE_BINARY_DIR}/bin")
+set(CMAKE_RUNTIME_OUTPUT_DIRECTORY_RELEASE "${CMAKE_BINARY_DIR}/bin")
+set(CMAKE_RUNTIME_OUTPUT_DIRECTORY_RELWITHDEBINFO "${CMAKE_BINARY_DIR}/bin")
+set(CMAKE_RUNTIME_OUTPUT_DIRECTORY_MINSIZEREL "${CMAKE_BINARY_DIR}/bin")
+
+option(ANQSTWEBBASE_BUILD_TESTS "Build AnQstWebBase unit tests" ON)
+
+include("${CMAKE_CURRENT_SOURCE_DIR}/AnQstWebBaseAbi.cmake" OPTIONAL)
+if(NOT DEFINED ANQST_WEBBASE_ABI_HASH_STAMP OR ANQST_WEBBASE_ABI_HASH_STAMP STREQUAL "_local_0")
+    string(TIMESTAMP ANQST_WEBBASE_LOCAL_EPOCH "%s")
+    set(ANQST_WEBBASE_ABI_HASH_STAMP "_local_${ANQST_WEBBASE_LOCAL_EPOCH}")
+endif()
+set(ANQST_WEBBASE_TARGET "anqstwebhost${ANQST_WEBBASE_ABI_HASH_STAMP}")
+configure_file(
+    "${CMAKE_CURRENT_SOURCE_DIR}/src/AnQstWebBaseAbi.h.in"
+    "${CMAKE_CURRENT_BINARY_DIR}/generated/AnQstWebBaseAbi.h"
+    @ONLY
+)
+
+find_package(Qt5 REQUIRED COMPONENTS Core Widgets Network WebEngineWidgets WebChannel)
+
+get_target_property(QT5_CORE_DLL_RELEASE Qt5::Core IMPORTED_LOCATION_RELEASE)
+if(NOT QT5_CORE_DLL_RELEASE)
+    get_target_property(QT5_CORE_DLL_RELEASE Qt5::Core IMPORTED_LOCATION)
+endif()
+get_filename_component(QT5_BIN_DIR "${QT5_CORE_DLL_RELEASE}" DIRECTORY)
+find_program(WINDEPLOYQT_EXECUTABLE windeployqt HINTS "${QT5_BIN_DIR}")
+
+function(anqst_configure_qt_runtime target_name)
+    set_target_properties(${target_name} PROPERTIES
+        RUNTIME_OUTPUT_DIRECTORY "${CMAKE_RUNTIME_OUTPUT_DIRECTORY}"
+        RUNTIME_OUTPUT_DIRECTORY_DEBUG "${CMAKE_RUNTIME_OUTPUT_DIRECTORY_DEBUG}"
+        RUNTIME_OUTPUT_DIRECTORY_RELEASE "${CMAKE_RUNTIME_OUTPUT_DIRECTORY_RELEASE}"
+        RUNTIME_OUTPUT_DIRECTORY_RELWITHDEBINFO "${CMAKE_RUNTIME_OUTPUT_DIRECTORY_RELWITHDEBINFO}"
+        RUNTIME_OUTPUT_DIRECTORY_MINSIZEREL "${CMAKE_RUNTIME_OUTPUT_DIRECTORY_MINSIZEREL}"
+    )
+
+    if(WIN32 AND WINDEPLOYQT_EXECUTABLE)
+        add_custom_command(
+            TARGET ${target_name}
+            POST_BUILD
+            COMMAND "${WINDEPLOYQT_EXECUTABLE}"
+                --no-translations
+                --no-compiler-runtime
+                --no-opengl-sw
+                --release
+                --dir "$<TARGET_FILE_DIR:${target_name}>"
+                "$<TARGET_FILE:${target_name}>"
+            COMMENT "Deploying Qt runtime files for ${target_name}"
+            VERBATIM
+        )
+    endif()
+endfunction()
+
+if(NOT TARGET ${ANQST_WEBBASE_TARGET})
+    add_library(${ANQST_WEBBASE_TARGET} STATIC
+        src/AnQstBase93.cpp
+        src/AnQstBase93.h
+        src/AnQstBridgeProxy.cpp
+        src/AnQstBridgeProxy.h
+        src/AnQstWidgetDebugDialog.cpp
+        src/AnQstWidgetDebugDialog.h
+        src/AnQstWebHostBase.cpp
+        src/AnQstWebHostBase.h
+        src/AnQstHostBridgeFacade.cpp
+        src/AnQstHostBridgeFacade.h
+        src/AngularHttpBaseServer.cpp
+        src/AngularHttpBaseServer.h
+        src/UI/AnQstWidgetDebugDialog.ui
+        "${CMAKE_CURRENT_BINARY_DIR}/generated/AnQstWebBaseAbi.h"
+    )
+    set_target_properties(${ANQST_WEBBASE_TARGET} PROPERTIES
+        AUTOUIC_SEARCH_PATHS "${CMAKE_CURRENT_SOURCE_DIR}/src/UI"
+    )
+
+    target_link_libraries(${ANQST_WEBBASE_TARGET}
+        PUBLIC
+            Qt5::Core
+            Qt5::Widgets
+            Qt5::Network
+            Qt5::WebEngineWidgets
+            Qt5::WebChannel
+    )
+
+    target_include_directories(${ANQST_WEBBASE_TARGET}
+        PUBLIC
+            "${CMAKE_CURRENT_BINARY_DIR}/generated"
+            ${CMAKE_CURRENT_SOURCE_DIR}/src
+    )
+endif()
+
+if(NOT TARGET anqstwebhost)
+    add_library(anqstwebhost ALIAS ${ANQST_WEBBASE_TARGET})
+else()
+    get_target_property(ANQST_WEBBASE_EXISTING_ALIAS anqstwebhost ALIASED_TARGET)
+    if(NOT ANQST_WEBBASE_EXISTING_ALIAS)
+        set(ANQST_WEBBASE_EXISTING_ALIAS "non-alias target anqstwebhost")
+    endif()
+    if(NOT ANQST_WEBBASE_EXISTING_ALIAS STREQUAL ANQST_WEBBASE_TARGET)
+        message(STATUS "${CMAKE_CURRENT_SOURCE_DIR} exports ${ANQST_WEBBASE_TARGET} while shorthand anqstwebhost exports ${ANQST_WEBBASE_EXISTING_ALIAS}")
+    endif()
+endif()
+
+if(ANQSTWEBBASE_BUILD_TESTS)
+    enable_testing()
+    add_subdirectory(tests)
+endif()

package/AnQstWebBase/CMakeUserPresets.json

@@ -0,0 +1,14 @@
+{
+    "version": 4,
+    "configurePresets": [
+        {
+            "name": "linux-debug",
+            "displayName": "Linux Debug (system packages)",
+            "generator": "Ninja",
+            "binaryDir": "${sourceDir}/build",
+            "cacheVariables": {
+                "CMAKE_BUILD_TYPE": "Debug"
+            }
+        }
+    ]
+}

package/AnQstWebBase/README.md

@@ -0,0 +1,65 @@
+# AnQstWebBase Documentation
+
+This directory is a future-facing documentation area for designing a reusable Qt host base:
+`AnQstWebHostBase` (inherits from `QWidget` and owns an internal `QWebEngineView`), intended to support AnQst-generated widget classes.
+
+## Scope and constraints
+
+- Host any web app from **QRC** or **local filesystem directory**.
+- Default runtime remains embedded/local (`QWebEngine` + `QWebChannel`).
+- Development mode can be enabled with `enableDebug()` to:
+  - blank in-situ widget rendering,
+  - serve app assets over HTTP from configured content root,
+  - bridge AnQst transport over WebSocket for browser-attached development tools.
+- HTTP binding defaults to localhost and can be widened for LAN testing.
+- Host-owned bridge bootstrap: web apps must not include Qt `qwebchannel.js` script tags manually.
+- Embedded host diagnostics are exposed through `onWebEngineError(const QString& channel, const QString& detail)`.
+  - The native `QWebEngine` subset is the baseline and remains available even if JavaScript never initializes, bridge bootstrap never becomes usable, or the renderer crashes.
+  - JavaScript stack traces are additive enrichment captured through an early `DocumentCreation` script and surfaced through the same signal when the renderer and JS engine stay alive long enough to produce them.
+  - External-browser host mode is out of scope for this signal.
+
+## Documentation structure
+
+- `PHASE-1-Host-Base.md`  
+  High-level API and behavior shape for `AnQstWebHostBase`.
+- `PHASE-2-AnQstGen-Mapping.md`  
+  How AnQst spec concepts map onto the host base contract.
+- `PHASE-3-Widget-Specific-Generation.md`  
+  How generator output can derive spec-specific widgets from the base.
+- `PHASE-4-Validation-Adoption.md`  
+  Validation strategy and rollout phases.
+
+## Design goal
+
+Keep host APIs narrow and predictable so `AnQstGen` can generate a spec-specific widget class with minimal custom glue code.
+
+## Shared codec runtime helpers
+
+- `src/AnQstBase93.h` / `src/AnQstBase93.cpp` provide the shared C++ base93 encoder/decoder used by generated widget codecs.
+- Generated widgets call these helpers directly instead of emitting per-widget base93 implementations.
+
+## Current implementation note
+
+- The demo application in `../../Examples/demo/` is wired through generated C++ widget output (`../../Examples/demo/lib/demo-widget/generated_output/DemoHostWidget_QtWidget`) and links only against the autogenerated widget library target (`DemoHostWidgetWidget`).
+- The generated widget library carries the embedded Angular assets (`<WidgetName>.qrc` + `webapp/*`), so the Qt host app does not own web asset/QRC wiring.
+- The demo consumes `../../Examples/demo/lib/demo-widget/anqst-cmake/CMakeLists.txt` as the widget dependency entrypoint.
+- The previous standalone demo placeholder page (`../../Examples/demo/hello.html`) is removed from the canonical demo path.
+
+## Build notes
+
+- Linux (Ubuntu): use system packages only
+- Windows: Wild wild west, amirite?
+
+### Ubuntu quick start
+
+From workspace root:
+
+```bash
+sudo ./install_dependencies.sh
+```
+
+Then build:
+
+```bash
+Look at Examples/build.sh
+```

package/AnQstWebBase/src/AnQstBase93.cpp

@@ -0,0 +1,91 @@
+#include "AnQstBase93.h"
+
+#include <QChar>
+
+#include <cstddef>
+
+namespace ANQST_WEBBASE_NAMESPACE {
+
+namespace {
+constexpr char kBase93Alphabet[] =
+    " !#$%&'()*+,-./0123456789:;<=>?@ABCDEFGHIJKLMNOPQRSTUVWXYZ[]^_`abcdefghijklmnopqrstuvwxyz{|}~";
+
+inline int base93AlphabetIndex(QChar c) {
+    const unsigned int uc = c.unicode();
+    return static_cast<int>(uc) - 32 - static_cast<int>(uc > 34u) - static_cast<int>(uc > 92u);
+}
+} // namespace
+
+QString anqstBase93Encode(const std::vector<std::uint8_t>& bytes) {
+    const std::size_t inputSize = bytes.size();
+    const std::size_t fullBlocks = inputSize >> 2;
+    const std::size_t remainder = inputSize & 3u;
+    QString output(static_cast<qsizetype>(fullBlocks * 5 + (remainder ? remainder + 1 : 0)), QChar(u'\0'));
+    QChar* out = output.data();
+    std::size_t writeOffset = 0;
+    for (std::size_t i = 0; i < fullBlocks; ++i) {
+        const std::size_t byteOffset = i << 2;
+        std::uint32_t value =
+            (static_cast<std::uint32_t>(bytes[byteOffset]) << 24) |
+            (static_cast<std::uint32_t>(bytes[byteOffset + 1]) << 16) |
+            (static_cast<std::uint32_t>(bytes[byteOffset + 2]) << 8) |
+            static_cast<std::uint32_t>(bytes[byteOffset + 3]);
+        out[static_cast<qsizetype>(writeOffset + 4)] = QChar::fromLatin1(kBase93Alphabet[value % 93u]);
+        value /= 93u;
+        out[static_cast<qsizetype>(writeOffset + 3)] = QChar::fromLatin1(kBase93Alphabet[value % 93u]);
+        value /= 93u;
+        out[static_cast<qsizetype>(writeOffset + 2)] = QChar::fromLatin1(kBase93Alphabet[value % 93u]);
+        value /= 93u;
+        out[static_cast<qsizetype>(writeOffset + 1)] = QChar::fromLatin1(kBase93Alphabet[value % 93u]);
+        out[static_cast<qsizetype>(writeOffset)] = QChar::fromLatin1(kBase93Alphabet[value / 93u]);
+        writeOffset += 5;
+    }
+    if (remainder != 0u) {
+        const std::size_t byteOffset = fullBlocks << 2;
+        std::uint32_t value = 0;
+        for (std::size_t j = 0; j < remainder; ++j) {
+            value = (value << 8) | bytes[byteOffset + j];
+        }
+        for (std::size_t j = remainder + 1; j-- > 0;) {
+            out[static_cast<qsizetype>(writeOffset + j)] = QChar::fromLatin1(kBase93Alphabet[value % 93u]);
+            value /= 93u;
+        }
+    }
+    return output;
+}
+
+std::vector<std::uint8_t> anqstBase93Decode(const QString& encoded) {
+    const std::size_t inputSize = static_cast<std::size_t>(encoded.size());
+    const std::size_t fullBlocks = inputSize / 5;
+    const std::size_t remainder = inputSize - fullBlocks * 5;
+    std::vector<std::uint8_t> output(fullBlocks * 4 + (remainder ? remainder - 1 : 0));
+    const QChar* in = encoded.constData();
+    std::size_t writeOffset = 0;
+    for (std::size_t i = 0; i < fullBlocks; ++i) {
+        const std::size_t charOffset = i * 5;
+        std::uint32_t value = static_cast<std::uint32_t>(base93AlphabetIndex(in[static_cast<qsizetype>(charOffset)]));
+        value = value * 93u + static_cast<std::uint32_t>(base93AlphabetIndex(in[static_cast<qsizetype>(charOffset + 1)]));
+        value = value * 93u + static_cast<std::uint32_t>(base93AlphabetIndex(in[static_cast<qsizetype>(charOffset + 2)]));
+        value = value * 93u + static_cast<std::uint32_t>(base93AlphabetIndex(in[static_cast<qsizetype>(charOffset + 3)]));
+        value = value * 93u + static_cast<std::uint32_t>(base93AlphabetIndex(in[static_cast<qsizetype>(charOffset + 4)]));
+        output[writeOffset] = static_cast<std::uint8_t>(value >> 24);
+        output[writeOffset + 1] = static_cast<std::uint8_t>((value >> 16) & 255u);
+        output[writeOffset + 2] = static_cast<std::uint8_t>((value >> 8) & 255u);
+        output[writeOffset + 3] = static_cast<std::uint8_t>(value & 255u);
+        writeOffset += 4;
+    }
+    if (remainder != 0u) {
+        std::uint32_t value = 0;
+        for (std::size_t i = 0; i < remainder; ++i) {
+            value = value * 93u + static_cast<std::uint32_t>(
+                                      base93AlphabetIndex(in[static_cast<qsizetype>(fullBlocks * 5 + i)]));
+        }
+        for (std::size_t i = remainder - 1; i-- > 0;) {
+            output[writeOffset + i] = static_cast<std::uint8_t>(value & 255u);
+            value /= 256u;
+        }
+    }
+    return output;
+}
+
+} // namespace ANQST_WEBBASE_NAMESPACE

package/AnQstWebBase/src/AnQstBase93.h

@@ -0,0 +1,15 @@
+#pragma once
+
+#include "AnQstWebBaseAbi.h"
+
+#include <QString>
+
+#include <cstdint>
+#include <vector>
+
+namespace ANQST_WEBBASE_NAMESPACE {
+
+QString anqstBase93Encode(const std::vector<std::uint8_t>& bytes);
+std::vector<std::uint8_t> anqstBase93Decode(const QString& encoded);
+
+} // namespace ANQST_WEBBASE_NAMESPACE

package/AnQstWebBase/src/AnQstBridgeProxy.cpp

@@ -0,0 +1,30 @@
+#include "AnQstBridgeProxy.h"
+#include "AnQstHostBridgeFacade.h"
+
+namespace ANQST_WEBBASE_NAMESPACE {
+
+AnQstBridgeProxy::AnQstBridgeProxy(AnQstHostBridgeFacade* facade, QObject* parent)
+    : QObject(parent)
+    , m_facade(facade) {}
+
+void AnQstBridgeProxy::anQstBridge_registerSlot(const QString& service, const QString& member) {
+    m_facade->registerSlot(service, member);
+}
+
+QVariant AnQstBridgeProxy::anQstBridge_call(const QString& service, const QString& member, const QVariantList& args) {
+    return m_facade->call(service, member, args);
+}
+
+void AnQstBridgeProxy::anQstBridge_emit(const QString& service, const QString& member, const QVariantList& args) {
+    m_facade->emitMessage(service, member, args);
+}
+
+void AnQstBridgeProxy::anQstBridge_setInput(const QString& service, const QString& member, const QVariant& value) {
+    m_facade->setInput(service, member, value);
+}
+
+void AnQstBridgeProxy::anQstBridge_resolveSlot(const QString& requestId, bool ok, const QVariant& payload, const QString& error) {
+    m_facade->resolveSlot(requestId, ok, payload, error);
+}
+
+} // namespace ANQST_WEBBASE_NAMESPACE

package/AnQstWebBase/src/AnQstBridgeProxy.h

@@ -0,0 +1,41 @@
+#pragma once
+
+#include "AnQstWebBaseAbi.h"
+
+#include <QObject>
+#include <QString>
+#include <QVariant>
+#include <QVariantList>
+
+namespace ANQST_WEBBASE_NAMESPACE {
+
+class AnQstHostBridgeFacade;
+
+// Thin QObject registered with QWebChannel as the sole bridge endpoint.
+// Inherits only QObject so QWebChannel sees no QWidget/QObject properties
+// lacking NOTIFY signals, producing zero "no notify signal" warnings.
+class AnQstBridgeProxy : public QObject {
+    Q_OBJECT
+
+public:
+    explicit AnQstBridgeProxy(AnQstHostBridgeFacade* facade, QObject* parent = nullptr);
+
+    Q_INVOKABLE void anQstBridge_registerSlot(const QString& service, const QString& member);
+    Q_INVOKABLE QVariant anQstBridge_call(const QString& service, const QString& member, const QVariantList& args);
+    Q_INVOKABLE void anQstBridge_emit(const QString& service, const QString& member, const QVariantList& args);
+    Q_INVOKABLE void anQstBridge_setInput(const QString& service, const QString& member, const QVariant& value);
+    Q_INVOKABLE void anQstBridge_resolveSlot(const QString& requestId, bool ok, const QVariant& payload, const QString& error);
+
+signals:
+    void anQstBridge_outputUpdated(const QString& service, const QString& member, const QVariant& value);
+    void anQstBridge_slotInvocationRequested(const QString& requestId, const QString& service, const QString& member, const QVariantList& args);
+    void anQstBridge_hostDiagnostic(const QVariantMap& payload);
+    void anQstBridge_dropReceived(const QString& service, const QString& member, const QVariant& payload, double x, double y);
+    void anQstBridge_hoverUpdated(const QString& service, const QString& member, const QVariant& payload, double x, double y);
+    void anQstBridge_hoverLeft(const QString& service, const QString& member);
+
+private:
+    AnQstHostBridgeFacade* m_facade;
+};
+
+} // namespace ANQST_WEBBASE_NAMESPACE