Reveal full spatial graph structure with normalized layout controls

.github/workflows/ci.yml

@@ -8,6 +8,10 @@ on:
 env:
   CARGO_TERM_COLOR: always
   RUSTFLAGS: -D warnings
+  RUSTDOCFLAGS: -D warnings
+
+permissions:
+  contents: read
 
 jobs:
   test:
@@ -16,6 +20,10 @@ jobs:
     steps:
       - uses: actions/checkout@v4
 
+      - uses: actions/setup-python@v5
+        with:
+          python-version: '3.12'
+
       - name: Install system deps (Bevy / winit)
         run: |
           sudo apt-get update
@@ -35,13 +43,27 @@ jobs:
         run: cargo fmt --all -- --check
 
       - name: test hyper-viz
-        run: cargo test -p hyper-viz
+        run: cargo test --locked -p hyper-viz
 
       - name: test hyper-viz-bevy (lib)
-        run: cargo test -p hyper-viz-bevy --lib
+        run: cargo test --locked -p hyper-viz-bevy --lib
 
       - name: clippy
-        run: cargo clippy -p hyper-viz -p hyper-viz-bevy --all-targets -- -D warnings
+        run: cargo clippy --locked --workspace --all-targets -- -D warnings
+
+      - name: Public Rust documentation
+        run: cargo doc --locked --workspace --no-deps
+
+      - name: Exporter and benchmark aggregation tests
+        run: |
+          PYTHONPATH=scripts:scripts/benchmarks python -m unittest \
+            scripts/test_mathlib_graph.py scripts/benchmarks/test_datasets.py \
+            scripts/benchmarks/test_summarize.py
+
+      - name: CLI help and version
+        run: |
+          cargo run --locked -- --help
+          cargo run --locked -- --version
 
       - name: headless example
-        run: cargo run -p hyper-viz --example project_scene
+        run: cargo run --locked -p hyper-viz --example project_scene

CHANGELOG.md

