nodehammer 0.2.0rc1__tar.gz → 0.2.0rc5__tar.gz

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

@@ -14,13 +14,14 @@
 # Project archives packed by the viewer / make_nhproj.py — always generated.
 *.nhproj
 
-# config-flatten output written to the repo root (generated from fixtures/).
+# `config flatten` output written to the repo root (generated from fixtures/).
 /*_flat.toml
 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.0rc5}/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 serve` 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
@@ -227,10 +253,17 @@ set(NH_CORE_SOURCES
     src/ir/gltf/render/exporter.cpp
     src/ir/obj/render/exporter.cpp
     src/ir/render/exporter_registry.cpp
+    src/ir/fb/render/exporter.cpp
+    src/ir/render/json_exporter.cpp
     src/ir/json/semantic/exporter.cpp
     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
@@ -267,11 +300,7 @@ set(NH_CORE_SOURCES
     src/cli/pager.cpp
     src/cli/cmd_convert.cpp
     src/cli/cmd_inspect.cpp
-    src/cli/cmd_validate_config.cpp
-    src/cli/cmd_config_flatten.cpp
-    src/cli/cmd_dump_semantic.cpp
-    src/cli/cmd_dump_render.cpp
-    src/cli/cmd_config_lua.cpp
+    src/cli/cmd_config.cpp
 )
 
 # ── Application sources ───────────────────────────────────────────────────────
@@ -348,6 +377,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 +463,34 @@ 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
+        # Packing mounts a FilesystemProjectFs, so it is gated here rather than
+        # beside the ZipWorkingSet it builds -- that half *is* cross-platform.
+        src/project/pack.cpp
+        src/cli/cmd_project.cpp
+        # `viewer serve` 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 +769,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 +780,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)
@@ -813,7 +870,6 @@ if(CMAKE_CXX_COMPILER_ID STREQUAL "GNU")
         src/scene_build.cpp
         src/selection/selector.cpp
         src/cli/cmd_convert.cpp
-        src/cli/cmd_dump_semantic.cpp
         PROPERTIES COMPILE_OPTIONS "-Wno-maybe-uninitialized"
     )
 endif()
@@ -837,37 +893,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 serve`
+    # 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 serve
+    # --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.0rc5}/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.0rc5}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: nodehammer
-Version: 0.2.0rc1
+Version: 0.2.0rc5
 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">
@@ -75,8 +77,7 @@ versus what's on the roadmap.
 - **Analytical geometry surgery**: semantic-level azimuthal wedge cuts and
   boolean operations via [manifold](https://github.com/elalish/manifold),
   correct on non-manifold swept primitives, cooperative with UI progress.
-- **CLI**: `convert`, `inspect`, `validate-config`, `config-flatten`,
-  `dump-semantic`, `dump-render`, `viewer`.
+- **CLI**: `convert`, `inspect`, `config`, `project`, `viewer`.
 - **Viewer rendering pipeline**, live today:
   - Full offscreen HDR pipeline with ACES / Reinhard / AgX tonemapping and
     exposure control
@@ -88,7 +89,7 @@ versus what's on the roadmap.
     profile — renders on demand and caps the idle frame rate
   - Live ImPlot performance graphs in the debug panel
   - High-resolution, supersampled PNG screenshot export
-    (`nodehammer viewer --screenshot out.png ...`) — **verified on Metal**;
+    (`nodehammer viewer shot -o out.png ...`) — **verified on Metal**;
     the WebGL2/GLES3 and WebGPU readback paths compile and link but are not
     yet verified in-browser
 - **Builds on macOS, Linux, and Windows** natively (Metal, GLCORE, and D3D11
@@ -137,7 +138,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 |
@@ -160,18 +161,27 @@ Full design of record, including backend mapping and mode transitions:
 ## CLI
 
 ```
-nodehammer convert         # geometry → glTF / OBJ / render IR
-nodehammer inspect         # explore a semantic scene
-nodehammer validate-config # lint a TOML config before running it
-nodehammer config-flatten  # resolve config includes/overrides
-nodehammer dump-semantic   # dump the semantic scene as JSON
-nodehammer dump-render     # dump the render IR as JSON
-nodehammer viewer          # launch the interactive viewer
+nodehammer convert   # geometry in, anything out — the pipeline
+nodehammer inspect   # summary | tree | tags — ask about a scene
+nodehammer config    # validate | flatten — TOML and Lua configs
+nodehammer project   # pack | publish | info — .nhproj archives
+nodehammer viewer    # open | serve | shot | bench — the app
 ```
 
-Running the executable with no arguments at all (e.g. double-clicking
-`nodehammer.exe` in a file manager) also launches the viewer, in builds with
-`NODEHAMMER_WITH_VIEWER` enabled.
+Four nouns and one verb. The design of record, including the vocabulary and why
+each old name went, is [docs/cli-design.md](docs/cli-design.md).
+
+`convert` spans the whole pipeline, and **the output format decides how far it
+runs**: `-o scene.nhb` stops at the semantic scene, `-o scene.glb` tessellates
+first, and asking for both in one command is one pass rather than two.
+Tessellation is lossy by construction — solids become triangles — so `.nhb` is
+the faithful stop and `.glb` is a one-way door.
+
+```bash
+nodehammer project pack -c scene.toml -i odd.xml -o odd.nhproj
+nodehammer viewer odd.nhproj serve          # open it in a browser
+nodehammer project publish odd.nhproj -o site/
+```
 
 ## Building
 
@@ -233,7 +243,7 @@ The repo ships a real detector fixture — the Open Data Detector — ready to c
 
 ```bash
 just odd    # full ODD → glb (see the Justfile for single-stave recipes too)
-build/RelWithDebInfo/nodehammer viewer
+build/RelWithDebInfo/nodehammer viewer open
 ```
 
 ### …in a browser
@@ -244,9 +254,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.0rc5}/README.md

@@ -58,8 +58,7 @@ versus what's on the roadmap.
 - **Analytical geometry surgery**: semantic-level azimuthal wedge cuts and
   boolean operations via [manifold](https://github.com/elalish/manifold),
   correct on non-manifold swept primitives, cooperative with UI progress.
-- **CLI**: `convert`, `inspect`, `validate-config`, `config-flatten`,
-  `dump-semantic`, `dump-render`, `viewer`.
+- **CLI**: `convert`, `inspect`, `config`, `project`, `viewer`.
 - **Viewer rendering pipeline**, live today:
   - Full offscreen HDR pipeline with ACES / Reinhard / AgX tonemapping and
     exposure control
@@ -71,7 +70,7 @@ versus what's on the roadmap.
     profile — renders on demand and caps the idle frame rate
   - Live ImPlot performance graphs in the debug panel
   - High-resolution, supersampled PNG screenshot export
-    (`nodehammer viewer --screenshot out.png ...`) — **verified on Metal**;
+    (`nodehammer viewer shot -o out.png ...`) — **verified on Metal**;
     the WebGL2/GLES3 and WebGPU readback paths compile and link but are not
     yet verified in-browser
 - **Builds on macOS, Linux, and Windows** natively (Metal, GLCORE, and D3D11
@@ -120,7 +119,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 |
@@ -143,18 +142,27 @@ Full design of record, including backend mapping and mode transitions:
 ## CLI
 
 ```
-nodehammer convert         # geometry → glTF / OBJ / render IR
-nodehammer inspect         # explore a semantic scene
-nodehammer validate-config # lint a TOML config before running it
-nodehammer config-flatten  # resolve config includes/overrides
-nodehammer dump-semantic   # dump the semantic scene as JSON
-nodehammer dump-render     # dump the render IR as JSON
-nodehammer viewer          # launch the interactive viewer
+nodehammer convert   # geometry in, anything out — the pipeline
+nodehammer inspect   # summary | tree | tags — ask about a scene
+nodehammer config    # validate | flatten — TOML and Lua configs
+nodehammer project   # pack | publish | info — .nhproj archives
+nodehammer viewer    # open | serve | shot | bench — the app
 ```
 
-Running the executable with no arguments at all (e.g. double-clicking
-`nodehammer.exe` in a file manager) also launches the viewer, in builds with
-`NODEHAMMER_WITH_VIEWER` enabled.
+Four nouns and one verb. The design of record, including the vocabulary and why
+each old name went, is [docs/cli-design.md](docs/cli-design.md).
+
+`convert` spans the whole pipeline, and **the output format decides how far it
+runs**: `-o scene.nhb` stops at the semantic scene, `-o scene.glb` tessellates
+first, and asking for both in one command is one pass rather than two.
+Tessellation is lossy by construction — solids become triangles — so `.nhb` is
+the faithful stop and `.glb` is a one-way door.
+
+```bash
+nodehammer project pack -c scene.toml -i odd.xml -o odd.nhproj
+nodehammer viewer odd.nhproj serve          # open it in a browser
+nodehammer project publish odd.nhproj -o site/
+```
 
 ## Building
 
@@ -216,7 +224,7 @@ The repo ships a real detector fixture — the Open Data Detector — ready to c
 
 ```bash
 just odd    # full ODD → glb (see the Justfile for single-stave recipes too)
-build/RelWithDebInfo/nodehammer viewer
+build/RelWithDebInfo/nodehammer viewer open
 ```
 
 ### …in a browser
@@ -227,9 +235,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.0rc5}/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.0rc5}/ci/shared_consumer/main.cpp

@@ -108,12 +108,13 @@ int main() {
     }
     std::cout << std::flush;
 
-    if (!listed(semanticFormats, "synthetic") || !listed(semanticFormats, "flatbuffer")) {
+    if (!listed(semanticFormats, "synthetic") || !listed(semanticFormats, "nhb")) {
         std::cerr << "SemanticScene::formats() is missing a built-in format\n";
         return 1;
     }
     if (!listed(nodehammer::Config::formats(), "toml") ||
-        !listed(nodehammer::RenderScene::formats(), "gltf")) {
+        !listed(nodehammer::RenderScene::formats(), "gltf") ||
+        !listed(nodehammer::RenderScene::formats(), "nhr")) {
         std::cerr << "a built-in format is missing from formats()\n";
         return 1;
     }

{nodehammer-0.2.0rc1 → nodehammer-0.2.0rc5}/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 serve`. 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
@@ -191,7 +215,7 @@ if(TARGET flatbuffers)
 endif()
 
 # ── Lua config front-end (lua + sol2) ────────────────────────────────────────
-# Powers the `config-lua` CLI command and `Config::read`'s `.lua` branch — an
+# Powers the `config flatten` CLI command and `Config::read`'s `.lua` branch — an
 # unconditional source in nodehammer_lib on every platform, Emscripten included.
 # Both come from Conan (lua has no clean upstream CMake — it ships a Makefile —
 # so, like imgui/implot below, we resolve via find_package rather than a git