Add Unit Testing

.cursor/rules/cmake-target-design.mdc

@@ -0,0 +1,71 @@
+---
+description: CMake target-based design conventions for OVR (no catchall include paths, no self-referencing link lists)
+globs: **/CMakeLists.txt,**/*.cmake
+alwaysApply: false
+---
+
+# CMake target-based design
+
+OVR's build is target-driven: every dependency should expose a CMake target
+that carries its own include directories, compile definitions, sources, and
+link dependencies. Avoid broad include shims such as `${repo}/extern`.
+
+## No catchall `extern/` include paths
+
+```cmake
+# BAD - sweeping include path that resolves <X/Y.h> to whatever happens to
+# live under extern/X/. Order-dependent, fragile when deps overlap (e.g.
+# both tinygltf and stb bundle stb_image.h).
+target_include_directories(rendercommon PUBLIC
+  $<BUILD_INTERFACE:${CMAKE_CURRENT_SOURCE_DIR}/../extern>
+)
+
+# GOOD - each external dep owns its include path on its own target.
+# Consumers link the target; the include path propagates.
+target_link_libraries(rendercommon
+  PUBLIC tfnmodule           # carries <tfn/X.h>
+  PRIVATE stb tinyexr        # carry <stb_image.h>, <tinyexr.h>
+)
+```
+
+## Header layout mirrors include style
+
+When a local helper target is consumed via `<libname/X.h>`, mirror that in the
+filesystem so the target's own dir is the include root. Avoid `..` traversal in
+INTERFACE include directories.
+
+```
+extern/glfwapp/
+├── CMakeLists.txt              ← exposes ${CMAKE_CURRENT_LIST_DIR} as PUBLIC include
+└── glfwapp/                    ← matches the include prefix
+    ├── GLFWApp.h
+    └── camera_frame.h
+```
+
+## Don't put a target in a list it itself consumes
+
+```cmake
+# BAD - glfwApp PUBLIC-links ${GFX_LIBRARIES}, which contains glfwApp.
+# Self-referencing list, also forces imgui (also in GFX_LIBRARIES) to link
+# its own consumer.
+list(APPEND GFX_LIBRARIES glfwApp)
+target_link_libraries(glfwApp PUBLIC ${GFX_LIBRARIES})
+
+# GOOD - GFX_LIBRARIES is the lower-level set (gl, glfw, glad, imgui).
+# glfwApp consumes them; consumers of glfwApp link glfwApp directly.
+```
+
+## Namespace-scope FetchContent'd deps when they bundle conflicting headers
+
+If an upstream bundles private copies of headers we also provide independently
+(e.g. tinygltf bundles `stb_image.h` and `json.hpp`), do not expose the
+upstream root directly. Mirror it under `build/<dep>_compat/<dep>/` and expose
+only `build/<dep>_compat/`. Consumers then include `<dep/header.h>` while the
+upstream's quote-includes still resolve to its private bundled copies.
+
+## Use `SKIP_RETURN_CODE` for feature-probe fixtures
+
+CTest fixture-setup tests that may legitimately fail on hosts lacking a feature
+(e.g. `gpu_probe` on a no-GPU CI runner) should set `SKIP_RETURN_CODE` so the
+probe reports Skipped, not Failed. Dependent tests still skip through
+`FIXTURES_REQUIRED`; `ctest` itself stays green on expected no-feature hosts.

.cursor/rules/karpathy-guidelines.mdc

@@ -0,0 +1,70 @@
+---
+description: Behavioral guidelines to reduce common LLM coding mistakes. Use when writing, reviewing, or refactoring code to avoid overcomplication, make surgical changes, surface assumptions, and define verifiable success criteria.
+alwaysApply: true
+---
+
+# Karpathy behavioral guidelines
+
+Behavioral guidelines to reduce common LLM coding mistakes. Merge with project-specific instructions as needed.
+
+**Tradeoff:** These guidelines bias toward caution over speed. For trivial tasks, use judgment.
+
+## 1. Think Before Coding
+
+**Don't assume. Don't hide confusion. Surface tradeoffs.**
+
+Before implementing:
+- State your assumptions explicitly. If uncertain, ask.
+- If multiple interpretations exist, present them - don't pick silently.
+- If a simpler approach exists, say so. Push back when warranted.
+- If something is unclear, stop. Name what's confusing. Ask.
+
+## 2. Simplicity First
+
+**Minimum code that solves the problem. Nothing speculative.**
+
+- No features beyond what was asked.
+- No abstractions for single-use code.
+- No "flexibility" or "configurability" that wasn't requested.
+- No error handling for impossible scenarios.
+- If you write 200 lines and it could be 50, rewrite it.
+
+Ask yourself: "Would a senior engineer say this is overcomplicated?" If yes, simplify.
+
+## 3. Surgical Changes
+
+**Touch only what you must. Clean up only your own mess.**
+
+When editing existing code:
+- Don't "improve" adjacent code, comments, or formatting.
+- Don't refactor things that aren't broken.
+- Match existing style, even if you'd do it differently.
+- If you notice unrelated dead code, mention it - don't delete it.
+
+When your changes create orphans:
+- Remove imports/variables/functions that YOUR changes made unused.
+- Don't remove pre-existing dead code unless asked.
+
+The test: Every changed line should trace directly to the user's request.
+
+## 4. Goal-Driven Execution
+
+**Define success criteria. Loop until verified.**
+
+Transform tasks into verifiable goals:
+- "Add validation" → "Write tests for invalid inputs, then make them pass"
+- "Fix the bug" → "Write a test that reproduces it, then make it pass"
+- "Refactor X" → "Ensure tests pass before and after"
+
+For multi-step tasks, state a brief plan:
+```
+1. [Step] → verify: [check]
+2. [Step] → verify: [check]
+3. [Step] → verify: [check]
+```
+
+Strong success criteria let you loop independently. Weak criteria ("make it work") require constant clarification.
+
+---
+
+**These guidelines are working if:** fewer unnecessary changes in diffs, fewer rewrites due to overcomplication, and clarifying questions come before implementation rather than after mistakes.

.cursor/rules/license-and-attribution.mdc

@@ -0,0 +1,48 @@
+---
+description: License and citation hygiene for OVR and its submodules
+alwaysApply: true
+---
+
+# License and Attribution Hygiene
+
+## Verify attribution before writing
+
+License boilerplate is reusable; attribution is not. When copying or templating
+`LICENSE` / `CITATION.cff`, always audit the destination project's authorship
+before writing:
+
+1. Inspect the destination's source headers / README / git remote.
+2. Replace any copied trailing `Copyright YYYY <Name>` line with the
+   destination project's actual copyright holder.
+3. If there is any ambiguity, ask the user. Do not guess or preserve a copied
+   name "just in case".
+
+```bash
+# BAD - copies parent attribution into a submodule
+cp LICENSE extern/tfnmodule/LICENSE
+
+# GOOD - copy boilerplate only, then rewrite the trailing copyright line
+# after checking the destination project's own files.
+```
+
+## When asked to write CITATION.cff
+
+- Use author names from the destination project's source headers, README, or
+  existing citation metadata.
+- Do not add institutions, affiliations, addresses, or co-authors unless the
+  user asks or the project already declares them.
+- Do not infer ownership from adjacent repositories or old copied license text.
+
+## Submodules are not parent-repo files
+
+Submodule checkouts (`extern/<name>/`, `github-actions/`) are independent git
+repos. Files added there are working-tree changes inside the submodule, not
+normal parent-repo files. When editing a submodule, surface the two-step commit
+flow:
+
+```bash
+cd extern/<sub> && git add ... && git commit && git push
+cd ../..        && git add extern/<sub> && git commit  # bump pointer
+```
+
+The parent will show the submodule as dirty until both steps complete.

.cursor/rules/python-package-conventions.mdc

@@ -0,0 +1,59 @@
+---
+description: Conventions for the ovrpy Python package + scikit-build-core wheel
+globs: pyproject.toml,python/**,test/conftest.py,test/python/**
+alwaysApply: false
+---
+
+# ovrpy Python Package Conventions
+
+## Skipping is opt-in, never automatic
+
+`pytest test/python/` runs every parametrized variant by default - including
+the `[optix7]` (`gpu`) ones. A failing variant on a host lacking the hardware is
+a real signal, not an automatic skip.
+
+The user opts out explicitly:
+
+```bash
+pytest -m "not gpu"   # CPU-only
+pytest -m "not cpu"   # GPU-only
+ctest -LE gpu          # ctest equivalent
+```
+
+Do not add `libcuda.so.1` probing or any other "auto-skip the GPU tier on a
+GPU-less host" logic to the Python `_probe_backend`. The construct-time probe
+(`ovrpy.create_renderer(name)`) is the only acceptable automatic skip trigger,
+because it indicates a backend was not built / cannot construct, not that the
+host lacks runtime hardware.
+
+## pytest config lives in `pyproject.toml`
+
+Keep `[tool.pytest.ini_options]` in the repo-root `pyproject.toml`, not in
+`test/pytest.ini`. pytest finds the root config from any cwd in the tree; a
+`test/`-local config can be missed and cause `PytestUnknownMarkWarning` instead
+of `--strict-markers` enforcement.
+
+## Wheel install component is `ovrwheel`
+
+All `install(...)` rules that should ship in the pip/uv-built wheel must attach
+`COMPONENT ovrwheel`. `pyproject.toml` sets
+`install.components = ["ovrwheel"]` so third-party FetchContent install
+rules (glfw3, glad, ospray cmake configs) don't leak into the wheel.
+
+## Wheel binaries: bundle inside `<wheel>/ovrpy/` with `INSTALL_RPATH=$ORIGIN`
+
+`_core.so` plus the renderer/OSPRay/imgui closure live next to the package
+init. C++ apps go in `<wheel>/ovrpy/bin/` with `INSTALL_RPATH=$ORIGIN/..` and
+are surfaced on `$PATH` via Python entry-point shims in `python/ovrpy/_apps.py`
+(`os.execv` the bundled binary).
+
+Anchor shim lookups on `Path(_core.__file__).parent`, not
+`Path(__file__).parent`: editable installs resolve `_apps.py` to the source
+tree, while `_core.__file__` points at the real install location.
+
+## Loader-error helper translates missing system libs
+
+`python/ovrpy/__init__.py:_translate_loader_error` catches the dynamic linker's
+`lib<X>.so: cannot open shared object file` error and rewrites it with the
+missing system lib plus `apt`/`dnf` install hints. Extend `_SYSTEM_LIB_HINTS`
+when adding runtime deps that we deliberately don't bundle.