merged Version1.0 to main ready for new academic year, ready to publish to pypy

Author: jmacey

.claude/skills/wiki/SKILL.md

@@ -0,0 +1,92 @@
+---
+name: wiki
+description: Maintain the PyNGL knowledge wiki (wiki/). Use for /wiki status (report stale pages), /wiki update (refresh stale pages), /wiki build [page] (regenerate pages from source). Also use after any change to the public API or module layout to keep the wiki in sync.
+---
+
+# PyNGL Knowledge Wiki Maintenance
+
+The `wiki/` directory is an agent-maintained knowledge base about how PyNGL
+works, written for both humans and coding agents. Every page's frontmatter
+records which source files it describes (`sources`) and the commit it was
+last verified against (`synced`). The staleness checker is the single
+source of truth for what needs updating:
+
+    uv run wiki/tools/check_sync.py          # human report
+    uv run wiki/tools/check_sync.py --json   # machine-readable
+
+Exit code 0 = all fresh; 1 = something stale or in error.
+
+## Modes
+
+Parse the argument after `/wiki`:
+
+### `/wiki status`
+
+Run the checker and relay the report: which pages are STALE (and which
+source files changed), which are in ERROR, which src/ files are UNTRACKED
+(covered by no page). Make no edits.
+
+### `/wiki update`
+
+1. Run the checker with `--json`.
+2. For each STALE page:
+   - Read the page.
+   - Run `git diff <synced>..HEAD -- <sources...>` (the page's own values)
+     to see exactly what changed.
+   - Read the current source files that changed.
+   - Rewrite only the parts of the page the changes invalidate. Do not
+     rewrite prose that is still accurate.
+   - Set `synced` to the current full HEAD hash (`git rev-parse HEAD`).
+3. For each ERROR page: fix the frontmatter (usually a bad `synced` hash —
+   re-verify the page against current sources, then set `synced` to HEAD).
+4. For UNTRACKED files: either add them to the most relevant existing
+   page's `sources` (and document them) or note that a new page is needed.
+5. If more than ~4 pages are stale, fan out one subagent per page instead
+   of updating inline; give each subagent the page path, its changed
+   files, and the Page Format rules below.
+6. Re-run the checker; it must exit 0 before you finish.
+
+### `/wiki build [page]`
+
+Full regeneration of one page (by path) or every page listed in
+`wiki/index.md`. Dispatch one subagent per page. Each subagent must:
+read the page's source files in full, follow the Page Format below, and
+set `synced` to the current full HEAD hash. After all pages are built,
+run the checker (must exit 0) and update `wiki/index.md`'s page map if
+pages were added or removed.
+
+## Page Format (all modes must preserve this)
+
+Frontmatter, then four sections:
+
+    ---
+    sources:
+      - src/ncca/ngl/vec*.py          # repo-relative globs; * stays within
+      - tests/test_api_consistency.py # a directory, ** crosses directories
+    synced: <full 40-char commit hash>
+    ---
+
+    # <Page Title>
+
+    ## Summary
+    One paragraph: what this part of the system is for.
+
+    ## How it works
+    The narrative: data flow, class relationships, lifecycle.
+
+    ## Key invariants
+    Bulleted facts an agent must not violate when editing this code
+    (e.g. "`_data` is always `np.float32`").
+
+    ## Connections
+    Relative links to related wiki pages.
+
+## Style rules
+
+- Point at code with `path` / `path:symbol` references; never paste code
+  blocks longer than 3 lines — pasted code rots.
+- State invariants and contracts, not line-by-line narration.
+- Keep each page short enough to load whole as context (~150 lines max).
+- British "colour" spelling, per project convention.
+- When a module is added/renamed/removed, update the affected page's
+  `sources` list and `wiki/index.md`'s page map in the same change.

.github/workflows/docs.yml

@@ -0,0 +1,59 @@
+name: Deploy Docs
+
+on:
+  push:
+    branches: [main, Version1.0]
+    paths:
+      - "docs/**"
+      - "src/**"
+      - ".github/workflows/docs.yml"
+  workflow_dispatch:
+
+permissions:
+  contents: write
+
+concurrency:
+  group: docs-deploy
+  cancel-in-progress: true
+
+jobs:
+  # Strict build to catch docs drift: broken references, bad ::: targets,
+  # missing/orphaned nav entries, and docstring/signature mismatches.
+  docs-strict:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v6
+        with:
+          python-version: "3.13"
+
+      - name: Install the project (needed for mkdocstrings API reference)
+        run: uv sync --locked --all-extras --dev
+
+      - name: Install docs dependencies
+        run: uv pip install mkdocs "mkdocstrings[python]"
+
+      - name: Strict docs build
+        run: uv run mkdocs build --strict -f docs/mkdocs.yml
+
+  deploy:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v6
+        with:
+          python-version: "3.13"
+
+      - name: Install the project (needed for mkdocstrings API reference)
+        run: uv sync --locked --all-extras --dev
+
+      - name: Install docs dependencies
+        run: uv pip install mkdocs "mkdocstrings[python]"
+
+      - name: Deploy to GitHub Pages
+        working-directory: docs
+        run: uv run mkdocs gh-deploy --force --clean

.github/workflows/uv.yml

@@ -7,6 +7,23 @@ on:
     branches: [main]
 
 jobs:
+  # Enforces type hints (ANN) and docstrings (D) on src/ — see CLAUDE.md.
+  lint-annotations-docstrings:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v6
+        with:
+          python-version: "3.13"
+
+      - name: Install the project
+        run: uv sync --locked --all-extras --dev
+
+      - name: Check type annotations and docstrings
+        run: uv run ruff check src/
+
   build:
     name: UV tests
     runs-on: ${{ matrix.os }}

.gitignore

@@ -70,3 +70,15 @@ venv.bak/
 
 # Cython debug symbols
 cython_debug/
+
+NGLDebug.log
+*.backup
+.DS_Store
+.serena
+err*
+doc/site*
+docs/site/
+.superpowers/
+
+# Agent worktrees
+.worktrees/

AGENTS.md

@@ -206,3 +206,10 @@ You understand modern Python development practices, architectural patterns, and
 You are a specialist in computer graphics programming and use appropriate technologies such as WebGPU and OpenGL.
 
 You can use https://github.com/NCCA and https://nccastaff.bournemouth.ac.uk/jmacey/ as context for educational graphics programming patterns and best practices.
+
+
+## Documentation and English Guide
+
+- Write using clear, concise English as would be used by an English-speaking professional. Do not use jargon or technical terms unless they are standard in the field. Do not use emojis or other non-standard formatting, including emdashes or other non-standard punctuation.
+
+When making changes to the PyNGL codebase, always ensure that you check the documentation and tutorials and ensure any changes you make are reflected in the documentation.

CLAUDE.md

@@ -38,6 +38,35 @@ uv run pre-commit run --all-files
 
 A `Taskfile.yml` (go-task) wraps some of these: `task test-all`, `task lint`, `task coverage`, `task sync`.
 
+## Documentation sync — do this whenever you touch the public API
+
+The docs site (https://ncca.github.io/PyNGL/) is built with MkDocs + mkdocstrings from `docs/` and deployed by `.github/workflows/docs.yml`. mkdocstrings renders each class/function's docstring **live from `src/` at build time**, so editing a docstring updates the site automatically — but it does **not** discover new symbols. When you add, rename, or remove a public class or function you MUST also:
+
+1. Update the matching `::: ncca.ngl...` directive in the relevant `docs/docs/*.md` page (Math, Geometry, VAO, Shaders, Camera, ImageAndTexture, Text, Misc). A new symbol that isn't listed there never appears in the docs.
+2. Add any new page to `nav:` in `docs/mkdocs.yml`.
+3. Ensure the symbol has a complete Google-style docstring — it *is* the rendered API reference — and update any tutorial examples in `docs/docs/tutorials/` that use it.
+4. Update the README feature list and this file's **Architecture** section if the module layout changed.
+
+Verify before committing (this is the drift check `gh-deploy` skips):
+
+```bash
+uv run --with mkdocs --with "mkdocstrings[python]" mkdocs build --strict -f docs/mkdocs.yml
+```
+
+`--strict` fails on broken references, bad `:::` targets, missing/orphaned nav entries, and docstring/signature mismatches (griffe warnings). The strict build passes clean and runs as a **blocking** `docs-strict` job in `docs.yml` — keep it at zero warnings.
+
+### Type hints and docstring linting
+
+Ruff enforces type-hint presence (`ANN` rules) and docstring presence/format (`D` rules, Google convention) on `src/` — see `[tool.ruff.lint]` in `pyproject.toml` (`ANN401`/`Any` is deliberately allowed at math/shader-uniform bridge points). Check before committing with the normal lint command — it already picks up these rules from config:
+
+```bash
+uv run ruff check src/
+```
+
+**Do not** run `ruff check --select ANN,D src/` — an explicit CLI `--select` overrides the config's `ignore` list, which wrongly re-flags the allowed `ANN401` cases.
+
+`src/` passes clean and the check runs as a **blocking** `lint-annotations-docstrings` CI job (see `uv.yml`). Any new or touched function/class must have complete type hints and a Google-style docstring.
+
 **Always run the whole test suite after making changes, not just the tests for the touched file.**
 
 ## Test architecture — read this before writing/running tests
@@ -48,28 +77,54 @@ A `Taskfile.yml` (go-task) wraps some of these: `task test-all`, `task lint`, `t
 
 ### Core math/graphics library — `src/ncca/ngl/`
 
-Flat module layout, one class family per file, all re-exported from `src/ncca/ngl/__init__.py`. Key groups:
+Flat module layout, one class family per file, all re-exported from `src/ncca/ngl/__init__.py`. This top-level package holds only API-agnostic modules (no direct `OpenGL.GL` imports); OpenGL-coupled modules live in the `src/ncca/ngl/opengl/` sub-package (see below) and are **not** re-exported from `ncca.ngl` — import them from `ncca.ngl.opengl` directly. Key groups:
 
 - **Math primitives**: `vec2.py`/`vec3.py`/`vec4.py` (+ `vec*_array.py` list-like containers), `mat2.py`/`mat3.py`/`mat4.py`, `quaternion.py`, `plane.py`, `bbox.py`, `transform.py`, `util.py` (lookAt/perspective/ortho/frustum/clamp/lerp).
-- **Mesh/geometry**: `base_mesh.py` (`BaseMesh`, `Face`) is the base for loadable/generatable geometry; `obj.py` (`Obj`) parses Wavefront OBJ on top of it; `prim_data.py` generates raw vertex data for primitive shapes (`Prims` enum + `PrimData`); `primitives.py` wraps that data into drawable VAOs via `VAOFactory`.
-- **VAO abstraction**: `abstract_vao.py` defines the `AbstractVAO` interface + `VertexData`; `simple_vao.py`, `simple_index_vao.py`, `multi_buffer_vao.py` are concrete OpenGL implementations; `vao_factory.py` (`VAOFactory`) is a registry/factory so new VAO types can be added without touching call sites.
-- **Shaders (OpenGL)**: `shader.py` (single compiled shader) → `shader_program.py` (linked program, uniform setters) → `shader_lib.py` (`ShaderLib`, a singleton registry of named shader programs — this is the conventional entry point application code uses, not `ShaderProgram` directly).
-- **Cameras/input**: `first_person_camera.py`, `pyside_event_handling_mixin.py` (mouse/keyboard camera control mixin for PySide6 apps).
-- **Other**: `image.py` (Pillow-backed), `texture.py`, `text.py` (freetype-py glyph atlas + geometry-shader quads), `random.py`, `log.py` (colored logger, `setup_logger`).
+- **Mesh/geometry data**: `bezier_curve.py`, `prim_data.py` generates raw vertex data for primitive shapes (`Prims` enum + `PrimData`); `obj.py` (`Obj`) parses Wavefront OBJ files, importing `BaseMesh`/`Face` and `Texture` from `ncca.ngl.opengl`.
+- **Cameras**: `first_person_camera.py`.
+- **Other**: `image.py` (Pillow-backed), `random.py`, `log.py` (colored logger, `setup_logger`).
+
+### `src/ncca/ngl/opengl/`
+
+OpenGL-coupled modules (anything that directly `import OpenGL.GL`), mirroring the `webgpu/` sub-package structure. Re-exported from `src/ncca/ngl/opengl/__init__.py`; import as `from ncca.ngl.opengl import X`, not from `ncca.ngl`.
+
+- **Mesh/geometry**: `base_mesh.py` (`BaseMesh`, `Face`) is the base for loadable/generatable geometry; `primitives.py` (`Primitives`) wraps `PrimData` (from top-level `ncca.ngl`) into drawable VAOs via `VAOFactory`.
+- **VAO abstraction**: `abstract_vao.py` defines the `AbstractVAO` interface + `VertexData`; `simple_vao.py`, `simple_index_vao.py`, `multi_buffer_vao.py` are concrete implementations; `vao_factory.py` (`VAOFactory`) is a registry/factory so new VAO types can be added without touching call sites.
+- **Shaders**: `shader.py` (single compiled shader) → `shader_program.py` (linked program, uniform setters) → `shader_lib.py` (`ShaderLib`, a singleton registry of named shader programs — this is the conventional entry point application code uses, not `ShaderProgram` directly).
+- **Input**: `pyside_event_handling_mixin.py` (mouse/keyboard camera control mixin for PySide6 apps).
+- **Other**: `texture.py`, `text.py` (freetype-py glyph atlas + geometry-shader quads), `shaders/` (glsl assets used by `shader_lib.py`).
 
 ### `src/ncca/ngl/webgpu/`
 
-Parallel rendering stack targeting `wgpu` instead of OpenGL. `base_webgpu_pipeline.py` is the common base; `*_pipeline.py` files (triangle, line, point, point_list, instanced_geometry, custom_shader) are concrete render pipelines; `pipeline_factory.py` mirrors the OpenGL `VAOFactory` pattern for pipelines; `pipeline_shaders.py`/`webgpu_constants.py` hold shader source and enum constants. Has its own `__main__.py` for standalone demo/dev runs.
+Parallel rendering stack targeting `wgpu` instead of OpenGL. `webgpu_widget.py` (`WebGPUWidget`) is the PySide6 widget applications subclass — it renders offscreen and blits the result, so there is no OpenGL context or swapchain to manage. `base_webgpu_pipeline.py` is the common base; `*_pipeline.py` files (triangle, line, point, point_list, instanced_geometry, custom_shader) are concrete render pipelines; `pipeline_factory.py` mirrors the OpenGL `VAOFactory` pattern for pipelines; `pipeline_shaders.py`/`webgpu_constants.py` hold shader source and enum constants. Has its own `__main__.py` for standalone demo/dev runs.
 
 ### `src/ncca/ngl/widgets/`
 
-PySide6 (Qt) widgets for editing/displaying NGL types in GUIs: `vec2widget.py`/`vec3widget.py`/`vec4widget.py`, `mat4widget.py`, `transformwidget.py`, `rgbcolourwidget.py`/`rgbacolourwidget.py`, `lookatwidget.py`. Has GLSL assets under `widgets/glsl/`.
+PySide6 (Qt) widgets for editing/displaying NGL types in GUIs: `vec2widget.py`/`vec3widget.py`/`vec4widget.py`, `mat2widget.py`/`mat3widget.py`/`mat4widget.py` (editable NxN grids sharing the private `_MatGridWidget` base in `mat_grid_widget.py`; Mat3Widget/Mat4Widget add a method combo box for `rotate_x`/`rotate_y`/`rotate_z`/`scale`/`translate`), `transformwidget.py`, `rgbcolourwidget.py`/`rgbacolourwidget.py`, `lookatwidget.py`, `perspectivewidget.py`. Has GLSL assets under `widgets/glsl/`.
+
+### `src/ncca/ngl/qml/`
+
+Qt Quick (QML) equivalents of the `widgets/` PySide6 widgets: `vec2_model.py`/`vec3_model.py`/`vec4_model.py`,
+`mat_grid_model.py` (shared base) + `mat2_model.py`/`mat3_model.py`/`mat4_model.py`, `transform_model.py`,
+`lookat_model.py`, `perspective_model.py`, `rgb_colour_model.py`/`rgba_colour_model.py` — each a `QObject` registered as a QML type via
+`@QmlElement`, paired with a same-named `.qml` view file (`Vec3Widget.qml`, `Mat4Widget.qml`, etc.) plus shared
+`DecimalSpinBox.qml`/`MatrixGridWidget.qml` components. It is a file-based QML module (`qmldir` declares
+`module ncca.ngl.qml`), so external `.qml` files only resolve `import ncca.ngl.qml 1.0` after calling the exported
+`add_import_path(engine)`. Has its own `__main__.py` + `main.qml` demo, run via `python -m ncca.ngl.qml`.
 
 ### API consistency conventions
 
-- Vector/matrix classes implement `copy()`, `to_numpy()`, `to_list()`, `to_tuple()`, and `__hash__`.
+- All math classes (`Vec2/3/4`, `Mat2/3/4`, `Quaternion`) follow one contract:
+  numpy `np.float32` storage in `_data`; immutable-style operations returning
+  new objects (`normalized()`, `transposed()`, `inverse()`, `clamped()` — only
+  `set()` and element assignment mutate); constructors take components with a
+  sensible default; `from_list`/`from_numpy` classmethods;
+  `copy()`/`to_numpy()`/`to_list()`/`to_tuple()`; `__eq__`/`__hash__`; eval-able
+  `__repr__`. `@` is the linear-algebra product; `*` is scalar only, except
+  `Quaternion * Vec3`, which rotates the vector (kept per spec).
+  `tests/test_api_consistency.py` enforces this — run it when touching math code.
 - Prefer numpy arrays (`np.float32`) over Python lists for numeric data; use `__slots__` on data-heavy classes.
-- Module-specific errors are plain `Exception` subclasses named `<Module>Error` (e.g. `Mat3Error`, `ObjParseVertexError`), raised rather than returning sentinel values.
+- Module-specific errors are plain `Exception` subclasses named `<Module>Error` (e.g. `MatrixError`, `ObjParseVertexError`), raised rather than returning sentinel values.
 - **"Colour"** (not "color") is the correct spelling in this codebase's identifiers, docs, and variables.
 - Docstrings are Google-style with Args/Returns/Raises; type hints are required on all function signatures and class attributes.
 - Executable scripts use the shebang `#!/usr/bin/env -S uv run --script`.

LICENSE.txt

@@ -4,4 +4,4 @@ Permission is hereby granted, free of charge, to any person obtaining a copy of
 
 The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
 
-THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.