@@ -0,0 +1,52 @@
+# Release notes
+
+## 0.2.0 — unreleased
+
+Rust workspace crates, the `hyper` CLI, `hypergraph-viz`, and the
+`hypergraph-viz-viewer` companion share version `0.2.0`. The Python `[viewer]`
+extra requires the matching companion. This minor version marks new layout and
+exploration features and Rust API changes while the project remains pre-1.0.
+
+### Features
+
+- Connectivity-based spatial initialization, Normalized and LinLog force models,
+  separate pair/set weights, degree/arity normalization, derived-set influence,
+  movement limits, display fading, structural rebuild, and full-graph framing.
+- An optional native dependency canvas (`--view dependencies`) with validated
+  import direction, independent import/dependent traversal, filters, shortest
+  paths, exact module search, expansion, and bounded navigation history.
+- Rust dependency-query APIs and source attributes retained in projected scenes.
+- Clean camera tours with structural layout and wall-clock navigation capture;
+  timestamped video export preserves navigation speed when captures are dropped,
+  with adjustable hull opacity and bounded group outlines for dense tours.
+- Expanded API, architecture, viewer, migration, and contributor documentation.
+
+### Fixes
+
+- Scene entities refresh when input reloads in dependency mode, preventing stale
+  indices on return to Spatial. Newly created nodes stay hidden in Dependencies.
+- Explicit HIF input formats continue through CLI startup and watched reloads
+  when a view mode is selected.
+
+### Compatibility and migration
+
+- `LayoutConfig` struct literals must provide `topology` or use
+  `..Default::default()`. Construct `ForceLayout3D` through its constructors;
+  its structural connectivity cache is private.
+- Manual `SceneMeta`, `SceneNode`, and `SceneHyperedge` literals require `attrs`.
+  `SceneHyperedge::hub_index` is optional: only bipartite projections have hubs.
+  See the [Rust API migration guide](docs/API.md#scene-migration).
+- Manual `ShowcaseConfig` literals require `clean`, `realtime`, `structural`,
+  `hull_opacity`, and `hull_outlines`. Use `false` for these booleans and `None`
+  for opacity to retain the original annotated offline tour.
+- Headless layout defaults retain Legacy forces, and Auto view remains Spatial.
+  Native `hypergraph.v1` and session `hyperviz.session.v1` formats remain supported.
+- Python imports, HIF interchange, viewer launching, and CPython 3.10+ support
+  retain their existing interfaces. These layout controls are available through
+  Rust and the native viewer; this release adds no Python layout API or notebook
+  embedding.
+
+The published `0.1.2` wheels predate these features. Build this checkout until
+`0.2.0` is published. Package publication requires a separately created
+`python-v0.2.0` tag on a validated commit; see the [release guide](docs/PYTHON_RELEASE.md).
+Rust crates retain `publish = false` pending a separate crates.io release decision.

CONTRIBUTING.md

@@ -9,9 +9,9 @@ This repository is **visualization only**:
 
 | In scope | Out of scope |
 |---|---|
-| `hypergraph.v1` schema, scene IR, projections | Memory engines / claim pipelines |
-| Headless 3D force layout | Proprietary host business logic |
-| Optional Bevy + egui viewer | Publishing crates without a release decision |
+| Native/HIF interchange, scene IR, projections | Memory engines / claim pipelines |
+| Headless layout, dependency queries | Proprietary host business logic |
+| Optional Bevy viewer, Python bindings and launcher | Publishing packages without a release decision |
 
 Do not add Atomic Memory Core types, private service URLs, secrets, or claim-
 pipeline code here. Host apps own those concerns and should feed this library
@@ -21,12 +21,21 @@ plain vertices + hyperedges (or `hypergraph.v1` JSON).
 
 Requirements: Rust **1.89+** (see `rust-toolchain.toml`; Bevy 0.18 MSRV), a
 GPU/windowing stack for the native viewer.
+Workspace-wide clippy and documentation also build the Python extension and
+require **CPython 3.10+** on PATH. When your system Python is older, activate a
+supported virtual environment first or set `PYO3_PYTHON=/path/to/python3.12`.
 
 ```bash
-cargo test -p hyper-viz
-cargo test -p hyper-viz-bevy --lib
-cargo clippy -p hyper-viz -p hyper-viz-bevy --all-targets -- -D warnings
+cargo test --locked -p hyper-viz
+cargo test --locked -p hyper-viz-bevy --lib
+cargo clippy --locked --workspace --all-targets -- -D warnings
 cargo fmt --all -- --check
+RUSTDOCFLAGS="-D warnings" cargo doc --locked --workspace --no-deps
+
+# Standard-library exporter and benchmark aggregation checks
+PYTHONPATH=scripts:scripts/benchmarks python3 -m unittest \
+  scripts/test_mathlib_graph.py scripts/benchmarks/test_datasets.py \
+  scripts/benchmarks/test_summarize.py
 
 # Headless example
 cargo run -p hyper-viz --example project_scene
@@ -35,6 +44,28 @@ cargo run -p hyper-viz --example project_scene
 cargo run -- fixtures/sample.json
 ```
 
+For Python development, use CPython 3.10+ and a virtual environment:
+
+```bash
+python -m venv .venv
+. .venv/bin/activate # Windows PowerShell: .venv\Scripts\Activate.ps1
+python -m pip install maturin==1.9.6 -r crates/hyper-viz-python/requirements-test.txt
+maturin develop --locked --manifest-path crates/hyper-viz-python/Cargo.toml
+cargo run --locked -p hyper-viz-python --bin stub_gen
+git diff --exit-code -- crates/hyper-viz-python/python/hyper_viz/_core.pyi
+python -m pytest crates/hyper-viz-python/tests -q
+python -m mypy --strict crates/hyper-viz-python/python/hyper_viz
+python crates/hyper-viz-python/examples/xgi_interop.py
+```
+
+The launcher tests use a substitute executable and can run without a display.
+Desktop wheel builds and installed-package integration checks run in
+[the Python workflow](.github/workflows/python.yml) on all supported platforms.
+See the [release guide](docs/PYTHON_RELEASE.md) for package contents and source
+distribution checks. Compile documentation examples when changing public APIs,
+and update [API](docs/API.md), [architecture](docs/ARCHITECTURE.md), and the
+relevant user guide when behavior changes.
+
 ## Pull requests
 
 - Prefer small, focused diffs with a clear Conventional Commit subject.

Cargo.toml

@@ -3,7 +3,7 @@ resolver = "2"
 members = ["crates/hyper-viz", "crates/hyper-viz-bevy", "crates/hyper-viz-python"]
 
 [workspace.package]
-version = "0.1.2"
+version = "0.2.0"
 edition = "2024"
 license = "MIT OR Apache-2.0"
 authors = ["Bregy Malpartida <bregy@atomicstrata.ai>"]

README.md

@@ -2,6 +2,10 @@
 
 **A native 3D hypergraph viewer for Python workflows and Rust applications.**
 
+<a href="docs/media/mathlib-realtime.mp4">
+  <img src="docs/media/mathlib-realtime.gif" alt="Realtime navigation through the Mathlib dependency case study" width="100%">
+</a>
+
 A hypergraph represents a group relationship as one edge connecting any number
 of nodes: authors on a paper, participants in an interaction, or modules in a
 dependency group. Hyper lets you inspect those memberships, find overlapping
@@ -10,12 +14,6 @@ groups, and explore neighborhoods with search, picking, and lasso selection.
 [Try the viewer](#try-the-viewer) · [Use Python](#use-from-python) ·
 [Use Rust](#use-from-rust) · [Documentation](#documentation)
 
-[![Mathlib module dependency groups in Hyper's native 3D viewer](docs/media/mathlib.gif)](docs/media/mathlib.mp4)
-
-[Full-resolution Mathlib demo](docs/media/mathlib.mp4) ·
-[Reproduce the demo](docs/mathlib-demo.md).
-The recording uses a settled layout; it is not a live-layout performance test.
-
 ## Try the viewer
 
 Install [uv](https://docs.astral.sh/uv/getting-started/installation/), then open
@@ -154,6 +152,21 @@ Notebook embedding, live Python updates, and direct scientific-library object
 adapters are not yet available; see the [notebook roadmap](docs/NOTEBOOK_ROADMAP.md)
 for browser plans.
 
+## Layout and exploration
+
+Choose bipartite, clique, or star projection to inspect the same memberships
+from different views. Search, picking, lasso selection, and neighborhood focus
+help you explore individual nodes and overlapping groups; display settings and
+saved sessions keep the view manageable.
+
+The upcoming `0.2.0` release adds connectivity-based initialization and tunable
+Legacy, Normalized, and LinLog layouts. An optional dependency canvas explores
+graphs with validated import-direction attributes through bounded traversal,
+filters, and shortest paths. See the [viewer guide](docs/VIEWER.md),
+[Rust layout and query APIs](docs/API.md), and [release notes](CHANGELOG.md).
+Build this checkout to use these additions until `0.2.0` is published;
+published `0.1.2` wheels predate them.
+
 ## Use from Rust
 
 The `hyper-viz` core handles JSON I/O, projections, and 3D force layout without
@@ -209,6 +222,25 @@ See the [viewer guide](docs/VIEWER.md) for more commands, and the
 
 </details>
 
+## Use cases and benchmarks
+
+Hyper works with group relationships such as coauthorship, biochemical
+reactions, collaboration networks, and software dependencies. The Python
+quick start above demonstrates overlapping coauthor groups.
+
+One larger case study explores **Mathlib module imports** and their dependency
+groups. It provides a reproducible dataset and a workload for evaluating layout
+and rendering behavior.
+
+
+[Case study and reproduction](docs/mathlib-demo.md) ·
+[Full-resolution recording](docs/media/mathlib-realtime.mp4) ·
+[Layout comparisons and native measurements](docs/benchmarks/module-explorer.md).
+The recording follows realtime camera motion through a settled layout, with
+capture overhead included; it is not a live-layout performance test.
+The [ecosystem benchmarks](docs/benchmarks/ecosystem-2026-10-03/README.md)
+cover additional workloads, methods, and limitations.
+
 ## Documentation
 
 | Guide | What you'll find |

crates/hyper-viz-bevy/Cargo.toml

@@ -28,7 +28,7 @@ hyper-viz = { workspace = true }
 bevy = { version = "0.18", default-features = false, features = [
     "default_app", "2d_bevy_render", "3d_bevy_render", "ui_bevy_render", "scene", "picking",
     "std", "android-game-activity", "android_shared_stdcxx", "bevy_winit",
-    "default_font", "multi_threaded", "webgl2", "x11", "wayland", "sysinfo_plugin",
+    "default_font", "multi_threaded", "webgl2", "x11", "wayland", "sysinfo_plugin", "bmp",
 ] }
 bevy_egui = "0.39"
 bevy_panorbit_camera = { version = "0.34", features = ["bevy_egui"] }

crates/hyper-viz-bevy/README.md

@@ -76,3 +76,14 @@ On quit (and ~450ms after the last change) the viewer writes
 selection, focus neighborhood, and find. Desktop path is
 the OS config dir (`hyper-viz/session.json`); wasm uses `localStorage`.
 `HYPER_VIZ_SESSION` overrides the file or `off` disables it.
+
+Auto mode preserves the spatial viewer. The optional native egui dependency
+canvas requires `.with_view_mode(ViewMode::Dependencies)` or `--view dependencies`.
+It provides exact module selection, directional expansion, filters, shortest paths,
+a clipped layered canvas, full neighbor lists, and history. Use `.with_view_mode(ViewMode::Spatial)`
+on the plugin to keep a host in Spatial, or configure a standalone app through
+`VisualizerConfig::with_module` and `visualizer_app_with_config`. The dependency
+view pauses spatial work; returning restores the previous simulation state.
+
+See [Mathlib exploration](../../docs/mathlib-demo.md#explore-imports-and-dependents)
+and `examples/module_benchmark.rs` for normal-canvas measurements.