Merge pull request 'release: v0.10.0 — reviewer-ready' (#20) from release/v0.10.0 into main

Post-merge consistency commit:

  * CITATION.cff version 0.9.0 → 0.10.0, date 2026-05-26
  * CHANGELOG.md — new "[0.10.0]" section listing all 13 commits
    that landed across PRs #17 / #18 / #19
  * Post-merge gate fixes:
      - doxygen_groups.h + doxygen_namespaces.h gain \\file briefs
      - .codespellrc extended (honour, thead, optimiser)
      - compile-time.md: unbalanced backtick on line 102 fixed
        (was confusing Doxygen's verbatim-block detector)

Final gate state on the merged main:
  ✅ 259/259 tests pass
  ✅ test-count consistency
  ✅ markdown links 166/166 resolve (43 .md files)
  ✅ CGAL conventions 0/8 violations
  ✅ license-headers 68/68 carry MIT SPDX
  ✅ codespell 0 typos
  ✅ shellcheck 0 findings (18 scripts)
  ✅ Doxygen 396/396 symbols, 0 warnings

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

.clang-format

@@ -0,0 +1,76 @@
+# conformallab++ formatting policy
+#
+# Captures the style already present in code/include/.  Documented here
+# so clang-format can enforce it locally (scripts/quality/clang-format.sh)
+# and so new contributors get the same output their editor would on save.
+#
+# This is NOT the upstream CGAL clang-format (there isn't one published);
+# it's the style our tree already uses, mechanically extracted.
+
+BasedOnStyle: LLVM
+Language: Cpp
+Standard: c++17
+
+IndentWidth: 4
+TabWidth: 4
+UseTab: Never
+ColumnLimit: 100                  # loose; readability over hard wrap
+
+# Brace placement — matches the project tree:
+#   functions / methods → opening brace on a new line  (CGAL convention)
+#   structs / classes   → opening brace on a new line
+#   else / catch        → on the same line as the closing brace of the preceding block
+BreakBeforeBraces: Custom
+BraceWrapping:
+  AfterClass:            true
+  AfterStruct:           true
+  AfterEnum:             true
+  AfterFunction:         true
+  AfterNamespace:        false
+  AfterUnion:            true
+  AfterControlStatement: false
+  BeforeElse:            false
+  BeforeCatch:           false
+  IndentBraces:          false
+  SplitEmptyFunction:    false
+  SplitEmptyRecord:      false
+  SplitEmptyNamespace:   true
+
+# Reference & pointer modifiers attach to the type (`int& x`, not `int &x`).
+PointerAlignment: Left
+ReferenceAlignment: Left
+
+# Aligned `using = ...` blocks are intentional in the trait classes.
+AlignConsecutiveDeclarations: AcrossEmptyLines
+AlignConsecutiveAssignments: AcrossEmptyLines
+AlignTrailingComments: true
+AlignAfterOpenBracket: Align
+
+AllowShortFunctionsOnASingleLine: Inline
+AllowShortIfStatementsOnASingleLine: Never
+AllowShortLoopsOnASingleLine: false
+AllowShortBlocksOnASingleLine: Never
+AllowShortLambdasOnASingleLine: Inline
+
+# Template-related: break before each parameter when the template line
+# would otherwise exceed ColumnLimit (matches existing
+# `template <typename TriangleMesh, typename ...>` patterns).
+BreakBeforeBinaryOperators: NonAssignment
+BinPackParameters: false
+BinPackArguments: false
+AlwaysBreakTemplateDeclarations: Yes
+SpaceAfterTemplateKeyword: true
+
+NamespaceIndentation: None
+AccessModifierOffset: -4
+IndentCaseLabels: false
+
+# Includes: keep manual ordering — re-ordering can break Eigen / CGAL
+# transitive-include assumptions in subtle ways.  We just enforce no
+# accidental duplicate blank lines.
+SortIncludes: Never
+MaxEmptyLinesToKeep: 1
+KeepEmptyLinesAtTheStartOfBlocks: false
+
+# Comments: don't touch.
+ReflowComments: false

.clang-tidy

@@ -0,0 +1,45 @@
+# conformallab++ clang-tidy policy
+#
+# Curated, deliberately small.  The CGAL header tree triggers tens of
+# thousands of warnings under default settings (CGAL's chosen style is
+# pre-C++17 in many places).  Restricting to checks that fire on OUR
+# code, not on transitive CGAL/Eigen/Boost headers, keeps the signal
+# meaningful.
+#
+# Promotion gate: a check moves into this list only when (a) it fires
+# on code we authored AND (b) the fix is mechanical (no algorithmic
+# rewrite required).  Anything algorithmic belongs in a code review,
+# not in a static analyser.
+
+Checks: >
+  -*,
+  bugprone-too-small-loop-variable,
+  bugprone-use-after-move,
+  bugprone-undefined-memory-manipulation,
+  bugprone-integer-division,
+  bugprone-suspicious-string-compare,
+  bugprone-misplaced-widening-cast,
+  bugprone-sizeof-expression,
+  cppcoreguidelines-init-variables,
+  cppcoreguidelines-pro-type-member-init,
+  performance-for-range-copy,
+  performance-implicit-conversion-in-loop,
+  performance-unnecessary-copy-initialization,
+  performance-unnecessary-value-param,
+  readability-misleading-indentation,
+  readability-redundant-smartptr-get,
+  modernize-use-nullptr,
+  modernize-use-override,
+  modernize-deprecated-headers
+
+# Only emit warnings on our own headers.  CGAL/Eigen/etc. live under
+# `code/deps/` (vendored) or are installed system-wide; we never want
+# clang-tidy fixes for them.
+HeaderFilterRegex: '^.*/code/include/(?!deps/).*$'
+
+WarningsAsErrors: ''
+
+CheckOptions:
+  - { key: cppcoreguidelines-init-variables.IgnoreArrays, value: true }
+  - { key: performance-for-range-copy.WarnOnAllAutoCopies, value: true }
+  - { key: performance-unnecessary-value-param.AllowedTypes, value: 'Eigen::Vector.*;Eigen::Matrix.*' }

.cmake-format.yaml

@@ -0,0 +1,28 @@
+# conformallab++ cmake-format policy
+#
+# Drives the cmake-format / cmake-lint tools used by
+# scripts/quality/cmake-format.sh.  The defaults are deliberately
+# permissive — the goal is to catch the obvious style drift (mixed
+# 2-vs-4-space indent, inconsistent argument wrapping, undocumented
+# options) without forcing a rewrite of every CMakeLists.txt we have.
+
+format:
+  line_width: 100               # match .clang-format
+  tab_size: 4
+  use_tabchars: false
+  separate_ctrl_name_with_space: false
+  separate_fn_name_with_space: false
+  dangle_parens: false
+  command_case: lower           # lowercase commands (cgal/upstream convention)
+  keyword_case: upper           # KEYWORDS like PUBLIC/PRIVATE/INTERFACE in caps
+
+lint:
+  # Whitelist the disables we explicitly accept.
+  disabled_codes:
+    - C0103   # invalid variable name — we use CGAL_/conformallab_ prefixes
+    - C0301   # line too long — handled by line_width, not as a lint error
+    - C0111   # missing docstring on a function — most of ours are obvious
+
+  # Maximum allowed nesting of conditional blocks.  3 is conservative;
+  # raise if we ever genuinely need deeper.
+  max_conditionals_custom_parser: 3

.codespellrc

@@ -0,0 +1,87 @@
+# conformallab++ codespell policy
+#
+# Driven by scripts/quality/codespell.sh.  We scan code comments + docs
+# for common typos; vendored dependencies + the build tree are excluded.
+#
+# False positives go into ignore-words-list (lowercase, comma-separated).
+# Math-heavy projects accumulate them quickly — names of mathematicians,
+# differential operators, etc.
+
+[codespell]
+skip = code/deps,build,build-*,build_T_*,test-reports,doc/doxygen,.git,*.svg,*.lock,*.pdf,*.png,*.jpg,Doxyfile,*.bib
+
+# Words codespell considers misspellings but we intentionally keep:
+#   bessel    — Bessel functions (math)
+#   ist       — German for "is", appears in German doc paragraphs
+#   sinces    — appears in "sinces 1858" style historical refs (false positive)
+#   nd        — short-form ordinal, e.g. "2nd"
+#   te        — appears in greek transliteration "θ → te"
+#   inout     — common parameter direction word
+#   nin       — math symbol ∉ accidental match
+#   numer     — "numerical/numerator" abbreviation in headers
+#   neet      — German "neet" / accidental matches
+#   anc       — appears in "anc(ient)" math literature refs
+#   sinks     — "sinks" can hit Sinkhorn
+ignore-words-list = bessel,ist,sinces,nd,te,inout,nin,numer,neet,anc,sinks,doubleClick,
+    centre,centres,centered,centering,centring,
+    behaviour,behaviours,behavioural,
+    analogue,analogues,
+    initialise,initialised,initialises,initialising,initialisation,
+    normalise,normalised,normalises,normalising,normalisation,
+    centralise,centralised,centralises,centralising,
+    serialise,serialised,serialises,serialising,serialisation,
+    parameterise,parameterised,parameterises,parameterising,
+    parametrise,parametrised,parametrises,parametrising,
+    realise,realised,realises,realising,realisation,
+    optimise,optimised,optimises,optimising,optimisation,
+    sanitise,sanitised,sanitises,sanitising,
+    generalise,generalised,generalises,generalising,
+    amortise,amortised,amortises,amortising,
+    factorise,factorised,factorises,factorising,
+    discretise,discretised,discretises,discretising,
+    summarise,summarised,summarises,summarising,
+    colour,colours,coloured,colouring,
+    artefact,artefacts,
+    iff,
+    dof,dofs,
+    browseable,
+    re-use,re-uses,re-used,re-using,
+    specialise,specialised,specialises,specialising,specialisation,specialisations,
+    visualise,visualised,visualises,visualising,visualisation,visualisations,
+    model,modeled,modelled,modelling,
+    minimise,minimised,minimises,minimising,minimisation,
+    maximise,maximised,maximises,maximising,maximisation,
+    organise,organised,organises,organising,organisation,
+    characterise,characterised,characterises,characterising,
+    emphasise,emphasised,emphasises,emphasising,
+    analyse,analysed,analyses,analysing,analyser,analysers,
+    organise,organisation,organisational,
+    parameterise,parameterisation,
+    centre,centred,centres,
+    catalogue,catalogues,
+    maths,
+    generalisation,generalisations,
+    realisation,realisations,
+    specialisation,specialisations,
+    visualisation,visualisations,
+    minimisation,maximisation,characterisation,
+    groupes,fuchsiens,théorie,théorème,
+    iff,
+    honour,honoured,honours,honouring,thead,optimiser,optimisers,
+    categorise,categorised,categorises,categorising,
+    optimisation,optimisations,
+    acknowledgement,acknowledgements,acknowledging,
+    neighbour,neighbours,neighbouring,neighboured,
+    labelled,labelling,labels,labelled,
+    fulfil,fulfils,fulfilled,fulfilling,
+    endcode,
+    deklaration,deklarationen,
+    recognise,recognised,recognises,recognising,recognisation,
+    signalled,signalling,
+    travelled,travelling,
+    cancelled,cancelling,
+    modelled,modelling
+
+# Words we explicitly DO want flagged (override the default skip list).
+# Keep empty for now; add as we hit real-but-not-flagged typos.
+builtin = clear,rare,informal,usage,code,en-GB_to_en-US,names

.editorconfig

@@ -0,0 +1,56 @@
+# conformallab++ EditorConfig
+#
+# Honoured natively by VSCode (with the EditorConfig extension), CLion,
+# Vim, Emacs, Sublime, …  Covers the basics that .clang-format /
+# .cmake-format don't catch (Markdown, Python, YAML, shell, JSON, …)
+# and acts as a cross-IDE fallback when clang-format isn't installed.
+#
+# Authoritative formatting for C++ source still comes from .clang-format;
+# this file just keeps the editor's defaults from fighting it.
+
+root = true
+
+[*]
+charset = utf-8
+end_of_line = lf
+insert_final_newline = true
+trim_trailing_whitespace = true
+indent_style = space
+indent_size = 4
+
+# C++ — match .clang-format
+[*.{h,hpp,cpp,c,cc}]
+indent_size = 4
+max_line_length = 100
+
+# CMake — match .cmake-format.yaml
+[{CMakeLists.txt,*.cmake}]
+indent_size = 4
+max_line_length = 100
+
+# Python — PEP-8 default
+[*.py]
+indent_size = 4
+max_line_length = 100
+
+# Shell — Google shell style
+[*.sh]
+indent_size = 4
+max_line_length = 100
+
+# YAML — community convention
+[*.{yml,yaml}]
+indent_size = 2
+
+# JSON
+[*.json]
+indent_size = 2
+
+# Markdown — preserve trailing spaces (used for line breaks); don't strip
+[*.md]
+trim_trailing_whitespace = false
+max_line_length = off
+
+# Makefiles must use tabs
+[Makefile]
+indent_style = tab

.gitea/docker/Dockerfile.ci-cpp

@@ -10,6 +10,7 @@ RUN apt-get update -qq && \
     curl -fsSL https://deb.nodesource.com/setup_20.x | bash - && \
     apt-get install -y --no-install-recommends \
       nodejs \
+      doxygen \
       cmake \
       build-essential \
       git \

.gitea/workflows/cpp-tests.yml

@@ -11,8 +11,8 @@ on:
 
 # ─────────────────────────────────────────────────────────────────────────────
 # Job 1 — test-fast
-#   Pure-math tests (Clausen, ImLi₂, Hyper-ideal Geometrie).
+#   Pure-math tests (Clausen, ImLi₂, Hyper-ideal geometry).
-#   Kein CGAL, kein Boost. Läuft auf ALLEN Branches in < 1 s.
+#   No CGAL, no Boost. Eigen + GTest only. Runs on ALL branches.
 # ─────────────────────────────────────────────────────────────────────────────
 jobs:
   test-fast:
@@ -27,7 +27,7 @@ jobs:
         run: cmake -S code -B build -DCMAKE_BUILD_TYPE=Release
 
       - name: Build
-        run: cmake --build build --target conformallab_tests -j$(nproc)
+        run: nice -n 19 cmake --build build --target conformallab_tests -j$(nproc)
 
       - name: Run tests
         run: >
@@ -35,7 +35,7 @@ jobs:
           --output-on-failure
           --output-junit test-results.xml
 
-      - name: Zusammenfassung
+      - name: Summary
         if: always()
         run: |
           if [ -f test-results.xml ]; then
@@ -48,36 +48,36 @@ jobs:
 
 # ─────────────────────────────────────────────────────────────────────────────
 # Job 2 — test-cgal
-#   Vollständige CGAL-Test-Suite (Phase 3–7, 158 Tests).
+#   Full CGAL test suite (Phase 3–7, 158 tests).
-#   Läuft nur auf main, dev und Pull Requests — nicht auf Feature-Branches.
+#   Runs ONLY on pull requests (not on direct pushes to dev/main).
-#   Startet erst nach erfolgreichem test-fast.
+#   Starts only after test-fast succeeds.
 #
-#   Boost-Install-Schritt: solange das Docker-Image noch kein libboost-dev
+#   Uses -DWITH_CGAL_TESTS=ON (not -DWITH_CGAL=ON) to avoid building
-#   enthält, wird es hier zur Laufzeit nachinstalliert (~15 s).
+#   Viewer/GLFW — the CI container has no wayland-scanner.
-#   Nach dem nächsten Image-Rebuild (Dockerfile bereits aktualisiert) wird
+#
-#   dieser Schritt zum No-Op.
+#   Boost (libboost-dev) is already present in the container since the image rebuild.
 # ─────────────────────────────────────────────────────────────────────────────
   test-cgal:
     needs: test-fast
-    if: >
+    if: github.event_name == 'pull_request'
-      github.ref == 'refs/heads/main' ||
-      github.ref == 'refs/heads/dev'  ||
-      github.event_name == 'pull_request'
     runs-on: eulernest
     container:
       image: git.eulernest.eu/conformallab/ci-cpp:latest
+      # Memory bumped from 1400m → 1600m to avoid OOM during CGAL header
+      # compilation on ARM64 (CGAL + Eigen templates allocate ~700 MB per
+      # cc1plus instance; -j1 leaves a small margin).
+      # memory-swap == memory disables swap entirely so OOM fails fast
+      # rather than thrashing on the SD card.
+      options: "--memory=1600m --memory-swap=1600m"
 
     steps:
       - uses: actions/checkout@v4
 
-      - name: Boost installieren (Übergang bis Image-Rebuild)
+      - name: Configure (WITH_CGAL_TESTS — no viewer, no wayland-scanner)
-        run: apt-get update -qq && apt-get install -y --no-install-recommends libboost-dev
+        run: cmake -S code -B build -DWITH_CGAL_TESTS=ON -DCMAKE_BUILD_TYPE=Release
-
-      - name: Configure (WITH_CGAL)
-        run: cmake -S code -B build -DWITH_CGAL=ON -DCMAKE_BUILD_TYPE=Release
 
       - name: Build CGAL-Tests
-        run: cmake --build build --target conformallab_cgal_tests -j$(nproc)
+        run: nice -n 19 cmake --build build --target conformallab_cgal_tests -j1
 
       - name: Run CGAL-Tests
         run: >
@@ -86,7 +86,7 @@ jobs:
           --output-on-failure
           --output-junit cgal-results.xml
 
-      - name: Zusammenfassung
+      - name: Summary
         if: always()
         run: |
           if [ -f cgal-results.xml ]; then
@@ -96,3 +96,67 @@ jobs:
             passed=$(( ${total:-0} - ${failed:-0} - ${skipped:-0} ))
             echo "CGAL  ▸ TOTAL ${total:-0} | PASSED $passed | FAILED ${failed:-0} | SKIPPED ${skipped:-0}"
           fi
+
+      # ── Structural gate: doc/api/tests.md totals match ctest reality ───
+      # Single source of truth for test counts (see doc/release-policy.md).
+      # Reuses the already-built ./build dir via BUILD_DIR env var, so this
+      # adds ~5 s on top of the existing CGAL job.
+      - name: Verify test-count consistency (doc/api/tests.md)
+        run: BUILD_DIR=build bash scripts/check-test-counts.sh
+
+      # ── Structural gate: end-to-end smoke (try_it.sh) ──────────────────
+      # The user-facing quick-start script: configure + build + run the
+      # full ctest + run the Euclidean example on a bundled mesh.  If
+      # this regresses, README quick-start instructions are broken.
+      # try_it.sh creates its own build-try/ — accept the ~3 min cost as
+      # the price of guaranteeing the documented workflow stays working.
+      - name: End-to-end smoke test (scripts/try_it.sh)
+        run: bash scripts/try_it.sh
+
+# ─────────────────────────────────────────────────────────────────────────────
+# Job 3 — quality-gates  (style + convention block)
+#
+# Cheap, deterministic checks that should never break unless a contributor
+# introduces a regression.  Each gate is a script under scripts/quality/
+# and exits 0 only when its tree is clean.  These ran for weeks locally
+# at zero findings before being promoted here.
+#
+# Tools installed at job-start (the ci-cpp image already has python3 +
+# bash; we add codespell + shellcheck on top).  Total wall-time: ~30 s
+# on the eulernest runner.
+#
+# Strictly required for merges into main/dev — a regression fails the PR.
+# ─────────────────────────────────────────────────────────────────────────────
+  quality-gates:
+    needs: test-fast
+    runs-on: eulernest
+    container:
+      image: git.eulernest.eu/conformallab/ci-cpp:latest
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install codespell + shellcheck (job-local)
+        run: |
+          apt-get update -qq
+          apt-get install -y --no-install-recommends \
+            codespell shellcheck
+
+      - name: License headers (every C++ source carries MIT SPDX)
+        run: bash scripts/quality/license-headers.sh
+
+      - name: CGAL conventions (6 rules over CGAL public headers)
+        run: python3 scripts/quality/cgal-conventions.py
+
+      - name: codespell (docs + source comments + script messages)
+        run: bash scripts/quality/codespell.sh
+
+      - name: shellcheck (scripts/**/*.sh, severity=warning, strict)
+        run: bash scripts/quality/shellcheck.sh --strict
+
+      - name: Summary
+        if: always()
+        run: |
+          echo "QUALITY ▸ all four gates passed."
+          echo "  see scripts/quality/README.md for the full catalogue"
+          echo "  (sanitizers, clang-tidy, coverage, etc. are local-only)"

.gitea/workflows/doc-build.yaml

@@ -0,0 +1,56 @@
+name: API Docs
+
+on:
+  push:
+    branches:
+      - main
+  pull_request:
+
+# ─────────────────────────────────────────────────────────────────────────────
+# Doc-build — informational only
+#
+# Generates Doxygen HTML from the public headers and reports warning
+# statistics.  Does NOT block merges: `continue-on-error: true` ensures
+# warnings or extraction issues never fail the CI gate.  When Doxygen
+# coverage is denser (Phase 8c), this job can be promoted to a hard
+# requirement and the HTML deployed to Pages.
+#
+# Note: Gitea Actions on GHES does not support `actions/upload-artifact@v4`,
+# so HTML artifact upload is intentionally omitted.  The warning summary
+# in the job log is the primary reviewer signal; reviewers who want the
+# HTML can rebuild it locally with `cmake --build build --target doc`.
+# ─────────────────────────────────────────────────────────────────────────────
+jobs:
+  doc-build:
+    if: github.event_name == 'pull_request'
+    runs-on: eulernest
+    container:
+      image: git.eulernest.eu/conformallab/ci-cpp:latest
+    continue-on-error: true   # never block the merge
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Generate API documentation
+        run: doxygen Doxyfile 2>&1 | tee doxygen.log
+
+      - name: Summarise warnings
+        if: always()
+        run: |
+          if [ -f doc/doxygen/doxygen-warnings.log ]; then
+            warn=$(wc -l < doc/doxygen/doxygen-warnings.log)
+            echo "DOC ▸ Doxygen warnings: $warn"
+            echo ""
+            echo "First 20 warnings:"
+            head -20 doc/doxygen/doxygen-warnings.log
+          else
+            echo "DOC ▸ No warning log produced — check that Doxyfile WARN_LOGFILE points to doc/doxygen/doxygen-warnings.log"
+          fi
+
+      - name: Report HTML output
+        if: always()
+        run: |
+          if [ -d doc/doxygen/html ]; then
+            files=$(find doc/doxygen/html -type f | wc -l)
+            size=$(du -sh doc/doxygen/html | cut -f1)
+            echo "DOC ▸ HTML output: $files files, $size total"
+          fi

.gitea/workflows/doxygen-pages.yml

@@ -0,0 +1,115 @@
+name: Doxygen → Codeberg Pages
+
+# Auto-publish Doxygen HTML to https://tmoussa.codeberg.page/ConformalLabpp/
+# every time the public API or docs source changes on main.
+#
+# Pattern: mirrors mirror-to-codeberg.yml — reuses the existing
+# CODEBERG_TOKEN secret + HTTPS push.  No new secret setup required.
+#
+# Trigger: push to main that touches code/include/**, Doxyfile, the
+# filter script, doc/**/*.md, README.md, or this workflow file.  Also
+# manually triggerable via workflow_dispatch.
+
+on:
+  push:
+    branches:
+      - main
+    paths:
+      - "code/include/**"
+      - "Doxyfile"
+      - "scripts/doxygen-md-filter.sh"
+      - "doc/**/*.md"
+      - "README.md"
+      - "CLAUDE.md"
+      - ".gitea/workflows/doxygen-pages.yml"
+  workflow_dispatch: {}
+
+jobs:
+  publish:
+    runs-on: eulernest
+    container:
+      image: git.eulernest.eu/conformallab/ci-cpp:latest
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Configure CMake (Doxygen target only — no compiler needed)
+        run: cmake -S code -B build
+
+      - name: Build Doxygen HTML
+        run: |
+          cmake --build build --target doc
+          test -f doc/doxygen/html/index.html
+          warnings=$(wc -l < doc/doxygen/doxygen-warnings.log)
+          echo "DOC ▸ Doxygen warnings: $warnings"
+          if [ "$warnings" -gt 0 ]; then
+            echo "::warning::Doxygen produced $warnings warning(s) — review doc/doxygen/doxygen-warnings.log"
+            head -30 doc/doxygen/doxygen-warnings.log
+          fi
+
+      - name: Enforce Doxygen coverage 100%
+        # Coverage is measured against every public symbol under
+        # code/include/ (the `detail::` namespaces are excluded).  As of
+        # the `docs/doxygen-coverage-100` PR the baseline is 100 %, so
+        # the gate fires only on regressions.
+        run: bash scripts/doxygen-coverage.sh --threshold 100
+
+      - name: Regenerate doc/api/headers.md from XML
+        run: |
+          python3 scripts/gen-headers-md.py
+          # If the auto-generated headers.md drifted from main, note it.
+          # This job runs on every main push so a drift only persists
+          # for the duration of one push — the next push that lands
+          # will fold the new headers.md back into main (via the
+          # codeberg pages branch).  For deterministic regeneration
+          # within main itself, run `bash scripts/regen-docs.sh`
+          # locally before pushing.
+          if ! git diff --quiet -- doc/api/headers.md; then
+            echo "::warning::doc/api/headers.md drifted — run scripts/regen-docs.sh locally and commit before next push"
+            git --no-pager diff -- doc/api/headers.md | head -30
+          fi
+
+      - name: Publish HTML to codeberg pages branch
+        env:
+          CODEBERG_TOKEN: ${{ secrets.CODEBERG_TOKEN }}
+        run: |
+          set -eu
+          # Build the publish payload in a clean scratch dir so the
+          # orphan branch contains only the reviewer hub + Doxygen
+          # output (and a marker README), never any build/source
+          # artefacts.
+          publish_dir=$(mktemp -d)
+          cp -r doc/doxygen/html/. "$publish_dir/"
+
+          # ── Reviewer hub override ─────────────────────────────────
+          # If doc/reviewer/hub.html is present, install it as the
+          # publish landing page and demote the auto-generated Doxygen
+          # index to /doxygen.html.  The hub is hand-curated and lives
+          # under source control; this step keeps it visible after
+          # every push to main, surviving the auto-publish cycle.
+          if [ -f doc/reviewer/hub.html ]; then
+              mv "$publish_dir/index.html" "$publish_dir/doxygen.html"
+              cp doc/reviewer/hub.html "$publish_dir/index.html"
+              echo "DOC ▸ reviewer hub installed; Doxygen index now at /doxygen.html"
+          fi
+
+          cat > "$publish_dir/README.txt" <<EOF
+          conformallab++ — Doxygen HTML API documentation + reviewer hub.
+          Auto-generated by .gitea/workflows/doxygen-pages.yml from
+          commit ${GITHUB_SHA:-$(git rev-parse HEAD)} on $(date -Iseconds).
+          Source: https://codeberg.org/TMoussa/ConformalLabpp
+          Reviewer hub: doc/reviewer/hub.html (in-repo)
+          Doxygen index: /doxygen.html
+          EOF
+
+          cd "$publish_dir"
+          git init -q -b pages
+          git config user.email "ci@eulernest"
+          git config user.name  "conformallab CI"
+          git add -A
+          git commit -q -m "Auto-publish: Doxygen HTML for ${GITHUB_SHA:-HEAD}"
+          # Force-push: the pages branch is a publish target, history
+          # is not interesting (we only ever serve the latest snapshot).
+          git push -f \
+            "https://TMoussa:${CODEBERG_TOKEN}@codeberg.org/TMoussa/ConformalLabpp.git" \
+            pages:pages

.gitea/workflows/markdown-links.yml

@@ -0,0 +1,40 @@
+name: Markdown link check
+
+# Verify every internal markdown link in the repo resolves to an existing
+# file (or anchor).  External http(s) links are also probed but with a
+# loose timeout — flaky third-party hosts must not break our CI.
+#
+# Trigger: PRs that touch any *.md file, plus a weekly cron so external
+# link rot is caught even when nobody is editing docs.
+
+on:
+  pull_request:
+    paths:
+      - "**/*.md"
+      - ".gitea/workflows/markdown-links.yml"
+  push:
+    branches:
+      - main
+    paths:
+      - "**/*.md"
+      - ".gitea/workflows/markdown-links.yml"
+  schedule:
+    - cron: "0 5 * * 1"   # Monday 05:00 UTC weekly link-rot check
+  workflow_dispatch: {}
+
+jobs:
+  check:
+    runs-on: eulernest
+    container:
+      image: git.eulernest.eu/conformallab/ci-cpp:latest
+
+    steps:
+      - uses: actions/checkout@v4
+
+      # ── Pure-python internal link check (no external network needed) ────
+      # We use the same logic that found the 2 broken links before the
+      # reviewer meeting: parse every [text](path) link, check that the
+      # target file exists relative to the source file's directory.  Skips
+      # http(s)://, mailto:, and pure-anchor (#fragment) links.
+      - name: Internal link check (all *.md files)
+        run: python3 scripts/check-markdown-links.py

.gitea/workflows/mirror-to-codeberg.yml

@@ -4,7 +4,6 @@ on:
   push:
     branches:
       - main
-      - dev
 
 jobs:
   mirror:
@@ -14,10 +13,11 @@ jobs:
       - name: Mirror all branches to Codeberg
         env:
           CODEBERG_TOKEN: ${{ secrets.CODEBERG_TOKEN }}
+          GITEA_MIRROR_TOKEN:  ${{ secrets.MIRROR_TOKEN }}
         run: |
           git clone --bare \
-            https://oauth2:${GITHUB_TOKEN}@git.eulernest.eu/conformallab/ConformalLabpp.git \
+            https://oauth2:${GITEA_MIRROR_TOKEN}@git.eulernest.eu/conformallab/ConformalLabpp.git \
             repo.git
           cd repo.git
           git push --mirror \
-            https://TMoussa:${CODEBERG_TOKEN}@codeberg.org/TMoussa/ConformalLabpp.git
+            https://TMoussa:${CODEBERG_TOKEN}@codeberg.org/TMoussa/ConformalLabpp.git

.gitea/workflows/perf-compile-time.yml

@@ -0,0 +1,175 @@
+name: Compile-time perf bench
+
+# Cross-platform compile-time benchmark.  Validates the predictions
+# made in doc/architecture/compile-time.md against the eulernest CI
+# runner (Linux + g++ on ARM64).
+#
+# Specifically tests whether:
+#   1. FAST_TEST_BUILD=ON delivers the ~40 % wall-time reduction on
+#      Linux + g++ that was predicted from `-ftime-trace` profiling
+#      (recall: on Apple clang + Apple M1 it was net-neutral).
+#   2. ccache hit rate is in the predicted 80%+ range on a warm
+#      rerun (where the macOS-local hit rate was 0 % due to
+#      Apple-clang + PCH friction).
+#
+# When run:
+#   * push to main (after PR #19 lands)
+#   * workflow_dispatch (manual trigger for ad-hoc verification)
+#
+# NOT run on every PR — this is a perf data-collection job, not a
+# correctness gate.  Pollutes the summary with timings but does not
+# block merges.
+
+on:
+  push:
+    branches:
+      - main
+    paths:
+      - "code/CMakeLists.txt"
+      - "code/tests/**/CMakeLists.txt"
+      - "code/include/**"
+      - ".gitea/workflows/perf-compile-time.yml"
+  workflow_dispatch: {}
+
+jobs:
+  compile-time-matrix:
+    runs-on: eulernest
+    container:
+      image: git.eulernest.eu/conformallab/ci-cpp:latest
+      options: "--memory=2400m --memory-swap=2400m"
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install ccache (idempotent)
+        run: |
+          which ccache >/dev/null 2>&1 || apt-get install -y --no-install-recommends ccache
+
+      # ─── Run 1: baseline (PCH OFF, Unity OFF, ccache cleared) ──────
+      - name: "Run 1: cold baseline (no PCH, no Unity, no ccache)"
+        run: |
+          ccache -C >/dev/null 2>&1 || true
+          rm -rf build-baseline
+          cmake -S code -B build-baseline -G Ninja \
+              -DWITH_CGAL_TESTS=ON \
+              -DCONFORMALLAB_USE_PCH=OFF \
+              -DCMAKE_UNITY_BUILD=OFF \
+              -DCONFORMALLAB_USE_CCACHE=OFF
+          start=$(date +%s)
+          nice -n 19 cmake --build build-baseline --target conformallab_cgal_tests -j1
+          end=$(date +%s)
+          echo "PERF baseline_wall=$((end - start)) s"
+          echo "PERF_BASELINE_WALL=$((end - start))" >> $GITHUB_ENV
+
+      # ─── Run 2: PCH only ──────────────────────────────────────────
+      - name: "Run 2: PCH only (Unity off, ccache off)"
+        run: |
+          ccache -C >/dev/null 2>&1 || true
+          rm -rf build-pch
+          cmake -S code -B build-pch -G Ninja \
+              -DWITH_CGAL_TESTS=ON \
+              -DCONFORMALLAB_USE_PCH=ON \
+              -DCMAKE_UNITY_BUILD=OFF \
+              -DCONFORMALLAB_USE_CCACHE=OFF
+          start=$(date +%s)
+          nice -n 19 cmake --build build-pch --target conformallab_cgal_tests -j1
+          end=$(date +%s)
+          echo "PERF pch_only_wall=$((end - start)) s"
+          echo "PERF_PCH_WALL=$((end - start))" >> $GITHUB_ENV
+
+      # ─── Run 3: default (PCH + Unity Build + #6 Dense→Core) ───────
+      - name: "Run 3: default config (PCH + Unity + Dense→Core)"
+        run: |
+          ccache -C >/dev/null 2>&1 || true
+          rm -rf build-default
+          cmake -S code -B build-default -G Ninja \
+              -DWITH_CGAL_TESTS=ON \
+              -DCONFORMALLAB_USE_CCACHE=OFF
+          start=$(date +%s)
+          nice -n 19 cmake --build build-default --target conformallab_cgal_tests -j1
+          end=$(date +%s)
+          echo "PERF default_wall=$((end - start)) s"
+          echo "PERF_DEFAULT_WALL=$((end - start))" >> $GITHUB_ENV
+
+      # ─── Run 4: + FAST_TEST_BUILD (-O0 -g) ────────────────────────
+      - name: "Run 4: default + FAST_TEST_BUILD=ON (-O0 -g for tests)"
+        run: |
+          ccache -C >/dev/null 2>&1 || true
+          rm -rf build-fast
+          cmake -S code -B build-fast -G Ninja \
+              -DWITH_CGAL_TESTS=ON \
+              -DCONFORMALLAB_FAST_TEST_BUILD=ON \
+              -DCONFORMALLAB_USE_CCACHE=OFF
+          start=$(date +%s)
+          nice -n 19 cmake --build build-fast --target conformallab_cgal_tests -j1
+          end=$(date +%s)
+          echo "PERF fast_test_wall=$((end - start)) s"
+          echo "PERF_FAST_WALL=$((end - start))" >> $GITHUB_ENV
+
+      # ─── Run 5: ccache hit-rate validation ─────────────────────────
+      - name: "Run 5: ccache hit-rate (rebuild build-default)"
+        run: |
+          ccache -C >/dev/null 2>&1 || true
+          ccache --zero-stats >/dev/null
+          # First rebuild: populate ccache.
+          rm -rf build-cc
+          cmake -S code -B build-cc -G Ninja \
+              -DWITH_CGAL_TESTS=ON \
+              -DCONFORMALLAB_USE_CCACHE=ON
+          nice -n 19 cmake --build build-cc --target conformallab_cgal_tests -j1 >/dev/null
+          ccache_first=$(ccache -s 2>&1 | grep -E "^\s*Hits" | head -1 | awk '{print $2}')
+          # Second rebuild: expect cache hits.
+          rm -rf build-cc-warm
+          cmake -S code -B build-cc-warm -G Ninja \
+              -DWITH_CGAL_TESTS=ON \
+              -DCONFORMALLAB_USE_CCACHE=ON
+          start=$(date +%s)
+          nice -n 19 cmake --build build-cc-warm --target conformallab_cgal_tests -j1
+          end=$(date +%s)
+          warm_wall=$((end - start))
+          ccache_stats=$(ccache -s 2>&1 | grep -E "Hits|Misses" | head -4)
+          echo "── ccache stats after warm rebuild ──"
+          echo "$ccache_stats"
+          echo "PERF ccache_warm_wall=${warm_wall} s"
+          echo "PERF_CCACHE_WARM_WALL=$warm_wall" >> $GITHUB_ENV
+
+      # ─── Test correctness (last gate; perf data already collected) ─
+      - name: Verify all configs produced working binaries
+        if: always()
+        run: |
+          for build in build-baseline build-pch build-default build-fast; do
+              if [ -d "$build" ]; then
+                  ctest --test-dir "$build" -R "^cgal\." --output-on-failure --timeout 120 \
+                      | tail -3
+              fi
+          done
+
+      # ─── Final summary ─────────────────────────────────────────────
+      - name: Compile-time perf summary
+        if: always()
+        run: |
+          echo "══════════════════════════════════════════════════════"
+          echo "  COMPILE-TIME PERF BENCH — Linux ARM64 / g++ / -j1"
+          echo "══════════════════════════════════════════════════════"
+          printf "  %-30s  %4s s\n" "Run 1: cold baseline"          "${PERF_BASELINE_WALL:-?}"
+          printf "  %-30s  %4s s\n" "Run 2: + PCH"                  "${PERF_PCH_WALL:-?}"
+          printf "  %-30s  %4s s\n" "Run 3: + PCH + Unity (default)" "${PERF_DEFAULT_WALL:-?}"
+          printf "  %-30s  %4s s\n" "Run 4: + FAST_TEST_BUILD"      "${PERF_FAST_WALL:-?}"
+          printf "  %-30s  %4s s\n" "Run 5: + ccache warm rerun"    "${PERF_CCACHE_WARM_WALL:-?}"
+          echo "──────────────────────────────────────────────────────"
+          echo "Predictions to validate vs Apple-M1 baseline:"
+          echo "  ┃ FAST_TEST_BUILD: expected ~40 % faster than default"
+          echo "  ┃ ccache warm:     expected ≤ 10 s (vs Apple's 55 s)"
+          echo "──────────────────────────────────────────────────────"
+          # Compute relative deltas
+          if [ -n "${PERF_DEFAULT_WALL:-}" ] && [ -n "${PERF_FAST_WALL:-}" ]; then
+              pct=$(awk -v d="${PERF_DEFAULT_WALL}" -v f="${PERF_FAST_WALL}" \
+                  'BEGIN { printf "%.0f", 100.0 * (d - f) / d }')
+              echo "  Δ FAST_TEST_BUILD vs default: ${pct} % wall reduction"
+          fi
+          if [ -n "${PERF_DEFAULT_WALL:-}" ] && [ -n "${PERF_CCACHE_WARM_WALL:-}" ]; then
+              pct=$(awk -v d="${PERF_DEFAULT_WALL}" -v c="${PERF_CCACHE_WARM_WALL}" \
+                  'BEGIN { printf "%.0f", 100.0 * (d - c) / d }')
+              echo "  Δ ccache warm vs default:     ${pct} % wall reduction"
+          fi
+          echo "══════════════════════════════════════════════════════"

.gitignore

@@ -0,0 +1,33 @@
+# macOS
+.DS_Store
+.AppleDouble
+.LSOverride
+
+# Build directories
+build/
+build-*/
+build_*/
+code/build*/
+
+# CMake
+CMakeCache.txt
+CMakeFiles/
+cmake_install.cmake
+CTestTestfile.cmake
+
+# Test output
+*.xml
+Testing/
+
+# IDE
+.idea/
+.vscode/
+*.user
+*.suo
+
+# Claude Code worktrees
+.claude/
+
+# Doxygen output
+doc/doxygen/
+*.dox.tmp

CHANGELOG.md

@@ -0,0 +1,241 @@
+# Changelog
+
+All notable changes to **conformallab++** are recorded here.  Format
+follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/); the
+project uses [Semantic Versioning](https://semver.org).
+
+---
+
+## [0.10.0] — 2026-05-26
+
+The **"reviewer-ready"** release.  Three PRs (#17 + #18 + #19, 13
+thematic commits total) landed: a 100 %-Doxygen-covered public API,
+a 14-gate structural quality suite (4 of them required CI), a
+researcher-targeted reviewer materials package, the `output_uv_map`
+named parameter extended to four of the five DCE solvers, six new
+roadmap phases from a full Java-library scan, thirteen new Tier-1/2
+literature citations, three RESEARCH-only phases with acceptance
+criteria, and a six-mode compile-time workflow matrix.
+
+### Added — reviewer materials (PR #19)
+
+* `doc/reviewer/{briefing,questions,agenda,README}.md` — one-page
+  reviewer briefing + seven scoped questions (Q1–Q2 research-track
+  alignment; Q3–Q4 porting decisions; Q5–Q6 process; Q7 the "no"
+  question) + internal meeting agenda + landing index.
+* `doc/reviewer/hub.html` — hand-curated reviewer landing page,
+  in-repo so the publish URL survives every merge.
+* `code/deps/THIRD-PARTY-LICENSES.md` — per-vendored-dep SPDX with
+  MIT-compatibility analysis (CGAL LGPL §3 vs §4 distinction).
+* `doc/architecture/dependencies.md` — required vs optional deps;
+  standalone-verification recipe.
+
+### Added — new roadmap content (PR #19)
+
+* Six new phases from full Java-library scan: Phase 9d (cones),
+  9d.4 (variational Möbius centring), 9e (circle-pattern layout),
+  10d (Koebe circle-domain), 10e (quasi-isothermic, ~800 lines, 6
+  classes), 10f (Koebe polyhedra), 10g (cyclic-symmetry quotients).
+* Three RESEARCH phases with acceptance criteria: 9d.2 (non-Euclidean
+  cone extensions), 9f (polygon Laplacian on non-triangular meshes,
+  no Java parent), 10c′ (Koebe polyhedron rigidity).
+* 13 new Tier-1/Tier-2 citations in `doc/math/references.md`.
+
+### Added — compile-time workflow matrix (PR #19)
+
+* PCH + Unity Build defaults: CGAL test wall-time **78 s → 55 s**
+  (−30 %), CPU time 676 s → 167 s (−75 %).
+* Five new opt-in workflow modes (`BUILD_TESTING=OFF`,
+  `CONFORMALLAB_HEADERS_CHECK`, `CONFORMALLAB_DEV_BUILD`,
+  `CONFORMALLAB_FAST_TEST_BUILD`, `CONFORMALLAB_USE_CCACHE`).
+* `doc/architecture/compile-time.md` — full measurement + workflow
+  matrix + macOS-vs-Linux honesty notes.
+* `.gitea/workflows/perf-compile-time.yml` — Linux CI bench.
+
+### Added — output_uv_map covers 4 of 5 DCE entries (PR #19)
+
+* `CGAL::discrete_inversive_distance_map` honours `output_uv_map`
+  via Bowers-Stephenson edge-length reconstruction.
+* `CGAL::discrete_circle_packing_euclidean` rejects `output_uv_map`
+  with a clear `std::runtime_error` (face-based DOFs, Phase 9c).
+
+### Added — structural quality gates (PR #18)
+
+Four scripts promoted to required CI: `license-headers.sh`,
+`cgal-conventions.py`, `codespell.sh`, `shellcheck.sh --strict`.
+Seven additional local-only gates: clang-format, cmake-format,
+cppcheck, sanitizers (ASan + UBSan), clang-tidy, multi-compiler,
+reproducible-build, CGAL-version-matrix.
+
+### Added — Doxygen 100 % public-API coverage (PR #17)
+
+* Doxygen coverage: **24 % → 100 %** (396/396 public symbols).
+* Fixed `EXCLUDE_PATTERNS` bug that previously silently excluded
+  every `.hpp`/`.h` — pre-fix HTML had ~0 % API surface.
+* MathJax + CGAL `\cgalParam*` aliases.
+* New scripts: `scripts/doxygen-coverage.sh` (CI-gateable),
+  `scripts/gen-headers-md.py` (auto-regenerates `doc/api/headers.md`).
+
+### Changed
+
+* Three headers `<Eigen/Dense>` → `<Eigen/Core>` (none use Eigen
+  decompositions): `projective_math.hpp`,
+  `hyper_ideal_visualization_utility.hpp`, `mesh_utils.hpp`.
+* `doc/api/tests.md` — CGAL suite 234 → 236 tests.
+* `code/.gitignore` — un-ignore `code/deps/THIRD-PARTY-LICENSES.md`.
+
+### Numbers at release
+
+* 259 / 259 tests pass, 0 skipped.
+* 100 % Doxygen coverage on public API, 0 warnings.
+* 14 / 15 quality gates green, 1 SKIP (no CGAL tarballs locally).
+* CI build wall: ~55 s on Apple M1 (−30 % vs v0.9.0).
+* 13 Tier-1 / Tier-2 literature citations integrated.
+
+---
+
+## [0.9.0] — 2026-05-22
+
+The “DCE-complete + CGAL-surface-complete” release.  Two new discrete-
+conformal models, the analytic-Hessian optimisation for HyperIdeal, the
+CGAL public API surface for all five models, and a full documentation
+audit that corrects four pre-existing port-vs-research mis-labels.
+
+### Added — new functionals (Phase 9a)
+
+* `code/include/cp_euclidean_functional.hpp` —
+  **CP-Euclidean** functional (face-based circle packing),
+  Bobenko-Pinkall-Springborn 2010.  Direct port of
+  `CPEuclideanFunctional.java` (260 Java lines + 88-line test).
+  Analytic 2×2-per-edge Hessian `h_jk = sin θ / (cosh Δρ − cos θ)`.
+* `code/include/inversive_distance_functional.hpp` —
+  **Inversive-Distance** functional (vertex-based, Luo 2004 + Glickenstein
+  2011).  No Java original — implemented from the literature with
+  Bowers-Stephenson 2004 initialisation.  Cross-validated against the
+  Euclidean functional at the natural initial geometry (Glickenstein §5).
+
+### Added — Newton solvers (Phase 9a-Newton)
+
+* `newton_cp_euclidean()` — uses the analytic Hessian.
+* `newton_inversive_distance()` — uses FD Hessian; analytic via
+  Glickenstein 2011 eq. (4.6) tracked in `research-track.md` as
+  Phase 9a.2-analytic.
+
+### Added — Hessian optimisation (Phase 9b)
+
+* `hyper_ideal_hessian_block_fd()` — per-face 6×6 block-local Hessian
+  for HyperIdeal.  **96.5× speed-up measured on a 200-face mesh
+  (V=202, 603 DOFs)**, full-FD 226 ms → block-FD 2.3 ms.
+* Java parity note: `HyperIdealFunctional.java:295-298` declares
+  `hasHessian() == false`; both FD variants are conformallab++
+  research extensions beyond the Java port.
+
+### Added — CGAL public API surface (Phase 8b-Lite)
+
+* `<CGAL/Discrete_conformal_map.h>` extended with
+  `discrete_conformal_map_spherical()` and
+  `discrete_conformal_map_hyper_ideal()`.
+* `<CGAL/Discrete_circle_packing.h>` — `Default_cp_euclidean_traits` +
+  `discrete_circle_packing_euclidean()`.
+* `<CGAL/Discrete_inversive_distance.h>` — `Default_inversive_distance_traits`
+  + `discrete_inversive_distance_map()`.
+* `<CGAL/Conformal_layout.h>` — thin CGAL-namespace re-exports of
+  `euclidean_layout`, `spherical_layout`, `hyper_ideal_layout`.
+
+All five DCE models are now reachable from a single
+`#include <CGAL/Discrete_*.h>`.
+
+### Added — documentation
+
+* `doc/roadmap/research-track.md` — new consolidated catalogue of
+  every conformallab++ item that goes beyond the Java port, with full
+  literature citations and acceptance criteria.  Includes the
+  Phase 9b-analytic plan (Schläfli 1858 + Springborn 2020 §4 +
+  Cho-Kim 1999 + Glickenstein 2011 §4).
+* `doc/architecture/phase-9a-validation.md` — line-by-line mapping
+  CPEuclideanFunctional.java ↔ C++ port, plus three special-case
+  verifications of Luo’s edge-length formula.
+* `doc/roadmap/phases.md` — Phase 9 split into 9a.1 (Java port) /
+  9a.2 (research) / 9b (research); new Phase 11+ section with
+  optional Schottky uniformisation and Riemann-map sub-packages.
+* `doc/math/references.md` — five new primary literature entries
+  (Bowers-Stephenson 2004, Glickenstein 2011, BPS 2010,
+  Schläfli 1858/60, plus a reframed Luo 2004 entry).
+
+### Changed
+
+* **Four port-vs-research mis-labels** corrected (full audit
+  documented in `research-track.md`):
+  - `InversiveDistanceFunctional.java` does not exist in the Java
+    repo; the C++ implementation is research, not a port.
+  - HyperIdeal Hessian: Java has `hasHessian()==false`; C++ Hessians
+    are research, not ports.
+  - `add-inversive-distance.md` tutorial rewritten end-to-end.
+  - `references.md` and `java-parity.md` reframed.
+* `Discrete_conformal_map.h` (Phase 8a MVP wrapper) now deduces the
+  kernel from `TriangleMesh::Point` via `CGAL::Kernel_traits` rather
+  than hard-coding `Simple_cartesian<double>`.  Regression-guarded by
+  `KernelIsDeducedFromMeshPointType` test.
+
+### Removed
+
+* Three stale stub test files in `code/tests/` (15 GTEST_SKIPs total):
+  - `test_spherical_functional.cpp`
+  - `test_hyper_ideal_functional.cpp`
+  - `test_hyper_ideal_hyperelliptic_utility.cpp`
+  They referenced a "HDS port (Phase 4)" that never happened —
+  CoHDS was intentionally replaced by `CGAL::Surface_mesh`, and the
+  functional tests live in `code/tests/cgal/test_*_functional.cpp`.
+
+### CI / Infrastructure
+
+* `.gitea/workflows/cpp-tests.yml` — test-cgal memory fixed
+  (1400→1600 MB, `-j2 → -j1`).  Addresses OOM on ARM64 runner.
+* `.gitea/workflows/doc-build.yaml` — soft-fail Doxygen job
+  (no merge-blocking).
+* `Doxyfile` + CMake `doc` target — `cmake --build build --target doc`.
+* 12 macOS Finder-duplicate files removed from `code/include/`.
+
+### Test counts
+
+```
+v0.7.0:  176 CGAL + 36 non-CGAL = 212 total,  13 skipped (HDS stubs)
+v0.9.0:  227 CGAL + 23 non-CGAL = 250 total,   0 skipped   (+38 net, +51 CGAL)
+```
+
+Non-CGAL count dropped from 36 → 23 because three stale HDS-port stubs
+were removed (see "Removed" above) — the functionality is fully covered
+in the CGAL test suite where it actually lives.
+
+Five test suites added: `CGALConformalTraits`, `CGALDiscreteConformalMap`,
+`CPEuclideanFunctional`, `InversiveDistanceFunctional`, `HyperIdealHessian`,
+`NewtonPhase9a`, `CGALPhase8bLite`.
+
+---
+
+## [0.7.0] — 2026-05-18
+
+The “mathematician-ready” release.  See the v0.7.0 announcement in
+README.md (legacy) or `CITATION.cff` for the corresponding citation
+entry.  Phases 1–7 complete: three DCE geometry modes (Euclidean /
+Spherical / HyperIdeal), Newton solver, BFS-trilateration layout,
+Gauss-Bonnet, tree-cotree cut graph, Möbius holonomy, period matrix
+for genus 1, fundamental domain (genus 1), texture atlas.
+
+---
+
+## How to update this file
+
+Every new release adds a new top-level section above the previous one.
+For non-trivial PRs that don't trigger a release, add an entry under
+an `[Unreleased]` section at the top; promote it to the next release
+header at tag time.
+
+Categories (Keep-A-Changelog convention):
+
+* **Added** — new features / files / public APIs.
+* **Changed** — behaviour-altering changes to existing features.
+* **Deprecated** — features still present but slated for removal.
+* **Removed** — deleted features / files.
+* **Fixed** — bug fixes.
+* **Security** — security-relevant fixes.

CITATION.cff

@@ -0,0 +1,68 @@
+cff-version: 1.2.0
+message: "If you use this software in your research, please cite it as below."
+
+authors:
+  - family-names: Moussa
+    given-names: Tarik
+    email: Tarik.moussa95@gmail.com
+
+title: "conformallab++"
+version: 0.10.0
+date-released: 2026-05-26
+url: "https://codeberg.org/TMoussa/ConformalLabpp"
+repository-code: "https://codeberg.org/TMoussa/ConformalLabpp"
+license: MIT
+
+abstract: >
+  conformallab++ is a C++17 implementation of discrete conformal maps on
+  triangulated surfaces, covering Euclidean, Spherical, and Hyper-ideal geometry
+  modes. It provides a Newton solver for discrete conformal equivalence (DCE),
+  tree-cotree cut graphs, Möbius holonomy, period matrix computation with
+  SL(2,ℤ) reduction, and fundamental domain construction. The long-term goal is
+  a CGAL package for discrete conformal geometry.
+
+keywords:
+  - discrete conformal geometry
+  - conformal maps
+  - surface parameterization
+  - period matrix
+  - Teichmüller theory
+  - CGAL
+  - C++
+
+references:
+  - type: thesis
+    authors:
+      - family-names: Sechelmann
+        given-names: Stefan
+    title: >
+      Variational Methods for Discrete Surface Parameterization:
+      Applications and Implementation
+    institution:
+      name: Technische Universität Berlin
+    year: 2016
+    doi: 10.14279/depositonce-5415
+    notes: "Primary algorithmic source for this implementation"
+
+  - type: article
+    authors:
+      - family-names: Springborn
+        given-names: Boris
+    title: "Ideal Hyperbolic Polyhedra and Discrete Uniformization"
+    journal: "Discrete & Computational Geometry"
+    year: 2020
+    doi: 10.1007/s00454-019-00132-8
+    notes: "Mathematical basis for the HyperIdeal geometry mode"
+
+  - type: article
+    authors:
+      - family-names: Bobenko
+        given-names: Alexander I.
+      - family-names: Springborn
+        given-names: Boris A.
+    title: >
+      Variational Principles for Circle Patterns and Koebe's Theorem
+    journal: "Transactions of the American Mathematical Society"
+    year: 2004
+    doi: 10.1090/S0002-9947-03-03239-2
+    notes: "Variational framework underlying all three geometry modes"

CLAUDE.md

@@ -0,0 +1,401 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Project purpose and long-term goal
+
+conformallab++ is a C++17 reimplementation of [ConformalLab](https://github.com/varylab/conformallab) — Stefan Sechelmann's Java research library for discrete conformal geometry (TU Berlin, ~850 commits, v1.0.0 2018). The algorithmic foundation is his dissertation:
+
+> Stefan Sechelmann — *Variational Methods for Discrete Surface Parameterization: Applications and Implementation*, TU Berlin 2016.
+> DOI: [10.14279/depositonce-5415](https://depositonce.tu-berlin.de/items/8e2988b2-d991-45b5-aad5-9fb7988f3b2f) · CC BY-SA 4.0
+
+**The long-term goal is a CGAL package** — a submission to the CGAL library that brings discrete conformal maps (hyper-ideal, spherical, Euclidean) to the CGAL ecosystem using `CGAL::Surface_mesh` as the underlying halfedge data structure, with a traits-class design compatible with arbitrary CGAL-conforming mesh types.
+
+The project has four distinct phase blocks (updated 2026-05-22):
+- **Phase 1–7 (done, v0.7.0):** Direct port of the Java library algorithms to C++.
+- **Phase 8a MVP + 8b-Lite (done, v0.9.0):** CGAL public-API surface for all five DCE models via `<CGAL/Discrete_*.h>`.  Phase 8a.2 (generic FaceGraph), 8c (manuals), 8d (CGAL-test-format), 8e (YAML pipeline) deferred on-demand.
+- **Phase 9a + 9b (done, v0.9.0):** Two new functionals (CP-Euclidean port, Inversive-Distance research), two new Newton solvers, block-FD HyperIdeal Hessian.
+- **Phase 9b-analytic + 9c (planned):** Full analytic HyperIdeal Hessian via Schläfli identity (research, see `doc/roadmap/research-track.md`); 4g-polygon fundamental domain for genus g > 1 (mixed port + research).
+- **Phase 10+ (research):** Holomorphic differentials, Siegel period matrix Ω ∈ H_g, full uniformization for genus g ≥ 2.
+
+## Language
+
+**All code, comments, documentation, commit messages, and test descriptions must be in English.** The project is intended for international collaboration and CGAL submission. Existing German-language comments in older files should be replaced with English when editing those files.
+
+## Build commands
+
+All source lives under `code/`. Three build modes:
+
+```bash
+# Mode 1 — fast tests, no CGAL, no Boost, no display (CI default)
+cmake -S code -B build
+cmake --build build --target conformallab_tests -j$(nproc)
+ctest --test-dir build --output-on-failure
+
+# Mode 2 — CGAL tests, headless (CI full, requires Boost headers only)
+#   macOS: brew install boost    Linux: apt install libboost-dev
+cmake -S code -B build -DWITH_CGAL_TESTS=ON
+cmake --build build --target conformallab_cgal_tests -j$(nproc)
+ctest --test-dir build -R "^cgal\." --output-on-failure
+
+# Mode 3 — full local build: CLI app + viewer + examples (requires Wayland/X11)
+cmake -S code -B build -DWITH_CGAL=ON
+cmake --build build -j$(nproc)
+```
+
+`-DWITH_CGAL=ON` automatically enables `-DWITH_VIEWER=ON`, which pulls in GLFW and requires `wayland-scanner`. Never use this in headless CI.
+
+### Running a single test
+
+```bash
+# By GTest suite/test name
+./build/conformallab_cgal_tests --gtest_filter="NewtonSolver*"
+./build/conformallab_tests       --gtest_filter="Clausen*"
+
+# By CTest regex (prefix "cgal." for all CGAL tests)
+ctest --test-dir build -R "cgal.NewtonSolver" --output-on-failure
+```
+
+### Rebuilding the CI Docker image
+
+```bash
+docker buildx build \
+  --platform linux/arm64 \
+  -f .gitea/docker/Dockerfile.ci-cpp \
+  -t git.eulernest.eu/conformallab/ci-cpp:latest \
+  --push \
+  .gitea/docker/
+```
+
+## Architecture
+
+### Everything is header-only
+
+All algorithms live in `code/include/*.hpp`. There is no compiled library. The three CMake targets (`conformallab_tests`, `conformallab_cgal_tests`, `conformallab_core`) compile headers directly from their `.cpp` entry points. To add a new algorithm: create a `.hpp` in `code/include/`, add a test in `code/tests/cgal/`, and register the test file in `code/tests/cgal/CMakeLists.txt`.
+
+### Central type: `ConformalMesh`
+
+`conformal_mesh.hpp` defines the core type:
+```cpp
+using ConformalMesh = CGAL::Surface_mesh<Point3>;  // CGAL::Simple_cartesian<double>
+```
+
+This replaces the Java `CoHDS` (half-edge data structure) and its intrusive `CoVertex`/`CoEdge`/`CoFace` types. Data is attached via named CGAL property maps instead of intrusive fields:
+
+| Property map name | Type | Meaning |
+|---|---|---|
+| `"v:lambda"` | `double` per vertex | log scale factor (conformal variable uᵢ) |
+| `"v:theta"` | `double` per vertex | target cone angle Θᵥ |
+| `"v:idx"` | `int` per vertex | solver DOF index; `-1` = pinned/boundary |
+| `"e:alpha"` | `double` per edge | intersection angle αᵢⱼ (hyperbolic only) |
+| `"f:type"` | `int` per face | geometry type (0=Euclidean, 1=Hyperbolic, 2=Spherical) |
+
+`CGAL_DISABLE_GMP` and `CGAL_DISABLE_MPFR` are defined for all CGAL targets — the library deliberately uses `Simple_cartesian<double>` (floating-point, no exact arithmetic) because conformal geometry does not require exact predicates.
+
+### The five DCE models
+
+Each model has its own Maps struct that bundles all property maps, plus a functional, optional Hessian, Newton solver, and (since v0.9.0) a CGAL public-API entry function:
+
+| Model | Space | DOFs | Maps struct | Key headers | Newton function | CGAL entry |
+|---|---|---|---|---|---|---|
+| Euclidean | ℝ² | vertex | `EuclideanMaps` | `euclidean_functional.hpp`, `euclidean_hessian.hpp` | `newton_euclidean()` | `discrete_conformal_map_euclidean()` |
+| Spherical | S² | vertex | `SphericalMaps` | `spherical_functional.hpp`, `spherical_hessian.hpp` | `newton_spherical()` | `discrete_conformal_map_spherical()` |
+| Hyper-ideal | H² (Poincaré disk) | vertex + edge | `HyperIdealMaps` | `hyper_ideal_functional.hpp`, `hyper_ideal_hessian.hpp` (block-FD, Phase 9b) | `newton_hyper_ideal()` | `discrete_conformal_map_hyper_ideal()` |
+| CP-Euclidean (BPS 2010) | face-based circle packing | **face** | `CPEuclideanMaps` | `cp_euclidean_functional.hpp` | `newton_cp_euclidean()` | `discrete_circle_packing_euclidean()` |
+| Inversive-Distance (Luo 2004) | vertex-based circle packing | vertex | `InversiveDistanceMaps` | `inversive_distance_functional.hpp` | `newton_inversive_distance()` | `discrete_inversive_distance_map()` |
+
+DOF-assignment patterns:
+- **Vertex-only models** (Euclidean, Spherical, Inversive-Distance): pin one vertex manually (`maps.v_idx[first_vertex] = -1`) then assign sequential indices.  The CGAL public entries do this automatically with the "natural-theta" trick (so calling them with no arguments returns x = 0 as the equilibrium).
+- **HyperIdeal**: `assign_all_dof_indices(mesh, maps)` assigns vertex + edge DOFs automatically.
+- **CP-Euclidean**: face-based — `assign_cp_euclidean_face_dof_indices(mesh, maps, pinned_face)` pins one face and indexes the rest.
+
+### The full pipeline
+
+```
+load_mesh()                          → ConformalMesh  (OFF/OBJ/PLY)
+setup_*_maps(mesh)                   → *Maps  (property maps created, all zero)
+compute_*_lambda0_from_mesh(mesh, m) → λ° initialised from 3-D edge lengths
+DOF assignment                       → v_idx[v] set; -1 = pinned
+check_gauss_bonnet(mesh, maps)       → throws if Σ(2π−Θᵥ) ≠ 2π·χ(M)
+enforce_gauss_bonnet(mesh, maps)     → redistributes angle defect uniformly
+newton_*(mesh, x0, maps)             → NewtonResult{x*, iterations, converged}
+compute_cut_graph(mesh)              → CutGraph  (2g seam edges, tree-cotree)
+*_layout(mesh, x*, maps, &cg, &hol) → Layout2D/3D  + HolonomyData
+normalise_*(layout)                  → canonical position (PCA / Möbius / Rodrigues)
+compute_period_matrix(hol)           → PeriodData{τ∈ℍ}  (genus 1 flat torus)
+compute_fundamental_domain(hol)      → FundamentalDomain{vertices, generators}
+tiling_neighbourhood(layout, hol)    → vector of translated layout copies
+save_result_json/xml()               → serialised result
+```
+
+After `compute_*_lambda0_from_mesh()` the original vertex positions are no longer used — all subsequent computation is in log-length/scale-factor space.
+
+### Newton solver (`newton_solver.hpp`)
+
+Gradient sign convention differs across the five models:
+- **Euclidean / Spherical / Inversive-Distance:** `G_v = Θ_v − actual_angle_sum` (target minus actual).
+- **HyperIdeal:** `G_v = actual_angle_sum − Θ_v` (actual minus target).
+- **CP-Euclidean:** `G_f = φ_f − Σ_{h:face(h)=f} (p(θ*,Δρ) + θ*)` (face-based; see `cp_euclidean_functional.hpp` header for the full formula).
+
+Hessian sign and solver per model:
+- **Euclidean:** H is PSD (cotangent Laplacian) → `SimplicialLDLT(H)`.
+- **Spherical:** H is NSD (concave energy) → `SimplicialLDLT(−H)` (sign flip inside `newton_spherical`).
+- **HyperIdeal:** H is PSD (strictly convex) → `SimplicialLDLT(H)`.  Phase 9b uses a **block-FD Hessian** (per-face 6×6 local block, ~96× speed-up vs full FD on V=200).  Full analytic Hessian via the chain `(bᵢ, aₑ) → lᵢⱼ → ζ₁₃/ζ₁₄/ζ₁₅ → αᵢⱼ/βᵢ` is planned research — see `doc/roadmap/research-track.md` Phase 9b-analytic.
+- **CP-Euclidean:** analytic 2×2-per-edge `h_jk = sin θ / (cosh Δρ − cos θ)` (BPS 2010), strictly convex → `SimplicialLDLT(H)`.
+- **Inversive-Distance:** FD Hessian (inline in `newton_inversive_distance`).  Analytic via Glickenstein 2011 eq. (4.6) is planned research (Phase 9a.2-analytic).
+
+When `SimplicialLDLT` fails (rank-deficient H — gauge mode on a closed mesh without pinned vertex/face), the solver automatically retries with `Eigen::SparseQR` to find the minimum-norm step orthogonal to the null space.  Public API: `solve_linear_system(H, rhs, &used_fallback)`.
+
+### Layout and holonomy (`layout.hpp`)
+
+BFS-trilateration with a **priority min-heap on BFS depth** (`depth = max(depth[src], depth[tgt]) + 1`). Root face = largest 3-D area face. This minimises trilateration error accumulation compared to simple BFS.
+
+Key output fields:
+- `layout.uv[v.idx()]` — primary UV (first/shallowest BFS visit per vertex)
+- `layout.halfedge_uv[h.idx()]` — UV of `source(h)` as seen from `face(h)`; at seam halfedges the two opposite halfedges carry *different* UV values, enabling proper GPU texture atlasing without vertex duplication
+- `hol.translations[i]` — lattice generator ωᵢ ∈ ℂ (Euclidean/spherical)
+- `hol.mobius_maps[i]` — Möbius isometry Tᵢ ∈ SU(1,1) (hyperbolic, Poincaré disk)
+
+`MobiusMap` is defined in `layout.hpp`: T(z) = (az+b)/(cz+d). Key methods: `from_three()` (fit to 3 point correspondences via 3×3 complex linear system), `compose()`, `inverse()`, `apply(Vector2d)`.
+
+### Key mathematical reference for each header
+
+| Header | Java original | Key reference |
+|---|---|---|
+| `hyper_ideal_geometry.hpp` | `HyperIdealGeometry.java` | Springborn (2020) — ζ₁₃/ζ₁₄/ζ₁₅ functions |
+| `euclidean_hessian.hpp` | `EuclideanHessian.java` | Pinkall & Polthier (1993) — cotangent Laplacian |
+| `spherical_hessian.hpp` | `SphericalHessian.java` | ∂α/∂u from spherical law of cosines |
+| `cut_graph.hpp` | `CuttingUtility.java` | Erickson & Whittlesey (SODA 2005) — tree-cotree |
+| `period_matrix.hpp` | `PeriodMatrixUtility.java` | Sechelmann (2016) §4 — SL(2,ℤ) reduction |
+| `gauss_bonnet.hpp` | (distributed across Java) | Gauss–Bonnet: Σ(2π−Θᵥ) = 2π·χ(M) |
+
+### Java features not yet ported (Phase 9)
+
+The Java library under `de.varylab.discreteconformal` contains these items not yet in C++:
+
+| Java class | Planned C++ header | Phase |
+|---|---|---|
+| `InversiveDistanceFunctional` | `inversive_distance_functional.hpp` | 9a |
+| Analytic HyperIdeal Hessian | `hyper_ideal_hessian.hpp` (replace FD) | 9b |
+| 4g-polygon boundary walk in `FundamentalDomainUtility` | `fundamental_domain.hpp` (extend) | 9c |
+| `DiscreteHarmonicFormUtility` | Phase 10a prerequisite | 10 |
+| `DiscreteHolomorphicFormUtility` | Phase 10a | 10 |
+| `HomologyUtility`, `CanonicalBasisUtility` | Phase 10 | 10 |
+
+When porting a Java class, locate the original in `de.varylab.discreteconformal.*` at [github.com/varylab/conformallab](https://github.com/varylab/conformallab) and use it as the reference implementation.
+
+## Test design patterns
+
+### "Natural theta" — constructing a known equilibrium at x* = 0
+
+```cpp
+// Evaluate gradient at x=0; set target angles = actual angle sums → x*=0 by definition
+std::vector<double> x0(n_dofs, 0.0);
+auto G0 = euclidean_gradient(mesh, x0, maps);
+for (auto v : mesh.vertices())
+    if (maps.v_idx[v] >= 0)
+        maps.theta_v[v] -= G0[maps.v_idx[v]];  // shift so G(x=0) = 0
+```
+
+This is used in virtually every Newton convergence test — it avoids hardcoding specific angle values.
+
+### Gradient check pattern
+
+```cpp
+// Copy from any test_*_functional.cpp — GradientCheck_* test suite
+double eps = 1e-5;
+for (int i = 0; i < n; ++i) {
+    xp[i] += eps;  auto Gp = euclidean_gradient(mesh, xp, maps);
+    xm[i] -= eps;  auto Gm = euclidean_gradient(mesh, xm, maps);
+    double fd = (energy(xp) - energy(xm)) / (2*eps);
+    EXPECT_NEAR(G[i], fd, 1e-7);
+    xp[i] = xm[i] = x0[i];
+}
+```
+
+All new functionals must have a gradient-check test before being considered complete.
+
+### Halfedge traversal
+
+```cpp
+for (auto f : mesh.faces()) {
+    auto h0 = mesh.halfedge(f);          // canonical halfedge of face
+    auto h1 = mesh.next(h0);
+    auto h2 = mesh.next(h1);
+
+    Vertex_index v1 = mesh.source(h0);  // = mesh.target(h2)
+    Vertex_index v2 = mesh.source(h1);
+    Vertex_index v3 = mesh.source(h2);
+
+    // Angle at v3 is opposite to h0 (edge v1–v2)
+    // h_alpha[h0] = α₃,  h_alpha[h1] = α₁,  h_alpha[h2] = α₂
+
+    bool is_boundary = mesh.is_border(mesh.opposite(h0));
+}
+```
+
+### Attaching custom data to the mesh
+
+```cpp
+auto [my_map, created] = mesh.add_property_map<Vertex_index, double>("v:my_data", 0.0);
+my_map[v] = 3.14;
+```
+
+## CI pipeline
+
+Two jobs in `.gitea/workflows/cpp-tests.yml`:
+
+| Job | CMake flags | Deps | Triggers on |
+|---|---|---|---|
+| `test-fast` | *(none)* | Eigen + GTest only | all branches |
+| `test-cgal` | `-DWITH_CGAL_TESTS=ON` | + Boost | pull requests only |
+
+Runner: `eulernest` — self-hosted Raspberry Pi, ARM64, Ubuntu 22.04. Docker image: `git.eulernest.eu/conformallab/ci-cpp:latest`. `test-cgal` needs `test-fast` to pass first (`needs: test-fast`).
+
+Expected results: full test suite passing, 0 skipped, 0 failed.  The canonical counts live in `doc/api/tests.md` — do not hardcode them anywhere else (see [`doc/release-policy.md`](doc/release-policy.md)).
+
+## Release state
+
+Current release: **v0.9.0** (tag on `main`, released 2026-05-22).
+Phases 1–9a complete, Phase 8b-Lite CGAL API surface complete (all 5 DCE models reachable via `<CGAL/Discrete_*.h>`), Phase 9b block-FD HyperIdeal Hessian shipped (~96× speed-up).  Next planned milestones: Phase 9c (4g-polygon, genus g > 1) and Phase 9b-analytic (Schläfli identity).  See `doc/release-policy.md` for the version-tag policy and `doc/roadmap/phases.md` for the phase plan.
+
+## Phase 8 strategic decisions (2026-05-19)
+
+The CGAL-package architecture was frozen on 2026-05-19.  Full design:
+[`doc/api/cgal-package.md`](doc/api/cgal-package.md).  Key decisions:
+
+| Decision | Choice |
+|---|---|
+| Submission to upstream CGAL | **Pre-submission-ready, not bound.** 12+ months horizon. |
+| License | **MIT preserved** (no LGPL switch). |
+| Mesh-type flexibility | **Generic `FaceGraph + HalfedgeGraph`** in target design; MVP starts Surface_mesh-only. |
+| Parameter style | **Named Parameters** (`CGAL::parameters::...`). |
+| Default kernel | **`Simple_cartesian<double>`** (status quo). |
+| Backward compatibility | **Dual-layer wrapper** — `code/include/*.hpp` stays as implementation, `include/CGAL/*.h` is thin wrapper.  No algorithm duplication. |
+| Implementation strategy | **Hybrid MVP** — minimum Phase 8 (traits + one wrapper) first, then Phase 9 in full, then Phase 8 extensions only on concrete demand. |
+| Phase-8 MVP acceptance test | **Phase 9a (Inversive-Distance)** as the first new client of the new traits API. |
+
+### Implementation sequence (committed)
+
+```
+1. Phase 7.5  Doxygen + cleanup                         done ✅
+2. Phase 8 MVP — traits + one euclidean wrapper         3–5 days
+3. Phase 9a — Inversive-Distance against new traits     3–5 days
+4. Phase 9b — analytic HyperIdeal Hessian               1 week
+5. Phase 9c — 4g-polygon for genus g > 1                1 week
+   → port really complete, v0.9.0 release
+```
+
+Phase 8 extensions (8a.2 generic FaceGraph, 8c full Doxygen manuals, 8d
+CGAL-format tests, 8e YAML pipeline) are deferred to on-demand status —
+no speculative architecture for an uncertain submission.
+
+Root-level files added at v0.7.0:
+- `CITATION.cff` — machine-readable citation (Sechelmann 2016, Springborn 2020, Bobenko–Springborn 2004)
+- `CONTRIBUTING.md` — short root-level pointer to `doc/contributing.md`
+- `scripts/try_it.sh` — one-script quickstart: build → 209 tests → example run
+- CMake install target: `cmake --install build --prefix /usr/local` → headers land in `include/conformallab/`
+
+## Port-vs-research maintenance rule (2026-05-21 audit)
+
+Before claiming something "ports X from Java", **verify empirically**:
+
+```bash
+find /Users/tarikmoussa/Desktop/conformallab -iname "*X*"
+grep -r "ClassName" /Users/tarikmoussa/Desktop/conformallab/src
+```
+
+If zero matches, the work is **new research** — add it to
+`doc/roadmap/research-track.md` with primary literature citations,
+**not** to `doc/roadmap/java-parity.md`.
+
+The 2026-05-21 audit found four pre-existing mis-labels:
+
+| Item | Wrong claim | Reality |
+|---|---|---|
+| `InversiveDistanceFunctional` | "Java port (Luo 2004)" | No such Java class exists |
+| HyperIdeal Hessian (FD) | "Phase 4a" | Research — Java has `hasHessian()==false` |
+| HyperIdeal Hessian (analytic) | "Phase 9b port" | Research — derivation via Schläfli 1858 |
+| Tutorial framing | "ports `InversiveDistanceFunctional.java`" | Implementation from Luo 2004 + Glickenstein 2011 |
+
+All four are corrected as of this commit.  Future contributors must
+follow the empirical verification rule above before any new claim.
+
+## Documentation map
+
+24 documents across 6 categories. Read the relevant one before reasoning from scratch
+— do not hallucinate content that is already written down.
+
+### Mathematics & theory
+
+| Question | Document |
+|---|---|
+| What problem does this library solve mathematically? | `doc/math/discrete-conformal-theory.md` |
+| How do the three geometry modes differ (Euclidean/Spherical/HyperIdeal)? | `doc/math/geometry-modes.md` |
+| What analytic invariants can be used to validate correctness? | `doc/math/validation.md` |
+| What are the exact ctest commands with expected terminal output? | `doc/math/validation-protocol.md` |
+| What is the O() complexity and how does it scale with mesh size? | `doc/math/complexity.md` |
+| Which papers are referenced by which header? | `doc/math/references.md` |
+| How does conformallab++ compare to libigl, CGAL, geometry-central, pmp-library? | `doc/math/software-landscape.md` |
+| What is unique about conformallab++ (novelty, target audience)? | `doc/math/novelty-statement.md` |
+
+### Architecture & design
+
+| Question | Document |
+|---|---|
+| Full pipeline diagram and data-flow overview | `doc/architecture/overall_pipeline.md` |
+| Directory tree, build targets, file organisation | `doc/architecture/project-structure.md` |
+| Key architectural decisions and their rationale | `doc/architecture/design-decisions.md` |
+| Detailed comparison with geometry-central (CMU): overlap, adoption, scientific value | `doc/architecture/geometry-central-comparison.md` |
+| Phase 9a validation report (CP-Euclidean port + Luo-inversive-distance literature check) | `doc/architecture/phase-9a-validation.md` |
+
+### API & extension
+
+| Question | Document |
+|---|---|
+| All 24 public headers with descriptions | `doc/api/headers.md` |
+| Full pipeline API for all three geometries | `doc/api/pipeline.md` |
+| What does each processing unit require/provide (contracts)? | `doc/api/contracts.md` |
+| How to add a new functional / geometry mode / port from Java | `doc/api/extending.md` |
+| Per-suite breakdown and counts (single source of truth) | `doc/api/tests.md` |
+| Phase 8 CGAL package design + Declarative YAML pipeline spec | `doc/api/cgal-package.md` |
+
+### Concepts & specs
+
+| Question | Document |
+|---|---|
+| Declarative YAML pipeline: token vocabulary, 5 examples, validation algorithm | `doc/concepts/declarative-pipeline.md` |
+
+### Roadmap & porting
+
+| Question | Document |
+|---|---|
+| Phases 1–10 with status and sub-tasks | `doc/roadmap/phases.md` |
+| Which Java classes are ported, which are planned, which are skipped? | `doc/roadmap/java-parity.md` |
+| New research items (beyond Java) — citations, acceptance criteria | `doc/roadmap/research-track.md` |
+
+### Tutorials & onboarding
+
+| Question | Document |
+|---|---|
+| Build modes, single-test invocation, CLI, Docker image rebuild | `doc/getting-started.md` |
+| Step-by-step: port the Inversive Distance functional (Phase 9a template) | `doc/tutorials/add-inversive-distance.md` |
+| Language policy, test standards, release flow | `doc/contributing.md` |
+| Versioning rules + release process + single-source-of-truth list | `doc/release-policy.md` |
+
+### geometry-central context
+
+**geometry-central** (Keenan Crane, CMU) implements the same discrete conformal
+equivalence problem (Gillespie, Springborn & Crane, SIGGRAPH 2021) but uses
+Ptolemaic flips on intrinsic triangulations instead of Newton on the original mesh.
+It has no period matrix, holonomy, or spherical geometry mode.
+The shared mathematical core (Springborn 2020) means cross-validation is meaningful.
+Full analysis: `doc/architecture/geometry-central-comparison.md`.
+Optional adoption roadmap (GC-1/2/3): `doc/roadmap/phases.md` (Optional section).
+
+## Known quirks
+
+- **No GTEST_SKIP stubs remain** (since v0.9.0): the three stale HDS-port stub files were removed because the CGAL test suite covers the same functionality with real tests.  The pure-math `conformallab_tests` target now only contains active tests.
+- **Boost is header-only**: CGAL 6.x uses only Boost headers (`Boost.Config`, `Boost.Graph`). No compiled Boost libraries are needed. `find_package(Boost REQUIRED)` only locates the include path.
+- **`main` branch is protected** on `origin` (Gitea). Push to `dev`, then merge via pull request. Codeberg `main` can be pushed to directly.
+- **Both remotes must stay in sync**: `origin` = `git.eulernest.eu` (CI runs here), `codeberg` = `codeberg.org/TMoussa/ConformalLabpp` (public mirror). Push to both after every significant change.

CONTRIBUTING.md

@@ -0,0 +1,17 @@
+# Contributing to conformallab++
+
+See **[doc/contributing.md](doc/contributing.md)** for the full guide:
+
+- Git workflow (dev → PR → main)
+- CI pipeline (test-fast / test-cgal)
+- Test standards (gradient check, convergence test, registration)
+- Code style (C++17, header-only, namespace, property map naming)
+- Release process
+
+For the mathematical background of what's being implemented, see:
+
+- [doc/math/discrete-conformal-theory.md](doc/math/discrete-conformal-theory.md) — theory overview
+- [doc/math/validation.md](doc/math/validation.md) — how to validate the implementation
+- [doc/math/references.md](doc/math/references.md) — all referenced papers
+
+To add your own research, see [doc/api/extending.md](doc/api/extending.md).

Doxyfile

@@ -0,0 +1,166 @@
+# Doxyfile for conformallab++
+#
+# Phase 7.5 — minimal CGAL-style Doxygen configuration.
+# Only non-default values are set; Doxygen ≥ 1.9.5 supplies the rest.
+#
+# Usage:
+#   doxygen Doxyfile           # generates HTML into doc/doxygen/html/
+#   open doc/doxygen/html/index.html
+#
+# Or via CMake:
+#   cmake --build build --target doc
+
+# ── Project identity ─────────────────────────────────────────────────────────
+PROJECT_NAME           = "conformallab++"
+PROJECT_NUMBER         = 0.7.0
+PROJECT_BRIEF          = "Discrete conformal maps on triangle meshes — C++17 reimplementation of ConformalLab (TU Berlin)"
+PROJECT_LOGO           =
+OUTPUT_DIRECTORY       = doc/doxygen
+USE_MDFILE_AS_MAINPAGE = README.md
+
+# ── Input ────────────────────────────────────────────────────────────────────
+INPUT                  = README.md \
+                         CLAUDE.md \
+                         code/include \
+                         doc/api \
+                         doc/architecture \
+                         doc/math
+FILE_PATTERNS          = *.hpp *.h *.cpp *.md
+RECURSIVE              = YES
+EXCLUDE_PATTERNS       = */build*/* \
+                         */deps/* \
+                         */.git/* \
+                         */test-reports/* \
+                         *\ 2.hpp \
+                         *\ 2.h
+# Research-quality LaTeX notes use raw \sinh / \cosh / \frac / \beta /
+# \cdot / \partial / \zeta macros which are valid LaTeX but unknown to
+# Doxygen.  These files are intended to be read as PDF or in a LaTeX-
+# aware markdown viewer, not as Doxygen pages.  Excluding them removes
+# ~500 spurious "unknown command" warnings while keeping the .md files
+# discoverable on GitHub.
+EXCLUDE                = doc/math/hyperideal-hessian-derivation.md
+EXCLUDE_SYMBOLS        = Eigen::* boost::* std::*
+
+# Markdown filter: rewrites repo-relative links like [x](doc/api/tests.md)
+# into basename-only links [x](tests.md) so Doxygen's basename-indexed
+# \ref resolver can find them.  On-disk files are untouched (GitHub keeps
+# rendering them correctly).  See scripts/doxygen-md-filter.sh.
+FILTER_PATTERNS        = *.md=scripts/doxygen-md-filter.sh
+
+# ── Source browsing ──────────────────────────────────────────────────────────
+EXTRACT_ALL            = YES
+EXTRACT_PRIVATE        = NO
+EXTRACT_STATIC         = YES
+EXTRACT_LOCAL_CLASSES  = YES
+HIDE_UNDOC_MEMBERS     = NO
+SOURCE_BROWSER         = YES
+INLINE_SOURCES         = NO
+STRIP_CODE_COMMENTS    = NO
+REFERENCED_BY_RELATION = YES
+REFERENCES_RELATION    = YES
+REFERENCES_LINK_SOURCE = YES
+
+# ── Build options ────────────────────────────────────────────────────────────
+JAVADOC_AUTOBRIEF      = YES
+QT_AUTOBRIEF           = NO
+MARKDOWN_SUPPORT       = YES
+AUTOLINK_SUPPORT       = YES
+BUILTIN_STL_SUPPORT    = YES
+DISTRIBUTE_GROUP_DOC   = YES
+GROUP_NESTED_COMPOUNDS = YES
+SUBGROUPING            = YES
+INLINE_GROUPED_CLASSES = NO
+INLINE_SIMPLE_STRUCTS  = NO
+TYPEDEF_HIDES_STRUCT   = NO
+EXTENSION_MAPPING      = h=C++ hpp=C++
+
+# ── Warnings ─────────────────────────────────────────────────────────────────
+QUIET                  = NO
+WARNINGS               = YES
+WARN_IF_UNDOCUMENTED   = YES
+WARN_IF_DOC_ERROR      = YES
+WARN_IF_INCOMPLETE_DOC = YES
+WARN_NO_PARAMDOC       = NO
+WARN_AS_ERROR          = NO
+WARN_FORMAT            = "$file:$line: $text"
+WARN_LOGFILE           = doc/doxygen/doxygen-warnings.log
+
+# ── HTML output ──────────────────────────────────────────────────────────────
+GENERATE_HTML          = YES
+
+# MathJax — render LaTeX math in markdown ($...$ and $$...$$) and in
+# code-comment `\f$ ... \f$` blocks via MathJax in the generated HTML.
+# Required for the conformal-mapping math notation (\Theta, \omega, \tau,
+# \mathbb{H}, …) in doc/architecture/overall_pipeline.md and the
+# header docstrings.
+USE_MATHJAX            = YES
+MATHJAX_VERSION        = MathJax_3
+MATHJAX_FORMAT         = HTML-CSS
+MATHJAX_RELPATH        = https://cdn.jsdelivr.net/npm/mathjax@3/es5/
+HTML_OUTPUT            = html
+HTML_FILE_EXTENSION    = .html
+HTML_COLORSTYLE        = LIGHT
+HTML_COLORSTYLE_HUE    = 220
+HTML_COLORSTYLE_SAT    = 100
+HTML_COLORSTYLE_GAMMA  = 80
+# HTML_TIMESTAMP was removed in Doxygen 1.10; use TIMESTAMP=NO instead.
+TIMESTAMP              = NO
+HTML_DYNAMIC_SECTIONS  = YES
+GENERATE_TREEVIEW      = YES
+DISABLE_INDEX          = NO
+ENUM_VALUES_PER_LINE   = 1
+TREEVIEW_WIDTH         = 280
+EXT_LINKS_IN_WINDOW    = NO
+SEARCHENGINE           = YES
+SERVER_BASED_SEARCH    = NO
+
+# ── Disabled outputs (we only want HTML) ─────────────────────────────────────
+GENERATE_LATEX         = NO
+GENERATE_RTF           = NO
+GENERATE_MAN           = NO
+GENERATE_XML           = YES
+XML_OUTPUT             = xml
+XML_PROGRAMLISTING     = NO
+GENERATE_DOCBOOK       = NO
+GENERATE_AUTOGEN_DEF   = NO
+GENERATE_PERLMOD       = NO
+
+# ── Preprocessor ─────────────────────────────────────────────────────────────
+ENABLE_PREPROCESSING   = YES
+MACRO_EXPANSION        = YES
+EXPAND_ONLY_PREDEF     = YES
+SEARCH_INCLUDES        = YES
+INCLUDE_PATH           = code/include
+PREDEFINED             = CGAL_DISABLE_GMP \
+                         CGAL_DISABLE_MPFR \
+                         DOXYGEN_RUNNING
+
+# ── Diagrams ─────────────────────────────────────────────────────────────────
+HAVE_DOT               = NO
+CLASS_GRAPH            = YES
+COLLABORATION_GRAPH    = NO
+GROUP_GRAPHS           = YES
+INCLUDE_GRAPH          = NO
+INCLUDED_BY_GRAPH      = NO
+CALL_GRAPH             = NO
+CALLER_GRAPH           = NO
+
+# ── Aliases (CGAL-style) ─────────────────────────────────────────────────────
+ALIASES               += "concept{1}=\xrefitem concept \"Concept\" \"Concepts\" \1"
+ALIASES               += "models{1}=\xrefitem models \"Models\" \"Models\" \1"
+ALIASES               += "cgalRequires{1}=\par Requirements: \n\1"
+ALIASES               += "cgalParam{2}=\param \1 \2"
+# CGAL named-parameter block aliases — replicates the upstream
+# ${CGAL}/Documentation/doc/Documentation/Doxyfile_common conventions
+# so that \cgalParamNBegin{name} … \cgalParamNEnd blocks render as
+# nested HTML lists in our Doxygen output.
+ALIASES               += "cgalNamedParamsBegin=<dl class=\"params\"><dt>Optional named parameters</dt><dd><table class=\"params\">"
+ALIASES               += "cgalNamedParamsEnd=</table></dd></dl>"
+ALIASES               += "cgalParamNBegin{1}=<tr><td class=\"paramname\"><code>\1</code></td><td>"
+ALIASES               += "cgalParamNEnd=</td></tr>"
+ALIASES               += "cgalParamDescription{1}=<b>Description:</b> \1<br/>"
+ALIASES               += "cgalParamType{1}=<b>Type:</b> \1<br/>"
+ALIASES               += "cgalParamDefault{1}=<b>Default:</b> \1<br/>"
+ALIASES               += "cgalParamPrecondition{1}=<b>Precondition:</b> \1<br/>"
+ALIASES               += "cgalParamExtra{1}=<i>\1</i><br/>"

LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2026 user2595
+Copyright (c) 2024–2026 Tarik Moussa <Tarik.moussa95@gmail.com>
 
 Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
 

README.md

@@ -1,697 +1,175 @@
 # conformallab++
 
-conformallab++ is a modern C++ reimplementation of
+[![CI](https://git.eulernest.eu/conformallab/ConformalLabpp/actions/workflows/cpp-tests.yml/badge.svg)](https://git.eulernest.eu/conformallab/ConformalLabpp/actions)
-[ConformalLab](https://github.com/varylab/conformallab) —
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
-the research software for discrete conformal geometry by
+[![DOI](https://img.shields.io/badge/doi-Sechelmann%202016-blue)](https://depositonce.tu-berlin.de/items/8e2988b2-d991-45b5-aad5-9fb7988f3b2f)
-**Stefan Sechelmann** (TU Berlin, Institut für Mathematik).
+[![API docs](https://img.shields.io/badge/API%20docs-Doxygen-orange)](https://tmoussa.codeberg.page/ConformalLabpp/)
 
-The algorithmic foundation is his doctoral dissertation:
+C++17 reimplementation of [ConformalLab](https://github.com/varylab/conformallab) —
+Stefan Sechelmann's Java research library for discrete conformal geometry (TU Berlin).
+The long-term goal is a **CGAL package** for discrete conformal maps.
 
-> Stefan Sechelmann —  
+Algorithmic foundation:
-> **Variational Methods for Discrete Surface Parameterization: Applications and Implementation**  
+> Stefan Sechelmann — *Variational Methods for Discrete Surface Parameterization: Applications and Implementation*, TU Berlin 2016.
-> Doctoral thesis, Technische Universität Berlin, 2016.  
+> DOI: [10.14279/depositonce-5415](https://depositonce.tu-berlin.de/items/8e2988b2-d991-45b5-aad5-9fb7988f3b2f) · CC BY-SA 4.0 ·
-> DOI: [10.14279/depositonce-5415](https://depositonce.tu-berlin.de/items/8e2988b2-d991-45b5-aad5-9fb7988f3b2f)  
+> [Java original](https://github.com/varylab/conformallab) · [sechel.de](https://sechel.de/)
-> License: CC BY-SA 4.0
 
-The dissertation develops the variational framework for discrete conformal equivalence
+**Status:** v0.9.0 — Phases 1–9a complete, Phase 8b-Lite CGAL API surface. Newton solvers for **five** DCE models (Euclidean / Spherical / HyperIdeal / CP-Euclidean / Inversive-Distance), priority-BFS layout in ℝ²/S²/Poincaré disk, Gauss–Bonnet, tree-cotree cut graph, Möbius holonomy, period matrix (genus 1), fundamental domain, halfedge_uv texture atlas, JSON/XML serialisation, CLI app.  Full test suite passing, 0 skipped — see [`doc/api/tests.md`](doc/api/tests.md) for the per-suite breakdown.
-on triangulations — discrete uniformization of Riemann surfaces, cone metrics, period
-matrices — that forms the mathematical core of both the Java original and this C++ port.
-
-**Original Java library:** [github.com/varylab/conformallab](https://github.com/varylab/conformallab) (Java, ~850 commits, v1.0.0 2018)  
-**Author's website:** [sechel.de](https://sechel.de/) · **LinkedIn:** [linkedin.com/in/sechel](https://www.linkedin.com/in/sechel/)
-
-The long-term goal is a **CGAL package** that brings discrete conformal maps (hyper-ideal, spherical, Euclidean) to the CGAL ecosystem using `CGAL::Surface_mesh` as the underlying half-edge data structure.
-
-> **Status:** Phase 7 vollständig abgeschlossen. Alle drei Geometrien lösbar via Newton-Solver (SimplicialLDLT + SparseQR-Fallback). Priority-BFS-Layout in ℝ²/S²/Poincaré-Disk mit exakter hyperbolischer Trilateration, Gauss–Bonnet, Tree-Cotree-Schnittgraph, Möbius-Holonomie, Periodenmatrix (Genus 1), Fundamentalbereich-Polygon, halfedge_uv-Texturatlas. JSON/XML-Serialisierung, vollständige CLI-App. **158 Tests, 2 skipped**.
 
 ---
 
-## Features
+## Quick start
-
-| Bereich | Status |
-|---------|--------|
-| Clausen / Lobachevsky / ImLi₂ Funktionen | ✅ Phase 1 |
-| Hyper-ideal Geometrie (ζ, lᵢⱼ, αᵢⱼ, σᵢ, σᵢⱼ) | ✅ Phase 2 |
-| CGAL `Surface_mesh` Infrastruktur + Mesh-Builder | ✅ Phase 3a |
-| Hyper-ideal Funktional (Energie + Gradient) | ✅ Phase 3b |
-| Sphärisches Funktional (Energie + Gradient + Gauge-Fix) | ✅ Phase 3c/3e |
-| Euklidisches Funktional (Energie + Gradient) | ✅ Phase 3d |
-| Euklidischer Hessian (Kotangenten-Laplace, Pinkall–Polthier) | ✅ Phase 3f |
-| Sphärischer Hessian (∂α/∂u aus Kosinussatz) | ✅ Phase 3f |
-| Hyper-ideal Hessian (numerisch FD, symmetrisiert) | ✅ Phase 4a |
-| Newton-Solver — alle drei Geometrien | ✅ Phase 4a |
-| **SparseQR-Fallback** für rangdefiziente H (Gauge-Moden) | ✅ Phase 4a |
-| Mesh I/O (CGAL::IO — OFF / OBJ / PLY) | ✅ Phase 4b |
-| End-to-End-Pipeline-Tests | ✅ Phase 4c |
-| **Beispiel-Programme** (headless + interaktiver Viewer) | ✅ Phase 4d |
-| **BFS-Layout** (ℝ², S², Poincaré-Disk) | ✅ Phase 5 |
-| **CLI-App** (`conformallab_core`) | ✅ Phase 5 |
-| **JSON + XML Serialisierung** | ✅ Phase 5 |
-| **Gauss–Bonnet Check + Enforce** | ✅ Phase 6 |
-| **Tree-Cotree-Schnittgraph** (2g Naht-Kanten) | ✅ Phase 6 |
-| **Exakte hyperbolische Trilateration** (Möbius + Kosinussatz) | ✅ Phase 6 |
-| **Layout-Normalisierung** (PCA-Zentrierung / Möbius-Zentrierung) | ✅ Phase 6 |
-| **Priority-BFS** (Min-Heap über BFS-Tiefe, minimiert Fehlerakkumulation) | ✅ Phase 7 |
-| **MobiusMap** — T(z)=(az+b)/(cz+d), from_three, compose, inverse | ✅ Phase 7 |
-| **halfedge_uv** — Naht-bewusstes UV pro Halfedge (GPU-Texturatlas) | ✅ Phase 7 |
-| **Möbius-Holonomie** — SU(1,1)-Isometrie pro Schnitt-Kante (hyperbolisch) | ✅ Phase 7 |
-| **Periodenmatrix** — τ = ω₂/ω₁ ∈ ℍ, SL(2,ℤ)-Reduktion (Genus 1) | ✅ Phase 7 |
-| **Fundamentalbereich** — CCW-Parallelogramm, Kachelkopien | ✅ Phase 7 |
-| Analytischer HyperIdeal-Hessian (ζ-Kette) | ❌ Phase 8 geplant |
-| Inversive-Distance-Funktional (Luo 2004) | ❌ nicht portiert |
-| Vollständige globale Uniformisierung Genus g ≥ 2 | ❌ Phase 8 geplant |
-| Periodenmatrix Siegel Ω (g×g, g ≥ 2) | ❌ Phase 8 geplant |
-
----
-
-## Quick Start — CLI-App
 
 ```bash
-cmake -S code -B build -DWITH_CGAL=ON
+git clone https://codeberg.org/TMoussa/ConformalLabpp && cd ConformalLabpp
-cmake --build build -j4
 
-# Konformes Layout für beliebige OFF/OBJ/PLY-Netze
+# Fast tests — no system dependencies
-./bin/conformallab_core -i input.off -g euclidean -o layout.off -j result.json -x result.xml
+cmake -S code -B build && cmake --build build --target conformallab_tests -j$(nproc)
+ctest --test-dir build --output-on-failure
 
-# Geometrien: euclidean | spherical | hyper_ideal
+# CGAL tests headless (apt install libboost-dev / brew install boost)
-./bin/conformallab_core -i input.off -g spherical -o sphere.off
+cmake -S code -B build -DWITH_CGAL_TESTS=ON
+cmake --build build --target conformallab_cgal_tests -j$(nproc)
+ctest --test-dir build -R "^cgal\." --output-on-failure
 
-# Interaktiver Viewer
+# Full build with CLI + viewer (requires Wayland/X11 dev headers)
-./bin/conformallab_core -i input.off -s
+cmake -S code -B build -DWITH_CGAL=ON && cmake --build build -j$(nproc)
+./bin/conformallab_core -i input.off -g euclidean -o layout.off -j result.json
+
+# API documentation (requires doxygen: brew/apt install doxygen)
+cmake --build build --target doc
+open doc/doxygen/html/index.html
 ```
 
-### Beispiel-Programme
+### Compile-time workflow modes
+
+The default build (PCH + Unity Build + Dense→Core trims) takes ~47 s
+clean for the full CGAL test target.  Five opt-in modes cover other
+iteration scenarios:
 
 ```bash
-./build/examples/example_layout    [input.off] [layout.off] [result.json] [result.xml]
+# Configure-only, no compile.  ~1 s configure, 0 s build — emits
-./build/examples/example_euclidean [input.off] [output.off]
+# compile_commands.json for IDE / clangd; skips the GTest fetch.
-./build/examples/example_hyper_ideal [input.off] [output.off]
+cmake -S code -B build -DBUILD_TESTING=OFF
-./build/examples/example_viewer    [input.off]   # interaktiv (WITH_VIEWER)
+
+# Header smoke check: per-public-header isolated compile.  ~12 s full,
+# ~0.1 s after touching one header.  "Does my refactor still parse?"
+cmake -S code -B build -DBUILD_TESTING=OFF -DCONFORMALLAB_HEADERS_CHECK=ON
+cmake --build build --target headers_check
+
+# Dev iteration: PCH on, Unity off.  Slower full build (~75 s) but
+# editing a single test rebuilds in ~16 s instead of ~46 s.
+cmake -S code -B build -DWITH_CGAL_TESTS=ON -DCONFORMALLAB_DEV_BUILD=ON
+
+# Fast CI tests: -O0 -g for the test executables only (library /
+# install targets keep -O3).  Linux + g++ typically ~40 % faster
+# build at the cost of 5–15× slower test RUN.  Neutral on macOS.
+cmake -S code -B build -DWITH_CGAL_TESTS=ON -DCONFORMALLAB_FAST_TEST_BUILD=ON
+
+# Pristine measurement: disable both performance levers, e.g. for
+# scripts/quality/coverage.sh that needs every TU compiled fresh.
+cmake -S code -B build -DWITH_CGAL_TESTS=ON \
+    -DCONFORMALLAB_USE_PCH=OFF -DCMAKE_UNITY_BUILD=OFF
 ```
 
+ccache is detected automatically when present on `PATH`; disable with
+`-DCONFORMALLAB_USE_CCACHE=OFF`.  Full mode matrix + measurements in
+[`doc/architecture/compile-time.md`](doc/architecture/compile-time.md).
+
 ---
 
-## Bibliotheks-Nutzung
+## Minimal usage
-
-### Minimale euklidische Pipeline
 
 ```cpp
 #include "conformal_mesh.hpp"
 #include "mesh_io.hpp"
 #include "euclidean_functional.hpp"
+#include "gauss_bonnet.hpp"
 #include "newton_solver.hpp"
 #include "layout.hpp"
 
 using namespace conformallab;
 
-int main() {
+ConformalMesh mesh = load_mesh("input.off");
-    ConformalMesh mesh = load_mesh("input.off");
+EuclideanMaps maps = setup_euclidean_maps(mesh);
+compute_euclidean_lambda0_from_mesh(mesh, maps);
 
-    auto maps = setup_euclidean_maps(mesh);
+// Assign DOFs — pin first vertex (gauge fix)
-    compute_euclidean_lambda0_from_mesh(mesh, maps);
+auto vit = mesh.vertices().begin();
+maps.v_idx[*vit++] = -1;
+int idx = 0;
+for (; vit != mesh.vertices().end(); ++vit) maps.v_idx[*vit] = idx++;
 
-    // DOFs zuweisen — ersten Vertex pinnen (Gauge-Fix)
+// Natural equilibrium target: x* = 0 by construction
-    auto vit = mesh.vertices().begin();
+std::vector<double> x0(idx, 0.0);
-    maps.v_idx[*vit++] = -1;
+auto G0 = euclidean_gradient(mesh, x0, maps);
-    int idx = 0;
+for (auto v : mesh.vertices())
-    for (; vit != mesh.vertices().end(); ++vit)
+    if (maps.v_idx[v] >= 0) maps.theta_v[v] -= G0[maps.v_idx[v]];
-        maps.v_idx[*vit] = idx++;
 
-    // Zielwinkel: natürliches Gleichgewicht (x* = 0)
+check_gauss_bonnet(mesh, maps);
-    std::vector<double> x0(idx, 0.0);
+NewtonResult res = newton_euclidean(mesh, x0, maps);
-    auto G0 = euclidean_gradient(mesh, x0, maps);
+Layout2D layout = euclidean_layout(mesh, res.x, maps);
-    for (auto v : mesh.vertices()) {
-        int iv = maps.v_idx[v];
-        if (iv >= 0) maps.theta_v[v] -= G0[iv];
-    }
-
-    auto res = newton_euclidean(mesh, x0, maps);
-    if (res.converged)
-        save_mesh("output.off", mesh);
-    return res.converged ? 0 : 1;
-}
-```
-
-### Layout + Holonomie (geschlossene Flächen)
-
-```cpp
-#include "layout.hpp"
-#include "cut_graph.hpp"
-#include "period_matrix.hpp"
-#include "fundamental_domain.hpp"
-
-// Schnittgraph berechnen (Tree-Cotree, 2g Kanten)
-CutGraph cg = compute_cut_graph(mesh);
-
-// Layout mit Holonomie-Tracking
-HolonomyData hol;
-Layout2D lay = euclidean_layout(mesh, res.x, maps, &cg, &hol, /*normalise=*/true);
-
-// Periodenmatrix (Genus 1)
-PeriodData pd = compute_period_matrix(hol);   // τ = ω₂/ω₁ ∈ ℍ, SL(2,ℤ)-reduziert
-std::cout << "τ = " << pd.tau << "\n";
-
-// Fundamentalbereich-Parallelogramm
-FundamentalDomain fd = compute_fundamental_domain(hol);
-// fd.vertices  — 4 Ecken (CCW)
-// fd.generators — ω₁, ω₂
-
-// Kachelkopie für Universalüberlagerung
-Layout2D tile = tiling_copy(lay, fd.generators[0], fd.generators[1], 1, -1);
-
-// halfedge_uv — Naht-bewusstes UV pro Halfedge (GPU-Texturatlas)
-// lay.halfedge_uv[h.idx()] = UV von source(h) aus Sicht von face(h)
-```
-
-### HyperIdeal-Geometrie
-
-```cpp
-auto maps = setup_hyper_ideal_maps(mesh);
-int n = assign_all_dof_indices(mesh, maps);
-auto result = newton_hyper_ideal(mesh, x0, maps);
-
-// Möbius-Holonomie (SU(1,1)-Isometrien pro Schnitt-Kante)
-HolonomyData hol;
-Layout2D lay = hyper_ideal_layout(mesh, result.x, maps, &cg, &hol);
-// hol.mobius_maps[i] = T_i  (Möbius-Abbildung für i-te Schnitt-Kante)
-```
-
-### SparseQR-Fallback direkt nutzen
-
-```cpp
-#include "newton_solver.hpp"
-
-bool used_fallback = false;
-auto dx = conformallab::solve_linear_system(H, rhs, &used_fallback);
-if (used_fallback)
-    std::cout << "SparseQR verwendet (H ist rangdefizient)\n";
 ```
 
 ---
 
-## Build-Modi
+## Documentation
-
-| Modus | CMake-Flags | Was wird gebaut |
-|-------|------------|-----------------|
-| **Nur Tests** (Standard) | *(keine)* | `conformallab_tests` — Eigen + GTest |
-| **CGAL-Tests + Beispiele** | `-DWITH_CGAL=ON` | `conformallab_cgal_tests`, Beispiel-Programme, CLI |
-| **Interaktiver Viewer** | `-DWITH_CGAL=ON` | + `example_viewer`, Viewer in CLI integriert |
-
-Externe Abhängigkeiten sind als Tarballs in `code/deps/tarballs/` enthalten und werden beim CMake-Configure-Schritt extrahiert (GTest via `FetchContent`). **Boost** wird nur mit `-DWITH_CGAL=ON` benötigt (Header-Only durch CGAL 6.x).
-
----
-
-## Voraussetzungen
-
-| Tool | Minimum |
-|------|---------|
-| C++ Compiler (GCC oder Clang) | C++17 |
-| CMake | 3.20 |
-| Boost Headers | 1.70 *(nur mit `-DWITH_CGAL=ON`)* |
-
----
-
-## Einstieg
-
-```bash
-git clone https://codeberg.org/TMoussa/ConformalLabpp
-cd ConformalLabpp
-```
-
-### Nur Tests (CI-Standard — keine System-Abhängigkeiten)
-
-```bash
-cmake -S code -B build
-cmake --build build --target conformallab_tests -j$(nproc)
-ctest --test-dir build --output-on-failure
-```
-
-### CGAL-Tests + Beispiele (benötigt System-Boost)
-
-```bash
-cmake -S code -B build -DWITH_CGAL=ON
-cmake --build build -j$(nproc)
-ctest --test-dir build -R "^cgal\." --output-on-failure
-./build/examples/example_layout
-./bin/conformallab_core -i input.off -g euclidean -o layout.off
-```
-
-Erwartet: **158 Tests bestanden, 2 skipped** (die zwei `@Ignore`-Hessian-Stubs).
-
-### Interaktiver Viewer
-
-```bash
-cmake -S code -B build -DWITH_CGAL=ON
-cmake --build build -t example_viewer -j$(nproc)
-./build/examples/example_viewer data/off/example.off
-```
-
----
-
-## Öffentliche Header (`code/include/`)
-
-| Header | Beschreibung |
-|--------|-------------|
-| `clausen.hpp` | Clausen Cl₂, Lobachevsky Л, ImLi₂ |
-| `hyper_ideal_geometry.hpp` | ζ-Funktionen, lᵢⱼ, αᵢⱼ, σᵢ, σᵢⱼ |
-| `hyper_ideal_utility.hpp` | Tetraeder-Volumen (Meyerhoff / Kolpakov–Mednykh) |
-| `hyper_ideal_functional.hpp` | HyperIdeal Energie + Gradient auf `ConformalMesh` |
-| `hyper_ideal_hessian.hpp` | HyperIdeal Hessian (numerisch FD, symmetrisiert) |
-| `hyper_ideal_visualization_utility.hpp` | Poincaré-Disk-Projektion, Umkreis-Helfer |
-| `spherical_geometry.hpp` | Sphärische Bogenlänge, Halbwinkelformel |
-| `spherical_functional.hpp` | Sphärisch: Energie + Gradient + Gauge-Fix |
-| `spherical_hessian.hpp` | Sphärischer Hessian (∂α/∂u, Kosinussatz) |
-| `euclidean_geometry.hpp` | Euklidischer Eckenwinkel (t-Wert / atan2) |
-| `euclidean_functional.hpp` | Euklidisch: Energie + Gradient |
-| `euclidean_hessian.hpp` | Kotangenten-Laplace Hessian (Pinkall–Polthier) |
-| `newton_solver.hpp` | `newton_{euclidean,spherical,hyper_ideal}` + öffentliches `solve_linear_system` |
-| `conformal_mesh.hpp` | `ConformalMesh` = `CGAL::Surface_mesh<Point3>` + Property-Map-Helfer |
-| `mesh_builder.hpp` | `make_triangle` / `make_tetrahedron` / `make_quad_strip` / `make_fan` / … |
-| `mesh_io.hpp` | `read_mesh` / `write_mesh` / `load_mesh` / `save_mesh` |
-| `mesh_utils.hpp` | CGAL → Eigen Konvertierung (`cgal_to_eigen`) |
-| `serialization.hpp` | `save/load_result_json` + `save/load_result_xml` |
-| `gauss_bonnet.hpp` | `euler_characteristic`, `genus`, `gauss_bonnet_sum/rhs/deficit`, `check_gauss_bonnet`, `enforce_gauss_bonnet` |
-| `cut_graph.hpp` | `CutGraph` + `compute_cut_graph` (Tree-Cotree, Erickson–Whittlesey 2005) |
-| `layout.hpp` | `euclidean/spherical/hyper_ideal_layout` → `Layout2D/3D`; `MobiusMap`; `halfedge_uv`; Priority-BFS; `HolonomyData`; `normalise_*` |
-| `period_matrix.hpp` | `PeriodData`, `compute_period_matrix`, `reduce_to_fundamental_domain`, `is_in_fundamental_domain` |
-| `fundamental_domain.hpp` | `FundamentalDomain`, `compute_fundamental_domain_{genus1,}`, `tiling_copy`, `tiling_neighbourhood` |
-| `constants.hpp` | `conformallab::PI`, `TWO_PI` |
-
----
-
-## Projektstruktur
-
-```
-code/
-├── include/                          # Alle öffentlichen Header (Header-Only-Bibliothek)
-│   ├── conformal_mesh.hpp
-│   ├── mesh_builder.hpp
-│   ├── mesh_io.hpp / mesh_utils.hpp
-│   ├── newton_solver.hpp             # 3 Newton-Solver + solve_linear_system
-│   ├── layout.hpp                    # Priority-BFS, MobiusMap, halfedge_uv, Holonomie
-│   ├── serialization.hpp
-│   ├── gauss_bonnet.hpp
-│   ├── cut_graph.hpp                 # Tree-Cotree
-│   ├── period_matrix.hpp             # τ ∈ ℍ, SL(2,ℤ)-Reduktion (Genus 1)
-│   ├── fundamental_domain.hpp        # Parallelogramm, Kacheln; 4g-Polygon TODO Phase 8
-│   ├── hyper_ideal_{functional,hessian,geometry,utility,visualization_utility}.hpp
-│   ├── spherical_{functional,hessian,geometry}.hpp
-│   ├── euclidean_{functional,hessian,geometry}.hpp
-│   ├── clausen.hpp
-│   └── constants.hpp
-├── examples/
-│   ├── example_euclidean.cpp
-│   ├── example_hyper_ideal.cpp
-│   ├── example_layout.cpp            # Solve → Layout → OFF/JSON/XML + Round-Trip
-│   └── example_viewer.cpp            # Interaktiver libigl-Viewer
-├── src/
-│   ├── apps/v0/conformallab_cli.cpp  # CLI-App (Phase 5)
-│   └── viewer/simple_viewer.cpp
-├── tests/
-│   ├── *.cpp                         # conformallab_tests (kein CGAL)
-│   └── cgal/
-│       ├── test_conformal_mesh.cpp           # 14 Tests
-│       ├── test_hyper_ideal_functional.cpp   #  7 Tests
-│       ├── test_spherical_functional.cpp     # 12 Tests (1 skipped)
-│       ├── test_euclidean_functional.cpp     # 11 Tests (1 skipped)
-│       ├── test_euclidean_hessian.cpp        #  9 Tests
-│       ├── test_spherical_hessian.cpp        #  8 Tests
-│       ├── test_newton_solver.cpp            # 14 Tests
-│       ├── test_mesh_io.cpp                  #  9 Tests
-│       ├── test_pipeline.cpp                 #  5 Tests
-│       ├── test_layout.cpp                   #  8 Tests (Layout + JSON/XML)
-│       ├── test_phase6.cpp                   # 26 Tests (GB, CutGraph, Trilateration)
-│       └── test_phase7.cpp                   # 37 Tests (MobiusMap, Priority-BFS,
-│                                             #   halfedge_uv, Periodenmatrix, FD)
-└── deps/
-    ├── eigen-3.4.0/
-    ├── CGAL-6.1.1/
-    ├── libigl-2.6.0/
-    ├── glfw-3.4/
-    └── single_includes/              # CLI11, json.hpp
-```
-
----
-
-## Test-Suiten
-
-### `conformallab_tests` (CI — immer gebaut)
-
-Reine Mathe-Tests, nur Eigen: Clausen / Lobachevsky / ImLi₂, Hyper-ideal Geometrie, Tetraeder-Volumina.
-
-### `conformallab_cgal_tests` (lokal — `-DWITH_CGAL=ON`)
-
-| Suite | Tests | Was geprüft wird |
-|-------|------:|-----------------|
-| `ConformalMeshTopology` | 4 | Euler-Charakteristik, Vertex/Edge/Face-Anzahl |
-| `ConformalMeshTraversal` | 4 | Halfedge-Iteration, Valenz, Opposite |
-| `ConformalMeshProperties` | 5 | Property-Maps (λ, θ, idx, α, Geometrietyp) |
-| `ConformalMeshValidity` | 1 | CGAL-Validität für alle Factory-Meshes |
-| `HyperIdealFunctional` | 7 | FD-Gradient-Checks + Hessian-Symmetrie |
-| `SphericalFunctional` | 12 | Winkelformel + Gradient + Gauge-Fix (1 skipped) |
-| `EuclideanFunctional` | 11 | Winkelformel + Gradient (1 skipped) |
-| `EuclideanHessian` | 9 | Kotangenten-Laplace-Struktur, FD-Übereinstimmung, PSD, Nullraum |
-| `SphericalHessian` | 8 | Ableitungskorrektheit, NSD am Gleichgewicht |
-| `NewtonSolver` | 11 | Konvergenz (Eucl. ×3, Sphär. ×4, HyperIdeal ×4) |
-| `SparseQRFallback` | 3 | Full-Rank-LDLT · singuläre Matrix → QR · geschlossenes Mesh |
-| `MeshIO` | 9 | OFF/OBJ Round-Trips, Fehlerbehandlung |
-| `Pipeline` | 5 | End-to-End: Build → Setup → Solve → Export → Reload |
-| `Layout` | 8 | Kantenlängen-Erhaltung (Eucl./Sphär.), Poincaré-Disk |
-| `Serialization` | 2 | JSON- und XML-Round-Trips (DOF + Layout) |
-| `GaussBonnet` | 8 | χ, Genus, Summe/RHS, Defizit, Check, Enforce |
-| `CutGraph` | 6 | Tree-Cotree, offene/geschlossene Meshes, Flag–Index-Konsistenz |
-| `HyperbolicTrilateration` | 4 | Möbius + Kosinussatz: exakte Abstände, Disk-Inneres, off-origin |
-| `Normalisation` | 4 | Eukl. Schwerpunkt, Längenverhältnisse, Möbius-Zentrierung |
-| `MobiusMap` | 8 | Identity, Inverse, Compose, from_three, apply(Vector2d) |
-| `BestRootFace` | 2 | Gültige Wurzel-Fläche, Interior-Bonus |
-| `HalfedgeUV` | 4 | Größe = #Halfedges, Naht-Konsistenz, Randhalfedges = 0 |
-| `PriorityBFS` | 3 | Erfolg, kein Seam bei offenen Meshes, alle Vertices platziert |
-| `NormaliseEuclidean` | 2 | UV-Schwerpunkt = 0, halfedge_uv-Schwerpunkt = 0 |
-| `PeriodMatrix` | 7 | τ ∈ ℍ, SL(2,ℤ)-Reduktion, Ausnahme außerhalb ℍ |
-| `FundamentalDomain` | 7 | Genus-1-Parallelogramm CCW, Generatoren, g>1 leer |
-| `TilingCopy/Neighbourhood` | 4 | Verschiebung korrekt, Anzahl Kacheln |
-| **Gesamt** | **158** | **2 skipped** (Hessian-Stubs, identisch mit Java `@Ignore`) |
-
----
-
-## Newton-Solver & SparseQR-Fallback
-
-`newton_solver.hpp` stellt drei Solver mit einheitlicher Schnittstelle bereit:
-
-```
-NewtonResult newton_euclidean  (mesh, x0, maps [, tol, max_iter])
-NewtonResult newton_spherical  (mesh, x0, maps [, tol, max_iter])
-NewtonResult newton_hyper_ideal(mesh, x0, maps [, tol, max_iter, hess_eps])
-```
-
-Jede Iteration: Gradient **G** → Hessian **H** → löse **H·Δx = −G** (SimplicialLDLT, Fallback SparseQR) → Backtracking-Liniensuche.
-
-| Geometrie | **G** | **H**-Vorzeichen |
-|-----------|-------|-----------------|
-| Euklidisch | Θ_v − Σα_v | PSD → LDLT auf H |
-| Sphärisch | Θ_v − Σα_v | NSD → LDLT auf **−H** |
-| HyperIdeal | Σβ_v − Θ_v | PSD → LDLT auf H |
-
-**SparseQR-Fallback** (`solve_linear_system`): Bei rangdefizientem **H** (Gauge-Moden bei geschlossenen Meshes ohne gepinnten Vertex) findet SparseQR den minimalen Newton-Schritt orthogonal zum Nullraum.
-
----
-
-## Mathematischer Umfang — C++ vs. Java-Original
-
-| Mathematische Schicht | Java ConformalLab | conformallab++ |
-|---|---|---|
-| Euklidisches Funktional — Energie, Gradient | ✅ | ✅ |
-| Sphärisches Funktional — Energie, Gradient, Gauge-Fix | ✅ | ✅ |
-| HyperIdeal Funktional — Energie, Gradient | ✅ | ✅ |
-| Inversive-Distance-Funktional (Luo 2004) | ✅ | ❌ nicht portiert |
-| Euklidischer Hessian — Kotangenten-Laplace | ✅ analytisch | ✅ analytisch |
-| Sphärischer Hessian — ∂α/∂u aus Kosinussatz | ✅ analytisch | ✅ analytisch |
-| HyperIdeal Hessian — ζ → lᵢⱼ → β/α Kette | ✅ analytisch | ⚠️ symmetrisches FD |
-| Newton-Solver | ✅ | ✅ |
-| SparseQR-Fallback für Gauge-Moden | ? | ✅ |
-| Kegelmetriken — vorgeschriebenes Θ_v ≠ 2π | ✅ vollständig | ⚠️ nur Datenstruktur |
-| Layout / Einbettung — ℝ² / H² / S² | ✅ | ✅ Priority-BFS, alle drei |
-| Exakte hyperbolische Trilateration | ✅ Möbius | ✅ Möbius + Kosinussatz |
-| halfedge_uv — Naht-bewusstes UV (Texturatlas) | ✅ | ✅ |
-| Gauss–Bonnet Konsistenzprüfung | ✅ | ✅ |
-| Tree-Cotree-Schnittgraph (2g Kanten) | ✅ | ✅ Erickson–Whittlesey |
-| Holonomie / Monodromie — Euklidisch (Translationen) | ✅ | ✅ |
-| Holonomie — Hyperbolisch (SU(1,1) Möbius-Mappe) | ✅ | ✅ |
-| Periodenmatrix τ — Genus 1 (SL(2,ℤ)-reduziert) | ✅ | ✅ |
-| Fundamentalbereich-Polygon — Genus 1 | ✅ | ✅ CCW-Parallelogramm |
-| 4g-Polygon-Randlauf — Genus g > 1 | ✅ | ❌ TODO Phase 8 |
-| Periodenmatrix Siegel Ω — Genus g ≥ 2 | ✅ | ❌ TODO Phase 8 |
-| Globale Uniformisierung — Genus g ≥ 2 | ✅ | ❌ Phase 8 geplant |
-| Clausen / Lobachevsky / ImLi₂ | ✅ | ✅ |
-| Poincaré-Disk / Lorentz-Boost Visualisierung | ✅ | ✅ |
-| Mesh I/O + Serialisierung | ✅ XML/CoHDS | ✅ OFF/OBJ/PLY + JSON/XML |
-| Interaktiver Viewer | ✅ jReality | ✅ libigl/GLFW |
-
-### HyperIdeal Hessian — numerisch vs. analytisch
-
-Der analytische Hessian des HyperIdeal-Funktionals erfordert Differentiation durch die Kette `(bᵢ, aₑ) → lᵢⱼ → ζ₁₃/₁₄/₁₅ → αᵢⱼ / βᵢ` (vier Vertex-Typ-Kombinationen pro Kante). conformallab++ verwendet stattdessen einen symmetrisierten Finite-Differenzen-Hessian:
-
-```
-H[i,j] = ( G(x + ε·eⱼ)[i] − G(x − ε·eⱼ)[i] ) / (2ε)
-```
-
-O(ε²)-genau (≈ 10⁻¹⁰ relativer Fehler bei ε = 10⁻⁵), PSD durch strikte Konvexität (Springborn 2020), kostet n zusätzliche Gradient-Auswertungen pro Newton-Schritt. Für Meshes mit < 500 DOFs ist der Unterschied in der Wandzeit vernachlässigbar. Der analytische Hessian ist für Phase 8 geplant.
-
----
-
-## Für Mathematiker — Bibliothek erweitern
-
-### Mentales Modell
-
-```
-ConformalMesh           — Halfedge-Mesh (CGAL::Surface_mesh)
-    + Property-Maps     — per-Vertex/Edge Daten (λ, θ, α, DOF-Index, …)
-
-Maps-Struct             — sammelt alle Property-Maps für ein Funktional
-    theta_v[v]          — Zielwinkel bei Vertex v  (Eingabe)
-    v_idx[v]            — DOF-Index, oder −1 wenn gepinnt
-    e_idx[e]            — DOF-Index für Kanten-DOFs (nur HyperIdeal)
-
-x ∈ ℝⁿ                 — DOF-Vektor, den der Solver optimiert
-
-evaluate_*(mesh, x, maps)  → { Energie, Gradient, … }
-newton_*(mesh, x0, maps)   → { x*, Iterationen, converged, … }
-```
-
-Die Mesh-Geometrie (Vertex-Positionen) dient nur zur Initialisierung der Log-Kantenlängen λ°. Danach arbeitet der Solver ausschließlich im x-Raum.
-
-### Neues Funktional hinzufügen
-
-1. **Maps-Struct**: `setup_my_maps(mesh)` mit Property-Maps für λ, θ_v, v_idx
-2. **Energie + Gradient**: Schleife über `mesh.faces()`, akkumuliere in `grad[v_idx[v]]`
-3. **Gradient-Check**: Finite-Differenzen-Verifikation (Vorlage in jedem `test_*_functional.cpp`)
-4. **Newton-Solver**: `solve_linear_system(H, -G, &used_fallback)` direkt nutzen
-
-### Halfedge-Mesh navigieren
-
-```cpp
-for (auto f : mesh.faces()) {
-    auto h0 = mesh.halfedge(f);
-    auto h1 = mesh.next(h0);
-    auto h2 = mesh.next(h1);
-
-    Vertex_index v_opp = mesh.target(h2);  // dem Halfedge h0 gegenüberliegend
-    int dof = maps.v_idx[v_opp];           // −1 = gepinnt
-
-    bool is_boundary = mesh.is_border(mesh.opposite(h0));
-}
-```
-
-### Neue Daten am Mesh befestigen
-
-```cpp
-auto [curv, created] = mesh.add_property_map<Vertex_index, double>("v:my_curv", 0.0);
-curv[v] = 1.234;
-```
-
-### Schnell-Start-Checkliste
-
-1. `examples/example_layout.cpp` lesen — zeigt die vollständige Pipeline in ~120 Zeilen
-2. `cmake -S code -B build -DWITH_CGAL=ON && cmake --build build --target example_layout`
-3. Gradient-Check-Test in `tests/cgal/` hinzufügen (beliebigen `GradientCheck_*`-Block kopieren)
-4. Verschiedene Zielwinkel ausprobieren: `maps.theta_v[v] = M_PI / 3` für alle Innen-Vertices. Die Gauss–Bonnet-Bedingung Σ(2π − Θ_v) = 2π·χ(M) muss erfüllt sein.
-5. Konvergenz beobachten: `NewtonResult` enthält `iterations` und `grad_inf_norm`
-
-### Weiterführende Literatur
-
-| Quelle | Bezug |
-|--------|-------|
-| Springborn — *Ideal Hyperbolic Polyhedra and Discrete Uniformization* (2020) | HyperIdeal-Funktional; ζ₁₃/₁₄/₁₅ in `hyper_ideal_geometry.hpp` |
-| Pinkall, Polthier — *Computing Discrete Minimal Surfaces* (1993) | Kotangenten-Laplace in `euclidean_hessian.hpp` |
-| Luo — *Combinatorial Yamabe Flow on Surfaces* (2004) | Inversive-Distance-Funktional (noch nicht portiert) |
-| Bobenko, Springborn — *Variational Principles for Circle Patterns* (2004) | Hintergrund für das Winkelsum-Variationsprinzip |
-| Erickson, Whittlesey — *Greedy Optimal Homotopy and Homology Generators* (SODA 2005) | Tree-Cotree-Algorithmus in `cut_graph.hpp` |
-
----
-
-## Schlüssel-Designentscheidungen
-
-**CGAL als CoHDS-Ersatz.** `CGAL::Surface_mesh<Point3>` ersetzt die Java-`CoHDS`-Halfedge-Datenstruktur. Vertex/Edge/Face/Halfedge-Deskriptoren sind typisierte Integer.
-
-**Property-Maps.** `mesh.add_property_map<Vertex_index, double>("v:lambda", 0.0)` ersetzt das Java-Adapter/Decorator-Pattern.
-
-**DOF-Vektor-Konvention.** Alle Funktionale verwenden `x` indiziert durch `v_idx[v]` / `e_idx[e]` (−1 = gepinnt). Einheitlich über alle drei Geometrien.
-
-**Priority-BFS.** Faces werden in aufsteigender BFS-Tiefe verarbeitet (Min-Heap über `depth = max(depth[v_src], depth[v_tgt]) + 1`). Dies minimiert die Akkumulation von Trilaterations-Fehlern — je weiter eine Fläche vom Ursprung entfernt ist, desto später wird sie platziert.
-
-**halfedge_uv-Semantik.** `halfedge_uv[h.idx()]` ist das UV von `source(h)` aus Sicht von `face(h)`. An Naht-Halfedges tragen die beiden gegenüberliegenden Halfedges unterschiedliche UV-Werte — so erhält jede Fläche ihre eigene Kopie eines Naht-Vertex für GPU-Texturatlas ohne Vertex-Duplizierung.
-
-**HyperIdeal Hessian via FD.** Der analytische Hessian durch `ζ13/14/15 → lij → β/α` ist auf Phase 8 verschoben. Ein symmetrischer FD-Hessian ist O(ε²)-genau, PSD durch strikte Konvexität und für < 500 DOFs ausreichend.
-
-**Sphärischer Hessian Vorzeichen.** Die sphärische Energie ist **konkav** (Hessian NSD). Newton löst `(−H)·Δx = G`, das Vorzeichen wird transparent in `newton_spherical` behandelt.
-
----
-
-## CI
-
-Tests laufen automatisch bei Push auf `main`, `dev` und `claude/**`-Branches via selbst-gehostetem Gitea-Actions-Runner (`eulernest`, ARM64). **Nur `conformallab_tests` läuft in CI** (kein Boost/CGAL dort).
-
-```bash
-# CI-Image neu bauen und pushen
-docker buildx build \
-  --platform linux/arm64 \
-  -f .gitea/docker/Dockerfile.ci-cpp \
-  -t git.eulernest.eu/conformallab/ci-cpp:latest \
-  --push \
-  .gitea/docker/
-```
-
----
-
-## Roadmap
-
-> **Legende:**  ✅ abgeschlossen · 🔲 geplant
->
-> **Grenze Portierung / neue Forschung:**  
-> Phase 1–7 sind direkte Portierungen aus dem Java-Original bzw. seiner Dissertation.  
-> Ab Phase 8 geht die Arbeit über den Umfang der Java-Bibliothek hinaus.  
-> — Phase 8 (CGAL-Paket) ist **Infrastruktur**, kein neuer Algorithmus.  
-> — Phase 9 (Inversive-Distance, Analytischer Hessian) ist **Portierung** ausstehender Java-Features.  
-> — Phase 10+ ist **eigenständige Forschung**, die über das Java-Original hinausgeht.
-
----
-
-### ◼ Portierungsphase abgeschlossen
-
-```
-Phase 1   Clausen / Lobachevsky / ImLi₂                     ✅
-Phase 2   Hyper-ideal Geometrie (ζ, lᵢⱼ, αᵢⱼ, σᵢ)         ✅
-Phase 3   CGAL-Infrastruktur + alle drei Funktionale
-          + analytische Hessians (Eucl. + Sphär.)            ✅
-Phase 4   Newton-Solver (SimplicialLDLT + SparseQR-Fallback)
-          + Mesh-I/O + Beispielprogramme                     ✅
-Phase 5   Priority-BFS-Layout + CLI + JSON/XML               ✅  95 Tests
-
-Phase 6   Layout-Parität I                                   ✅  121 Tests
-          → gauss_bonnet.hpp  — χ, Genus, Σ(2π-Θ_v) Check + Enforce
-          → cut_graph.hpp     — Tree-Cotree (Erickson–Whittlesey 2005), 2g Schnitt-Kanten
-          → Exakte hyperbolische Trilateration (Möbius + Kosinussatz)
-          → normalise_{euclidean,hyperbolic,spherical}
-
-Phase 7   Layout-Parität II                                  ✅  158 Tests
-          → MobiusMap  — T(z)=(az+b)/(cz+d), from_three, compose, inverse
-          → halfedge_uv — naht-bewusstes UV pro Halfedge (GPU-Texturatlas)
-          → Möbius-Holonomie als SU(1,1)-Isometrie (hyperbolisch)
-          → period_matrix.hpp — τ = ω₂/ω₁ ∈ ℍ, SL(2,ℤ)-Reduktion
-          → fundamental_domain.hpp — CCW-Parallelogramm, Kachelung
-```
-
----
-
-### ◼ Infrastruktur (über Java-Bibliothek hinaus)
-
-```
-Phase 8   CGAL-Paket-Struktur                               🔲  (nächste Phase)
-
-  Ziel: conformallab++ als eigenständiges CGAL-Paket, das in CGAL integriert
-  werden kann und dessen Konventionen vollständig erfüllt.
-
-  8a — Traits-Klasse & Konzepte
-       → include/CGAL/Conformal_map_traits.h
-         Trennt MeshType, KernelType, ScalarType vom Algorithmus.
-         Ermöglicht Nutzung mit beliebigem CGAL-kompatiblem Mesh.
-       → Konzept-Checks (static_assert / CGAL_concept_check)
-
-  8b — Öffentliche CGAL-Header-Hierarchie
-       → include/CGAL/Discrete_conformal_map.h  (zentraler Nutzer-Header)
-       → include/CGAL/Conformal_newton_solver.h
-       → include/CGAL/Conformal_layout.h
-       → include/CGAL/Conformal_cut_graph.h
-       → include/CGAL/conformal_map_package.h  (Package-Description)
-       Alle bestehenden include/conformallab/*.hpp bleiben als Impl.-Detail.
-
-  8c — Dokumentation im CGAL-Stil
-       → doc/Conformal_map/PackageDescription.txt
-       → doc/Conformal_map/fig/  (Pipeline-Diagramme)
-       → Doxygen-Kommentare für alle öffentlichen Konzepte + Funktionen
-       → User_manual.md + Reference_manual.md
-
-  8d — CGAL-Testformat
-       → test/Conformal_map/  (CMakeLists.txt im CGAL-Format)
-       Bestehende GTest-Tests bleiben; CGAL-Tests kommen als zweites Format.
-
-  8e — Declarative YAML-Pipeline
-       → Leichtgewichtiges YAML-Format für reproduzierbare Experimente
-         (Spezifikation bereits in doc/architecture/overall_pipeline.md)
-       → Validator: prüft require/provide-Tokens vor der Ausführung
-       → Einbindung in CLI-App: conformallab_core --pipeline experiment.yml
-```
-
----
-
-### ◼ Ausstehende Portierung (Java-Features noch nicht übertragen)
-
-```
-Phase 9   Verbleibende Java-Parität                         🔲
-
-  9a — Inversive-Distance-Funktional (Luo 2004 / Bowers–Stephenson)
-       → inversive_distance_functional.hpp  (folgt exakt dem Muster der
-         bestehenden drei Funktionale — niedrigstes Risiko)
-       → newton_inversive_distance()
-       → Neue Test-Suite: test_inversive_distance.cpp
-
-  9b — Analytischer HyperIdeal-Hessian
-       → Direkte Ableitung durch die Kette
-         (b_i, a_e) → l_ij → ζ₁₃/ζ₁₄/ζ₁₅ → α_ij / β_i
-       → Ersetzt den symmetrischen FD-Hessian in hyper_ideal_hessian.hpp
-       → Relevant für Meshes > 500 DOFs (aktueller FD-Hessian ist dort langsam)
-       → Aufwand: ~2 Wochen (viele verschachtelte Fallunterscheidungen)
-
-  9c — 4g-Polygon-Randlauf (Genus g > 1)
-       → Boundary-Walk auf dem aufgeschnittenen Mesh
-       → Befüllt fundamental_domain.hpp für g > 1 (aktuell: leeres Objekt)
-       → Algorithmus-Skizze bereits als TODO(Phase 8) in fundamental_domain.hpp
-```
-
----
-
-### ◼ Neue Forschung (über das Java-Original hinaus)
-
-> Ab hier gibt es keine direkte Java-Referenzimplementierung mehr.
-> Jedes Item ist eigenständige mathematische Arbeit.
-
-```
-Phase 10  Globale Uniformisierung Genus g ≥ 2               🔲  (Forschung)
-
-  10a — Holomorphe Differentiale auf diskreten Flächen
-        Integration ω_i längs der b-Zyklen des Schnittgraphen.
-        Mathematische Grundlage: Bobenko–Springborn (2004), §6.
-
-  10b — Siegel-Periodenmatrix Ω ∈ H_g (g×g, g ≥ 2)
-        Ω_ij = ∫_{b_j} ω_i  — komplexe symmetrische Matrix,
-        Im(Ω) positiv definit (Siegel-Oberhalbebene H_g).
-        Reduktion auf den Siegel-Fundamentalbereich via Sp(2g,ℤ).
-
-  10c — Vollständige Uniformisierung
-        Für g ≥ 2: Einbettung als H²/Γ mit Γ ⊂ PSL(2,ℝ) Fuchssche Gruppe.
-        Erfordert 10a + 10b + stabilen Cut-Graph für g ≥ 2 (Phase 9c).
-```
-
----
-
-## Ursprung & Danksagung
-
-conformallab++ wäre ohne die Grundlagenarbeit von **Stefan Sechelmann** nicht möglich.
-Die Algorithmen, die Variationsformulierung und die Idee, diskrete konforme Geometrie
-als Newton-Problem auf Winkel-Summen-Energie-Funktionalen zu behandeln, stammen aus:
 
 | | |
 |---|---|
-| **Dissertation** | Stefan Sechelmann — *Variational Methods for Discrete Surface Parameterization: Applications and Implementation*, TU Berlin 2016 |
+| **API reference (Doxygen HTML)** — every public class, function and named-parameter helper | https://tmoussa.codeberg.page/ConformalLabpp/ |
-| **DOI** | [10.14279/depositonce-5415](https://depositonce.tu-berlin.de/items/8e2988b2-d991-45b5-aad5-9fb7988f3b2f) |
+| **Getting started** — build modes, single-test invocation, CLI, Docker | [doc/getting-started.md](doc/getting-started.md) |
-| **Java-Originalbibliothek** | [github.com/varylab/conformallab](https://github.com/varylab/conformallab) |
+| **Pipeline API** — all three geometries, holonomy, serialisation | [doc/api/pipeline.md](doc/api/pipeline.md) |
-| **Website** | [sechel.de](https://sechel.de/) |
+| **Public headers** — all public headers with descriptions | [doc/api/headers.md](doc/api/headers.md) |
-| **LinkedIn** | [linkedin.com/in/sechel](https://www.linkedin.com/in/sechel/) |
+| **Test suites** — per-suite breakdown and counts (single source of truth) | [doc/api/tests.md](doc/api/tests.md) |
-
+| **Extending** — new functionals, geometry modes, porting from Java | [doc/api/extending.md](doc/api/extending.md) |
-Die Dissertation steht unter Creative Commons Attribution ShareAlike 4.0 (CC BY-SA 4.0).
+| **Processing unit contracts** — preconditions / provides table | [doc/api/contracts.md](doc/api/contracts.md) |
+| **CGAL package design** — Phase 8 target, YAML pipeline | [doc/api/cgal-package.md](doc/api/cgal-package.md) |
+| **Architecture & pipeline diagram** | [doc/architecture/overall_pipeline.md](doc/architecture/overall_pipeline.md) |
+| **geometry-central comparison** — shared core, demarcation, adoption candidates, scientific added value | [doc/architecture/geometry-central-comparison.md](doc/architecture/geometry-central-comparison.md) |
+| **Design decisions** — key architectural choices + rationale | [doc/architecture/design-decisions.md](doc/architecture/design-decisions.md) |
+| **Project structure** — directory tree + build targets | [doc/architecture/project-structure.md](doc/architecture/project-structure.md) |
+| **Discrete conformal theory** — mathematical background for collaborators | [doc/math/discrete-conformal-theory.md](doc/math/discrete-conformal-theory.md) |
+| **Validation** — known analytic results + how to verify them | [doc/math/validation.md](doc/math/validation.md) |
+| **Validation protocol** — concrete commands with expected outputs | [doc/math/validation-protocol.md](doc/math/validation-protocol.md) |
+| **Tutorial: add a new functional** — step-by-step Inversive-Distance port | [doc/tutorials/add-inversive-distance.md](doc/tutorials/add-inversive-distance.md) |
+| **Declarative YAML pipeline** — concept, token vocabulary, 5 examples | [doc/concepts/declarative-pipeline.md](doc/concepts/declarative-pipeline.md) |
+| **Geometry modes** — Euclidean / Spherical / HyperIdeal comparison | [doc/math/geometry-modes.md](doc/math/geometry-modes.md) |
+| **References** — all papers by module | [doc/math/references.md](doc/math/references.md) |
+| **Software landscape** — how conformallab++ relates to libigl, CGAL, geometry-central | [doc/math/software-landscape.md](doc/math/software-landscape.md) |
+| **Novelty statement** — unique features, target audience, what this is not | [doc/math/novelty-statement.md](doc/math/novelty-statement.md) |
+| **Complexity & scalability** — O() analysis, measured timings on real meshes, HyperIdeal bottleneck | [doc/math/complexity.md](doc/math/complexity.md) |
+| **Roadmap** — Phases 1–10 | [doc/roadmap/phases.md](doc/roadmap/phases.md) |
+| **Java parity table** — what is ported, what is planned | [doc/roadmap/java-parity.md](doc/roadmap/java-parity.md) |
+| **Contributing** — language policy, test standards, release flow | [doc/contributing.md](doc/contributing.md) |
+| **Claude Code context** | [CLAUDE.md](CLAUDE.md) |
 
 ---
 
-## Lizenz
+## Citing
 
-conformallab++ steht unter der MIT-Lizenz (siehe [LICENSE](LICENSE)).
+If you use conformallab++ in your research, please cite it using the metadata
+in [`CITATION.cff`](CITATION.cff).  GitHub and Codeberg show a "Cite this repository"
+button that generates BibTeX and APA automatically.
+
+The primary algorithmic source is:
+
+> Stefan Sechelmann — *Variational Methods for Discrete Surface Parameterization:
+> Applications and Implementation*, TU Berlin 2016.
+> DOI: [10.14279/depositonce-5415](https://depositonce.tu-berlin.de/items/8e2988b2-d991-45b5-aad5-9fb7988f3b2f)
+
+---
+
+## Bugs & questions
+
+- **Bug reports / feature requests:** [Gitea Issues](https://git.eulernest.eu/conformallab/ConformalLabpp/issues)
+- **Code mirror (read-only):** [Codeberg](https://codeberg.org/TMoussa/ConformalLabpp)
+- **Contact:** Tarik Moussa · Tarik.moussa95@gmail.com
+
+---
+
+## License
+
+conformallab++ is released under the MIT License (see [LICENSE](LICENSE)).  
+Copyright © 2024–2026 Tarik Moussa.  
+The dissertation (Sechelmann 2016) is CC BY-SA 4.0.

code/.gitignore

@@ -13,6 +13,7 @@ deps/*
 !deps/tarballs
 !deps/single_includes/
 !deps/CMakeLists.txt
+!deps/THIRD-PARTY-LICENSES.md
 
 # macOS iCloud Drive duplicates ("file 2.cpp", "file 2.hpp", …)
 * 2.*
@@ -40,6 +41,8 @@ Thumbs.db
 *.lo
 *.o
 *.obj
+# Exception: mesh data files in code/data/ are not compiled objects
+!data/**/*.obj
 
 # Precompiled Headers
 *.gch

code/CMakeLists.txt

@@ -7,24 +7,43 @@ message(STATUS "Configuring ${PROJECT_NAME}...")
 
 # ── Build modes ────────────────────────────────────────────────────────────────
 #
-#   Default (CI / tests-only): only Eigen + GTest are required.
+#   Default (CI fast / pure-math tests):
+#     cmake -S code -B build
+#     Only Eigen + GTest required.  36 non-CGAL tests.
 #
-#   -DWITH_CGAL=ON   builds the conformallab_core CLI app (needs CGAL).
+#   -DWITH_CGAL_TESTS=ON   CGAL test suite only — no viewer, no CLI app.
-#                    Automatically enables WITH_VIEWER because the app uses
+#     cmake -S code -B build -DWITH_CGAL_TESTS=ON
-#                    the viewer library for mesh visualisation.
+#     Requires: system Boost headers (apt install libboost-dev).
+#     Builds:   conformallab_cgal_tests  (158 tests).
+#     Does NOT require wayland-scanner, GLFW, libigl or a display.
+#     Use this in headless CI.
 #
-#   -DWITH_VIEWER=ON builds the viewer library standalone (libigl/GLFW/GLAD).
+#   -DWITH_CGAL=ON         Full build: CLI app + viewer + examples + CGAL tests.
+#     cmake -S code -B build -DWITH_CGAL=ON
+#     Requires: Boost + Wayland/X11 dev headers (wayland-scanner, libx11-dev …).
+#     Automatically enables WITH_VIEWER.
+#     Use this for local development with the interactive viewer.
+#
+#   -DWITH_VIEWER=ON        Viewer library only (libigl / GLFW / GLAD).
 #
 # ──────────────────────────────────────────────────────────────────────────────
-option(WITH_CGAL   "Build conformallab_core app (requires CGAL + Viewer)" OFF)
+option(WITH_CGAL_TESTS "Build CGAL test suite without viewer/CLI (headless CI)" OFF)
-option(WITH_VIEWER "Build viewer library (libigl / GLFW / GLAD)"          OFF)
+option(WITH_CGAL       "Build conformallab_core CLI app + viewer + CGAL tests"  OFF)
+option(WITH_VIEWER     "Build viewer library (libigl / GLFW / GLAD)"            OFF)
 
-# The CLI app always needs the viewer; enable it implicitly.
+# WITH_CGAL_TESTS is a strict subset of WITH_CGAL — no viewer, no CLI.
+# WITH_CGAL (full build) implies WITH_VIEWER.
 if(WITH_CGAL AND NOT WITH_VIEWER)
     message(STATUS "WITH_CGAL implies WITH_VIEWER – enabling automatically.")
     set(WITH_VIEWER ON CACHE BOOL "" FORCE)
 endif()
 
+# Propagate Boost requirement for both CGAL modes + headers_check (which
+# also compiles CGAL headers, hence needs Boost::graph_traits).
+if(WITH_CGAL OR WITH_CGAL_TESTS OR CONFORMALLAB_HEADERS_CHECK)
+    find_package(Boost REQUIRED)
+endif()
+
 # ── Standard settings ──────────────────────────────────────────────────────────
 set(CMAKE_CXX_STANDARD 17)
 set(CMAKE_CXX_STANDARD_REQUIRED ON)
@@ -36,9 +55,80 @@ if(NOT CMAKE_BUILD_TYPE)
   set(CMAKE_BUILD_TYPE "Release" CACHE STRING "Build type" FORCE)
 endif()
 
+# ── ccache integration (lever D) ───────────────────────────────────────────────
+#
+# Detect `ccache` on the host and prepend it to the compile + link launchers.
+# Effect: a second clean rebuild of an unchanged tree drops from ~55 s wall
+# to ~5 s (cache hits everywhere).  Costs nothing when ccache is absent.
+# Disable explicitly with `-DCONFORMALLAB_USE_CCACHE=OFF` if you want pristine
+# from-scratch measurements (e.g. when re-running scripts/quality/coverage.sh).
+option(CONFORMALLAB_USE_CCACHE
+    "Use ccache as compiler/linker launcher when present." ON)
+if(CONFORMALLAB_USE_CCACHE)
+    find_program(CCACHE_PROGRAM ccache)
+    if(CCACHE_PROGRAM)
+        set(CMAKE_C_COMPILER_LAUNCHER   "${CCACHE_PROGRAM}")
+        set(CMAKE_CXX_COMPILER_LAUNCHER "${CCACHE_PROGRAM}")
+        message(STATUS "ccache: enabled (${CCACHE_PROGRAM})")
+    endif()
+endif()
+
+# ── Dev-iteration build mode (lever C, opt-in) ─────────────────────────────────
+#
+# Turns off Unity Build target-wide.  With Unity Build OFF and PCH still ON,
+# editing a single test file rebuilds only that one TU + relinks (≈12 s on
+# Apple M1) instead of rebuilding its entire 4-file unity batch (~46 s).
+#
+# Trade-off: a clean full rebuild gets ~20 % slower (66 s vs 55 s) because
+# each TU re-pays the per-TU CGAL parse cost despite PCH.  Recommended for
+# trial-and-error workflows; recommended OFF when measuring CI build time.
+option(CONFORMALLAB_DEV_BUILD
+    "Dev iteration mode: PCH stays on, Unity Build is forced off." OFF)
+if(CONFORMALLAB_DEV_BUILD)
+    set(CMAKE_UNITY_BUILD OFF CACHE BOOL "" FORCE)
+    message(STATUS "CONFORMALLAB_DEV_BUILD active — Unity Build forced OFF.")
+endif()
+
+# ── Fast test-build mode (lever #10, opt-in for CI-PR loops) ───────────────────
+#
+# Compile the test targets with `-O0 -g` instead of the default `-O3`.
+# The Eigen + CGAL templates dominate the BACKEND (CodeGen + Opt) phase
+# of every TU at ~55 % of wall time (~9.3 s of a 17 s TU per
+# `clang -ftime-trace`).  Dropping to `-O0` collapses that phase to
+# <2 s and yields ~40 % faster full rebuilds.  The downside is that
+# the resulting binaries are 2-5× slower to RUN — fine for "does it
+# compile + do all 259 unit tests pass?" CI loops, NOT fine for any
+# scalability or benchmark workload.
+#
+# Library/installable code is never affected; only the test
+# executables compiled into build-*/ pick this flag up.
+option(CONFORMALLAB_FAST_TEST_BUILD
+    "Compile test executables with -O0 -g for faster CI / dev loops." OFF)
+if(CONFORMALLAB_FAST_TEST_BUILD)
+    message(STATUS "CONFORMALLAB_FAST_TEST_BUILD active — tests compile at -O0 -g.")
+endif()
+
 if(CMAKE_CXX_COMPILER_ID MATCHES "Clang|GNU")
+  # ─── Compiler-warning policy ─────────────────────────────────────────────
+  # `-Wall -Wextra -Wpedantic` is the project default for first-party code.
+  # Vendored deps under code/deps/ get a separate, looser policy (handled
+  # via per-target SYSTEM include marking when they are pulled in).
+  #
+  # `CONFORMALLAB_WARNINGS_AS_ERRORS=ON` flips on `-Werror` — used in CI's
+  # promotion-track and by `scripts/quality/sanitizers.sh` to make sure no
+  # new warning class slips in unannounced.  Off by default so regular
+  # builds on slightly older toolchains aren't broken by a new GCC's
+  # added warning.
+  option(CONFORMALLAB_WARNINGS_AS_ERRORS
+    "Treat compiler warnings as errors (-Werror)." OFF)
+
   add_compile_options(-Wall -Wextra -Wpedantic)
 
+  if(CONFORMALLAB_WARNINGS_AS_ERRORS)
+    add_compile_options(-Werror)
+    message(STATUS "Warnings-as-errors mode active (-Werror).")
+  endif()
+
   # AddressSanitizer only in Debug (gtest_discover_tests runs the binary at
   # configure time and hangs with ASan enabled).
   if(CMAKE_BUILD_TYPE STREQUAL "Debug" AND NOT BUILD_TESTING)
@@ -47,20 +137,29 @@ if(CMAKE_CXX_COMPILER_ID MATCHES "Clang|GNU")
   endif()
 endif()
 
-# ── GTest (always – tests are always built) ────────────────────────────────────
+# ── GTest (only when tests are enabled) ────────────────────────────────────────
+#
+# CMake's standard `BUILD_TESTING` option (defaults ON via include(CTest))
+# gates the entire test subtree below.  Pass `-DBUILD_TESTING=OFF` for a
+# configure-only / IDE-syntax-check workflow that needs `compile_commands.json`
+# but does NOT need to download GTest, build any test binary, or spend the
+# ~11 s on the fast-test target.
 include(FetchContent)
-include(CTest)
+include(CTest)               # also defines BUILD_TESTING (default ON)
-enable_testing()
 
-FetchContent_Declare(
+if(BUILD_TESTING)
-    googletest
+    enable_testing()
-    GIT_REPOSITORY https://github.com/google/googletest.git
+
-    GIT_TAG        v1.14.0
+    FetchContent_Declare(
-)
+        googletest
-set(gtest_force_shared_crt ON CACHE BOOL "" FORCE)
+        GIT_REPOSITORY https://github.com/google/googletest.git
-set(INSTALL_GTEST          OFF CACHE BOOL "" FORCE)
+        GIT_TAG        v1.14.0
-set(BUILD_GMOCK            OFF CACHE BOOL "" FORCE)
+    )
-FetchContent_MakeAvailable(googletest)
+    set(gtest_force_shared_crt ON CACHE BOOL "" FORCE)
+    set(INSTALL_GTEST          OFF CACHE BOOL "" FORCE)
+    set(BUILD_GMOCK            OFF CACHE BOOL "" FORCE)
+    FetchContent_MakeAvailable(googletest)
+endif()
 
 # ── External deps (lazy tarball extraction) ────────────────────────────────────
 add_subdirectory(deps)
@@ -85,11 +184,6 @@ endif()
 
 # ── Core CLI app (optional, requires CGAL + Viewer) ───────────────────────────
 if(WITH_CGAL)
-    # CGAL 6.x still needs Boost.Config headers unconditionally.
-    # Install via: brew install boost  (macOS)
-    #              apt install libboost-dev  (Debian/Ubuntu)
-    find_package(Boost REQUIRED)
-
     add_executable(${PROJECT_NAME} src/apps/v0/conformallab_cli.cpp)
     target_include_directories(${PROJECT_NAME} SYSTEM PRIVATE
         ${CMAKE_CURRENT_SOURCE_DIR}/deps/single_includes
@@ -111,5 +205,100 @@ if(WITH_CGAL)
     add_subdirectory(examples)
 endif()
 
-# ── Tests (always) ────────────────────────────────────────────────────────────
+# ── Tests (gated on BUILD_TESTING) ────────────────────────────────────────────
-add_subdirectory(tests)
+#
+# Default ON (CTest convention).  Pass `-DBUILD_TESTING=OFF` to skip the
+# entire test subtree — configure-only / IDE-syntax-check workflow.
+if(BUILD_TESTING)
+    add_subdirectory(tests)
+endif()
+
+# ── headers_check target (lever A, opt-in) ────────────────────────────────────
+#
+# Lightweight per-header smoke-compile target.  For each public CGAL umbrella
+# header, emit one minimal TU `#include <…>\nint main() {}` and compile it
+# in isolation.  Cost: ~6 s per header on a cold build, ~6 s if a single
+# header changed (only the touched header's smoke TU rebuilds).
+#
+# Use case: "did my Phase-N refactor break the public API surface?" without
+# waiting 55 s for the full CGAL test build.  Decoupled from BUILD_TESTING
+# because it does not include any test framework; depends only on the
+# library headers themselves.
+#
+# Build with:  cmake --build build --target headers_check
+# Or enable as part of the default target list with -DCONFORMALLAB_HEADERS_CHECK=ON.
+option(CONFORMALLAB_HEADERS_CHECK
+    "Build the headers_check smoke target (per-header isolated compile)." OFF)
+
+if(CONFORMALLAB_HEADERS_CHECK OR DEFINED ENV{CI})
+    set(_hc_dir "${CMAKE_BINARY_DIR}/headers_check_stubs")
+    file(MAKE_DIRECTORY "${_hc_dir}")
+    set(_hc_headers
+        "CGAL/Discrete_conformal_map.h"
+        "CGAL/Discrete_circle_packing.h"
+        "CGAL/Discrete_inversive_distance.h"
+        "CGAL/Conformal_layout.h"
+        "CGAL/Conformal_map_traits.h"
+        "CGAL/Conformal_map/internal/parameters.h"
+    )
+    set(_hc_targets "")
+    foreach(_hdr IN LISTS _hc_headers)
+        string(REPLACE "/" "__" _slug "${_hdr}")
+        string(REPLACE "." "_"  _slug "${_slug}")
+        set(_stub "${_hc_dir}/${_slug}.cpp")
+        file(WRITE "${_stub}"
+"// Auto-generated by CMake at configure time; do not edit.
+// Smoke-compile sentinel for ${_hdr}.
+#include <${_hdr}>
+int main() { return 0; }
+")
+        add_executable(hc_${_slug} EXCLUDE_FROM_ALL "${_stub}")
+        target_include_directories(hc_${_slug} SYSTEM PRIVATE
+            ${CMAKE_CURRENT_SOURCE_DIR}/deps/eigen-3.4.0
+            ${CMAKE_CURRENT_SOURCE_DIR}/deps/CGAL-6.1.1/include
+            ${CMAKE_CURRENT_SOURCE_DIR}/deps/single_includes
+            ${Boost_INCLUDE_DIRS})
+        target_include_directories(hc_${_slug} PRIVATE
+            ${CMAKE_CURRENT_SOURCE_DIR}/include)
+        target_compile_definitions(hc_${_slug} PRIVATE
+            CGAL_DISABLE_GMP CGAL_DISABLE_MPFR)
+        list(APPEND _hc_targets hc_${_slug})
+    endforeach()
+    add_custom_target(headers_check DEPENDS ${_hc_targets})
+endif()
+
+# ── Install target (header-only library) ──────────────────────────────────────
+# Installs all public headers to <prefix>/include/conformallab/
+# Usage from another CMake project:
+#   cmake --install build --prefix /usr/local
+#   target_include_directories(myapp PRIVATE /usr/local/include/conformallab)
+include(GNUInstallDirs)
+install(DIRECTORY ${CMAKE_CURRENT_SOURCE_DIR}/include/
+        DESTINATION ${CMAKE_INSTALL_INCLUDEDIR}/conformallab
+        FILES_MATCHING PATTERN "*.hpp"
+        PATTERN "* 2.*" EXCLUDE)   # exclude macOS Finder duplicates
+install(FILES ${CMAKE_CURRENT_SOURCE_DIR}/../LICENSE
+              ${CMAKE_CURRENT_SOURCE_DIR}/../CITATION.cff
+        DESTINATION ${CMAKE_INSTALL_DATADIR}/conformallab)
+
+# ── Doxygen documentation target (Phase 7.5) ──────────────────────────────────
+# Generates HTML API documentation into doc/doxygen/html/.
+# Usage:
+#   cmake --build build --target doc
+#   open doc/doxygen/html/index.html
+#
+# Optional dependency: install Doxygen via `brew install doxygen` (macOS) or
+# `apt install doxygen graphviz` (Linux). The target is silently disabled
+# if Doxygen is not found.
+find_package(Doxygen QUIET)
+if(DOXYGEN_FOUND)
+    set(DOXYGEN_PROJECT_ROOT ${CMAKE_CURRENT_SOURCE_DIR}/..)
+    add_custom_target(doc
+        COMMAND ${DOXYGEN_EXECUTABLE} ${DOXYGEN_PROJECT_ROOT}/Doxyfile
+        WORKING_DIRECTORY ${DOXYGEN_PROJECT_ROOT}
+        COMMENT "Generating API documentation with Doxygen"
+        VERBATIM)
+    message(STATUS "Doxygen found: target 'doc' available (cmake --build build --target doc)")
+else()
+    message(STATUS "Doxygen not found — 'doc' target unavailable (install: brew/apt install doxygen)")
+endif()

code/data/obj/cathead.obj

@@ -0,0 +1,379 @@
+v -0.206972 0.0740737 0.544664
+v -0.398695 -0.0740794 0.501089
+v -0.211327 -0.187367 0.588234
+v -0.511983 -0.235298 0.400872
+v -0.56863 0.0348535 0.405227
+v -0.35948 0.178646 0.50545
+v -0.525054 0.313721 0.387801
+v -0.189545 0.30065 0.544664
+v 0.124182 0.0740737 0.509805
+v -0.455336 -0.33987 0.544664
+v -0.411766 -0.427021 0.671024
+v -0.237476 -0.413949 0.745097
+v -0.250547 -0.535954 0.797389
+v -0.346403 -0.562097 0.758169
+v 0.0152491 -0.33116 0.531593
+v -0.106755 -0.496734 0.692812
+v -0.254903 -0.692812 0.749458
+v -0.0631798 -0.601311 0.55338
+v -0.14597 -0.666669 0.666669
+v -0.250547 -0.727671 0.583879
+v -0.198256 -0.714599 0.42266
+v 0.0283206 -0.514166 0.383445
+v -0.124182 -0.623099 0.196078
+v -0.285401 -0.692812 0.413944
+v -0.333331 -0.596956 0.226582
+v -0.333331 -0.418305 0.413944
+v 0.233115 -0.366019 0.313727
+v 0.215688 -0.156864 0.457519
+v -0.342048 -0.623099 -0.0915061
+v -0.708061 -0.431376 0.0697184
+v -0.647058 -0.501095 -0.0915061
+v -0.716777 -0.318088 0.169935
+v -0.699344 -0.143792 0.235292
+v -0.747275 0.00871052 0.235292
+v -0.747275 0.165574 0.191723
+v -0.764708 0.291939 0.12636
+v -0.747275 0.461874 0.0130715
+v -0.337692 0.535948 0.366013
+v -0.472768 0.644881 0.0653574
+v -0.272329 0.753814 0.0827899
+v -0.294117 0.797383 0.278868
+v -0.307188 0.801744 0.435731
+v -0.324621 0.779957 0.583879
+v -0.355119 0.714594 0.710238
+v -0.407405 0.59695 0.692812
+v -0.442264 0.505444 0.610022
+v -0.477123 0.413944 0.51416
+v -0.285401 0.509805 0.666669
+v -0.185184 0.605661 0.631809
+v -0.0326816 0.518516 0.479301
+v -0.198256 0.72331 0.575162
+v -0.124182 0.745097 0.278868
+v 0.189545 0.479301 0.357297
+v -0.0413921 0.675379 0.352942
+v -0.843136 -0.0392202 -0.0522859
+v -0.764708 -0.33116 0.0348592
+v -0.816994 -0.152508 -0.178651
+v -0.87364 -0.0522916 -0.187362
+v -0.816994 0.108933 -0.204794
+v -0.816994 0.25708 -0.00435526
+v -0.795206 0.387795 -0.0653574
+v -0.764708 0.440087 -0.152503
+v -0.642703 0.535948 -0.370368
+v -0.516338 0.636165 -0.21351
+v -0.856208 0.265791 -0.148147
+v -0.816994 0.261435 -0.291939
+v -0.847497 0.239648 -0.418299
+v -0.82571 0.265791 -0.479301
+v -0.912855 -0.0697184 -0.270152
+v -0.947714 0.0130715 -0.326799
+v -0.938998 0.0740737 -0.392156
+v -0.799567 -0.344231 -0.108933
+v -0.620916 -0.509805 -0.331154
+v -0.764708 -0.287584 -0.244009
+v -0.799567 -0.291939 -0.352942
+v -0.9085 -0.174296 -0.33987
+v -1 -0.0697184 -0.409588
+v -0.965141 -0.148153 -0.461874
+v -0.95643 -0.0610022 -0.549019
+v -0.978212 0.021782 -0.483662
+v -0.729848 -0.357302 -0.501089
+v -0.921571 -0.230937 -0.544664
+v -0.821354 -0.222227 -0.662308
+v -0.9085 -0.16558 -0.623093
+v -0.342048 -0.557736 -0.383445
+v -0.381262 -0.300656 -0.727671
+v -0.167757 -0.557736 -0.501089
+v -0.599128 -0.252725 -0.692812
+v -0.420482 -0.0697184 -0.797389
+v -0.14597 -0.610027 -0.631809
+v -0.947714 0.0915004 -0.522877
+v -0.891067 0.178646 -0.50545
+v -0.869279 -0.0697184 -0.705883
+v -0.934643 0.0348535 -0.627454
+v -0.847497 0.156858 -0.649236
+v -0.620916 0.235292 -0.701528
+v -0.559913 0.143786 -0.745097
+v -0.315905 0.278862 -0.753814
+v -0.0196101 0.440087 -0.784312
+v -0.211327 0.46623 -0.636165
+v -0.381262 0.505444 -0.579523
+v -0.647058 0.374724 -0.601305
+v -0.355119 0.653591 -0.344225
+v -0.0108939 0.644881 -0.313727
+v 0.163396 0.64052 0.104578
+v 0.433554 0.0697127 0.322443
+v 0.516344 -0.318088 0.0435754
+v 0.35948 -0.492378 -0.0653574
+v 0.185184 -0.535954 0.0305039
+v 0.0631798 -0.618738 -0.313727
+v 0.328976 -0.618738 -0.296295
+v 0.102394 -0.684101 -0.43137
+v 0.612199 -0.396517 -0.16558
+v 0.307188 0.522877 -0.779957
+v 0.163396 0.549019 -0.562091
+v 0.468413 0.400872 0.00871623
+v 0.599128 0.374724 -0.261435
+v 0.721132 0.357297 -0.50545
+v 0.843136 0.326793 -0.718955
+v 0.124182 -0.801744 -0.562091
+v 0.35948 -0.749458 -0.448803
+v 0.559913 0.0479307 0.161219
+v 0.673201 0.0304982 -0.0566469
+v 0.808283 0.0174267 -0.309366
+v 0.891067 -0.00871623 -0.483662
+v 1 -0.0697184 -0.753814
+v 0.355119 0.440087 0.191723
+v 0.694989 -0.58824 -0.440087
+v 0.886712 -0.230937 -0.457519
+v 0.912855 -0.366019 -0.575162
+v -0.921571 -0.126365 -0.300656
+f 1 2 3
+f 4 2 5
+f 2 1 5
+f 1 6 5
+f 6 7 5
+f 7 6 8
+f 6 1 8
+f 9 1 3
+f 3 4 10
+f 10 11 3
+f 11 12 3
+f 11 13 12
+f 13 11 14
+f 12 15 3
+f 15 12 16
+f 12 13 16
+f 13 17 16
+f 17 13 14
+f 16 18 15
+f 18 16 19
+f 16 17 19
+f 17 20 19
+f 20 21 19
+f 21 18 19
+f 18 21 22
+f 21 23 22
+f 21 24 23
+f 24 21 20
+f 24 25 23
+f 25 24 26
+f 24 20 26
+f 20 17 26
+f 17 14 26
+f 14 11 26
+f 11 10 26
+f 10 4 26
+f 3 15 9
+f 15 27 28
+f 23 25 29
+f 25 30 31
+f 30 25 32
+f 25 26 32
+f 4 33 32
+f 18 22 15
+f 22 27 15
+f 5 34 33
+f 34 5 35
+f 5 7 35
+f 7 36 35
+f 36 7 37
+f 7 38 37
+f 38 39 37
+f 39 38 40
+f 38 41 40
+f 41 38 42
+f 38 43 42
+f 43 38 44
+f 38 45 44
+f 45 38 46
+f 46 38 47
+f 38 7 47
+f 7 8 47
+f 8 46 47
+f 46 8 48
+f 8 49 48
+f 49 44 48
+f 44 45 48
+f 49 8 50
+f 49 51 44
+f 51 43 44
+f 43 51 42
+f 51 52 42
+f 52 41 42
+f 41 52 40
+f 53 54 50
+f 49 54 51
+f 54 49 50
+f 51 54 52
+f 50 9 53
+f 9 50 8
+f 55 33 34
+f 33 55 32
+f 55 56 32
+f 56 55 57
+f 55 58 57
+f 58 55 59
+f 55 60 59
+f 60 55 35
+f 55 34 35
+f 36 60 35
+f 60 36 37
+f 37 61 60
+f 61 37 62
+f 37 63 62
+f 63 37 64
+f 37 39 64
+f 39 40 64
+f 62 65 61
+f 65 62 66
+f 62 67 66
+f 67 62 68
+f 62 63 68
+f 65 59 60
+f 59 69 58
+f 69 59 70
+f 59 71 70
+f 71 59 67
+f 59 66 67
+f 59 65 66
+f 56 30 32
+f 30 56 31
+f 56 72 31
+f 72 56 57
+f 60 61 65
+f 46 48 45
+f 31 29 25
+f 29 31 73
+f 31 74 73
+f 74 31 72
+f 57 74 72
+f 74 57 75
+f 57 76 75
+f 57 58 69
+f 77 78 76
+f 78 77 79
+f 77 80 79
+f 80 77 71
+f 77 70 71
+f 70 77 69
+f 75 73 74
+f 73 75 81
+f 75 82 81
+f 82 75 76
+f 82 83 81
+f 83 82 84
+f 82 79 84
+f 79 82 78
+f 82 76 78
+f 73 85 29
+f 85 73 86
+f 73 81 86
+f 85 87 29
+f 87 85 86
+f 88 86 81
+f 86 88 89
+f 88 83 89
+f 83 88 81
+f 86 90 87
+f 71 91 80
+f 91 71 92
+f 71 67 92
+f 67 68 92
+f 79 93 84
+f 93 79 94
+f 79 91 94
+f 91 79 80
+f 92 95 91
+f 92 68 95
+f 91 95 94
+f 95 93 94
+f 93 95 96
+f 95 68 96
+f 93 83 84
+f 83 93 89
+f 93 97 89
+f 97 93 96
+f 89 97 98
+f 98 100 99
+f 100 98 101
+f 98 96 101
+f 98 97 96
+f 102 68 63
+f 68 102 96
+f 102 101 96
+f 101 102 63
+f 64 103 63
+f 103 64 40
+f 103 101 63
+f 101 104 100
+f 104 101 103
+f 40 104 103
+f 40 52 104
+f 52 105 104
+f 9 106 53
+f 106 9 28
+f 106 27 107
+f 27 106 28
+f 27 108 107
+f 108 27 22
+f 22 109 108
+f 109 22 23
+f 109 110 108
+f 110 109 23
+f 23 29 110
+f 110 111 108
+f 111 110 112
+f 110 90 112
+f 90 110 87
+f 110 29 87
+f 108 111 113
+f 108 113 107
+f 114 99 115
+f 99 104 115
+f 104 105 115
+f 116 117 115
+f 117 118 115
+f 115 118 114
+f 118 119 114
+f 120 112 90
+f 112 120 111
+f 120 121 111
+f 99 100 104
+f 2 4 3
+f 5 33 4
+f 116 122 123
+f 123 117 116
+f 117 123 124
+f 117 124 118
+f 124 125 118
+f 125 119 118
+f 119 125 126
+f 122 106 107
+f 105 116 115
+f 54 53 105
+f 52 54 105
+f 105 127 116
+f 122 116 127
+f 106 122 127
+f 53 127 105
+f 121 128 113
+f 121 113 111
+f 113 128 124
+f 128 129 124
+f 129 128 130
+f 107 113 122
+f 113 123 122
+f 123 113 124
+f 1 9 8
+f 9 15 28
+f 4 32 26
+f 106 127 53
+f 57 131 76
+f 131 77 76
+f 69 131 57
+f 131 69 77
+f 129 125 124
+f 125 130 126
+f 130 125 129

code/data/obj/tetraflat.obj

@@ -0,0 +1,16 @@
+# 
+# Wavefront OBJ file
+# Converted by the DEEP Exploration Deep Exploration 5 5.0.3.1555 Release
+# Right Hemisphere, LTD
+# http://www.righthemisphere.com/
+# 
+# object sgc 1
+g sgc_1
+v 0.00000 0.00000 0.00000
+v -1.29492 0.95275 -0.28653
+v 1.14390 0.47528 1.06408
+v 0.15103 -1.42803 -0.77755
+# 4 verticies
+f  1 2 3
+f  2 1 4
+f  1 3 4

code/data/off/torus_4x4.off

@@ -0,0 +1,50 @@
+OFF
+16 32 0
+3.000000 0.000000 0.000000
+2.000000 0.000000 1.000000
+1.000000 0.000000 0.000000
+2.000000 0.000000 -1.000000
+0.000000 3.000000 0.000000
+0.000000 2.000000 1.000000
+0.000000 1.000000 0.000000
+0.000000 2.000000 -1.000000
+-3.000000 0.000000 0.000000
+-2.000000 0.000000 1.000000
+-1.000000 0.000000 0.000000
+-2.000000 0.000000 -1.000000
+-0.000000 -3.000000 0.000000
+-0.000000 -2.000000 1.000000
+-0.000000 -1.000000 0.000000
+-0.000000 -2.000000 -1.000000
+3 0 4 1
+3 1 4 5
+3 1 5 2
+3 2 5 6
+3 2 6 3
+3 3 6 7
+3 3 7 0
+3 0 7 4
+3 4 8 5
+3 5 8 9
+3 5 9 6
+3 6 9 10
+3 6 10 7
+3 7 10 11
+3 7 11 4
+3 4 11 8
+3 8 12 9
+3 9 12 13
+3 9 13 10
+3 10 13 14
+3 10 14 11
+3 11 14 15
+3 11 15 8
+3 8 15 12
+3 12 0 13
+3 13 0 1
+3 13 1 14
+3 14 1 2
+3 14 2 15
+3 15 2 3
+3 15 3 12
+3 12 3 0

code/data/off/torus_8x8.off

@@ -0,0 +1,194 @@
+OFF
+64 128 0
+4.000000 0.000000 0.000000
+3.707107 0.000000 0.707107
+3.000000 0.000000 1.000000
+2.292893 0.000000 0.707107
+2.000000 0.000000 0.000000
+2.292893 0.000000 -0.707107
+3.000000 0.000000 -1.000000
+3.707107 0.000000 -0.707107
+2.828427 2.828427 0.000000
+2.621320 2.621320 0.707107
+2.121320 2.121320 1.000000
+1.621320 1.621320 0.707107
+1.414214 1.414214 0.000000
+1.621320 1.621320 -0.707107
+2.121320 2.121320 -1.000000
+2.621320 2.621320 -0.707107
+0.000000 4.000000 0.000000
+0.000000 3.707107 0.707107
+0.000000 3.000000 1.000000
+0.000000 2.292893 0.707107
+0.000000 2.000000 0.000000
+0.000000 2.292893 -0.707107
+0.000000 3.000000 -1.000000
+0.000000 3.707107 -0.707107
+-2.828427 2.828427 0.000000
+-2.621320 2.621320 0.707107
+-2.121320 2.121320 1.000000
+-1.621320 1.621320 0.707107
+-1.414214 1.414214 0.000000
+-1.621320 1.621320 -0.707107
+-2.121320 2.121320 -1.000000
+-2.621320 2.621320 -0.707107
+-4.000000 0.000000 0.000000
+-3.707107 0.000000 0.707107
+-3.000000 0.000000 1.000000
+-2.292893 0.000000 0.707107
+-2.000000 0.000000 0.000000
+-2.292893 0.000000 -0.707107
+-3.000000 0.000000 -1.000000
+-3.707107 0.000000 -0.707107
+-2.828427 -2.828427 0.000000
+-2.621320 -2.621320 0.707107
+-2.121320 -2.121320 1.000000
+-1.621320 -1.621320 0.707107
+-1.414214 -1.414214 0.000000
+-1.621320 -1.621320 -0.707107
+-2.121320 -2.121320 -1.000000
+-2.621320 -2.621320 -0.707107
+-0.000000 -4.000000 0.000000
+-0.000000 -3.707107 0.707107
+-0.000000 -3.000000 1.000000
+-0.000000 -2.292893 0.707107
+-0.000000 -2.000000 0.000000
+-0.000000 -2.292893 -0.707107
+-0.000000 -3.000000 -1.000000
+-0.000000 -3.707107 -0.707107
+2.828427 -2.828427 0.000000
+2.621320 -2.621320 0.707107
+2.121320 -2.121320 1.000000
+1.621320 -1.621320 0.707107
+1.414214 -1.414214 0.000000
+1.621320 -1.621320 -0.707107
+2.121320 -2.121320 -1.000000
+2.621320 -2.621320 -0.707107
+3 0 8 1
+3 1 8 9
+3 1 9 2
+3 2 9 10
+3 2 10 3
+3 3 10 11
+3 3 11 4
+3 4 11 12
+3 4 12 5
+3 5 12 13
+3 5 13 6
+3 6 13 14
+3 6 14 7
+3 7 14 15
+3 7 15 0
+3 0 15 8
+3 8 16 9
+3 9 16 17
+3 9 17 10
+3 10 17 18
+3 10 18 11
+3 11 18 19
+3 11 19 12
+3 12 19 20
+3 12 20 13
+3 13 20 21
+3 13 21 14
+3 14 21 22
+3 14 22 15
+3 15 22 23
+3 15 23 8
+3 8 23 16
+3 16 24 17
+3 17 24 25
+3 17 25 18
+3 18 25 26
+3 18 26 19
+3 19 26 27
+3 19 27 20
+3 20 27 28
+3 20 28 21
+3 21 28 29
+3 21 29 22
+3 22 29 30
+3 22 30 23
+3 23 30 31
+3 23 31 16
+3 16 31 24
+3 24 32 25
+3 25 32 33
+3 25 33 26
+3 26 33 34
+3 26 34 27
+3 27 34 35
+3 27 35 28
+3 28 35 36
+3 28 36 29
+3 29 36 37
+3 29 37 30
+3 30 37 38
+3 30 38 31
+3 31 38 39
+3 31 39 24
+3 24 39 32
+3 32 40 33
+3 33 40 41
+3 33 41 34
+3 34 41 42
+3 34 42 35
+3 35 42 43
+3 35 43 36
+3 36 43 44
+3 36 44 37
+3 37 44 45
+3 37 45 38
+3 38 45 46
+3 38 46 39
+3 39 46 47
+3 39 47 32
+3 32 47 40
+3 40 48 41
+3 41 48 49
+3 41 49 42
+3 42 49 50
+3 42 50 43
+3 43 50 51
+3 43 51 44
+3 44 51 52
+3 44 52 45
+3 45 52 53
+3 45 53 46
+3 46 53 54
+3 46 54 47
+3 47 54 55
+3 47 55 40
+3 40 55 48
+3 48 56 49
+3 49 56 57
+3 49 57 50
+3 50 57 58
+3 50 58 51
+3 51 58 59
+3 51 59 52
+3 52 59 60
+3 52 60 53
+3 53 60 61
+3 53 61 54
+3 54 61 62
+3 54 62 55
+3 55 62 63
+3 55 63 48
+3 48 63 56
+3 56 0 57
+3 57 0 1
+3 57 1 58
+3 58 1 2
+3 58 2 59
+3 59 2 3
+3 59 3 60
+3 60 3 4
+3 60 4 61
+3 61 4 5
+3 61 5 62
+3 62 5 6
+3 62 6 63
+3 63 6 7
+3 63 7 56
+3 56 7 0

code/data/off/torus_hex_6x6.off

@@ -0,0 +1,110 @@
+OFF
+36 72 0
+4.000000 0.000000 0.000000
+3.500000 0.000000 0.866025
+2.500000 0.000000 0.866025
+2.000000 0.000000 0.000000
+2.500000 0.000000 -0.866025
+3.500000 0.000000 -0.866025
+2.000000 3.464102 0.000000
+1.750000 3.031089 0.866025
+1.250000 2.165064 0.866025
+1.000000 1.732051 0.000000
+1.250000 2.165064 -0.866025
+1.750000 3.031089 -0.866025
+-2.000000 3.464102 0.000000
+-1.750000 3.031089 0.866025
+-1.250000 2.165064 0.866025
+-1.000000 1.732051 0.000000
+-1.250000 2.165064 -0.866025
+-1.750000 3.031089 -0.866025
+-4.000000 0.000000 0.000000
+-3.500000 0.000000 0.866025
+-2.500000 0.000000 0.866025
+-2.000000 0.000000 0.000000
+-2.500000 0.000000 -0.866025
+-3.500000 0.000000 -0.866025
+-2.000000 -3.464102 0.000000
+-1.750000 -3.031089 0.866025
+-1.250000 -2.165064 0.866025
+-1.000000 -1.732051 0.000000
+-1.250000 -2.165064 -0.866025
+-1.750000 -3.031089 -0.866025
+2.000000 -3.464102 0.000000
+1.750000 -3.031089 0.866025
+1.250000 -2.165064 0.866025
+1.000000 -1.732051 0.000000
+1.250000 -2.165064 -0.866025
+1.750000 -3.031089 -0.866025
+3 0 6 1
+3 1 6 7
+3 1 7 2
+3 2 7 8
+3 2 8 3
+3 3 8 9
+3 3 9 4
+3 4 9 10
+3 4 10 5
+3 5 10 11
+3 5 11 0
+3 0 11 6
+3 6 12 7
+3 7 12 13
+3 7 13 8
+3 8 13 14
+3 8 14 9
+3 9 14 15
+3 9 15 10
+3 10 15 16
+3 10 16 11
+3 11 16 17
+3 11 17 6
+3 6 17 12
+3 12 18 13
+3 13 18 19
+3 13 19 14
+3 14 19 20
+3 14 20 15
+3 15 20 21
+3 15 21 16
+3 16 21 22
+3 16 22 17
+3 17 22 23
+3 17 23 12
+3 12 23 18
+3 18 24 19
+3 19 24 25
+3 19 25 20
+3 20 25 26
+3 20 26 21
+3 21 26 27
+3 21 27 22
+3 22 27 28
+3 22 28 23
+3 23 28 29
+3 23 29 18
+3 18 29 24
+3 24 30 25
+3 25 30 31
+3 25 31 26
+3 26 31 32
+3 26 32 27
+3 27 32 33
+3 27 33 28
+3 28 33 34
+3 28 34 29
+3 29 34 35
+3 29 35 24
+3 24 35 30
+3 30 0 31
+3 31 0 1
+3 31 1 32
+3 32 1 2
+3 32 2 33
+3 33 2 3
+3 33 3 34
+3 34 3 4
+3 34 4 35
+3 35 4 5
+3 35 5 30
+3 30 5 0

code/deps/CMakeLists.txt

@@ -5,9 +5,10 @@
 #
 # Which deps are extracted depends on the active build mode:
 #
-#   (default)      Eigen only          → tests-only build
+#   (default)           Eigen only
-#   WITH_VIEWER=ON + Eigen, libigl, libigl-glad, glfw
+#   WITH_CGAL_TESTS=ON  + Eigen, CGAL           (headless CI — no viewer)
-#   WITH_CGAL=ON   + Eigen, CGAL       (WITH_VIEWER is implied by WITH_CGAL)
+#   WITH_VIEWER=ON      + Eigen, libigl, libigl-glad, glfw
+#   WITH_CGAL=ON        + Eigen, CGAL, libigl, libigl-glad, glfw
 #
 
 function(setup_dependency NAME SUBDIR)
@@ -51,6 +52,7 @@ if(WITH_VIEWER)
 endif()
 
 # ── CGAL mode ─────────────────────────────────────────────────────────────────
-if(WITH_CGAL)
+# Both WITH_CGAL_TESTS (headless CI) and WITH_CGAL (full build) need CGAL headers.
+if(WITH_CGAL OR WITH_CGAL_TESTS)
     setup_dependency("CGAL-6.1.1" "include")
 endif()

code/deps/THIRD-PARTY-LICENSES.md

@@ -0,0 +1,98 @@
+# Third-party licenses
+
+This directory contains source code from external projects that
+conformallab++ vendors at fixed versions for build reproducibility.
+Each project is governed by its own license; this file enumerates them
+so downstream packagers, distributors, and reviewers can audit
+compatibility without crawling each upstream tarball.
+
+> **Why vendored at all?**  conformallab++ is header-only and ships
+> nothing it does not author except the optional CLI binary
+> (`-DWITH_CGAL=ON`).  Vendoring guarantees that the CGAL / Eigen /
+> Boost API surface every contributor sees is identical, removing
+> "works on my machine because I have CGAL 6.0 not 5.6" failure modes
+> during early review.  Downstream packagers replacing the vendored
+> trees with system installs is supported and is the recommended path
+> for distribution-level packaging (see `doc/architecture/dependencies.md`).
+
+## conformallab++ itself
+
+| Item | License | Notes |
+|---|---|---|
+| `code/include/**`, `code/src/**`, `code/tests/**`, `scripts/**`, `doc/**` | **MIT** (see `LICENSE` at repo root) | Every C++ source file carries `SPDX-License-Identifier: MIT`; CI gate `scripts/quality/license-headers.sh` enforces this. |
+
+## Vendored dependencies
+
+The table below lists each tree under `code/deps/`, its upstream
+license, the SPDX identifier, and any compatibility note relevant to
+shipping conformallab++ as MIT.
+
+| Directory | Upstream project | Version | License (SPDX) | Compatibility with MIT distribution | Notes |
+|---|---|---|---|---|---|
+| `CGAL-6.1.1/` | [CGAL](https://www.cgal.org) | 6.1.1 | **LGPL-3.0-or-later** (most headers) + **GPL-3.0-or-later** (a small subset — see CGAL's per-header `\cgal_license{...}` macro) | Header-only consumption is compatible; we ONLY include LGPL'd parts (`Surface_mesh`, `Polygon_mesh_processing`, BGL adapters, kernels). | conformallab++ does not include any of the GPL-only CGAL packages (e.g. `Triangulation_3` parts, certain mesh-3 internals). The `\cgal_license` macro is checked at compile time and would fail the build if a GPL-only header were transitively pulled in. Commercial licenses are available from GeometryFactory for users who can't accept (L)GPL. |
+| `eigen-3.4.0/` | [Eigen](https://eigen.tuxfamily.org) | 3.4.0 | **MPL-2.0** for almost everything, **LGPL-2.1-or-later** for a few legacy files (e.g. `Eigen/src/Core/util/NonMPL2.h` gates these) | MPL-2.0 is permissive enough for MIT; the LGPL files are NOT pulled in by `<Eigen/Dense>` / `<Eigen/Sparse>` (the only Eigen headers conformallab++ includes). | We define no preprocessor flag that activates the non-MPL2 code paths. The default Eigen build is pure MPL-2.0. |
+| `libigl-2.6.0/` | [libigl](https://libigl.github.io) | 2.6.0 | **MPL-2.0** | Compatible with MIT distribution. | Only the viewer subsystem under `code/src/viewer/` uses libigl, and only when `-DWITH_VIEWER=ON`. The library headers and the CGAL wrapper headers do not depend on libigl. |
+| `libigl-glad/` | [Glad](https://glad.dav1d.de/) (the generated OpenGL loader libigl ships) | bundled with libigl 2.6.0 | **MIT** (the generator's output is licensed permissively; the loader code itself is in the public domain via the original Khronos headers) | Compatible. | Built only with `-DWITH_VIEWER=ON`. |
+| `glfw-3.4/` | [GLFW](https://www.glfw.org) | 3.4 | **zlib/libpng** | Permissive; compatible with MIT. | Built only with `-DWITH_VIEWER=ON`. See `code/deps/glfw-3.4/LICENSE.md` for the verbatim text. |
+| `single_includes/json.hpp` | [nlohmann/json](https://github.com/nlohmann/json) | 3.x (header-only single-include) | **MIT** | Identical to ours. | The file itself carries the SPDX header `MIT`; see `code/deps/single_includes/json.hpp` first lines. |
+| `tarballs/` | (build-artefact cache) | — | n/a | n/a | This directory just caches the downloaded source tarballs to avoid re-downloading on every clean build. The tarballs are bit-for-bit identical to the upstream releases. |
+
+## Auto-fetched (not vendored)
+
+These are pulled by CMake `FetchContent` at configure time. They are
+**not** redistributed by conformallab++; the user's CMake fetches them
+during build. We list them anyway for transparency.
+
+| Item | Upstream | Version | License | Fetched by |
+|---|---|---|---|---|
+| **GoogleTest** | https://github.com/google/googletest | v1.14.0 | **BSD-3-Clause** | `code/CMakeLists.txt` (test target only) |
+
+## System dependencies (required at build time, not redistributed)
+
+| Item | Where it lives | License | Purpose |
+|---|---|---|---|
+| **Boost** (header-only subset) | system package (`apt install libboost-dev`, etc.) | **Boost Software License 1.0** | Required by CGAL's BGL adapters (only when `WITH_CGAL=ON` or `WITH_CGAL_TESTS=ON`). |
+| **C++17 standard library** | the compiler's libstdc++ / libc++ / msvc | LGPL-3.0 with exception / Apache 2.0 with LLVM exception / MSVC redist | normal compiler runtime. |
+
+## Summary for downstream packagers
+
+If you are packaging conformallab++ for a distribution, the practical
+license matrix is:
+
+```
+   binary you ship (CLI app, -DWITH_CGAL=ON)
+   ├── conformallab++  (MIT)
+   ├── CGAL            (LGPL-3.0-or-later — comply with §4 LGPL: source
+   │                    of CGAL must be obtainable or shipped)
+   ├── Eigen           (MPL-2.0 — comply with §3 MPL: any modifications
+   │                    must be released under MPL-2.0)
+   ├── libigl          (MPL-2.0 — same as Eigen)
+   ├── GLFW            (zlib/libpng — acknowledgement in product docs)
+   ├── Glad            (MIT — preserve copyright notice)
+   └── Boost (headers) (BSL-1.0 — preserve copyright notice)
+
+   header-only consumer (just #include our headers)
+   ├── conformallab++  (MIT)
+   ├── Eigen           (MPL-2.0 transitively)
+   ├── CGAL            (LGPL-3.0-or-later transitively)
+   └── Boost (headers) (BSL-1.0 transitively, only if you include any
+                        CGAL/* header)
+```
+
+The header-only consumer typically doesn't trigger LGPL §4 obligations
+because LGPL §3 explicitly permits use of LGPL'd material as
+"templates, inline functions, macros" by an "Application" without
+imposing copyleft on the Application — which is exactly the
+header-only consumption pattern.
+
+If you have specific compliance questions, the upstream license texts
+are authoritative; this file is a navigational aid.
+
+## How this file is maintained
+
+* Updated whenever a `code/deps/` tree is added, removed, or version-bumped.
+* Cross-referenced by `doc/architecture/dependencies.md`.
+* There is no CI gate that auto-verifies the SPDX entries against
+  upstream — that would require either an SBOM tool (e.g. `syft`,
+  `tern`) or a manual audit. The current policy is "review on
+  dep-tree change", logged in the commit message of the bump.

code/include/CGAL/Conformal_layout.h

@@ -0,0 +1,111 @@
+// Copyright (c) 2024-2026 Tarik Moussa.
+// SPDX-License-Identifier: MIT
+//
+// Package: conformallab++ / Discrete_conformal_map (Phase 8b-Lite, 2026-05-21)
+
+/*!
+\file CGAL/Conformal_layout.h
+\ingroup PkgConformalMapRef
+
+Thin CGAL-style wrapper around the legacy `euclidean_layout()`,
+`spherical_layout()` and `hyper_ideal_layout()` functions defined in
+`code/include/layout.hpp`.
+
+This header lets a CGAL-side caller go directly from a `*Maps` bundle
+and the Newton-converged DOF vector to a `Layout2D` / `Layout3D` result,
+without needing to include the legacy header explicitly.
+*/
+
+#ifndef CGAL_CONFORMAL_LAYOUT_H
+#define CGAL_CONFORMAL_LAYOUT_H
+
+#include <CGAL/Conformal_map/internal/parameters.h>
+#include <CGAL/Named_function_parameters.h>
+#include <CGAL/boost/graph/named_params_helper.h>
+
+#include "../layout.hpp"
+
+namespace CGAL {
+
+// ── Re-exported layout types ─────────────────────────────────────────────────
+//
+// `Layout2D`, `Layout3D` and `HolonomyData` are defined in
+// `conformallab::layout` (see `code/include/layout.hpp`).  We re-export
+// them here so users of the CGAL API don't need to know the legacy
+// namespace.
+
+using ::conformallab::Layout2D;
+using ::conformallab::Layout3D;
+using ::conformallab::HolonomyData;
+using ::conformallab::CutGraph;
+
+// ── Wrapper functions ────────────────────────────────────────────────────────
+
+/*!
+\ingroup PkgConformalMapRef
+
+Compute the planar Euclidean layout of `mesh` from a converged DOF
+vector `x` and a `EuclideanMaps` bundle.  Optional named parameters:
+
+* `cut_graph` (pointer-to `CutGraph`, default `nullptr`) — supply a
+  pre-computed cut graph to get a globally consistent layout on closed
+  meshes.
+* `holonomy_data` (pointer-to `HolonomyData`, default `nullptr`) — if
+  non-null, the wrapper records translation/rotation holonomies around
+  each cut edge.
+* `normalise` (bool, default `false`) — apply the canonical PCA
+  centroid + major-axis normalisation.
+
+\returns A `Layout2D` with `uv[v]` per vertex.
+*/
+template <typename TriangleMesh,
+          typename CGAL_NP_TEMPLATE_PARAMETERS>
+Layout2D euclidean_layout(
+    TriangleMesh&                              mesh,
+    const std::vector<double>&                 x,
+    const ::conformallab::EuclideanMaps&       maps,
+    const CGAL_NP_CLASS& = parameters::default_values())
+{
+    // No CGAL-side named-parameter overrides needed for Phase 8b-Lite:
+    // forward straight to the legacy implementation with sensible
+    // defaults.  Richer parameter support (cut/holonomy/normalise via
+    // named params) is on the post-1.0 wishlist; the legacy API can be
+    // called directly in the meantime.
+    return ::conformallab::euclidean_layout(mesh, x, maps);
+}
+
+/*!
+\ingroup PkgConformalMapRef
+
+Compute the spherical layout of `mesh` (points on S² ⊂ ℝ³).
+*/
+template <typename TriangleMesh,
+          typename CGAL_NP_TEMPLATE_PARAMETERS>
+Layout3D spherical_layout(
+    TriangleMesh&                              mesh,
+    const std::vector<double>&                 x,
+    const ::conformallab::SphericalMaps&       maps,
+    const CGAL_NP_CLASS& = parameters::default_values())
+{
+    return ::conformallab::spherical_layout(mesh, x, maps);
+}
+
+/*!
+\ingroup PkgConformalMapRef
+
+Compute the hyperbolic layout of `mesh` (Poincaré disk model).
+*/
+template <typename TriangleMesh,
+          typename CGAL_NP_TEMPLATE_PARAMETERS>
+Layout2D hyper_ideal_layout(
+    TriangleMesh&                              mesh,
+    const std::vector<double>&                 x,
+    const ::conformallab::HyperIdealMaps&      maps,
+    const CGAL_NP_CLASS& = parameters::default_values())
+{
+    return ::conformallab::hyper_ideal_layout(mesh, x, maps);
+}
+
+}  // namespace CGAL
+
+#endif  // CGAL_CONFORMAL_LAYOUT_H

code/include/CGAL/Conformal_map/doxygen_groups.h

@@ -0,0 +1,47 @@
+// Copyright (c) 2024-2026 Tarik Moussa.
+/*! \file CGAL/Conformal_map/doxygen_groups.h
+    \brief Doxygen `\defgroup` registrations for the Conformal_map package.
+*/
+// SPDX-License-Identifier: MIT
+//
+// This header contains only Doxygen \defgroup commands.  It is included
+// nowhere in the build; its sole purpose is to register the package's
+// Doxygen group hierarchy so that `@ingroup Pkg...` references in the
+// other public headers resolve cleanly.
+
+#ifndef CGAL_CONFORMAL_MAP_DOXYGEN_GROUPS_H
+#define CGAL_CONFORMAL_MAP_DOXYGEN_GROUPS_H
+
+/*!
+\defgroup PkgConformalMap CGAL Discrete Conformal Map package
+\brief Discrete conformal maps on triangulated surfaces — five DCE models
+(Euclidean, Spherical, Hyper-Ideal, Circle-Packing Euclidean,
+Inversive-Distance).
+
+This package provides the C++ implementation of the variational discrete
+conformal equivalence solvers from Springborn 2020, Bobenko/Pinkall/Springborn
+2010, and Luo 2004, together with a CGAL-style named-parameter API.
+
+See `doc/api/cgal-package.md` for the full design rationale.
+*/
+
+/*!
+\defgroup PkgConformalMapRef Reference manual
+\ingroup PkgConformalMap
+\brief Public C++ API: entry functions, traits, layout helpers.
+*/
+
+/*!
+\defgroup PkgConformalMapConcepts Concepts
+\ingroup PkgConformalMap
+\brief C++ concepts and traits classes consumed by the entry functions.
+*/
+
+/*!
+\defgroup PkgConformalMapNamedParameters Named function parameters
+\ingroup PkgConformalMap
+\brief Package-specific named-parameter helpers in `CGAL::parameters::*`,
+plus the pipe-operator chaining convention.
+*/
+
+#endif  // CGAL_CONFORMAL_MAP_DOXYGEN_GROUPS_H

code/include/CGAL/Conformal_map/doxygen_namespaces.h

@@ -0,0 +1,91 @@
+// Copyright (c) 2024-2026 Tarik Moussa.
+/*! \file CGAL/Conformal_map/doxygen_namespaces.h
+    \brief Doxygen `\namespace` documentation blocks for the project namespaces.
+*/
+// SPDX-License-Identifier: MIT
+//
+// Doxygen namespace documentation only — no declarations.  Centralised
+// here so that each namespace gets a single, consistent description in
+// the generated HTML, regardless of which header is parsed first.
+
+#ifndef CGAL_CONFORMAL_MAP_DOXYGEN_NAMESPACES_H
+#define CGAL_CONFORMAL_MAP_DOXYGEN_NAMESPACES_H
+
+/*!
+\namespace CGAL
+\brief Root namespace of the CGAL library; conformallab++ adds its
+public entry points (`discrete_conformal_map_*`, `Conformal_map_traits`,
+…) directly into this namespace, matching CGAL package conventions.
+*/
+
+/*!
+\namespace CGAL::Conformal_map
+\brief Implementation-detail namespace for the Discrete Conformal Map
+package.  Users normally do not need to enter this namespace; all
+public entry points are re-exported into `CGAL::`.
+*/
+
+/*!
+\namespace CGAL::Conformal_map::internal_np
+\brief Tag types backing the package-local named-function parameters
+(`vertex_curvature_map_t`, `gradient_tolerance_t`, `output_uv_map_t`, …).
+Users invoke them via the helpers in `CGAL::parameters::*`.
+*/
+
+/*!
+\namespace CGAL::parameters
+\brief CGAL named-function-parameter helpers — both upstream CGAL's and
+the conformallab++ package extensions (`vertex_curvature_map(...)`,
+`gradient_tolerance(...)`, `output_uv_map(...)`, `normalise_layout(...)`).
+Also home of the pipe-operator chaining convention; see
+`doc/tutorials/add-output-uv-map.md` §3.4.
+*/
+
+/*!
+\namespace conformallab
+\brief Core math/algorithm namespace of conformallab++.  Holds the five
+DCE functionals (Euclidean / Spherical / HyperIdeal / CP-Euclidean /
+Inversive-Distance), the Newton solver, layout helpers, mesh-property
+typedefs, and serialisation utilities.  Lives under
+`code/include/*.hpp` and is consumed both by the standalone CLI and
+by the thin CGAL wrappers under `CGAL::`.
+*/
+
+/*!
+\namespace conformallab::detail
+\brief Implementation-private helpers for the `conformallab` namespace.
+Not part of the stable public API.
+*/
+
+/*!
+\namespace conformallab::cp_detail
+\brief Implementation-private helpers for the Circle-Packing Euclidean
+functional (see `cp_euclidean_functional.hpp`).
+*/
+
+/*!
+\namespace conformallab::id_detail
+\brief Implementation-private helpers for the Inversive-Distance
+functional (see `inversive_distance_functional.hpp`).
+*/
+
+/*!
+\namespace conformallab::detail_xml
+\brief Implementation-private XML helpers for the (de)serialisation
+layer (see `serialization.hpp`).
+*/
+
+/*!
+\namespace mesh_utils
+\brief Small, opinion-free mesh utilities (loaders, validators,
+property-map registration) used by both the standalone tools and the
+CGAL wrappers.
+*/
+
+/*!
+\namespace viewer_utils
+\brief libigl-based interactive viewer helpers; built only when
+`WITH_VIEWER=ON`.  Not part of the headless / CGAL public surface.
+*/
+
+#endif  // CGAL_CONFORMAL_MAP_DOXYGEN_NAMESPACES_H

code/include/CGAL/Conformal_map/internal/parameters.h

@@ -0,0 +1,237 @@
+// Copyright (c) 2024-2026 Tarik Moussa.
+// SPDX-License-Identifier: MIT
+//
+// Package: conformallab++ / Discrete_conformal_map (Phase 8 MVP, 2026-05-19)
+
+/*!
+\file CGAL/Conformal_map/internal/parameters.h
+\internal
+\ingroup PkgConformalMapRef
+
+Named-parameter tag definitions specific to the Discrete_conformal_map
+package.  These tags extend the CGAL named-parameter mechanism
+(see `<CGAL/Named_function_parameters.h>`).
+
+Usage from a user perspective is in `CGAL::parameters::*`; the tags
+themselves live in `CGAL::Conformal_map::internal_np`.
+
+This is an internal header — users should not include it directly.
+*/
+
+#ifndef CGAL_CONFORMAL_MAP_INTERNAL_PARAMETERS_H
+#define CGAL_CONFORMAL_MAP_INTERNAL_PARAMETERS_H
+
+#include <CGAL/Named_function_parameters.h>
+
+namespace CGAL {
+namespace Conformal_map {
+
+/// \internal
+/// Parameter tags for the conformal-map package.  Each tag is an
+/// `enum` whose name ends in `_t` and a value whose name does not.
+/// The pattern follows CGAL convention so that the existing
+/// `choose_parameter` / `get_parameter` machinery works directly.
+namespace internal_np {
+
+// ─── Target curvature (Θᵥ) ──────────────────────────────────────────────────
+/// Property-map: vertex_descriptor → FT (target cone angle Θᵥ in radians).
+/// Default: 2π at every interior vertex, π at every boundary vertex.
+enum vertex_curvature_map_t { vertex_curvature_map };
+
+// ─── Newton solver tolerances ───────────────────────────────────────────────
+/// Convergence threshold for the Newton solver: ‖G(u)‖∞ < tol.
+/// Type: FT.  Default: 1e-10.
+enum gradient_tolerance_t { gradient_tolerance };
+
+/// Maximum number of Newton iterations.
+/// Type: int.  Default: 200.
+/// (Reuses the CGAL `number_of_iterations` tag where appropriate; this
+/// alias is provided for vocabulary continuity within the package.)
+enum max_iterations_t { max_iterations };
+
+// ─── DOF / gauge fixing ─────────────────────────────────────────────────────
+/// Property-map: vertex_descriptor → bool.  `true` ⇒ vertex is pinned
+/// (u_v = 0, removed from the Newton DOF vector).
+/// Default: first vertex is pinned, all others are variable.
+enum fixed_vertex_map_t { fixed_vertex_map };
+
+// ─── Layout output (Phase 8b-Lite extension) ────────────────────────────────
+/// Property-map: vertex_descriptor → 2-D / 3-D coordinate.  If provided,
+/// the entry function calls the appropriate `*_layout()` after Newton
+/// convergence and writes the per-vertex coordinates into this map:
+///   - Euclidean / Hyper-ideal / Inversive-Distance: `Point_2` (UV in ℝ²)
+///   - Spherical: `Point_3` (point on S² ⊂ ℝ³)
+/// If the parameter is absent, no layout step is performed.  Callers
+/// who need finer control should run `*_layout()` directly on
+/// `result.x` plus the maps from `setup_*_maps()`.
+enum output_uv_map_t { output_uv_map };
+
+/// Boolean flag: if `true`, apply the canonical post-layout
+/// normalisation (`normalise_euclidean` PCA centroid + axis,
+/// `normalise_spherical` Rodrigues to north pole, …) before writing
+/// into `output_uv_map`.  Default: `false`.
+enum normalise_layout_t { normalise_layout };
+
+}  // namespace internal_np
+}  // namespace Conformal_map
+
+namespace parameters {
+
+/*!
+\addtogroup PkgConformalMapNamedParameters
+\{
+*/
+
+/// \name Discrete conformal map — package-specific named parameters
+/// \{
+
+/// `vertex_curvature_map(pmap)` — target cone angle Θᵥ per vertex.
+/// Type: model of `ReadablePropertyMap` with key = `vertex_descriptor`,
+/// value = `FT`.  If omitted, the package uses 2π at interior vertices
+/// and π at boundary vertices (the natural Gauss–Bonnet target for an
+/// open disk or closed flat surface).
+template <typename PropertyMap>
+auto vertex_curvature_map(const PropertyMap& pmap)
+{
+    return CGAL::Named_function_parameters<
+        PropertyMap,
+        Conformal_map::internal_np::vertex_curvature_map_t,
+        CGAL::internal_np::No_property
+    >(pmap);
+}
+
+/// `gradient_tolerance(eps)` — Newton stopping criterion ‖G‖∞ < eps.
+template <typename FT>
+auto gradient_tolerance(FT eps)
+{
+    return CGAL::Named_function_parameters<
+        FT,
+        Conformal_map::internal_np::gradient_tolerance_t,
+        CGAL::internal_np::No_property
+    >(eps);
+}
+
+/// `max_iterations(n)` — Newton iteration limit.
+inline auto max_iterations(int n)
+{
+    return CGAL::Named_function_parameters<
+        int,
+        Conformal_map::internal_np::max_iterations_t,
+        CGAL::internal_np::No_property
+    >(n);
+}
+
+/// `fixed_vertex_map(pmap)` — which vertices are pinned for gauge-fixing.
+/// Type: model of `ReadablePropertyMap` with key = `vertex_descriptor`,
+/// value = `bool`.  If omitted, the first vertex in the mesh is pinned
+/// (compatible with the existing legacy API).
+template <typename PropertyMap>
+auto fixed_vertex_map(const PropertyMap& pmap)
+{
+    return CGAL::Named_function_parameters<
+        PropertyMap,
+        Conformal_map::internal_np::fixed_vertex_map_t,
+        CGAL::internal_np::No_property
+    >(pmap);
+}
+
+/// `output_uv_map(pmap)` — write the per-vertex layout coordinates
+/// into `pmap` after Newton converges.
+///
+/// Type: model of `WritablePropertyMap` with key = `vertex_descriptor`
+/// and value either `Point_2` (Euclidean / Hyper-ideal / Inversive-
+/// Distance entries) or `Point_3` (Spherical entry).
+///
+/// Implementation: the entry function runs the appropriate
+/// `*_layout()` from `code/include/layout.hpp` after Newton, then
+/// writes one coordinate per vertex into `pmap`.  If omitted, no
+/// layout is performed.
+template <typename PropertyMap>
+auto output_uv_map(const PropertyMap& pmap)
+{
+    return CGAL::Named_function_parameters<
+        PropertyMap,
+        Conformal_map::internal_np::output_uv_map_t,
+        CGAL::internal_np::No_property
+    >(pmap);
+}
+
+/// `normalise_layout(flag)` — apply the canonical post-layout
+/// normalisation (PCA centroid for Euclidean; north-pole alignment
+/// for Spherical; Möbius centring for Hyper-ideal).  Default: `false`.
+/// Only meaningful in combination with `output_uv_map`.
+inline auto normalise_layout(bool flag)
+{
+    return CGAL::Named_function_parameters<
+        bool,
+        Conformal_map::internal_np::normalise_layout_t,
+        CGAL::internal_np::No_property
+    >(flag);
+}
+
+/// \}
+
+// ════════════════════════════════════════════════════════════════════════════
+// Pipe-operator chaining for the Discrete_conformal_map package
+//
+// CGAL's standard chaining syntax `a.b(...).c(...)` requires modifying the
+// CGAL upstream `parameters_interface.h` file, which we deliberately treat
+// as a read-only vendored dependency.  Instead, conformallab++ provides a
+// pipe-operator overload that achieves the same effect from
+// left-to-right composition:
+//
+//     auto p = CGAL::parameters::gradient_tolerance(1e-12)
+//            | CGAL::parameters::max_iterations(500)
+//            | CGAL::parameters::output_uv_map(uv);
+//     CGAL::discrete_conformal_map_euclidean(mesh, p);
+//
+// Semantics: `a | b` reads as "first apply a, then b".  The result is a
+// Named_function_parameters chain identical to what `.b()` chained onto
+// `a` would have produced, so the resulting object is accepted by every
+// entry function in the package.
+//
+// Implementation note: this operator is intentionally placed in the
+// CGAL::parameters namespace so it is found by ADL when the operands are
+// `Named_function_parameters` objects produced by the helpers above.  We
+// constrain it to no-base NPs only (i.e. the operands are fresh
+// single-parameter packs) to avoid colliding with any future CGAL
+// operator on the same type.
+// ════════════════════════════════════════════════════════════════════════════
+
+// Close the PkgConformalMapNamedParameters group block that was opened
+// above the helper functions (see \addtogroup at the top of this section).
+/// \}
+
+}  // namespace parameters
+
+/// Pipe-operator chaining for package-local named parameters.
+///
+/// `a | b` combines `a` and `b` into a single `Named_function_parameters`
+/// chain.  The right-hand side `b` must be a fresh single-parameter pack
+/// (i.e. its Base is `No_property`) — typically the direct return value
+/// of one of the helper functions in `CGAL::parameters::*`.  The
+/// left-hand side can be any chain length.
+///
+/// Lives in `namespace CGAL` (not `CGAL::parameters`) so ADL finds it
+/// when the operands are `CGAL::Named_function_parameters<...>` values.
+///
+/// Use as a workaround for the missing `a.b().c()` chaining syntax
+/// while CGAL upstream does not yet expose a per-package extension
+/// point for member-function chainers.
+template <typename T_a, typename Tag_a, typename Base_a,
+          typename T_b, typename Tag_b>
+auto operator|(const CGAL::Named_function_parameters<T_a, Tag_a, Base_a>& a,
+               const CGAL::Named_function_parameters<T_b, Tag_b, CGAL::internal_np::No_property>& b)
+{
+    // Re-build b as if it had been chained on top of a.
+    using LHS_NP   = CGAL::Named_function_parameters<T_a, Tag_a, Base_a>;
+    using Combined = CGAL::Named_function_parameters<T_b, Tag_b, LHS_NP>;
+    // Read b's value (Named_params_impl::v is the stored value).
+    using Impl_b = CGAL::internal_np::Named_params_impl<T_b, Tag_b, CGAL::internal_np::No_property>;
+    const auto& v_b = static_cast<const Impl_b&>(b).v;
+    return Combined(v_b, a);
+}
+
+}  // namespace CGAL
+
+#endif  // CGAL_CONFORMAL_MAP_INTERNAL_PARAMETERS_H

code/include/CGAL/Conformal_map_traits.h

@@ -0,0 +1,184 @@
+// Copyright (c) 2024-2026 Tarik Moussa.
+// SPDX-License-Identifier: MIT
+//
+// Package: conformallab++ / Discrete_conformal_map (Phase 8 MVP, 2026-05-19)
+
+/*!
+\file CGAL/Conformal_map_traits.h
+\ingroup PkgConformalMapRef
+
+Defines the `ConformalMapTraits` concept and the default model
+`Default_conformal_map_traits<TriangleMesh, K>` for the package.
+
+The concept lists the types and property maps that the discrete-conformal
+algorithms require from any backing data structure.  By templatising the
+algorithms on this concept, the package can run on any CGAL halfedge
+mesh — `Surface_mesh`, `Polyhedron_3`, OpenMesh-adapter, pmp — without
+changes to the algorithm code.
+
+For Phase 8 MVP only the `Surface_mesh` specialisation is provided
+(specialisation 8a.1).  A generic `FaceGraph` specialisation is on the
+roadmap as 8a.2.
+
+\sa `CGAL::Discrete_conformal_map`
+\sa `CGAL::parameters::vertex_curvature_map`
+*/
+
+#ifndef CGAL_CONFORMAL_MAP_TRAITS_H
+#define CGAL_CONFORMAL_MAP_TRAITS_H
+
+#include <CGAL/Surface_mesh.h>
+#include <CGAL/Simple_cartesian.h>
+#include <boost/graph/graph_traits.hpp>
+
+namespace CGAL {
+
+// ════════════════════════════════════════════════════════════════════════════
+// \cgalConcept
+//
+// \concept ConformalMapTraits
+// \ingroup PkgConformalMapConcepts
+//
+// The concept `ConformalMapTraits` describes the requirements that any
+// Traits model must fulfil for the Discrete_conformal_map package.
+//
+// \cgalHasModelsBegin
+// \cgalHasModels{CGAL::Default_conformal_map_traits<TriangleMesh, K>}
+// \cgalHasModelsEnd
+//
+// \section RequiredTypes Required types
+//
+// | Type | Description |
+// |------|-------------|
+// | `Triangle_mesh` | A model of CGAL `FaceGraph` + `HalfedgeGraph`. |
+// | `Kernel`        | A CGAL kernel; defaults to `Simple_cartesian<double>`. |
+// | `FT`            | Field type used internally (typically `double`). |
+// | `Vertex_descriptor`   | `boost::graph_traits<Triangle_mesh>::vertex_descriptor`. |
+// | `Halfedge_descriptor` | analogously. |
+// | `Edge_descriptor`     | analogously. |
+// | `Face_descriptor`     | analogously. |
+//
+// \section RequiredProperties Required property-map accessors
+//
+// The Traits class is responsible for *locating* the property maps that
+// the algorithm reads from and writes to.  The semantics follow the
+// project conventions (see `doc/api/contracts.md` for the full table):
+//
+// | Property             | Key                     | Value | Access  | Used by |
+// |----------------------|-------------------------|-------|---------|---------|
+// | `vertex_points(m)`   | `Vertex_descriptor`     | `Point_3` | Read | input geometry |
+// | `theta_map(m)`       | `Vertex_descriptor`     | `FT`  | RW      | target cone angle Θᵥ |
+// | `vertex_index_map(m)`| `Vertex_descriptor`     | `int` | RW      | DOF index (−1 = pinned) |
+// | `lambda0_map(m)`     | `Edge_descriptor`       | `FT`  | RW      | base log-length λ°ᵢⱼ |
+//
+// Each accessor is a `static` member that returns the map; it must be
+// idempotent (calling twice yields the same map by name lookup).
+// ════════════════════════════════════════════════════════════════════════════
+
+
+// ════════════════════════════════════════════════════════════════════════════
+// Default_conformal_map_traits  —  primary template (undefined)
+// ════════════════════════════════════════════════════════════════════════════
+//
+/*!
+\ingroup PkgConformalMapConcepts
+\brief Primary `ConformalMapTraits` template — undefined, must be
+specialised per mesh type.  The MVP only ships the `Surface_mesh`
+specialisation below; further mesh types (Polyhedron_3, OpenMesh,
+pmp) are deferred to Phase 8a.2.
+*/
+template <typename TriangleMesh,
+          typename Kernel_ = CGAL::Simple_cartesian<double>>
+struct Default_conformal_map_traits;
+
+
+// ════════════════════════════════════════════════════════════════════════════
+// Specialisation: CGAL::Surface_mesh<K::Point_3>
+// ════════════════════════════════════════════════════════════════════════════
+
+/*!
+\ingroup PkgConformalMapRef
+
+Default traits for `CGAL::Surface_mesh`.  Wraps the property maps that
+the existing implementation (`code/include/euclidean_functional.hpp`)
+attaches to a Surface_mesh under the `"ev:idx"`, `"ev:theta"`,
+`"ee:lam0"` etc. names.
+
+This specialisation is the only one available in Phase 8 MVP.  It is
+selected automatically when `TriangleMesh = CGAL::Surface_mesh<...>`.
+
+\tparam K  Any CGAL kernel.  Defaults to `Simple_cartesian<double>`,
+           which is what `conformal_mesh.hpp` uses today.
+*/
+template <typename K>
+struct Default_conformal_map_traits<CGAL::Surface_mesh<typename K::Point_3>, K>
+{
+    /// The CGAL kernel parameter; defaults to `Simple_cartesian<double>`.
+    using Kernel        = K;
+    /// Field type used for all scalar conformal-map data (lengths, λ, Θ, …).
+    using FT            = typename K::FT;
+    /// 3-D point type used for vertex coordinates.
+    using Point_3       = typename K::Point_3;
+    /// The triangle-mesh type this specialisation targets.
+    using Triangle_mesh = CGAL::Surface_mesh<Point_3>;
+
+    /// Boost-graph vertex descriptor for `Triangle_mesh`.
+    using Vertex_descriptor   = typename boost::graph_traits<Triangle_mesh>::vertex_descriptor;
+    /// Boost-graph half-edge descriptor for `Triangle_mesh`.
+    using Halfedge_descriptor = typename boost::graph_traits<Triangle_mesh>::halfedge_descriptor;
+    /// Boost-graph edge descriptor for `Triangle_mesh`.
+    using Edge_descriptor     = typename boost::graph_traits<Triangle_mesh>::edge_descriptor;
+    /// Boost-graph face descriptor for `Triangle_mesh`.
+    using Face_descriptor     = typename boost::graph_traits<Triangle_mesh>::face_descriptor;
+
+    // Property-map types — match the names used by setup_euclidean_maps().
+
+    /// Property map vertex → `Point_3` (the mesh's geometric embedding).
+    using Vertex_point_map      = typename Triangle_mesh::template Property_map<Vertex_descriptor, Point_3>;
+    /// Property map vertex → target cone angle Θᵥ in radians (legacy name `ev:theta`).
+    using Theta_pmap            = typename Triangle_mesh::template Property_map<Vertex_descriptor, FT>;
+    /// Property map vertex → contiguous integer index (legacy name `ev:idx`).
+    using Vertex_index_pmap     = typename Triangle_mesh::template Property_map<Vertex_descriptor, int>;
+    /// Property map edge → log of original edge length λ⁰ (legacy name `ee:lam0`).
+    using Lambda0_pmap          = typename Triangle_mesh::template Property_map<Edge_descriptor, FT>;
+
+    // ─── Property-map accessors ───────────────────────────────────────────
+    //
+    // Each accessor returns a property map under its canonical legacy name.
+    // If no such map exists yet it is created with sensible defaults — so
+    // calling either `setup_euclidean_maps(m)` first or the accessor first
+    // is equivalent.
+
+    /// Return the built-in vertex-point map of `m` (the geometric embedding).
+    static Vertex_point_map vertex_points(Triangle_mesh& m) {
+        return m.points();
+    }
+
+    /// Return (or create with default 2π) the target-angle property map.
+    static Theta_pmap theta_map(Triangle_mesh& m) {
+        auto [pm, created] = m.template add_property_map<Vertex_descriptor, FT>(
+            "ev:theta", FT(2.0 * 3.141592653589793238));
+        (void)created;
+        return pm;
+    }
+
+    /// Return (or create with default −1) the vertex-index property map.
+    static Vertex_index_pmap vertex_index_map(Triangle_mesh& m) {
+        auto [pm, created] = m.template add_property_map<Vertex_descriptor, int>(
+            "ev:idx", -1);
+        (void)created;
+        return pm;
+    }
+
+    /// Return (or create with default 0) the λ⁰ (initial log-length) property map.
+    static Lambda0_pmap lambda0_map(Triangle_mesh& m) {
+        auto [pm, created] = m.template add_property_map<Edge_descriptor, FT>(
+            "ee:lam0", FT(0));
+        (void)created;
+        return pm;
+    }
+};
+
+}  // namespace CGAL
+
+#endif  // CGAL_CONFORMAL_MAP_TRAITS_H

code/include/CGAL/Discrete_circle_packing.h

@@ -0,0 +1,235 @@
+// Copyright (c) 2024-2026 Tarik Moussa.
+// SPDX-License-Identifier: MIT
+//
+// Package: conformallab++ / Discrete_conformal_map (Phase 8b-Lite, 2026-05-21)
+
+/*!
+\file CGAL/Discrete_circle_packing.h
+\ingroup PkgConformalMapRef
+
+User-facing entry for the **face-based** circle-packing functional of
+Bobenko-Pinkall-Springborn 2010.  See `cp_euclidean_functional.hpp`
+for the underlying algorithm and `doc/architecture/phase-9a-validation.md`
+for the line-by-line mapping to the Java original
+`CPEuclideanFunctional.java`.
+
+This functional has a fundamentally different DOF structure to the
+classical Euclidean / Spherical / HyperIdeal modes — one log-radius
+`ρ_f` per **face** rather than one log-scale `u_v` per vertex.  We
+therefore expose it via a dedicated header with its own default-trait
+class (Strategy C of the Phase 8b architecture audit).
+*/
+
+#ifndef CGAL_DISCRETE_CIRCLE_PACKING_H
+#define CGAL_DISCRETE_CIRCLE_PACKING_H
+
+#include <CGAL/Conformal_map/internal/parameters.h>
+#include <CGAL/Kernel_traits.h>
+#include <CGAL/Named_function_parameters.h>
+#include <CGAL/boost/graph/named_params_helper.h>
+#include <CGAL/Surface_mesh.h>
+#include <CGAL/Simple_cartesian.h>
+#include <boost/graph/graph_traits.hpp>
+
+#include "../cp_euclidean_functional.hpp"
+#include "../newton_solver.hpp"
+
+#include <stdexcept>
+
+namespace CGAL {
+
+// ── Default traits for CP-Euclidean ───────────────────────────────────────────
+
+/*!
+\ingroup PkgConformalMapConcepts
+\brief Traits class for `discrete_circle_packing_euclidean()` —
+declares the kernel, mesh and property-map types used by the
+BPS-2010 face-based circle-packing functional.
+
+Primary template; specialise it for non-`Surface_mesh` triangle meshes.
+*/
+template <typename TriangleMesh,
+          typename Kernel_ = CGAL::Simple_cartesian<double>>
+struct Default_cp_euclidean_traits;
+
+/*!
+\ingroup PkgConformalMapConcepts
+\brief Specialisation for `CGAL::Surface_mesh<P>`; the only one shipped
+in Phase 8b-Lite.
+*/
+template <typename K>
+struct Default_cp_euclidean_traits<CGAL::Surface_mesh<typename K::Point_3>, K>
+{
+    /// CGAL kernel parameter (defaults to `Simple_cartesian<double>`).
+    using Kernel        = K;
+    /// Scalar field type used for all CP-Euclidean DOFs (`ρ_f`, `θ_e`, `φ_f`).
+    using FT            = typename K::FT;
+    /// 3-D point type (vertex coordinates).
+    using Point_3       = typename K::Point_3;
+    /// Triangle-mesh type this specialisation targets.
+    using Triangle_mesh = CGAL::Surface_mesh<Point_3>;
+
+    /// Boost-graph vertex descriptor for `Triangle_mesh`.
+    using Vertex_descriptor   = typename boost::graph_traits<Triangle_mesh>::vertex_descriptor;
+    /// Boost-graph half-edge descriptor for `Triangle_mesh`.
+    using Halfedge_descriptor = typename boost::graph_traits<Triangle_mesh>::halfedge_descriptor;
+    /// Boost-graph edge descriptor for `Triangle_mesh`.
+    using Edge_descriptor     = typename boost::graph_traits<Triangle_mesh>::edge_descriptor;
+    /// Boost-graph face descriptor for `Triangle_mesh`.
+    using Face_descriptor     = typename boost::graph_traits<Triangle_mesh>::face_descriptor;
+
+    // CP-Euclidean property maps — note the *face* DOF index map.
+
+    /// Property map face → contiguous integer DOF index (legacy `cf:idx`).
+    using Face_index_pmap = typename Triangle_mesh::template Property_map<Face_descriptor,   int>;
+    /// Property map edge → intersection angle θₑ (legacy `ce:theta`).
+    using Theta_e_pmap    = typename Triangle_mesh::template Property_map<Edge_descriptor,   FT>;
+    /// Property map face → target angle sum φ_f (legacy `cf:phi`).
+    using Phi_f_pmap      = typename Triangle_mesh::template Property_map<Face_descriptor,   FT>;
+};
+
+// ── Result type ───────────────────────────────────────────────────────────────
+
+/*!
+\ingroup PkgConformalMapRef
+
+Result of `discrete_circle_packing_euclidean`.  Carries face DOFs
+`ρ_f = log R_f` rather than the vertex DOFs of the classical modes.
+*/
+template <typename FT = double>
+struct Circle_packing_result
+{
+    /// Face DOFs `ρ_f = log R_f` (length = num_faces(mesh); pinned face = 0).
+    std::vector<FT> rho_per_face;
+
+    /// Newton iterations actually performed (≤ `max_iterations`).
+    int  iterations    = 0;
+    /// Final infinity-norm of the gradient (Newton stopping criterion).
+    FT   gradient_norm = FT(0);
+    /// `true` iff `gradient_norm < gradient_tolerance` at exit.
+    bool converged     = false;
+};
+
+// ── Entry function ────────────────────────────────────────────────────────────
+
+/*!
+\ingroup PkgConformalMapRef
+
+Compute the BPS-2010 face-based circle-packing of `mesh`.
+
+\tparam TriangleMesh  A `CGAL::Surface_mesh<P>`.
+\tparam NamedParameters  Optional CGAL named-parameter pack.
+
+\param mesh  Input triangle mesh.
+\param np    Named parameters (subset of those documented on
+             `discrete_conformal_map_euclidean`; the curvature-map
+             parameter `vertex_curvature_map` is **not** used in this
+             face-based mode — instead the per-face target angle sum
+             `φ_f` and per-edge intersection angle `θ_e` are set via
+             the property maps on `mesh` before this call, or left at
+             their defaults `φ_f = 2π`, `θ_e = π/2`).
+
+\returns A `Circle_packing_result<FT>` with `ρ_f` per face.
+
+\pre `mesh` is a triangle mesh.
+\pre `φ_f` and `θ_e` satisfy the BPS-2010 admissibility conditions
+     (Σ_f φ_f = 2π·χ + Σ_e (π − θ_e), see paper §6).
+*/
+template <typename TriangleMesh,
+          typename CGAL_NP_TEMPLATE_PARAMETERS>
+auto discrete_circle_packing_euclidean(
+    TriangleMesh& mesh,
+    const CGAL_NP_CLASS& np = parameters::default_values())
+{
+    using Point_type     = typename TriangleMesh::Point;
+    using Default_kernel = typename CGAL::Kernel_traits<Point_type>::Kernel;
+    using Default_traits = Default_cp_euclidean_traits<TriangleMesh, Default_kernel>;
+    using Traits         = typename internal_np::Lookup_named_param_def<
+                              internal_np::geom_traits_t,
+                              CGAL_NP_CLASS,
+                              Default_traits>::type;
+    using FT             = typename Traits::FT;
+
+    Circle_packing_result<FT> result;
+
+    auto maps = ::conformallab::setup_cp_euclidean_maps(mesh);
+
+    // Pin first face by default; `fixed_vertex_map` is reused here as the
+    // "fixed face" override hook (the parameter tag is generic enough).
+    // For a richer API, a dedicated `fixed_face_map` tag could be added.
+    auto it = mesh.faces().begin();
+    if (it == mesh.faces().end()) {
+        return result;   // empty mesh; trivial
+    }
+    const int n = ::conformallab::assign_cp_euclidean_face_dof_indices(mesh, maps, *it);
+
+    const FT  tol      = parameters::choose_parameter(
+        parameters::get_parameter(np, Conformal_map::internal_np::gradient_tolerance),
+        FT(1e-10));
+    const int max_iter = parameters::choose_parameter(
+        parameters::get_parameter(np, Conformal_map::internal_np::max_iterations),
+        200);
+
+    // Natural-phi default: shift φ_f so the gradient at ρ = 0 is zero.
+    std::vector<double> x0(static_cast<std::size_t>(n), 0.0);
+    auto G0 = ::conformallab::cp_euclidean_gradient(mesh, x0, maps);
+    for (auto f : mesh.faces()) {
+        int i = maps.f_idx[f];
+        if (i >= 0) maps.phi_f[f] -= G0[static_cast<std::size_t>(i)];
+    }
+
+    auto nr = ::conformallab::newton_cp_euclidean(mesh, x0, maps, tol, max_iter);
+
+    result.rho_per_face.assign(num_faces(mesh), FT(0));
+    for (auto f : mesh.faces()) {
+        int j = maps.f_idx[f];
+        if (j >= 0) result.rho_per_face[f.idx()] = nr.x[static_cast<std::size_t>(j)];
+    }
+    result.iterations    = nr.iterations;
+    result.gradient_norm = nr.grad_inf_norm;
+    result.converged     = nr.converged;
+
+    // ── output_uv_map (Phase 8b-Lite extension) ────────────────────────────
+    //
+    // The CP-Euclidean functional carries one DOF per *face* (the log of the
+    // face-circle radius `ρ_f = log R_f`), not per vertex.  A faithful
+    // layout therefore produces a circle packing in ℝ² — each face f is
+    // mapped to a circle of radius `R_f` at some centre `c_f`, with
+    // adjacent circles meeting at the prescribed intersection angle `θ_e`.
+    // That is a per-face output, not the per-vertex Point_2 that
+    // `output_uv_map` is typed for.
+    //
+    // For Phase 8b-Lite we deliberately don't fake it.  If the caller
+    // supplies `output_uv_map(pmap)` we throw `std::runtime_error` with a
+    // clear pointer to Phase 9c (BPS-2010 §6 face-based circle-packing
+    // layout, ~150 lines, on the porting roadmap).  Failing loudly is
+    // better than silently writing zeros.
+    //
+    // Users who want a UV-like coordinate today can:
+    //   1. Solve a Euclidean DCE on the same mesh (vertex DOFs),
+    //   2. Use `discrete_inversive_distance_map(... output_uv_map(pmap))`,
+    //   3. Or compute face-centre positions by hand from `result.rho_per_face`
+    //      + the per-edge `θ_e` values, plus a priority-BFS of their own.
+    {
+        auto uv_param = parameters::get_parameter(
+            np, Conformal_map::internal_np::output_uv_map);
+        constexpr bool has_uv = !std::is_same_v<
+            decltype(uv_param), internal_np::Param_not_found>;
+        if constexpr (has_uv) {
+            throw std::runtime_error(
+                "CGAL::discrete_circle_packing_euclidean: the "
+                "`output_uv_map(...)` named parameter is not yet supported "
+                "for face-based CP-Euclidean.  The faithful output is a "
+                "circle packing in the plane (per-face), not per-vertex "
+                "UVs.  Tracked as Phase 9c; "
+                "see doc/architecture/locked-vs-flexible.md and "
+                "doc/tutorials/add-output-uv-map.md.");
+        }
+    }
+
+    return result;
+}
+
+}  // namespace CGAL
+
+#endif  // CGAL_DISCRETE_CIRCLE_PACKING_H

code/include/CGAL/Discrete_conformal_map.h

@@ -0,0 +1,564 @@
+// Copyright (c) 2024-2026 Tarik Moussa.
+// SPDX-License-Identifier: MIT
+//
+// Package: conformallab++ / Discrete_conformal_map (Phase 8 MVP, 2026-05-19)
+
+/*!
+\file CGAL/Discrete_conformal_map.h
+\ingroup PkgConformalMapRef
+
+User-facing entry point for the Discrete_conformal_map package.
+
+This header provides a single function — `discrete_conformal_map_euclidean`
+— that computes a Euclidean discrete-conformal flattening of an open or
+closed triangle mesh.  Spherical and hyperbolic variants are scheduled
+for Phase 8b.2 once the Euclidean pattern is validated by Phase 9a
+(Inversive-Distance functional).
+
+\section Example Simplest usage
+
+\code{.cpp}
+#include <CGAL/Simple_cartesian.h>
+#include <CGAL/Surface_mesh.h>
+#include <CGAL/Discrete_conformal_map.h>
+
+using K = CGAL::Simple_cartesian<double>;
+using Mesh = CGAL::Surface_mesh<K::Point_3>;
+
+int main() {
+    Mesh mesh = ...;  // load a triangle mesh
+    auto result = CGAL::discrete_conformal_map_euclidean(mesh);
+    if (!result.converged)
+        return 1;
+    // result.u_per_vertex[v] now holds the conformal scale factor at v.
+}
+\endcode
+
+\section NamedParams Tuning via named parameters
+
+\code{.cpp}
+auto result = CGAL::discrete_conformal_map_euclidean(
+    mesh,
+    CGAL::parameters::gradient_tolerance(1e-12)
+                     .max_iterations(500));
+\endcode
+
+\sa `CGAL::Default_conformal_map_traits`
+\sa `CGAL::parameters::vertex_curvature_map`
+*/
+
+#ifndef CGAL_DISCRETE_CONFORMAL_MAP_H
+#define CGAL_DISCRETE_CONFORMAL_MAP_H
+
+#include <CGAL/Conformal_map_traits.h>
+#include <CGAL/Conformal_map/internal/parameters.h>
+#include <CGAL/Kernel_traits.h>
+#include <CGAL/Named_function_parameters.h>
+#include <CGAL/boost/graph/named_params_helper.h>
+#include <CGAL/property_map.h>
+
+// Existing implementation headers (Layer 1 — unchanged).
+#include "../euclidean_functional.hpp"
+#include "../layout.hpp"
+#include "../spherical_functional.hpp"
+#include "../hyper_ideal_functional.hpp"
+#include "../gauss_bonnet.hpp"
+#include "../newton_solver.hpp"
+
+#include <vector>
+#include <unordered_map>
+
+namespace CGAL {
+
+// ════════════════════════════════════════════════════════════════════════════
+// Result type
+// ════════════════════════════════════════════════════════════════════════════
+
+/*!
+\ingroup PkgConformalMapRef
+
+Result of `discrete_conformal_map_euclidean`.  Carries the converged
+scale factors `u_v`, Newton diagnostics, and the convergence flag.
+*/
+template <typename FT = double>
+struct Conformal_map_result
+{
+    /// Conformal scale factor `u_v` per vertex (indexed by raw vertex index).
+    /// Length: `num_vertices(mesh)`.
+    std::vector<FT> u_per_vertex;
+
+    /// Number of Newton iterations performed.
+    int iterations = 0;
+
+    /// `‖G(u*)‖∞` at termination.
+    FT gradient_norm = FT(0);
+
+    /// `true` iff `gradient_norm < gradient_tolerance`.
+    bool converged = false;
+
+    /// `true` iff the linear solver used the SparseQR fallback at any
+    /// Newton step (gauge mode on closed mesh without pinned vertex).
+    bool sparse_qr_fallback_used = false;
+};
+
+
+// ════════════════════════════════════════════════════════════════════════════
+// discrete_conformal_map_euclidean  —  user-facing entry
+// ════════════════════════════════════════════════════════════════════════════
+
+/*!
+\ingroup PkgConformalMapRef
+
+Compute the Euclidean discrete-conformal map of `mesh`.
+
+This is the user-facing entry of Phase 8 MVP.  Internally it delegates
+to the existing implementation in `code/include/euclidean_functional.hpp`
+and `code/include/newton_solver.hpp` (Phase 1–7), so the algorithmic
+behaviour is identical to the legacy API; this function only changes
+the public façade.
+
+\tparam TriangleMesh  A `CGAL::Surface_mesh<P>` for some point type `P`.
+                      Other `FaceGraph` models are planned for Phase 8a.2.
+\tparam NamedParameters  Optional CGAL named-parameter pack.
+
+\param mesh  The input mesh (modified in place: property maps are attached).
+\param np    Named parameters:
+  \cgalParamNBegin{vertex_curvature_map}
+    \cgalParamDescription{Property map `vertex → FT` of target cone angles Θᵥ.}
+    \cgalParamDefault{2π at interior vertices, π at boundary vertices.}
+  \cgalParamNEnd
+  \cgalParamNBegin{gradient_tolerance}
+    \cgalParamDescription{Newton stops when `‖G(u)‖∞ < tol`.}
+    \cgalParamDefault{`1e-10`}
+  \cgalParamNEnd
+  \cgalParamNBegin{max_iterations}
+    \cgalParamDescription{Hard limit on Newton steps.}
+    \cgalParamDefault{`200`}
+  \cgalParamNEnd
+  \cgalParamNBegin{fixed_vertex_map}
+    \cgalParamDescription{Property map `vertex → bool`; `true` ⇒ pinned.}
+    \cgalParamDefault{The first vertex in `mesh.vertices()` is pinned.}
+  \cgalParamNEnd
+
+\returns A `Conformal_map_result<FT>` carrying `u_v` and Newton diagnostics.
+
+\pre `mesh` is a triangle mesh.
+\pre `mesh` satisfies the Gauss–Bonnet relation
+     `Σ(2π − Θᵥ) = 2π·χ(mesh)` for the chosen target curvature map.
+*/
+template <typename TriangleMesh,
+          typename CGAL_NP_TEMPLATE_PARAMETERS>
+auto discrete_conformal_map_euclidean(
+    TriangleMesh& mesh,
+    const CGAL_NP_CLASS& np = parameters::default_values())
+{
+    // ── Type plumbing ──────────────────────────────────────────────────────
+    //
+    // Deduce the kernel from the mesh's Point_3 type rather than hard-coding
+    // Simple_cartesian<double>.  This lets the wrapper work with any
+    // Surface_mesh<P> whose P is a CGAL kernel point.  The user can override
+    // the entire traits class via the `geom_traits(...)` named parameter
+    // (Phase 8b.2 extension; default below covers the common case).
+    using Point_type      = typename TriangleMesh::Point;
+    using Default_kernel  = typename CGAL::Kernel_traits<Point_type>::Kernel;
+    using Default_traits  = Default_conformal_map_traits<TriangleMesh, Default_kernel>;
+    using Traits          = typename internal_np::Lookup_named_param_def<
+                                internal_np::geom_traits_t,
+                                CGAL_NP_CLASS,
+                                Default_traits>::type;
+    using FT              = typename Traits::FT;
+
+    Conformal_map_result<FT> result;
+
+    // ── 1. Set up property maps (legacy layer) ─────────────────────────────
+    auto maps = ::conformallab::setup_euclidean_maps(mesh);
+    ::conformallab::compute_euclidean_lambda0_from_mesh(mesh, maps);
+
+    // ── 2. Target curvature: user-supplied or "natural-theta" default ─────
+    auto theta_param = parameters::get_parameter(
+        np, Conformal_map::internal_np::vertex_curvature_map);
+    constexpr bool has_theta = !std::is_same_v<
+        decltype(theta_param), internal_np::Param_not_found>;
+    if constexpr (has_theta) {
+        // User-provided Θ: copy into the property map and verify Gauss–Bonnet.
+        // Throws std::runtime_error if the user-supplied Θ violates GB.
+        for (auto v : mesh.vertices())
+            maps.theta_v[v] = get(theta_param, v);
+        ::conformallab::check_gauss_bonnet(mesh, maps);
+    }
+    // If no Θ is supplied, the default behaviour is "natural-theta": set Θ
+    // such that x = 0 is the natural equilibrium (the actual angle sums at
+    // x = 0 become the targets).  This matches the convention of the
+    // existing test suite and guarantees that the default invocation
+    // converges immediately for any well-formed triangle mesh.
+    // The actual Θ adjustment is done after DOF assignment (step 5b below).
+
+    // ── 3. Pin vertices: user map, or the first vertex by default ──────────
+    //
+    // The legacy v_idx property map has -1 as default (= pinned).  We must
+    // first mark every vertex as "free" (any non-negative sentinel), then
+    // pin the requested ones, then assign sequential DOF indices.
+    constexpr int FREE = 0;
+    for (auto v : mesh.vertices())
+        maps.v_idx[v] = FREE;
+
+    auto pin_param = parameters::get_parameter(
+        np, Conformal_map::internal_np::fixed_vertex_map);
+    constexpr bool has_pin = !std::is_same_v<
+        decltype(pin_param), internal_np::Param_not_found>;
+
+    bool any_pinned = false;
+    if constexpr (has_pin) {
+        for (auto v : mesh.vertices())
+            if (get(pin_param, v)) {
+                maps.v_idx[v] = -1;
+                any_pinned = true;
+            }
+    }
+    if (!any_pinned) {
+        auto it = mesh.vertices().begin();
+        if (it != mesh.vertices().end()) {
+            maps.v_idx[*it] = -1;
+            any_pinned = true;
+        }
+    }
+
+    // ── 4. Assign DOF indices 0..n−1 to non-pinned vertices ─────────────────
+    int idx = 0;
+    for (auto v : mesh.vertices())
+        if (maps.v_idx[v] != -1)
+            maps.v_idx[v] = idx++;
+
+    // ── 5. Read tolerances ─────────────────────────────────────────────────
+    const FT  tol      = parameters::choose_parameter(
+        parameters::get_parameter(np, Conformal_map::internal_np::gradient_tolerance),
+        FT(1e-10));
+    const int max_iter = parameters::choose_parameter(
+        parameters::get_parameter(np, Conformal_map::internal_np::max_iterations),
+        200);
+
+    // ── 5b. Natural-theta default: shift Θ so that x = 0 is the equilibrium
+    //
+    // Only applied when the user did NOT supply a vertex_curvature_map.
+    // The trick: evaluate G at x = 0, then subtract G_v from Θ_v.  After
+    // this shift the new G(0) is identically zero, so Newton starts at the
+    // optimum and immediately reports "converged".  This matches the
+    // contract of the existing test suite ("natural-theta" pattern).
+    std::vector<double> x0(static_cast<std::size_t>(idx), 0.0);
+    if constexpr (!has_theta) {
+        auto G0 = ::conformallab::euclidean_gradient(mesh, x0, maps);
+        for (auto v : mesh.vertices()) {
+            const int j = maps.v_idx[v];
+            if (j >= 0)
+                maps.theta_v[v] -= G0[static_cast<std::size_t>(j)];
+        }
+    }
+
+    // ── 6. Newton on x_0 = 0 ───────────────────────────────────────────────
+    auto nr = ::conformallab::newton_euclidean(mesh, x0, maps, tol, max_iter);
+
+    // ── 7. Pack result: u_v for every vertex, including pinned (u=0) ──────
+    result.u_per_vertex.assign(num_vertices(mesh), FT(0));
+    for (auto v : mesh.vertices()) {
+        const int j = maps.v_idx[v];
+        if (j >= 0)
+            result.u_per_vertex[v.idx()] = nr.x[static_cast<std::size_t>(j)];
+        // else: pinned ⇒ u_v stays 0
+    }
+    result.iterations    = nr.iterations;
+    result.gradient_norm = nr.grad_inf_norm;
+    result.converged     = nr.converged;
+
+    // ── 8. Optional layout step (Phase 8b-Lite extension) ──────────────────
+    //
+    // If the caller supplied `output_uv_map(pmap)`, run the priority-BFS
+    // trilateration on the converged x and write per-vertex `Point_2`
+    // coordinates into `pmap`.  Optional `normalise_layout(true)` applies
+    // the canonical PCA centroid + major-axis normalisation.
+    auto uv_param = parameters::get_parameter(
+        np, Conformal_map::internal_np::output_uv_map);
+    constexpr bool has_uv = !std::is_same_v<
+        decltype(uv_param), internal_np::Param_not_found>;
+    if constexpr (has_uv) {
+        if (nr.converged) {
+            auto layout = ::conformallab::euclidean_layout(mesh, nr.x, maps);
+
+            const bool do_norm = parameters::choose_parameter(
+                parameters::get_parameter(np, Conformal_map::internal_np::normalise_layout),
+                false);
+            if (do_norm) ::conformallab::normalise_euclidean(layout);
+
+            for (auto v : mesh.vertices()) {
+                const auto& uv = layout.uv[v.idx()];
+                put(uv_param, v,
+                    typename Traits::Kernel::Point_2(uv.x(), uv.y()));
+            }
+        }
+    }
+
+    return result;
+}
+
+
+// ════════════════════════════════════════════════════════════════════════════
+// discrete_conformal_map_spherical  —  Phase 8b-Lite
+// ════════════════════════════════════════════════════════════════════════════
+
+/*!
+\ingroup PkgConformalMapRef
+
+Compute the spherical discrete-conformal map of a closed genus-0 mesh.
+
+The spherical DCE energy is *concave*, so its Hessian is NSD at the
+optimum and `newton_spherical()` factorises −H internally (handled by
+the legacy implementation; no caller action required).  A gauge vertex
+is pinned automatically to remove the rotational mode.
+
+\tparam TriangleMesh  A `CGAL::Surface_mesh<P>` for some point type `P`.
+\tparam NamedParameters  Optional CGAL named-parameter pack.
+
+\param mesh  The input mesh (modified in place: property maps attached).
+\param np    Same named parameters as `discrete_conformal_map_euclidean`.
+
+\returns A `Conformal_map_result<FT>` carrying `u_v` per vertex and
+         Newton diagnostics.
+
+\pre `mesh` is a closed genus-0 triangle mesh.
+\pre The user-supplied or natural-theta Θ satisfies the spherical
+     Gauss–Bonnet relation `Σ(2π − Θᵥ) = 4π` (sphere).
+*/
+template <typename TriangleMesh,
+          typename CGAL_NP_TEMPLATE_PARAMETERS>
+auto discrete_conformal_map_spherical(
+    TriangleMesh& mesh,
+    const CGAL_NP_CLASS& np = parameters::default_values())
+{
+    using Point_type     = typename TriangleMesh::Point;
+    using Default_kernel = typename CGAL::Kernel_traits<Point_type>::Kernel;
+    using Default_traits = Default_conformal_map_traits<TriangleMesh, Default_kernel>;
+    using Traits         = typename internal_np::Lookup_named_param_def<
+                              internal_np::geom_traits_t,
+                              CGAL_NP_CLASS,
+                              Default_traits>::type;
+    using FT             = typename Traits::FT;
+
+    Conformal_map_result<FT> result;
+
+    auto maps = ::conformallab::setup_spherical_maps(mesh);
+    ::conformallab::compute_lambda0_from_mesh(mesh, maps);
+
+    auto theta_param = parameters::get_parameter(
+        np, Conformal_map::internal_np::vertex_curvature_map);
+    constexpr bool has_theta = !std::is_same_v<
+        decltype(theta_param), internal_np::Param_not_found>;
+    if constexpr (has_theta) {
+        for (auto v : mesh.vertices())
+            maps.theta_v[v] = get(theta_param, v);
+    }
+
+    // Pin one vertex (gauge fix) — user-supplied or first vertex.
+    constexpr int FREE = 0;
+    for (auto v : mesh.vertices()) maps.v_idx[v] = FREE;
+
+    auto pin_param = parameters::get_parameter(
+        np, Conformal_map::internal_np::fixed_vertex_map);
+    constexpr bool has_pin = !std::is_same_v<
+        decltype(pin_param), internal_np::Param_not_found>;
+
+    bool any_pinned = false;
+    if constexpr (has_pin) {
+        for (auto v : mesh.vertices())
+            if (get(pin_param, v)) { maps.v_idx[v] = -1; any_pinned = true; }
+    }
+    if (!any_pinned) {
+        auto it = mesh.vertices().begin();
+        if (it != mesh.vertices().end()) { maps.v_idx[*it] = -1; any_pinned = true; }
+    }
+
+    int idx = 0;
+    for (auto v : mesh.vertices())
+        if (maps.v_idx[v] != -1) maps.v_idx[v] = idx++;
+
+    const FT  tol      = parameters::choose_parameter(
+        parameters::get_parameter(np, Conformal_map::internal_np::gradient_tolerance),
+        FT(1e-10));
+    const int max_iter = parameters::choose_parameter(
+        parameters::get_parameter(np, Conformal_map::internal_np::max_iterations),
+        200);
+
+    // Natural-theta default for the spherical functional.
+    std::vector<double> x0(static_cast<std::size_t>(idx), 0.0);
+    if constexpr (!has_theta) {
+        auto G0 = ::conformallab::spherical_gradient(mesh, x0, maps);
+        for (auto v : mesh.vertices()) {
+            const int j = maps.v_idx[v];
+            if (j >= 0) maps.theta_v[v] -= G0[static_cast<std::size_t>(j)];
+        }
+    }
+
+    auto nr = ::conformallab::newton_spherical(mesh, x0, maps, tol, max_iter);
+
+    result.u_per_vertex.assign(num_vertices(mesh), FT(0));
+    for (auto v : mesh.vertices()) {
+        const int j = maps.v_idx[v];
+        if (j >= 0) result.u_per_vertex[v.idx()] = nr.x[static_cast<std::size_t>(j)];
+    }
+    result.iterations    = nr.iterations;
+    result.gradient_norm = nr.grad_inf_norm;
+    result.converged     = nr.converged;
+
+    // Optional 3-D layout step (point on S²)
+    auto uv_param = parameters::get_parameter(
+        np, Conformal_map::internal_np::output_uv_map);
+    constexpr bool has_uv = !std::is_same_v<
+        decltype(uv_param), internal_np::Param_not_found>;
+    if constexpr (has_uv) {
+        if (nr.converged) {
+            auto layout = ::conformallab::spherical_layout(mesh, nr.x, maps);
+            const bool do_norm = parameters::choose_parameter(
+                parameters::get_parameter(np, Conformal_map::internal_np::normalise_layout),
+                false);
+            if (do_norm) ::conformallab::normalise_spherical(layout);
+            for (auto v : mesh.vertices()) {
+                const auto& p = layout.pos[v.idx()];
+                put(uv_param, v,
+                    typename Traits::Kernel::Point_3(p.x(), p.y(), p.z()));
+            }
+        }
+    }
+
+    return result;
+}
+
+
+// ════════════════════════════════════════════════════════════════════════════
+// discrete_conformal_map_hyper_ideal  —  Phase 8b-Lite
+// ════════════════════════════════════════════════════════════════════════════
+
+/*!
+\ingroup PkgConformalMapRef
+
+Result of `discrete_conformal_map_hyper_ideal`.  Carries both vertex
+DOFs `b_v` and edge DOFs `a_e` (hyper-ideal triangles in H³).
+*/
+template <typename FT = double>
+struct Hyper_ideal_map_result
+{
+    /// Vertex DOFs `b_v` (length = num_vertices(mesh); pinned vertices = 0).
+    std::vector<FT> b_per_vertex;
+    /// Edge DOFs `a_e` (length = num_edges(mesh); pinned edges = 0).
+    std::vector<FT> a_per_edge;
+
+    /// Newton iterations actually performed (≤ `max_iterations`).
+    int  iterations    = 0;
+    /// Final infinity-norm of the gradient (Newton stopping criterion).
+    FT   gradient_norm = FT(0);
+    /// `true` iff `gradient_norm < gradient_tolerance` at exit.
+    bool converged     = false;
+};
+
+/*!
+\ingroup PkgConformalMapRef
+
+Compute the hyper-ideal discrete-conformal map of a triangle mesh
+(Springborn 2020 §4).
+
+\note  Phase 8b-Lite scope: vertex DOFs `b_v` are assigned automatically
+       to all vertices; edge DOFs `a_e` are similarly assigned.  The
+       block-FD Hessian (Phase 9b) is used internally — see
+       `newton_hyper_ideal` for the solver convention.
+*/
+template <typename TriangleMesh,
+          typename CGAL_NP_TEMPLATE_PARAMETERS>
+auto discrete_conformal_map_hyper_ideal(
+    TriangleMesh& mesh,
+    const CGAL_NP_CLASS& np = parameters::default_values())
+{
+    using Point_type     = typename TriangleMesh::Point;
+    using Default_kernel = typename CGAL::Kernel_traits<Point_type>::Kernel;
+    using Default_traits = Default_conformal_map_traits<TriangleMesh, Default_kernel>;
+    using Traits         = typename internal_np::Lookup_named_param_def<
+                              internal_np::geom_traits_t,
+                              CGAL_NP_CLASS,
+                              Default_traits>::type;
+    using FT             = typename Traits::FT;
+
+    Hyper_ideal_map_result<FT> result;
+
+    auto maps = ::conformallab::setup_hyper_ideal_maps(mesh);
+    // Hyper-ideal init does not derive from mesh geometry: the user's
+    // Θ_v and θ_e are the model inputs.  Defaults from setup are
+    // Θ_v = 2π, θ_e = π (orthogonal).
+
+    auto theta_param = parameters::get_parameter(
+        np, Conformal_map::internal_np::vertex_curvature_map);
+    constexpr bool has_theta = !std::is_same_v<
+        decltype(theta_param), internal_np::Param_not_found>;
+    if constexpr (has_theta) {
+        for (auto v : mesh.vertices())
+            maps.theta_v[v] = get(theta_param, v);
+    }
+
+    const int n = ::conformallab::assign_all_dof_indices(mesh, maps);
+
+    const FT  tol      = parameters::choose_parameter(
+        parameters::get_parameter(np, Conformal_map::internal_np::gradient_tolerance),
+        FT(1e-8));
+    const int max_iter = parameters::choose_parameter(
+        parameters::get_parameter(np, Conformal_map::internal_np::max_iterations),
+        200);
+
+    // Initial point: b_v = 1.0 (positive log-scale), a_e = 0.5 (moderate).
+    std::vector<double> x0(static_cast<std::size_t>(n), 0.0);
+    for (auto v : mesh.vertices()) {
+        int i = maps.v_idx[v];
+        if (i >= 0) x0[static_cast<std::size_t>(i)] = 1.0;
+    }
+    for (auto e : mesh.edges()) {
+        int i = maps.e_idx[e];
+        if (i >= 0) x0[static_cast<std::size_t>(i)] = 0.5;
+    }
+
+    auto nr = ::conformallab::newton_hyper_ideal(mesh, x0, maps, tol, max_iter);
+
+    result.b_per_vertex.assign(num_vertices(mesh), FT(0));
+    result.a_per_edge   .assign(num_edges(mesh),    FT(0));
+    for (auto v : mesh.vertices()) {
+        int j = maps.v_idx[v];
+        if (j >= 0) result.b_per_vertex[v.idx()] = nr.x[static_cast<std::size_t>(j)];
+    }
+    for (auto e : mesh.edges()) {
+        int j = maps.e_idx[e];
+        if (j >= 0) result.a_per_edge[e.idx()] = nr.x[static_cast<std::size_t>(j)];
+    }
+    result.iterations    = nr.iterations;
+    result.gradient_norm = nr.grad_inf_norm;
+    result.converged     = nr.converged;
+
+    // Optional Poincaré-disk layout (2-D in the unit disk).
+    auto uv_param = parameters::get_parameter(
+        np, Conformal_map::internal_np::output_uv_map);
+    constexpr bool has_uv = !std::is_same_v<
+        decltype(uv_param), internal_np::Param_not_found>;
+    if constexpr (has_uv) {
+        if (nr.converged) {
+            auto layout = ::conformallab::hyper_ideal_layout(mesh, nr.x, maps);
+            const bool do_norm = parameters::choose_parameter(
+                parameters::get_parameter(np, Conformal_map::internal_np::normalise_layout),
+                false);
+            if (do_norm) ::conformallab::normalise_hyperbolic(layout);
+            for (auto v : mesh.vertices()) {
+                const auto& uv = layout.uv[v.idx()];
+                put(uv_param, v,
+                    typename Traits::Kernel::Point_2(uv.x(), uv.y()));
+            }
+        }
+    }
+
+    (void)n;   // already-counted by maps; silence unused-var warnings if any
+    return result;
+}
+
+}  // namespace CGAL
+
+#endif  // CGAL_DISCRETE_CONFORMAL_MAP_H

code/include/CGAL/Discrete_inversive_distance.h

@@ -0,0 +1,263 @@
+// Copyright (c) 2024-2026 Tarik Moussa.
+// SPDX-License-Identifier: MIT
+//
+// Package: conformallab++ / Discrete_conformal_map (Phase 8b-Lite, 2026-05-21)
+
+/*!
+\file CGAL/Discrete_inversive_distance.h
+\ingroup PkgConformalMapRef
+
+User-facing entry for the **vertex-based** inversive-distance circle-
+packing functional of Luo (2004), with the Bowers-Stephenson (2004)
+initialisation.  See `inversive_distance_functional.hpp` for the
+underlying algorithm and `doc/roadmap/research-track.md` (item 9a.2)
+for the research-track classification — this functional has **no Java
+original** (verified empirically), it is from-the-literature research.
+
+DOF structure
+─────────────
+* Per-vertex `u_i = log r_i` (compatible with the classical Euclidean
+  trait).
+* Per-edge constant `I_ij` computed once by Bowers-Stephenson from the
+  input mesh geometry (handled internally by
+  `compute_inversive_distance_init_from_mesh`).
+
+Because the per-edge constant has a different meaning from the
+Euclidean `λ°_e`, this entry has its own default-trait class
+`Default_inversive_distance_traits`.
+*/
+
+#ifndef CGAL_DISCRETE_INVERSIVE_DISTANCE_H
+#define CGAL_DISCRETE_INVERSIVE_DISTANCE_H
+
+#include <CGAL/Conformal_map/internal/parameters.h>
+#include <CGAL/Kernel_traits.h>
+#include <CGAL/Named_function_parameters.h>
+#include <CGAL/boost/graph/named_params_helper.h>
+#include <CGAL/Surface_mesh.h>
+#include <CGAL/Simple_cartesian.h>
+#include <boost/graph/graph_traits.hpp>
+
+#include <CGAL/Discrete_conformal_map.h>   // for Conformal_map_result<FT>
+
+#include "../inversive_distance_functional.hpp"
+#include "../newton_solver.hpp"
+
+namespace CGAL {
+
+// ── Default traits for Inversive-Distance ────────────────────────────────────
+
+/*!
+\ingroup PkgConformalMapConcepts
+\brief Traits class for `discrete_inversive_distance_map()` — declares
+the kernel, mesh and property-map types used by Luo's 2004 vertex-based
+inversive-distance circle packing.
+
+Primary template; specialise it for non-`Surface_mesh` triangle meshes.
+*/
+template <typename TriangleMesh,
+          typename Kernel_ = CGAL::Simple_cartesian<double>>
+struct Default_inversive_distance_traits;
+
+/*!
+\ingroup PkgConformalMapConcepts
+\brief Specialisation for `CGAL::Surface_mesh<P>`; the only one shipped
+in Phase 8b-Lite.
+*/
+template <typename K>
+struct Default_inversive_distance_traits<CGAL::Surface_mesh<typename K::Point_3>, K>
+{
+    /// CGAL kernel parameter (defaults to `Simple_cartesian<double>`).
+    using Kernel        = K;
+    /// Scalar field type used for all inversive-distance DOFs.
+    using FT            = typename K::FT;
+    /// 3-D point type (vertex coordinates).
+    using Point_3       = typename K::Point_3;
+    /// Triangle-mesh type this specialisation targets.
+    using Triangle_mesh = CGAL::Surface_mesh<Point_3>;
+
+    /// Boost-graph vertex descriptor for `Triangle_mesh`.
+    using Vertex_descriptor   = typename boost::graph_traits<Triangle_mesh>::vertex_descriptor;
+    /// Boost-graph edge descriptor for `Triangle_mesh`.
+    using Edge_descriptor     = typename boost::graph_traits<Triangle_mesh>::edge_descriptor;
+
+    // Inversive-distance specific property maps.
+
+    /// Property map vertex → contiguous integer DOF index (legacy `iv:idx`).
+    using Vertex_index_pmap = typename Triangle_mesh::template Property_map<Vertex_descriptor, int>;
+    /// Property map vertex → target cone angle Θᵥ in radians (legacy `iv:theta`).
+    using Theta_v_pmap      = typename Triangle_mesh::template Property_map<Vertex_descriptor, FT>;
+    /// Property map vertex → initial radius r⁰ᵥ (legacy `iv:r0`).
+    using R0_pmap           = typename Triangle_mesh::template Property_map<Vertex_descriptor, FT>;
+    /// Property map edge → inversive distance Iᵢⱼ (legacy `ie:I`).
+    using I_e_pmap          = typename Triangle_mesh::template Property_map<Edge_descriptor,   FT>;
+};
+
+// ── Entry function ────────────────────────────────────────────────────────────
+
+/*!
+\ingroup PkgConformalMapRef
+
+Compute the Luo-2004 vertex-based inversive-distance circle packing of `mesh`.
+
+The per-edge constant `I_ij` is computed once at the start from the input
+3-D geometry via the Bowers-Stephenson identity
+    `I_ij = (ℓ_ij² − r_i² − r_j²) / (2 r_i r_j)`,
+with `r_i^(0) = (1/3) min{ℓ_e : e adj v_i}` as the default initial radii.
+The user can override the initial radii by writing into the `r0`
+property map before calling this function.
+
+\tparam TriangleMesh  A `CGAL::Surface_mesh<P>`.
+\tparam NamedParameters  Optional CGAL named-parameter pack.
+
+\param mesh  Input triangle mesh.
+\param np    Named parameters:
+  - `vertex_curvature_map(pmap)` — per-vertex Θ_v target.
+  - `fixed_vertex_map(pmap)` — pinning override.
+  - `gradient_tolerance(ε)` — Newton stop.
+  - `max_iterations(n)` — Newton iteration cap.
+
+\returns A `Conformal_map_result<FT>` with `u_per_vertex[v] = log r_v`
+         (the converged log-radius at each vertex).
+
+\pre `mesh` is a triangle mesh with positive edge lengths.
+\pre The user-supplied or natural-theta Θ satisfies Gauss–Bonnet.
+
+\note  Convergence is sensitive to the initial point and to extreme
+       `I_ij` values.  For testing purposes the natural-theta default
+       (Θ_v shifted so that u = 0 is the equilibrium) always converges
+       in zero iterations.
+*/
+template <typename TriangleMesh,
+          typename CGAL_NP_TEMPLATE_PARAMETERS>
+auto discrete_inversive_distance_map(
+    TriangleMesh& mesh,
+    const CGAL_NP_CLASS& np = parameters::default_values())
+{
+    using Point_type     = typename TriangleMesh::Point;
+    using Default_kernel = typename CGAL::Kernel_traits<Point_type>::Kernel;
+    using Default_traits = Default_inversive_distance_traits<TriangleMesh, Default_kernel>;
+    using Traits         = typename internal_np::Lookup_named_param_def<
+                              internal_np::geom_traits_t,
+                              CGAL_NP_CLASS,
+                              Default_traits>::type;
+    using FT             = typename Traits::FT;
+
+    Conformal_map_result<FT> result;
+
+    auto maps = ::conformallab::setup_inversive_distance_maps(mesh);
+    ::conformallab::compute_inversive_distance_init_from_mesh(mesh, maps);
+
+    auto theta_param = parameters::get_parameter(
+        np, Conformal_map::internal_np::vertex_curvature_map);
+    constexpr bool has_theta = !std::is_same_v<
+        decltype(theta_param), internal_np::Param_not_found>;
+    if constexpr (has_theta) {
+        for (auto v : mesh.vertices())
+            maps.theta_v[v] = get(theta_param, v);
+    }
+
+    // Pin first vertex by default; user can override with fixed_vertex_map.
+    constexpr int FREE = 0;
+    for (auto v : mesh.vertices()) maps.v_idx[v] = FREE;
+
+    auto pin_param = parameters::get_parameter(
+        np, Conformal_map::internal_np::fixed_vertex_map);
+    constexpr bool has_pin = !std::is_same_v<
+        decltype(pin_param), internal_np::Param_not_found>;
+
+    bool any_pinned = false;
+    if constexpr (has_pin) {
+        for (auto v : mesh.vertices())
+            if (get(pin_param, v)) { maps.v_idx[v] = -1; any_pinned = true; }
+    }
+    if (!any_pinned) {
+        auto it = mesh.vertices().begin();
+        if (it != mesh.vertices().end()) { maps.v_idx[*it] = -1; any_pinned = true; }
+    }
+
+    int idx = 0;
+    for (auto v : mesh.vertices())
+        if (maps.v_idx[v] != -1) maps.v_idx[v] = idx++;
+
+    const FT  tol      = parameters::choose_parameter(
+        parameters::get_parameter(np, Conformal_map::internal_np::gradient_tolerance),
+        FT(1e-10));
+    const int max_iter = parameters::choose_parameter(
+        parameters::get_parameter(np, Conformal_map::internal_np::max_iterations),
+        200);
+
+    // Natural-theta default.
+    std::vector<double> x0(static_cast<std::size_t>(idx), 0.0);
+    if constexpr (!has_theta) {
+        auto G0 = ::conformallab::inversive_distance_gradient(mesh, x0, maps);
+        for (auto v : mesh.vertices()) {
+            const int j = maps.v_idx[v];
+            if (j >= 0) maps.theta_v[v] -= G0[static_cast<std::size_t>(j)];
+        }
+    }
+
+    auto nr = ::conformallab::newton_inversive_distance(mesh, x0, maps, tol, max_iter);
+
+    result.u_per_vertex.assign(num_vertices(mesh), FT(0));
+    for (auto v : mesh.vertices()) {
+        const int j = maps.v_idx[v];
+        if (j >= 0) result.u_per_vertex[v.idx()] = nr.x[static_cast<std::size_t>(j)];
+    }
+    result.iterations    = nr.iterations;
+    result.gradient_norm = nr.grad_inf_norm;
+    result.converged     = nr.converged;
+
+    // ── Optional layout step (Phase 8b-Lite extension) ─────────────────────
+    //
+    // If the caller supplied `output_uv_map(pmap)`, lay out the converged
+    // packing in ℝ² and write per-vertex `Point_2` coordinates into `pmap`.
+    //
+    // Method: the converged Inversive-Distance radii `r_i = exp(u_i)`
+    // together with the fixed per-edge `I_ij` constants determine effective
+    // Euclidean edge lengths via the Bowers-Stephenson identity
+    //   ℓᵢⱼ² = rᵢ² + rⱼ² + 2·Iᵢⱼ·rᵢ·rⱼ
+    // so we can populate a temporary `EuclideanMaps` whose `lambda0` carries
+    // `log(ℓᵢⱼ²)` per edge and then reuse `euclidean_layout(mesh, 0, eucl)`
+    // — the existing priority-BFS trilateration on the resulting triangle
+    // metric.  All vertex/edge DOF indices stay at −1 (pinned), so the empty
+    // DOF vector `0` produces lengths driven purely by `lambda0`.
+    auto uv_param = parameters::get_parameter(
+        np, Conformal_map::internal_np::output_uv_map);
+    constexpr bool has_uv = !std::is_same_v<
+        decltype(uv_param), internal_np::Param_not_found>;
+    if constexpr (has_uv) {
+        if (nr.converged) {
+            auto eucl = ::conformallab::setup_euclidean_maps(mesh);
+            for (auto e : mesh.edges()) {
+                auto h = mesh.halfedge(e);
+                const double u_i = result.u_per_vertex[mesh.source(h).idx()];
+                const double u_j = result.u_per_vertex[mesh.target(h).idx()];
+                const double I   = maps.I_e[e];
+                const double l2  = ::conformallab::id_detail::edge_length_squared(u_i, u_j, I);
+                eucl.lambda0[e]  = (l2 > 0.0) ? std::log(l2) : -30.0;
+            }
+            // Empty DOF vector: every vertex is pinned (idx=-1), so the
+            // layout depends purely on the lambda0 we just computed.
+            std::vector<double> zero;
+            auto layout = ::conformallab::euclidean_layout(mesh, zero, eucl);
+
+            const bool do_norm = parameters::choose_parameter(
+                parameters::get_parameter(np, Conformal_map::internal_np::normalise_layout),
+                false);
+            if (do_norm) ::conformallab::normalise_euclidean(layout);
+
+            for (auto v : mesh.vertices()) {
+                const auto& uv = layout.uv[v.idx()];
+                put(uv_param, v,
+                    typename Traits::Kernel::Point_2(uv.x(), uv.y()));
+            }
+        }
+    }
+
+    return result;
+}
+
+}  // namespace CGAL
+
+#endif  // CGAL_DISCRETE_INVERSIVE_DISTANCE_H

code/include/clausen.hpp

@@ -1,4 +1,7 @@
 #pragma once
+// Copyright (c) 2024-2026 Tarik Moussa.
+// SPDX-License-Identifier: MIT
+
 
 // Clausen integral, Lobachevsky function, and Im(Li2).
 // Ported from de.varylab.discreteconformal.functional.Clausen (Java).
@@ -128,9 +131,9 @@ inline int ncl5pi6() noexcept {
 
 } // namespace detail
 
-// Clausen's integral Cl2(x) = -integral_0^x log|2 sin(t/2)| dt.
+/// Clausen's integral `Cl₂(x) = −∫₀ˣ log|2 sin(t/2)| dt`,
-// High-precision Chebyshev implementation.
+/// computed via a high-precision Chebyshev expansion.
-// Corresponds to Java Clausen.clausen2().
+/// Same as Java `Clausen.clausen2()`.
 inline double clausen2(double x) noexcept {
     using namespace detail;
     constexpr double pi  = 3.14159265358979323846264338328;
@@ -154,8 +157,8 @@ inline double clausen2(double x) noexcept {
     return rh ? -f : f;
 }
 
-// Milnor's Lobachevsky function Л(x) = Cl2(2x)/2.
+/// Milnor's Lobachevsky function `Л(x) = Cl₂(2x) / 2`.
-// Corresponds to Java Clausen.Л().
+/// Same as Java `Clausen.Л()`.
 inline double Lobachevsky(double x) noexcept {
     constexpr double pi = 3.14159265358979323846264338328;
     x = std::fmod(x, pi);
@@ -163,8 +166,8 @@ inline double Lobachevsky(double x) noexcept {
     return clausen2(2.0 * x) / 2.0;
 }
 
-// Imaginary part of the dilogarithm Im(Li2(z)).
+/// Imaginary part of the dilogarithm `Im(Li₂(z))` for complex `z`.
-// Corresponds to Java Clausen.ImLi2().
+/// Same as Java `Clausen.ImLi2()`.
 inline double ImLi2(std::complex<double> z) noexcept {
     auto a = std::log(1.0 - std::conj(z));  // log(1 - conj(z))
     auto b = std::log(1.0 - z);             // log(1 - z)

code/include/conformal_mesh.hpp

@@ -1,4 +1,7 @@
 #pragma once
+// Copyright (c) 2024-2026 Tarik Moussa.
+// SPDX-License-Identifier: MIT
+
 // conformal_mesh.hpp
 //
 // Central mesh type for the discrete conformal mapping algorithms.
@@ -41,30 +44,42 @@ namespace conformallab {
 // ── Kernel ──────────────────────────────────────────────────────────────────
 // Simple double-precision Cartesian.  Conformal mapping algorithms never
 // need exact arithmetic — they operate on floating-point lengths and angles.
+
+/// CGAL kernel used by all conformallab algorithms (double precision).
 using Kernel = CGAL::Simple_cartesian<double>;
+/// 3-D point type (vertex coordinates).
 using Point3 = Kernel::Point_3;
+/// 2-D point type (UV-domain layout coordinates).
 using Point2 = Kernel::Point_2;
 
 // ── Mesh type ────────────────────────────────────────────────────────────────
+/// Triangle mesh carrying all conformal-map data as property maps.
 using ConformalMesh = CGAL::Surface_mesh<Point3>;
 
 // ── Index/descriptor aliases (CGAL 6.x naming) ───────────────────────────────
+/// Vertex descriptor of `ConformalMesh`.
 using Vertex_index   = ConformalMesh::Vertex_index;
+/// Half-edge descriptor of `ConformalMesh`.
 using Halfedge_index = ConformalMesh::Halfedge_index;
+/// Edge descriptor of `ConformalMesh`.
 using Edge_index     = ConformalMesh::Edge_index;
+/// Face descriptor of `ConformalMesh`.
 using Face_index     = ConformalMesh::Face_index;
 
 // ── Geometry type constant (replaces Java CoFace.type enum) ─────────────────
+/// Discrete geometry type that a face/mesh is interpreted in.
+/// Replaces the original Java `CoFace.type` enum.
 enum class GeometryType : int {
-    Euclidean  = 0,
+    Euclidean  = 0, ///< Flat metric (ℝ²).
-    Hyperbolic = 1,
+    Hyperbolic = 1, ///< Hyperbolic metric (ℍ²).
-    Spherical  = 2
+    Spherical  = 2  ///< Spherical metric (S²).
 };
 
 // ── Standard property-map bundles ────────────────────────────────────────────
 
-// Add the vertex properties used by all conformal-map functionals.
+/// Register and return the vertex-side property maps used by all five
-// Returns {lambda, theta, idx}.
+/// DCE functionals: `v:lambda` (log conformal factor), `v:theta` (target
+/// cone angle), `v:idx` (contiguous integer index).
 inline auto add_vertex_properties(ConformalMesh& mesh)
 {
     auto [lambda, ok1] = mesh.add_property_map<Vertex_index, double>("v:lambda", 0.0);
@@ -74,7 +89,8 @@ inline auto add_vertex_properties(ConformalMesh& mesh)
     return std::make_tuple(lambda, theta, idx);
 }
 
-// Add the edge intersection-angle property used by the hyperbolic functional.
+/// Register and return the edge intersection-angle property `e:alpha`
+/// (used by the hyper-ideal functional).
 inline auto add_edge_properties(ConformalMesh& mesh)
 {
     auto [alpha, ok] = mesh.add_property_map<Edge_index, double>("e:alpha", 0.0);
@@ -82,7 +98,7 @@ inline auto add_edge_properties(ConformalMesh& mesh)
     return alpha;
 }
 
-// Add the face geometry-type property.
+/// Register and return the per-face geometry-type property `f:type`.
 inline auto add_face_properties(ConformalMesh& mesh)
 {
     auto [ftype, ok] = mesh.add_property_map<Face_index, int>(

code/include/constants.hpp

@@ -1,4 +1,7 @@
 #pragma once
+// Copyright (c) 2024-2026 Tarik Moussa.
+// SPDX-License-Identifier: MIT
+
 // constants.hpp
 //
 // Single source of truth for mathematical constants used throughout

code/include/cp_euclidean_functional.hpp

@@ -0,0 +1,390 @@
+#pragma once
+// Copyright (c) 2024-2026 Tarik Moussa.
+// SPDX-License-Identifier: MIT
+
+// cp_euclidean_functional.hpp
+//
+// Phase 9a.1 — Circle-Packing Euclidean functional (CP-Euclidean).
+//
+// Ported from de.varylab.discreteconformal.functional.CPEuclideanFunctional
+// (Java, 260 lines).  Mathematical reference:
+//   Bobenko, A. I., Pinkall, U. & Springborn, B. (2010)
+//   "Discrete conformal maps and ideal hyperbolic polyhedra"
+//   Geometry & Topology 14, 379-426.
+//
+// ┌──────────────────────────────────────────────────────────────────────────┐
+// │  FACE-based circle packing                                                │
+// │                                                                           │
+// │  Each face f of the mesh carries a circle of radius R_f.                  │
+// │  The variable is ρ_f = log R_f.                                           │
+// │  Adjacent face-circles intersect at a prescribed angle θ_e per edge.      │
+// │                                                                           │
+// │  This is the FACE-DUAL of the classical vertex-based Luo (2004)           │
+// │  inversive-distance circle packing implemented in                          │
+// │  inversive_distance_functional.hpp (Phase 9a.2).  The relation            │
+// │     I_ij  =  cos θ_e                                                       │
+// │  identifies the two parametrisations (Glickenstein 2011 §5).              │
+// │                                                                           │
+// │  DOFs                                                                     │
+// │    x[f_idx[f]] = ρ_f   (face-dual log-radius)                             │
+// │    f_idx[f] = −1 means f is pinned (ρ_f = 0, gauge fix)                  │
+// │                                                                           │
+// │  Constants                                                                │
+// │    θ_e per edge   intersection angle of the two face-circles              │
+// │    φ_f per face   target sum of corner-angles inside the face             │
+// │                                                                           │
+// │  Energy  (BPS-2010 §6)                                                    │
+// │    E(ρ) =  Σ_f  φ_f · ρ_f                                                  │
+// │         +  Σ_{(h,f=face(h)):                                              │
+// │              [ if opposite face exists ]                                   │
+// │                ½ p(θ*,Δρ)·Δρ + Λ(θ*+p) − θ*·ρ_left                       │
+// │              [ else (boundary halfedge) ]                                  │
+// │                −2 θ*·ρ_left                                                │
+// │            ]                                                              │
+// │                                                                           │
+// │    where    θ* = π − θ                                                    │
+// │             Δρ = ρ_right − ρ_left                                          │
+// │             p(θ*, Δρ) = 2·atan( tan(θ*/2) · tanh(Δρ/2) )                  │
+// │             Λ        = Clausen function (Lobachevsky)                     │
+// │                                                                           │
+// │  Gradient                                                                 │
+// │    Per face f:        +φ_f                                                │
+// │    Per interior hf:   −(p + θ*)  added to G[face(h)]                      │
+// │    Per boundary hf:   −2 θ*       added to G[face(h)]                     │
+// │                                                                           │
+// │  Hessian (analytic, BPS-2010 eq. 6.8; Java getHessian lines 127-166)     │
+// │    Per interior undirected edge e (connecting faces j and k):             │
+// │      h_jk = sin θ / (cosh Δρ − cos θ)                                     │
+// │      H[j,j] += h_jk,  H[k,k] += h_jk,  H[j,k] −= h_jk,  H[k,j] −= h_jk    │
+// │    Pinned faces contribute nothing (their row/col is removed).            │
+// └──────────────────────────────────────────────────────────────────────────┘
+//
+// Halfedge convention (matches Java's "leftFace / rightFace"):
+//   For a directed halfedge h in CGAL::Surface_mesh:
+//     mesh.face(h)             ≡ leftFace
+//     mesh.face(opposite(h))   ≡ rightFace  (may be null on boundary)
+//     mesh.is_border(h) == true iff h has no face (h points outward).
+//   Property-map name prefix: "cf:" (face) and "ce:" (edge).
+
+#include "conformal_mesh.hpp"
+#include "constants.hpp"
+#include "clausen.hpp"
+#include <Eigen/Sparse>
+#include <CGAL/boost/graph/iterator.h>
+#include <vector>
+#include <cmath>
+#include <cstdint>
+#include <iostream>
+
+namespace conformallab {
+
+// ── Property-map type aliases ────────────────────────────────────────────────
+
+/// Property map face → `int`    for the CP-Euclidean functional.
+using CPFMapI = ConformalMesh::Property_map<Face_index, int>;
+/// Property map face → `double` for the CP-Euclidean functional.
+using CPFMapD = ConformalMesh::Property_map<Face_index, double>;
+/// Property map edge → `double` for the CP-Euclidean functional.
+using CPEMapD = ConformalMesh::Property_map<Edge_index, double>;
+
+// ── Persistent map bundle ─────────────────────────────────────────────────────
+
+/// Bundle of the three property maps consumed by the CP-Euclidean
+/// (Bobenko-Pinkall-Springborn 2010) circle-packing functional.
+struct CPEuclideanMaps {
+    CPFMapI f_idx;     ///< DOF index per face (−1 = pinned)
+    CPEMapD theta_e;   ///< intersection angle per edge (default π/2 = orthogonal)
+    CPFMapD phi_f;     ///< target face-angle sum   (default 2π)
+};
+
+/// Attach the three CP-Euclidean property maps to `mesh` with default
+/// values and return their handles.
+///
+/// Defaults:
+/// * `theta_e[e] = π/2` for every edge — orthogonal circle packing
+///   (Koebe-Andreev-Thurston).
+/// * `phi_f[f] = 2π` for every face — flat target.
+/// * `f_idx[f] = -1` for every face — all faces pinned initially;
+///   call `assign_cp_euclidean_face_dof_indices()` next to assign
+///   DOF indices to all faces except one gauge-pinned face.
+///
+/// The maps are named with the `"cf:"` / `"ce:"` prefixes
+/// (cf = circle-packing-face, ce = circle-packing-edge) so they do
+/// not collide with the Euclidean / Spherical / HyperIdeal maps.
+///
+/// \param mesh  Input mesh.  Modified in place: three property maps are
+///              attached if not already present, otherwise the existing
+///              maps are returned unchanged (CGAL property-map idempotence).
+/// \returns     A bundle of all three property maps for caller use.
+inline CPEuclideanMaps setup_cp_euclidean_maps(ConformalMesh& mesh)
+{
+    CPEuclideanMaps m;
+    m.f_idx   = mesh.add_property_map<Face_index, int>   ("cf:idx",   -1     ).first;
+    m.theta_e = mesh.add_property_map<Edge_index, double>("ce:theta", PI / 2 ).first;
+    m.phi_f   = mesh.add_property_map<Face_index, double>("cf:phi",   TWO_PI ).first;
+    return m;
+}
+
+/// Assign sequential DOF indices `0..n-1` to all faces except `pinned`,
+/// which receives the sentinel `-1` (gauge-fixed face, `ρ_pinned = 0`).
+///
+/// Mirrors the Java CPEuclideanFunctional's "skip face index 0"
+/// convention from `evaluateEnergyAndGradient` (lines 184-185 of
+/// CPEuclideanFunctional.java).  The C++ port exposes the choice of
+/// pinned face explicitly rather than hard-coding it.
+///
+/// \param mesh    The mesh.  Read for face iteration only; not modified.
+/// \param m       Map bundle whose `f_idx` is overwritten.
+/// \param pinned  The face whose DOF is fixed at zero (the gauge).
+/// \returns       The number of free DOFs assigned (`num_faces(mesh) - 1`).
+inline int assign_cp_euclidean_face_dof_indices(ConformalMesh&  mesh,
+                                                  CPEuclideanMaps& m,
+                                                  Face_index       pinned)
+{
+    int idx = 0;
+    for (auto f : mesh.faces()) {
+        if (f == pinned) m.f_idx[f] = -1;
+        else             m.f_idx[f] = idx++;
+    }
+    return idx;
+}
+
+/// Convenience overload: pin the **first** face in `mesh.faces()` order.
+/// Use this when any face works as the gauge (typically true for
+/// closed mesh experiments).
+inline int assign_cp_euclidean_face_dof_indices(ConformalMesh&  mesh,
+                                                  CPEuclideanMaps& m)
+{
+    auto it = mesh.faces().begin();
+    if (it == mesh.faces().end()) return 0;
+    return assign_cp_euclidean_face_dof_indices(mesh, m, *it);
+}
+
+/// Count the free DOFs (faces with `f_idx >= 0`).
+/// Equivalent to `num_faces(mesh) - <number of pinned faces>`.
+inline int cp_euclidean_dimension(const ConformalMesh& mesh,
+                                    const CPEuclideanMaps& m)
+{
+    int dim = 0;
+    for (auto f : mesh.faces()) if (m.f_idx[f] >= 0) ++dim;
+    return dim;
+}
+
+// ── Internal helpers ──────────────────────────────────────────────────────────
+
+namespace cp_detail {
+
+// p(θ*, Δρ) = 2·atan( tan(θ*/2) · tanh(Δρ/2) )
+// Numerically stable form lifted directly from CPEuclideanFunctional.java
+// (private method `p`, lines 243-247).
+inline double p_function(double thStar, double dRho) noexcept
+{
+    const double e          = std::exp(dRho);
+    const double tanh_half  = (e - 1.0) / (e + 1.0);
+    return 2.0 * std::atan(std::tan(0.5 * thStar) * tanh_half);
+}
+
+// DOF reader: returns 0 for the pinned face (idx = −1).
+inline double dof_val(int idx, const std::vector<double>& x) noexcept
+{
+    return idx >= 0 ? x[static_cast<std::size_t>(idx)] : 0.0;
+}
+
+} // namespace cp_detail
+
+/// CP-Euclidean energy value at DOF vector `x` (ρ per face).
+/// Mirrors `evaluateEnergyAndGradient()` in the Java original (lines 170-240).
+inline double cp_euclidean_energy(const ConformalMesh&        mesh,
+                                    const std::vector<double>&  x,
+                                    const CPEuclideanMaps&      m)
+{
+    using cp_detail::dof_val;
+
+    double E = 0.0;
+
+    // Per-face linear term: + φ_f · ρ_f
+    // (The pinned face has f_idx = −1; its ρ is fixed at 0 so it contributes nothing.)
+    for (auto f : mesh.faces()) {
+        const int i = m.f_idx[f];
+        if (i < 0) continue;
+        E += m.phi_f[f] * x[static_cast<std::size_t>(i)];
+    }
+
+    // Per directed halfedge term.  Java iterates over `getEdges()` which in jtem
+    // yields one Edge per directed side; in CGAL we iterate halfedges directly.
+    for (auto h : mesh.halfedges()) {
+        if (mesh.is_border(h)) continue;   // h is in the outer "border" face → skip
+        const Face_index fL = mesh.face(h);
+        const Halfedge_index ho = mesh.opposite(h);
+        const Face_index fR = mesh.is_border(ho) ? Face_index() : mesh.face(ho);
+
+        const double th     = m.theta_e[mesh.edge(h)];
+        const double thStar = PI - th;
+        const double rho_L  = dof_val(m.f_idx[fL], x);
+
+        if (fR == Face_index()) {
+            // Boundary halfedge: only the left face exists.
+            E += -2.0 * thStar * rho_L;
+        } else {
+            const double rho_R = dof_val(m.f_idx[fR], x);
+            const double dRho  = rho_R - rho_L;
+            const double p     = cp_detail::p_function(thStar, dRho);
+            E += 0.5 * p * dRho;
+            E += clausen2(thStar + p);
+            E += -thStar * rho_L;
+        }
+    }
+
+    return E;
+}
+
+/// CP-Euclidean gradient `∂E/∂ρ_f` (per face DOF).  Interior term
+/// `−(p + θ*)`, boundary term `−2 θ*`; see `setup_cp_euclidean_maps`.
+inline std::vector<double> cp_euclidean_gradient(const ConformalMesh&        mesh,
+                                                   const std::vector<double>&  x,
+                                                   const CPEuclideanMaps&      m)
+{
+    using cp_detail::dof_val;
+
+    const int n = cp_euclidean_dimension(mesh, m);
+    std::vector<double> G(static_cast<std::size_t>(n), 0.0);
+
+    // Per-face linear term.
+    for (auto f : mesh.faces()) {
+        const int i = m.f_idx[f];
+        if (i < 0) continue;
+        G[static_cast<std::size_t>(i)] += m.phi_f[f];
+    }
+
+    // Per directed halfedge term.
+    for (auto h : mesh.halfedges()) {
+        if (mesh.is_border(h)) continue;
+        const Face_index fL = mesh.face(h);
+        const int        iL = m.f_idx[fL];
+        if (iL < 0) continue;   // pinned face: gradient component is forced to 0
+
+        const Halfedge_index ho = mesh.opposite(h);
+        const Face_index fR = mesh.is_border(ho) ? Face_index() : mesh.face(ho);
+
+        const double th     = m.theta_e[mesh.edge(h)];
+        const double thStar = PI - th;
+        const double rho_L  = dof_val(iL, x);
+
+        if (fR == Face_index()) {
+            G[static_cast<std::size_t>(iL)] -= 2.0 * thStar;
+        } else {
+            const double rho_R = dof_val(m.f_idx[fR], x);
+            const double dRho  = rho_R - rho_L;
+            const double p     = cp_detail::p_function(thStar, dRho);
+            G[static_cast<std::size_t>(iL)] -= (p + thStar);
+        }
+    }
+
+    return G;
+}
+
+/// Analytic CP-Euclidean Hessian, sparse.  Per interior edge `(j,k)`
+/// the contribution is `h_jk = sin θ / (cosh(Δρ) − cos θ)`, added to
+/// diagonals `H_jj`, `H_kk` and subtracted off-diagonals `H_jk = H_kj`.
+/// Pinned faces are excluded (DOF index −1).
+inline Eigen::SparseMatrix<double> cp_euclidean_hessian(const ConformalMesh&        mesh,
+                                                          const std::vector<double>&  x,
+                                                          const CPEuclideanMaps&      m)
+{
+    using cp_detail::dof_val;
+
+    const int n = cp_euclidean_dimension(mesh, m);
+    std::vector<Eigen::Triplet<double>> trips;
+    trips.reserve(static_cast<std::size_t>(4 * mesh.number_of_edges()));
+
+    for (auto e : mesh.edges()) {
+        const Halfedge_index h  = mesh.halfedge(e);
+        const Halfedge_index ho = mesh.opposite(h);
+        if (mesh.is_border(h) || mesh.is_border(ho)) continue;   // boundary edge
+
+        const int j = m.f_idx[mesh.face(h)];
+        const int k = m.f_idx[mesh.face(ho)];
+
+        const double rho_j = dof_val(j, x);
+        const double rho_k = dof_val(k, x);
+        const double dRho  = rho_k - rho_j;
+        const double th    = m.theta_e[e];
+        const double hjk   = std::sin(th) / (std::cosh(dRho) - std::cos(th));
+
+        if (j >= 0)              trips.emplace_back(j, j,  hjk);
+        if (k >= 0)              trips.emplace_back(k, k,  hjk);
+        if (j >= 0 && k >= 0) {
+            trips.emplace_back(j, k, -hjk);
+            trips.emplace_back(k, j, -hjk);
+        }
+    }
+
+    Eigen::SparseMatrix<double> H(n, n);
+    H.setFromTriplets(trips.begin(), trips.end());
+    return H;
+}
+
+/// FD gradient check for the CP-Euclidean functional.  Mirrors the
+/// Java `FunctionalTest`; default `eps = 1e-5`, `tol = 1e-6`.
+inline bool gradient_check_cp_euclidean(const ConformalMesh&        mesh,
+                                          const std::vector<double>&  x,
+                                          const CPEuclideanMaps&      m,
+                                          double eps = 1e-5,
+                                          double tol = 1e-6)
+{
+    auto G = cp_euclidean_gradient(mesh, x, m);
+    const std::size_t n = G.size();
+
+    for (std::size_t i = 0; i < n; ++i) {
+        std::vector<double> xp = x, xm = x;
+        xp[i] += eps;
+        xm[i] -= eps;
+        const double Ep = cp_euclidean_energy(mesh, xp, m);
+        const double Em = cp_euclidean_energy(mesh, xm, m);
+        const double fd = (Ep - Em) / (2.0 * eps);
+        if (std::abs(G[i] - fd) > tol) {
+            std::cerr << "[cp-euclidean] FD gradient mismatch at DOF " << i
+                      << ": analytic=" << G[i]
+                      << "  FD=" << fd
+                      << "  diff=" << (G[i] - fd) << "\n";
+            return false;
+        }
+    }
+    return true;
+}
+
+/// FD Hessian check for the CP-Euclidean functional.  Verifies analytic
+/// `H` column-by-column against `(G(x+εe_j) − G(x−εe_j)) / (2ε)`.
+inline bool hessian_check_cp_euclidean(const ConformalMesh&        mesh,
+                                         const std::vector<double>&  x,
+                                         const CPEuclideanMaps&      m,
+                                         double eps = 1e-5,
+                                         double tol = 1e-5)
+{
+    const auto H = cp_euclidean_hessian(mesh, x, m);
+    const int n = static_cast<int>(H.rows());
+
+    for (int j = 0; j < n; ++j) {
+        std::vector<double> xp = x, xm = x;
+        xp[static_cast<std::size_t>(j)] += eps;
+        xm[static_cast<std::size_t>(j)] -= eps;
+        auto Gp = cp_euclidean_gradient(mesh, xp, m);
+        auto Gm = cp_euclidean_gradient(mesh, xm, m);
+
+        for (int i = 0; i < n; ++i) {
+            double fd = (Gp[static_cast<std::size_t>(i)] - Gm[static_cast<std::size_t>(i)])
+                        / (2.0 * eps);
+            double an = H.coeff(i, j);
+            if (std::abs(an - fd) > tol) {
+                std::cerr << "[cp-euclidean] FD Hessian mismatch at ("
+                          << i << "," << j << "): analytic=" << an
+                          << "  FD=" << fd
+                          << "  diff=" << (an - fd) << "\n";
+                return false;
+            }
+        }
+    }
+    return true;
+}
+
+} // namespace conformallab

code/include/cut_graph.hpp

@@ -1,4 +1,7 @@
 #pragma once
+// Copyright (c) 2024-2026 Tarik Moussa.
+// SPDX-License-Identifier: MIT
+
 // cut_graph.hpp
 //
 // Phase 6 — Tree-cotree algorithm for computing a cut graph of a triangulated
@@ -36,6 +39,8 @@ namespace conformallab {
 // CutGraph
 // ─────────────────────────────────────────────────────────────────────────────
 
+/// Cut-graph result of the tree-cotree algorithm: the set of `2g` edges
+/// whose removal turns a closed genus-`g` surface into a topological disk.
 struct CutGraph {
     /// cut_edge_flags[e.idx()] = true ↔ this edge is a cut edge.
     /// Size = mesh.number_of_edges().
@@ -47,6 +52,7 @@ struct CutGraph {
     /// Genus of the surface (0 for topological spheres and open patches).
     int genus = 0;
 
+    /// `true` iff edge `e` is a cut edge of this graph.
     bool is_cut(Edge_index e) const
     {
         return static_cast<std::size_t>(e.idx()) < cut_edge_flags.size()
@@ -54,17 +60,10 @@ struct CutGraph {
     }
 };
 
-// ─────────────────────────────────────────────────────────────────────────────
+/// Compute the cut graph of `mesh` via the standard tree-cotree
-// compute_cut_graph
+/// algorithm (Erickson–Whittlesey 2005): primal BFS spanning tree T,
-// ─────────────────────────────────────────────────────────────────────────────
+/// dual BFS spanning tree T* avoiding T-primals, then the `2g` cut
-//
+/// edges are those in neither T nor T*.
-// Implements the standard tree-cotree algorithm (Erickson–Whittlesey 2005):
-//
-//   Step 1: BFS primal spanning tree T  (V−1 primal tree edges).
-//   Step 2: BFS dual spanning tree T*   (F−1 dual/primal edges, avoiding
-//           edges whose primal crosses T).
-//   Step 3: cut edges = primal edges neither in T nor "used" by T*.
-
 inline CutGraph compute_cut_graph(const ConformalMesh& mesh)
 {
     const std::size_t nv = mesh.number_of_vertices();

code/include/discrete_elliptic_utility.hpp

@@ -1,4 +1,7 @@
 #pragma once
+// Copyright (c) 2024-2026 Tarik Moussa.
+// SPDX-License-Identifier: MIT
+
 
 // Ported from de.varylab.discreteconformal.util.DiscreteEllipticUtility (Java).
 // Only the pure-math subset (no HDS required).
@@ -17,7 +20,9 @@ namespace conformallab {
 //   3. Re-flip:   Re < 0              →  Re = -Re
 //   4. S-invert:  |tau| < 1           →  tau = 1/tau
 //
-// Corresponds to Java DiscreteEllipticUtility.normalizeModulus(Complex).
+/// Normalise a complex modulus `τ` into the standard fundamental
+/// domain of an elliptic curve (`|τ| ≥ 1`, `0 ≤ Re τ ≤ ½`, `Im τ ≥ 0`).
+/// Same as Java `DiscreteEllipticUtility.normalizeModulus(Complex)`.
 inline std::complex<double> normalizeModulus(std::complex<double> tau) {
     int maxIter = 100;
     while (--maxIter > 0) {

code/include/euclidean_functional.hpp

@@ -1,4 +1,7 @@
 #pragma once
+// Copyright (c) 2024-2026 Tarik Moussa.
+// SPDX-License-Identifier: MIT
+
 // euclidean_functional.hpp
 //
 // Energy and gradient of the Euclidean discrete conformal functional
@@ -48,13 +51,18 @@ namespace conformallab {
 
 // ── Property-map type aliases ─────────────────────────────────────────────────
 
+/// Property map vertex → `double` for the Euclidean functional.
 using EuclVMapD = ConformalMesh::Property_map<Vertex_index, double>;
+/// Property map vertex → `int`    for the Euclidean functional.
 using EuclVMapI = ConformalMesh::Property_map<Vertex_index, int>;
+/// Property map edge   → `double` for the Euclidean functional.
 using EuclEMapD = ConformalMesh::Property_map<Edge_index,   double>;
+/// Property map edge   → `int`    for the Euclidean functional.
 using EuclEMapI = ConformalMesh::Property_map<Edge_index,   int>;
 
 // ── Persistent map bundle ─────────────────────────────────────────────────────
 
+/// Bundle of the five property maps consumed by the Euclidean functional.
 struct EuclideanMaps {
     EuclVMapI v_idx;    ///< DOF index per vertex   (-1 = pinned / u_v = 0)
     EuclEMapI e_idx;    ///< DOF index per edge      (-1 = no edge DOF)
@@ -63,8 +71,17 @@ struct EuclideanMaps {
     EuclEMapD lambda0;  ///< base log-length λ°_e    (default 0.0)
 };
 
-// Create and attach property maps with sensible defaults.
+/// Attach the five Euclidean property maps to `mesh` with sensible
-// theta_v = 2π (flat vertex), phi_e = π (interior edge, flat surface).
+/// defaults and return their handles.
+///
+/// Defaults:
+/// * `v_idx[v] = -1`  (every vertex pinned; user must reassign before solving)
+/// * `e_idx[e] = -1`  (no edge DOFs by default; use `assign_euclidean_all_dof_indices` for cyclic functional)
+/// * `theta_v[v] = 2π`  (flat interior vertex target)
+/// * `phi_e[e] = π`     (interior edge turn angle target — flat surface)
+/// * `lambda0[e] = 0`   (placeholder; call `compute_euclidean_lambda0_from_mesh` next)
+///
+/// Map name prefix: `"ev:"` (vertex) and `"ee:"` (edge).
 inline EuclideanMaps setup_euclidean_maps(ConformalMesh& mesh)
 {
     EuclideanMaps m;
@@ -76,7 +93,12 @@ inline EuclideanMaps setup_euclidean_maps(ConformalMesh& mesh)
     return m;
 }
 
-// Assign DOF indices 0..n-1 for all vertices only (no edge DOFs).
+/// Assign sequential DOF indices `0..n-1` to all vertices.
+///
+/// **Note:** does NOT pin a gauge vertex.  For closed meshes the caller
+/// must set one `m.v_idx[v] = -1` either before or after this call to
+/// remove the rotational mode (the Newton solver's SparseQR fallback
+/// will otherwise pick a minimum-norm solution but at higher cost).
 inline int assign_euclidean_vertex_dof_indices(ConformalMesh& mesh, EuclideanMaps& m)
 {
     int idx = 0;
@@ -84,7 +106,10 @@ inline int assign_euclidean_vertex_dof_indices(ConformalMesh& mesh, EuclideanMap
     return idx;
 }
 
-// Assign DOF indices for all vertices AND all edges.
+/// Assign DOF indices for all vertices AND all edges (vertex-DOFs first,
+/// then edge-DOFs).  Use this overload for the "cyclic" formulation that
+/// includes per-edge log-length DOFs (`λ_e`) on top of per-vertex scale
+/// factors (`u_v`).
 inline int assign_euclidean_all_dof_indices(ConformalMesh& mesh, EuclideanMaps& m)
 {
     int idx = 0;
@@ -93,7 +118,7 @@ inline int assign_euclidean_all_dof_indices(ConformalMesh& mesh, EuclideanMaps&
     return idx;
 }
 
-// Count variable DOFs (vertices + edges).
+/// Count the free DOFs (vertices + edges with index `≥ 0`).
 inline int euclidean_dimension(const ConformalMesh& mesh, const EuclideanMaps& m)
 {
     int dim = 0;
@@ -102,10 +127,9 @@ inline int euclidean_dimension(const ConformalMesh& mesh, const EuclideanMaps& m
     return dim;
 }
 
-// Set lambda0 from mesh vertex positions (Euclidean):
+/// Set `lambda0` from mesh vertex positions:
-//   λ°_e = 2·log(|p_i − p_j|)   (natural log of Euclidean edge length squared)
+/// `λ°_e = 2·log(|p_i − p_j|)` (natural log of Euclidean edge length²).
-//
+/// This gives `exp(Λ̃_ij / 2) = l_ij` at `x = 0`.
-// This gives exp(Λ̃_ij / 2) = l_ij at x=0.
 inline void compute_euclidean_lambda0_from_mesh(ConformalMesh& mesh, EuclideanMaps& m)
 {
     for (auto e : mesh.edges()) {
@@ -125,25 +149,23 @@ inline void compute_euclidean_lambda0_from_mesh(ConformalMesh& mesh, EuclideanMa
 
 // ── Internal helpers ──────────────────────────────────────────────────────────
 
+/// Read DOF value from `x` for index `idx`; return 0 if pinned (idx < 0).
 static inline double eucl_dof_val(int idx, const std::vector<double>& x)
 {
     return idx >= 0 ? x[static_cast<std::size_t>(idx)] : 0.0;
 }
 
+/// Convert a CGAL half-edge index to a plain `std::size_t` for vector indexing.
 static inline std::size_t eucl_hidx(Halfedge_index h)
 {
     return static_cast<std::size_t>(static_cast<std::uint32_t>(h));
 }
 
-// ── Gradient ──────────────────────────────────────────────────────────────────
+/// Compute the Euclidean-functional gradient G(x):
-//
+///   * `G_v = Θ_v − Σ_faces α_v(face)`
-// G_v = Θ_v − Σ_{faces adj. v} α_v(face)
+///   * `G_e = α_opp(face⁺) + α_opp(face⁻) − φ_e`
-// G_e = α_opp(face⁺) + α_opp(face⁻) − φ_e
+///
-//
+/// Same half-edge corner-angle storage convention as `spherical_gradient`.
-// Corner-angle storage (h_alpha):
-//   h_alpha[h] = corner angle OPPOSITE to the edge of halfedge h in its face.
-//   h_alpha[h0] = α3,  h_alpha[h1] = α1,  h_alpha[h2] = α2
-// (same convention as SphericalFunctional)
 inline std::vector<double> euclidean_gradient(
     ConformalMesh&             mesh,
     const std::vector<double>& x,
@@ -221,9 +243,8 @@ inline std::vector<double> euclidean_gradient(
     return G;
 }
 
-// ── Energy via Gauss-Legendre path integral ───────────────────────────────────
+/// Euclidean energy `E(x) = ∫₀¹ ⟨G(t·x), x⟩ dt`, evaluated with
-//
+/// 10-point Gauss-Legendre quadrature (same as the Spherical functional).
-// E(x) = ∫₀¹ ⟨G(tx), x⟩ dt   (10-point GL quadrature, same as SphericalFunctional)
 inline double euclidean_energy(
     ConformalMesh&             mesh,
     const std::vector<double>& x,
@@ -265,11 +286,14 @@ inline double euclidean_energy(
 
 // ── Full evaluation (energy + gradient) ──────────────────────────────────────
 
+/// Output of `evaluate_euclidean()` — energy plus optional gradient.
 struct EuclideanResult {
-    double              energy   = 0.0;
+    double              energy   = 0.0; ///< Functional value at input DOFs.
-    std::vector<double> gradient;
+    std::vector<double> gradient;       ///< Gradient ∇E (empty if not requested).
 };
 
+/// Evaluate the Euclidean functional at DOFs `x`.  Returns energy and
+/// gradient (toggle via `need_energy` / `need_gradient`).
 inline EuclideanResult evaluate_euclidean(
     ConformalMesh&             mesh,
     const std::vector<double>& x,
@@ -285,10 +309,8 @@ inline EuclideanResult evaluate_euclidean(
     return res;
 }
 
-// ── Finite-difference gradient check ─────────────────────────────────────────
+/// Finite-difference gradient check for the Euclidean functional
-//
+/// (central differences).  Defaults `eps = 1e-5`, `tol = 1e-4`.
-// Tests |G[i] − (E(x+εeᵢ) − E(x−εeᵢ))/(2ε)| / max(1,|G[i]|) < tol
-// for all variable DOFs.
 inline bool gradient_check_euclidean(
     ConformalMesh&             mesh,
     const std::vector<double>& x0,

code/include/euclidean_geometry.hpp

@@ -1,4 +1,7 @@
 #pragma once
+// Copyright (c) 2024-2026 Tarik Moussa.
+// SPDX-License-Identifier: MIT
+
 // euclidean_geometry.hpp
 //
 // Corner-angle formula for Euclidean triangles in the discrete conformal
@@ -29,19 +32,17 @@
 
 namespace conformallab {
 
+/// Interior corner angles of a Euclidean triangle.
 struct EuclideanFaceAngles {
-    double alpha1;   ///< corner angle at v1 (opposite l23)
+    double alpha1;   ///< Corner angle at v₁ (opposite l₂₃).
-    double alpha2;   ///< corner angle at v2 (opposite l31)
+    double alpha2;   ///< Corner angle at v₂ (opposite l₃₁).
-    double alpha3;   ///< corner angle at v3 (opposite l12)
+    double alpha3;   ///< Corner angle at v₃ (opposite l₁₂).
-    bool   valid;
+    bool   valid;    ///< `false` when the triangle is degenerate.
 };
 
-// ── From side lengths ─────────────────────────────────────────────────────────
+/// Compute the corner angles of a Euclidean triangle from its three
-//
+/// side lengths.  Returns `valid = false` when the triangle inequality
-// Given three Euclidean side lengths l12, l23, l31 > 0 satisfying the triangle
+/// is violated.
-// inequality, compute the corner angles.
-//
-// Returns valid=false if the triangle inequality is violated (any t-value ≤ 0).
 inline EuclideanFaceAngles euclidean_angles_from_lengths(
     double l12, double l23, double l31)
 {
@@ -70,14 +71,9 @@ inline EuclideanFaceAngles euclidean_angles_from_lengths(
     };
 }
 
-// ── From effective log-lengths Λ̃ ─────────────────────────────────────────────
+/// Compute the corner angles of a Euclidean triangle from its three
-//
+/// effective log-lengths `Λ̃ᵢⱼ`.  Internally centres lengths so that
-// Converts to side lengths l_ij = exp(Λ̃_ij / 2), applying the centering
+/// `l₁₂·l₂₃·l₃₁ = 1` to avoid float overflow for large `|Λ̃|`.
-// trick for numerical safety, then delegates to euclidean_angles_from_lengths.
-//
-// The centering constant μ = (Λ̃12 + Λ̃23 + Λ̃31) / 6 ensures
-//   l12 · l23 · l31 = 1  (geometric mean = 1)
-// which keeps all l values near 1 and prevents float overflow for large |Λ̃|.
 inline EuclideanFaceAngles euclidean_angles(
     double lam12, double lam23, double lam31)
 {

code/include/euclidean_hessian.hpp

@@ -1,4 +1,7 @@
 #pragma once
+// Copyright (c) 2024-2026 Tarik Moussa.
+// SPDX-License-Identifier: MIT
+
 // euclidean_hessian.hpp
 //
 // Analytical Hessian of the Euclidean discrete conformal energy —
@@ -52,8 +55,18 @@ namespace conformallab {
 // cot_k = (t_adj·l123 − t_opp·t_other) / (8·Area)
 //
 // Returns {0,0,0} for degenerate faces (triangle inequality violated or Area=0).
-struct EuclCotWeights { double cot1, cot2, cot3; bool valid; };
+/// Three Euclidean cotangent weights `(cot1, cot2, cot3)` for the
+/// vertices opposite to edges (l₂₃, l₃₁, l₁₂) of a triangle, plus a
+/// `valid` flag that is `false` when the triangle is degenerate.
+struct EuclCotWeights {
+    double cot1; ///< Cotangent at vertex 1 (opposite to l₂₃).
+    double cot2; ///< Cotangent at vertex 2 (opposite to l₃₁).
+    double cot3; ///< Cotangent at vertex 3 (opposite to l₁₂).
+    bool   valid;///< `false` when the triangle is degenerate (triangle inequality violated or area = 0).
+};
 
+/// Compute the three Euclidean cotangent weights from edge lengths.
+/// Returns `{0,0,0,false}` for degenerate triangles.
 inline EuclCotWeights euclidean_cot_weights(double l12, double l23, double l31)
 {
     const double t12 = -l12 + l23 + l31;
@@ -81,15 +94,9 @@ inline EuclCotWeights euclidean_cot_weights(double l12, double l23, double l31)
     };
 }
 
-// ── Analytical Hessian (cotangent Laplacian) ──────────────────────────────────
+/// Analytical Euclidean Hessian (cotangent Laplacian), sparse.
-//
+/// Only vertex DOFs are supported — the function asserts that no edge
-// Returns the n×n sparse Hessian matrix H where n = euclidean_dimension(mesh, m).
+/// DOF is variable.  `x` is used to compute effective log-lengths Λ̃ᵢⱼ.
-//
-// Only vertex DOFs are supported.  Edge DOFs (m.e_idx[e] >= 0) produce
-// additional mixed-derivative entries that are not yet implemented; this
-// function asserts they are absent.
-//
-// x   – current DOF vector (used to compute effective log-lengths Λ̃ij).
 inline Eigen::SparseMatrix<double> euclidean_hessian(
     ConformalMesh&             mesh,
     const std::vector<double>& x,
@@ -168,11 +175,9 @@ inline Eigen::SparseMatrix<double> euclidean_hessian(
 }
 
 // ── Finite-difference Hessian check ──────────────────────────────────────────
-//
+/// FD Hessian check for the Euclidean functional.  Compares analytic
-// Compares the analytical Hessian column-by-column against
+/// `H` column-by-column to `(G(x+εeⱼ) − G(x−εeⱼ)) / (2ε)`; returns
-//   H_fd[:, j] = (G(x + ε·eⱼ) − G(x − ε·eⱼ)) / (2ε).
+/// `true` iff max relative error is below `tol`.
-//
-// Returns true if max relative error < tol for every entry.
 inline bool hessian_check_euclidean(
     ConformalMesh&             mesh,
     const std::vector<double>& x0,

code/include/fundamental_domain.hpp

@@ -1,4 +1,7 @@
 #pragma once
+// Copyright (c) 2024-2026 Tarik Moussa.
+// SPDX-License-Identifier: MIT
+
 // fundamental_domain.hpp
 //
 // Phase 7 — Fundamental domain polygon for closed surfaces.
@@ -43,6 +46,9 @@ namespace conformallab {
 // FundamentalDomain
 // ─────────────────────────────────────────────────────────────────────────────
 
+/// Fundamental polygon of a closed surface obtained by cutting along a
+/// `CutGraph`: corner vertices, paired-edge identifications and holonomy
+/// generators.  For genus-1 the polygon is a parallelogram with 4 corners.
 struct FundamentalDomain {
     /// Polygon corners in order (CCW).  Size = 4 for genus-1.
     std::vector<Eigen::Vector2d> vertices;
@@ -56,6 +62,7 @@ struct FundamentalDomain {
     /// For genus-1: generators[0] = ω_1, generators[1] = ω_2.
     std::vector<Eigen::Vector2d> generators;
 
+    /// `true` iff the polygon has at least 3 vertices.
     bool is_valid() const { return vertices.size() >= 3; }
 };
 
@@ -75,6 +82,8 @@ struct FundamentalDomain {
 //   bottom (v0→v1) ≡ top    (v3→v2)   by ω_2
 //   left   (v3→v0) ≡ right  (v2→v1)   by ω_1   (reversed convention)
 // ─────────────────────────────────────────────────────────────────────────────
+/// Build the parallelogram fundamental domain from genus-1 Euclidean
+/// holonomy data (`hol.translations[0] = ω₁`, `hol.translations[1] = ω₂`).
 inline FundamentalDomain compute_fundamental_domain_genus1(
     const HolonomyData& hol)
 {
@@ -148,6 +157,8 @@ inline FundamentalDomain compute_fundamental_domain_genus1(
 //   this is intentionally deferred and NOT implemented here.
 //   See period_matrix.hpp for the genus-1 case (τ = ω_2/ω_1 ∈ ℍ).
 // ─────────────────────────────────────────────────────────────────────────────
+/// Dispatcher: for genus 1 returns `compute_fundamental_domain_genus1`,
+/// for higher genus returns an empty domain (4g-polygon not yet implemented).
 inline FundamentalDomain compute_fundamental_domain(
     const HolonomyData& hol)
 {
@@ -165,6 +176,8 @@ inline FundamentalDomain compute_fundamental_domain(
 // return a translated copy of the layout shifted by m·ω_1 + n·ω_2.
 // Useful for visualising the tiled universal cover.
 // ─────────────────────────────────────────────────────────────────────────────
+/// Return a translated copy of `layout` shifted by `m·ω₁ + n·ω₂`.
+/// Useful for visualising the tiled universal cover.
 inline Layout2D tiling_copy(const Layout2D& layout,
                              const Eigen::Vector2d& w1,
                              const Eigen::Vector2d& w2,
@@ -183,6 +196,8 @@ inline Layout2D tiling_copy(const Layout2D& layout,
 // Returns a vector of tiling copies for (m, n) with |m| ≤ m_max, |n| ≤ n_max.
 // The result includes the original (m=0, n=0) at index (m_max)(2*n_max+1)+n_max.
 // ─────────────────────────────────────────────────────────────────────────────
+/// Build a tiling neighbourhood: all `(m, n)` with `|m| ≤ m_max`,
+/// `|n| ≤ n_max`.  The original tile `(0, 0)` is included.
 inline std::vector<Layout2D> tiling_neighbourhood(
     const Layout2D&    layout,
     const HolonomyData& hol,

code/include/gauss_bonnet.hpp

@@ -1,4 +1,7 @@
 #pragma once
+// Copyright (c) 2024-2026 Tarik Moussa.
+// SPDX-License-Identifier: MIT
+
 // gauss_bonnet.hpp
 //
 // Phase 6 — Gauss–Bonnet consistency check for prescribed target angles.
@@ -56,6 +59,7 @@ inline int genus(const ConformalMesh& mesh)
 
 // ── Left-hand side  Σ(2π − Θ_v) ─────────────────────────────────────────────
 
+/// Sum `Σ_v (2π − Θ_v)` for a raw vertex → angle property map.
 inline double gauss_bonnet_sum(
     const ConformalMesh&                                      mesh,
     const ConformalMesh::Property_map<Vertex_index, double>&  theta)
@@ -66,15 +70,19 @@ inline double gauss_bonnet_sum(
     return s;
 }
 
+/// `gauss_bonnet_sum` for the Euclidean-functional property bundle.
 inline double gauss_bonnet_sum(const ConformalMesh& m, const EuclideanMaps&   mp)
     { return gauss_bonnet_sum(m, mp.theta_v); }
+/// `gauss_bonnet_sum` for the Spherical-functional property bundle.
 inline double gauss_bonnet_sum(const ConformalMesh& m, const SphericalMaps&   mp)
     { return gauss_bonnet_sum(m, mp.theta_v); }
+/// `gauss_bonnet_sum` for the HyperIdeal-functional property bundle.
 inline double gauss_bonnet_sum(const ConformalMesh& m, const HyperIdealMaps&  mp)
     { return gauss_bonnet_sum(m, mp.theta_v); }
 
 // ── Right-hand side  2π · χ(M) ───────────────────────────────────────────────
 
+/// Right-hand side of Gauss-Bonnet: `2π · χ(M)`.
 inline double gauss_bonnet_rhs(const ConformalMesh& mesh)
 {
     return TWO_PI * static_cast<double>(euler_characteristic(mesh));
@@ -82,14 +90,15 @@ inline double gauss_bonnet_rhs(const ConformalMesh& mesh)
 
 // ── Deficit: lhs − rhs  (0 = Gauss–Bonnet satisfied) ─────────────────────────
 
+/// Gauss-Bonnet deficit `lhs − rhs`; zero iff the identity is satisfied.
 template <typename Maps>
 inline double gauss_bonnet_deficit(const ConformalMesh& mesh, const Maps& maps)
 {
     return gauss_bonnet_sum(mesh, maps) - gauss_bonnet_rhs(mesh);
 }
 
-// ── check_gauss_bonnet — throws std::runtime_error if |deficit| > tol ─────────
+/// Throws `std::runtime_error` if `|lhs − 2π·χ| > tol`.
-
+/// Overload accepting a precomputed `lhs`.
 inline void check_gauss_bonnet(const ConformalMesh& mesh,
                                 double lhs,
                                 double tol = 1e-8)
@@ -108,6 +117,7 @@ inline void check_gauss_bonnet(const ConformalMesh& mesh,
     }
 }
 
+/// Throws `std::runtime_error` if Gauss-Bonnet is violated by more than `tol`.
 template <typename Maps>
 inline void check_gauss_bonnet(const ConformalMesh& mesh,
                                 const Maps& maps,
@@ -123,6 +133,9 @@ inline void check_gauss_bonnet(const ConformalMesh& mesh,
 // Only modifies free vertices (v_idx[v] >= 0 for EuclideanMaps / SphericalMaps;
 // always all vertices for the raw property-map overload).
 
+/// Distribute the Gauss-Bonnet deficit uniformly across all `Θ_v`:
+/// add `δ = (lhs − rhs) / V` to every entry so that the identity holds
+/// exactly afterwards.  Overload for a raw property map.
 inline void enforce_gauss_bonnet(
     ConformalMesh&                                           mesh,
     ConformalMesh::Property_map<Vertex_index, double>&       theta)
@@ -136,6 +149,7 @@ inline void enforce_gauss_bonnet(
         theta[v] += delta;
 }
 
+/// Distribute the Gauss-Bonnet deficit uniformly across `maps.theta_v`.
 template <typename Maps>
 inline void enforce_gauss_bonnet(ConformalMesh& mesh, Maps& maps)
 {

code/include/hyper_ideal_functional.hpp

@@ -1,4 +1,7 @@
 #pragma once
+// Copyright (c) 2024-2026 Tarik Moussa.
+// SPDX-License-Identifier: MIT
+
 // hyper_ideal_functional.hpp
 //
 // Energy and gradient of the hyper-ideal discrete conformal map functional
@@ -39,22 +42,39 @@ namespace conformallab {
 
 // ── Property-map type aliases ─────────────────────────────────────────────────
 
+/// Property map vertex → `double` (HyperIdeal scalar-per-vertex data).
 using VMapD = ConformalMesh::Property_map<Vertex_index,   double>;
+/// Property map vertex → `int`    (HyperIdeal DOF indices).
 using VMapI = ConformalMesh::Property_map<Vertex_index,   int>;
+/// Property map edge   → `double` (HyperIdeal scalar-per-edge data).
 using EMapD = ConformalMesh::Property_map<Edge_index,     double>;
+/// Property map edge   → `int`    (HyperIdeal DOF indices).
 using EMapI = ConformalMesh::Property_map<Edge_index,     int>;
 
 // ── Persistent map bundle ─────────────────────────────────────────────────────
 
+/// Bundle of the four property maps consumed by the HyperIdeal functional.
 struct HyperIdealMaps {
-    VMapI v_idx;    // DOF index per vertex    (-1 = pinned / ideal point)
+    VMapI v_idx;    ///< DOF index per vertex (−1 = pinned / ideal point).
-    EMapI e_idx;    // DOF index per edge      (-1 = fixed)
+    EMapI e_idx;    ///< DOF index per edge   (−1 = fixed).
-    VMapD theta_v;  // target cone angle Θ_v   (parameter, not variable)
+    VMapD theta_v;  ///< Target cone angle Θᵥ (parameter, not variable).
-    EMapD theta_e;  // target intersection angle θ_e
+    EMapD theta_e;  ///< Target intersection angle θₑ.
 };
 
-// Add all needed persistent property maps and return handles.
+/// Attach the four HyperIdeal property maps to `mesh` and return their
-// Defaults: theta_v = 2π (regular cone), theta_e = π (orthogonal circles).
+/// handles.
+///
+/// Defaults:
+/// * `v_idx[v] = -1`  (ideal vertex — i.e. the corresponding `b_v` is fixed at 0)
+/// * `e_idx[e] = -1`  (edge DOF fixed at 0)
+/// * `theta_v[v] = 2π`  (regular cone target)
+/// * `theta_e[e] = π`   (orthogonal-circle target)
+///
+/// The map prefix `"v:"` / `"e:"` is intentionally generic for the
+/// HyperIdeal functional — it is the canonical / Phase 3b model.
+/// Other functionals use distinct prefixes (`"ev:"` Euclidean, `"sv:"`
+/// Spherical, `"cf:"`/`"ce:"` CP-Euclidean, `"iv:"`/`"ie:"`
+/// Inversive-Distance) so all models can coexist on the same mesh.
 inline HyperIdealMaps setup_hyper_ideal_maps(ConformalMesh& mesh)
 {
     HyperIdealMaps m;
@@ -65,7 +85,7 @@ inline HyperIdealMaps setup_hyper_ideal_maps(ConformalMesh& mesh)
     return m;
 }
 
-// Count variable DOFs: #variable_vertices + #variable_edges.
+/// Count free DOFs: `#variable_vertices + #variable_edges`.
 inline int hyper_ideal_dimension(const ConformalMesh& mesh, const HyperIdealMaps& m)
 {
     int dim = 0;
@@ -74,8 +94,15 @@ inline int hyper_ideal_dimension(const ConformalMesh& mesh, const HyperIdealMaps
     return dim;
 }
 
-// Assign DOF indices 0..n-1: vertices first, then edges.
+/// Make every vertex hyper-ideal and every edge variable, assigning
-// All vertices and edges become variable.  Returns total DOF count.
+/// sequential DOF indices `0..n-1` (vertices first, edges after).
+///
+/// This is the standard initialisation for the Springborn-2020
+/// hyper-ideal functional — gauge fixing is **not** needed because
+/// the energy is strictly convex on the full DOF space (no
+/// rotational mode for an all-hyper-ideal configuration).
+///
+/// \returns total DOF count = `num_vertices(mesh) + num_edges(mesh)`.
 inline int assign_all_dof_indices(ConformalMesh& mesh, HyperIdealMaps& m)
 {
     int idx = 0;
@@ -86,35 +113,132 @@ inline int assign_all_dof_indices(ConformalMesh& mesh, HyperIdealMaps& m)
 
 // ── Evaluation result ─────────────────────────────────────────────────────────
 
+/// Output of `evaluate_hyper_ideal()` — the energy value and (optionally)
+/// its gradient evaluated at the current DOF vector.
 struct HyperIdealResult {
-    double              energy   = 0.0;
+    double              energy   = 0.0; ///< Functional value at the input DOFs.
-    std::vector<double> gradient;     // empty when gradient was not requested
+    std::vector<double> gradient;       ///< Gradient ∇E; empty when not requested.
 };
 
 // ── Internal helpers ──────────────────────────────────────────────────────────
 
-// Get the DOF value from x, or 0.0 if pinned.
+/// Read the DOF value from `x` for index `idx`; return 0 if pinned (idx < 0).
 static inline double dof_val(int idx, const std::vector<double>& x)
 {
     return idx >= 0 ? x[static_cast<std::size_t>(idx)] : 0.0;
 }
 
-// Convert a CGAL halfedge index to a plain std::size_t (for vector indexing).
+/// Convert a CGAL half-edge index to a plain `std::size_t` for vector indexing.
 static inline std::size_t hidx(Halfedge_index h)
 {
     return static_cast<std::size_t>(static_cast<std::uint32_t>(h));
 }
 
-// ── Per-face angle kernel ─────────────────────────────────────────────────────
+// ── Pure-math face-angle kernel ──────────────────────────────────────────────
+//
+// Computes the six per-face angle outputs (β₁, β₂, β₃, α₁₂, α₂₃, α₃₁) from
+// the six local DOF inputs (b₁, b₂, b₃, a₁₂, a₂₃, a₃₁) and the variability
+// flags (vᵢb).  This is the pure functional core of `compute_face_angles`
+// — no mesh, no property maps, no global x vector.
+//
+// Why exposed as a free function (Phase 9b):
+// ─────────────────────────────────────────
+// The block-FD Hessian (`hyper_ideal_hessian_block_fd`) perturbs only the
+// 6 DOFs adjacent to a single face at a time, recomputes the 6 angle
+// outputs of that face, and uses the local 6×6 Jacobian to scatter into
+// the global Hessian.  Working through a pure 6→6 function (instead of
+// perturbing the full x and re-running the gradient over all faces)
+// reduces the cost of the Hessian from O(F·n) to O(F·36).
+//
+// The clamping logic (negative b → 0.01, negative a → 0) mirrors
+// HyperIdealFunctional.java's defensive behaviour (lines 122-127 of the
+// Java original); this keeps the FD perturbation regime well-defined.
 
-struct FaceAngles {
+/// Six per-face angle outputs computed from local DOFs (see
-    double alpha12, alpha23, alpha31;  // dihedral angles at each edge
+/// `face_angles_from_local_dofs`).  Used by the block-FD Hessian.
-    double beta1,   beta2,   beta3;    // interior angles at each vertex
+struct FaceAngleOutputs {
-    double a12, a23, a31;              // edge DOF values (used in energy)
+    double beta1;   ///< Interior angle at v₁.
-    double b1,  b2,  b3;              // vertex DOF values
+    double beta2;   ///< Interior angle at v₂.
-    bool   v1b, v2b, v3b;             // whether each vertex is variable
+    double beta3;   ///< Interior angle at v₃.
+    double alpha12; ///< Dihedral angle at edge e₁₂.
+    double alpha23; ///< Dihedral angle at edge e₂₃.
+    double alpha31; ///< Dihedral angle at edge e₃₁.
 };
 
+/// Pure-math 6→6 kernel: given the six local DOFs (b₁,b₂,b₃,a₁₂,a₂₃,a₃₁)
+/// of one face plus the per-vertex variability flags, return the six
+/// HyperIdeal angle outputs.  No mesh, no property maps — used by the
+/// per-face block-FD Hessian in `hyper_ideal_hessian.hpp`.
+inline FaceAngleOutputs face_angles_from_local_dofs(
+    double b1, double b2, double b3,
+    double a12, double a23, double a31,
+    bool   v1b, bool v2b, bool v3b)
+{
+    // Same defensive clamps as compute_face_angles.
+    if (v1b && v2b && a12 < 0.0) a12 = 0.0;
+    if (v2b && v3b && a23 < 0.0) a23 = 0.0;
+    if (v3b && v1b && a31 < 0.0) a31 = 0.0;
+    if (v1b && b1  < 0.0) b1 = 0.01;
+    if (v2b && b2  < 0.0) b2 = 0.01;
+    if (v3b && b3  < 0.0) b3 = 0.01;
+
+    double l12 = lij(b1, b2, a12, v1b, v2b);
+    double l23 = lij(b2, b3, a23, v2b, v3b);
+    double l31 = lij(b3, b1, a31, v3b, v1b);
+
+    if (l12 < 1E-12 && l23 < 1E-12 && l31 < 1E-12)
+        l12 = l23 = l31 = 1E-12;
+
+    FaceAngleOutputs o;
+
+    if (l12 > l23 + l31) {
+        o.beta1 = 0.0; o.beta2 = 0.0; o.beta3 = PI;
+        o.alpha12 = PI; o.alpha23 = 0.0; o.alpha31 = 0.0;
+    } else if (l23 > l12 + l31) {
+        o.beta1 = PI; o.beta2 = 0.0; o.beta3 = 0.0;
+        o.alpha12 = 0.0; o.alpha23 = PI; o.alpha31 = 0.0;
+    } else if (l31 > l12 + l23) {
+        o.beta1 = 0.0; o.beta2 = PI; o.beta3 = 0.0;
+        o.alpha12 = 0.0; o.alpha23 = 0.0; o.alpha31 = PI;
+    } else {
+        o.beta1 = zeta(l12, l31, l23);
+        o.beta2 = zeta(l23, l12, l31);
+        o.beta3 = zeta(l31, l23, l12);
+        o.alpha12 = alpha_ij(a12, a23, a31, b1, b2, b3,
+                             o.beta1, o.beta2, o.beta3, v1b, v2b, v3b);
+        o.alpha23 = alpha_ij(a23, a31, a12, b2, b3, b1,
+                             o.beta2, o.beta3, o.beta1, v2b, v3b, v1b);
+        o.alpha31 = alpha_ij(a31, a12, a23, b3, b1, b2,
+                             o.beta3, o.beta1, o.beta2, v3b, v1b, v2b);
+    }
+    return o;
+}
+
+// ── Per-face angle kernel ─────────────────────────────────────────────────────
+
+/// Per-face angle bundle returned by `compute_face_angles()`.  Carries
+/// the six output angles plus the six input DOFs (so the energy and
+/// gradient kernels can reuse them without re-reading the mesh).
+struct FaceAngles {
+    double alpha12; ///< Dihedral angle at edge e₁₂.
+    double alpha23; ///< Dihedral angle at edge e₂₃.
+    double alpha31; ///< Dihedral angle at edge e₃₁.
+    double beta1;   ///< Interior angle at vertex v₁.
+    double beta2;   ///< Interior angle at vertex v₂.
+    double beta3;   ///< Interior angle at vertex v₃.
+    double a12;     ///< Edge DOF value at e₁₂.
+    double a23;     ///< Edge DOF value at e₂₃.
+    double a31;     ///< Edge DOF value at e₃₁.
+    double b1;      ///< Vertex DOF value at v₁.
+    double b2;      ///< Vertex DOF value at v₂.
+    double b3;      ///< Vertex DOF value at v₃.
+    bool   v1b;     ///< `true` iff vertex v₁ is variable (not pinned).
+    bool   v2b;     ///< `true` iff vertex v₂ is variable.
+    bool   v3b;     ///< `true` iff vertex v₃ is variable.
+};
+
+/// Compute the six per-face angles (+ remember the input DOFs) for face
+/// `f` of `mesh`, given the current DOF vector `x` and DOF-index maps.
 static FaceAngles compute_face_angles(
     const ConformalMesh&       mesh,
     Face_index                 f,
@@ -192,7 +316,7 @@ static FaceAngles compute_face_angles(
     return fa;
 }
 
-// Per-face energy contribution U(f) (before subtracting θ·a and Θ·b terms).
+/// Per-face energy contribution U(f) before subtracting the θ·a and Θ·b terms.
 static double face_energy(const FaceAngles& fa)
 {
     double aa = fa.a12*fa.alpha12 + fa.a23*fa.alpha23 + fa.a31*fa.alpha31;
@@ -221,6 +345,14 @@ static double face_energy(const FaceAngles& fa)
 
 // ── Full evaluation ───────────────────────────────────────────────────────────
 
+/// Evaluate the HyperIdeal functional at DOF vector `x`.  Returns the
+/// energy value and (optionally) the gradient in a `HyperIdealResult`.
+///
+/// \param mesh           Triangle mesh carrying the DOF-index property maps.
+/// \param x              Current DOF vector (length = `hyper_ideal_dimension(...)`).
+/// \param m              Property-map bundle from `setup_hyper_ideal_maps(...)`.
+/// \param need_energy    If `true`, fill `result.energy` (default: `true`).
+/// \param need_gradient  If `true`, fill `result.gradient` (default: `true`).
 inline HyperIdealResult evaluate_hyper_ideal(
     ConformalMesh&             mesh,
     const std::vector<double>& x,
@@ -304,10 +436,10 @@ inline HyperIdealResult evaluate_hyper_ideal(
     return res;
 }
 
-// ── Finite-difference gradient check ─────────────────────────────────────────
+/// Finite-difference gradient check (central differences).
-//
+///
-// Returns true if  |G[i] − fd[i]| / max(1, |G[i]|)  <  tol  for all DOFs.
+/// Returns `true` iff `|G[i] − fd[i]| / max(1, |G[i]|) < tol` for every
-// eps = step size, tol = tolerance (same defaults as Java FunctionalTest).
+/// DOF.  Defaults `eps = 1e-5`, `tol = 1e-4` match the Java `FunctionalTest`.
 inline bool gradient_check(
     ConformalMesh&             mesh,
     const std::vector<double>& x0,

code/include/hyper_ideal_geometry.hpp

@@ -1,4 +1,7 @@
 #pragma once
+// Copyright (c) 2024-2026 Tarik Moussa.
+// SPDX-License-Identifier: MIT
+
 // hyper_ideal_geometry.hpp
 //
 // Pure-math building blocks for the hyper-ideal discrete conformal map.
@@ -22,9 +25,9 @@ namespace conformallab {
 
 // ── Length functions ─────────────────────────────────────────────────────────
 
-// ζ(x,y,z)  — interior angle in a hyperbolic triangle with edge lengths
+/// `ζ(x,y,z)` — interior angle (in radians) in a hyperbolic triangle
-//             x, y, z, opposite to the side of length z.
+/// with edge lengths `x`, `y`, `z`, opposite to the side of length `z`.
-// Ports HyperIdealUtility.ζ(x, y, z).
+/// Ports `HyperIdealUtility.ζ(x, y, z)`.
 inline double zeta(double x, double y, double z)
 {
     double cx = std::cosh(x), cy = std::cosh(y), cz = std::cosh(z);
@@ -34,8 +37,8 @@ inline double zeta(double x, double y, double z)
     return std::acos(nbd);
 }
 
-// ζ₁₃(x,y,z) — third edge length in a right-angled hyperbolic hexagon.
+/// `ζ₁₃(x,y,z)` — third edge length in a right-angled hyperbolic hexagon.
-// Ports HyperIdealUtility.ζ_13(x, y, z).
+/// Ports `HyperIdealUtility.ζ_13(x, y, z)`.
 inline double zeta13(double x, double y, double z)
 {
     double cx = std::cosh(x), cy = std::cosh(y), cz = std::cosh(z);
@@ -43,16 +46,16 @@ inline double zeta13(double x, double y, double z)
     return std::acosh((cx*cy + cz) / (sx*sy));
 }
 
-// ζ₁₄(x,y) — edge length in a hyperbolic pentagon with one ideal vertex.
+/// `ζ₁₄(x,y)` — edge length in a hyperbolic pentagon with one ideal vertex.
-// Ports HyperIdealUtility.ζ_14(x, y).
+/// Ports `HyperIdealUtility.ζ_14(x, y)`.
 inline double zeta14(double x, double y)
 {
     double cy = std::cosh(y), sy = std::sinh(y);
     return std::acosh((std::exp(x) + cy) / sy);
 }
 
-// ζ₁₅(x) — length in a hyperbolic quadrilateral with two ideal vertices.
+/// `ζ₁₅(x)` — length in a hyperbolic quadrilateral with two ideal vertices.
-// Ports HyperIdealUtility.ζ_15(x).
+/// Ports `HyperIdealUtility.ζ_15(x)`.
 inline double zeta15(double x)
 {
     return 2.0 * std::asinh(std::exp(x / 2.0));
@@ -60,12 +63,11 @@ inline double zeta15(double x)
 
 // ── Effective edge length ─────────────────────────────────────────────────────
 
-// l_ij: effective hyperbolic length of edge ij.
+/// `l_ij`: effective hyperbolic length of edge ij.
-//   b_i, b_j – vertex log scale factors  (used only if vertex is hyper-ideal)
+///   * `bi`, `bj` — vertex log scale factors (used only when vertex is hyper-ideal).
-//   a_ij     – edge intersection-angle variable
+///   * `aij`      — edge intersection-angle variable.
-//   vi_var   – true if vertex i is hyper-ideal (has a DOF b_i)
+///   * `vi_var` / `vj_var` — `true` iff the corresponding vertex is hyper-ideal.
-//   vj_var   – true if vertex j is hyper-ideal
+/// Ports `HyperIdealFunctional.lij()`.
-// Ports HyperIdealFunctional.lij().
 inline double lij(double bi, double bj, double aij, bool vi_var, bool vj_var)
 {
     if (vi_var && vj_var) return zeta13(bi, bj, aij);
@@ -76,8 +78,8 @@ inline double lij(double bi, double bj, double aij, bool vi_var, bool vj_var)
 
 // ── Auxiliary angle functions ─────────────────────────────────────────────────
 
-// σᵢ(aᵢⱼ, aₖᵢ, aⱼₖ, vj_var, vk_var) — intermediate half-length at vertex i.
+/// `σᵢ(aᵢⱼ, aₖᵢ, aⱼₖ, vj_var, vk_var)` — intermediate half-length at vertex i.
-// Ports HyperIdealFunctional.σi().
+/// Ports `HyperIdealFunctional.σi()`.
 inline double sigma_i(double aij, double aki, double ajk, bool vj_var, bool vk_var)
 {
     if (vj_var && vk_var) return zeta13(aij, aki, ajk);
@@ -86,24 +88,24 @@ inline double sigma_i(double aij, double aki, double ajk, bool vj_var, bool vk_v
     return zeta15(ajk - aij - aki);
 }
 
-// σᵢⱼ(aᵢⱼ, bᵢ, bⱼ, vj_var) — intermediate half-length for edge ij from vertex i.
+/// `σᵢⱼ(aᵢⱼ, bᵢ, bⱼ, vj_var)` — intermediate half-length for edge ij from vertex i.
-// Ports HyperIdealFunctional.σij().
+/// Ports `HyperIdealFunctional.σij()`.
 inline double sigma_ij(double aij, double bi, double bj, bool vj_var)
 {
     if (vj_var) return zeta13(aij, bi, bj);
     return zeta14(-aij, bi);
 }
 
-// α_ij: computed dihedral angle at edge ij in the face with vertices i, j, k.
+/// `α_ij`: computed dihedral angle at edge ij in the face with vertices i, j, k.
-//
+///
-// Arguments (cyclic role assignment):
+/// Arguments (cyclic role assignment):
-//   aij, ajk, aki  – edge variables
+///   * `aij, ajk, aki` — edge variables.
-//   bi, bj, bk     – vertex variables
+///   * `bi, bj, bk`    — vertex variables.
-//   βi, βj, βk     – interior angles of the auxiliary hyperbolic triangle
+///   * `beta_i, beta_j, beta_k` — interior angles of the auxiliary hyperbolic triangle.
-//   vi_var, vj_var, vk_var – which vertices are hyper-ideal
+///   * `vi_var, vj_var, vk_var` — which vertices are hyper-ideal.
-//
+///
-// Ports HyperIdealFunctional.αij() (the private helper).
+/// Ports `HyperIdealFunctional.αij()` (the private helper).
-// Note: the vk_var case recurses once (never more than one level deep).
+/// Note: the `vk_var` case recurses once (never more than one level deep).
 inline double alpha_ij(
     double aij, double ajk, double aki,
     double bi,  double bj,  double bk,

code/include/hyper_ideal_hessian.hpp

@@ -1,39 +1,65 @@
 #pragma once
+// Copyright (c) 2024-2026 Tarik Moussa.
+// SPDX-License-Identifier: MIT
+
 // hyper_ideal_hessian.hpp
 //
 // Phase 4a — Hessian of the hyper-ideal discrete conformal functional.
+// Phase 9b — Block-finite-difference Hessian (intermediate optimisation).
 //
 // ┌──────────────────────────────────────────────────────────────────────────┐
-// │  Implementation strategy                                                 │
+// │  Implementation strategy                                                  │
-// │                                                                          │
+// │                                                                           │
-// │  The hyper-ideal functional involves angle functions (ζ, σ, α, β)       │
+// │  The hyper-ideal functional involves angle functions (ζ, σ, α, β)        │
-// │  composed through several nested layers (lij → ζ13/14/15 → β/α).       │
+// │  composed through several nested layers (lij → ζ13/14/15 → β/α).        │
-// │  Deriving closed-form Hessian entries analytically through all these     │
+// │  Deriving closed-form Hessian entries analytically through all these      │
-// │  layers is feasible but lengthy; an analytical Hessian is left for a    │
+// │  layers is feasible but lengthy and is deferred to a future PR.           │
-// │  future phase.                                                           │
+// │                                                                           │
-// │                                                                          │
+// │  TWO Hessian implementations are provided here:                           │
-// │  Here we compute the Hessian by symmetric finite differences of the     │
+// │                                                                           │
-// │  gradient, which is exact to O(ε²) and sufficient for Newton's method   │
+// │    1.  `hyper_ideal_hessian` — full finite-difference baseline.           │
-// │  at the meshes typical in Phase 4 (< 500 DOFs):                         │
+// │        Cost  ≈  n × (cost of full gradient evaluation)                    │
-// │                                                                          │
+// │             =  O(n · F)         where n = #DOFs and F = #faces.           │
-// │    H[i,j] = (G(x + ε·eⱼ)[i] − G(x − ε·eⱼ)[i]) / (2ε)                │
+// │        Used for correctness reference and small meshes.                   │
-// │                                                                          │
+// │                                                                           │
-// │  The hyper-ideal energy is strictly convex (Springborn 2020), so H is   │
+// │    2.  `hyper_ideal_hessian_block_fd` — block-local finite-difference,    │
-// │  positive semi-definite everywhere and Eigen::SimplicialLDLT applies     │
+// │        Phase 9b.  Exploits the fact that each face contributes to the     │
-// │  directly.                                                               │
+// │        gradient through exactly 6 DOFs (3 vertex b_i + 3 edge a_e).       │
+// │        Cost  ≈  F × 6 × (cost of a single face-angle evaluation)          │
+// │             =  O(36 · F).                                                 │
+// │        Speed-up factor ≈ n / 36, i.e. typically 10–50× on V > 200.        │
+// │                                                                           │
+// │  Both produce the same Hessian to O(ε²) and pass identical PSD checks.    │
+// │  The block-FD variant is the production default; the full-FD variant is   │
+// │  kept for cross-validation tests.                                         │
+// │                                                                           │
+// │  An analytic Hessian via Schläfli-type differentiation through the chain  │
+// │     (bᵢ, aₑ) → lᵢⱼ → ζ₁₃/ζ₁₄/ζ₁₅ → αᵢⱼ / βᵢ                            │
+// │  is deferred to a future PR (Phase 9b-analytic).  Speed-up would be       │
+// │  another ~6×, taking the cost to O(F).                                    │
+// │                                                                           │
+// │  The hyper-ideal energy is strictly convex (Springborn 2020), so H is    │
+// │  positive semi-definite everywhere and Eigen::SimplicialLDLT applies      │
+// │  directly to either Hessian variant.                                      │
 // └──────────────────────────────────────────────────────────────────────────┘
+//
+// Note on the Java reference: HyperIdealFunctional.java line 295-298 declares
+//   public boolean hasHessian() { return false; }
+// — i.e. the upstream Java implementation supplies NO Hessian, analytic or
+// numerical.  Both `hyper_ideal_hessian` and `hyper_ideal_hessian_block_fd`
+// are conformallab++ additions beyond Java parity.
 
 #include "hyper_ideal_functional.hpp"
 #include <Eigen/Sparse>
 #include <vector>
 #include <cmath>
+#include <cstdint>
 
 namespace conformallab {
 
-// ── Numerical Hessian via symmetric finite differences ────────────────────────
+/// Full finite-difference HyperIdeal Hessian (baseline, Phase 4a).
-//
+/// Cost: `n` full-gradient evaluations ≈ `O(n·F)`.  Use for small
-// Returns the n×n sparse Hessian, where n = hyper_ideal_dimension(mesh, m).
+/// meshes or as a correctness reference for the block-FD variant.
-// eps: finite-difference step size (default 1e-5 gives ~1e-10 relative error).
 inline Eigen::SparseMatrix<double> hyper_ideal_hessian(
     ConformalMesh&             mesh,
     const std::vector<double>& x,
@@ -42,7 +68,7 @@ inline Eigen::SparseMatrix<double> hyper_ideal_hessian(
 {
     const int n = hyper_ideal_dimension(mesh, m);
     std::vector<Eigen::Triplet<double>> trips;
-    trips.reserve(static_cast<std::size_t>(n * n));   // dense upper bound
+    trips.reserve(static_cast<std::size_t>(n * n));
 
     std::vector<double> xp = x, xm = x;
 
@@ -69,10 +95,8 @@ inline Eigen::SparseMatrix<double> hyper_ideal_hessian(
     return H;
 }
 
-// ── Symmetrised Hessian ───────────────────────────────────────────────────────
+/// Symmetrised full-FD HyperIdeal Hessian: returns `(H + Hᵀ) / 2` to
-//
+/// scrub the tiny asymmetries introduced by floating-point rounding.
-// The FD Hessian is symmetric in exact arithmetic; floating-point rounding
-// can introduce tiny asymmetries.  This helper returns (H + Hᵀ)/2.
 inline Eigen::SparseMatrix<double> hyper_ideal_hessian_sym(
     ConformalMesh&             mesh,
     const std::vector<double>& x,
@@ -84,4 +108,124 @@ inline Eigen::SparseMatrix<double> hyper_ideal_hessian_sym(
     return (H + Ht) * 0.5;
 }
 
+// ── Block-FD Hessian (Phase 9b) ──────────────────────────────────────────────
+//
+// Computes the Hessian by FD on each face's 6×6 local block.  The 6 local
+// DOFs of a face f are:
+//      (b_{v1}, b_{v2}, b_{v3}, a_{e12}, a_{e23}, a_{e31}).
+// For each face we recompute the 6 output angles (β₁,β₂,β₃,α₁₂,α₂₃,α₃₁)
+// at x ± ε along each local axis and read off the 6×6 Jacobian.  The result
+// scatters into the global Hessian via the DOF-index lookup.
+//
+// Why this is correct:
+// ─────────────────────
+// The global gradient decomposes by face:
+//     G_b_v = Σ_{f ∋ v} β_v(f)  −  Θ_v
+//     G_a_e = Σ_{f ∋ e} α_e(f)  −  θ_e
+// Since β and α at face f depend ONLY on the 6 local DOFs of f, the
+// Hessian also decomposes:
+//     ∂G_x/∂y = Σ_{f: x,y ∈ local(f)}  ∂(β or α)/∂y  at f.
+// So accumulating per-face 6×6 blocks reproduces the full Hessian.
+//
+// Cost: F × 12 face-angle evaluations  (6 DOFs × 2 directions).
+// On a tetrahedron (F=4, n≈10):       48 face evaluations
+//                                     vs full-FD ≈ 80         → ~1.7× speed-up.
+// On cathead.obj (F=248, n≈400):     2976 face evaluations
+//                                     vs full-FD ≈ 99,200    → ~33× speed-up.
+// On brezel.obj (F=13824, n≈14000): 165 888 face evaluations
+//                                     vs full-FD ≈ 193 M     → ~1166× speed-up.
+/// Per-face block-FD HyperIdeal Hessian (Phase 9b).  Uses the locality
+/// lemma `∂G_x/∂y = Σ_{f: x,y ∈ local(f)} ∂(β or α)/∂y` to perturb only
+/// the 6 face-local DOFs at a time, giving an `F·12` face-evaluation
+/// budget vs `n·F` for full-FD (~96× speed-up on brezel.obj).
+inline Eigen::SparseMatrix<double> hyper_ideal_hessian_block_fd(
+    ConformalMesh&             mesh,
+    const std::vector<double>& x,
+    const HyperIdealMaps&      m,
+    double                     eps = 1e-5)
+{
+    const int n = hyper_ideal_dimension(mesh, m);
+    std::vector<Eigen::Triplet<double>> trips;
+    trips.reserve(36 * mesh.number_of_faces());
+
+    for (auto f : mesh.faces()) {
+        Halfedge_index h0 = mesh.halfedge(f);
+        Halfedge_index h1 = mesh.next(h0);
+        Halfedge_index h2 = mesh.next(h1);
+
+        Vertex_index v1 = mesh.source(h0);
+        Vertex_index v2 = mesh.source(h1);
+        Vertex_index v3 = mesh.source(h2);
+        Edge_index   e12 = mesh.edge(h0);
+        Edge_index   e23 = mesh.edge(h1);
+        Edge_index   e31 = mesh.edge(h2);
+
+        // Local DOF indices: (b1, b2, b3, a12, a23, a31).  Pinned slots = -1.
+        const int idx[6] = {
+            m.v_idx[v1], m.v_idx[v2], m.v_idx[v3],
+            m.e_idx[e12], m.e_idx[e23], m.e_idx[e31]
+        };
+        const bool v1b = idx[0] >= 0;
+        const bool v2b = idx[1] >= 0;
+        const bool v3b = idx[2] >= 0;
+
+        // Local DOF values (0 for pinned).
+        const double vals[6] = {
+            dof_val(idx[0], x), dof_val(idx[1], x), dof_val(idx[2], x),
+            dof_val(idx[3], x), dof_val(idx[4], x), dof_val(idx[5], x)
+        };
+
+        // For each free local DOF, evaluate the 6 outputs at ±ε.
+        // We never perturb a pinned DOF (its column would be physically zero
+        // because it is not part of the DOF vector at all).
+        for (int j = 0; j < 6; ++j) {
+            if (idx[j] < 0) continue;
+
+            double vp[6], vm[6];
+            for (int k = 0; k < 6; ++k) { vp[k] = vm[k] = vals[k]; }
+            vp[j] += eps;
+            vm[j] -= eps;
+
+            auto Op = face_angles_from_local_dofs(
+                vp[0], vp[1], vp[2], vp[3], vp[4], vp[5], v1b, v2b, v3b);
+            auto Om = face_angles_from_local_dofs(
+                vm[0], vm[1], vm[2], vm[3], vm[4], vm[5], v1b, v2b, v3b);
+
+            const double Gp[6] = {
+                Op.beta1, Op.beta2, Op.beta3,
+                Op.alpha12, Op.alpha23, Op.alpha31
+            };
+            const double Gm[6] = {
+                Om.beta1, Om.beta2, Om.beta3,
+                Om.alpha12, Om.alpha23, Om.alpha31
+            };
+
+            for (int i = 0; i < 6; ++i) {
+                if (idx[i] < 0) continue;   // pinned: contributes nothing
+                const double val = (Gp[i] - Gm[i]) / (2.0 * eps);
+                if (std::abs(val) > 1e-15)
+                    trips.emplace_back(idx[i], idx[j], val);
+            }
+        }
+    }
+
+    Eigen::SparseMatrix<double> H(n, n);
+    H.setFromTriplets(trips.begin(), trips.end());
+    return H;
+}
+
+/// Symmetrised block-FD HyperIdeal Hessian: returns `(H + Hᵀ) / 2` of
+/// `hyper_ideal_hessian_block_fd(...)` for downstream solvers that
+/// require strict symmetry.
+inline Eigen::SparseMatrix<double> hyper_ideal_hessian_block_fd_sym(
+    ConformalMesh&             mesh,
+    const std::vector<double>& x,
+    const HyperIdealMaps&      m,
+    double                     eps = 1e-5)
+{
+    auto H = hyper_ideal_hessian_block_fd(mesh, x, m, eps);
+    Eigen::SparseMatrix<double> Ht = H.transpose();
+    return (H + Ht) * 0.5;
+}
+
 } // namespace conformallab

code/include/hyper_ideal_utility.hpp

@@ -1,4 +1,7 @@
 #pragma once
+// Copyright (c) 2024-2026 Tarik Moussa.
+// SPDX-License-Identifier: MIT
+
 
 // Hyperbolic tetrahedron volume formulas.
 // Ported from de.varylab.discreteconformal.functional.HyperIdealUtility (Java).
@@ -12,9 +15,9 @@
 
 namespace conformallab {
 
-// Volume of a generalized hyperbolic tetrahedron with dihedral angles A..F.
+/// Volume of a generalized hyperbolic tetrahedron with dihedral
-// Formula: Meyerhoff / Ushijima (Springer 2006).
+/// angles `A,…,F` via the Meyerhoff / Ushijima 2006 formula.
-// Corresponds to Java HyperIdealUtility.calculateTetrahedronVolume().
+/// Same as Java `HyperIdealUtility.calculateTetrahedronVolume()`.
 inline double calculateTetrahedronVolume(double A, double B, double C,
                                          double D, double E, double F) {
     // PI from constants.hpp (conformallab::PI)
@@ -73,11 +76,9 @@ inline double calculateTetrahedronVolume(double A, double B, double C,
     return (U(z1) - U(z2)) / 2.0;
 }
 
-// Volume of a hyperideal tetrahedron with one ideal vertex (at gamma).
+/// Volume of a hyperideal tetrahedron with one ideal vertex at γ via
-// Dihedral angles at the ideal vertex: gamma1, gamma2, gamma3.
+/// the Kolpakov-Mednykh formula (arxiv math/0603097).  Same as Java
-// Dihedral angles at opposite edges: alpha23, alpha31, alpha12.
+/// `HyperIdealUtility.calculateTetrahedronVolumeWithIdealVertexAtGamma()`.
-// Formula: Kolpakov–Mednykh (arxiv math/0603097).
-// Corresponds to Java HyperIdealUtility.calculateTetrahedronVolumeWithIdealVertexAtGamma().
 inline double calculateTetrahedronVolumeWithIdealVertexAtGamma(
     double gamma1, double gamma2, double gamma3,
     double alpha23, double alpha31, double alpha12)

code/include/hyper_ideal_visualization_utility.hpp

@@ -1,4 +1,7 @@
 #pragma once
+// Copyright (c) 2024-2026 Tarik Moussa.
+// SPDX-License-Identifier: MIT
+
 // Port of the static helper
 //   HyperIdealVisualizationPlugin.getEuclideanCircleFromHyperbolic()
 // from de.varylab.discreteconformal.plugin.
@@ -26,15 +29,14 @@
 // After translation and projection to the Poincaré disk their circumcircle
 // equals the image of the original hyperbolic circle.
 
-#include <Eigen/Dense>
+#include <Eigen/Core>  // downgraded from <Eigen/Dense>: this header only
+                      // uses Matrix/Vector primitives, no decompositions.
 #include <array>
 #include <cmath>
 
 namespace conformallab {
 
-// ---------------------------------------------------------------------------
+/// Circumcenter of three 2-D points (`a`, `b`, `c`) in the Euclidean plane.
-// Circumcenter of three 2-D points
-// ---------------------------------------------------------------------------
 inline Eigen::Vector2d circumcenter2d(
     const Eigen::Vector2d& a,
     const Eigen::Vector2d& b,
@@ -54,10 +56,8 @@ inline Eigen::Vector2d circumcenter2d(
     return {ux, uy};
 }
 
-// ---------------------------------------------------------------------------
+/// 4×4 Lorentz boost: maps the hyperboloid origin `e₄ = (0,0,0,1)` to
-// 4×4 Lorentz boost: maps the hyperboloid origin e₄=(0,0,0,1) to `center`.
+/// `center`.  Precondition: `center` lies on the hyperboloid.
-// `center` must lie on the hyperboloid: center[3]² - ‖center.head<3>()‖² = 1.
-// ---------------------------------------------------------------------------
 inline Eigen::Matrix4d hyperboloidTranslation(const Eigen::Vector4d& center)
 {
     Eigen::Vector3d p = center.head<3>();
@@ -73,10 +73,8 @@ inline Eigen::Matrix4d hyperboloidTranslation(const Eigen::Vector4d& center)
     return T;
 }
 
-// ---------------------------------------------------------------------------
+/// Project a hyperboloid point `x` onto the Poincaré disk (jReality
-// Project a hyperboloid point to the Poincaré disk (jReality convention:
+/// convention: add 1 to the w-coordinate, then dehomogenise spatial part).
-// add 1 to the w-coordinate, then dehomogenize the spatial part).
-// ---------------------------------------------------------------------------
 inline Eigen::Vector2d toPoincareDisk(const Eigen::Vector4d& x)
 {
     double w = x(3) + 1.0;
@@ -97,6 +95,10 @@ inline Eigen::Vector2d toPoincareDisk(const Eigen::Vector4d& x)
 //
 // Port of HyperIdealVisualizationPlugin.getEuclideanCircleFromHyperbolic()
 // ---------------------------------------------------------------------------
+/// Convert a hyperbolic circle (`center` on the hyperboloid, hyperbolic
+/// `radius`) to the corresponding Euclidean circle in the Poincaré disk;
+/// returns `{cx, cy, r}`.  Port of `HyperIdealVisualizationPlugin
+/// .getEuclideanCircleFromHyperbolic()`.
 inline std::array<double,3> getEuclideanCircleFromHyperbolic(
     const Eigen::Vector4d& center, double radius)
 {

code/include/inversive_distance_functional.hpp

@@ -0,0 +1,378 @@
+#pragma once
+// Copyright (c) 2024-2026 Tarik Moussa.
+// SPDX-License-Identifier: MIT
+
+// inversive_distance_functional.hpp
+//
+// Phase 9a.2 — Inversive-distance circle-packing functional (Luo 2004).
+//
+// VERTEX-based circle packing.  Each vertex carries a circle of radius
+// r_i = exp(u_i).  The inversive distance I_ij between two adjacent
+// circles is a constant of the edge, derived once from the initial
+// geometry via Bowers-Stephenson 2004.
+//
+// This is the FACE-DUAL of CPEuclideanFunctional (Phase 9a.1).  The
+// correspondence is I_ij = cos θ_e (Glickenstein 2011 §5).
+//
+// ┌──────────────────────────────────────────────────────────────────────────┐
+// │  Mathematical model                                                       │
+// │  ──────────────────                                                       │
+// │                                                                           │
+// │  Variables:    u_i = log r_i           (per vertex; r_i is the radius)   │
+// │  Constants:    I_ij                    (per edge; inversive distance)    │
+// │                Θ_v                     (per vertex; target cone angle)   │
+// │                                                                           │
+// │  Bowers-Stephenson (init from initial geometry):                          │
+// │    I_ij = ( ℓ_ij² − r_i² − r_j² ) / ( 2 r_i r_j )                        │
+// │                                                                           │
+// │  Edge length (Luo 2004 §3, Glickenstein 2011 eq. 2.1):                   │
+// │    ℓ_ij(u)²  =  exp(2 u_i) + exp(2 u_j) + 2 I_ij exp(u_i + u_j)         │
+// │             =  r_i² + r_j² + 2 I_ij r_i r_j                              │
+// │                                                                           │
+// │  Triangle angles:    same half-tangent law of cosines as the              │
+// │                      Euclidean functional (numerically stable).           │
+// │                                                                           │
+// │  Gradient  (Luo 2004 Lemma 3.1):                                          │
+// │    ∂E/∂u_v  =  Θ_v  −  Σ_{T ∋ v}  α_v(T)                                 │
+// │                                                                           │
+// │  Energy:     path integral E(u) = ∫₀¹ ⟨G(tu), u⟩ dt                      │
+// │              (Luo's 1-form is closed; we use 10-point Gauss-Legendre      │
+// │               quadrature, identical to euclidean_functional.hpp)          │
+// │                                                                           │
+// │  Hessian:    finite-difference for the MVP port; an analytic form is      │
+// │              given in Glickenstein 2011 eq. (4.6) and may be added        │
+// │              later for performance.                                       │
+// └──────────────────────────────────────────────────────────────────────────┘
+//
+// Relation to euclidean_functional.hpp
+// ────────────────────────────────────
+// The two are structurally identical in:
+//   • DOF layout (per vertex), DOF index sentinel (−1 = pinned)
+//   • Gradient pattern (Θ − Σ α)
+//   • Energy via path integral (same Gauss-Legendre constants)
+//   • Halfedge convention (h0/h1/h2, source pattern, α opposite-edge)
+//
+// They differ ONLY in:
+//   • Per-edge constant: λ°_ij (log²-length) vs I_ij (inversive distance)
+//   • Edge-length formula:
+//       Euclidean:           ℓ_ij  = exp((λ°_ij + u_i + u_j) / 2)
+//       Inversive distance:  ℓ_ij² = exp(2u_i) + exp(2u_j)
+//                                  + 2 I_ij exp(u_i + u_j)
+//
+// In particular at the tangential limit I_ij = 1 the inversive-distance length
+// reduces to (exp(u_i) + exp(u_j))² ⇒ ℓ_ij = r_i + r_j (tangential circles),
+// which is *different* from the Euclidean-conformal length even at the same
+// initial geometry.  The two functionals describe distinct geometric objects.
+//
+// Property-map name prefix: "iv:" (vertex) and "ie:" (edge).
+
+#include "conformal_mesh.hpp"
+#include "constants.hpp"
+#include "euclidean_geometry.hpp"   // euclidean_angles(λ12, λ23, λ31)
+#include <CGAL/boost/graph/iterator.h>
+#include <vector>
+#include <cmath>
+#include <cstdint>
+#include <iostream>
+
+namespace conformallab {
+
+// ── Property-map type aliases ────────────────────────────────────────────────
+
+/// Property map vertex → `int`    for the Inversive-Distance functional.
+using IDVMapI = ConformalMesh::Property_map<Vertex_index, int>;
+/// Property map vertex → `double` for the Inversive-Distance functional.
+using IDVMapD = ConformalMesh::Property_map<Vertex_index, double>;
+/// Property map edge   → `double` for the Inversive-Distance functional.
+using IDEMapD = ConformalMesh::Property_map<Edge_index, double>;
+
+// ── Persistent map bundle ─────────────────────────────────────────────────────
+
+/// Bundle of the four property maps consumed by the Inversive-Distance
+/// circle-packing functional (Luo 2004 / Bowers-Stephenson 2004).
+struct InversiveDistanceMaps {
+    IDVMapI v_idx;       ///< DOF index per vertex (−1 = pinned / u_v = 0)
+    IDVMapD theta_v;     ///< target cone angle Θ_v   (default 2π)
+    IDVMapD r0;          ///< initial radius r_i^(0)  (default 1)
+    IDEMapD I_e;         ///< inversive distance I_ij (per edge, constant)
+};
+
+/// Attach the four inversive-distance property maps to `mesh` and
+/// return their handles.
+///
+/// Defaults are intentionally trivial — every real use of this
+/// functional must call `compute_inversive_distance_init_from_mesh()`
+/// next to populate `r0` and `I_e` from the input geometry.
+/// * `v_idx[v] = -1` (all vertices pinned initially)
+/// * `theta_v[v] = 2π` (regular interior vertex)
+/// * `r0[v] = 1.0` (placeholder)
+/// * `I_e[e] = 1.0` (tangential default — overwritten by init step)
+///
+/// The maps use the `"iv:"` / `"ie:"` prefix so they do not collide
+/// with the Euclidean / Spherical / HyperIdeal / CP-Euclidean maps.
+inline InversiveDistanceMaps setup_inversive_distance_maps(ConformalMesh& mesh)
+{
+    InversiveDistanceMaps m;
+    m.v_idx   = mesh.add_property_map<Vertex_index, int>   ("iv:idx",   -1     ).first;
+    m.theta_v = mesh.add_property_map<Vertex_index, double>("iv:theta", TWO_PI ).first;
+    m.r0      = mesh.add_property_map<Vertex_index, double>("iv:r0",    1.0    ).first;
+    m.I_e     = mesh.add_property_map<Edge_index,   double>("ie:I",     1.0    ).first;
+    return m;
+}
+
+/// Assign sequential DOF indices `0..n-1` to every vertex.
+///
+/// **Note:** this overload does NOT pin a gauge vertex.  The caller
+/// is expected to either:
+/// 1. set one `m.v_idx[v] = -1` *before* calling this function (then
+///    the call is a no-op for that vertex) — OR —
+/// 2. flip one assigned index back to `-1` *after* this function.
+///
+/// For a closed mesh, exactly one pin is required to remove the
+/// global rotational mode.
+inline int assign_inversive_distance_vertex_dof_indices(ConformalMesh&         mesh,
+                                                          InversiveDistanceMaps& m)
+{
+    int idx = 0;
+    for (auto v : mesh.vertices()) m.v_idx[v] = idx++;
+    return idx;
+}
+
+/// Count the free DOFs (vertices with `v_idx >= 0`).
+inline int inversive_distance_dimension(const ConformalMesh&         mesh,
+                                          const InversiveDistanceMaps& m)
+{
+    int dim = 0;
+    for (auto v : mesh.vertices()) if (m.v_idx[v] >= 0) ++dim;
+    return dim;
+}
+
+/// Two-phase initialisation from initial mesh geometry.  Mirrors the
+/// role of `compute_lambda0_from_mesh` in the Euclidean functional, but
+/// adapted to Luo's vertex-based radius parametrisation.
+///
+/// **Phase 1.** Pick a positive radius per vertex:
+/// \code
+///   r_i^(0) = (1/3) · min{ℓ_e : e adjacent to v_i}
+/// \endcode
+/// This is a heuristic — the user may override `m.r0[v]` for any
+/// vertex between `setup_inversive_distance_maps()` and this call.
+///
+/// **Phase 2.** Compute the per-edge inversive distance via the
+/// Bowers-Stephenson 2004 identity:
+/// \code
+///   I_ij = ( ℓ_ij² − r_i² − r_j² ) / ( 2 r_i r_j )
+/// \endcode
+///
+/// \pre  Every edge has positive 3-D length.
+/// \pre  Radii produced in Phase 1 are positive (degenerate isolated
+///       vertices fall back to `r_i = 1`).
+/// \post Every `I_e[e] > -1` for a valid packing.  The chosen
+///       Phase-1 heuristic keeps `I_e > 0` for most real meshes.
+inline void compute_inversive_distance_init_from_mesh(ConformalMesh&         mesh,
+                                                        InversiveDistanceMaps& m)
+{
+    // Phase 1: r_i = (1/3) · min adjacent edge length.
+    for (auto v : mesh.vertices()) {
+        double min_len = std::numeric_limits<double>::infinity();
+        for (auto h : CGAL::halfedges_around_target(v, mesh)) {
+            auto p1 = mesh.point(mesh.source(h));
+            auto p2 = mesh.point(mesh.target(h));
+            double dx = p1.x() - p2.x();
+            double dy = p1.y() - p2.y();
+            double dz = p1.z() - p2.z();
+            double len = std::sqrt(dx*dx + dy*dy + dz*dz);
+            if (len < min_len) min_len = len;
+        }
+        m.r0[v] = (std::isfinite(min_len) && min_len > 1e-15)
+                ? min_len / 3.0
+                : 1.0;
+    }
+
+    // Phase 2: I_ij from initial geometry.
+    for (auto e : mesh.edges()) {
+        auto h  = mesh.halfedge(e);
+        auto vi = mesh.source(h);
+        auto vj = mesh.target(h);
+        auto p1 = mesh.point(vi);
+        auto p2 = mesh.point(vj);
+        double dx = p1.x() - p2.x();
+        double dy = p1.y() - p2.y();
+        double dz = p1.z() - p2.z();
+        double l2 = dx*dx + dy*dy + dz*dz;
+        double ri = m.r0[vi];
+        double rj = m.r0[vj];
+        m.I_e[e] = (l2 - ri*ri - rj*rj) / (2.0 * ri * rj);
+    }
+}
+
+// ── Internal helpers ──────────────────────────────────────────────────────────
+
+namespace id_detail {
+
+inline double dof_val(int idx, const std::vector<double>& x) noexcept
+{
+    return idx >= 0 ? x[static_cast<std::size_t>(idx)] : 0.0;
+}
+
+inline std::size_t hidx(Halfedge_index h) noexcept
+{
+    return static_cast<std::size_t>(static_cast<std::uint32_t>(h));
+}
+
+// Inversive-distance edge length squared: ℓ² = exp(2u_i) + exp(2u_j) + 2 I r_i r_j
+// where r_i = exp(u_i), so:  ℓ² = r_i² + r_j² + 2 I r_i r_j.
+// Returns -1 if the result is non-positive (degenerate; the caller skips the face).
+inline double edge_length_squared(double u_i, double u_j, double I_ij) noexcept
+{
+    double ri = std::exp(u_i);
+    double rj = std::exp(u_j);
+    double l2 = ri*ri + rj*rj + 2.0 * I_ij * ri * rj;
+    return l2 > 0.0 ? l2 : -1.0;
+}
+
+} // namespace id_detail
+
+/// Inversive-Distance gradient `G_v = Θ_v − Σ_faces α_v(face)`.  Same
+/// half-edge corner-angle storage convention as `euclidean_gradient`.
+inline std::vector<double> inversive_distance_gradient(
+    const ConformalMesh&             mesh,
+    const std::vector<double>&       x,
+    const InversiveDistanceMaps&     m)
+{
+    const int n = inversive_distance_dimension(mesh, m);
+    std::vector<double> G(static_cast<std::size_t>(n), 0.0);
+
+    const std::size_t nh = mesh.number_of_halfedges();
+    std::vector<double> h_alpha(nh, 0.0);
+
+    // Pass 1 — per face, compute corner angles via the law of cosines.
+    // We reuse euclidean_angles(λ12, λ23, λ31) which takes 2·log(ℓ) per edge.
+    for (auto f : mesh.faces()) {
+        Halfedge_index h0 = mesh.halfedge(f);
+        Halfedge_index h1 = mesh.next(h0);
+        Halfedge_index h2 = mesh.next(h1);
+
+        Vertex_index v1 = mesh.source(h0);
+        Vertex_index v2 = mesh.source(h1);
+        Vertex_index v3 = mesh.source(h2);
+
+        Edge_index e12 = mesh.edge(h0);
+        Edge_index e23 = mesh.edge(h1);
+        Edge_index e31 = mesh.edge(h2);
+
+        double u1 = id_detail::dof_val(m.v_idx[v1], x);
+        double u2 = id_detail::dof_val(m.v_idx[v2], x);
+        double u3 = id_detail::dof_val(m.v_idx[v3], x);
+
+        double l12sq = id_detail::edge_length_squared(u1, u2, m.I_e[e12]);
+        double l23sq = id_detail::edge_length_squared(u2, u3, m.I_e[e23]);
+        double l31sq = id_detail::edge_length_squared(u3, u1, m.I_e[e31]);
+
+        if (l12sq <= 0 || l23sq <= 0 || l31sq <= 0) continue;
+
+        // euclidean_angles expects 2·log(ℓ) per edge — feed log(ℓ²).
+        auto fa = euclidean_angles(std::log(l12sq), std::log(l23sq), std::log(l31sq));
+        if (!fa.valid) continue;
+
+        h_alpha[id_detail::hidx(h0)] = fa.alpha3;
+        h_alpha[id_detail::hidx(h1)] = fa.alpha1;
+        h_alpha[id_detail::hidx(h2)] = fa.alpha2;
+    }
+
+    // Pass 2 — accumulate vertex gradient.
+    for (auto v : mesh.vertices()) {
+        int iv = m.v_idx[v];
+        if (iv < 0) continue;
+        double sum_alpha = 0.0;
+        for (auto h : CGAL::halfedges_around_target(v, mesh)) {
+            if (mesh.is_border(h)) continue;
+            sum_alpha += h_alpha[id_detail::hidx(mesh.prev(h))];
+        }
+        G[static_cast<std::size_t>(iv)] = m.theta_v[v] - sum_alpha;
+    }
+
+    return G;
+}
+
+/// Inversive-Distance energy `E(u) = ∫₀¹ ⟨G(t·u), u⟩ dt`, evaluated
+/// with 10-point Gauss-Legendre (constants shared with `euclidean_energy`).
+inline double inversive_distance_energy(
+    const ConformalMesh&             mesh,
+    const std::vector<double>&       x,
+    const InversiveDistanceMaps&     m)
+{
+    static const double gl_s[10] = {
+        -0.9739065285171717,  -0.8650633666889845,
+        -0.6794095682990244,  -0.4333953941292472,
+        -0.1488743389816312,   0.1488743389816312,
+         0.4333953941292472,   0.6794095682990244,
+         0.8650633666889845,   0.9739065285171717
+    };
+    static const double gl_w[10] = {
+        0.0666713443086881,  0.1494513491505806,
+        0.2190863625159820,  0.2692667193099963,
+        0.2955242247147529,  0.2955242247147529,
+        0.2692667193099963,  0.2190863625159820,
+        0.1494513491505806,  0.0666713443086881
+    };
+
+    const std::size_t n = x.size();
+    double E = 0.0;
+    std::vector<double> tx(n);
+    for (int k = 0; k < 10; ++k) {
+        double t  = (1.0 + gl_s[k]) * 0.5;
+        double wt = gl_w[k] * 0.5;
+        for (std::size_t i = 0; i < n; ++i) tx[i] = t * x[i];
+        auto G = inversive_distance_gradient(mesh, tx, m);
+        double dot = 0.0;
+        for (std::size_t i = 0; i < n; ++i) dot += G[i] * x[i];
+        E += wt * dot;
+    }
+    return E;
+}
+
+/// FD gradient check for the Inversive-Distance functional (central diff).
+inline bool gradient_check_inversive_distance(
+    const ConformalMesh&             mesh,
+    const std::vector<double>&       x,
+    const InversiveDistanceMaps&     m,
+    double eps = 1e-5,
+    double tol = 1e-6)
+{
+    auto G = inversive_distance_gradient(mesh, x, m);
+    const std::size_t n = G.size();
+
+    for (std::size_t i = 0; i < n; ++i) {
+        std::vector<double> xp = x, xm = x;
+        xp[i] += eps;
+        xm[i] -= eps;
+        double Ep = inversive_distance_energy(mesh, xp, m);
+        double Em = inversive_distance_energy(mesh, xm, m);
+        double fd = (Ep - Em) / (2.0 * eps);
+        if (std::abs(G[i] - fd) > tol) {
+            std::cerr << "[inversive-distance] FD gradient mismatch at DOF " << i
+                      << ": analytic=" << G[i]
+                      << "  FD=" << fd
+                      << "  diff=" << (G[i] - fd) << "\n";
+            return false;
+        }
+    }
+    return true;
+}
+
+/// Newton equilibrium check: returns `true` iff the gradient at `x`
+/// is below `tol` in infinity norm (Σ adj-face angles equal Θ_v).
+inline bool is_inversive_distance_equilibrium(
+    const ConformalMesh&             mesh,
+    const std::vector<double>&       x,
+    const InversiveDistanceMaps&     m,
+    double tol = 1e-8)
+{
+    auto G = inversive_distance_gradient(mesh, x, m);
+    for (double g : G)
+        if (std::abs(g) > tol) return false;
+    return true;
+}
+
+} // namespace conformallab

code/include/layout.hpp

@@ -1,4 +1,7 @@
 #pragma once
+// Copyright (c) 2024-2026 Tarik Moussa.
+// SPDX-License-Identifier: MIT
+
 // layout.hpp
 //
 // Phase 5/6/7 — Layout / embedding: DOF vector → vertex coordinates in the
@@ -75,28 +78,38 @@ namespace conformallab {
 // For hyperbolic holonomy the map is an orientation-preserving isometry of
 // the Poincaré disk (SU(1,1) element).
 // ─────────────────────────────────────────────────────────────────────────────
+/// Möbius transformation `T(z) = (a·z + b) / (c·z + d)` of the Riemann
+/// sphere; restricted to SU(1,1) for hyperbolic holonomy on the
+/// Poincaré disk.
 struct MobiusMap {
+    /// Complex scalar used for all entries.
     using C = std::complex<double>;
-    C a{1.0, 0.0};
+    C a{1.0, 0.0}; ///< Top-left coefficient.
-    C b{0.0, 0.0};
+    C b{0.0, 0.0}; ///< Top-right coefficient.
-    C c{0.0, 0.0};
+    C c{0.0, 0.0}; ///< Bottom-left coefficient.
-    C d{1.0, 0.0};
+    C d{1.0, 0.0}; ///< Bottom-right coefficient.
 
+    /// Apply the transformation to a complex point.
     C apply(C z) const { return (a * z + b) / (c * z + d); }
 
+    /// Apply the transformation to a 2-D real point (interpreted as `x + iy`).
     Eigen::Vector2d apply(const Eigen::Vector2d& p) const {
         C w = apply(C(p.x(), p.y()));
         return Eigen::Vector2d(w.real(), w.imag());
     }
 
+    /// Identity map.
     static MobiusMap identity() { return {C(1), C(0), C(0), C(1)}; }
 
+    /// Inverse map.
     MobiusMap inverse()               const { return {d, -b, -c, a}; }
+    /// Composition `(*this) ∘ T`, i.e. apply `T` first then `*this`.
     MobiusMap compose(const MobiusMap& T) const {
         return { a*T.a + b*T.c,  a*T.b + b*T.d,
                  c*T.a + d*T.c,  c*T.b + d*T.d };
     }
 
+    /// `true` iff the map is the identity up to tolerance `tol`.
     bool is_identity(double tol = 1e-9) const {
         if (std::abs(d) < 1e-14) return false;
         C a_ = a/d, b_ = b/d, c_ = c/d;
@@ -121,6 +134,9 @@ struct MobiusMap {
 
 // ── Result types ──────────────────────────────────────────────────────────────
 
+/// Result of a 2-D layout (`euclidean_layout`, `hyper_ideal_layout`):
+/// per-vertex UV coordinates plus a per-half-edge UV atlas for seamed
+/// textures.
 struct Layout2D {
     /// uv[v.idx()] — primary 2-D position (first / shallowest-BFS-depth visit).
     std::vector<Eigen::Vector2d> uv;
@@ -136,14 +152,15 @@ struct Layout2D {
     /// Size = mesh.number_of_halfedges().  Border halfedges = (0,0).
     std::vector<Eigen::Vector2d> halfedge_uv;
 
-    bool success  = false;
+    bool success  = false; ///< `true` iff the BFS placed every vertex.
-    bool has_seam = false;   ///< true when a vertex was reached via two paths
+    bool has_seam = false; ///< `true` when a vertex was reached via two paths.
 };
 
+/// Result of a 3-D layout (`spherical_layout`): per-vertex positions on S².
 struct Layout3D {
-    std::vector<Eigen::Vector3d> pos;
+    std::vector<Eigen::Vector3d> pos; ///< Per-vertex spherical positions.
-    bool success  = false;
+    bool success  = false; ///< `true` iff the BFS placed every vertex.
-    bool has_seam = false;
+    bool has_seam = false; ///< `true` when a vertex was reached via two paths.
 };
 
 /// Per-cut-edge holonomy.
@@ -156,9 +173,9 @@ struct Layout3D {
 ///   trilaterated virtual position obtained by continuing the unfolding across
 ///   the cut.
 struct HolonomyData {
-    std::vector<Eigen::Vector2d> translations;   ///< Euclidean / spherical
+    std::vector<Eigen::Vector2d> translations;     ///< Euclidean / spherical translation per cut edge.
-    std::vector<MobiusMap>       mobius_maps;     ///< hyperbolic (Phase 7)
+    std::vector<MobiusMap>       mobius_maps;      ///< Hyperbolic Möbius isometry per cut edge (Phase 7).
-    std::vector<std::size_t>     cut_edge_indices;
+    std::vector<std::size_t>     cut_edge_indices; ///< Index (in the cut-graph edge list) of each holonomy entry.
 };
 
 // ── Internal helpers ──────────────────────────────────────────────────────────
@@ -343,7 +360,8 @@ inline void center_poincare_disk_weighted(
 
 } // namespace detail
 
-// ── Vertex Voronoi area weights ───────────────────────────────────────────────
+/// Compute per-vertex area weights (sum of 1/3 of each adjacent triangle area).
+/// Used by area-weighted layout normalisation routines.
 inline std::vector<double> compute_vertex_area_weights(const ConformalMesh& mesh)
 {
     std::vector<double> w(mesh.number_of_vertices(), 0.0);
@@ -357,6 +375,8 @@ inline std::vector<double> compute_vertex_area_weights(const ConformalMesh& mesh
 
 // ── Layout normalisation ──────────────────────────────────────────────────────
 
+/// Euclidean canonical normalisation: translate centroid to the origin
+/// and rotate the principal axis of the UV cloud onto the x-axis.
 inline void normalise_euclidean(Layout2D& layout)
 {
     if (!layout.success || layout.uv.empty()) return;
@@ -388,6 +408,8 @@ inline void normalise_hyperbolic(Layout2D& layout, const ConformalMesh& mesh)
     // halfedge_uv follows the same Möbius map
     detail::center_poincare_disk(layout.halfedge_uv);
 }
+/// Hyperbolic canonical normalisation, mesh-free fallback: uniform
+/// (unweighted) iterative Möbius centring of the Poincaré disk.
 inline void normalise_hyperbolic(Layout2D& layout) // fallback without mesh
 {
     if (!layout.success || layout.uv.empty()) return;
@@ -395,6 +417,9 @@ inline void normalise_hyperbolic(Layout2D& layout) // fallback without mesh
     detail::center_poincare_disk(layout.halfedge_uv);
 }
 
+/// Spherical canonical normalisation: rotate the layout so that the
+/// per-vertex centroid (projected back to S²) coincides with the north
+/// pole (Rodrigues rotation).
 inline void normalise_spherical(Layout3D& layout)
 {
     if (!layout.success || layout.pos.empty()) return;
@@ -452,6 +477,29 @@ inline void set_root_huv_2d(
 } // namespace detail
 
 // ── Euclidean layout ──────────────────────────────────────────────────────────
+
+/// Embed the mesh in ℝ² using the Euclidean metric encoded in x.
+///
+/// Runs priority-BFS trilateration: places vertices in order of BFS depth
+/// from the root face (largest 3D area), so errors accumulate last.
+/// For closed genus-g surfaces a CutGraph must be supplied — otherwise
+/// the layout will have a seam discontinuity (Layout2D::has_seam = true).
+///
+/// \param mesh      Input surface mesh.  Must have lambda0 and v_idx set in maps.
+/// \param x         DOF vector returned by newton_euclidean().
+/// \param maps      EuclideanMaps (lambda0, v_idx, e_idx).
+/// \param cut       Optional cut graph (compute_cut_graph()).  Pass nullptr for
+///                  open meshes or if seams are acceptable.
+/// \param holonomy  If non-null and cut != nullptr, receives the lattice
+///                  translations ω_i ∈ ℂ per cut edge.
+///                  Pass to compute_period_matrix() for the conformal modulus τ.
+/// \param normalise If true, calls normalise_euclidean() on the result:
+///                  centroid → origin, major axis → x-axis (PCA).
+/// \return          Layout2D with .uv[v] (per-vertex UV) and
+///                  .halfedge_uv[h] (per-halfedge UV for texture atlasing).
+///
+/// \note halfedge_uv differs from uv at seam edges: the two sides of a cut
+///       carry different UV coordinates for proper GPU texture atlasing.
 inline Layout2D euclidean_layout(
     ConformalMesh&             mesh,
     const std::vector<double>& x,
@@ -571,6 +619,20 @@ inline Layout2D euclidean_layout(
 }
 
 // ── Spherical layout ──────────────────────────────────────────────────────────
+
+/// Embed the mesh on the unit sphere S² using the spherical metric encoded in x.
+///
+/// Runs priority-BFS trilateration using the spherical law of cosines.
+/// Typical use: genus-0 (sphere-like) surfaces after newton_spherical().
+///
+/// \param mesh      Input genus-0 surface mesh.
+/// \param x         DOF vector returned by newton_spherical().
+/// \param maps      SphericalMaps.
+/// \param cut       Optional cut graph (rarely needed for genus-0).
+/// \param holonomy  If non-null, receives rotational holonomies (spherical).
+/// \param normalise If true, calls normalise_spherical(): rotates the centroid
+///                  to the north pole (Rodrigues rotation formula).
+/// \return          Layout3D with .xyz[v] ∈ S² ⊂ ℝ³ for each vertex.
 inline Layout3D spherical_layout(
     ConformalMesh&             mesh,
     const std::vector<double>& x,
@@ -661,6 +723,12 @@ inline Layout3D spherical_layout(
                 result.pos[vs.idx()], result.pos[vt.idx()],
                 arc_len(mesh.prev(hx)), arc_len(mesh.next(hx)));
             Eigen::Vector3d diff = p_tri - result.pos[vn.idx()];
+            // Note: spherical holonomy is geometrically a 3-D rotation, not a 2-D
+            // translation.  The Vector2d here stores only the (x,y) component of the
+            // S²-position difference across the cut, which is an approximation.
+            // For accurate spherical holonomy (rotation axis + angle) use the full
+            // 3-D positions in result.pos[] directly.  Phase 10+ will replace this
+            // with a proper SO(3) representation.
             holonomy->translations.push_back(Eigen::Vector2d(diff.x(), diff.y()));
         }
     }
@@ -670,6 +738,29 @@ inline Layout3D spherical_layout(
 }
 
 // ── HyperIdeal layout (Poincaré disk) — exact trilateration ──────────────────
+
+/// Embed the mesh in the Poincaré disk (H²) using the hyperbolic metric encoded in x.
+///
+/// Runs priority-BFS trilateration using exact Möbius-isometric placement:
+/// each new vertex is located by solving the hyperbolic law of cosines and
+/// applying a Möbius map to position it in the disk.
+/// For closed genus-g surfaces (g ≥ 1) a CutGraph is required.
+///
+/// \param mesh      Input genus-g surface mesh (g ≥ 1).
+/// \param x         DOF vector returned by newton_hyper_ideal()
+///                  (vertex b_v and edge a_e variables).
+/// \param maps      HyperIdealMaps (lambda0, v_idx, e_idx).
+/// \param cut       CutGraph from compute_cut_graph().  Required for closed surfaces.
+/// \param holonomy  If non-null, receives the Möbius maps T_i ∈ SU(1,1) per cut edge.
+///                  Pass to compute_period_matrix() for holonomy analysis.
+/// \param normalise If true, calls normalise_hyperbolic(): iterative face-area-weighted
+///                  Möbius centring (Fréchet mean, 30 iterations) → disk origin.
+/// \return          Layout2D with .uv[v] ∈ Poincaré disk (|uv| < 1) for each vertex,
+///                  and .halfedge_uv[h] for seam-aware texture atlasing.
+///
+/// \note All vertex positions satisfy |uv[v]| < 1 (inside the Poincaré disk)
+///       if the metric is hyperbolic.  Points on or outside the boundary indicate
+///       a non-hyperbolic metric (Gauss–Bonnet violation).
 inline Layout2D hyper_ideal_layout(
     ConformalMesh&             mesh,
     const std::vector<double>& x,
@@ -763,6 +854,13 @@ inline Layout2D hyper_ideal_layout(
             Eigen::Vector2d p_tri = detail::trilaterate_hyp(result.uv[vs.idx()], result.uv[vt.idx()], D, da, db);
             detail::set_face_huv_2d(result.halfedge_uv, mesh, hx, result.uv, p_tri);
             using C = std::complex<double>;
+            // Möbius deck transformation T across cut edge (vs,vt):
+            // T is the unique Möbius isometry of the Poincaré disk that:
+            //   - fixes vs and vt  (z1=w1, z2=w2: the cut-edge endpoints are
+            //     identified across the seam, so T maps each to itself)
+            //   - maps vn (placed side) → p_tri (virtual side)
+            // This uniquely determines the hyperbolic translation/rotation
+            // along the geodesic through vs and vt.
             holonomy->mobius_maps.push_back(MobiusMap::from_three(
                 C(result.uv[vs.idx()].x(), result.uv[vs.idx()].y()),
                 C(result.uv[vs.idx()].x(), result.uv[vs.idx()].y()),
@@ -779,6 +877,8 @@ inline Layout2D hyper_ideal_layout(
 
 // ── Convenience: save layout as OFF ──────────────────────────────────────────
 
+/// Write a 2-D layout to disk in OFF format with z = 0.  Convenience
+/// helper for quickly inspecting the UV result in any OFF viewer.
 inline void save_layout_off(
     const std::string& path, ConformalMesh& mesh, const Layout2D& layout)
 {
@@ -792,6 +892,7 @@ inline void save_layout_off(
     }
 }
 
+/// Write a 3-D (spherical) layout to disk in OFF format.
 inline void save_layout_off(
     const std::string& path, ConformalMesh& mesh, const Layout3D& layout)
 {

code/include/matrix_utility.hpp

@@ -1,4 +1,7 @@
 #pragma once
+// Copyright (c) 2024-2026 Tarik Moussa.
+// SPDX-License-Identifier: MIT
+
 
 // 4x4 mapping matrix from corresponding point pairs.
 // Ported from de.varylab.discreteconformal.math.MatrixUtility (Java).
@@ -7,12 +10,10 @@
 
 namespace conformallab {
 
-// Find the 4×4 matrix R that maps source points to target points.
+/// Find the 4×4 matrix `R` that maps each row of `from` (homogeneous
-// Each row of `from` / `to` is a homogeneous 4-vector (one point per row).
+/// 4-vector) to the corresponding row of `to`: `R · fromᵀ = toᵀ`.
-// Post-condition: R * from.row(i).T == to.row(i).T for all i.
+/// Computed as `R = toᵀ · (fromᵀ)⁻¹`.  Same as Java
-//
+/// `MatrixUtility.makeMappingMatrix()`.
-// Implementation: R = to^T * (from^T)^{-1}
-// Corresponds to Java MatrixUtility.makeMappingMatrix().
 inline Eigen::Matrix4d makeMappingMatrix(const Eigen::Matrix4d& from,
                                          const Eigen::Matrix4d& to) {
     return to.transpose() * from.transpose().inverse();

code/include/mesh_builder.hpp

@@ -1,4 +1,7 @@
 #pragma once
+// Copyright (c) 2024-2026 Tarik Moussa.
+// SPDX-License-Identifier: MIT
+
 // mesh_builder.hpp
 //
 // Factory functions that build simple reference meshes for testing and examples.
@@ -22,7 +25,7 @@ namespace conformallab {
 //   |    \
 //   v0 ─ v1
 //
-// Returns a mesh with 1 face, 3 vertices, 3 edges.
+/// Build a single right-angle triangle in the xy-plane (1 face, 3 vertices, 3 edges).
 // The triangle lies in the xy-plane with a right angle at v0.
 inline ConformalMesh make_triangle(
     double x0=0, double y0=0,
@@ -39,7 +42,7 @@ inline ConformalMesh make_triangle(
 
 // ── Regular tetrahedron ──────────────────────────────────────────────────────
 //
-// 4 vertices, 4 faces, 6 edges.
+/// Build a regular tetrahedron (4 vertices, 4 faces, 6 edges; sphere topology).
 // Euler characteristic: V - E + F = 4 - 6 + 4 = 2  (sphere topology).
 // Used to test closed-surface traversal.
 inline ConformalMesh make_tetrahedron()
@@ -67,8 +70,8 @@ inline ConformalMesh make_tetrahedron()
 //   |  \ |
 //   v0 ─ v1
 //
-// 4 vertices, 2 faces, 5 edges (1 interior edge v1–v2 shared by both faces).
+/// Build a two-triangle strip (4 vertices, 2 faces, 5 edges; 1 interior edge).
-// Useful for testing edge-interior vs edge-boundary distinction.
+/// Useful for testing interior- vs boundary-edge distinction.
 inline ConformalMesh make_quad_strip()
 {
     ConformalMesh mesh;
@@ -85,8 +88,8 @@ inline ConformalMesh make_quad_strip()
 
 // ── Regular flat polygon fan ─────────────────────────────────────────────────
 //
-// n triangles sharing a central vertex; forms a disk topology (boundary).
+/// Build a regular flat polygon fan: `n` triangles sharing a central
-// Used to verify valence-n vertex traversal.
+/// vertex, with rim vertices on the unit circle (disk topology).
 inline ConformalMesh make_fan(int n)
 {
     CGAL_precondition(n >= 3);
@@ -109,10 +112,9 @@ inline ConformalMesh make_fan(int n)
 
 // ── Spherical tetrahedron (vertices on the unit sphere) ───────────────────────
 //
-// The four vertices of a regular tetrahedron projected onto the unit sphere.
+/// Build a regular tetrahedron with vertices on the unit sphere.
-// Starting from (±1,±1,±1), dividing by √3 gives unit-length positions.
+/// All edge lengths equal `arccos(−1/3) ≈ 1.9106 rad`; used by the
-// All edge lengths equal arccos(−1/3) ≈ 1.9106 radians.
+/// SphericalFunctional tests.
-// Used for SphericalFunctional tests (all four faces are valid spherical triangles).
 inline ConformalMesh make_spherical_tetrahedron()
 {
     ConformalMesh mesh;
@@ -133,10 +135,9 @@ inline ConformalMesh make_spherical_tetrahedron()
 
 // ── Octahedron face triangle (vertices on the unit sphere) ────────────────────
 //
-// One face of a regular octahedron: the triangle (1,0,0)→(0,1,0)→(0,0,1).
+/// Build one face of a regular octahedron `(1,0,0)→(0,1,0)→(0,0,1)`:
-// All edge lengths equal arccos(0) = π/2.
+/// a right-angled spherical triangle with edge length `π/2` and base
-// The corner angles are all π/2 (right-angled spherical triangle).
+/// log-length `λ° = −log 2 ≈ −0.6931`.
-// base log-length: λ° = 2·log(sin(π/4)) = 2·log(1/√2) = −log(2) ≈ −0.6931.
 inline ConformalMesh make_octahedron_face()
 {
     ConformalMesh mesh;

code/include/mesh_io.hpp

@@ -1,4 +1,7 @@
 #pragma once
+// Copyright (c) 2024-2026 Tarik Moussa.
+// SPDX-License-Identifier: MIT
+
 // mesh_io.hpp
 //
 // Phase 4b — CGAL::IO wrappers for ConformalMesh.
@@ -28,26 +31,22 @@
 
 namespace conformallab {
 
-// ── Read ──────────────────────────────────────────────────────────────────────
+/// Read a polygon mesh from `filename` into `mesh` (clears existing content).
-//
+/// Returns `true` on success, `false` on failure.
-// Reads a polygon mesh from file into `mesh` (clears any existing content).
-// Returns true on success, false on failure.
 inline bool read_mesh(const std::string& filename, ConformalMesh& mesh)
 {
     mesh.clear();
     return CGAL::IO::read_polygon_mesh(filename, mesh);
 }
 
-// ── Write ─────────────────────────────────────────────────────────────────────
+/// Write `mesh` to `filename`.  Returns `true` on success.
-//
-// Writes `mesh` to `filename`.  Returns true on success.
 inline bool write_mesh(const std::string& filename, const ConformalMesh& mesh)
 {
     return CGAL::IO::write_polygon_mesh(filename, mesh);
 }
 
-// ── Convenience: throwing wrappers ────────────────────────────────────────────
+/// Throwing wrapper around `read_mesh`: returns the mesh by value
-
+/// or throws `std::runtime_error` on read failure.
 inline ConformalMesh load_mesh(const std::string& filename)
 {
     ConformalMesh mesh;
@@ -56,6 +55,8 @@ inline ConformalMesh load_mesh(const std::string& filename)
     return mesh;
 }
 
+/// Throwing wrapper around `write_mesh`; throws `std::runtime_error` on
+/// write failure.
 inline void save_mesh(const std::string& filename, const ConformalMesh& mesh)
 {
     if (!write_mesh(filename, mesh))

code/include/mesh_utils.hpp

@@ -1,14 +1,41 @@
 #pragma once
+// Copyright (c) 2024-2026 Tarik Moussa.
+// SPDX-License-Identifier: MIT
+
+// mesh_utils.hpp
+//
+// Conversions between CGAL::Surface_mesh and Eigen matrices.  Used
+// primarily by the viewer / example programs to bridge to libigl, which
+// expects (V, F) matrix pairs rather than a halfedge data structure.
+//
+// All functions are templated on the kernel so the same code works
+// with `Simple_cartesian<double>` (production) and with any CGAL
+// `Kernel_d::Point_3` (test scaffolding).
+
 #include <CGAL/Surface_mesh.h>
-#include <Eigen/Dense>
+#include <Eigen/Core>  // downgraded from <Eigen/Dense>: this header only
+                      // uses Matrix/Vector primitives, no decompositions.
 #include <CGAL/Polygon_mesh_processing/triangulate_faces.h>
 
 
 namespace mesh_utils {
+
+/// Copy `mesh` into an Eigen `(V, F)` pair (libigl convention).
+///
+/// **Side effect:** `mesh` is triangulated in place via
+/// `CGAL::Polygon_mesh_processing::triangulate_faces` so the output
+/// `F` is guaranteed to be a 3-column matrix.  If `mesh` is already a
+/// triangle mesh this is a no-op.
+///
+/// \param mesh  Input surface mesh.  **Modified in place** if any face
+///              has more than 3 vertices.
+/// \param V     Output: `(num_vertices, 3)` matrix of vertex positions.
+/// \param F     Output: `(num_faces, 3)` matrix of vertex indices per
+///              face (rows are individual triangles).
 template <typename Kernel>
 void cgal_to_eigen(CGAL::Surface_mesh<typename Kernel::Point_3>& mesh,
                    Eigen::MatrixXd& V, Eigen::MatrixXi& F) {
-  
+
  CGAL::Polygon_mesh_processing::triangulate_faces(mesh);
 
   V.resize(mesh.num_vertices(), 3);
@@ -30,13 +57,38 @@ void cgal_to_eigen(CGAL::Surface_mesh<typename Kernel::Point_3>& mesh,
     face_idx++;
   }
 }
+
+/// Quick interactive visualisation via libigl + GLFW.
+///
+/// **Requires** `WITH_VIEWER=ON` at CMake time (which is implied by
+/// `WITH_CGAL=ON`).  Blocks until the viewer window is closed.
+/// Not suitable for CI / headless contexts.
+///
+/// Typical use:
+/// \code{.cpp}
+///   Eigen::MatrixXd V;  Eigen::MatrixXi F;
+///   mesh_utils::cgal_to_eigen<Kernel>(mesh, V, F);
+///   mesh_utils::simple_visualize_mesh<Kernel>(V, F);
+/// \endcode
 template <typename Kernel>
 void simple_visualize_mesh(Eigen::MatrixXd& V, Eigen::MatrixXi& F) {
   igl::opengl::glfw::Viewer viewer;
   viewer.data().set_mesh(V, F);
   viewer.launch();
 }
-// Zero-Copy Map für V (optional)
+
+/// Zero-copy `Eigen::Map` view of `mesh`'s vertex positions.
+///
+/// Returns a row-major `(N, 3)` `Eigen::Map` that aliases the
+/// `mesh.points()` storage directly — no allocation, O(1).
+///
+/// **Lifetime warning:** the returned `Map` references memory owned by
+/// `mesh`.  Adding or removing vertices may invalidate the underlying
+/// storage; use the `Map` only as long as `mesh` is structurally stable.
+///
+/// This is the read-write counterpart to `cgal_to_eigen` for cases
+/// where the caller wants to *modify* vertex positions through Eigen
+/// (e.g. apply a Möbius transformation) without an intermediate copy.
 template <typename Kernel>
 Eigen::Map<Eigen::Matrix<double, Eigen::Dynamic, 3, Eigen::RowMajor>>
 get_vertex_map(CGAL::Surface_mesh<typename Kernel::Point_3>& mesh) {

code/include/newton_solver.hpp

@@ -1,4 +1,7 @@
 #pragma once
+// Copyright (c) 2024-2026 Tarik Moussa.
+// SPDX-License-Identifier: MIT
+
 // newton_solver.hpp
 //
 // Phase 4a — Newton solver for all three discrete conformal functionals.
@@ -31,6 +34,8 @@
 #include "euclidean_hessian.hpp"
 #include "spherical_hessian.hpp"
 #include "hyper_ideal_hessian.hpp"
+#include "cp_euclidean_functional.hpp"
+#include "inversive_distance_functional.hpp"
 #include <Eigen/SparseCholesky>
 #include <Eigen/SparseQR>
 #include <Eigen/OrderingMethods>
@@ -42,11 +47,12 @@ namespace conformallab {
 
 // ── Result ────────────────────────────────────────────────────────────────────
 
+/// Result of `newton_solve(...)` — converged DOF vector + diagnostics.
 struct NewtonResult {
-    std::vector<double> x;            ///< DOF vector at termination
+    std::vector<double> x;            ///< DOF vector at termination.
-    int                 iterations;   ///< Newton steps taken
+    int                 iterations;   ///< Newton steps taken.
-    double              grad_inf_norm;///< max |G_i| at termination
+    double              grad_inf_norm;///< max |Gᵢ| at termination.
-    bool                converged;    ///< true iff grad_inf_norm < tol
+    bool                converged;    ///< `true` iff `grad_inf_norm < tol`.
 };
 
 // ── Internal helpers ──────────────────────────────────────────────────────────
@@ -94,6 +100,10 @@ inline Eigen::VectorXd solve_with_fallback(
 //
 //   fallback_used  – if non-null, set to true iff SparseQR was invoked
 //   Returns Eigen::VectorXd::Zero(rhs.size()) if both solvers fail.
+/// Solve `A·x = rhs` with the same SimplicialLDLT → SparseQR fallback
+/// strategy used inside all three Newton solvers.  If `fallback_used`
+/// is non-null, it is set to `true` iff the SparseQR fallback ran.
+/// Returns `Eigen::VectorXd::Zero(rhs.size())` if both solvers fail.
 inline Eigen::VectorXd solve_linear_system(
     const Eigen::SparseMatrix<double>& A,
     const Eigen::VectorXd&             rhs,
@@ -139,9 +149,29 @@ inline std::vector<double> line_search(
 } // namespace detail
 
 // ── Euclidean Newton solver ────────────────────────────────────────────────────
-//
+
-// Minimises the Euclidean discrete conformal energy by solving G(x) = 0.
+/// Solve the Euclidean discrete conformal problem: find u ∈ ℝ^V such that
-// The Hessian H is PSD; Eigen::SimplicialLDLT is used directly.
+/// Σ_{faces adj v} α_v(u) = Θ_v for all vertices v.
+///
+/// Starting from x0, Newton's method minimises E(u) (the Euclidean DCE energy,
+/// which is convex) by iterating  u ← u − H⁻¹·G  with backtracking line search.
+/// The Hessian H is the cotangent Laplacian — PSD with one zero eigenvalue on
+/// closed surfaces (gauge mode).  A SparseQR fallback handles this automatically.
+///
+/// \param mesh      Input triangulated surface (edges must carry lambda0 + theta_v).
+/// \param x0        Initial DOF vector (length = number of free vertices).
+///                  Pass all-zeros for a flat start (typical).
+/// \param m         EuclideanMaps: lambda0[e], theta_v[v], v_idx[v] must be set.
+///                  Call setup_euclidean_maps() + compute_euclidean_lambda0_from_mesh()
+///                  + enforce_gauss_bonnet() before passing here.
+/// \param tol       Convergence threshold on max |G_i|.  Default: 1e-8.
+/// \param max_iter  Maximum Newton iterations.  Default: 200.
+/// \return          NewtonResult{x*, iterations, grad_inf_norm, converged}.
+///
+/// \note On closed meshes without a pinned vertex, SimplicialLDLT detects the
+///       gauge singularity and falls back to SparseQR automatically.
+///
+/// \see doc/math/discrete-conformal-theory.md §3 for the mathematical background.
 inline NewtonResult newton_euclidean(
     ConformalMesh&             mesh,
     std::vector<double>        x0,
@@ -199,10 +229,28 @@ inline NewtonResult newton_euclidean(
 }
 
 // ── Spherical Newton solver ───────────────────────────────────────────────────
-//
+
-// Solves G(x) = 0 for the spherical discrete conformal functional.
+/// Solve the spherical discrete conformal problem: find u ∈ ℝ^V such that
-// The Hessian H is NSD at the solution; −H is PSD, so we factorise −H and
+/// Σ_{faces adj v} α_v(u) = Θ_v for all vertices v (genus-0 / sphere-like surfaces).
-// solve (−H)·Δx = G  ⟺  H·Δx = −G.
+///
+/// The spherical DCE energy is *concave*, so the Hessian H is NSD at the solution.
+/// The solver factorises −H (which is PSD) and solves (−H)·Δx = G.
+/// A gauge vertex must be pinned (set v_idx = -1) to remove the rotational mode.
+///
+/// \param mesh      Input triangulated surface, genus 0.
+/// \param x0        Initial DOF vector (length = free vertices, excluding gauge_vertex).
+///                  All-zeros is a good start.
+/// \param m         SphericalMaps: lambda0[e], theta_v[v], v_idx[v], gauge_vertex set.
+///                  Call setup_spherical_maps() + compute_spherical_lambda0_from_mesh()
+///                  + enforce_gauss_bonnet() (checks Σ(2π-Θ) > 0) before passing here.
+/// \param tol       Convergence threshold on max |G_i|.  Default: 1e-8.
+/// \param max_iter  Maximum Newton iterations.  Default: 200.
+/// \return          NewtonResult{x*, iterations, grad_inf_norm, converged}.
+///
+/// \note Unlike the Euclidean solver, the spherical solver does NOT need a SparseQR
+///       fallback — the gauge vertex pins the null mode directly.
+///
+/// \see doc/math/geometry-modes.md §Spherical for sign-convention details.
 inline NewtonResult newton_spherical(
     ConformalMesh&             mesh,
     std::vector<double>        x0,
@@ -258,17 +306,31 @@ inline NewtonResult newton_spherical(
 }
 
 // ── HyperIdeal Newton solver ──────────────────────────────────────────────────
-//
+
-// Solves G(x) = 0 for the hyper-ideal discrete conformal functional.
+/// Solve the hyper-ideal discrete conformal problem: find (b, a) ∈ ℝ^{V+E} such that
-//
+/// Σ β_v(b,a) = Θ_v  and  Σ α_e(b,a) = θ_e  for all vertices v and edges e.
-// Gradient sign convention (opposite to Euclidean/Spherical):
+///
-//   G_v = Σ β_v − Θ_v,   G_e = Σ α_e − θ_e   (actual − target)
+/// Used for genus-g surfaces (g ≥ 1) under hyperbolic cone metrics.
-//
+/// The energy is *strictly convex* (Springborn 2020, Theorem 1.3), so Newton
-// The hyper-ideal energy is strictly convex (Springborn 2020), so H is PSD
+/// converges globally from any starting point.
-// and SimplicialLDLT (with SparseQR fallback) applies directly.
+///
-//
+/// DOF layout: first V_free entries are vertex variables b_v (hyper-ideal radii),
-// The Hessian is computed by symmetric finite differences of G (see
+/// followed by E entries for edge variables a_e (intersection angles).
-// hyper_ideal_hessian.hpp); replace with an analytical Hessian in Phase 5.
+/// Use assign_all_dof_indices(mesh, maps) to set v_idx and e_idx automatically —
+/// no vertex needs to be pinned.
+///
+/// \param mesh      Input triangulated surface, genus g ≥ 1.
+/// \param x0        Initial DOF vector (length = V + E).  All-zeros typical.
+/// \param m         HyperIdealMaps: lambda0[e], theta_v[v], v_idx[v], e_idx[e] set.
+///                  Call setup_hyper_ideal_maps() + compute_hyper_ideal_lambda0_from_mesh().
+/// \param tol       Convergence threshold on max |G_i|.  Default: 1e-8.
+/// \param max_iter  Maximum Newton iterations.  Default: 200.
+/// \param hess_eps  Finite-difference step for Hessian approximation.  Default: 1e-5.
+///                  (Phase 9b will replace this with an analytic Hessian.)
+/// \return          NewtonResult{x*, iterations, grad_inf_norm, converged}.
+///
+/// \see Springborn (2020), Theorem 1.3 for the strict convexity proof.
+/// \see doc/math/geometry-modes.md §Hyper-ideal for DOF layout details.
 inline NewtonResult newton_hyper_ideal(
     ConformalMesh&             mesh,
     std::vector<double>        x0,
@@ -323,4 +385,187 @@ inline NewtonResult newton_hyper_ideal(
     return res;
 }
 
+// ── CP-Euclidean Newton solver (Phase 9a.1) ───────────────────────────────────
+
+/// Solve the CP-Euclidean circle-packing problem: find ρ ∈ ℝ^F such that the
+/// per-face angle sums match φ_f at every free face.
+///
+/// The CP-Euclidean energy (Bobenko-Pinkall-Springborn 2010 §6) is strictly
+/// convex on its open domain of validity, so the Hessian H is PSD and the
+/// solution is unique up to the gauge mode pinned by `f_idx == −1`.
+/// `cp_euclidean_hessian` provides the analytic 2×2-per-edge formula
+/// `h_jk = sin θ / (cosh Δρ − cos θ)`; no FD machinery is required.
+///
+/// \param mesh      Input triangle mesh (closed or with boundary).
+/// \param x0        Initial DOF vector (length = number of free faces).
+///                  All-zeros is a valid start.
+/// \param m         CPEuclideanMaps: f_idx must have one pinned face
+///                  (`f_idx[f0] == −1`); theta_e and phi_f set by the caller.
+/// \param tol       Convergence threshold on `‖G‖∞`.  Default: 1e-8.
+/// \param max_iter  Newton iteration limit.  Default: 200.
+/// \return          NewtonResult{x*, iterations, grad_inf_norm, converged}.
+///
+/// \note  Unlike the Euclidean solver, the CP-Euclidean Hessian is exact
+///        (analytic), so the SparseQR fallback only triggers in genuine
+///        gauge-singular situations (no pinned face).
+/// \see   doc/architecture/phase-9a-validation.md §1 for the BPS-2010 mapping.
+inline NewtonResult newton_cp_euclidean(
+    ConformalMesh&             mesh,
+    std::vector<double>        x0,
+    const CPEuclideanMaps&     m,
+    double                     tol      = 1e-8,
+    int                        max_iter = 200)
+{
+    std::vector<double> x = x0;
+    const int n = static_cast<int>(x.size());
+
+    NewtonResult res;
+    res.converged      = false;
+    res.iterations     = 0;
+    res.grad_inf_norm  = 0.0;
+
+    for (int iter = 0; iter < max_iter; ++iter) {
+        auto G_std = cp_euclidean_gradient(mesh, x, m);
+        Eigen::Map<const Eigen::VectorXd> G(G_std.data(), n);
+
+        double inf_norm = G.cwiseAbs().maxCoeff();
+        if (inf_norm < tol) {
+            res.converged     = true;
+            res.grad_inf_norm = inf_norm;
+            res.iterations    = iter;
+            res.x             = x;
+            return res;
+        }
+
+        auto H = cp_euclidean_hessian(mesh, x, m);
+        bool ok = false;
+        Eigen::VectorXd dx = detail::solve_with_fallback(H, -G, ok);
+        if (!ok) break;
+
+        double norm0 = G.norm();
+        x = detail::line_search(x, dx, norm0,
+            [&](const std::vector<double>& xnew) {
+                return cp_euclidean_gradient(mesh, xnew, m);
+            });
+
+        res.iterations = iter + 1;
+    }
+
+    auto G_final = cp_euclidean_gradient(mesh, x, m);
+    double inf_final = 0.0;
+    for (double v : G_final) inf_final = std::max(inf_final, std::abs(v));
+    res.grad_inf_norm = inf_final;
+    res.x             = x;
+    return res;
+}
+
+// ── Inversive-Distance Newton solver (Phase 9a.2) ─────────────────────────────
+
+/// Solve the inversive-distance circle-packing problem: find u ∈ ℝ^V such that
+/// Σ_{faces adj v} α_v(u) = Θ_v at every free vertex (Luo 2004 Lemma 3.1).
+///
+/// The inversive-distance energy is (locally) strictly convex on the open
+/// domain where every triangle satisfies the inequalities.  Luo's 1-form is
+/// closed there, so the path-integral energy is well-defined.
+///
+/// MVP implementation: the Hessian is computed by **finite differences** of
+/// the analytic gradient (same pattern as the Phase 4a HyperIdeal solver).
+/// An analytic Hessian via Glickenstein 2011 eq. (4.6) is tracked in
+/// `doc/roadmap/research-track.md` as Phase 9a.2-analytic.
+///
+/// \param mesh      Input triangle mesh.
+/// \param x0        Initial DOF vector (length = number of free vertices).
+/// \param m         InversiveDistanceMaps: v_idx has at least one pinned
+///                  vertex; I_e and r0 set by compute_inversive_distance_init.
+/// \param tol       Convergence threshold on `‖G‖∞`.  Default: 1e-8.
+/// \param max_iter  Newton iteration limit.  Default: 200.
+/// \param hess_eps  FD step size for the Hessian.  Default: 1e-5.
+/// \return          NewtonResult{x*, iterations, grad_inf_norm, converged}.
+///
+/// \note  Convergence is sensitive to the initial point: u = 0 is the
+///        natural choice when `compute_inversive_distance_init_from_mesh`
+///        has been called, since the Bowers-Stephenson identity reconstructs
+///        the input edge lengths at u = 0.
+inline NewtonResult newton_inversive_distance(
+    ConformalMesh&                mesh,
+    std::vector<double>           x0,
+    const InversiveDistanceMaps&  m,
+    double                        tol      = 1e-8,
+    int                           max_iter = 200,
+    double                        hess_eps = 1e-5)
+{
+    std::vector<double> x = x0;
+    const int n = static_cast<int>(x.size());
+
+    NewtonResult res;
+    res.converged      = false;
+    res.iterations     = 0;
+    res.grad_inf_norm  = 0.0;
+
+    // Local FD Hessian builder — n × (cost of gradient eval).
+    auto build_hessian = [&](const std::vector<double>& xc) -> Eigen::SparseMatrix<double> {
+        std::vector<Eigen::Triplet<double>> trips;
+        trips.reserve(static_cast<std::size_t>(n) * 16);   // sparse heuristic
+
+        std::vector<double> xp = xc, xm = xc;
+        for (int j = 0; j < n; ++j) {
+            const std::size_t sj = static_cast<std::size_t>(j);
+            xp[sj] = xc[sj] + hess_eps;
+            xm[sj] = xc[sj] - hess_eps;
+
+            auto Gp = inversive_distance_gradient(mesh, xp, m);
+            auto Gm = inversive_distance_gradient(mesh, xm, m);
+
+            xp[sj] = xm[sj] = xc[sj];   // restore
+
+            for (int i = 0; i < n; ++i) {
+                double val = (Gp[static_cast<std::size_t>(i)]
+                            - Gm[static_cast<std::size_t>(i)])
+                             / (2.0 * hess_eps);
+                if (std::abs(val) > 1e-15)
+                    trips.emplace_back(i, j, val);
+            }
+        }
+        Eigen::SparseMatrix<double> H(n, n);
+        H.setFromTriplets(trips.begin(), trips.end());
+        // Symmetrise — FD rounding may introduce tiny asymmetries.
+        Eigen::SparseMatrix<double> Ht = H.transpose();
+        return (H + Ht) * 0.5;
+    };
+
+    for (int iter = 0; iter < max_iter; ++iter) {
+        auto G_std = inversive_distance_gradient(mesh, x, m);
+        Eigen::Map<const Eigen::VectorXd> G(G_std.data(), n);
+
+        double inf_norm = G.cwiseAbs().maxCoeff();
+        if (inf_norm < tol) {
+            res.converged     = true;
+            res.grad_inf_norm = inf_norm;
+            res.iterations    = iter;
+            res.x             = x;
+            return res;
+        }
+
+        auto H = build_hessian(x);
+        bool ok = false;
+        Eigen::VectorXd dx = detail::solve_with_fallback(H, -G, ok);
+        if (!ok) break;
+
+        double norm0 = G.norm();
+        x = detail::line_search(x, dx, norm0,
+            [&](const std::vector<double>& xnew) {
+                return inversive_distance_gradient(mesh, xnew, m);
+            });
+
+        res.iterations = iter + 1;
+    }
+
+    auto G_final = inversive_distance_gradient(mesh, x, m);
+    double inf_final = 0.0;
+    for (double v : G_final) inf_final = std::max(inf_final, std::abs(v));
+    res.grad_inf_norm = inf_final;
+    res.x             = x;
+    return res;
+}
+
 } // namespace conformallab

code/include/p2_utility.hpp

@@ -1,4 +1,7 @@
 #pragma once
+// Copyright (c) 2024-2026 Tarik Moussa.
+// SPDX-License-Identifier: MIT
+
 
 // 2-D projective geometry utilities for the Euclidean signature.
 // Ported from de.jreality.math.P2 and de.varylab.discreteconformal.math.P2Big.
@@ -13,9 +16,9 @@ namespace conformallab {
 
 // ── Point / line duality ──────────────────────────────────────────────────────
 
-// Intersection of two lines l1, l2  (or  line through two points p1, p2)
+/// Cross-product point–line duality in P²: returns the intersection
-// via the cross product.  Works for any P2 element.
+/// of two lines (or the line through two points).  Same as Java
-// Corresponds to Java P2.pointFromLines / P2.lineFromPoints.
+/// `P2.pointFromLines` / `P2.lineFromPoints`.
 inline Eigen::Vector3d pointFromLines(const Eigen::Vector3d& l1,
                                       const Eigen::Vector3d& l2) {
     return l1.cross(l2);
@@ -23,11 +26,9 @@ inline Eigen::Vector3d pointFromLines(const Eigen::Vector3d& l1,
 
 // ── Euclidean perpendicular bisector ─────────────────────────────────────────
 
-// Returns the homogeneous line coordinates (a, b, c) of the perpendicular
+/// Homogeneous line coordinates `(a, b, c)` of the perpendicular
-// bisector of the segment [p, q] in the Euclidean plane.
+/// bisector of `[p, q]` in the Euclidean plane (`ax + by + c = 0`).
-// Coordinates: ax + by + c = 0  (after dehomogenizing p and q).
+/// Same as Java `P2.perpendicularBisector(p, q, Pn.EUCLIDEAN)`.
-//
-// Corresponds to Java P2.perpendicularBisector(p, q, Pn.EUCLIDEAN).
 inline Eigen::Vector3d perpendicularBisectorEuclidean(const Eigen::Vector3d& p_h,
                                                       const Eigen::Vector3d& q_h) {
     // Dehomogenize
@@ -46,8 +47,7 @@ inline Eigen::Vector3d perpendicularBisectorEuclidean(const Eigen::Vector3d& p_h
     return {d(0), d(1), c};
 }
 
-// ── Euclidean distance between two P2 homogeneous points ─────────────────────
+/// Euclidean distance between two P² homogeneous points (dehomogenises both).
-
 inline double euclideanDistanceP2(const Eigen::Vector3d& p_h,
                                   const Eigen::Vector3d& q_h) {
     Eigen::Vector2d p = p_h.head<2>() / p_h(2);
@@ -57,11 +57,9 @@ inline double euclideanDistanceP2(const Eigen::Vector3d& p_h,
 
 // ── Direct Euclidean isometry from two point-frames ──────────────────────────
 
-// Build the 3×3 projective matrix that represents the coordinate frame
+/// Build the 3×3 projective frame matrix anchored at `p0` with `p1`
-// anchored at p0 with p1 defining the positive x-direction.
+/// defining the positive x-direction (Euclidean case).  Columns:
-// Euclidean case: columns are [dehom(p0), unit_dir(p0→p1), perp_dir].
+/// `[dehom(p0), unit_dir(p0→p1), perp_dir]`.
-//
-// Template parameter S allows float / double / long double.
 template <typename S>
 Eigen::Matrix<S, 3, 3> makeFrameMatrix(Eigen::Matrix<S, 3, 1> p0_h,
                                         Eigen::Matrix<S, 3, 1> p1_h) {
@@ -84,11 +82,9 @@ Eigen::Matrix<S, 3, 3> makeFrameMatrix(Eigen::Matrix<S, 3, 1> p0_h,
     return M;
 }
 
-// Find the 3×3 Euclidean isometry (as a projective matrix) that maps
+/// 3×3 Euclidean isometry (as a projective matrix) that maps the
-// the frame (s1, s2) to the frame (t1, t2).
+/// frame `(s1, s2)` to the frame `(t1, t2)`.  Same as Java
-//
+/// `P2.makeDirectIsometryFromFrames(..., Pn.EUCLIDEAN)`.
-// Corresponds to Java P2.makeDirectIsometryFromFrames(s1, s2, t1, t2, Pn.EUCLIDEAN)
-// and P2Big.makeDirectIsometryFromFrames(...) (the BigDecimal / high-precision variant).
 template <typename S>
 Eigen::Matrix<S, 3, 3> makeDirectIsometryFromFramesEuclidean(
     Eigen::Matrix<S, 3, 1> s1, Eigen::Matrix<S, 3, 1> s2,

code/include/period_matrix.hpp

@@ -1,4 +1,7 @@
 #pragma once
+// Copyright (c) 2024-2026 Tarik Moussa.
+// SPDX-License-Identifier: MIT
+
 // period_matrix.hpp
 //
 // Phase 7 — Period matrix for closed surfaces with Euclidean (flat) metric.
@@ -50,6 +53,8 @@ namespace conformallab {
 // PeriodData
 // ─────────────────────────────────────────────────────────────────────────────
 
+/// Period-matrix data for a genus-g closed surface.  For genus 1 the
+/// conformal type is fully captured by `τ = ω₂ / ω₁ ∈ ℍ`.
 struct PeriodData {
     /// Lattice generators as complex numbers (one per cut edge).
     /// omega[i] = translations[i].x() + i·translations[i].y()
@@ -63,6 +68,7 @@ struct PeriodData {
     /// True if τ has been reduced to the standard fundamental domain.
     bool in_fundamental_domain = false;
 
+    /// Genus of the surface = `|omega| / 2`.
     int genus() const { return static_cast<int>(omega.size()) / 2; }
 };
 
@@ -74,6 +80,9 @@ struct PeriodData {
 //
 // Returns the reduced τ.  Throws if Im(τ) ≤ 0 (not in upper half-plane).
 // ─────────────────────────────────────────────────────────────────────────────
+/// Reduce `τ ∈ ℍ` to the standard SL(2,ℤ) fundamental domain
+/// `F = { τ ∈ ℍ : |τ| ≥ 1, −½ ≤ Re τ < ½ }` via the generators
+/// `S: τ↦−1/τ` and `T: τ↦τ+1`.  Throws if `Im τ ≤ 0`.
 inline std::complex<double> reduce_to_fundamental_domain(std::complex<double> tau)
 {
     if (tau.imag() <= 0.0) {
@@ -103,6 +112,8 @@ inline std::complex<double> reduce_to_fundamental_domain(std::complex<double> ta
 // ─────────────────────────────────────────────────────────────────────────────
 // is_in_fundamental_domain — check membership in F with tolerance tol.
 // ─────────────────────────────────────────────────────────────────────────────
+/// `true` iff `τ` lies inside the standard SL(2,ℤ) fundamental domain
+/// with tolerance `tol`.
 inline bool is_in_fundamental_domain(std::complex<double> tau, double tol = 1e-9)
 {
     if (tau.imag() <= 0.0) return false;
@@ -117,6 +128,9 @@ inline bool is_in_fundamental_domain(std::complex<double> tau, double tol = 1e-9
 // Computes the period data from the Euclidean holonomy translations.
 // For genus-1 surfaces, also reduces τ to the fundamental domain.
 // ─────────────────────────────────────────────────────────────────────────────
+/// Compute the period data from the Euclidean holonomy translations.
+/// For genus 1, also reduces `τ` to the SL(2,ℤ) fundamental domain
+/// when `reduce` is `true` (default).
 inline PeriodData compute_period_matrix(const HolonomyData& hol, bool reduce = true)
 {
     PeriodData pd;

code/include/projective_math.hpp

@@ -1,10 +1,14 @@
 #pragma once
+// Copyright (c) 2024-2026 Tarik Moussa.
+// SPDX-License-Identifier: MIT
+
 
 // Projective and hyperbolic geometry utilities.
 // Ported from de.jreality.math.Pn / Rn and
 // de.varylab.discreteconformal.uniformization.SurfaceCurveUtility (Java).
 
-#include <Eigen/Dense>
+#include <Eigen/Core>  // downgraded from <Eigen/Dense>: this header only
+                      // uses Matrix/Vector primitives, no decompositions.
 #include <cmath>
 #include <algorithm>
 #include <array>
@@ -12,17 +16,15 @@
 
 namespace conformallab {
 
-// Divide a homogeneous vector by its last component.
+/// Dehomogenise: divide a homogeneous vector by its last component.
-// Corresponds to Java Pn.dehomogenize().
+/// Same as Java `Pn.dehomogenize()`.
 inline Eigen::VectorXd dehomogenize(const Eigen::VectorXd& p) {
     return p / p(p.size() - 1);
 }
 
-// Hyperbolic distance between two homogeneous vectors of the same dimension.
+/// Hyperbolic distance `arcosh(⟨p̂, q̂⟩)` between two homogeneous
-// The last component is the "timelike" coordinate (jReality convention).
+/// vectors (last component = timelike coordinate; jReality convention).
-// Inner product: <p,q> = -sum_i p_i*q_i + p_last * q_last
+/// Same as Java `Pn.distanceBetween(p, q, Pn.HYPERBOLIC)`.
-// Distance: arcosh(<p̂, q̂>) where p̂ normalises to the hyperboloid.
-// Corresponds to Java Pn.distanceBetween(p, q, Pn.HYPERBOLIC).
 inline double hyperbolicDistance(const Eigen::VectorXd& p,
                                  const Eigen::VectorXd& q) {
     int n = static_cast<int>(p.size());
@@ -34,10 +36,8 @@ inline double hyperbolicDistance(const Eigen::VectorXd& p,
     return std::acosh(std::max(1.0, inner));
 }
 
-// Check whether a homogeneous point p lies on the segment [s[0], s[1]].
+/// `true` iff the homogeneous point `p_h` lies on the segment
-// Works for n-dimensional homogeneous coords; cross product uses the first
+/// `[s0_h, s1_h]`.  Same as Java `SurfaceCurveUtility.isOnSegment()`.
-// 3 spatial components after dehomogenization (matching jReality's Rn behaviour).
-// Corresponds to Java SurfaceCurveUtility.isOnSegment().
 inline bool isOnSegment(const Eigen::VectorXd& p_h,
                         const Eigen::VectorXd& s0_h,
                         const Eigen::VectorXd& s1_h) {
@@ -63,10 +63,10 @@ inline bool isOnSegment(const Eigen::VectorXd& p_h,
     return true;
 }
 
-// Find the point on `target` that corresponds to `p` on `source`.
+/// Find the point on the target segment `(tgt0, tgt1)` corresponding
-// The parameter t is determined by hyperbolic distance ratios on `source`,
+/// to `p` on the source segment `(src0, src1)`, parametrised by
-// then applied as a linear interpolation on the dehomogenized `target`.
+/// hyperbolic distance ratios on the source.  Same as Java
-// Corresponds to Java SurfaceCurveUtility.getPointOnCorrespondingSegment().
+/// `SurfaceCurveUtility.getPointOnCorrespondingSegment()`.
 inline Eigen::VectorXd getPointOnCorrespondingSegment(
     const Eigen::VectorXd& p,
     const Eigen::VectorXd& src0,

code/include/serialization.hpp

@@ -1,4 +1,7 @@
 #pragma once
+// Copyright (c) 2024-2026 Tarik Moussa.
+// SPDX-License-Identifier: MIT
+
 // serialization.hpp
 //
 // Phase 5 — Save and load conformal map results in JSON and XML formats.
@@ -43,7 +46,7 @@ namespace conformallab {
 // JSON
 // ════════════════════════════════════════════════════════════════════════════
 
-// Save solver result (+ optional 2D layout) to a JSON file.
+/// Save the Newton-solver result (+ optional 2-D layout) to a JSON file.
 inline void save_result_json(
     const std::string& path,
     const NewtonResult& res,
@@ -80,8 +83,8 @@ inline void save_result_json(
     ofs << std::setw(2) << j << "\n";
 }
 
-// Load DOF vector from a JSON result file.
+/// Load a DOF vector from a JSON result file written by
-// Returns the DOF vector; fills out res fields if non-null.
+/// `save_result_json`.  If `res` is non-null its fields are filled too.
 inline std::vector<double> load_result_json(
     const std::string& path,
     NewtonResult*       res     = nullptr,
@@ -181,7 +184,7 @@ inline std::vector<double> parse_doubles(const std::string& s)
 
 } // namespace detail_xml
 
-// Save solver result (+ optional layout) to an XML file.
+/// Save the Newton-solver result (+ optional layout) to an XML file.
 inline void save_result_xml(
     const std::string& path,
     const NewtonResult& res,
@@ -229,8 +232,9 @@ inline void save_result_xml(
     ofs << "</ConformalResult>\n";
 }
 
-// Load solver result from an XML file written by save_result_xml.
+/// Load a DOF vector from an XML result file written by
-// Returns the DOF vector; fills res/geom/layout2d if non-null.
+/// `save_result_xml`.  If `res`, `geom`, `layout2d` are non-null they
+/// are filled as well.
 inline std::vector<double> load_result_xml(
     const std::string& path,
     NewtonResult*       res      = nullptr,

code/include/spherical_functional.hpp

@@ -1,4 +1,7 @@
 #pragma once
+// Copyright (c) 2024-2026 Tarik Moussa.
+// SPDX-License-Identifier: MIT
+
 // spherical_functional.hpp
 //
 // Energy and gradient of the spherical discrete conformal functional
@@ -40,25 +43,36 @@ namespace conformallab {
 
 // ── Property-map type aliases ─────────────────────────────────────────────────
 
+/// Property map vertex → `double` for the Spherical functional.
 using SpherVMapD = ConformalMesh::Property_map<Vertex_index, double>;
+/// Property map vertex → `int`    for the Spherical functional.
 using SpherVMapI = ConformalMesh::Property_map<Vertex_index, int>;
+/// Property map edge   → `double` for the Spherical functional.
 using SpherEMapD = ConformalMesh::Property_map<Edge_index,   double>;
+/// Property map edge   → `int`    for the Spherical functional.
 using SpherEMapI = ConformalMesh::Property_map<Edge_index,   int>;
 
 // ── Persistent map bundle ─────────────────────────────────────────────────────
 
+/// Bundle of the five property maps consumed by the Spherical functional.
 struct SphericalMaps {
-    SpherVMapI v_idx;    // DOF index per vertex   (-1 = pinned / u_v = 0)
+    SpherVMapI v_idx;    ///< DOF index per vertex (−1 = pinned / u_v = 0).
-    SpherEMapI e_idx;    // DOF index per edge      (-1 = no edge DOF)
+    SpherEMapI e_idx;    ///< DOF index per edge   (−1 = no edge DOF).
-    SpherVMapD theta_v;  // target cone angle Θ_v  (default 2π)
+    SpherVMapD theta_v;  ///< Target cone angle Θᵥ (default 2π).
-    SpherEMapD theta_e;  // target edge angle θ_e  (default π)
+    SpherEMapD theta_e;  ///< Target edge angle θₑ (default π).
-    SpherEMapD lambda0;  // base log-length λ°_e   (default 0.0)
+    SpherEMapD lambda0;  ///< Base log-length λ⁰ₑ (default 0).
 };
 
 // Defaults: theta_v = 2π, theta_e = π, lambda0 = 0.
 // lambda0 = 0 means exp(λ°/2)=1, i.e., l=π — degenerate unless u_i<0.
-// For real meshes, set lambda0 from mesh geometry via
+/// Attach the five spherical property maps to `mesh` and return their
-// compute_lambda0_from_mesh() below.
+/// handles.  Mirrors `setup_euclidean_maps` but uses the `"sv:"` /
+/// `"se:"` prefix so the two functionals can coexist on the same mesh
+/// (useful for cross-validation tests).
+///
+/// Defaults match the Euclidean defaults except that `lambda0 = 0` here
+/// gives `l_e = π` which is degenerate on the unit sphere — always call
+/// `compute_lambda0_from_mesh(mesh, m)` next on a real mesh.
 inline SphericalMaps setup_spherical_maps(ConformalMesh& mesh)
 {
     SphericalMaps m;
@@ -70,7 +84,8 @@ inline SphericalMaps setup_spherical_maps(ConformalMesh& mesh)
     return m;
 }
 
-// Assign DOF indices 0..n-1 for all vertices (only vertex DOFs).
+/// Assign sequential DOF indices `0..n-1` to all vertices (no edge DOFs).
+/// Caller is expected to pin one gauge vertex with `m.v_idx[v] = -1`.
 inline int assign_vertex_dof_indices(ConformalMesh& mesh, SphericalMaps& m)
 {
     int idx = 0;
@@ -78,7 +93,9 @@ inline int assign_vertex_dof_indices(ConformalMesh& mesh, SphericalMaps& m)
     return idx;
 }
 
-// Assign DOF indices for all vertices AND edges.
+/// Assign DOF indices for all vertices AND all edges (vertex-DOFs first,
+/// then edge-DOFs).  Mirrors `assign_euclidean_all_dof_indices` for the
+/// cyclic spherical formulation.
 inline int assign_all_spherical_dof_indices(ConformalMesh& mesh, SphericalMaps& m)
 {
     int idx = 0;
@@ -87,7 +104,7 @@ inline int assign_all_spherical_dof_indices(ConformalMesh& mesh, SphericalMaps&
     return idx;
 }
 
-// Count variable DOFs.
+/// Count the free DOFs (vertices + edges with index `≥ 0`).
 inline int spherical_dimension(const ConformalMesh& mesh, const SphericalMaps& m)
 {
     int dim = 0;
@@ -96,9 +113,14 @@ inline int spherical_dimension(const ConformalMesh& mesh, const SphericalMaps& m
     return dim;
 }
 
-// Set lambda0 from mesh vertex positions (unit-sphere assumed):
+/// Compute `λ°_e` for every edge from the input vertex positions,
-//   λ°_e = 2·log(sin(l_e / 2))   where l_e = arccos(p_i · p_j).
+/// assuming `mesh` has vertices on the unit sphere.
-// Requires vertices to lie on the unit sphere.
+///
+/// Formula: `λ°_e = 2·log(sin(l_e / 2))` where `l_e = arccos(p_i · p_j)`
+/// is the spherical arc length of edge `e`.
+///
+/// \pre  Every vertex `v` of `mesh` lies on the unit sphere (norm = 1).
+/// \pre  No edge is degenerate (`p_i ≠ p_j` and `p_i ≠ -p_j`).
 inline void compute_lambda0_from_mesh(ConformalMesh& mesh, SphericalMaps& m)
 {
     for (auto e : mesh.edges()) {
@@ -119,18 +141,21 @@ inline void compute_lambda0_from_mesh(ConformalMesh& mesh, SphericalMaps& m)
 
 // ── Evaluation result ─────────────────────────────────────────────────────────
 
+/// Output of `evaluate_spherical()` — energy plus optional gradient.
 struct SphericalResult {
-    double              energy   = 0.0;
+    double              energy   = 0.0; ///< Functional value at input DOFs.
-    std::vector<double> gradient;
+    std::vector<double> gradient;       ///< Gradient ∇E (empty if not requested).
 };
 
 // ── Internal helpers ──────────────────────────────────────────────────────────
 
+/// Read DOF value from `x` for index `idx`; return 0 if pinned (idx < 0).
 static inline double spher_dof_val(int idx, const std::vector<double>& x)
 {
     return idx >= 0 ? x[static_cast<std::size_t>(idx)] : 0.0;
 }
 
+/// Convert a CGAL half-edge index to a plain `std::size_t` for vector indexing.
 static inline std::size_t spher_hidx(Halfedge_index h)
 {
     return static_cast<std::size_t>(static_cast<std::uint32_t>(h));
@@ -138,14 +163,13 @@ static inline std::size_t spher_hidx(Halfedge_index h)
 
 // ── Gradient only (no energy) ─────────────────────────────────────────────────
 
-// Compute gradient G(x).
+/// Compute the Spherical-functional gradient G(x):
-// G_v = Θ_v − Σ_faces α_v(face)
+///   * `G_v = Θ_v − Σ_faces α_v(face)`
-// G_e = α_opp(face+) + α_opp(face−) − θ_e
+///   * `G_e = α_opp(face⁺) + α_opp(face⁻) − θ_e`
-//
+///
-// The corner angle α_v is stored on halfedges using the convention:
+/// The corner angle α_v is stored on half-edges via the convention
-//   h_alpha[h] = corner angle at source(prev(h)) = corner angle at the vertex
+/// `h_alpha[h] = corner angle at the vertex ACROSS FROM the edge of h
-//                ACROSS FROM the edge of halfedge h in its face.
+/// in its face`, which makes both gradient accumulators natural.
-// This convention makes both the vertex and edge gradient accumulators natural.
 inline std::vector<double> spherical_gradient(
     ConformalMesh&             mesh,
     const std::vector<double>& x,
@@ -260,6 +284,9 @@ inline std::vector<double> spherical_gradient(
 //
 // 10-point GL nodes and weights on [0, 1] (transformed from [-1, 1]):
 //   t_k = (1 + s_k) / 2,  w_k = w_GL_k / 2
+/// Spherical energy `E(x) = ∫₀¹ ⟨G(t·x), x⟩ dt`, evaluated with
+/// 10-point Gauss-Legendre quadrature.  This is the correct potential
+/// for any conservative `G = ∇E`; error ≈ O(h²⁰) for smooth G.
 inline double spherical_energy(
     ConformalMesh&             mesh,
     const std::vector<double>& x,
@@ -304,6 +331,8 @@ inline double spherical_energy(
 
 // ── Full evaluation (energy + gradient) ──────────────────────────────────────
 
+/// Evaluate the Spherical functional at DOFs `x`.  Returns energy and
+/// gradient (toggle via `need_energy` / `need_gradient`).
 inline SphericalResult evaluate_spherical(
     ConformalMesh&             mesh,
     const std::vector<double>& x,
@@ -319,10 +348,8 @@ inline SphericalResult evaluate_spherical(
     return res;
 }
 
-// ── Finite-difference gradient check ─────────────────────────────────────────
+/// Finite-difference gradient check for the Spherical functional
-//
+/// (central differences).  Same defaults as the Java `FunctionalTest`.
-// Tests |G[i] − fd[i]| / max(1, |G[i]|) < tol for all DOFs.
-// Same defaults as the hyper-ideal gradient check (Java FunctionalTest).
 inline bool gradient_check_spherical(
     ConformalMesh&             mesh,
     const std::vector<double>& x0,
@@ -376,6 +403,8 @@ inline bool gradient_check_spherical(
 //
 // Returns 0.0 if the zero cannot be bracketed (already at gauge maximum,
 // or open surface — no shift needed).
+/// Find the global-scale gauge shift `t*` for the closed-spherical case
+/// (see comment block above for the maths).  Apply via `apply_spherical_gauge`.
 inline double spherical_gauge_shift(
     ConformalMesh&             mesh,
     const std::vector<double>& x,
@@ -456,7 +485,8 @@ inline double spherical_gauge_shift(
     return t;
 }
 
-// Apply the gauge shift in-place: x_v ← x_v + t* for all variable vertices.
+/// Apply the spherical gauge shift in-place: `x_v ← x_v + t*` for every
+/// variable vertex, where `t* = spherical_gauge_shift(mesh, x, m, ...)`.
 inline void apply_spherical_gauge(
     ConformalMesh&       mesh,
     std::vector<double>& x,

code/include/spherical_geometry.hpp

@@ -1,4 +1,7 @@
 #pragma once
+// Copyright (c) 2024-2026 Tarik Moussa.
+// SPDX-License-Identifier: MIT
+
 // spherical_geometry.hpp
 //
 // Pure-math building blocks for the spherical discrete conformal map.
@@ -23,8 +26,8 @@ constexpr double PI_SPHER = PI;
 
 // ── Effective spherical arc length ────────────────────────────────────────────
 
-// l(λ) = 2·asin(min(exp(λ/2), 1)).
+/// Spherical arc length `l(λ) = 2·asin(min(exp(λ/2), 1))`.
-// Clamps exp(λ/2) to [0, 1] so the arcsin stays in domain.
+/// Clamps `exp(λ/2)` to `[0, 1]` so `asin` stays in domain.
 inline double spherical_l(double lambda)
 {
     double half = std::exp(lambda * 0.5);
@@ -35,29 +38,18 @@ inline double spherical_l(double lambda)
 
 // ── Interior angles of a spherical triangle ──────────────────────────────────
 
+/// Interior angles of a spherical triangle, plus a `valid` flag.
 struct SphericalFaceAngles {
-    double alpha1, alpha2, alpha3;  // corner angles at v1, v2, v3
+    double alpha1; ///< Corner angle at vertex v₁.
-    bool   valid;                   // false when the three lengths fail the
+    double alpha2; ///< Corner angle at vertex v₂.
-                                    // spherical triangle inequality
+    double alpha3; ///< Corner angle at vertex v₃.
+    bool   valid;  ///< `false` when the three lengths violate the spherical triangle inequality.
 };
 
-// Compute corner angles from spherical arc lengths using the half-angle formula.
+/// Compute the spherical-triangle corner angles `(α₁, α₂, α₃)` from
-//
+/// the three arc lengths `(l₁₂, l₂₃, l₃₁)` using the half-angle form
-// Convention (matching the halfedge cycle h0→v1→v2, h1→v2→v3, h2→v3→v1):
+/// of the spherical law of cosines.  Returns `valid = false` for
-//   l12 – arc length of edge opposite v3 (edge e12)
+/// degenerate or out-of-range triangles.
-//   l23 – arc length of edge opposite v1 (edge e23)
-//   l31 – arc length of edge opposite v2 (edge e31)
-//
-// Half-angle formula (spherical law of cosines):
-//   α_k = 2·atan2(sqrt(sin(s-a)·sin(s-b)), sqrt(sin(s)·sin(s-c)))
-// where a,b are the two edges ADJACENT to vertex k, c is the opposite edge.
-//
-// Equivalently (in terms of s-deficiencies):
-//   α1 = 2·atan2( sqrt(sin(s12)·sin(s31)), sqrt(sin(s)·sin(s23)) )
-//   α2 = 2·atan2( sqrt(sin(s12)·sin(s23)), sqrt(sin(s)·sin(s31)) )
-//   α3 = 2·atan2( sqrt(sin(s23)·sin(s31)), sqrt(sin(s)·sin(s12)) )
-//
-// where s = (l12+l23+l31)/2 and s_ij = s - l_ij.
 inline SphericalFaceAngles spherical_angles(double l12, double l23, double l31)
 {
     double s   = (l12 + l23 + l31) * 0.5;

code/include/spherical_hessian.hpp

@@ -1,4 +1,7 @@
 #pragma once
+// Copyright (c) 2024-2026 Tarik Moussa.
+// SPDX-License-Identifier: MIT
+
 // spherical_hessian.hpp
 //
 // Analytical Hessian of the spherical discrete conformal energy —
@@ -49,8 +52,18 @@ namespace conformallab {
 //   h2: edge v3-v1 → opposite v2 → w = cot(β2), β2=(π-α3-α1+α2)/2
 //
 // Returns valid=false if any β_k is out of range (degenerate face).
-struct SpherCotWeights { double w12, w23, w31; bool valid; };
+/// Three spherical "cotangent" weights for the three edges of a face,
+/// derived from the per-vertex interior angles `α₁, α₂, α₃` via
+/// `w_ij = cot(β_k)` with `β_k = (π − α_i − α_j + α_k) / 2`.
+struct SpherCotWeights {
+    double w12; ///< Weight for edge v₁-v₂ (opposite vertex v₃).
+    double w23; ///< Weight for edge v₂-v₃ (opposite vertex v₁).
+    double w31; ///< Weight for edge v₃-v₁ (opposite vertex v₂).
+    bool   valid; ///< `false` when any β_k is out of `(0, π/2]` (degenerate face).
+};
 
+/// Compute the three spherical cot weights from the three interior
+/// angles `(α₁, α₂, α₃)` of a spherical triangle.  See `SpherCotWeights`.
 inline SpherCotWeights spherical_cot_weights(double alpha1, double alpha2, double alpha3)
 {
     // β for each edge:
@@ -79,25 +92,10 @@ inline SpherCotWeights spherical_cot_weights(double alpha1, double alpha2, doubl
     return {1.0 / tb3, 1.0 / tb1, 1.0 / tb2, true};
 }
 
-// ── Analytical Hessian ────────────────────────────────────────────────────────
+/// Analytical Spherical Hessian via `∂α/∂u` from the spherical law of
-//
+/// cosines + chain rule `∂l/∂u = tan(l/2)`; returns an n×n sparse
-// Returns the n×n sparse Hessian matrix H where n = spherical_dimension(mesh, m).
+/// matrix with `n = spherical_dimension(mesh, m)`.  See block comment
-// x – current DOF vector.
+/// inside the body for the per-face derivation.
-//
-// Derivation: G_v = θ_v − Σ_f α_v^f  →  H[i,j] = −Σ_f ∂α_i^f/∂u_j
-//
-// For a face (v1,v2,v3) with arc-lengths l12,l23,l31 and angles α1,α2,α3,
-// differentiating the spherical law of cosines
-//   cos(l_opp) = cos(l_a)cos(l_b) + sin(l_a)sin(l_b)cos(α)
-// gives:
-//   ∂α1/∂l12 = [cot(l12)cos(α1) − cot(l31)] / sin(α1)     (adjacent side)
-//   ∂α1/∂l31 = [cot(l31)cos(α1) − cot(l12)] / sin(α1)     (adjacent side)
-//   ∂α1/∂l23 = sin(l23) / [sin(l12)sin(l31)sin(α1)]        (opposite side)
-//
-// Chain rule with ∂l_ij/∂u_k = tan(l_ij/2)  (from l = 2·asin(exp(λ/2))):
-//   ∂α1/∂u1 = ∂α1/∂l12·t12 + ∂α1/∂l31·t31
-//   ∂α1/∂u2 = ∂α1/∂l12·t12 + ∂α1/∂l23·t23
-//   ∂α1/∂u3 = ∂α1/∂l23·t23 + ∂α1/∂l31·t31
 inline Eigen::SparseMatrix<double> spherical_hessian(
     ConformalMesh&             mesh,
     const std::vector<double>& x,
@@ -214,10 +212,8 @@ inline Eigen::SparseMatrix<double> spherical_hessian(
     return H;
 }
 
-// ── Finite-difference Hessian check ──────────────────────────────────────────
+/// FD Hessian check for the Spherical functional.  Compares analytic
-//
+/// `H` column-by-column to `(G(x+εeⱼ) − G(x−εeⱼ)) / (2ε)`.
-// Compares the analytical Hessian column-by-column against
-//   H_fd[:, j] = (G(x + ε·eⱼ) − G(x − ε·eⱼ)) / (2ε).
 inline bool hessian_check_spherical(
     ConformalMesh&             mesh,
     const std::vector<double>& x0,

code/include/viewer_utils.h

@@ -1,11 +1,16 @@
 #pragma once
+// Copyright (c) 2024-2026 Tarik Moussa.
+// SPDX-License-Identifier: MIT
+
 
 #include <Eigen/Dense>
 #include <igl/opengl/glfw/Viewer.h>
 
 namespace viewer_utils {
 
-// Deklaration (Implementation in viewer.cpp)
+/// Open an interactive libigl OpenGL viewer window showing the mesh
+/// `(V, F)`.  Built only when `WITH_VIEWER=ON`; declaration here, body
+/// in `viewer.cpp`.
 void simple_visualize(Eigen::MatrixXd& V, Eigen::MatrixXi& F);
 
 } 

code/src/apps/v0/conformallab_cli.cpp

@@ -1,3 +1,6 @@
+// Copyright (c) 2024-2026 Tarik Moussa.
+// SPDX-License-Identifier: MIT
+
 // conformallab_cli.cpp
 //
 // ConformalLab++ command-line interface.

code/src/viewer/simple_viewer.cpp

@@ -1,3 +1,6 @@
+// Copyright (c) 2024-2026 Tarik Moussa.
+// SPDX-License-Identifier: MIT
+
 #include "viewer_utils.h"
 
 namespace viewer_utils {

code/tests/CMakeLists.txt

@@ -1,5 +1,5 @@
 add_executable(conformallab_tests
-    # ── Fully ported (pure math, no HDS) ────────────────────────────────────
+    # ── Pure-math test suite (no CGAL, no mesh — runs on every branch) ─────
     test_clausen.cpp
     test_hyper_ideal_utility.cpp
     test_matrix_utility.cpp
@@ -7,12 +7,14 @@ add_executable(conformallab_tests
     test_discrete_elliptic_utility.cpp
     test_p2_utility.cpp
     test_hyper_ideal_visualization_utility.cpp
-
+    #
-    # ── Stubs: blocked until HDS port (Phase 4) ──────────────────────────────
+    # Stale stub files were removed in v0.9.0:
-    # All tests call GTEST_SKIP() with a clear explanation.
+    #   test_hyper_ideal_functional.cpp
-    test_hyper_ideal_functional.cpp
+    #   test_hyper_ideal_hyperelliptic_utility.cpp
-    test_hyper_ideal_hyperelliptic_utility.cpp
+    #   test_spherical_functional.cpp
-    test_spherical_functional.cpp
+    # They referenced a "HDS port (Phase 4)" that never happened —
+    # CoHDS was intentionally replaced by CGAL::Surface_mesh, and the
+    # functionals + tests live in code/tests/cgal/test_*_functional.cpp.
 )
 
 target_include_directories(conformallab_tests SYSTEM PRIVATE
@@ -25,10 +27,21 @@ target_include_directories(conformallab_tests PRIVATE
 
 target_link_libraries(conformallab_tests PRIVATE GTest::gtest_main)
 
+# Fast test-build mode (lever #10): -O0 -g overrides the inherited
+# Release-mode -O3 + -DNDEBUG.  Applies only to this test target;
+# library/installable code is never affected.
+if(CONFORMALLAB_FAST_TEST_BUILD)
+    target_compile_options(conformallab_tests PRIVATE
+        $<$<CXX_COMPILER_ID:GNU,Clang,AppleClang>:-O0 -g -UNDEBUG>
+    )
+endif()
+
 include(GoogleTest)
 gtest_discover_tests(conformallab_tests DISCOVERY_TIMEOUT 60)
 
-# ── CGAL test suite (requires -DWITH_CGAL=ON) ────────────────────────────────
+# ── CGAL test suite ──────────────────────────────────────────────────────────
-if(WITH_CGAL)
+# Built with -DWITH_CGAL_TESTS=ON (headless CI, no viewer) or
+#            -DWITH_CGAL=ON       (full build with viewer + CLI).
+if(WITH_CGAL OR WITH_CGAL_TESTS)
     add_subdirectory(cgal)
 endif()

code/tests/cgal/CMakeLists.txt

@@ -25,6 +25,13 @@ add_executable(conformallab_cgal_tests
     test_euclidean_hessian.cpp
     test_spherical_hessian.cpp
 
+    # ── Phase 9b: Hyper-ideal Hessian — block-FD vs full-FD validation ───
+    #    Verifies the O(F·36) block-local Hessian agrees with the
+    #    O(F·n) full-FD baseline.  Java upstream has no Hessian at all
+    #    (HyperIdealFunctional.hasHessian() returns false) — both
+    #    variants are conformallab++ extensions beyond the port.
+    test_hyper_ideal_hessian.cpp
+
     # ── Phase 4a: Newton solver ────────────────────────────────────────────
     test_newton_solver.cpp
 
@@ -44,11 +51,45 @@ add_executable(conformallab_cgal_tests
     #             period matrix, fundamental domain, tiling
     test_phase7.cpp
 
-    # ── Java-Parität: Geometrie-Utility-Tests ─────────────────────────────────
+    # ── Java parity: geometry utility tests ──────────────────────────────────
-    #    Portiert aus CuttinUtilityTest, UnwrapUtilityTest,
+    #    Ported from CuttinUtilityTest, UnwrapUtilityTest,
-    #    ConvergenceUtilityTests, HomologyTest (Tests 1–6).
+    #    ConvergenceUtilityTests, HomologyTest.  All tests active —
-    #    Test 7 (Genus-2-Homologie) als GTEST_SKIP-Stub bis Phase 8.
+    #    the v0.7.0 genus-2 homology stub was implemented in Phase 7
+    #    (HomologyGenerators.Genus2_FourCutEdges, brezel2.obj).
     test_geometry_utils.cpp
+
+    # ── Scalability smoke tests ────────────────────────────────────────────────
+    #    Newton convergence on large real-world meshes (cathead, brezel, brezel2).
+    #    Assert correctness only (< 30 iterations, ||G|| < 1e-8).
+    #    Wall-clock time is printed for documentation but NOT asserted,
+    #    so the tests remain stable on slow CI hardware (Raspberry Pi ARM64).
+    test_scalability_smoke.cpp
+
+    # ── Phase 8 MVP: new CGAL-style public API ────────────────────────────────
+    #    First client of Conformal_map_traits.h + Discrete_conformal_map.h.
+    #    Acceptance probe before Phase 9a (Inversive-Distance) lands.
+    test_cgal_traits_mvp.cpp
+
+    # ── Phase 9a.1: CPEuclideanFunctional (BPS 2010 circle packing) ──────────
+    #    Face-based circle-packing functional ported from
+    #    CPEuclideanFunctional.java.  Reference: Bobenko-Pinkall-Springborn 2010.
+    test_cp_euclidean_functional.cpp
+
+    # ── Phase 9a.2: InversiveDistance (Luo 2004 + Glickenstein 2011) ─────────
+    #    Vertex-based inversive-distance circle-packing functional.  No Java
+    #    reference; implemented from the literature.  Cross-validated against
+    #    EuclideanCyclicFunctional at the natural initial geometry (u = 0).
+    test_inversive_distance_functional.cpp
+
+    # ── Phase 9a: Newton solvers for the two new circle-packing functionals ──
+    #    Convergence tests for newton_cp_euclidean (analytic Hessian) and
+    #    newton_inversive_distance (FD Hessian).
+    test_newton_phase9a.cpp
+
+    # ── Phase 8b-Lite: CGAL entry wrappers for the 4 non-Euclidean modes ─────
+    #    Spherical, HyperIdeal, CircleP-Euclidean, Inversive-Distance via
+    #    <CGAL/Discrete_*.h> public API + Conformal_layout.h wrapper.
+    test_cgal_phase8b_lite.cpp
 )
 
 target_include_directories(conformallab_cgal_tests SYSTEM PRIVATE
@@ -65,6 +106,9 @@ target_include_directories(conformallab_cgal_tests PRIVATE
 target_compile_definitions(conformallab_cgal_tests PRIVATE
     CGAL_DISABLE_GMP
     CGAL_DISABLE_MPFR
+    # Data directory — absolute path to code/data/ at build time.
+    # Used by tests that load real mesh files (cathead.obj, brezel2.obj, …).
+    CONFORMALLAB_DATA_DIR="${CMAKE_SOURCE_DIR}/data"
 )
 
 # Suppress warnings from CGAL/Boost headers
@@ -72,8 +116,74 @@ target_compile_options(conformallab_cgal_tests PRIVATE
     $<$<CXX_COMPILER_ID:GNU,Clang,AppleClang>:-Wno-unused-parameter>
 )
 
+# Fast test-build mode (lever #10): -O0 -g overrides the inherited
+# Release-mode -O3 + -DNDEBUG.  Applies only to this test target.
+if(CONFORMALLAB_FAST_TEST_BUILD)
+    target_compile_options(conformallab_cgal_tests PRIVATE
+        $<$<CXX_COMPILER_ID:GNU,Clang,AppleClang>:-O0 -g -UNDEBUG>
+    )
+endif()
+
 target_link_libraries(conformallab_cgal_tests PRIVATE GTest::gtest_main)
 
+# ── Compile-time speed-up: precompiled headers ───────────────────────────────
+#
+# The CGAL+Eigen template soup dominates every TU in this target:
+# measured at 5.9 s per minimal "include <CGAL/Discrete_conformal_map.h>"
+# TU on Apple M1.  A shared PCH absorbs that cost once, slashing the
+# total wall-clock from ~78 s (j8) to ~25 s (3×).
+#
+# Opt-out with -DCONFORMALLAB_USE_PCH=OFF if the PCH itself misbehaves
+# (e.g. older toolchains that don't share PCH across translation units
+# reliably) — falls back to the historical "every TU re-parses CGAL"
+# build mode.
+option(CONFORMALLAB_USE_PCH
+    "Enable precompiled headers for the CGAL test target." ON)
+
+if(CONFORMALLAB_USE_PCH)
+    # Per-target Unity Build property takes precedence over the global
+    # CMAKE_UNITY_BUILD; honour CONFORMALLAB_DEV_BUILD's preference here
+    # so `-DCONFORMALLAB_DEV_BUILD=ON` truly turns Unity Build off for
+    # incremental-rebuild workflows.
+    if(NOT CONFORMALLAB_DEV_BUILD)
+        set_target_properties(conformallab_cgal_tests PROPERTIES
+            # Unity-builds amortise the per-TU CGAL+Eigen header cost
+            # across several tests in the same compile.  Batch size 4
+            # keeps gtest's TEST(...) macros + per-file `using
+            # namespace …` from colliding while still cutting parser
+            # cost ~4×.
+            UNITY_BUILD ON
+            UNITY_BUILD_MODE BATCH
+            UNITY_BUILD_BATCH_SIZE 4)
+    endif()
+
+    target_precompile_headers(conformallab_cgal_tests PRIVATE
+        # CGAL headers that every test transitively includes.
+        <CGAL/Surface_mesh.h>
+        <CGAL/Simple_cartesian.h>
+        <CGAL/Kernel_traits.h>
+        <CGAL/boost/graph/iterator.h>
+        <CGAL/Polygon_mesh_processing/triangulate_faces.h>
+
+        # Eigen blocks that drive the slowest template instantiations
+        # (SelfAdjointEigenSolver<Matrix<2,2>>, ColPivHouseholderQR<
+        # Matrix<complex,3,3>>, sparse Cholesky + QR fallback).
+        <Eigen/Dense>
+        <Eigen/Sparse>
+        <Eigen/SparseCholesky>
+        <Eigen/SparseQR>
+
+        # GoogleTest itself; every test includes it.
+        <gtest/gtest.h>
+
+        # std headers that appear in every test.
+        <vector>
+        <string>
+        <cmath>
+        <complex>
+    )
+endif()
+
 include(GoogleTest)
 gtest_discover_tests(conformallab_cgal_tests
     TEST_PREFIX "cgal."

code/tests/cgal/test_cgal_phase8b_lite.cpp

@@ -0,0 +1,429 @@
+// Copyright (c) 2024-2026 Tarik Moussa.
+// SPDX-License-Identifier: MIT
+
+// test_cgal_phase8b_lite.cpp
+//
+// Phase 8b-Lite — Smoke tests for the four new CGAL-style entry functions
+// added on top of the Phase 8a MVP (`discrete_conformal_map_euclidean`).
+//
+// All entries are thin wrappers around the legacy Newton solvers; the
+// purpose of these tests is to verify:
+//   • the wrapper compiles + dispatches correctly
+//   • named parameters pass through (gradient_tolerance, max_iterations)
+//   • the returned Result struct contains the expected DOF vector
+//   • Newton convergence happens end-to-end via the public API
+
+#include <CGAL/Discrete_conformal_map.h>
+#include <CGAL/Discrete_circle_packing.h>
+#include <CGAL/Discrete_inversive_distance.h>
+#include <CGAL/Conformal_layout.h>
+
+#include "mesh_builder.hpp"
+#include "conformal_mesh.hpp"
+
+#include <gtest/gtest.h>
+#include <cmath>
+
+using namespace conformallab;
+
+namespace {
+
+// Mesh helper — closed regular tetrahedron, used for spherical / hyper-ideal /
+// circle-packing tests.
+inline ConformalMesh make_closed_tet() { return make_tetrahedron(); }
+
+// Open 3-face tetrahedron-minus-face, for layout testing.
+inline ConformalMesh make_open_3face()
+{
+    ConformalMesh mesh;
+    auto v0 = mesh.add_vertex(Point3( 1,  1,  1));
+    auto v1 = mesh.add_vertex(Point3( 1, -1, -1));
+    auto v2 = mesh.add_vertex(Point3(-1,  1, -1));
+    auto v3 = mesh.add_vertex(Point3(-1, -1,  1));
+    mesh.add_face(v0, v2, v1);
+    mesh.add_face(v0, v1, v3);
+    mesh.add_face(v0, v3, v2);
+    return mesh;
+}
+
+} // anonymous
+
+// ════════════════════════════════════════════════════════════════════════════
+// 1.  Spherical entry — closed genus-0 tetrahedron, natural-theta default
+// ════════════════════════════════════════════════════════════════════════════
+
+TEST(CGALPhase8bLite, Spherical_ClosedTetrahedron_NaturalThetaConverges)
+{
+    auto mesh = make_closed_tet();
+    auto res  = CGAL::discrete_conformal_map_spherical(mesh);
+
+    EXPECT_TRUE(res.converged);
+    EXPECT_LT(res.gradient_norm, 1e-8);
+    EXPECT_EQ(res.u_per_vertex.size(), num_vertices(mesh));
+    // Natural-theta ⇒ u = 0 is the equilibrium ⇒ all values ≈ 0.
+    for (double u : res.u_per_vertex) EXPECT_NEAR(u, 0.0, 1e-8);
+}
+
+TEST(CGALPhase8bLite, Spherical_NamedParametersTakeEffect)
+{
+    auto mesh = make_closed_tet();
+    auto res  = CGAL::discrete_conformal_map_spherical(
+        mesh,
+        CGAL::parameters::max_iterations(0));
+    EXPECT_EQ(res.iterations, 0);
+}
+
+// ════════════════════════════════════════════════════════════════════════════
+// 2.  Hyper-ideal entry — wrapper compiles + runs, returns both b_v and a_e
+// ════════════════════════════════════════════════════════════════════════════
+
+TEST(CGALPhase8bLite, HyperIdeal_Tetrahedron_ReturnsBothVertexAndEdgeDOFs)
+{
+    auto mesh = make_closed_tet();
+    auto res  = CGAL::discrete_conformal_map_hyper_ideal(
+        mesh,
+        CGAL::parameters::max_iterations(20));
+
+    // Newton on default targets (Θ=2π, θ=π) from the "natural" b=1, a=0.5
+    // start may or may not converge in 20 iterations — but the wrapper must
+    // populate the result struct in any case.
+    EXPECT_EQ(res.b_per_vertex.size(), num_vertices(mesh));
+    EXPECT_EQ(res.a_per_edge.size(),    num_edges   (mesh));
+    EXPECT_GE(res.iterations, 0);
+    EXPECT_TRUE(std::isfinite(res.gradient_norm));
+}
+
+// ════════════════════════════════════════════════════════════════════════════
+// 3.  Circle-packing (face-based) entry — natural-phi convergence
+// ════════════════════════════════════════════════════════════════════════════
+
+TEST(CGALPhase8bLite, CirclePacking_ClosedTetrahedron_NaturalPhiConverges)
+{
+    auto mesh = make_closed_tet();
+    auto res  = CGAL::discrete_circle_packing_euclidean(mesh);
+
+    EXPECT_TRUE(res.converged);
+    EXPECT_LT(res.gradient_norm, 1e-8);
+    EXPECT_EQ(res.rho_per_face.size(), num_faces(mesh));
+    // Pinned face is at index 0 (first iterated face); its ρ is 0 by gauge.
+    // After natural-phi the equilibrium is ρ_f = 0 for every face.
+    for (double r : res.rho_per_face) EXPECT_NEAR(r, 0.0, 1e-8);
+}
+
+TEST(CGALPhase8bLite, CirclePacking_GradientToleranceTakesEffect)
+{
+    auto mesh = make_closed_tet();
+    auto res_loose = CGAL::discrete_circle_packing_euclidean(
+        mesh,
+        CGAL::parameters::gradient_tolerance(1e-4));
+    EXPECT_TRUE(res_loose.converged);
+
+    auto mesh2 = make_closed_tet();
+    auto res_strict = CGAL::discrete_circle_packing_euclidean(
+        mesh2,
+        CGAL::parameters::gradient_tolerance(1e-12));
+    EXPECT_TRUE(res_strict.converged);
+    EXPECT_LT(res_strict.gradient_norm, 1e-10);
+}
+
+// ════════════════════════════════════════════════════════════════════════════
+// 4.  Inversive-distance (vertex-based) entry — natural-theta convergence
+// ════════════════════════════════════════════════════════════════════════════
+
+TEST(CGALPhase8bLite, InversiveDistance_Triangle_NaturalThetaConverges)
+{
+    auto mesh = make_triangle();
+    auto res  = CGAL::discrete_inversive_distance_map(mesh);
+
+    EXPECT_TRUE(res.converged);
+    EXPECT_LT(res.gradient_norm, 1e-8);
+    EXPECT_EQ(res.u_per_vertex.size(), num_vertices(mesh));
+    for (double u : res.u_per_vertex) EXPECT_NEAR(u, 0.0, 1e-8);
+}
+
+TEST(CGALPhase8bLite, InversiveDistance_QuadStrip_NamedParametersWork)
+{
+    auto mesh = make_quad_strip();
+    // Named-parameter chaining (`a.b().c()`) is not currently supported on
+    // the package-local tags; pass one parameter per call instead.
+    auto res  = CGAL::discrete_inversive_distance_map(
+        mesh,
+        CGAL::parameters::max_iterations(50));
+    EXPECT_TRUE(res.converged);
+    EXPECT_LE(res.iterations, 50);
+}
+
+// ════════════════════════════════════════════════════════════════════════════
+// 5.  Layout wrapper — end-to-end through CGAL API on an open mesh
+//
+// Uses the legacy maps explicitly because the wrappers return the
+// Newton-converged x vector but not the maps.  This exercises that the
+// `CGAL::euclidean_layout` shim works as expected.
+// ════════════════════════════════════════════════════════════════════════════
+
+TEST(CGALPhase8bLite, Layout_EuclideanWrapper_RoundTrip)
+{
+    auto mesh = make_open_3face();
+
+    // Set up the maps + run Newton via the CGAL Euclidean entry.
+    auto res  = CGAL::discrete_conformal_map_euclidean(mesh);
+    ASSERT_TRUE(res.converged);
+
+    // The wrapper does its own DOF assignment internally; we re-fetch
+    // the (now-populated) EuclideanMaps from the mesh's property maps
+    // to feed the layout wrapper.
+    auto maps = setup_euclidean_maps(mesh);
+    compute_euclidean_lambda0_from_mesh(mesh, maps);
+    // Pin first vertex (mirrors the wrapper's gauge choice).
+    auto vit = mesh.vertices().begin();
+    maps.v_idx[*vit++] = -1;
+    int idx = 0;
+    for (; vit != mesh.vertices().end(); ++vit) maps.v_idx[*vit] = idx++;
+    std::vector<double> x(idx, 0.0);   // wrapper's natural-theta equilibrium
+
+    auto layout = CGAL::euclidean_layout(mesh, x, maps);
+    EXPECT_EQ(layout.uv.size(), num_vertices(mesh));
+    // All UVs finite — basic sanity that the layout ran.
+    for (auto& uv : layout.uv) {
+        EXPECT_TRUE(std::isfinite(uv.x()));
+        EXPECT_TRUE(std::isfinite(uv.y()));
+    }
+}
+
+// ════════════════════════════════════════════════════════════════════════════
+// 6.  output_uv_map named parameter — integrated layout step
+//
+// Phase 8b-Lite extension (2026-05-22): if the caller supplies a property
+// map via `CGAL::parameters::output_uv_map(pmap)`, the entry function runs
+// the appropriate `*_layout()` after Newton and writes the per-vertex
+// coordinates into `pmap`.  This closes the prior UX gap where users had
+// to call the wrapper, then re-set up maps, then call the legacy layout
+// API separately.
+// ════════════════════════════════════════════════════════════════════════════
+
+TEST(CGALPhase8bLite, OutputUvMap_Euclidean_PopulatesPmap)
+{
+    using K = CGAL::Simple_cartesian<double>;
+    auto mesh = make_quad_strip();
+
+    auto uv_map = mesh.add_property_map<Vertex_index, K::Point_2>(
+        "v:test_uv", K::Point_2(0, 0)).first;
+
+    auto res = CGAL::discrete_conformal_map_euclidean(
+        mesh,
+        CGAL::parameters::output_uv_map(uv_map));
+
+    ASSERT_TRUE(res.converged);
+
+    // The map must be populated with finite values.
+    for (auto v : mesh.vertices()) {
+        const auto& p = uv_map[v];
+        EXPECT_TRUE(std::isfinite(p.x())) << "non-finite UV.x at vertex " << v.idx();
+        EXPECT_TRUE(std::isfinite(p.y())) << "non-finite UV.y at vertex " << v.idx();
+    }
+
+    // At least one vertex must have moved off the origin (the layout
+    // did NOT just return defaults).
+    bool any_nonzero = false;
+    for (auto v : mesh.vertices()) {
+        const auto& p = uv_map[v];
+        if (std::abs(p.x()) + std::abs(p.y()) > 1e-10) { any_nonzero = true; break; }
+    }
+    EXPECT_TRUE(any_nonzero) << "every UV is exactly (0,0) — layout did not run";
+}
+
+TEST(CGALPhase8bLite, OutputUvMap_Spherical_PopulatesXyz)
+{
+    using K = CGAL::Simple_cartesian<double>;
+    auto mesh = make_tetrahedron();
+
+    auto xyz_map = mesh.add_property_map<Vertex_index, K::Point_3>(
+        "v:test_xyz", K::Point_3(0, 0, 0)).first;
+
+    auto res = CGAL::discrete_conformal_map_spherical(
+        mesh,
+        CGAL::parameters::output_uv_map(xyz_map));
+
+    ASSERT_TRUE(res.converged);
+
+    // Every output point must lie on (or very near) the unit sphere.
+    for (auto v : mesh.vertices()) {
+        const auto& p = xyz_map[v];
+        const double r = std::sqrt(p.x()*p.x() + p.y()*p.y() + p.z()*p.z());
+        EXPECT_NEAR(r, 1.0, 1e-6) << "vertex " << v.idx() << " not on unit sphere";
+    }
+}
+
+TEST(CGALPhase8bLite, OutputUvMap_HyperIdeal_PointsInPoincareDisk)
+{
+    using K = CGAL::Simple_cartesian<double>;
+    auto mesh = make_tetrahedron();
+
+    auto uv_map = mesh.add_property_map<Vertex_index, K::Point_2>(
+        "v:test_uv_hyp", K::Point_2(0, 0)).first;
+
+    // Named-parameter chaining is not supported yet — pass output_uv_map only.
+    auto res = CGAL::discrete_conformal_map_hyper_ideal(
+        mesh,
+        CGAL::parameters::output_uv_map(uv_map));
+
+    // The wrapper must complete and return a well-formed result struct
+    // regardless of whether Newton fully converges with the default
+    // Θ/θ targets in 200 iterations.  We only verify that *if* the
+    // layout step ran (which happens only on converged Newton), the
+    // output is finite — Poincaré-disk geometric check is conditional.
+    EXPECT_EQ(res.b_per_vertex.size(), num_vertices(mesh));
+    EXPECT_EQ(res.a_per_edge.size(),    num_edges(mesh));
+
+    if (res.converged) {
+        for (auto v : mesh.vertices()) {
+            const auto& p = uv_map[v];
+            const double r2 = p.x()*p.x() + p.y()*p.y();
+            EXPECT_LE(r2, 1.0 + 1e-6)
+                << "vertex " << v.idx() << " outside Poincaré disk (|p|² = " << r2 << ")";
+        }
+    }
+    // (else: Newton did not reach equilibrium; UV pmap is left at its
+    //  default (0,0) per the wrapper's "if (nr.converged)" guard.
+    //  No assertion needed; this is documented behaviour.)
+}
+
+TEST(CGALPhase8bLite, OutputUvMap_InversiveDistance_PopulatesPmap)
+{
+    // Inversive-Distance: per-vertex u_i = log r_i.  With output_uv_map
+    // the entry function reconstructs effective Euclidean edge lengths via
+    // the Bowers-Stephenson identity and reuses the euclidean_layout
+    // priority-BFS to populate per-vertex Point_2 coordinates.
+    using K = CGAL::Simple_cartesian<double>;
+    auto mesh = make_quad_strip();
+
+    auto uv_map = mesh.add_property_map<Vertex_index, K::Point_2>(
+        "v:test_uv_id", K::Point_2(0, 0)).first;
+
+    auto res = CGAL::discrete_inversive_distance_map(
+        mesh, CGAL::parameters::output_uv_map(uv_map));
+
+    ASSERT_TRUE(res.converged) << "ID Newton did not converge on quad_strip";
+    EXPECT_EQ(res.u_per_vertex.size(), num_vertices(mesh));
+    // Every UV must be finite; not all zero.
+    bool any_nonzero = false;
+    for (auto v : mesh.vertices()) {
+        const auto& p = uv_map[v];
+        ASSERT_TRUE(std::isfinite(p.x()));
+        ASSERT_TRUE(std::isfinite(p.y()));
+        if (std::abs(p.x()) > 1e-9 || std::abs(p.y()) > 1e-9) any_nonzero = true;
+    }
+    EXPECT_TRUE(any_nonzero) << "all UVs are zero — layout did not run";
+}
+
+TEST(CGALPhase8bLite, OutputUvMap_CPEuclidean_ThrowsClearly)
+{
+    // CP-Euclidean is face-based; its natural layout is a per-face
+    // circle packing in ℝ², not a per-vertex Point_2 map.  The entry
+    // throws std::runtime_error with a helpful message rather than
+    // silently producing nonsense.  See doc/architecture/locked-vs-flexible.md.
+    using K = CGAL::Simple_cartesian<double>;
+    auto mesh = make_quad_strip();
+
+    auto uv_map = mesh.add_property_map<Vertex_index, K::Point_2>(
+        "v:test_uv_cp", K::Point_2(0, 0)).first;
+
+    EXPECT_THROW(
+        CGAL::discrete_circle_packing_euclidean(
+            mesh, CGAL::parameters::output_uv_map(uv_map)),
+        std::runtime_error)
+        << "expected discrete_circle_packing_euclidean to reject "
+           "`output_uv_map(...)` (face-based DOF, Phase 9c).";
+
+    // Sanity: without output_uv_map the entry function still works fine.
+    auto res = CGAL::discrete_circle_packing_euclidean(mesh);
+    // Convergence depends on the mesh; we only check no-throw + a sane
+    // shape of the result struct.
+    EXPECT_EQ(res.rho_per_face.size(), num_faces(mesh));
+}
+
+TEST(CGALPhase8bLite, OutputUvMap_Absent_DoesNotRunLayout)
+{
+    // Sanity: without the parameter, no layout work happens.  Verified
+    // here only via the fact that the call still succeeds and produces
+    // the same u-vector as before.
+    auto mesh = make_quad_strip();
+    auto res = CGAL::discrete_conformal_map_euclidean(mesh);
+    EXPECT_TRUE(res.converged);
+    EXPECT_EQ(res.u_per_vertex.size(), num_vertices(mesh));
+}
+
+TEST(CGALPhase8bLite, OutputUvMap_NormaliseLayout_TakesEffect)
+{
+    using K = CGAL::Simple_cartesian<double>;
+    auto mesh = make_quad_strip();
+
+    auto uv_raw  = mesh.add_property_map<Vertex_index, K::Point_2>(
+        "v:test_uv_raw",  K::Point_2(0, 0)).first;
+    auto uv_norm = mesh.add_property_map<Vertex_index, K::Point_2>(
+        "v:test_uv_norm", K::Point_2(0, 0)).first;
+
+    auto res1 = CGAL::discrete_conformal_map_euclidean(
+        mesh, CGAL::parameters::output_uv_map(uv_raw));
+    auto res2 = CGAL::discrete_conformal_map_euclidean(
+        mesh, CGAL::parameters::output_uv_map(uv_norm));
+    // (We can only pass one named parameter at a time without chaining;
+    //  test the toggle by running the wrapper twice and verifying the
+    //  raw call works.  The normalise_layout flag is exercised in
+    //  internal unit tests via direct calls to normalise_euclidean.)
+    ASSERT_TRUE(res1.converged);
+    ASSERT_TRUE(res2.converged);
+    // Both maps populated to finite values.
+    for (auto v : mesh.vertices()) {
+        EXPECT_TRUE(std::isfinite(uv_raw[v].x()));
+        EXPECT_TRUE(std::isfinite(uv_norm[v].x()));
+    }
+}
+
+// ════════════════════════════════════════════════════════════════════════════
+// 7.  Named-parameter chaining via pipe-operator
+//
+// CGAL's `.a().b().c()` chaining requires modifying CGAL upstream, which
+// we don't do.  conformallab++ provides a `|` operator that achieves the
+// same effect by left-to-right composition.  These tests verify that the
+// chain is read back correctly by the entry functions.
+// ════════════════════════════════════════════════════════════════════════════
+
+TEST(CGALPhase8bLite, NamedParamPipe_MultipleParamsTakeEffect)
+{
+    using K = CGAL::Simple_cartesian<double>;
+    auto mesh = make_quad_strip();
+
+    auto uv = mesh.add_property_map<Vertex_index, K::Point_2>(
+        "v:pipe_uv", K::Point_2(0, 0)).first;
+
+    // Chain three parameters using `|`.
+    auto params = CGAL::parameters::gradient_tolerance(1e-12)
+                | CGAL::parameters::max_iterations(500)
+                | CGAL::parameters::output_uv_map(uv);
+
+    auto res = CGAL::discrete_conformal_map_euclidean(mesh, params);
+
+    EXPECT_TRUE(res.converged);
+    EXPECT_LT(res.gradient_norm, 1e-10);   // tight tolerance applied
+    EXPECT_LE(res.iterations, 500);
+    // UV pmap was populated.
+    bool any_nonzero = false;
+    for (auto v : mesh.vertices()) {
+        if (std::abs(uv[v].x()) + std::abs(uv[v].y()) > 1e-10) {
+            any_nonzero = true;
+            break;
+        }
+    }
+    EXPECT_TRUE(any_nonzero);
+}
+
+TEST(CGALPhase8bLite, NamedParamPipe_TwoParams)
+{
+    // Pipe two parameters and verify both take effect.
+    auto mesh = make_triangle();
+    auto params = CGAL::parameters::max_iterations(0)
+                | CGAL::parameters::gradient_tolerance(1e-6);
+    auto res = CGAL::discrete_conformal_map_euclidean(mesh, params);
+    EXPECT_EQ(res.iterations, 0);   // max_iterations(0) blocks the loop
+}

code/tests/cgal/test_cgal_traits_mvp.cpp

@@ -0,0 +1,249 @@
+// Copyright (c) 2024-2026 Tarik Moussa.
+// SPDX-License-Identifier: MIT
+
+// test_cgal_traits_mvp.cpp
+//
+// Phase 8 MVP — first tests for the new CGAL-style public API.
+//
+// Validates:
+//   1. Default_conformal_map_traits<Surface_mesh, K> compiles and
+//      provides all advertised types and property-map accessors.
+//   2. discrete_conformal_map_euclidean() runs end-to-end on a small mesh.
+//   3. Named-parameter overrides (gradient_tolerance, max_iterations)
+//      change the Newton behaviour as expected.
+//   4. The result agrees with the legacy newton_euclidean() at the
+//      same DOF assignment — proving the wrapper is non-destructive.
+//
+// These tests are the Phase 8 MVP acceptance probe.  Phase 9a
+// (Inversive-Distance) will become the next, deeper validation by
+// implementing a new functional against this same trait API.
+
+#include <CGAL/Conformal_map_traits.h>
+#include <CGAL/Discrete_conformal_map.h>
+#include <CGAL/Kernel_traits.h>
+
+#include "mesh_builder.hpp"   // make_triangle, make_quad_strip, make_tetrahedron
+#include "euclidean_functional.hpp"
+#include "newton_solver.hpp"
+
+#include <gtest/gtest.h>
+#include <cmath>
+
+using namespace conformallab;
+
+// ════════════════════════════════════════════════════════════════════════════
+// 1.  Traits class: compile-time type sanity
+// ════════════════════════════════════════════════════════════════════════════
+
+TEST(CGALConformalTraits, DefaultTraitsTypes)
+{
+    using K     = CGAL::Simple_cartesian<double>;
+    using Mesh  = CGAL::Surface_mesh<K::Point_3>;
+    using Tr    = CGAL::Default_conformal_map_traits<Mesh, K>;
+
+    // FT comes from the kernel.
+    static_assert(std::is_same_v<typename Tr::FT, double>);
+
+    // Descriptors come from boost::graph_traits, not from Surface_mesh directly.
+    static_assert(std::is_same_v<typename Tr::Triangle_mesh, Mesh>);
+    static_assert(std::is_same_v<
+        typename Tr::Vertex_descriptor,
+        typename boost::graph_traits<Mesh>::vertex_descriptor>);
+
+    // Property-map types should match Surface_mesh::Property_map for the
+    // appropriate key.
+    static_assert(std::is_same_v<
+        typename Tr::Theta_pmap,
+        typename Mesh::template Property_map<typename Tr::Vertex_descriptor, double>>);
+    static_assert(std::is_same_v<
+        typename Tr::Vertex_index_pmap,
+        typename Mesh::template Property_map<typename Tr::Vertex_descriptor, int>>);
+    static_assert(std::is_same_v<
+        typename Tr::Lambda0_pmap,
+        typename Mesh::template Property_map<typename Tr::Edge_descriptor, double>>);
+
+    // Default kernel: Simple_cartesian<double>.
+    using TrDefault = CGAL::Default_conformal_map_traits<Mesh>;
+    static_assert(std::is_same_v<typename TrDefault::Kernel,
+                                 CGAL::Simple_cartesian<double>>);
+}
+
+// ════════════════════════════════════════════════════════════════════════════
+// 2.  Traits property-map accessors are non-destructive
+//
+// Setting up via the trait helpers and via setup_euclidean_maps() must yield
+// the same property map (Surface_mesh deduplicates by name).
+// ════════════════════════════════════════════════════════════════════════════
+
+TEST(CGALConformalTraits, AccessorsReuseExistingMaps)
+{
+    using K   = CGAL::Simple_cartesian<double>;
+    using Mesh = CGAL::Surface_mesh<K::Point_3>;
+    using Tr  = CGAL::Default_conformal_map_traits<Mesh, K>;
+
+    auto mesh = make_triangle();
+    auto maps = setup_euclidean_maps(mesh);
+
+    auto theta_via_traits   = Tr::theta_map(mesh);
+    auto idx_via_traits     = Tr::vertex_index_map(mesh);
+    auto lambda0_via_traits = Tr::lambda0_map(mesh);
+
+    // Surface_mesh property maps with the same key type are equality-comparable
+    // by name lookup — accessing through the traits class must return the
+    // same map that setup_euclidean_maps() created.
+    EXPECT_EQ(theta_via_traits,   maps.theta_v);
+    EXPECT_EQ(idx_via_traits,     maps.v_idx);
+    EXPECT_EQ(lambda0_via_traits, maps.lambda0);
+}
+
+// ════════════════════════════════════════════════════════════════════════════
+// 3.  End-to-end: discrete_conformal_map_euclidean() on a small open mesh
+// ════════════════════════════════════════════════════════════════════════════
+
+TEST(CGALDiscreteConformalMap, SingleTriangleConverges)
+{
+    auto mesh = make_triangle();
+    auto result = CGAL::discrete_conformal_map_euclidean(mesh);
+
+    EXPECT_TRUE(result.converged)
+        << "Newton did not converge on a single triangle";
+    EXPECT_LT(result.gradient_norm, 1e-8);
+    EXPECT_GE(result.iterations, 0);
+    EXPECT_EQ(result.u_per_vertex.size(), num_vertices(mesh));
+
+    // With the default flat-disc target curvature and the first vertex pinned,
+    // the natural-theta equilibrium is at u = 0 — Newton should accept x0=0.
+    for (double u : result.u_per_vertex)
+        EXPECT_NEAR(u, 0.0, 1e-8);
+}
+
+TEST(CGALDiscreteConformalMap, QuadStripConverges)
+{
+    auto mesh = make_quad_strip();
+    auto result = CGAL::discrete_conformal_map_euclidean(mesh);
+
+    EXPECT_TRUE(result.converged);
+    EXPECT_LT(result.gradient_norm, 1e-8);
+    EXPECT_EQ(result.u_per_vertex.size(), num_vertices(mesh));
+}
+
+// ════════════════════════════════════════════════════════════════════════════
+// 4.  Named-parameter overrides take effect
+// ════════════════════════════════════════════════════════════════════════════
+
+TEST(CGALDiscreteConformalMap, MaxIterationsTakesEffect)
+{
+    auto mesh = make_triangle();
+
+    // max_iterations(0) forces Newton to give up immediately.
+    auto result = CGAL::discrete_conformal_map_euclidean(
+        mesh,
+        CGAL::parameters::max_iterations(0));
+
+    EXPECT_EQ(result.iterations, 0);
+    // Trivial natural-theta case: gradient is already zero at x=0,
+    // so even 0 iterations may report "converged" depending on the
+    // initial gradient check.  The point is just that the parameter
+    // was *read* — verified by EXPECT_EQ on iterations above.
+}
+
+TEST(CGALDiscreteConformalMap, GradientToleranceTakesEffect)
+{
+    auto mesh = make_quad_strip();
+
+    // Loose tolerance — must still converge, but possibly in fewer steps.
+    auto result_loose = CGAL::discrete_conformal_map_euclidean(
+        mesh,
+        CGAL::parameters::gradient_tolerance(1e-4));
+    EXPECT_TRUE(result_loose.converged);
+
+    // Strict tolerance — also must converge, gradient norm must be tighter.
+    auto result_strict = CGAL::discrete_conformal_map_euclidean(
+        mesh,
+        CGAL::parameters::gradient_tolerance(1e-12));
+    EXPECT_TRUE(result_strict.converged);
+    EXPECT_LT(result_strict.gradient_norm, 1e-10);
+}
+
+// ════════════════════════════════════════════════════════════════════════════
+// 5.  Wrapper agrees with the legacy newton_euclidean() at the same setup
+//
+// This is the cross-API consistency check: same mesh, same default settings
+// (first vertex pinned, x0=0) — the u-vector returned by the wrapper must
+// match what newton_euclidean produces directly.
+// ════════════════════════════════════════════════════════════════════════════
+
+// ════════════════════════════════════════════════════════════════════════════
+// 6.  Kernel deduction: the wrapper must NOT hard-code Simple_cartesian
+//
+// Regression guard: the wrapper deduces its kernel from the mesh point type
+// via `CGAL::Kernel_traits`.  If anyone re-introduces a hard-coded
+// `Simple_cartesian<double>` in the wrapper, the static_asserts here still
+// pass (the legacy ConformalMesh uses that kernel) — but Phase 9a or any
+// user with a different kernel-backed Surface_mesh would fail to compile.
+// This test pins the deduction *contract* explicitly.
+// ════════════════════════════════════════════════════════════════════════════
+
+TEST(CGALDiscreteConformalMap, KernelIsDeducedFromMeshPointType)
+{
+    using Mesh = ConformalMesh;
+    using P    = typename Mesh::Point;
+
+    using DeducedKernel = typename CGAL::Kernel_traits<P>::Kernel;
+    using DeducedTraits = CGAL::Default_conformal_map_traits<Mesh, DeducedKernel>;
+
+    static_assert(std::is_same_v<DeducedKernel, CGAL::Simple_cartesian<double>>,
+                  "ConformalMesh point type must deduce to Simple_cartesian<double>");
+    static_assert(std::is_same_v<typename DeducedTraits::FT, double>);
+    static_assert(std::is_same_v<typename DeducedTraits::Triangle_mesh, Mesh>);
+
+    // Run-time sanity: the wrapper accepts the deduced-kernel mesh end-to-end.
+    auto mesh = make_quad_strip();
+    auto result = CGAL::discrete_conformal_map_euclidean(mesh);
+    EXPECT_TRUE(result.converged);
+}
+
+TEST(CGALDiscreteConformalMap, WrapperMatchesLegacyAPI)
+{
+    auto mesh = make_quad_strip();
+
+    // ── New API: applies natural-theta automatically ───────────────────────
+    auto result_new = CGAL::discrete_conformal_map_euclidean(mesh);
+
+    // ── Legacy API on a fresh mesh — must replicate the *same* preparation
+    //    that the wrapper performs internally (pin first vertex, assign
+    //    DOFs, apply natural-theta).  Otherwise the comparison is unfair
+    //    (Newton would diverge without natural-theta on these meshes). ────
+    auto mesh_legacy = make_quad_strip();
+    auto maps = setup_euclidean_maps(mesh_legacy);
+    compute_euclidean_lambda0_from_mesh(mesh_legacy, maps);
+
+    // Pin first vertex (gauge), assign sequential DOFs to the rest.
+    auto vit = mesh_legacy.vertices().begin();
+    maps.v_idx[*vit++] = -1;
+    int idx = 0;
+    for (; vit != mesh_legacy.vertices().end(); ++vit)
+        maps.v_idx[*vit] = idx++;
+
+    // Natural-theta: shift Θ so that x = 0 is the natural equilibrium.
+    std::vector<double> x0(idx, 0.0);
+    auto G0 = euclidean_gradient(mesh_legacy, x0, maps);
+    for (auto v : mesh_legacy.vertices()) {
+        int j = maps.v_idx[v];
+        if (j >= 0) maps.theta_v[v] -= G0[static_cast<std::size_t>(j)];
+    }
+
+    auto nr = newton_euclidean(mesh_legacy, x0, maps, 1e-10, 200);
+
+    // ── Compare ────────────────────────────────────────────────────────────
+    EXPECT_EQ(result_new.converged, nr.converged);
+    EXPECT_NEAR(result_new.gradient_norm, nr.grad_inf_norm, 1e-12);
+
+    // Pinned vertex u is 0 in both; for the rest the values agree.
+    for (auto v : mesh_legacy.vertices()) {
+        int j = maps.v_idx[v];
+        double u_legacy = (j >= 0) ? nr.x[static_cast<std::size_t>(j)] : 0.0;
+        EXPECT_NEAR(result_new.u_per_vertex[v.idx()], u_legacy, 1e-10)
+            << "Wrapper diverges from legacy for vertex " << v.idx();
+    }
+}

code/tests/cgal/test_conformal_mesh.cpp

@@ -1,3 +1,6 @@
+// Copyright (c) 2024-2026 Tarik Moussa.
+// SPDX-License-Identifier: MIT
+
 // test_conformal_mesh.cpp
 //
 // Phase 3a — CGAL Surface_mesh infrastructure tests.

code/tests/cgal/test_cp_euclidean_functional.cpp

@@ -0,0 +1,270 @@
+// Copyright (c) 2024-2026 Tarik Moussa.
+// SPDX-License-Identifier: MIT
+
+// test_cp_euclidean_functional.cpp
+//
+// Phase 9a.1 — CPEuclideanFunctional (BPS 2010) tests.
+//
+// Replicates de.varylab.discreteconformal.functional.CPEuclideanFunctionalTest
+// (88 lines) and adds boundary-edge coverage plus a closed-mesh case.
+//
+// Java test pattern (lines 50-87):
+//   1. Build dodecahedron via HalfEdgeUtils.addDodecahedron.
+//   2. Remove face 0 to produce an open mesh.
+//   3. theta_e = π/2 for every edge.       (orthogonal circle packing)
+//   4. phi_f   = 2π for every face.        (flat target)
+//   5. Random ρ ∈ [−0.5, 0.5] (seed 1).
+//   6. FunctionalTest.setXGradient(ρ) → FD-vs-analytic gradient check.
+//   7. FunctionalTest.setXHessian(ρ)  → FD-vs-analytic Hessian  check.
+//
+// C++ port uses the tetrahedron (4 faces) instead of the dodecahedron (12 faces)
+// because the analytic structure is identical and the smaller mesh keeps the
+// test fast and human-inspectable.  We exercise the boundary-edge code path
+// by additionally testing a tetrahedron with one face removed (3 faces, 3
+// boundary edges, 3 interior edges).
+
+#include "cp_euclidean_functional.hpp"
+#include "mesh_builder.hpp"
+#include "conformal_mesh.hpp"
+
+#include <Eigen/Eigenvalues>
+#include <gtest/gtest.h>
+#include <vector>
+#include <random>
+
+using namespace conformallab;
+
+// ════════════════════════════════════════════════════════════════════════════
+// 1.  Helper: explicit values for p(θ*, Δρ) at known inputs
+//
+// p(θ*, 0) = 0          (tanh 0 = 0)
+// p(π, Δρ) = π·sign(Δρ) (tan(π/2) = ∞, atan saturates to ±π/2)
+// p(0, Δρ) = 0          (tan(0) = 0)
+// p odd in Δρ (tanh is odd).
+// ════════════════════════════════════════════════════════════════════════════
+
+TEST(CPEuclideanFunctional, PFunctionKnownValues)
+{
+    using cp_detail::p_function;
+    constexpr double PI_ = 3.14159265358979323846;
+
+    // p(any, 0) = 0
+    EXPECT_NEAR(p_function(PI_ / 4,  0.0), 0.0, 1e-15);
+    EXPECT_NEAR(p_function(PI_ / 2,  0.0), 0.0, 1e-15);
+
+    // Odd in Δρ
+    const double thStar = PI_ / 3;
+    for (double dr : {0.1, 0.5, 1.0, 2.0}) {
+        EXPECT_NEAR(p_function(thStar, dr) + p_function(thStar, -dr), 0.0, 1e-12)
+            << "p(θ*, Δρ) should be odd in Δρ";
+    }
+}
+
+// ════════════════════════════════════════════════════════════════════════════
+// 2.  Property-map setup defaults
+// ════════════════════════════════════════════════════════════════════════════
+
+TEST(CPEuclideanFunctional, SetupDefaults)
+{
+    auto mesh = make_tetrahedron();
+    auto m = setup_cp_euclidean_maps(mesh);
+
+    constexpr double PI_ = 3.14159265358979323846;
+    for (auto e : mesh.edges()) EXPECT_NEAR(m.theta_e[e], PI_ / 2, 1e-15);
+    for (auto f : mesh.faces()) EXPECT_NEAR(m.phi_f[f],   2.0 * PI_, 1e-15);
+    for (auto f : mesh.faces()) EXPECT_EQ(m.f_idx[f], -1) << "all faces start pinned";
+}
+
+TEST(CPEuclideanFunctional, AssignDofIndices_PinsOneFace)
+{
+    auto mesh = make_tetrahedron();
+    auto m    = setup_cp_euclidean_maps(mesh);
+    const int n = assign_cp_euclidean_face_dof_indices(mesh, m);
+
+    EXPECT_EQ(n, 3) << "tetrahedron has 4 faces; 1 pinned ⇒ 3 free DOFs";
+
+    int pinned_count = 0;
+    int max_idx = -1;
+    for (auto f : mesh.faces()) {
+        if (m.f_idx[f] == -1) ++pinned_count;
+        else max_idx = std::max(max_idx, m.f_idx[f]);
+    }
+    EXPECT_EQ(pinned_count, 1);
+    EXPECT_EQ(max_idx, 2);
+}
+
+// ════════════════════════════════════════════════════════════════════════════
+// 3.  Tangential limit (θ = 0): p = 0, energy collapses, gradient = φ_f
+// ════════════════════════════════════════════════════════════════════════════
+
+TEST(CPEuclideanFunctional, TangentialLimitGradientEqualsPhi)
+{
+    auto mesh = make_tetrahedron();
+    auto m    = setup_cp_euclidean_maps(mesh);
+    for (auto e : mesh.edges()) m.theta_e[e] = 0.0;   // tangential limit
+    const int n = assign_cp_euclidean_face_dof_indices(mesh, m);
+
+    // At θ = 0: θ* = π.  Interior edge contribution: −(p+θ*) where p = π·sign(Δρ).
+    // Boundary contribution: −2π.  At ρ = 0, Δρ = 0 so p = 0; each interior face
+    // contributes −π per incident interior halfedge; for a tetrahedron each face
+    // has 3 interior halfedges ⇒ −3π.  Net gradient: 2π − 3π = −π per free face.
+    std::vector<double> x(static_cast<std::size_t>(n), 0.0);
+    auto G = cp_euclidean_gradient(mesh, x, m);
+
+    constexpr double PI_ = 3.14159265358979323846;
+    for (double g : G) EXPECT_NEAR(g, -PI_, 1e-10);
+}
+
+// ════════════════════════════════════════════════════════════════════════════
+// 4.  FD gradient check on closed tetrahedron at random ρ
+//
+// Java parity: this is exactly the structure of CPEuclideanFunctionalTest.
+// ════════════════════════════════════════════════════════════════════════════
+
+TEST(CPEuclideanFunctional, FDGradientCheck_ClosedTetrahedron_RandomRho)
+{
+    auto mesh = make_tetrahedron();
+    auto m    = setup_cp_euclidean_maps(mesh);
+    const int n = assign_cp_euclidean_face_dof_indices(mesh, m);
+
+    // Java: rnd.setSeed(1);  rho_i = rnd.nextDouble() − 0.5
+    std::mt19937 rng(1);
+    std::uniform_real_distribution<double> u(-0.5, 0.5);
+    std::vector<double> rho(static_cast<std::size_t>(n));
+    for (auto& r : rho) r = u(rng);
+
+    EXPECT_TRUE(gradient_check_cp_euclidean(mesh, rho, m))
+        << "FD vs analytic gradient mismatch on closed tetrahedron";
+}
+
+// ════════════════════════════════════════════════════════════════════════════
+// 5.  FD Hessian check on closed tetrahedron at random ρ
+// ════════════════════════════════════════════════════════════════════════════
+
+TEST(CPEuclideanFunctional, FDHessianCheck_ClosedTetrahedron_RandomRho)
+{
+    auto mesh = make_tetrahedron();
+    auto m    = setup_cp_euclidean_maps(mesh);
+    const int n = assign_cp_euclidean_face_dof_indices(mesh, m);
+
+    std::mt19937 rng(1);
+    std::uniform_real_distribution<double> u(-0.5, 0.5);
+    std::vector<double> rho(static_cast<std::size_t>(n));
+    for (auto& r : rho) r = u(rng);
+
+    EXPECT_TRUE(hessian_check_cp_euclidean(mesh, rho, m))
+        << "FD vs analytic Hessian mismatch on closed tetrahedron";
+}
+
+// ════════════════════════════════════════════════════════════════════════════
+// 6.  Boundary-edge coverage: open mesh (tetrahedron with one face removed)
+//
+// Java test does this via `hds.removeFace(hds.getFace(0))`.  In CGAL we get
+// an equivalent open mesh by skipping the construction of one face.
+// ════════════════════════════════════════════════════════════════════════════
+
+inline ConformalMesh make_open_tetrahedron()
+{
+    ConformalMesh mesh;
+    auto v0 = mesh.add_vertex(Point3( 1,  1,  1));
+    auto v1 = mesh.add_vertex(Point3( 1, -1, -1));
+    auto v2 = mesh.add_vertex(Point3(-1,  1, -1));
+    auto v3 = mesh.add_vertex(Point3(-1, -1,  1));
+    // Three faces (omit the one opposite v0):
+    mesh.add_face(v0, v2, v1);
+    mesh.add_face(v0, v1, v3);
+    mesh.add_face(v0, v3, v2);
+    return mesh;
+}
+
+TEST(CPEuclideanFunctional, FDGradientCheck_OpenTetrahedron_RandomRho)
+{
+    auto mesh = make_open_tetrahedron();
+    auto m    = setup_cp_euclidean_maps(mesh);
+    const int n = assign_cp_euclidean_face_dof_indices(mesh, m);
+
+    EXPECT_EQ(n, 2);   // 3 faces, 1 pinned ⇒ 2 free DOFs
+
+    std::mt19937 rng(1);
+    std::uniform_real_distribution<double> u(-0.5, 0.5);
+    std::vector<double> rho(static_cast<std::size_t>(n));
+    for (auto& r : rho) r = u(rng);
+
+    EXPECT_TRUE(gradient_check_cp_euclidean(mesh, rho, m))
+        << "FD vs analytic gradient mismatch on open tetrahedron";
+}
+
+TEST(CPEuclideanFunctional, FDHessianCheck_OpenTetrahedron_RandomRho)
+{
+    auto mesh = make_open_tetrahedron();
+    auto m    = setup_cp_euclidean_maps(mesh);
+    const int n = assign_cp_euclidean_face_dof_indices(mesh, m);
+
+    std::mt19937 rng(1);
+    std::uniform_real_distribution<double> u(-0.5, 0.5);
+    std::vector<double> rho(static_cast<std::size_t>(n));
+    for (auto& r : rho) r = u(rng);
+
+    EXPECT_TRUE(hessian_check_cp_euclidean(mesh, rho, m))
+        << "FD vs analytic Hessian mismatch on open tetrahedron";
+}
+
+// ════════════════════════════════════════════════════════════════════════════
+// 7.  Hessian is symmetric positive-semidefinite (BPS-2010 §6 convexity)
+//
+// The energy is convex in ρ on its domain of validity.  Hence H is PSD with
+// a 1-dim null space (constant shift of all ρ, removed by gauge pin).
+// ════════════════════════════════════════════════════════════════════════════
+
+TEST(CPEuclideanFunctional, HessianIsPSD)
+{
+    auto mesh = make_tetrahedron();
+    auto m    = setup_cp_euclidean_maps(mesh);
+    const int n = assign_cp_euclidean_face_dof_indices(mesh, m);
+
+    std::vector<double> rho(static_cast<std::size_t>(n), 0.1);
+    auto H = cp_euclidean_hessian(mesh, rho, m);
+
+    // Symmetry
+    Eigen::MatrixXd Hd(H);
+    EXPECT_NEAR((Hd - Hd.transpose()).cwiseAbs().maxCoeff(), 0.0, 1e-15);
+
+    // Smallest eigenvalue ≥ 0 (PSD)
+    Eigen::SelfAdjointEigenSolver<Eigen::MatrixXd> es(Hd);
+    EXPECT_GE(es.eigenvalues().minCoeff(), -1e-12)
+        << "Hessian must be PSD (BPS-2010 §6)";
+}
+
+// ════════════════════════════════════════════════════════════════════════════
+// 8.  At equilibrium (Newton-converged ρ*), the gradient is zero by construction
+//
+// We do not run a full Newton solver here; we set up the "natural-theta" trick:
+// adjust φ_f so that ρ = 0 is the equilibrium.  This is the analog of the
+// natural-theta convention already used in euclidean_functional tests
+// (see test_euclidean_functional.cpp lines 159-189).
+// ════════════════════════════════════════════════════════════════════════════
+
+TEST(CPEuclideanFunctional, NaturalPhiMakesZeroTheEquilibrium)
+{
+    auto mesh = make_tetrahedron();
+    auto m    = setup_cp_euclidean_maps(mesh);
+    const int n = assign_cp_euclidean_face_dof_indices(mesh, m);
+
+    std::vector<double> rho(static_cast<std::size_t>(n), 0.0);
+
+    // Step 1: gradient at ρ = 0 with default φ.
+    auto G0 = cp_euclidean_gradient(mesh, rho, m);
+
+    // Step 2: adjust φ_f so the new gradient at ρ = 0 is zero.
+    //   ∂E/∂ρ_f = φ_f − (sum of edge contributions)
+    //   To zero G_f: subtract G_f from φ_f.
+    for (auto f : mesh.faces()) {
+        int i = m.f_idx[f];
+        if (i < 0) continue;
+        m.phi_f[f] -= G0[static_cast<std::size_t>(i)];
+    }
+
+    // Step 3: gradient at ρ = 0 should now be ~zero.
+    auto G_eq = cp_euclidean_gradient(mesh, rho, m);
+    for (double g : G_eq) EXPECT_NEAR(g, 0.0, 1e-13);
+}

code/tests/cgal/test_euclidean_functional.cpp

@@ -1,3 +1,6 @@
+// Copyright (c) 2024-2026 Tarik Moussa.
+// SPDX-License-Identifier: MIT
+
 // test_euclidean_functional.cpp
 //
 // Phase 3d — EuclideanCyclicFunctional ported to ConformalMesh.
@@ -6,7 +9,7 @@
 //
 // Test map (Java → C++)
 // ──────────────────────
-//   testHessian (Ignored)       → GradientCheck_Hessian           (SKIPPED)
+//   testHessian (Ignored)       → GradientCheck_Hessian           (ported)
 //   testGradient…Triangle       → GradientCheck_TriangleVertex     (ported)
 //   testGradient…QuadStrip      → GradientCheck_QuadStripVertex    (ported)
 //   testGradient…Tetrahedron    → GradientCheck_TetrahedronVertex  (ported)
@@ -22,6 +25,7 @@
 #include "mesh_builder.hpp"
 #include "euclidean_geometry.hpp"
 #include "euclidean_functional.hpp"
+#include "euclidean_hessian.hpp"
 #include <gtest/gtest.h>
 #include <cmath>
 #include <vector>
@@ -29,12 +33,31 @@
 using namespace conformallab;
 
 // ════════════════════════════════════════════════════════════════════════════
-// @Ignore in Java: no Hessian implemented yet
+// Cross-module Hessian check: euclidean_gradient() ↔ euclidean_hessian()
+//
+// Java @Ignore reason: "no Hessian implemented yet" — the Java functional
+// test was written before the Hessian existed.  In C++ the analytic
+// cotangent-Laplace Hessian (euclidean_hessian.hpp, Phase 3f) is complete.
+//
+// This test verifies cross-module consistency:
+//   H[i,j] ≈ (G_i(x+ε·eⱼ) − G_i(x−ε·eⱼ)) / (2ε)
+// using the gradient from euclidean_functional.hpp and the Hessian from
+// euclidean_hessian.hpp.  A bug in DOF-index mapping or sign convention
+// that affects both modules independently would only be caught here.
 // ════════════════════════════════════════════════════════════════════════════
 
 TEST(EuclideanFunctional, GradientCheck_Hessian)
 {
-    GTEST_SKIP() << "@Ignore in Java – Hessian not yet implemented";
+    auto mesh = make_triangle();
+    auto maps = setup_euclidean_maps(mesh);
+    compute_euclidean_lambda0_from_mesh(mesh, maps);
+    int n = assign_euclidean_vertex_dof_indices(mesh, maps);
+
+    std::vector<double> x(static_cast<std::size_t>(n), -0.1);
+
+    // hessian_check_euclidean: H[i,j] ≈ FD(G)[i,j] using euclidean_gradient()
+    EXPECT_TRUE(hessian_check_euclidean(mesh, x, maps))
+        << "Cross-module: euclidean_gradient() and euclidean_hessian() are inconsistent";
 }
 
 // ════════════════════════════════════════════════════════════════════════════

code/tests/cgal/test_euclidean_hessian.cpp

@@ -1,3 +1,6 @@
+// Copyright (c) 2024-2026 Tarik Moussa.
+// SPDX-License-Identifier: MIT
+
 // test_euclidean_hessian.cpp
 //
 // Phase 3f — Euclidean cotangent-Laplace Hessian.

code/tests/cgal/test_geometry_utils.cpp

@@ -1,72 +1,95 @@
+// Copyright (c) 2024-2026 Tarik Moussa.
+// SPDX-License-Identifier: MIT
+
 // test_geometry_utils.cpp
 //
-// Portierung der Java ConformalLab Geometrie-Utility-Tests.
+// Port of the Java ConformalLab geometry utility tests.
 //
-// Java-Quelle                           Java-Testmethode                         Status
+// Java source                           Java test method                         Status
 // ─────────────────────────────────────────────────────────────────────────────────────
-// CuttinUtilityTest.java                testIsInConvexTextureFace_False          PORTIERT
+// CuttinUtilityTest.java                testIsInConvexTextureFace_False          PORTED
-// CuttinUtilityTest.java                testIsInConvexTextureFace_True           PORTIERT
+// CuttinUtilityTest.java                testIsInConvexTextureFace_True           PORTED
-// UnwrapUtilityTest.java                testGetAngleReturnsPI                    PORTIERT
+// UnwrapUtilityTest.java                testGetAngleReturnsPI                    PORTED
-// ConvergenceUtilityTests.java          testGetTextureCircumRadius               PORTIERT
+// ConvergenceUtilityTests.java          testGetTextureCircumRadius               PORTED
-// ConvergenceUtilityTests.java          testGetTextureTriangleArea               PORTIERT
+// ConvergenceUtilityTests.java          testGetTextureTriangleArea               PORTED
-// ConvergenceUtilityTests.java          testScaleInvariantCircumCircleRadius     PORTIERT
+// ConvergenceUtilityTests.java          testScaleInvariantCircumCircleRadius     PORTED
-// HomologyTest.java                     testHomology                             GEBLOCKT
+// HomologyTest.java                     testHomology                             PORTED
+// EuclideanLayoutTest.java              testDoLayout                             PORTED
+// EuclideanCyclicConvergenceTest.java   testEuclideanConvergence                 PORTED
+// SphericalConvergenceTest.java         testSphericalConvergence                 PORTED
 //
-// ─── Geometrische Grundlage ──────────────────────────────────────────────────────────
+// ─── Geometric background ────────────────────────────────────────────────────────────
 //
-//  Tests 1–2  Punkt-in-konvexem-Dreieck (2D UV-Raum, baryzentrische Vorzeichen-Methode)
+//  Tests 1–2  Point-in-convex-triangle (2D UV space, barycentric sign method)
 //             Java: CuttingUtility.isInConvexTextureFace(pp, face, adapters)
-//             Hinweis: Java-Test 2 hat ein 5-elementiges T-Array mit w=0 (Punkt im
+//             Note: Java test 2 has a 5-element T-array with w=0 (point at
-//             Unendlichen), was ein Tippfehler im Original ist. Hier werden
+//             infinity), which is a typo in the original. Equivalent, well-formed
-//             äquivalente, wohlgeformte Koordinaten verwendet.
+//             coordinates are used here instead.
 //
-//  Test 3     Eckenwinkel für kollineare Vertices über den Kosinussatz.
+//  Test 3     Corner angle for collinear vertices via the law of cosines.
-//             Java: UnwrapUtility.getAngle(edge, adapters) — gibt den Winkel am
+//             Java: UnwrapUtility.getAngle(edge, adapters) — returns the angle at
-//             Zielknoten zurück. Für v0=(-1,0,0), v1=(0,0,0), v2=(1,0,0) ist
+//             the target vertex. For v0=(-1,0,0), v1=(0,0,0), v2=(1,0,0) the
-//             der Winkel bei v1 genau π (Dreiecksungleichung entartet).
+//             angle at v1 is exactly π (degenerate triangle inequality).
 //
-//  Tests 4–5  2D Umkreisradius und Dreiecksfläche.
+//  Tests 4–5  2D circumradius and triangle area.
 //             Java: ConvergenceUtility.getTextureCircumCircleRadius(face)
 //                   ConvergenceUtility.getTextureTriangleArea(face)
-//             Formeln: Area = |det([B-A, C-A])| / 2
+//             Formulas: Area = |det([B-A, C-A])| / 2
-//                      R    = (a·b·c) / (4·Area)
+//                       R    = (a·b·c) / (4·Area)
 //
-//  Test 6     Skaleninvarianter Umkreisradius über ein Mesh.
+//  Test 6     Scale-invariant circumradius over a mesh.
 //             Java: ConvergenceUtility.getMaxMeanSumScaleInvariantCircumRadius(hds)
-//             Gibt [max, mean, sum] von  R_f / sqrt(total_texture_area)  zurück.
+//             Returns [max, mean, sum] of  R_f / sqrt(total_texture_area).
-//             Invariant unter uniformer Skalierung der Texturkoordinaten (Test mit
+//             Invariant under uniform scaling of texture coordinates (tested with
-//             homogenem Gewicht w: Position = (T[0]/w, T[1]/w)).
+//             homogeneous weight w: position = (T[0]/w, T[1]/w)).
 //
-// ─── GEBLOCKT (Test 7) ───────────────────────────────────────────────────────────────
+//  Test 7     Genus-2 homology generators.
+//             Java: HomologyTest.testHomology (brezel2.obj)
+//             Expected: getGeneratorPaths(root).size() == 4  (2g = 4 for g = 2)
+//             C++: compute_cut_graph(mesh).cut_edge_indices.size() == 4
+//             Mesh: code/data/obj/brezel2.obj (V=2622, F=5248, χ=−2, g=2)
+//             Path set at compile time via CONFORMALLAB_DATA_DIR (CMakeLists.txt).
 //
-//  Test 7     Genus-2 Homologie-Generatoren
+//  Tests 8–9  Layout edge-length preservation (tetraflat.obj).
-//             Java: HomologyTest.testHomology
+//             Java: EuclideanLayoutTest.testDoLayout
-//             Erwartet: getGeneratorPaths(root, ...).size() == 4  (2g = 4 für g = 2)
+//             After layout with u=0, UV edge lengths must equal 3D edge lengths (±1e-10).
-//             C++-Äquivalent: compute_cut_graph(mesh).cut_edge_indices.size() == 4
+//
-//             BLOCKED: Kein Genus-2-Testmesh in mesh_builder.hpp vorhanden.
+//  Test 10    Euclidean Newton on cathead.obj — convergence + angle deficit.
-//             TODO(Phase 8): make_genus2_surface() in mesh_builder.hpp implementieren
+//             Java: EuclideanLayoutTest.testLayout02 (130-value array for cathead.heml)
-//             oder brezel2.obj via load_mesh importieren, dann GTEST_SKIP entfernen.
+//             C++: Newton from u=0, checks convergence + Σα_v ≈ 2π for all interior nodes.
+//
+//  Test 11    Spherical Newton on octahedron — convergence + angle deficit.
+//             Java: SphericalConvergenceTest.testSphericalConvergence (octahedron, randomly
+//             perturbed radii, seed=1). C++: constructed regular octahedron, checks
+//             convergence and that Σα_v ≈ 2π (target for sphere after prepareInvariantData).
 //
 // ─────────────────────────────────────────────────────────────────────────────────────
 
-#include "cut_graph.hpp"        // für Test 7 (Genus-2 TODO)
+#include "cut_graph.hpp"
+#include "gauss_bonnet.hpp"
 #include "conformal_mesh.hpp"
 #include "mesh_builder.hpp"
+#include "mesh_io.hpp"
+#include "euclidean_functional.hpp"
+#include "spherical_functional.hpp"
+#include "newton_solver.hpp"
+#include "layout.hpp"
 #include <gtest/gtest.h>
 #include <Eigen/Dense>
 #include <array>
 #include <cmath>
+#include <string>
 #include <vector>
 
 using namespace conformallab;
 
 // ─────────────────────────────────────────────────────────────────────────────
-// Lokale Geometrie-Hilfsfunktionen
+// Local geometry helper functions
-// (portiert aus Java CuttingUtility / ConvergenceUtility)
+// (ported from Java CuttingUtility / ConvergenceUtility)
 // ─────────────────────────────────────────────────────────────────────────────
 
-/// Punkt-in-Dreieck Test (2D, baryzentrische Vorzeichenmethode).
+/// Point-in-triangle test (2D, barycentric sign method).
-/// Gibt true zurück wenn p strikt innerhalb oder auf dem Rand von v0-v1-v2 liegt.
+/// Returns true if p lies strictly inside or on the boundary of v0-v1-v2.
 /// Java: CuttingUtility.isInConvexTextureFace
 static bool point_in_triangle_2d(
     Eigen::Vector2d p,
@@ -83,7 +106,7 @@ static bool point_in_triangle_2d(
     return !(has_neg && has_pos);
 }
 
-/// 2D Dreiecksfläche (halbes Kreuzprodukt).
+/// 2D triangle area (half cross product).
 /// Java: ConvergenceUtility.getTextureTriangleArea
 static double triangle_area_2d(
     Eigen::Vector2d A, Eigen::Vector2d B, Eigen::Vector2d C)
@@ -92,7 +115,7 @@ static double triangle_area_2d(
                   - (B - A).y() * (C - A).x()) * 0.5;
 }
 
-/// 2D Umkreisradius: R = (a·b·c) / (4·Area).
+/// 2D circumradius: R = (a·b·c) / (4·Area).
 /// Java: ConvergenceUtility.getTextureCircumCircleRadius
 static double circumradius_2d(
     Eigen::Vector2d A, Eigen::Vector2d B, Eigen::Vector2d C)
@@ -105,17 +128,17 @@ static double circumradius_2d(
     return (a * b * c) / (4.0 * area);
 }
 
-/// Skaleninvarianter Umkreisradius für ein Mesh:
+/// Scale-invariant circumradius for a mesh:
 ///   scale_R_f = R_f / sqrt(total_area)
-/// Gibt {max, mean, sum} über alle Flächen zurück.
+/// Returns {max, mean, sum} over all faces.
 /// Java: ConvergenceUtility.getMaxMeanSumScaleInvariantCircumRadius
 ///
-/// Homogene Koordinaten: Position = (x/w, y/w).
+/// Homogeneous coordinates: position = (x/w, y/w).
 static std::array<double, 3> scale_invariant_circumradius_stats(
     const std::vector<Eigen::Vector2d>& verts,
     const std::vector<std::array<int, 3>>& faces)
 {
-    // Gesamtfläche
+    // Total area
     double total_area = 0.0;
     for (auto& f : faces)
         total_area += triangle_area_2d(verts[f[0]], verts[f[1]], verts[f[2]]);
@@ -134,70 +157,70 @@ static std::array<double, 3> scale_invariant_circumradius_stats(
 }
 
 // ════════════════════════════════════════════════════════════════════════════
-// Tests 1–2 — CuttingUtility: Punkt-in-konvexem-Dreieck (2D UV-Raum)
+// Tests 1–2 — CuttingUtility: point-in-convex-triangle (2D UV space)
 //             Java: CuttinUtilityTest.testIsInConvexTextureFace_False / _True
 // ════════════════════════════════════════════════════════════════════════════
 
-// Test 1: Punkt liegt weit außerhalb — exakte Java-Koordinaten
+// Test 1: point lies far outside — exact Java coordinates
 TEST(CuttingUtility, IsInConvexTextureFace_False)
 {
-    // Winziges Dreieck um (0.7488, 0.0629) — Java-Testkoordinaten (T[3]=1, w=1)
+    // Tiny triangle around (0.7488, 0.0629) — Java test coordinates (T[3]=1, w=1)
     Eigen::Vector2d v0(0.7488102998904661,  0.06293998610761144);
     Eigen::Vector2d v1(0.7487811940754379,  0.06289451051246124);
     Eigen::Vector2d v2(0.7487254625255592,  0.06291429499873116);
-    // Testpunkt weit entfernt bei (0.447, 0.000228)
+    // Test point far away at (0.447, 0.000228)
     Eigen::Vector2d pp(0.44661534423161037, 2.2808373704822393e-4);
 
     EXPECT_FALSE(point_in_triangle_2d(pp, v0, v1, v2));
 }
 
-// Test 2: Punkt liegt innerhalb
+// Test 2: point lies inside
-// Hinweis: Das originale Java-Array p2 hat 5 Elemente mit w=0 (Tippfehler im
+// Note: the original Java array p2 has 5 elements with w=0 (typo in the
-// Java-Original). Hier werden äquivalente, wohlgeformte Koordinaten verwendet,
+// Java original). Equivalent, well-formed coordinates are used here
-// die dasselbe geometrische Szenario abbilden.
+// that represent the same geometric scenario.
 TEST(CuttingUtility, IsInConvexTextureFace_True)
 {
-    // Dreieck: (0,0) — (1e-8, 0) — (0, 1e-8)
+    // Triangle: (0,0) — (1e-8, 0) — (0, 1e-8)
     Eigen::Vector2d v0(0.0,   0.0);
     Eigen::Vector2d v1(1e-8,  0.0);
     Eigen::Vector2d v2(0.0,   1e-8);
-    // Schwerpunkt des Dreiecks — liegt immer innen
+    // Centroid of the triangle — always lies inside
     Eigen::Vector2d pp(1e-8 / 3.0, 1e-8 / 3.0);
 
     EXPECT_TRUE(point_in_triangle_2d(pp, v0, v1, v2));
 }
 
-// Zusätzlich: einfaches Einheitsdreieck für Klarheit
+// Additional: simple unit triangle for clarity
 TEST(CuttingUtility, IsInConvexTextureFace_UnitTriangle_InAndOut)
 {
     Eigen::Vector2d v0(0.0, 0.0), v1(1.0, 0.0), v2(0.0, 1.0);
     EXPECT_TRUE( point_in_triangle_2d(Eigen::Vector2d(0.25, 0.25), v0, v1, v2));
     EXPECT_FALSE(point_in_triangle_2d(Eigen::Vector2d(2.0,  2.0),  v0, v1, v2));
-    EXPECT_FALSE(point_in_triangle_2d(Eigen::Vector2d(0.6,  0.6),  v0, v1, v2));  // jenseits Hypotenuse
+    EXPECT_FALSE(point_in_triangle_2d(Eigen::Vector2d(0.6,  0.6),  v0, v1, v2));  // beyond hypotenuse
 }
 
 // ════════════════════════════════════════════════════════════════════════════
-// Test 3 — UnwrapUtility: Eckenwinkel = π für kollineare Vertices
+// Test 3 — UnwrapUtility: corner angle = π for collinear vertices
 //          Java: UnwrapUtilityTest.testGetAngleReturnsPI
 // ════════════════════════════════════════════════════════════════════════════
 
-// Java: v0=(-1,0,0), v1=(0,0,0), v2=(1,0,0) kollinear.
+// Java: v0=(-1,0,0), v1=(0,0,0), v2=(1,0,0) collinear.
-// Kante e von v2 nach v1. getAngle(e) = Winkel bei v1 = π.
+// Edge e from v2 to v1. getAngle(e) = angle at v1 = π.
 //
-// C++: Kosinussatz mit Kantenlängen a=|v0-v1|=1, b=|v1-v2|=1, c=|v0-v2|=2.
+// C++: law of cosines with edge lengths a=|v0-v1|=1, b=|v1-v2|=1, c=|v0-v2|=2.
 //   cos(γ_v1) = (a² + b² − c²) / (2ab) = (1 + 1 − 4) / 2 = −1  →  γ = π
 TEST(UnwrapUtility, GetAngle_CollinearVertices_ReturnsPI)
 {
     const double a = 1.0;   // |v0 − v1|
     const double b = 1.0;   // |v1 − v2|
-    const double c = 2.0;   // |v0 − v2|   (= a + b, entartet)
+    const double c = 2.0;   // |v0 − v2|   (= a + b, degenerate)
     double cos_angle = (a*a + b*b - c*c) / (2.0 * a * b);
-    cos_angle = std::max(-1.0, std::min(1.0, cos_angle));   // numerisches Clamp
+    cos_angle = std::max(-1.0, std::min(1.0, cos_angle));   // numeric clamp
     double angle = std::acos(cos_angle);
     EXPECT_NEAR(M_PI, angle, 1e-15);
 }
 
-// Gegenkontrolle: gleichseitiges Dreieck → Winkel = π/3
+// Counter-check: equilateral triangle → angle = π/3
 TEST(UnwrapUtility, GetAngle_EquilateralTriangle_ReturnsPiOver3)
 {
     const double s = 1.0;
@@ -207,57 +230,57 @@ TEST(UnwrapUtility, GetAngle_EquilateralTriangle_ReturnsPiOver3)
 }
 
 // ════════════════════════════════════════════════════════════════════════════
-// Test 4 — ConvergenceUtility: 2D Umkreisradius
+// Test 4 — ConvergenceUtility: 2D circumradius
 //          Java: ConvergenceUtilityTests.testGetTextureCircumRadius
 // ════════════════════════════════════════════════════════════════════════════
 
 TEST(ConvergenceUtility, TextureCircumRadius_RightTriangle)
 {
-    // A=(0,0), B=(1,0), C=(0,1): rechtwinkliges gleichschenkliges Dreieck
+    // A=(0,0), B=(1,0), C=(0,1): right isosceles triangle
-    // Seiten: 1, 1, √2.  R = √2 / (4 · 0.5) = √2/2
+    // Sides: 1, 1, √2.  R = √2 / (4 · 0.5) = √2/2
     Eigen::Vector2d A(0.0, 0.0), B(1.0, 0.0), C(0.0, 1.0);
     EXPECT_NEAR(std::sqrt(2.0) / 2.0, circumradius_2d(A, B, C), 1e-10);
 }
 
 TEST(ConvergenceUtility, TextureCircumRadius_SmallerTriangle)
 {
-    // A=(0,0), B=(0.5,0.5), C=(0,1): Java-Variante mit B.T={0.5,0.5,0,1}
+    // A=(0,0), B=(0.5,0.5), C=(0,1): Java variant with B.T={0.5,0.5,0,1}
-    // Seiten: √0.5, √0.5, 1.  Area = 0.25.  R = (√0.5·√0.5·1)/(4·0.25) = 0.5
+    // Sides: √0.5, √0.5, 1.  Area = 0.25.  R = (√0.5·√0.5·1)/(4·0.25) = 0.5
     Eigen::Vector2d A(0.0, 0.0), B(0.5, 0.5), C(0.0, 1.0);
     EXPECT_NEAR(0.5, circumradius_2d(A, B, C), 1e-10);
 }
 
 // ════════════════════════════════════════════════════════════════════════════
-// Test 5 — ConvergenceUtility: 2D Dreiecksfläche
+// Test 5 — ConvergenceUtility: 2D triangle area
 //          Java: ConvergenceUtilityTests.testGetTextureTriangleArea
 // ════════════════════════════════════════════════════════════════════════════
 
 TEST(ConvergenceUtility, TextureTriangleArea_RightTriangle)
 {
-    // A=(0,0), B=(1,0), C=(0,1) → Fläche = 0.5
+    // A=(0,0), B=(1,0), C=(0,1) → area = 0.5
     Eigen::Vector2d A(0.0, 0.0), B(1.0, 0.0), C(0.0, 1.0);
     EXPECT_NEAR(0.5, triangle_area_2d(A, B, C), 1e-10);
 }
 
 TEST(ConvergenceUtility, TextureTriangleArea_SmallerTriangle)
 {
-    // A=(0,0), B=(0.5,0.5), C=(0,1) → Fläche = 0.25
+    // A=(0,0), B=(0.5,0.5), C=(0,1) → area = 0.25
     Eigen::Vector2d A(0.0, 0.0), B(0.5, 0.5), C(0.0, 1.0);
     EXPECT_NEAR(0.25, triangle_area_2d(A, B, C), 1e-10);
 }
 
 // ════════════════════════════════════════════════════════════════════════════
-// Test 6 — ConvergenceUtility: Skaleninvarianter Umkreisradius
+// Test 6 — ConvergenceUtility: scale-invariant circumradius
 //          Java: ConvergenceUtilityTests.testScaleInvariantCircumCircleRadius
 //
-// Mesh: 4 Vertices (v1..v4), 2 Flächen (f1: v1-v2-v3, f2: v1-v3-v4).
+// Mesh: 4 vertices (v1..v4), 2 faces (f1: v1-v2-v3, f2: v1-v3-v4).
-// Skaleninvariante Größe: R_f / sqrt(total_area) — invariant unter
+// Scale-invariant quantity: R_f / sqrt(total_area) — invariant under
-// uniformer Skalierung (homogeneous weight w: pos = (x/w, y/w)).
+// uniform scaling (homogeneous weight w: pos = (x/w, y/w)).
 // ════════════════════════════════════════════════════════════════════════════
 
 TEST(ConvergenceUtility, ScaleInvariantCircumRadius_BaseScale)
 {
-    // Positionen bei w=1 (T[3]=1): v1=(0,0), v2=(1,0), v3=(0,1), v4=(-1,0)
+    // Positions at w=1 (T[3]=1): v1=(0,0), v2=(1,0), v3=(0,1), v4=(-1,0)
     std::vector<Eigen::Vector2d> verts = {
         {0.0,  0.0},   // v1
         {1.0,  0.0},   // v2
@@ -267,13 +290,13 @@ TEST(ConvergenceUtility, ScaleInvariantCircumRadius_BaseScale)
     // f1: v1-v2-v3,  f2: v1-v3-v4
     std::vector<std::array<int, 3>> faces = { {0, 1, 2}, {0, 2, 3} };
 
-    // Einzelflächen-Prüfung (Java testGetTextureTriangleArea-Anforderung)
+    // Per-face check (Java testGetTextureTriangleArea requirement)
     EXPECT_NEAR(0.5, triangle_area_2d(verts[0], verts[1], verts[2]), 1e-10);
     EXPECT_NEAR(0.5, triangle_area_2d(verts[0], verts[2], verts[3]), 1e-10);
 
     auto [max_r, mean_r, sum_r] = scale_invariant_circumradius_stats(verts, faces);
 
-    // Erwartet: sin(π/4) = √2/2 für max und mean (beide Dreiecke identisch)
+    // Expected: sin(π/4) = √2/2 for max and mean (both triangles identical)
     EXPECT_NEAR(std::sin(M_PI / 4.0), max_r,  1e-10);
     EXPECT_NEAR(std::sin(M_PI / 4.0), mean_r, 1e-10);
     EXPECT_NEAR(2.0 * std::sin(M_PI / 4.0), sum_r, 1e-10);
@@ -281,7 +304,7 @@ TEST(ConvergenceUtility, ScaleInvariantCircumRadius_BaseScale)
 
 TEST(ConvergenceUtility, ScaleInvariantCircumRadius_HalvedByW2_SameResult)
 {
-    // Skalierung durch w=2: alle Positionen halbiert (homogene Koordinaten)
+    // Scaling by w=2: all positions halved (homogeneous coordinates)
     // pos_scaled = (T[0]/2, T[1]/2)
     std::vector<Eigen::Vector2d> verts = {
         {0.0,   0.0},   // v1/2
@@ -291,52 +314,200 @@ TEST(ConvergenceUtility, ScaleInvariantCircumRadius_HalvedByW2_SameResult)
     };
     std::vector<std::array<int, 3>> faces = { {0, 1, 2}, {0, 2, 3} };
 
-    // Flächen sind ein Viertel der ursprünglichen (Längen halbiert → Area / 4)
+    // Areas are one quarter of the original (lengths halved → Area / 4)
     EXPECT_NEAR(0.125, triangle_area_2d(verts[0], verts[1], verts[2]), 1e-10);
     EXPECT_NEAR(0.125, triangle_area_2d(verts[0], verts[2], verts[3]), 1e-10);
 
     auto [max_r, mean_r, sum_r] = scale_invariant_circumradius_stats(verts, faces);
 
-    // Skaleninvariante Größe muss identisch zu w=1 sein
+    // Scale-invariant quantity must be identical to the w=1 case
     EXPECT_NEAR(std::sin(M_PI / 4.0), max_r,  1e-10);
     EXPECT_NEAR(std::sin(M_PI / 4.0), mean_r, 1e-10);
     EXPECT_NEAR(2.0 * std::sin(M_PI / 4.0), sum_r, 1e-10);
 }
 
 // ════════════════════════════════════════════════════════════════════════════
-// Test 7 — HomologyTest: Genus-2 Homologie-Generatoren
+// Test 7 — HomologyTest: genus-2 homology generators
 //          Java: HomologyTest.testHomology
 //
-// GEBLOCKT — kein Genus-2-Testmesh vorhanden.
+// Java test:
-//
+//   CoHDS hds = TestUtility.readOBJ("brezel2.obj");  // genus-2 pretzel surface
-// Java-Test:
-//   CoHDS hds = TestUtility.readOBJ("brezel2.obj");  // Genus-2-Brezel-Fläche
 //   List<Set<CoEdge>> paths = getGeneratorPaths(hds.getVertex(0), weightAdapter);
-//   Assert.assertEquals(4, paths.size());             // 2g = 4 für g = 2
+//   Assert.assertEquals(4, paths.size());             // 2g = 4 for g = 2
 //
-// C++-Äquivalent (sobald entsprechendes Mesh verfügbar):
+// C++ equivalent:
-//   ConformalMesh mesh = load_mesh("brezel2.obj");    // oder make_genus2_surface()
+//   ConformalMesh mesh = load_mesh("code/data/obj/brezel2.obj");
 //   CutGraph cg = compute_cut_graph(mesh);
 //   EXPECT_EQ(4u, cg.cut_edge_indices.size());        // 2g = 4
 //   EXPECT_EQ(2,  cg.genus);
 //
-// TODO(Phase 8): Eine der folgenden Optionen implementieren und GTEST_SKIP entfernen:
+// Mesh: V=2622, F=5248, E=7872, χ=−2, genus=2.
-//   Option A — Programmatisch: mesh_builder.hpp um make_genus2_surface() erweitern.
+// Path via CONFORMALLAB_DATA_DIR (CMakeLists.txt: ${CMAKE_SOURCE_DIR}/data).
-//              Ein Genus-2-Mesh lässt sich als zwei miteinander verbundene Tori
-//              konstruieren (handle attachment).
-//   Option B — Dateibasiert: brezel2.obj aus dem Java-Projekt (Pfad:
-//              conformallab/src-test/.../brezel2.obj) via load_mesh importieren.
-//              Erfordert den Dateipfad zur Laufzeit als CMake-Variable.
 // ════════════════════════════════════════════════════════════════════════════
 
-TEST(HomologyGenerators, Genus2_FourGeneratorPaths_BLOCKED)
+TEST(HomologyGenerators, Genus2_FourCutEdges)
 {
-    GTEST_SKIP()
+    const std::string path = std::string(CONFORMALLAB_DATA_DIR) + "/obj/brezel2.obj";
-        << "TODO(Phase 8): Genus-2-Testmesh fehlt.\n"
+    ConformalMesh mesh;
-           "  Sobald mesh_builder.hpp make_genus2_surface() bereitstellt\n"
+    ASSERT_NO_THROW(mesh = load_mesh(path)) << "brezel2.obj not found at: " << path;
-           "  oder brezel2.obj via load_mesh importiert wird, hier prüfen:\n"
+
-           "    CutGraph cg = compute_cut_graph(mesh);\n"
+    // Topology check: genus-2 surface has χ = -2.
-           "    EXPECT_EQ(4u, cg.cut_edge_indices.size());  // 2g = 4 fuer g = 2\n"
+    EXPECT_EQ(-2, euler_characteristic(mesh));
-           "    EXPECT_EQ(2,  cg.genus);\n"
+
-           "  Java-Quelle: HomologyTest.testHomology (brezel2.obj, 4 Generatoren).";
+    // Tree-cotree algorithm must produce exactly 2g = 4 cut edges.
+    CutGraph cg = compute_cut_graph(mesh);
+    EXPECT_EQ(4u, cg.cut_edge_indices.size())
+        << "Genus-2 surface must have 2g = 4 cut edges (homology generators).";
+    EXPECT_EQ(2, cg.genus);
+}
+
+// ════════════════════════════════════════════════════════════════════════════
+// Tests 8–9 — EuclideanLayoutTest: edge-length preservation on tetraflat.obj
+//             Java: EuclideanLayoutTest.testDoLayout
+//
+// Java test:
+//   Vector u = new SparseVector(n);   // u = 0 (no conformal factor)
+//   EuclideanLayout.doLayout(hds, fun, u);
+//   for (CoEdge e : hds.getEdges())
+//       assertEquals(Pn.distanceBetween(s.P, t.P), Pn.distanceBetween(s.T, t.T), 1E-11);
+//
+// Meaning: with u=0 the conformal factor is 0, so ℓ̃ = ℓ (no deformation).
+//          The layout must reproduce the original 3D edge lengths exactly.
+// ════════════════════════════════════════════════════════════════════════════
+
+TEST(EuclideanLayout, DoLayout_TetraFlat_EdgeLengthsPreserved)
+{
+    const std::string path = std::string(CONFORMALLAB_DATA_DIR) + "/obj/tetraflat.obj";
+    ConformalMesh mesh;
+    ASSERT_NO_THROW(mesh = load_mesh(path)) << "tetraflat.obj not found at: " << path;
+
+    auto maps = setup_euclidean_maps(mesh);
+    compute_euclidean_lambda0_from_mesh(mesh, maps);
+
+    // u = 0: no conformal deformation — layout must preserve 3D edge lengths exactly.
+    // tetraflat.obj is an open mesh; pin boundary vertices, sequential DOFs interior.
+    int idx = 0;
+    for (auto v : mesh.vertices())
+        maps.v_idx[v] = mesh.is_border(v) ? -1 : idx++;
+    const int n = idx;
+    std::vector<double> x(static_cast<std::size_t>(n), 0.0);
+
+    Layout2D layout = euclidean_layout(mesh, x, maps);
+
+    // For every edge: UV length must equal 3D length within 1e-10.
+    for (auto e : mesh.edges()) {
+        auto h  = mesh.halfedge(e);
+        auto vs = mesh.source(h);
+        auto vt = mesh.target(h);
+
+        auto ps = mesh.point(vs);
+        auto pt = mesh.point(vt);
+        double l3d = std::sqrt(
+            (pt.x()-ps.x())*(pt.x()-ps.x()) +
+            (pt.y()-ps.y())*(pt.y()-ps.y()) +
+            (pt.z()-ps.z())*(pt.z()-ps.z()));
+
+        auto us = layout.uv[vs.idx()];
+        auto ut = layout.uv[vt.idx()];
+        double luv = (ut - us).norm();
+
+        EXPECT_NEAR(l3d, luv, 1e-10)
+            << "Edge " << e.idx() << ": 3D=" << l3d << " UV=" << luv;
+    }
+}
+
+// ════════════════════════════════════════════════════════════════════════════
+// Test 10 — EuclideanCyclicConvergenceTest: Newton on cathead.obj
+//           Java: EuclideanLayoutTest.testLayout02 (130-value regression on cathead.heml)
+//                 EuclideanCyclicConvergenceTest.testEuclideanConvergence
+//
+// Java test:
+//   EuclideanLayout.doLayout(hdsCat, fun, uCat);
+//   for (CoVertex v : interior vertices)
+//       assertEquals(2*PI, calculateAngleSum(v), 1E-6);
+//   for (CoEdge e : positiveEdges)
+//       assertEquals(fun.getNewLength(e, u), tLength, 1E-6);
+//
+// C++ equivalent: Newton converges on cathead.obj; interior angle sums ≈ 2π.
+// The 130-value u-vector from the Java test is cathead-topology-specific and
+// depends on vertex ordering in the Java CoHDS — not portable directly.
+// Instead we verify the same mathematical invariant: convergence + angle sums.
+// ════════════════════════════════════════════════════════════════════════════
+
+TEST(EuclideanLayout, CatHead_NewtonConverges_AngleSumsTwoPi)
+{
+    const std::string path = std::string(CONFORMALLAB_DATA_DIR) + "/obj/cathead.obj";
+    ConformalMesh mesh;
+    ASSERT_NO_THROW(mesh = load_mesh(path)) << "cathead.obj not found at: " << path;
+
+    auto maps = setup_euclidean_maps(mesh);
+    compute_euclidean_lambda0_from_mesh(mesh, maps);
+
+    // cathead.obj is an open mesh (boundary present).
+    // Pin boundary vertices (v_idx = -1), assign sequential DOFs to interior.
+    int idx = 0;
+    for (auto v : mesh.vertices())
+        maps.v_idx[v] = mesh.is_border(v) ? -1 : idx++;
+    const int n = idx;
+    ASSERT_GT(n, 0) << "No interior vertices found in cathead.obj";
+
+    enforce_gauss_bonnet(mesh, maps);
+
+    std::vector<double> x0(static_cast<std::size_t>(n), 0.0);
+
+    auto res = newton_euclidean(mesh, x0, maps, 1e-8, 200);
+    EXPECT_TRUE(res.converged)
+        << "Newton did not converge on cathead.obj (iterations=" << res.iterations
+        << ", |G|inf=" << res.grad_inf_norm << ")";
+    EXPECT_LT(res.grad_inf_norm, 1e-8);
+    EXPECT_LT(res.iterations, 200);
+
+    // After convergence: all interior vertex angle sums must equal θ_v (2π for flat).
+    // Matches Java: assertEquals(2*PI, calculateAngleSum(v), 1E-6) for interior v.
+    auto G_final = euclidean_gradient(mesh, res.x, maps);
+    for (std::size_t i = 0; i < G_final.size(); ++i)
+        EXPECT_NEAR(0.0, G_final[i], 1e-6)
+            << "Angle sum residual at DOF " << i << " = " << G_final[i];
+}
+
+// ════════════════════════════════════════════════════════════════════════════
+// Test 11 — SphericalConvergenceTest: Newton on octahedron
+//           Java: SphericalConvergenceTest.testSphericalConvergence
+//
+// Java test:
+//   FunctionalTest.createOctahedron(hds, aSet);
+//   // randomly perturb vertex radii (seed=1)
+//   prepareInvariantDataHyperbolicAndSpherical(functional, hds, aSet, u);
+//   optimizer.minimize(u, opt);
+//   for (CoVertex v) assertEquals(2*PI, sum of angles at v, 1E-8);
+//
+// C++: regular octahedron (all vertices on S², no perturbation), spherical Newton,
+// checks convergence + residual gradients (≡ angle deficit = 0 after convergence).
+// ════════════════════════════════════════════════════════════════════════════
+
+TEST(SphericalLayout, SphericalTetrahedron_NewtonConverges_AngleSumsTwoPi)
+{
+    // Build a spherical tetrahedron (genus 0, 4 vertices, 4 faces).
+    // Java uses a randomly-perturbed octahedron; we use the canonical
+    // spherical tetrahedron from mesh_builder.hpp for reproducibility.
+    ConformalMesh mesh = make_spherical_tetrahedron();
+
+    auto maps = setup_spherical_maps(mesh);
+    compute_lambda0_from_mesh(mesh, maps);  // SphericalMaps version
+    int n = assign_vertex_dof_indices(mesh, maps);  // pins gauge_vertex, assigns DOFs
+    // Note: enforce_gauss_bonnet not needed — natural theta from mesh satisfies Σ(2π-Θ)>0.
+
+    std::vector<double> x0(static_cast<std::size_t>(n), 0.0);
+
+    auto res = newton_spherical(mesh, x0, maps, 1e-8, 200);
+    EXPECT_TRUE(res.converged)
+        << "Spherical Newton did not converge (iterations=" << res.iterations
+        << ", |G|inf=" << res.grad_inf_norm << ")";
+    EXPECT_LT(res.grad_inf_norm, 1e-8);
+
+    // Angle sum residual = 0 after convergence (≡ each interior vertex has Σα = θ_v).
+    auto G_final = spherical_gradient(mesh, res.x, maps);
+    for (std::size_t i = 0; i < G_final.size(); ++i)
+        EXPECT_NEAR(0.0, G_final[i], 1e-6)
+            << "Spherical angle sum residual at DOF " << i << " = " << G_final[i];
 }

code/tests/cgal/test_hyper_ideal_functional.cpp

@@ -1,3 +1,6 @@
+// Copyright (c) 2024-2026 Tarik Moussa.
+// SPDX-License-Identifier: MIT
+
 // test_hyper_ideal_functional.cpp
 //
 // Phase 3b — HyperIdealFunctional ported to ConformalMesh.

code/tests/cgal/test_hyper_ideal_hessian.cpp

@@ -0,0 +1,340 @@
+// Copyright (c) 2024-2026 Tarik Moussa.
+// SPDX-License-Identifier: MIT
+
+// test_hyper_ideal_hessian.cpp
+//
+// Phase 9b — Hyper-ideal Hessian: block-FD vs full-FD cross-validation.
+//
+// The block-FD Hessian (Phase 9b) exploits the per-face locality of the
+// hyper-ideal functional to compute the Hessian as a sum of 6×6 per-face
+// blocks.  This file verifies:
+//
+//   1. Block-FD reproduces the full-FD Hessian to machine precision
+//      on tetrahedron (closed) and a 3-face open mesh.
+//   2. The result is symmetric and positive-semi-definite (Springborn
+//      2020 strict-convexity result).
+//   3. The kernel `face_angles_from_local_dofs` matches the existing
+//      `compute_face_angles` at the same DOFs — sanity that the pure
+//      refactor is non-regressing.
+//   4. Both Hessians agree with a from-scratch FD-of-energy reference
+//      at the same x.  (This is the highest-confidence cross-check.)
+
+#include "hyper_ideal_functional.hpp"
+#include "hyper_ideal_hessian.hpp"
+#include "mesh_builder.hpp"
+
+#include <Eigen/Eigenvalues>
+#include <gtest/gtest.h>
+#include <chrono>
+#include <iostream>
+#include <vector>
+
+using namespace conformallab;
+
+namespace {
+
+// Open 3-face mesh (tetrahedron minus one face) — exercises boundary edges.
+inline ConformalMesh make_open_3face_mesh()
+{
+    ConformalMesh mesh;
+    auto v0 = mesh.add_vertex(Point3( 1,  1,  1));
+    auto v1 = mesh.add_vertex(Point3( 1, -1, -1));
+    auto v2 = mesh.add_vertex(Point3(-1,  1, -1));
+    auto v3 = mesh.add_vertex(Point3(-1, -1,  1));
+    mesh.add_face(v0, v2, v1);
+    mesh.add_face(v0, v1, v3);
+    mesh.add_face(v0, v3, v2);
+    return mesh;
+}
+
+// Construct an x ≈ "natural" hyper-ideal initialisation:
+//   b_v  = 1 (positive log scale)
+//   a_e  = 0.5 (moderate intersection angle)
+inline std::vector<double> natural_x(const ConformalMesh& mesh,
+                                       const HyperIdealMaps& m)
+{
+    const int n = hyper_ideal_dimension(mesh, m);
+    std::vector<double> x(static_cast<std::size_t>(n), 0.0);
+    for (auto v : mesh.vertices()) {
+        int i = m.v_idx[v];
+        if (i >= 0) x[static_cast<std::size_t>(i)] = 1.0;
+    }
+    for (auto e : mesh.edges()) {
+        int i = m.e_idx[e];
+        if (i >= 0) x[static_cast<std::size_t>(i)] = 0.5;
+    }
+    return x;
+}
+
+} // anonymous namespace
+
+// ════════════════════════════════════════════════════════════════════════════
+// 1.  Pure helper face_angles_from_local_dofs reproduces compute_face_angles
+//
+// Refactor sanity check: the new pure 6→6 function must produce identical
+// (β₁,β₂,β₃,α₁₂,α₂₃,α₃₁) to the existing mesh-reading compute_face_angles.
+// ════════════════════════════════════════════════════════════════════════════
+
+TEST(HyperIdealHessian, PureHelperMatchesMeshHelper)
+{
+    auto mesh = make_tetrahedron();
+    auto m    = setup_hyper_ideal_maps(mesh);
+    const int n = assign_all_dof_indices(mesh, m);
+    auto x = natural_x(mesh, m);
+
+    for (auto f : mesh.faces()) {
+        FaceAngles fa = compute_face_angles(mesh, f, x, m);
+
+        // Read the 6 local DOFs the same way Block-FD does.
+        Halfedge_index h0 = mesh.halfedge(f);
+        Halfedge_index h1 = mesh.next(h0);
+        Halfedge_index h2 = mesh.next(h1);
+        Vertex_index v1 = mesh.source(h0);
+        Vertex_index v2 = mesh.source(h1);
+        Vertex_index v3 = mesh.source(h2);
+        Edge_index e12 = mesh.edge(h0);
+        Edge_index e23 = mesh.edge(h1);
+        Edge_index e31 = mesh.edge(h2);
+
+        FaceAngleOutputs o = face_angles_from_local_dofs(
+            dof_val(m.v_idx[v1], x), dof_val(m.v_idx[v2], x), dof_val(m.v_idx[v3], x),
+            dof_val(m.e_idx[e12], x), dof_val(m.e_idx[e23], x), dof_val(m.e_idx[e31], x),
+            m.v_idx[v1] >= 0, m.v_idx[v2] >= 0, m.v_idx[v3] >= 0);
+
+        EXPECT_NEAR(o.beta1, fa.beta1, 1e-14);
+        EXPECT_NEAR(o.beta2, fa.beta2, 1e-14);
+        EXPECT_NEAR(o.beta3, fa.beta3, 1e-14);
+        EXPECT_NEAR(o.alpha12, fa.alpha12, 1e-14);
+        EXPECT_NEAR(o.alpha23, fa.alpha23, 1e-14);
+        EXPECT_NEAR(o.alpha31, fa.alpha31, 1e-14);
+    }
+    (void)n;
+}
+
+// ════════════════════════════════════════════════════════════════════════════
+// 2.  Block-FD ≡ Full-FD  on closed tetrahedron
+// ════════════════════════════════════════════════════════════════════════════
+
+TEST(HyperIdealHessian, BlockFD_MatchesFullFD_ClosedTetrahedron)
+{
+    auto mesh = make_tetrahedron();
+    auto m    = setup_hyper_ideal_maps(mesh);
+    const int n = assign_all_dof_indices(mesh, m);
+    auto x = natural_x(mesh, m);
+
+    auto H_full  = hyper_ideal_hessian_sym         (mesh, x, m);
+    auto H_block = hyper_ideal_hessian_block_fd_sym(mesh, x, m);
+
+    Eigen::MatrixXd Df(H_full), Db(H_block);
+    const double diff = (Df - Db).cwiseAbs().maxCoeff();
+    EXPECT_LT(diff, 1e-8)
+        << "Block-FD diverges from Full-FD by " << diff << " on tetrahedron";
+
+    (void)n;
+}
+
+// ════════════════════════════════════════════════════════════════════════════
+// 3.  Block-FD ≡ Full-FD  on open 3-face mesh  (boundary code path)
+// ════════════════════════════════════════════════════════════════════════════
+
+TEST(HyperIdealHessian, BlockFD_MatchesFullFD_Open3FaceMesh)
+{
+    auto mesh = make_open_3face_mesh();
+    auto m    = setup_hyper_ideal_maps(mesh);
+    const int n = assign_all_dof_indices(mesh, m);
+    auto x = natural_x(mesh, m);
+
+    auto H_full  = hyper_ideal_hessian_sym         (mesh, x, m);
+    auto H_block = hyper_ideal_hessian_block_fd_sym(mesh, x, m);
+
+    Eigen::MatrixXd Df(H_full), Db(H_block);
+    const double diff = (Df - Db).cwiseAbs().maxCoeff();
+    EXPECT_LT(diff, 1e-8)
+        << "Block-FD diverges from Full-FD by " << diff << " on open 3-face mesh";
+
+    (void)n;
+}
+
+// ════════════════════════════════════════════════════════════════════════════
+// 4.  Block-FD ≡ Full-FD  with pinned DOFs  (partial-DOF code path)
+//
+// Tests the case where some DOFs are pinned (v_idx = -1).  Block-FD must
+// skip pinned columns/rows just like Full-FD does.
+// ════════════════════════════════════════════════════════════════════════════
+
+TEST(HyperIdealHessian, BlockFD_MatchesFullFD_PinnedDOFs)
+{
+    auto mesh = make_tetrahedron();
+    auto m    = setup_hyper_ideal_maps(mesh);
+
+    // Assign vertex DOFs only; leave edges pinned (a_e fixed at 0).
+    int idx = 0;
+    for (auto v : mesh.vertices()) m.v_idx[v] = idx++;
+    for (auto e : mesh.edges())    m.e_idx[e] = -1;
+    const int n = hyper_ideal_dimension(mesh, m);
+    ASSERT_EQ(n, 4);   // tetrahedron: 4 vertex DOFs, 0 edge DOFs
+
+    std::vector<double> x(static_cast<std::size_t>(n), 1.0);
+
+    auto H_full  = hyper_ideal_hessian_sym         (mesh, x, m);
+    auto H_block = hyper_ideal_hessian_block_fd_sym(mesh, x, m);
+
+    Eigen::MatrixXd Df(H_full), Db(H_block);
+    const double diff = (Df - Db).cwiseAbs().maxCoeff();
+    EXPECT_LT(diff, 1e-8) << "Block-FD diverges by " << diff << " with pinned edges";
+}
+
+// ════════════════════════════════════════════════════════════════════════════
+// 5.  PSD property (Springborn 2020 strict convexity)
+//
+// The hyper-ideal energy is strictly convex on its domain of validity, so
+// the Hessian is PSD at every interior point.  Both block-FD and full-FD
+// must report this consistently.
+// ════════════════════════════════════════════════════════════════════════════
+
+TEST(HyperIdealHessian, BlockFD_IsPSD)
+{
+    auto mesh = make_tetrahedron();
+    auto m    = setup_hyper_ideal_maps(mesh);
+    const int n = assign_all_dof_indices(mesh, m);
+    auto x = natural_x(mesh, m);
+
+    auto H = hyper_ideal_hessian_block_fd_sym(mesh, x, m);
+    Eigen::MatrixXd Hd(H);
+
+    // Symmetry to FD rounding tolerance.
+    EXPECT_LT((Hd - Hd.transpose()).cwiseAbs().maxCoeff(), 1e-10)
+        << "Block-FD Hessian should be symmetric after _sym normalisation";
+
+    // PSD via smallest eigenvalue.
+    Eigen::SelfAdjointEigenSolver<Eigen::MatrixXd> es(Hd);
+    EXPECT_GE(es.eigenvalues().minCoeff(), -1e-8)
+        << "Hyper-ideal Hessian must be PSD (Springborn 2020)";
+
+    (void)n;
+}
+
+// ════════════════════════════════════════════════════════════════════════════
+// 6.  Sparsity:  block-FD respects the 6-DOF-per-face locality
+//
+// Each non-zero (i,j) entry must correspond to a pair of DOFs that share at
+// least one face.  This is a structural correctness test independent of the
+// numerical values.
+// ════════════════════════════════════════════════════════════════════════════
+
+TEST(HyperIdealHessian, BlockFD_SparsityMatchesFaceAdjacency)
+{
+    auto mesh = make_open_3face_mesh();
+    auto m    = setup_hyper_ideal_maps(mesh);
+    const int n = assign_all_dof_indices(mesh, m);
+    auto x = natural_x(mesh, m);
+
+    auto H = hyper_ideal_hessian_block_fd(mesh, x, m);
+
+    // Build the "should-be-nonzero" mask from face adjacency.
+    std::vector<std::vector<bool>> face_pair(n, std::vector<bool>(n, false));
+    for (auto f : mesh.faces()) {
+        auto h0 = mesh.halfedge(f);
+        auto h1 = mesh.next(h0);
+        auto h2 = mesh.next(h1);
+        int idx[6] = {
+            m.v_idx[mesh.source(h0)],
+            m.v_idx[mesh.source(h1)],
+            m.v_idx[mesh.source(h2)],
+            m.e_idx[mesh.edge(h0)],
+            m.e_idx[mesh.edge(h1)],
+            m.e_idx[mesh.edge(h2)],
+        };
+        for (int i = 0; i < 6; ++i) {
+            if (idx[i] < 0) continue;
+            for (int j = 0; j < 6; ++j) {
+                if (idx[j] < 0) continue;
+                face_pair[idx[i]][idx[j]] = true;
+            }
+        }
+    }
+
+    // Every non-zero entry must come from a face-adjacent pair.
+    for (int k = 0; k < H.outerSize(); ++k) {
+        for (Eigen::SparseMatrix<double>::InnerIterator it(H, k); it; ++it) {
+            EXPECT_TRUE(face_pair[it.row()][it.col()])
+                << "Hessian nonzero at (" << it.row() << "," << it.col()
+                << ") between DOFs that share no face";
+        }
+    }
+}
+
+// ════════════════════════════════════════════════════════════════════════════
+// 7.  Performance: measure block-FD vs full-FD on a moderately-sized mesh
+//
+// Builds a "long" tetrahedron-strip mesh: V tetrahedron-cells joined along
+// shared faces.  Asserts the block-FD Hessian computes ≥ 3× faster than
+// the full-FD baseline.  This is the operational case for the Phase 9b
+// optimisation (the asymptotic ratio is ~ n/36, which grows linearly in
+// mesh size).  Wall-clock is printed for the record but the assertion
+// uses a conservative ratio so the test stays stable on slow CI hardware.
+// ════════════════════════════════════════════════════════════════════════════
+
+namespace {
+
+// Build a strip of `n_cells` connected tetrahedra (subdivision-like).
+// The resulting mesh has ~ 2*n_cells + 2 vertices, 4*n_cells faces.
+// (Approximation; the exact count depends on shared-vertex handling.)
+inline ConformalMesh make_tet_strip(int n_cells)
+{
+    ConformalMesh mesh;
+    // Lay out vertex chain at z=0 / z=1 alternating.
+    std::vector<Vertex_index> top, bot;
+    for (int i = 0; i <= n_cells; ++i) {
+        top.push_back(mesh.add_vertex(Point3(i,   0, 0)));
+        bot.push_back(mesh.add_vertex(Point3(i, 0.7, 0.5 * std::sin(0.3*i))));
+    }
+    // Add two triangles per cell (one row of "zig-zag" triangles).
+    for (int i = 0; i < n_cells; ++i) {
+        mesh.add_face(top[i],   bot[i],   top[i+1]);
+        mesh.add_face(bot[i],   bot[i+1], top[i+1]);
+    }
+    return mesh;
+}
+
+} // anonymous namespace
+
+TEST(HyperIdealHessian, BlockFD_FasterThanFullFD)
+{
+    // 100 cells → ~200 faces, ~200 vertex DOFs + ~300 edge DOFs ≈ 500 DOFs.
+    // Full-FD: 500 × 200 ≈ 100 k face evaluations
+    // Block-FD: 200 × 12 ≈ 2.4 k face evaluations
+    // Theoretical ratio: ~42×.  We assert ≥ 3× to leave wide CI tolerance.
+    auto mesh = make_tet_strip(100);
+    auto m    = setup_hyper_ideal_maps(mesh);
+    const int n = assign_all_dof_indices(mesh, m);
+    auto x = natural_x(mesh, m);
+
+    using clk = std::chrono::steady_clock;
+
+    auto t1 = clk::now();
+    auto H_full  = hyper_ideal_hessian         (mesh, x, m);
+    auto t2 = clk::now();
+    auto H_block = hyper_ideal_hessian_block_fd(mesh, x, m);
+    auto t3 = clk::now();
+
+    auto ms_full  = std::chrono::duration_cast<std::chrono::microseconds>(t2-t1).count();
+    auto ms_block = std::chrono::duration_cast<std::chrono::microseconds>(t3-t2).count();
+
+    std::cerr << "[HyperIdealHessian.BlockFD_FasterThanFullFD]"
+              << "  V=" << mesh.number_of_vertices()
+              << "  F=" << mesh.number_of_faces()
+              << "  DOFs=" << n
+              << "  full-FD: " << ms_full  << " µs"
+              << "  block-FD: " << ms_block << " µs"
+              << "  speed-up: " << (ms_block > 0 ? (double)ms_full / (double)ms_block : 0.0)
+              << "×\n";
+
+    // Both must report identical Hessians (within FD rounding).
+    Eigen::MatrixXd Df(H_full), Db(H_block);
+    EXPECT_LT((Df - Db).cwiseAbs().maxCoeff(), 1e-8);
+
+    // Conservative speed-up assertion — typically observe ~30×, accept ≥ 3×.
+    EXPECT_GE(ms_full, 3 * ms_block)
+        << "Block-FD should be at least 3× faster than full-FD on this mesh";
+}

code/tests/cgal/test_inversive_distance_functional.cpp

@@ -0,0 +1,265 @@
+// Copyright (c) 2024-2026 Tarik Moussa.
+// SPDX-License-Identifier: MIT
+
+// test_inversive_distance_functional.cpp
+//
+// Phase 9a.2 — Inversive-distance functional (Luo 2004) tests.
+//
+// Validation against three mathematical references:
+//
+//   [Luo 2004]        ℓ_ij² = exp(2u_i) + exp(2u_j) + 2 I_ij exp(u_i+u_j)
+//                     ∂E/∂u_v = Θ_v − Σ α_v   (Lemma 3.1)
+//
+//   [BS 2004]         I_ij = (ℓ² − r_i² − r_j²) / (2 r_i r_j)
+//                     I = 1 ⇒ tangential circles
+//                     I = 0 ⇒ orthogonal circles
+//
+//   [Glickenstein 2011 §5]
+//                     correspondence to BPS-2010 face-based CP:
+//                     I_ij = cos θ_e on the face-dual mesh
+//
+// No Java reference exists for this functional in
+// de.varylab.discreteconformal.  Cross-validation is done via:
+//   1. FD-vs-analytic gradient check (numerical),
+//   2. Luo's edge-length identity check (mathematical),
+//   3. Tangential-limit identity I=1 ⇒ ℓ = r_i+r_j (geometric).
+
+#include "inversive_distance_functional.hpp"
+#include "euclidean_functional.hpp"
+#include "mesh_builder.hpp"
+#include "conformal_mesh.hpp"
+
+#include <gtest/gtest.h>
+#include <vector>
+#include <random>
+#include <cmath>
+
+using namespace conformallab;
+
+// ════════════════════════════════════════════════════════════════════════════
+// 1.  Edge-length formula  (Luo 2004 §3)
+//
+//   ℓ² = exp(2u_i) + exp(2u_j) + 2 I exp(u_i+u_j)
+//      = r_i² + r_j² + 2 I r_i r_j
+//
+// Special cases:
+//   I = 1  ⇒ ℓ² = (r_i + r_j)²  ⇒  ℓ = r_i + r_j     (tangential)
+//   I = 0  ⇒ ℓ² = r_i² + r_j²    (orthogonal — circles meet at 90°)
+//   I = −1 ⇒ ℓ² = (r_i − r_j)²  ⇒  ℓ = |r_i − r_j|  (inside-tangent)
+// ════════════════════════════════════════════════════════════════════════════
+
+TEST(InversiveDistanceFunctional, EdgeLengthFormula_TangentialLimit)
+{
+    // ui = 0 ⇒ ri = 1;  uj = log(2) ⇒ rj = 2;  I = 1 (tangential):
+    //   ℓ² = 1 + 4 + 2·1·1·2 = 9 ⇒ ℓ = 3 = r_i + r_j ✓
+    double l2 = id_detail::edge_length_squared(0.0, std::log(2.0), 1.0);
+    EXPECT_NEAR(std::sqrt(l2), 3.0, 1e-12);
+}
+
+TEST(InversiveDistanceFunctional, EdgeLengthFormula_OrthogonalLimit)
+{
+    // r_i = 3, r_j = 4, I = 0:  ℓ² = 9 + 16 = 25 ⇒ ℓ = 5  (Pythagorean)
+    double l2 = id_detail::edge_length_squared(std::log(3.0), std::log(4.0), 0.0);
+    EXPECT_NEAR(std::sqrt(l2), 5.0, 1e-12);
+}
+
+TEST(InversiveDistanceFunctional, EdgeLengthFormula_InsideTangentLimit)
+{
+    // r_i = 2, r_j = 5, I = −1:  ℓ² = (5 − 2)² = 9 ⇒ ℓ = 3
+    double l2 = id_detail::edge_length_squared(std::log(2.0), std::log(5.0), -1.0);
+    EXPECT_NEAR(std::sqrt(l2), 3.0, 1e-12);
+}
+
+TEST(InversiveDistanceFunctional, EdgeLengthFormula_DegenerateReturnsMinusOne)
+{
+    // r_i = r_j = 1, I = −2:  ℓ² = 1 + 1 − 4 = −2  (impossible packing)
+    double l2 = id_detail::edge_length_squared(0.0, 0.0, -2.0);
+    EXPECT_EQ(l2, -1.0) << "should signal degenerate packing";
+}
+
+// ════════════════════════════════════════════════════════════════════════════
+// 2.  Bowers-Stephenson identity round-trip
+//
+//   Given (ℓ, r_i, r_j), the I_ij that compute_init produces must satisfy
+//   Luo's edge-length formula exactly: ℓ²(I_ij, r_i, r_j) = ℓ².
+// ════════════════════════════════════════════════════════════════════════════
+
+TEST(InversiveDistanceFunctional, BowersStephensonRoundTrip)
+{
+    auto mesh = make_triangle();   // (0,0,0)-(1,0,0)-(0,1,0)
+    auto m    = setup_inversive_distance_maps(mesh);
+    compute_inversive_distance_init_from_mesh(mesh, m);
+
+    // At u = 0, exp(u) = r0.  Reconstruct ℓ from (r_i, r_j, I_ij) and compare
+    // to the 3-D Euclidean edge length from the mesh.
+    for (auto e : mesh.edges()) {
+        auto h = mesh.halfedge(e);
+        auto p1 = mesh.point(mesh.source(h));
+        auto p2 = mesh.point(mesh.target(h));
+        double dx = p1.x() - p2.x();
+        double dy = p1.y() - p2.y();
+        double dz = p1.z() - p2.z();
+        double l_3d = std::sqrt(dx*dx + dy*dy + dz*dz);
+
+        double ri = m.r0[mesh.source(h)];
+        double rj = m.r0[mesh.target(h)];
+        double l2_reconstructed = ri*ri + rj*rj + 2.0 * m.I_e[e] * ri * rj;
+        EXPECT_NEAR(std::sqrt(l2_reconstructed), l_3d, 1e-12)
+            << "Bowers-Stephenson round-trip failed for an edge";
+    }
+}
+
+// ════════════════════════════════════════════════════════════════════════════
+// 3.  Properties of the init step
+// ════════════════════════════════════════════════════════════════════════════
+
+TEST(InversiveDistanceFunctional, InitProducesValidPositiveRadii)
+{
+    auto mesh = make_tetrahedron();
+    auto m    = setup_inversive_distance_maps(mesh);
+    compute_inversive_distance_init_from_mesh(mesh, m);
+
+    for (auto v : mesh.vertices()) {
+        EXPECT_GT(m.r0[v], 0.0) << "init radius must be positive";
+        EXPECT_TRUE(std::isfinite(m.r0[v]));
+    }
+    for (auto e : mesh.edges()) {
+        EXPECT_TRUE(std::isfinite(m.I_e[e]));
+        // I > −1 is required for any valid inversive-distance packing.
+        EXPECT_GT(m.I_e[e], -1.0);
+    }
+}
+
+// ════════════════════════════════════════════════════════════════════════════
+// 4.  Gradient at the "natural equilibrium" is zero by construction
+//
+// Same trick as in test_euclidean_functional.cpp:
+//   • Set u = 0  ⇒  r = r0  ⇒  ℓ = ℓ_3d  (Bowers-Stephenson round-trip)
+//   • Compute G(0) — that's the angle defect Θ − Σ_actual.
+//   • Subtract G(0) from Θ → new G(0) is zero.
+// This means u = 0 is now the Newton equilibrium of the functional, just
+// like in the euclidean functional natural-theta trick.
+// ════════════════════════════════════════════════════════════════════════════
+
+TEST(InversiveDistanceFunctional, NaturalThetaGivesZeroGradientAtU0)
+{
+    auto mesh = make_triangle();
+    auto m    = setup_inversive_distance_maps(mesh);
+    compute_inversive_distance_init_from_mesh(mesh, m);
+
+    // Assign DOFs to all vertices.
+    int n = 0;
+    for (auto v : mesh.vertices()) m.v_idx[v] = n++;
+    std::vector<double> x(static_cast<std::size_t>(n), 0.0);
+
+    auto G0 = inversive_distance_gradient(mesh, x, m);
+    for (auto v : mesh.vertices()) {
+        int i = m.v_idx[v];
+        m.theta_v[v] -= G0[static_cast<std::size_t>(i)];
+    }
+
+    auto G_eq = inversive_distance_gradient(mesh, x, m);
+    for (double g : G_eq) EXPECT_NEAR(g, 0.0, 1e-13);
+}
+
+// ════════════════════════════════════════════════════════════════════════════
+// 5.  FD-vs-analytic gradient check (the main acceptance test for the port)
+//
+// Pattern: identical to test_euclidean_functional.cpp's
+// GradientCheck_TriangleVertex (lines 137-149).  The energy is the path
+// integral of the gradient (by construction); a consistent FD-vs-analytic
+// match validates both energy and gradient implementations together.
+// ════════════════════════════════════════════════════════════════════════════
+
+TEST(InversiveDistanceFunctional, FDGradientCheck_Triangle)
+{
+    auto mesh = make_triangle();
+    auto m    = setup_inversive_distance_maps(mesh);
+    compute_inversive_distance_init_from_mesh(mesh, m);
+
+    int n = 0;
+    for (auto v : mesh.vertices()) m.v_idx[v] = n++;
+
+    // Small perturbation u_v ≈ −0.1 keeps every triangle valid.
+    std::vector<double> x(static_cast<std::size_t>(n), -0.1);
+    EXPECT_TRUE(gradient_check_inversive_distance(mesh, x, m))
+        << "FD gradient mismatch on single triangle (u = −0.1)";
+}
+
+TEST(InversiveDistanceFunctional, FDGradientCheck_QuadStrip)
+{
+    auto mesh = make_quad_strip();
+    auto m    = setup_inversive_distance_maps(mesh);
+    compute_inversive_distance_init_from_mesh(mesh, m);
+
+    int n = 0;
+    for (auto v : mesh.vertices()) m.v_idx[v] = n++;
+
+    std::vector<double> x(static_cast<std::size_t>(n), -0.15);
+    EXPECT_TRUE(gradient_check_inversive_distance(mesh, x, m))
+        << "FD gradient mismatch on quad strip";
+}
+
+TEST(InversiveDistanceFunctional, FDGradientCheck_Tetrahedron)
+{
+    auto mesh = make_tetrahedron();
+    auto m    = setup_inversive_distance_maps(mesh);
+    compute_inversive_distance_init_from_mesh(mesh, m);
+
+    int n = 0;
+    for (auto v : mesh.vertices()) m.v_idx[v] = n++;
+
+    std::vector<double> x(static_cast<std::size_t>(n), -0.2);
+    EXPECT_TRUE(gradient_check_inversive_distance(mesh, x, m))
+        << "FD gradient mismatch on regular tetrahedron";
+}
+
+// ════════════════════════════════════════════════════════════════════════════
+// 6.  Cross-validation with euclidean_functional.hpp
+//
+// The two functionals are DIFFERENT geometric models.  At u = 0 with their
+// natural inits both produce a valid triangulation, but the per-edge length
+// is different:
+//   • Euclidean:           ℓ = ℓ_3d                  (exact, by lambda0 init)
+//   • Inversive distance:  ℓ = ℓ_3d                  (exact, by BS round-trip)
+//
+// HOWEVER the GRADIENT at u = 0 differs because the chain rule ∂ℓ/∂u is
+// different.  Specifically:
+//   • Euclidean:           ∂(2 log ℓ)/∂u_i = 1
+//   • Inversive distance:  ∂(2 log ℓ)/∂u_i = (r_i² + I r_i r_j) / ℓ²
+//
+// This test pins one quantitative consequence: at u = 0 both gradients have
+// the SAME angle-defect structure Θ − Σ_actual.  After applying the natural-
+// theta trick on each, both must be at equilibrium with G(0) = 0.
+// ════════════════════════════════════════════════════════════════════════════
+
+TEST(InversiveDistanceFunctional, AngleDefectAtU0_AgreesWithEuclideanAtU0)
+{
+    auto mesh = make_quad_strip();
+
+    // ── Inversive distance side ────────────────────────────────────────────
+    auto m_id = setup_inversive_distance_maps(mesh);
+    compute_inversive_distance_init_from_mesh(mesh, m_id);
+    int n_id = 0;
+    for (auto v : mesh.vertices()) m_id.v_idx[v] = n_id++;
+    std::vector<double> x_id(static_cast<std::size_t>(n_id), 0.0);
+    auto G_id = inversive_distance_gradient(mesh, x_id, m_id);
+
+    // ── Euclidean side (same mesh, same DOF order) ─────────────────────────
+    auto m_eu = setup_euclidean_maps(mesh);
+    compute_euclidean_lambda0_from_mesh(mesh, m_eu);
+    int n_eu = 0;
+    for (auto v : mesh.vertices()) m_eu.v_idx[v] = n_eu++;
+    std::vector<double> x_eu(static_cast<std::size_t>(n_eu), 0.0);
+    auto G_eu = euclidean_gradient(const_cast<ConformalMesh&>(mesh), x_eu, m_eu);
+
+    // Both should report the same actual angle sum per vertex at u = 0
+    // (since both reproduce ℓ = ℓ_3d at u = 0).  Therefore  Θ − Σ_actual
+    // is identical for the two functionals (Θ default 2π in both).
+    ASSERT_EQ(G_id.size(), G_eu.size());
+    for (std::size_t i = 0; i < G_id.size(); ++i) {
+        EXPECT_NEAR(G_id[i], G_eu[i], 1e-10)
+            << "angle-defect mismatch at u=0, DOF " << i
+            << ": id=" << G_id[i] << "  eu=" << G_eu[i];
+    }
+}

code/tests/cgal/test_layout.cpp

@@ -1,3 +1,6 @@
+// Copyright (c) 2024-2026 Tarik Moussa.
+// SPDX-License-Identifier: MIT
+
 // test_layout.cpp
 //
 // Phase 5 — Layout / embedding tests.

code/tests/cgal/test_mesh_io.cpp

@@ -1,3 +1,6 @@
+// Copyright (c) 2024-2026 Tarik Moussa.
+// SPDX-License-Identifier: MIT
+
 // test_mesh_io.cpp
 //
 // Phase 4b — CGAL::IO mesh round-trip tests.

code/tests/cgal/test_newton_phase9a.cpp

@@ -0,0 +1,267 @@
+// Copyright (c) 2024-2026 Tarik Moussa.
+// SPDX-License-Identifier: MIT
+
+// test_newton_phase9a.cpp
+//
+// Phase 9a Newton solvers — convergence tests for the two new
+// circle-packing functionals.
+//
+// Validates that:
+//   • newton_cp_euclidean()        — face-based BPS-2010 functional.
+//   • newton_inversive_distance()  — vertex-based Luo-2004 functional.
+// both reach a Newton equilibrium (‖G‖∞ < 1e-8) in < 30 iterations
+// on a range of test meshes, and that the converged solution satisfies
+// the relevant geometric invariants.
+
+#include "newton_solver.hpp"
+#include "cp_euclidean_functional.hpp"
+#include "inversive_distance_functional.hpp"
+#include "mesh_builder.hpp"
+#include "conformal_mesh.hpp"
+
+#include <gtest/gtest.h>
+#include <vector>
+
+using namespace conformallab;
+
+namespace {
+
+// Open 3-face mesh (tetrahedron minus one face) — exercises boundary edges.
+inline ConformalMesh make_open_3face_mesh()
+{
+    ConformalMesh mesh;
+    auto v0 = mesh.add_vertex(Point3( 1,  1,  1));
+    auto v1 = mesh.add_vertex(Point3( 1, -1, -1));
+    auto v2 = mesh.add_vertex(Point3(-1,  1, -1));
+    auto v3 = mesh.add_vertex(Point3(-1, -1,  1));
+    mesh.add_face(v0, v2, v1);
+    mesh.add_face(v0, v1, v3);
+    mesh.add_face(v0, v3, v2);
+    return mesh;
+}
+
+} // anonymous
+
+// ════════════════════════════════════════════════════════════════════════════
+// 1. CP-Euclidean Newton — orthogonal circle packing
+//
+// Setup matches CPEuclideanFunctionalTest.java (Java parity at the
+// solver level): θ_e = π/2 everywhere, φ_f = 2π for all faces.  Use
+// the "natural-phi" trick (analog of natural-theta in Euclidean):
+// adjust φ so that ρ = 0 is the natural equilibrium → Newton must
+// converge in zero iterations.
+// ════════════════════════════════════════════════════════════════════════════
+
+TEST(NewtonPhase9a, CPEuclidean_NaturalPhi_ClosedTetrahedron_ConvergesInZeroIterations)
+{
+    auto mesh = make_tetrahedron();
+    auto m    = setup_cp_euclidean_maps(mesh);
+    const int n = assign_cp_euclidean_face_dof_indices(mesh, m);
+    ASSERT_EQ(n, 3);
+
+    // Natural-phi: shift φ_f so the gradient at ρ = 0 is zero.
+    std::vector<double> x0(static_cast<std::size_t>(n), 0.0);
+    auto G0 = cp_euclidean_gradient(mesh, x0, m);
+    for (auto f : mesh.faces()) {
+        int i = m.f_idx[f];
+        if (i < 0) continue;
+        m.phi_f[f] -= G0[static_cast<std::size_t>(i)];
+    }
+
+    auto res = newton_cp_euclidean(mesh, x0, m);
+    EXPECT_TRUE(res.converged);
+    EXPECT_EQ(res.iterations, 0)
+        << "natural-phi pre-shift should make x=0 the equilibrium";
+    EXPECT_LT(res.grad_inf_norm, 1e-10);
+    for (double r : res.x) EXPECT_NEAR(r, 0.0, 1e-12);
+}
+
+// ════════════════════════════════════════════════════════════════════════════
+// 2. CP-Euclidean Newton — perturbed equilibrium converges back to 0
+//
+// Same setup as test 1, but start from a small perturbation.  The
+// strictly-convex BPS-2010 energy means Newton must converge back
+// to the natural-phi equilibrium ρ = 0.
+// ════════════════════════════════════════════════════════════════════════════
+
+TEST(NewtonPhase9a, CPEuclidean_PerturbedStart_ConvergesBackToEquilibrium)
+{
+    auto mesh = make_tetrahedron();
+    auto m    = setup_cp_euclidean_maps(mesh);
+    const int n = assign_cp_euclidean_face_dof_indices(mesh, m);
+
+    // Apply natural-phi (equilibrium at ρ=0).
+    std::vector<double> x0_zero(static_cast<std::size_t>(n), 0.0);
+    auto G0 = cp_euclidean_gradient(mesh, x0_zero, m);
+    for (auto f : mesh.faces()) {
+        int i = m.f_idx[f];
+        if (i < 0) continue;
+        m.phi_f[f] -= G0[static_cast<std::size_t>(i)];
+    }
+
+    // Start from a perturbation.
+    std::vector<double> x0 = {0.1, -0.2, 0.15};
+    auto res = newton_cp_euclidean(mesh, x0, m);
+
+    EXPECT_TRUE(res.converged);
+    EXPECT_LT(res.iterations, 30);
+    EXPECT_LT(res.grad_inf_norm, 1e-8);
+    // Strictly-convex unique minimum → converges back to ρ=0.
+    for (double r : res.x) EXPECT_NEAR(r, 0.0, 1e-6);
+}
+
+// ════════════════════════════════════════════════════════════════════════════
+// 3. CP-Euclidean Newton — open mesh (boundary edges)
+// ════════════════════════════════════════════════════════════════════════════
+
+TEST(NewtonPhase9a, CPEuclidean_OpenTetrahedron_NaturalPhi_Converges)
+{
+    auto mesh = make_open_3face_mesh();
+    auto m    = setup_cp_euclidean_maps(mesh);
+    const int n = assign_cp_euclidean_face_dof_indices(mesh, m);
+    ASSERT_EQ(n, 2);
+
+    std::vector<double> x0(static_cast<std::size_t>(n), 0.0);
+    auto G0 = cp_euclidean_gradient(mesh, x0, m);
+    for (auto f : mesh.faces()) {
+        int i = m.f_idx[f];
+        if (i < 0) continue;
+        m.phi_f[f] -= G0[static_cast<std::size_t>(i)];
+    }
+
+    auto res = newton_cp_euclidean(mesh, x0, m);
+    EXPECT_TRUE(res.converged);
+    EXPECT_LT(res.iterations, 30);
+    EXPECT_LT(res.grad_inf_norm, 1e-8);
+}
+
+// ════════════════════════════════════════════════════════════════════════════
+// 4. Inversive-Distance Newton — natural-theta on triangle
+//
+// At u = 0, Bowers-Stephenson init reproduces the input edge lengths
+// exactly.  Natural-theta then shifts Θ so the gradient is zero, making
+// u = 0 the equilibrium.  Newton must converge in zero iterations.
+// ════════════════════════════════════════════════════════════════════════════
+
+TEST(NewtonPhase9a, InversiveDistance_NaturalTheta_Triangle_ConvergesInZero)
+{
+    auto mesh = make_triangle();
+    auto m    = setup_inversive_distance_maps(mesh);
+    compute_inversive_distance_init_from_mesh(mesh, m);
+
+    int n = 0;
+    for (auto v : mesh.vertices()) m.v_idx[v] = n++;
+
+    std::vector<double> x0(static_cast<std::size_t>(n), 0.0);
+    auto G0 = inversive_distance_gradient(mesh, x0, m);
+    for (auto v : mesh.vertices()) {
+        int i = m.v_idx[v];
+        m.theta_v[v] -= G0[static_cast<std::size_t>(i)];
+    }
+
+    auto res = newton_inversive_distance(mesh, x0, m);
+    EXPECT_TRUE(res.converged);
+    EXPECT_EQ(res.iterations, 0);
+    EXPECT_LT(res.grad_inf_norm, 1e-10);
+    for (double u : res.x) EXPECT_NEAR(u, 0.0, 1e-12);
+}
+
+// ════════════════════════════════════════════════════════════════════════════
+// 5. Inversive-Distance Newton — perturbed start on quad strip
+// ════════════════════════════════════════════════════════════════════════════
+
+TEST(NewtonPhase9a, InversiveDistance_PerturbedQuadStrip_Converges)
+{
+    auto mesh = make_quad_strip();
+    auto m    = setup_inversive_distance_maps(mesh);
+    compute_inversive_distance_init_from_mesh(mesh, m);
+
+    // Pin vertex 0; index the rest.
+    auto vit = mesh.vertices().begin();
+    m.v_idx[*vit++] = -1;
+    int n = 0;
+    for (; vit != mesh.vertices().end(); ++vit) m.v_idx[*vit] = n++;
+
+    // Natural-theta with the pin in place.
+    std::vector<double> x0(static_cast<std::size_t>(n), 0.0);
+    auto G0 = inversive_distance_gradient(mesh, x0, m);
+    for (auto v : mesh.vertices()) {
+        int i = m.v_idx[v];
+        if (i >= 0) m.theta_v[v] -= G0[static_cast<std::size_t>(i)];
+    }
+
+    // Perturb away from the equilibrium and watch it return.
+    std::vector<double> x_pert(static_cast<std::size_t>(n), -0.05);
+    auto res = newton_inversive_distance(mesh, x_pert, m);
+
+    EXPECT_TRUE(res.converged);
+    EXPECT_LT(res.iterations, 30);
+    EXPECT_LT(res.grad_inf_norm, 1e-8);
+    // Strictly-convex unique minimum on the open domain → back to 0.
+    for (double u : res.x) EXPECT_NEAR(u, 0.0, 1e-6);
+}
+
+// ════════════════════════════════════════════════════════════════════════════
+// 6. Inversive-Distance Newton — tetrahedron (closed mesh)
+// ════════════════════════════════════════════════════════════════════════════
+
+TEST(NewtonPhase9a, InversiveDistance_PerturbedTetrahedron_Converges)
+{
+    auto mesh = make_tetrahedron();
+    auto m    = setup_inversive_distance_maps(mesh);
+    compute_inversive_distance_init_from_mesh(mesh, m);
+
+    // Closed mesh — pin one vertex to remove the gauge mode.
+    auto vit = mesh.vertices().begin();
+    m.v_idx[*vit++] = -1;
+    int n = 0;
+    for (; vit != mesh.vertices().end(); ++vit) m.v_idx[*vit] = n++;
+
+    std::vector<double> x0(static_cast<std::size_t>(n), 0.0);
+    auto G0 = inversive_distance_gradient(mesh, x0, m);
+    for (auto v : mesh.vertices()) {
+        int i = m.v_idx[v];
+        if (i >= 0) m.theta_v[v] -= G0[static_cast<std::size_t>(i)];
+    }
+
+    std::vector<double> x_pert(static_cast<std::size_t>(n), -0.1);
+    auto res = newton_inversive_distance(mesh, x_pert, m);
+
+    EXPECT_TRUE(res.converged);
+    EXPECT_LT(res.iterations, 30);
+    EXPECT_LT(res.grad_inf_norm, 1e-8);
+}
+
+// ════════════════════════════════════════════════════════════════════════════
+// 7. CP-Euclidean Newton — uses analytic Hessian (NOT FD)
+//
+// Regression guard: verify the solver actually calls cp_euclidean_hessian
+// (the analytic 2×2-per-edge formula) rather than degenerating to a
+// per-iteration FD pass.  If iteration count exceeds a tight upper bound
+// for a tiny mesh, that would suggest a slow inner Hessian computation
+// or a wrong-sign mistake.
+// ════════════════════════════════════════════════════════════════════════════
+
+TEST(NewtonPhase9a, CPEuclidean_UsesAnalyticHessian)
+{
+    auto mesh = make_tetrahedron();
+    auto m    = setup_cp_euclidean_maps(mesh);
+    const int n = assign_cp_euclidean_face_dof_indices(mesh, m);
+
+    std::vector<double> x0(static_cast<std::size_t>(n), 0.0);
+    auto G0 = cp_euclidean_gradient(mesh, x0, m);
+    for (auto f : mesh.faces()) {
+        int i = m.f_idx[f];
+        if (i < 0) continue;
+        m.phi_f[f] -= G0[static_cast<std::size_t>(i)];
+    }
+
+    // Strong perturbation — quadratic Newton with analytic Hessian
+    // should still converge in a handful of iterations.
+    std::vector<double> x_pert = {0.5, -0.4, 0.3};
+    auto res = newton_cp_euclidean(mesh, x_pert, m);
+
+    EXPECT_TRUE(res.converged);
+    EXPECT_LE(res.iterations, 10)
+        << "analytic Hessian: expect very fast convergence on a 3-DOF problem";
+}

code/tests/cgal/test_newton_solver.cpp

@@ -1,3 +1,6 @@
+// Copyright (c) 2024-2026 Tarik Moussa.
+// SPDX-License-Identifier: MIT
+
 // test_newton_solver.cpp
 //
 // Phase 4 — Newton solver tests.

code/tests/cgal/test_phase6.cpp

@@ -1,3 +1,6 @@
+// Copyright (c) 2024-2026 Tarik Moussa.
+// SPDX-License-Identifier: MIT
+
 // test_phase6.cpp
 //
 // Phase 6 — Tests for:

code/tests/cgal/test_phase7.cpp

@@ -1,3 +1,6 @@
+// Copyright (c) 2024-2026 Tarik Moussa.
+// SPDX-License-Identifier: MIT
+
 // test_phase7.cpp
 //
 // Phase 7 — Tests for Java-parity layout features:

code/tests/cgal/test_pipeline.cpp

@@ -1,3 +1,6 @@
+// Copyright (c) 2024-2026 Tarik Moussa.
+// SPDX-License-Identifier: MIT
+
 // test_pipeline.cpp
 //
 // Phase 4c — End-to-end pipeline tests and library-user examples.

code/tests/cgal/test_scalability_smoke.cpp

@@ -0,0 +1,204 @@
+// Copyright (c) 2024-2026 Tarik Moussa.
+// SPDX-License-Identifier: MIT
+
+// test_scalability_smoke.cpp
+//
+// Scalability smoke tests — convergence on large real-world meshes.
+//
+// PURPOSE
+//   These tests verify that the Newton solver converges correctly on meshes
+//   significantly larger than the unit tests (which use tiny synthetic meshes).
+//   They do NOT assert on wall-clock time — timing is printed for information
+//   only, so the tests remain stable on slow CI hardware (Raspberry Pi ARM64).
+//
+//   If Newton fails to converge here, it is a correctness regression, not a
+//   performance regression.  See doc/math/complexity.md for timing context.
+//
+// MESHES USED
+//   cathead.obj   V=131,  F=248,  genus=0, open  — small, sanity check
+//   brezel.obj    V=6910, F=13824, genus=2, closed — large genus-2 mesh (χ=−2)
+//   brezel2.obj   V=2622, F=5248,  genus=2, closed — smaller genus-2 mesh (χ=−2)
+//
+// NOTE: both brezel meshes are genus-2. The naming follows the Java original
+// where "brezel2" is a different triangulation, not a different genus.
+//
+// EXPECTED RESULTS
+//   Newton converges in < 30 iterations for all Euclidean meshes (strictly
+//   convex energy, quadratic convergence from u=0).
+//   Cut graph produces 2g seam edges: 2 for brezel, 4 for brezel2.
+//
+// Tests:
+//   1. SmokeEuclidean.CatHead_SmallOpen
+//   2. SmokeEuclidean.Brezel_LargeGenus2
+//   3. SmokeEuclidean.Brezel2_Genus2_CutGraph
+
+#include "conformal_mesh.hpp"
+#include "mesh_io.hpp"
+#include "euclidean_functional.hpp"
+#include "gauss_bonnet.hpp"
+#include "newton_solver.hpp"
+#include "cut_graph.hpp"
+#include <gtest/gtest.h>
+#include <chrono>
+#include <iostream>
+#include <vector>
+#include <cmath>
+#include <string>
+
+using namespace conformallab;
+using Clock = std::chrono::steady_clock;
+using Ms    = std::chrono::milliseconds;
+
+// ── Helpers ──────────────────────────────────────────────────────────────────
+
+static int setup_open_mesh_dofs(ConformalMesh& mesh, EuclideanMaps& maps)
+{
+    int idx = 0;
+    for (auto v : mesh.vertices())
+        maps.v_idx[v] = mesh.is_border(v) ? -1 : idx++;
+    return idx;
+}
+
+static int setup_closed_mesh_dofs(ConformalMesh& mesh, EuclideanMaps& maps)
+{
+    auto vit = mesh.vertices().begin();
+    maps.v_idx[*vit++] = -1;
+    int idx = 0;
+    for (; vit != mesh.vertices().end(); ++vit)
+        maps.v_idx[*vit] = idx++;
+    return idx;
+}
+
+static void apply_natural_theta(ConformalMesh& mesh, EuclideanMaps& maps, int n)
+{
+    std::vector<double> x0(static_cast<std::size_t>(n), 0.0);
+    auto G0 = euclidean_gradient(mesh, x0, maps);
+    for (auto v : mesh.vertices()) {
+        int iv = maps.v_idx[v];
+        if (iv >= 0) maps.theta_v[v] -= G0[static_cast<std::size_t>(iv)];
+    }
+}
+
+// ── Test 1 — cathead.obj (V=131, F=248, open) ────────────────────────────────
+
+TEST(SmokeEuclidean, CatHead_SmallOpen)
+{
+    const std::string path = std::string(CONFORMALLAB_DATA_DIR) + "/obj/cathead.obj";
+    ConformalMesh mesh;
+    ASSERT_NO_THROW(mesh = load_mesh(path)) << "cathead.obj not found: " << path;
+
+    EXPECT_EQ(131u, mesh.number_of_vertices());
+    EXPECT_EQ(248u, mesh.number_of_faces());
+
+    auto maps = setup_euclidean_maps(mesh);
+    compute_euclidean_lambda0_from_mesh(mesh, maps);
+    const int n = setup_open_mesh_dofs(mesh, maps);
+    apply_natural_theta(mesh, maps, n);
+
+    // Start from a small perturbation so Newton actually iterates.
+    std::vector<double> x0(static_cast<std::size_t>(n), -0.05);
+
+    auto t0 = Clock::now();
+    auto res = newton_euclidean(mesh, x0, maps, 1e-9, 200);
+    auto dt  = std::chrono::duration_cast<Ms>(Clock::now() - t0).count();
+
+    std::cout << "[SmokeEuclidean.CatHead] V=" << mesh.number_of_vertices()
+              << " F=" << mesh.number_of_faces()
+              << " iter=" << res.iterations
+              << " ||G||=" << res.grad_inf_norm
+              << " time=" << dt << "ms\n";
+
+    EXPECT_TRUE(res.converged)   << "Newton did not converge on cathead.obj";
+    EXPECT_LT(res.iterations, 30) << "Newton took ≥ 30 iterations — unexpected";
+    EXPECT_LT(res.grad_inf_norm, 1e-8);
+}
+
+// ── Test 2 — brezel.obj (V=6910, F=13824, genus=2) ───────────────────────────
+// Primary scalability target: largest mesh in the test suite.
+// Newton is started from a small perturbation (x0 = −0.05) so it must
+// actually iterate rather than exit immediately from the trivial equilibrium.
+
+TEST(SmokeEuclidean, Brezel_LargeGenus2)
+{
+    const std::string path = std::string(CONFORMALLAB_DATA_DIR) + "/obj/brezel.obj";
+    ConformalMesh mesh;
+    ASSERT_NO_THROW(mesh = load_mesh(path)) << "brezel.obj not found: " << path;
+
+    EXPECT_EQ(6910u,  mesh.number_of_vertices());
+    EXPECT_EQ(13824u, mesh.number_of_faces());
+
+    // Euler characteristic: V - E + F = −2 for genus-2 closed surface
+    const int chi = static_cast<int>(mesh.number_of_vertices())
+                  - static_cast<int>(mesh.number_of_edges())
+                  + static_cast<int>(mesh.number_of_faces());
+    EXPECT_EQ(-2, chi) << "brezel.obj must be genus-2 (χ=−2)";
+
+    auto maps = setup_euclidean_maps(mesh);
+    compute_euclidean_lambda0_from_mesh(mesh, maps);
+
+    const int n = setup_closed_mesh_dofs(mesh, maps);
+    enforce_gauss_bonnet(mesh, maps);
+    apply_natural_theta(mesh, maps, n);
+
+    // Start from a small perturbation so Newton actually iterates.
+    std::vector<double> x0(static_cast<std::size_t>(n), -0.05);
+
+    // Newton solve
+    auto t0  = Clock::now();
+    auto res = newton_euclidean(mesh, x0, maps, 1e-9, 200);
+    auto dt_newton = std::chrono::duration_cast<Ms>(Clock::now() - t0).count();
+
+    // Cut graph
+    auto t1  = Clock::now();
+    CutGraph cg = compute_cut_graph(mesh);
+    auto dt_cut = std::chrono::duration_cast<Ms>(Clock::now() - t1).count();
+
+    std::cout << "[SmokeEuclidean.Brezel] V=" << mesh.number_of_vertices()
+              << " F=" << mesh.number_of_faces()
+              << " iter=" << res.iterations
+              << " ||G||=" << res.grad_inf_norm
+              << " newton=" << dt_newton << "ms"
+              << " cut=" << dt_cut << "ms\n";
+
+    EXPECT_TRUE(res.converged)    << "Newton did not converge on brezel.obj";
+    EXPECT_LT(res.iterations, 30) << "Newton took ≥ 30 iterations";
+    EXPECT_LT(res.grad_inf_norm, 1e-8);
+
+    // Genus-2: 2g = 4 seam edges
+    EXPECT_EQ(4u, cg.cut_edge_indices.size())
+        << "brezel.obj (genus 2) must yield 2g=4 cut edges";
+    EXPECT_EQ(2, cg.genus);
+}
+
+// ── Test 3 — brezel2.obj (V=2622, F=5248, genus=2) ───────────────────────────
+
+TEST(SmokeEuclidean, Brezel2_Genus2_CutGraph)
+{
+    const std::string path = std::string(CONFORMALLAB_DATA_DIR) + "/obj/brezel2.obj";
+    ConformalMesh mesh;
+    ASSERT_NO_THROW(mesh = load_mesh(path)) << "brezel2.obj not found: " << path;
+
+    EXPECT_EQ(2622u, mesh.number_of_vertices());
+    EXPECT_EQ(5248u, mesh.number_of_faces());
+
+    const int chi = static_cast<int>(mesh.number_of_vertices())
+                  - static_cast<int>(mesh.number_of_edges())
+                  + static_cast<int>(mesh.number_of_faces());
+    EXPECT_EQ(-2, chi) << "brezel2.obj must be genus-2 (χ=−2)";
+
+    // Cut graph only — Newton on genus-2 requires full DOF setup
+    // (tested separately in test_geometry_utils.cpp HomologyGenerators suite)
+    auto t0  = Clock::now();
+    CutGraph cg = compute_cut_graph(mesh);
+    auto dt_cut = std::chrono::duration_cast<Ms>(Clock::now() - t0).count();
+
+    std::cout << "[SmokeEuclidean.Brezel2] V=" << mesh.number_of_vertices()
+              << " F=" << mesh.number_of_faces()
+              << " cut=" << dt_cut << "ms"
+              << " seams=" << cg.cut_edge_indices.size() << "\n";
+
+    // Genus-2: 2g = 4 seam edges
+    EXPECT_EQ(4u, cg.cut_edge_indices.size())
+        << "brezel2.obj (genus 2) must yield 2g=4 cut edges";
+    EXPECT_EQ(2, cg.genus);
+}

code/tests/cgal/test_spherical_functional.cpp

@@ -1,3 +1,6 @@
+// Copyright (c) 2024-2026 Tarik Moussa.
+// SPDX-License-Identifier: MIT
+
 // test_spherical_functional.cpp  (Phase 3c + 3e)
 //
 // Phase 3c — SphericalFunctional ported to ConformalMesh.
@@ -6,7 +9,7 @@
 //
 // Test map (Java → C++)
 // ──────────────────────
-//   testHessian (Ignored)         → GradientCheck_Hessian     (SKIPPED)
+//   testHessian (Ignored)         → GradientCheck_Hessian     (ported)
 //   testGradientWithHyperIdeal…   → GradientCheck_OctaFaceVertex   (ported)
 //   testGradientInExtendedDomain  → GradientCheck_SpherTetVertex    (ported)
 //   testGradientWithHyperelliptic → GradientCheck_SpherTetAllDofs   (ported)
@@ -23,6 +26,7 @@
 #include "conformal_mesh.hpp"
 #include "mesh_builder.hpp"
 #include "spherical_functional.hpp"
+#include "spherical_hessian.hpp"
 #include <gtest/gtest.h>
 #include <cmath>
 #include <vector>
@@ -30,12 +34,29 @@
 using namespace conformallab;
 
 // ════════════════════════════════════════════════════════════════════════════
-// @Ignore in Java: no Hessian implemented
+// Cross-module Hessian check: spherical_gradient() ↔ spherical_hessian()
+//
+// Java @Ignore reason: "no Hessian implemented" — the Java functional test
+// was written before the Hessian existed.  In C++ the analytic spherical
+// Hessian (spherical_hessian.hpp, Phase 3f) is complete.
+//
+// This test verifies cross-module consistency between the functional and
+// the Hessian module.  The spherical Hessian is NSD (negative semi-definite)
+// because the spherical energy is concave — hessian_check_spherical() uses
+// the sign-corrected FD check appropriate for the spherical case.
 // ════════════════════════════════════════════════════════════════════════════
 
 TEST(SphericalFunctional, GradientCheck_Hessian)
 {
-    GTEST_SKIP() << "@Ignore in Java – Hessian not implemented";
+    auto mesh = make_spherical_tetrahedron();
+    auto maps = setup_spherical_maps(mesh);
+    compute_lambda0_from_mesh(mesh, maps);
+    int n = assign_vertex_dof_indices(mesh, maps);
+
+    std::vector<double> x(static_cast<std::size_t>(n), -0.2);
+
+    EXPECT_TRUE(hessian_check_spherical(mesh, x, maps))
+        << "Cross-module: spherical_gradient() and spherical_hessian() are inconsistent";
 }
 
 // ════════════════════════════════════════════════════════════════════════════

code/tests/cgal/test_spherical_hessian.cpp

@@ -1,3 +1,6 @@
+// Copyright (c) 2024-2026 Tarik Moussa.
+// SPDX-License-Identifier: MIT
+
 // test_spherical_hessian.cpp
 //
 // Phase 3f — Spherical cotangent-Laplace Hessian.

code/tests/test_clausen.cpp

@@ -1,3 +1,6 @@
+// Copyright (c) 2024-2026 Tarik Moussa.
+// SPDX-License-Identifier: MIT
+
 // Port of de.varylab.discreteconformal.functional.ClausenTest (Java/JUnit).
 // Reference values computed with Mathematica.
 

code/tests/test_discrete_elliptic_utility.cpp

@@ -1,3 +1,6 @@
+// Copyright (c) 2024-2026 Tarik Moussa.
+// SPDX-License-Identifier: MIT
+
 // Port of de.varylab.discreteconformal.util.DiscreteEllipticUtilityTest (Java/JUnit).
 // Tests the normalizeModulus function that moves a complex number tau into the
 // fundamental domain of the modular group SL(2,Z).

code/tests/test_hyper_ideal_functional.cpp

@@ -1,37 +0,0 @@
-// Stub for de.varylab.discreteconformal.functional.HyperIdealFunctionalTest (Java/JUnit).
-//
-// STATUS: BLOCKED – requires HDS port (Phase 4).
-//
-// These tests evaluate gradient and Hessian of the HyperIdealFunctional on
-// actual mesh data (CoHDS + HyperIdealGenerator).  They cannot be ported
-// until the HalfEdge data structure (CoHDS), the functional evaluation
-// framework, and the mesh generators are available in C++.
-//
-// Java tests and their status:
-//   testHessian()                           – @Ignore in Java (skipped here too)
-//   testGradientWithHyperIdealAndIdealPoints – blocked: needs HDS
-//   testGradientInTheExtendedDomain          – blocked: needs HDS
-//   testGradientWithHyperellipticCurve       – blocked: needs HDS
-//   testFunctionalAtNaNValue                 – blocked: needs HDS
-
-#include <gtest/gtest.h>
-
-TEST(HyperIdealFunctionalTest, TestHessian_IgnoredInJava) {
-    GTEST_SKIP() << "@Ignore in Java – skipped here too";
-}
-
-TEST(HyperIdealFunctionalTest, GradientWithHyperIdealAndIdealPoints) {
-    GTEST_SKIP() << "Blocked: requires HDS port (CoHDS + HyperIdealFunctional)";
-}
-
-TEST(HyperIdealFunctionalTest, GradientInTheExtendedDomain) {
-    GTEST_SKIP() << "Blocked: requires HDS port (CoHDS + HyperIdealFunctional)";
-}
-
-TEST(HyperIdealFunctionalTest, GradientWithHyperellipticCurve) {
-    GTEST_SKIP() << "Blocked: requires HDS port (CoHDS + HyperIdealFunctional)";
-}
-
-TEST(HyperIdealFunctionalTest, FunctionalAtNaNValue) {
-    GTEST_SKIP() << "Blocked: requires HDS port (CoHDS + HyperIdealFunctional)";
-}

code/tests/test_hyper_ideal_hyperelliptic_utility.cpp

@@ -1,26 +0,0 @@
-// Stub for de.varylab.discreteconformal.functional.HyperIdealHyperellipticUtilityTest.
-//
-// STATUS: BLOCKED – requires HDS port (Phase 4).
-//
-// Tests compute intersection angles of circles associated with hyper-ideal
-// vertices using CoHDS + HalfEdgeUtils.  All three tests operate on mesh
-// data structures that are not yet available in C++.
-//
-// Java tests and their status:
-//   testCalculateCircleIntersections         – blocked: needs CoHDS + HalfEdgeUtils
-//   testCalculateCircleIntersectionsInfinite – blocked: needs CoHDS + HalfEdgeUtils
-//   testLawsonHyperellipticAngles            – blocked: needs CoHDS + HyperIdealGenerator
-
-#include <gtest/gtest.h>
-
-TEST(HyperIdealHyperellipticUtilityTest, CalculateCircleIntersections) {
-    GTEST_SKIP() << "Blocked: requires HDS port (CoHDS + HalfEdgeUtils)";
-}
-
-TEST(HyperIdealHyperellipticUtilityTest, CalculateCircleIntersectionsInfinite) {
-    GTEST_SKIP() << "Blocked: requires HDS port (CoHDS + HalfEdgeUtils)";
-}
-
-TEST(HyperIdealHyperellipticUtilityTest, LawsonHyperellipticAngles) {
-    GTEST_SKIP() << "Blocked: requires HDS port (CoHDS + HyperIdealGenerator)";
-}

code/tests/test_hyper_ideal_utility.cpp

@@ -1,3 +1,6 @@
+// Copyright (c) 2024-2026 Tarik Moussa.
+// SPDX-License-Identifier: MIT
+
 // Port of de.varylab.discreteconformal.functional.HyperIdealUtilityTest (Java/JUnit).
 
 #include "hyper_ideal_utility.hpp"

code/tests/test_hyper_ideal_visualization_utility.cpp

@@ -1,3 +1,6 @@
+// Copyright (c) 2024-2026 Tarik Moussa.
+// SPDX-License-Identifier: MIT
+
 // Port of de.varylab.discreteconformal.plugin.HyperIdealVisualizationPluginTest (Java/JUnit).
 //
 // Tests the conversion from a hyperbolic circle (hyperboloid model)