nodehammer 0.2.0rc1__tar.gz → 0.2.0rc3__tar.gz

{nodehammer-0.2.0rc1 → nodehammer-0.2.0rc3}/.gitignore

@@ -21,6 +21,7 @@ CMakeUserPresets.json
 # Python: the venv the wheel workflow builds against, and wheel output.
 /.venv/
 /dist/
+/dist-web/
 *.egg-info/
 .idea
 

{nodehammer-0.2.0rc1 → nodehammer-0.2.0rc3}/CMakeLists.txt

@@ -134,6 +134,32 @@ include(cmake/CompilerOptions.cmake)
 # into the shared target's INSTALL_INTERFACE include path.
 include(GNUInstallDirs)
 
+# ── The web runtime's contract ───────────────────────────────────────────────
+# The wasm viewer is delivered as a directory, not a program: a shell, a worker
+# script, three bundles and the stamp below. `nodehammer viewer --web` locates
+# one through a ladder of candidate directories (a flag, an environment
+# variable, this install path, later a download cache), which means it can be
+# handed a directory that nobody validated — an old checkout's build tree is
+# exactly the mistake a person makes while debugging, and no wheel metadata or
+# version pin can see it. So the runtime says what it is and the library checks
+# before it serves anything.
+#
+# What is compared is the schema id, not the version. What actually has to
+# agree between the two halves is the .nhproj + nh_manifest.json shape and the
+# compute worker's postMessage protocol — the last of which has already broken
+# once, silently, under Closure (dcc4a06, and scripts/check_wasm_module_
+# linkage.py exists because of it). An integer is at once stricter than a
+# version, because it catches same-version skew from a hand-pointed directory,
+# and looser, because it does not cry wolf on a patch release where nothing
+# about the contract moved. The version rides along in the stamp only so the
+# refusal can name it.
+#
+# BUMP THIS when the manifest/archive shape or the worker protocol changes.
+# Monotonic; never reused.
+set(NH_WEB_RUNTIME_SCHEMA 1)
+set(NH_WEB_RUNTIME_STAMP "nh_runtime.json")
+set(NH_WEB_RUNTIME_DIR "${CMAKE_INSTALL_DATADIR}/${PROJECT_NAME}/web")
+
 # ── FlatBuffers code generation ──────────────────────────────────────────────
 set(NH_FBS_SCHEMAS
     ${CMAKE_CURRENT_SOURCE_DIR}/schemas/semantic.fbs
@@ -231,6 +257,11 @@ set(NH_CORE_SOURCES
     src/ir/fb/semantic/exporter.cpp
     src/ir/semantic/exporter_registry.cpp
     src/detail/markup.cpp
+    # Host-side, despite the directory: locating and vetting the wasm runtime is
+    # something the *serving* process does. src/web/'s other two TUs are the
+    # Emscripten entry points and are not core.
+    src/web/runtime_locator.cpp
+    src/web/executable_path.cpp
     src/scene_build.cpp
     src/export_resolve.cpp
     src/version.cpp
@@ -348,6 +379,11 @@ set(NH_CORE_PRIVATE_DEPS
 
 set(NH_CORE_DEFINES "")
 
+# The web runtime's schema id, compiled in so `web::compiledSchema()` and the
+# `nh_runtime.json` the install rules stamp come from one `set()` and cannot
+# drift. See the contract block above GNUInstallDirs.
+list(APPEND NH_CORE_DEFINES NH_WEB_RUNTIME_SCHEMA=${NH_WEB_RUNTIME_SCHEMA})
+
 # Extra include directories for dependencies that ship variables instead of
 # imported targets — Geant4 is the only one today. Everything else propagates
 # its includes through the link.
@@ -429,11 +465,30 @@ list(APPEND NH_CORE_DEPS manifold::manifold)
 # the web *runtime* no longer references BagProjectFs (static-lib dead-strip
 # keeps it out of the wasm viewer), but the native CLI (cmd_viewer) and the
 # unit tests on both platforms still use it.
+#
+# The web viewer's server and staging are native-only for a plainer reason:
+# they exist to *serve* the wasm runtime to a browser, and a wasm module is the
+# thing being served. Sockets are the giveaway -- there are none in the sandbox.
+# The locator above is not gated, because "where would the runtime be" is a
+# question the wasm build can be asked and answer "nowhere" to.
 if(NOT EMSCRIPTEN)
     list(APPEND NH_CORE_SOURCES
         src/viewer/filesystem_project_fs.cpp
         src/viewer/native_bag_project_fs.cpp
+        src/web/static_server.cpp
+        src/web/stage.cpp
+        src/web/open_browser.cpp
+        # `viewer --web` itself. Excluded here rather than #ifdef'd inside:
+        # every line of it calls something in the three files above, so a wasm
+        # build of this TU would be a shell around a refusal. `run.cpp` skips
+        # the registration to match, and a wasm module simply has no `viewer`
+        # subcommand — which is right, since it *is* the viewer.
+        src/cli/cmd_viewer_web.cpp
     )
+    # Private: httplib.h is included by static_server.cpp and by nothing else,
+    # least of all a header. Header-only, so the shared library gains no link
+    # dependency and its package config gains no requirement.
+    list(APPEND NH_CORE_PRIVATE_DEPS httplib::httplib)
 endif()
 
 # WatchedFilesystemProjectFs (strategy doc step 4) decorates FilesystemProjectFs
@@ -712,7 +767,7 @@ endif()
 # executable per backend. Native picks the right backend for the host
 # (Metal on Apple, GLCORE on Linux/Windows). Emscripten builds BOTH GLES3
 # and WGPU executables from a single configure so the wasm shell can pick
-# at runtime via navigator.gpu — see web/viewer.html.
+# at runtime via navigator.gpu — see web/index.html.
 if(NODEHAMMER_WITH_VIEWER)
     # Defines nodehammer_shaders custom target + NH_SHADER_INCLUDE_DIR.
     add_subdirectory(shaders)
@@ -723,7 +778,7 @@ if(NODEHAMMER_WITH_VIEWER)
     # dispatcher (`nodehammer viewer …` alongside the other subcommands);
     # the wasm build skips CLI11 entirely and uses src/web/viewer_main.cpp,
     # which exposes a single `nh_viewer_start(opts_json)` C export driven
-    # by web/viewer.html.
+    # by web/index.html.
     function(nh_add_viewer_exe name viewer_lib)
         if(EMSCRIPTEN)
             add_executable(${name} src/web/viewer_main.cpp)
@@ -837,37 +892,100 @@ include(cmake/PicProbe.cmake)
 # (GNUInstallDirs is included near the top — the core-library helper needs
 # CMAKE_INSTALL_INCLUDEDIR for the shared target's INSTALL_INTERFACE.)
 
-# Native: single nodehammer executable. Emscripten + viewer: per-backend
-# wasm bundles named nodehammer-{gles3,wgpu}.{js,wasm}. Emscripten + no
-# viewer: headless nodehammer (just the .js + .wasm).
-if(EMSCRIPTEN AND NODEHAMMER_WITH_VIEWER)
-    set(NH_INSTALL_TARGETS nodehammer-gles3 nodehammer-wgpu nodehammer-compute)
-else()
-    set(NH_INSTALL_TARGETS nodehammer)
-endif()
-
 # Every install rule names a COMPONENT: Runtime to run nodehammer, Development
-# to build against it. A plain `cmake --install` still installs everything, so
-# existing callers are unaffected; what this adds is `--component Runtime` for a
-# release artifact that wants the CLI and its licences but not the headers.
+# to build against it, WebRuntime for the servable wasm payload. A plain
+# `cmake --install` still installs everything, so existing callers are
+# unaffected; what this adds is `--component Runtime` for a release artifact
+# that wants the CLI and its licences but not the headers.
 #
 # Tag every rule, not just the new ones — an untagged rule lands in a default
 # component named Unspecified and would be silently missing from *both* halves.
-install(TARGETS ${NH_INSTALL_TARGETS}
-    RUNTIME DESTINATION ${CMAKE_INSTALL_BINDIR}
-            COMPONENT Runtime
-)
+if(EMSCRIPTEN AND NODEHAMMER_WITH_VIEWER)
+    # This configuration does not install a *program*. What it installs is a
+    # directory a web server can point at: the shell, the worker script, the
+    # per-backend bundles and a stamp saying what they are. Six blobs under
+    # bin/ were never that — `scripts/build_pages_site.sh` only worked because
+    # it read the shell out of the source tree it happened to be running in, so
+    # the artifact alone could not be served by anything that did not also have
+    # a checkout.
+    #
+    # share/nodehammer/web is also the rung the asset ladder looks for relative
+    # to the executable (docs/cli-and-web-viewer-plan.md Part 1), which is why
+    # it is a datadir path and not an opaque one: a native install tree and a
+    # wasm install tree merge into one directory that `nodehammer viewer --web`
+    # can resolve without being told where anything is.
+    install(TARGETS nodehammer-gles3 nodehammer-wgpu nodehammer-compute
+        RUNTIME DESTINATION "${NH_WEB_RUNTIME_DIR}"
+                COMPONENT WebRuntime
+    )
 
-# Emscripten produces a sidecar .wasm next to each .js loader; CMake's
-# install(TARGETS RUNTIME) only picks up the primary output, so install
-# the blobs explicitly.
-if(EMSCRIPTEN)
-    foreach(_t ${NH_INSTALL_TARGETS})
+    # Emscripten produces a sidecar .wasm next to each .js loader; CMake's
+    # install(TARGETS RUNTIME) only picks up the primary output, so install
+    # the blobs explicitly.
+    foreach(_t nodehammer-gles3 nodehammer-wgpu nodehammer-compute)
         install(FILES "$<TARGET_FILE_DIR:${_t}>/${_t}.wasm"
+            DESTINATION "${NH_WEB_RUNTIME_DIR}"
+            COMPONENT WebRuntime
+        )
+    endforeach()
+
+    # The two files the browser loads that no compiler produced. They are as
+    # much a part of the runtime as the bundles — index.html is what picks a
+    # backend at all, and a bundle without its worker script tessellates on the
+    # main thread or not at all.
+    install(FILES
+            "${CMAKE_CURRENT_SOURCE_DIR}/web/index.html"
+            "${CMAKE_CURRENT_SOURCE_DIR}/src/web/compute_worker.js"
+        DESTINATION "${NH_WEB_RUNTIME_DIR}"
+        COMPONENT WebRuntime
+    )
+
+    # The stamp, written beside the bundles in the build tree so that a build
+    # directory and an install tree are the same shape — `just wasm-serve` and
+    # `just pages-site` stage straight out of the former, and `viewer --web
+    # --web-assets build/emscripten/Release` is the first thing any developer
+    # reaches for.
+    file(GENERATE
+        OUTPUT "$<TARGET_FILE_DIR:nodehammer-gles3>/${NH_WEB_RUNTIME_STAMP}"
+        CONTENT "{\n  \"schema\": ${NH_WEB_RUNTIME_SCHEMA},\n  \"version\": \"${NODEHAMMER_VERSION}\"\n}\n"
+    )
+    install(FILES "$<TARGET_FILE_DIR:nodehammer-gles3>/${NH_WEB_RUNTIME_STAMP}"
+        DESTINATION "${NH_WEB_RUNTIME_DIR}"
+        COMPONENT WebRuntime
+    )
+
+    # "The same shape" has to include the two files no compiler produces, or the
+    # claim above is false in exactly the way that bites: a build tree carrying a
+    # stamp and bundles but no shell passes every check a stamp can make and then
+    # serves 404 on `/`.
+    #
+    # Symlinks, not copies, and that is the whole point: an edit to web/index.html
+    # is live in a served build tree with no rebuild, which is what `just
+    # wasm-serve`'s link mode has always given. COPY_ON_ERROR covers Windows,
+    # where an unprivileged symlink fails and a stale copy is better than an
+    # incomplete directory.
+    foreach(_nh_shell_file
+            "${CMAKE_CURRENT_SOURCE_DIR}/web/index.html"
+            "${CMAKE_CURRENT_SOURCE_DIR}/src/web/compute_worker.js")
+        get_filename_component(_nh_shell_name "${_nh_shell_file}" NAME)
+        file(CREATE_LINK "${_nh_shell_file}"
+             "${CMAKE_CURRENT_BINARY_DIR}/${_nh_shell_name}"
+             COPY_ON_ERROR SYMBOLIC)
+    endforeach()
+else()
+    # Native: the single nodehammer executable. Emscripten with no viewer: the
+    # headless nodehammer bundle (just the .js + .wasm).
+    install(TARGETS nodehammer
+        RUNTIME DESTINATION ${CMAKE_INSTALL_BINDIR}
+                COMPONENT Runtime
+    )
+
+    if(EMSCRIPTEN)
+        install(FILES "$<TARGET_FILE_DIR:nodehammer>/nodehammer.wasm"
             DESTINATION ${CMAKE_INSTALL_BINDIR}
             COMPONENT Runtime
         )
-    endforeach()
+    endif()
 endif()
 
 install(FILES "${CMAKE_SOURCE_DIR}/LICENSE"

{nodehammer-0.2.0rc1 → nodehammer-0.2.0rc3}/Justfile

@@ -12,6 +12,7 @@ build_nodehammer_cmd := if os_family() == "windows" { "powershell -NoProfile -Ex
 
 # Cheap to re-export every time; conan dedupes by recipe revision.
 recipes:
+    conan export recipes/cli11 --version=2.7.2
     conan export recipes/sokol --version=2026.07.02
     conan export recipes/imgui --version=1.92.8
     conan export recipes/implot --version=1.0.0
@@ -328,7 +329,9 @@ wheel *args:
     # the only visible difference is the filename. Catch that here rather than
     # discovering it as a CI matrix that grew from one wheel per platform to one
     # per interpreter.
-    for whl in "$root"/dist/*.whl; do
+    # dist/ also holds nodehammer_web-*.whl, which is py3-none-any by design, so
+    # the glob names this distribution rather than every wheel in the directory.
+    for whl in "$root"/dist/nodehammer-*.whl; do
         case "$whl" in
             *-abi3-*) ;;
             *) echo "not an abi3 wheel: $(basename "$whl") -- STABLE_ABI did not engage" >&2
@@ -336,6 +339,65 @@ wheel *args:
         esac
     done
 
+# ── the web runtime wheel ─────────────────────────────────────────────────────
+# `nodehammer-web` is the other half of the Python story: a py3-none-any wheel
+# holding the Emscripten build, because no native toolchain can produce one and
+# a headless install has no use for 7 MB of it. See packaging/web/pyproject.toml.
+#
+# `src` is anything the runtime locator would accept -- a wasm build directory or
+# an install tree's share/nodehammer/web -- and it is staged by the same script
+# the Pages site uses, in application mode, so the payload is the one CI deploys.
+
+# Build the nodehammer-web wheel from a wasm build (run `just wasm-release` first)
+wheel-web src="build/emscripten/Release":
+    #!/usr/bin/env bash
+    set -euo pipefail
+    root="{{justfile_directory()}}"
+    src="{{src}}"
+    case "$src" in /*) ;; *) src="$root/$src" ;; esac
+    runtime="$root/packaging/web/src/nodehammer_web/runtime"
+    # Both sides emptied rather than overlaid. The staging directory is the
+    # obvious one; setuptools' build/lib is the one that bites, because
+    # `build_py` copies into it and never prunes -- a file dropped from the
+    # payload survives there and is added to the wheel from a previous run.
+    # Caught doing exactly that with a stale nodehammer-wgpu.wasm.zst.
+    rm -rf "$runtime" "$root/packaging/web/build"
+    "$root/scripts/stage_wasm_viewer.sh" copy none "$runtime" "$src"
+    uv build --wheel --out-dir "$root/dist" "$root/packaging/web"
+    # The mirror of the abi3 check above, and the same kind of silent failure:
+    # a wheel that picked up a platform tag would install nowhere it is needed.
+    for whl in "$root"/dist/nodehammer_web-*.whl; do
+        case "$whl" in
+            *-py3-none-any.whl) ;;
+            *) echo "not a pure wheel: $(basename "$whl")" >&2
+               exit 1 ;;
+        esac
+    done
+
+# The only check that reaches the rung a wheel fills. `--web-assets` and
+# NODEHAMMER_WEB_ASSETS are cleared out of the way on purpose: both outrank the
+# package, so leaving either set would test the wrong rung and pass anyway.
+#
+# The pair check reads dist/, so it fails on a directory holding two versions of
+# either distribution -- which is the stale-artifact case it exists to catch, and
+# locally usually just means `rm -rf dist` first.
+
+# Install both wheels from local files and serve the viewer out of them
+wheel-web-test: wheel wheel-web
+    #!/usr/bin/env bash
+    set -euo pipefail
+    root="{{justfile_directory()}}"
+    uv run --no-project --with packaging "$root/scripts/check_wheel_pair.py" "$root/dist"
+    venv=$(mktemp -d)/venv
+    uv venv --python 3.12 "$venv"
+    # --no-index: the pair under test is the one just built, never whatever an
+    # index happens to resolve. Only `nodehammer` is named -- pulling the runtime
+    # in is the dependency's job, and naming it here would pass even if the
+    # generated pin had gone missing.
+    VIRTUAL_ENV="$venv" uv pip install --quiet --no-index \
+        --find-links "$root/dist" nodehammer
+    env -u NODEHAMMER_WEB_ASSETS "$root/scripts/check_web_serve.py" "$venv/bin/nodehammer"
+
 # The Python counterpart of ci/shared_consumer: the build tree resolves
 # libnodehammer through CMake's own rpath, so only an installed wheel proves the
 # relative rpath and the bundled library are right.
@@ -347,7 +409,14 @@ wheel-test: wheel
     root="{{justfile_directory()}}"
     venv=$(mktemp -d)/venv
     uv venv --python 3.12 "$venv"
-    VIRTUAL_ENV="$venv" uv pip install --quiet pytest tomli-w "$root"/dist/nodehammer-*.whl
+    VIRTUAL_ENV="$venv" uv pip install --quiet pytest tomli-w
+    # --no-deps, in its own command so the test tools above still resolve.
+    # `nodehammer` requires `nodehammer-web`, which is built by a separate
+    # Emscripten toolchain -- resolving it here would either reach an index for
+    # something this recipe is not testing, or fail on a machine with no emsdk.
+    # What this recipe is for is the platform wheel's own payload and its
+    # relative rpath; `just wheel-web-test` is the one that exercises the pair.
+    VIRTUAL_ENV="$venv" uv pip install --quiet --no-deps "$root"/dist/nodehammer-*.whl
     cd "$root" && "$venv/bin/python" -m pytest tests/python -q
 
 # Build the Linux wheels the way CI does, in a manylinux container. Needs Docker.

{nodehammer-0.2.0rc1 → nodehammer-0.2.0rc3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: nodehammer
-Version: 0.2.0rc1
+Version: 0.2.0rc3
 Summary: Detector geometry tessellation and export
 Author: Paul Gessinger
 License-Expression: MIT
@@ -11,8 +11,10 @@ Classifier: Programming Language :: Python :: Implementation :: CPython
 Classifier: Topic :: Scientific/Engineering :: Physics
 Project-URL: Homepage, https://github.com/paulgessinger/nodehammer
 Requires-Python: >=3.12
+Requires-Dist: nodehammer-web==0.2.*
 Provides-Extra: dict
 Requires-Dist: tomli-w>=1.0; extra == "dict"
+Provides-Extra: web
 Description-Content-Type: text/markdown
 
 <p align="center">
@@ -137,7 +139,7 @@ natively, in the browser, and behind a published link.
 | **Working set** | the live, editable in-memory project (`ZipWorkingSet`) — what the viewer edits |
 | **Archive** | a serialized `.nhproj` of a working set — the portable, publishable unit |
 | **Project manifest** | root `nodehammer.toml` *inside* the archive: `[project]` entry keys + `[view]` initial steer |
-| **Sidecar** | `nh_manifest.json` next to `viewer.html` — points at archive(s), carries deployment presentation (lock, steer overrides) |
+| **Sidecar** | `nh_manifest.json` next to `index.html` — points at archive(s), carries deployment presentation (lock, steer overrides) |
 | **Steer** | view-state (camera, angle cut, rotation, toggles) — the ephemeral per-link layer, committed to the URL query |
 | **Provenance** | `Empty \| Local(name) \| Remote(url)` — where the working set came from; drives persistence and posture |
 | **Package** | the self-contained static folder emitted by **Publish** — drop it on any static host, zero server code |
@@ -244,9 +246,9 @@ web build supports:
 
 | | |
 |---|---|
-| [`/app/`](https://paulgessinger.github.io/nodehammer/app/viewer.html) | the open application — empty start; drop a `.nhproj` or loose config/geometry files onto it |
-| [`/odd/`](https://paulgessinger.github.io/nodehammer/odd/viewer.html) | the full Open Data Detector, preconfigured and content-locked |
-| [`/odd-simple/`](https://paulgessinger.github.io/nodehammer/odd-simple/viewer.html) | the simplified ODD — same, lighter to build |
+| [`/app/`](https://paulgessinger.github.io/nodehammer/app/) | the open application — empty start; drop a `.nhproj` or loose config/geometry files onto it |
+| [`/odd/`](https://paulgessinger.github.io/nodehammer/odd/) | the full Open Data Detector, preconfigured and content-locked |
+| [`/odd-simple/`](https://paulgessinger.github.io/nodehammer/odd-simple/) | the simplified ODD — same, lighter to build |
 
 Each directory is a self-contained static package of the kind the viewer's
 **Publish** command emits. Reproduce the whole site locally with

{nodehammer-0.2.0rc1 → nodehammer-0.2.0rc3}/README.md

@@ -120,7 +120,7 @@ natively, in the browser, and behind a published link.
 | **Working set** | the live, editable in-memory project (`ZipWorkingSet`) — what the viewer edits |
 | **Archive** | a serialized `.nhproj` of a working set — the portable, publishable unit |
 | **Project manifest** | root `nodehammer.toml` *inside* the archive: `[project]` entry keys + `[view]` initial steer |
-| **Sidecar** | `nh_manifest.json` next to `viewer.html` — points at archive(s), carries deployment presentation (lock, steer overrides) |
+| **Sidecar** | `nh_manifest.json` next to `index.html` — points at archive(s), carries deployment presentation (lock, steer overrides) |
 | **Steer** | view-state (camera, angle cut, rotation, toggles) — the ephemeral per-link layer, committed to the URL query |
 | **Provenance** | `Empty \| Local(name) \| Remote(url)` — where the working set came from; drives persistence and posture |
 | **Package** | the self-contained static folder emitted by **Publish** — drop it on any static host, zero server code |
@@ -227,9 +227,9 @@ web build supports:
 
 | | |
 |---|---|
-| [`/app/`](https://paulgessinger.github.io/nodehammer/app/viewer.html) | the open application — empty start; drop a `.nhproj` or loose config/geometry files onto it |
-| [`/odd/`](https://paulgessinger.github.io/nodehammer/odd/viewer.html) | the full Open Data Detector, preconfigured and content-locked |
-| [`/odd-simple/`](https://paulgessinger.github.io/nodehammer/odd-simple/viewer.html) | the simplified ODD — same, lighter to build |
+| [`/app/`](https://paulgessinger.github.io/nodehammer/app/) | the open application — empty start; drop a `.nhproj` or loose config/geometry files onto it |
+| [`/odd/`](https://paulgessinger.github.io/nodehammer/odd/) | the full Open Data Detector, preconfigured and content-locked |
+| [`/odd-simple/`](https://paulgessinger.github.io/nodehammer/odd-simple/) | the simplified ODD — same, lighter to build |
 
 Each directory is a self-contained static package of the kind the viewer's
 **Publish** command emits. Reproduce the whole site locally with

{nodehammer-0.2.0rc1 → nodehammer-0.2.0rc3}/ci/build.sh

@@ -50,6 +50,7 @@ esac
 
 case "$cmd" in
   conan-install)
+    conan export recipes/cli11 --version=2.7.2
     conan export recipes/sokol --version=2026.07.02
     conan export recipes/imgui --version=1.92.8
     conan export recipes/implot --version=1.0.0

{nodehammer-0.2.0rc1 → nodehammer-0.2.0rc3}/cmake/Dependencies.cmake

@@ -39,11 +39,14 @@ FetchContent_Declare(Catch2
 FetchContent_MakeAvailable(Catch2)
 
 # ── CLI11 ─────────────────────────────────────────────────────────────────────
+# 2.7.2 is a floor, not a preference. Up to and including 2.6.2 CLI11's character
+# tables were namespace-scope references bound to temporaries, which Emscripten
+# cannot run an atexit chain over -- see recipes/cli11/conanfile.py and issue #76.
 FetchContent_Declare(CLI11
     SYSTEM
     GIT_REPOSITORY https://github.com/CLIUtils/CLI11.git
-    GIT_TAG        v2.6.2
-    FIND_PACKAGE_ARGS 2.6.2
+    GIT_TAG        v2.7.2
+    FIND_PACKAGE_ARGS 2.7.2
 )
 FetchContent_MakeAvailable(CLI11)
 
@@ -56,6 +59,27 @@ FetchContent_Declare(nlohmann_json
 )
 FetchContent_MakeAvailable(nlohmann_json)
 
+# ── cpp-httplib ───────────────────────────────────────────────────────────────
+# The static server behind `viewer --web`. Native only: the wasm build has no
+# sockets, and the module it would serve is the thing being served.
+#
+# Chosen over the ~370 hand-rolled lines it replaces because it is *less* code
+# for today's behaviour, not only because of what comes next. What comes next
+# does matter though: `HttpProjectFs` needs request bodies and routing, and an
+# experiment framework pushing events needs a parser that has been attacked. The
+# `set_mount_point` + `set_default_headers` + `bind_to_any_port` trio covers the
+# static case in a few lines, and WebSocket (since 0.33.0) plus chunked content
+# providers cover the rest without a second dependency.
+if(NOT EMSCRIPTEN)
+    FetchContent_Declare(httplib
+        SYSTEM
+        GIT_REPOSITORY https://github.com/yhirose/cpp-httplib.git
+        GIT_TAG        v0.47.0
+        FIND_PACKAGE_ARGS 0.47.0
+    )
+    FetchContent_MakeAvailable(httplib)
+endif()
+
 # ── GLM ───────────────────────────────────────────────────────────────────────
 FetchContent_Declare(glm
     SYSTEM

nodehammer-0.2.0rc3/cmake/Version.cmake

@@ -0,0 +1,88 @@
+# The version of record is a git tag, read here with `git describe`. There is one
+# exception, and it comes first.
+#
+# Under scikit-build-core the version is decided on the Python side — setuptools_scm,
+# which speaks PEP 440 — and handed down as SKBUILD_PROJECT_VERSION. Prefer it
+# there, for two reasons. `git describe`'s spelling is not PEP 440, so the two
+# would disagree by construction; and a wheel built from an sdist has no .git to
+# describe at all, which would fall through to the branch below and ship a
+# libnodehammer whose nodehammer::version() reports 0.0.0 from inside a wheel
+# whose metadata says otherwise.
+#
+# The numeric prefix is what project(VERSION) and SOVERSION need; the full string
+# is what version.hpp reports, so a development wheel says
+# "0.1.3.post1.dev398+g920e6c5" — the same string pip shows, and strictly more
+# information than the "0.1.3-398-g920e6c5" it replaces. The prefix match has no
+# anchor at its end on purpose: a pre-release version keeps its numeric prefix
+# and everything after it rides in the full string.
+if(DEFINED SKBUILD_PROJECT_VERSION
+        AND SKBUILD_PROJECT_VERSION MATCHES "^([0-9]+)\\.([0-9]+)\\.([0-9]+)")
+    set(NODEHAMMER_VERSION_MAJOR "${CMAKE_MATCH_1}")
+    set(NODEHAMMER_VERSION_MINOR "${CMAKE_MATCH_2}")
+    set(NODEHAMMER_VERSION_PATCH "${CMAKE_MATCH_3}")
+    set(NODEHAMMER_VERSION "${SKBUILD_PROJECT_VERSION}")
+    return()
+endif()
+
+execute_process(
+    COMMAND git describe --tags --long --always
+    WORKING_DIRECTORY ${CMAKE_CURRENT_SOURCE_DIR}
+    OUTPUT_VARIABLE _git_describe
+    OUTPUT_STRIP_TRAILING_WHITESPACE
+    ERROR_QUIET
+    RESULT_VARIABLE _git_result
+)
+
+# The `(.*)` between the patch number and the commit distance is what makes a
+# pre-release tag a version rather than a fallthrough. `v0.2.0rc1` is spelled the
+# way setuptools_scm and PEP 440 want it, so the two halves of one release agree,
+# and it does not match a triple-only pattern — which is how tagging v0.2.0rc1
+# silently rewrote nodehammer::version(), the SOVERSION and the package config
+# version to 0.0.0 for every native and wasm build off that tag, while wheels
+# went on being right because they take the branch above.
+#
+# Greedy, and it backtracks to the last `-<digits>-g<hash>`, so both spellings
+# work: "v0.2.0rc1-3-gabc1234" and "v0.2.0-rc1-3-gabc1234" both yield the triple
+# 0.2.0 with the pre-release riding in the full string. The suffix is passed
+# through, not validated — this file's job is to report the tag that exists, not
+# to have an opinion about how it is spelled.
+if(_git_result EQUAL 0 AND _git_describe MATCHES
+        "^v([0-9]+)\\.([0-9]+)\\.([0-9]+)(.*)-([0-9]+)-g([0-9a-f]+)$")
+    # Named up front: six groups read as six groups, and CMAKE_MATCH_* is global
+    # state that the next `if(... MATCHES ...)` anywhere would overwrite.
+    set(NODEHAMMER_VERSION_MAJOR "${CMAKE_MATCH_1}")
+    set(NODEHAMMER_VERSION_MINOR "${CMAKE_MATCH_2}")
+    set(NODEHAMMER_VERSION_PATCH "${CMAKE_MATCH_3}")
+    set(_nh_pre "${CMAKE_MATCH_4}")
+    set(_nh_distance "${CMAKE_MATCH_5}")
+    set(_nh_hash "${CMAKE_MATCH_6}")
+
+    set(_nh_base
+        "${NODEHAMMER_VERSION_MAJOR}.${NODEHAMMER_VERSION_MINOR}.${NODEHAMMER_VERSION_PATCH}${_nh_pre}")
+    if(_nh_distance EQUAL 0)
+        set(NODEHAMMER_VERSION "${_nh_base}")
+    else()
+        set(NODEHAMMER_VERSION "${_nh_base}-${_nh_distance}-g${_nh_hash}")
+    endif()
+else()
+    # Loud, because it is silent failure that made this branch worth fixing: the
+    # build carries on and every version it reports is a lie, in four places at
+    # once, and nothing says so until someone reads one of them.
+    if(NOT _git_result EQUAL 0)
+        set(_nh_why "`git describe` failed — not a git checkout, or git is not installed")
+    else()
+        set(_nh_why "`git describe` returned \"${_git_describe}\", which names no vMAJOR.MINOR.PATCH tag")
+    endif()
+    message(WARNING
+        "nodehammer: could not derive a version — ${_nh_why}.\n"
+        "Falling back to 0.0.0, which is what nodehammer --version, "
+        "nodehammer::version(), the shared library SOVERSION and "
+        "nodehammer-config-version.cmake will all report — so "
+        "find_package(nodehammer <any version>) against this build will fail.\n"
+        "A tagless or shallow clone is the usual cause; `git fetch --tags` fixes it.")
+
+    set(NODEHAMMER_VERSION_MAJOR 0)
+    set(NODEHAMMER_VERSION_MINOR 0)
+    set(NODEHAMMER_VERSION_PATCH 0)
+    set(NODEHAMMER_VERSION "0.0.0")
+endif()

{nodehammer-0.2.0rc1 → nodehammer-0.2.0rc3}/conanfile.py

@@ -30,7 +30,7 @@ class Nodehammer(ConanFile):
     def requirements(self):
         self.requires("zstd/1.5.7")
         self.requires("catch2/3.15.1")
-        self.requires("cli11/2.6.2")
+        self.requires("cli11/2.7.2")
         self.requires("nlohmann_json/3.12.0")
         self.requires("glm/1.0.3")
         self.requires("tomlplusplus/3.4.0")
@@ -71,6 +71,18 @@ class Nodehammer(ConanFile):
         # never calls the `.lua` path, which today is both wasm bundles.
         self.requires("lua/5.4.6")
         self.requires("sol2/3.5.0")
+        # The static server behind `viewer --web`. Gated on the platform rather
+        # than unconditional, unlike miniz and lua above, because this one is not
+        # a capability of the library: it exists to *serve* the wasm runtime to a
+        # browser, and under Emscripten the wasm module is the thing being
+        # served. There are no sockets in the sandbox, and src/web/static_server.cpp
+        # is excluded from NH_CORE_SOURCES there for the same reason.
+        #
+        # Header-only, so it adds no link dependency beyond the platform's own
+        # sockets, and no OpenSSL unless CPPHTTPLIB_OPENSSL_SUPPORT is defined,
+        # which nothing here defines.
+        if self.settings.os != "Emscripten":
+            self.requires("cpp-httplib/0.47.0")
         # Viewer-only runtime dep. PlatformFolders resolves the OS-appropriate
         # cache / config directory on native; not needed on web. Skip under
         # Emscripten — the wasm viewer never links it and the package fails to

{nodehammer-0.2.0rc1 → nodehammer-0.2.0rc3}/include/nodehammer/cli.hpp

@@ -20,6 +20,7 @@
 
 #include <nodehammer/visibility.hpp>
 
+#include <filesystem>
 #include <span>
 #include <string_view>
 
@@ -39,6 +40,27 @@ struct RunOptions {
     /// typed the command, wrong when a program called a function. A TTY alone
     /// cannot tell those apart: an interactive interpreter has one.
     bool pager = false;
+
+    /// Where the wasm viewer runtime is, for callers that know.
+    ///
+    /// `viewer --web` needs a directory of Emscripten output that this library
+    /// cannot build and, in an embedded process, cannot find: under the Python
+    /// wheel the running executable is the interpreter, so the install-tree
+    /// guess resolves to the wrong prefix entirely. The `nodehammer-web` package
+    /// knows exactly where its own payload is, so it says.
+    ///
+    /// Empty means "I do not know of one", which is not an error — it costs one
+    /// rung of the search. It is a *default*, not an override: `--web-assets`
+    /// and `NODEHAMMER_WEB_ASSETS` both outrank it, so a person can point at a
+    /// locally built runtime without uninstalling anything.
+    ///
+    /// A `path` rather than a `string`, like every other file-taking member of
+    /// this API — and here it is not only consistency. On Windows a `path` holds
+    /// `wchar_t`, and building one from a narrow string decodes it in the active
+    /// code page, so a runtime under a directory with a non-ASCII name would
+    /// arrive mangled. Callers that have the real encoding — nanobind's
+    /// `stl/filesystem.h` caster above all — can hand it over intact.
+    std::filesystem::path webAssets;
 };
 
 /// Run one command line. Returns the exit code the executable would have.