nodehammer 0.2.0rc3__tar.gz → 0.2.0rc5__tar.gz

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

@@ -14,7 +14,7 @@
 # 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
 

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

@@ -136,7 +136,7 @@ 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
+# 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
@@ -253,6 +253,8 @@ 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
@@ -298,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 ───────────────────────────────────────────────────────
@@ -478,7 +476,11 @@ if(NOT EMSCRIPTEN)
         src/web/static_server.cpp
         src/web/stage.cpp
         src/web/open_browser.cpp
-        # `viewer --web` itself. Excluded here rather than #ifdef'd inside:
+        # 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`
@@ -868,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()
@@ -912,7 +913,7 @@ if(EMSCRIPTEN AND NODEHAMMER_WITH_VIEWER)
     # 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`
+    # 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}"
@@ -942,7 +943,7 @@ if(EMSCRIPTEN AND NODEHAMMER_WITH_VIEWER)
 
     # 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
+    # `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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: nodehammer
-Version: 0.2.0rc3
+Version: 0.2.0rc5
 Summary: Detector geometry tessellation and export
 Author: Paul Gessinger
 License-Expression: MIT
@@ -77,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
@@ -90,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
@@ -162,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
 
@@ -235,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

{nodehammer-0.2.0rc3 → 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
@@ -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

{nodehammer-0.2.0rc3 → 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.0rc3 → nodehammer-0.2.0rc5}/cmake/Dependencies.cmake

@@ -60,7 +60,7 @@ FetchContent_Declare(nlohmann_json
 FetchContent_MakeAvailable(nlohmann_json)
 
 # ── cpp-httplib ───────────────────────────────────────────────────────────────
-# The static server behind `viewer --web`. Native only: the wasm build has no
+# 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
@@ -215,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

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

@@ -57,7 +57,7 @@ class Nodehammer(ConanFile):
         # — and static-lib dead-strip keeps it out of any binary that does not
         # reference it.
         self.requires("miniz/3.0.2")
-        # Lua scripting config front-end: the `config-lua` CLI command and
+        # Lua scripting config front-end: the `config flatten` CLI command and
         # `Config::read`'s `.lua` branch. Lua is a small C interpreter; sol2 is
         # its header-only C++ binding (and pulls lua transitively, but we pin lua
         # explicitly for parity with the CMake find_package).
@@ -71,7 +71,7 @@ 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
+        # The static server behind `viewer serve`. 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

{nodehammer-0.2.0rc3 → nodehammer-0.2.0rc5}/fixtures/configs/lua/kitchen_sink.lua

@@ -1,7 +1,7 @@
 -- Kitchen-sink scripted config. Demonstrates the whole surface: top-level
 -- flags, per-format export overrides, include() of side-effect fragments (which
 -- in turn use() a shared constants module), literal keep/rule tails, and global
--- defaults. `config-lua -c fixtures/configs/lua/kitchen_sink.lua` emits
+-- defaults. `config flatten -c fixtures/configs/lua/kitchen_sink.lua` emits
 -- flattened TOML that round-trips through ConfigLoader.
 --
 -- The predicates name ODD geometry because that is the detector on hand, but

{nodehammer-0.2.0rc3 → nodehammer-0.2.0rc5}/fixtures/configs/lua/odd.lua

@@ -2,8 +2,8 @@
 --
 -- This is a faithful translation, not a demonstration: it builds the same
 -- scene as `fixtures/configs/odd.toml`, so the two can be compared directly.
--- `config-lua -c fixtures/configs/lua/odd.lua` and
--- `config-flatten -c fixtures/configs/odd.toml` emit equivalent TOML.
+-- `config flatten -c fixtures/configs/lua/odd.lua` and
+-- `config flatten -c fixtures/configs/odd.toml` emit equivalent TOML.
 --
 -- For a tour of the scripting surface itself, see kitchen_sink.lua.
 --

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

@@ -41,9 +41,29 @@ struct RunOptions {
     /// cannot tell those apart: an interactive interpreter has one.
     bool pager = false;
 
+    /// Suppress the running commentary commands write to stderr.
+    ///
+    /// On by default, and the mirror image of `pager` above: what a person
+    /// watching a conversion wants — what was written, what was merged, where a
+    /// root landed — is noise to a program that called a function and will read
+    /// the exit code. `src/cli/main.cpp` clears it, so somebody who typed the
+    /// command still gets the commentary; an embedder gets silence without
+    /// having to discover the member.
+    ///
+    /// It silences *narration only*. Diagnostics and the line a failing command
+    /// prints before it answers non-zero are not narration and are never
+    /// affected — a switch that hides errors is a trap rather than a setting.
+    /// Neither are reports the caller asked for by name (`--timing`,
+    /// `--size-report`): naming a report is asking for it.
+    ///
+    /// Nothing that a caller might *parse* is on that channel to begin with.
+    /// stdout carries the answer — the flattened document, the JSON, the path
+    /// to the archive — and this flag cannot turn any of it off.
+    bool quiet = true;
+
     /// Where the wasm viewer runtime is, for callers that know.
     ///
-    /// `viewer --web` needs a directory of Emscripten output that this library
+    /// `viewer serve` 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
@@ -60,7 +80,12 @@ struct RunOptions {
     /// 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;
+    ///
+    /// Braced rather than bare: every other member here carries a default, and
+    /// under `-Wmissing-field-initializers` a member without one makes
+    /// `{.quiet = false}` -- the natural way to set one field -- a warning at
+    /// each call site, which `-Werror` turns into a build failure.
+    std::filesystem::path webAssets{};
 };
 
 /// Run one command line. Returns the exit code the executable would have.

{nodehammer-0.2.0rc3 → nodehammer-0.2.0rc5}/include/nodehammer/config.hpp

@@ -121,7 +121,7 @@ class Config {
     /// open says nothing about a document's contents, which is what this
     /// promised to describe.
     ///
-    /// This is what `nodehammer validate-config` does, available to a caller
+    /// This is what `nodehammer config validate` does, available to a caller
     /// that wants to check a config without committing to using it — an editor,
     /// a CI step, a settings dialog.
     [[nodiscard]] NH_API static DiagnosticList check(const std::filesystem::path &path);

{nodehammer-0.2.0rc3 → nodehammer-0.2.0rc5}/include/nodehammer/semantic_scene.hpp

@@ -44,7 +44,7 @@ class SemanticScene {
     /// without the enclosing type (#41 §4).
     struct ReadOptions {
         /// Explicit input format — one of the names `formats()` reports, e.g.
-        /// "synthetic", "json", "flatbuffer", or "tgeo"/"dd4hep" where the
+        /// "synthetic", "json", "nhb", or "tgeo"/"dd4hep" where the
         /// backend is present. Empty means "infer from the path extension". A
         /// name this build does not have throws rather than failing to link: the
         /// format is a value, so nothing earlier could have known.
@@ -55,9 +55,10 @@ class SemanticScene {
         /// Explicit output format: "json" or "nhb". Empty means "infer from the
         /// path extension".
         ///
-        /// The write side spells the FlatBuffer format "nhb" where the read side
-        /// spells it "flatbuffer" — the two registries were named independently
-        /// and `formats()` reports both rather than picking a winner.
+        /// The same names the read side takes. The two registries were named
+        /// independently and disagreed for a while — the FlatBuffer format was
+        /// "nhb" to write and "flatbuffer" to read, so `formats()` listed both
+        /// and a caller had to know which direction it was facing.
         std::string format;
     };
 

{nodehammer-0.2.0rc3 → nodehammer-0.2.0rc5}/packaging/web/README.md

@@ -16,7 +16,7 @@ You do not normally call that. Installing this package alongside `nodehammer` is
 what makes
 
 ```console
-$ nodehammer viewer --web
+$ nodehammer viewer serve
 ```
 
 open the viewer in a browser: the command stages a servable directory from this

{nodehammer-0.2.0rc3 → nodehammer-0.2.0rc5}/packaging/web/src/nodehammer_web/__init__.py

@@ -6,7 +6,7 @@ serving it is the library's job, and this only answers the question the library
 cannot answer for itself.
 
 That question is worth spelling out, because it is the whole reason this package
-exists as a separate distribution. ``nodehammer viewer --web`` needs a directory
+exists as a separate distribution. ``nodehammer viewer serve`` needs a directory
 of Emscripten output, and it finds one by walking a ladder --- ``--web-assets``,
 then ``NODEHAMMER_WEB_ASSETS``, then whatever the calling program supplies, then
 ``<executable>/../share/nodehammer/web``. Under a wheel the last rung is wrong:

{nodehammer-0.2.0rc3 → nodehammer-0.2.0rc5}/pyproject.toml

@@ -113,7 +113,7 @@ NODEHAMMER_WERROR = "OFF"
 provider = "scikit_build_core.metadata.setuptools_scm"
 
 # ── the dependency on nodehammer-web ─────────────────────────────────────────
-# `viewer --web` needs a runtime no native build can produce, so it comes from a
+# `viewer serve` needs a runtime no native build can produce, so it comes from a
 # sibling distribution. That is a plain dependency rather than an extra: the wasm
 # never runs unless asked, so a headless install pays 2.9 MB and nothing else,
 # and "the GUI works after pip install nodehammer" is worth more than that.

{nodehammer-0.2.0rc3 → nodehammer-0.2.0rc5}/python/nodehammer/__main__.py

@@ -25,8 +25,14 @@ def main() -> int:
     is the whole reason the option exists: reaching this function means a person
     typed a command at a shell, which is the one situation where taking over
     their terminal until they press q is the helpful thing to do.
+
+    ``quiet`` is inverted for the same reason and points the same way. The
+    progress a command reports on stderr is written for somebody watching it
+    happen, and here somebody is. ``-q`` still turns it off, exactly as it does
+    for the compiled executable -- which sets both of these identically
+    (``src/cli/main.cpp``), so the two front doors behave the same.
     """
-    return run(sys.argv[1:], pager=True)
+    return run(sys.argv[1:], pager=True, quiet=False)
 
 
 if __name__ == "__main__":

{nodehammer-0.2.0rc3 → nodehammer-0.2.0rc5}/python/nodehammer/cli.py

@@ -14,6 +14,13 @@ here::
     if code != 0:
         ...
 
+Two streams, and the split is what makes this callable rather than only
+typeable. **stdout is the answer** -- the flattened config, the JSON, the path
+to the archive that was written. **stderr is everything about producing it** --
+diagnostics, and the running commentary a person watching would want. ``quiet``
+silences the commentary and defaults to on here, because reaching this function
+means a program called it. Diagnostics are never silenced.
+
 Output goes to the process's stdout and stderr at the file-descriptor level,
 not through ``sys.stdout`` -- the commands print from C++. In a notebook that
 means it lands in the terminal the kernel was started from rather than in the
@@ -36,7 +43,7 @@ __all__ = ["run"]
 def _web_runtime_dir() -> str:
     """Where the ``nodehammer-web`` package put the wasm viewer runtime.
 
-    ``viewer --web`` needs a directory of Emscripten output that this wheel does
+    ``viewer serve`` needs a directory of Emscripten output that this wheel does
     not carry -- it is a separate ``py3-none-any`` distribution, so a headless
     install can drop it and a GUI one can have it without either being a
     different build. C++ cannot find it: under a wheel the running executable is
@@ -72,7 +79,7 @@ def _web_runtime_dir() -> str:
         return ""
 
 
-def run(args: Sequence[str] | None = None, *, pager: bool = False) -> int:
+def run(args: Sequence[str] | None = None, *, pager: bool = False, quiet: bool = True) -> int:
     """Run one command line and return the exit code the executable would give.
 
     :param args: the arguments *after* the program name, as
@@ -87,15 +94,32 @@ def run(args: Sequence[str] | None = None, *, pager: bool = False) -> int:
         replaces this process's file descriptor 1 and then blocks until someone
         quits ``less``. The console script turns it on, because there a person
         really did type the command.
+    :param quiet: suppress the progress and summary lines commands write to
+        stderr -- ``Writing odd.glb ...``, ``root <dir>``, ``wrote flat.toml``.
+        On by default, and off in the console script, for exactly the reason
+        ``pager`` is the other way round: that commentary is for a person
+        watching the work, and a caller of this function is not one.
+
+        It hides narration only. Diagnostics and the line a failing command
+        prints before it answers non-zero always come through, because a switch
+        that hides errors is a trap; so do reports asked for by name
+        (``--timing``, ``--size-report``). Nothing a caller might *parse* is on
+        that stream in the first place.
+
+        ``["-v", "convert", ...]`` turns the commentary back on from the
+        arguments, which is the form to reach for when the caller does not own
+        this call -- a test harness, a notebook cell being debugged.
 
     :returns: 0 on success, non-zero otherwise. A command that could not do its
         job reports the reason on stderr and answers with a code, exactly as the
-        executable does -- it does not raise.
+        executable does -- it does not raise. ``config validate`` answers this
+        way too: an invalid document is a report on stdout *and* a non-zero
+        code, so a caller never has to scrape a stream to learn the verdict.
 
     :raises nodehammer.Error: only for a failure that escaped a command body,
         which is a defect rather than a diagnosis.
 
-    ``viewer --web`` is told where the wasm runtime is, if the ``nodehammer-web``
+    ``viewer serve`` is told where the wasm runtime is, if the ``nodehammer-web``
     package is installed alongside this one -- see :func:`_web_runtime_dir`. That
     is a default and not an override: ``--web-assets`` and
     ``NODEHAMMER_WEB_ASSETS`` still win, so a locally built runtime can be tried
@@ -107,4 +131,4 @@ def run(args: Sequence[str] | None = None, *, pager: bool = False) -> int:
     """
     if args is None:
         args = sys.argv[1:]
-    return _nodehammer.cli_run([str(a) for a in args], pager, _web_runtime_dir())
+    return _nodehammer.cli_run([str(a) for a in args], pager, quiet, _web_runtime_dir())

{nodehammer-0.2.0rc3 → nodehammer-0.2.0rc5}/scripts/check_pages_site.py

@@ -7,7 +7,7 @@ parts a static check *can* see:
   - every posture directory carries the shell, the worker script and both
     backend runtimes (a missing bundle is a blank canvas at runtime);
   - each one is self-describing: an `nh_runtime.json` naming the schema id the
-    bundles were built against, which is what `nodehammer viewer --web` checks
+    bundles were built against, which is what `nodehammer viewer serve` checks
     before serving a directory it was merely pointed at;
   - the application posture has no sidecar — that absence *is* what selects
     application mode in `index.html`;

{nodehammer-0.2.0rc3 → nodehammer-0.2.0rc5}/scripts/check_web_serve.py

@@ -1,5 +1,5 @@
 #!/usr/bin/env python3
-"""Run `viewer --web`, fetch everything it serves, and stop it.
+"""Run `viewer serve`, fetch everything it serves, and stop it.
 
 The staged root and the server agree or they do not, and the only cheap proof is
 to ask the server for every file the runtime is supposed to contain. A browser
@@ -62,8 +62,14 @@ def _await_url(lines: queue.Queue, seen: list[str]) -> str:
         if line is None:
             fail("the command exited before serving anything; output:\n" + "".join(seen))
         seen.append(line)
-        if line.startswith("serving "):
-            return line.split(None, 1)[1].strip()
+        # The URL arrives alone on stdout, with the banner around it on stderr:
+        # `viewer serve` puts it there precisely so a caller does not have to
+        # find it inside a sentence. This stream has both merged, so the URL is
+        # the line that *is* one -- matching a prefix would be matching the
+        # narration, which is the half free to be reworded.
+        candidate = line.strip()
+        if candidate.startswith(("http://", "https://")):
+            return candidate
 
 
 def _get(url: str) -> tuple[int, int]:
@@ -82,7 +88,7 @@ def main() -> None:
     if len(sys.argv) < 2:
         sys.exit(__doc__)
 
-    command = [*sys.argv[1:], "viewer", "--web", "--no-browser", "--port", "0"]
+    command = [*sys.argv[1:], "viewer", "serve", "--no-browser", "--port", "0"]
     print("$ " + " ".join(command), flush=True)
 
     # stderr is merged in rather than discarded: the ladder's explanation goes

{nodehammer-0.2.0rc3 → nodehammer-0.2.0rc5}/scripts/make_nhproj.py

@@ -19,6 +19,12 @@ same inputs always hash to the same name — the archive is named
 `project.<content-hash>.nhproj` so republishing cache-busts for free while an
 unchanged publication keeps its URL.
 
+`nodehammer project pack` is the shipped way to build one of these, and produces
+the same shape from the same `buildArchiveWorkingSet` walk. This script stays for
+the wasm dev loop and the Pages build, which run against an Emscripten tree
+without necessarily having a native `nodehammer` binary to call — and which want
+the content-hashed name that `pack` does not generate.
+
 Usage:
     scripts/make_nhproj.py <scene> <out-dir>
 

{nodehammer-0.2.0rc3 → nodehammer-0.2.0rc5}/src/api/render_scene.cpp

@@ -16,26 +16,6 @@
 namespace nodehammer {
 namespace {
 
-constexpr std::string_view kNhr = "nhr";
-
-// @TODO: Potentially unify this with other occurrences
-[[nodiscard]] std::string lowerExtension(const std::filesystem::path &path) {
-    std::string ext = path.extension().string();
-    std::transform(ext.begin(), ext.end(), ext.begin(),
-                   [](unsigned char c) { return static_cast<char>(std::tolower(c)); });
-    return ext;
-}
-
-/// `.nhr` and `.nhr.zst`. The compound form needs the second extension checked
-/// explicitly, since `path.extension()` only ever reports the last one.
-[[nodiscard]] bool isNhrPath(const std::filesystem::path &path) {
-    const auto ext = lowerExtension(path);
-    if (ext == ".nhr") {
-        return true;
-    }
-    return ext == ".zst" && lowerExtension(path.stem()) == ".nhr";
-}
-
 void appendUnique(std::vector<std::string> &out, std::string_view name) {
     if (std::find(out.begin(), out.end(), name) == out.end()) {
         out.emplace_back(name);
@@ -66,9 +46,11 @@ RenderScene RenderScene::read(std::span<const std::byte> nhr) {
 
 std::span<const std::string_view> RenderScene::formats() {
     static const std::vector<std::string> owned = [] {
-        // `nhr` first because it is the only format this type can also *read*;
-        // the exporters follow in registration order.
-        std::vector<std::string> out{std::string{kNhr}};
+        // Straight off the registry, in registration order. `nhr` used to be
+        // prepended here by hand, because it was dispatched by `write` rather
+        // than registered -- which is exactly what made this list and the CLI's
+        // disagree. It is an exporter now, so there is one source.
+        std::vector<std::string> out;
         const auto registry = ir::RenderExporterRegistry::makeDefault();
         for (const auto &exp : registry.exporters()) {
             appendUnique(out, exp->formatName());
@@ -83,20 +65,6 @@ void RenderScene::write(const std::filesystem::path &path, const OutputConfig &o
                         const WriteOptions &options) const {
     const auto &scene = api::sceneOrThrow(*this, "RenderScene::write");
 
-    // The render IR's own format is not in the exporter registry — nothing in
-    // the CLI writes one — so it is dispatched here, ahead of the registry that
-    // would otherwise report it as unknown.
-    // @TODO: Change the above and include it in the registry, so the CLI can write it too.
-    if (options.format == kNhr || (options.format.empty() && isNhrPath(path))) {
-        try {
-            const auto bytes = ir::renderSceneToBytes(scene);
-            detail::zstd_io::writeBytesToFile(path, bytes);
-            return;
-        } catch (const std::exception &e) {
-            api::rethrowAsError(e, codes::kFatalExportWriteFailed, path.string());
-        }
-    }
-
     const auto registry = ir::RenderExporterRegistry::makeDefault();
     const auto *exporter = registry.resolve(path, options.format);
     if (exporter == nullptr) {