Deploy 0f87067

.claude/hooks/init-sync-check.sh

@@ -0,0 +1,108 @@
+#!/usr/bin/env bash
+#
+# SessionStart init check — git sync verification for marota-fork sessions.
+#
+# Runs automatically at the start of every Claude Code session. It performs a
+# REAL `git fetch` of the repository's default branch and reports whether the
+# current working branch is in sync with it (ahead / behind counts), so a new
+# session never assumes it is up to date based on a possibly-stale local
+# `origin/<default>` ref.
+#
+# Design contract:
+#   * READ-ONLY   — never mutates the working tree, index, or any branch
+#                   (only `git fetch`, which updates remote-tracking refs).
+#   * NON-FATAL   — any failure (no network, no git, detached HEAD, …) exits 0
+#                   so it can never block or break session startup.
+#   * SCOPED      — only emits the detailed check for `marota/*` origins, per
+#                   the "starting a new session from a marota fork" request;
+#                   a no-op for every other remote.
+#   * SYNCHRONOUS — fast (one time-boxed fetch); stdout is surfaced to the
+#                   session as startup context.
+#
+set -uo pipefail
+
+# Drain hook stdin (SessionStart passes a JSON payload we don't need) so the
+# pipe closes cleanly.
+cat >/dev/null 2>&1 || true
+
+repo_root="${CLAUDE_PROJECT_DIR:-$(git rev-parse --show-toplevel 2>/dev/null || true)}"
+[ -z "${repo_root}" ] && exit 0
+cd "${repo_root}" 2>/dev/null || exit 0
+
+# Only act inside a git work tree.
+git rev-parse --is-inside-work-tree >/dev/null 2>&1 || exit 0
+
+origin_url="$(git remote get-url origin 2>/dev/null || true)"
+
+# Guard: only run for marota forks. Everything else is a silent no-op.
+case "${origin_url}" in
+  *marota/*) : ;;
+  *) exit 0 ;;
+esac
+
+# Resolve the default branch: origin/HEAD -> `git remote show` -> main.
+default_branch="$(git symbolic-ref --quiet --short refs/remotes/origin/HEAD 2>/dev/null | sed 's#^origin/##')"
+if [ -z "${default_branch}" ]; then
+  default_branch="$(git remote show origin 2>/dev/null | sed -n 's/.*HEAD branch: //p' | head -1)"
+fi
+[ -z "${default_branch}" ] && default_branch="main"
+
+current_branch="$(git rev-parse --abbrev-ref HEAD 2>/dev/null || echo '(detached)')"
+
+# Do a REAL fetch — never trust the local origin ref. Time-boxed + non-fatal.
+fetch_status="ok"
+if command -v timeout >/dev/null 2>&1; then
+  timeout 60 git fetch --quiet origin "${default_branch}" 2>/dev/null || fetch_status="failed"
+else
+  git fetch --quiet origin "${default_branch}" 2>/dev/null || fetch_status="failed"
+fi
+
+counts="$(git rev-list --left-right --count "origin/${default_branch}...HEAD" 2>/dev/null || true)"
+behind="$(printf '%s' "${counts}" | awk '{print $1}')"
+ahead="$(printf '%s' "${counts}" | awk '{print $2}')"
+
+echo "── Session init: git sync check (marota fork) ─────────────────────────"
+echo "repo:            $(basename "${repo_root}")"
+echo "current branch:  ${current_branch}"
+echo "default branch:  origin/${default_branch}"
+echo "origin fetch:    ${fetch_status}"
+if [ -n "${counts}" ]; then
+  echo "vs origin/${default_branch}:  ${behind:-?} behind, ${ahead:-?} ahead"
+  if [ "${behind:-0}" -gt 0 ] 2>/dev/null; then
+    echo "ACTION: branch is BEHIND origin/${default_branch} by ${behind} commit(s)."
+    echo "        Rebase onto the latest default before pushing follow-up work:"
+    echo "          git fetch origin ${default_branch} && git rebase origin/${default_branch}"
+  elif [ "${ahead:-0}" -eq 0 ] 2>/dev/null; then
+    echo "STATUS: in sync — branch tip equals origin/${default_branch}"
+    echo "        (fresh branch, no unmerged work). If a prior PR for this branch"
+    echo "        was already merged, treat new work as a fresh change on this base."
+  else
+    echo "STATUS: ${ahead} local commit(s) ahead of origin/${default_branch}, 0 behind — up to date."
+  fi
+else
+  echo "NOTE: could not compute ahead/behind (origin/${default_branch} missing or fetch failed)."
+fi
+echo "PRINCIPLE: always run a real 'git fetch' to confirm sync against the remote —"
+echo "           do not rely on a possibly-stale local origin ref."
+echo "───────────────────────────────────────────────────────────────────────"
+
+# ── PR target reminder ─────────────────────────────────────────────────
+# Pull requests for Co-Study4Grid are opened SYSTEMATICALLY on the upstream
+# `ainetus` repo (base = ainetus default branch, head = marota:<branch>),
+# never on the `marota` fork. A cross-fork PR into `ainetus` can only be
+# CREATED from a session that has the `ainetus` repo in scope, and
+# cross-tier repo adds are blocked mid-session — so a marota-only session
+# CANNOT open the PR (the create step fails with an access-denied error).
+echo "── PR target: ALWAYS ainetus (upstream), never the marota fork ────────"
+echo "  * Open PRs against ainetus/Co-Study4Grid (base = its default branch,"
+echo "    head = marota:<branch>). Same rule for Expert_op4grid_recommender."
+echo "  * To create one, START THE SESSION with ainetus/Co-Study4Grid (and"
+echo "    ainetus/Expert_op4grid_recommender) as the INITIAL sources — a"
+echo "    session rooted only at marota cannot add ainetus later (cross-tier"
+echo "    add is blocked) and the PR step will fail access-denied."
+echo "  * From a marota-only session: push the branch, then hand off a ready"
+echo "    PR compare link:"
+echo "    https://github.com/ainetus/Co-Study4Grid/compare/${default_branch}...marota:<branch>?expand=1"
+echo "───────────────────────────────────────────────────────────────────────"
+
+exit 0

.claude/settings.json

@@ -0,0 +1,14 @@
+{
+  "hooks": {
+    "SessionStart": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "$CLAUDE_PROJECT_DIR/.claude/hooks/init-sync-check.sh"
+          }
+        ]
+      }
+    ]
+  }
+}

.dockerignore

@@ -0,0 +1,33 @@
+# Build artifacts / caches — rebuilt inside the image.
+frontend/node_modules
+frontend/dist
+frontend/dist-standalone
+**/__pycache__
+**/*.pyc
+**/*.pyo
+
+# Local virtualenvs.
+venv
+.venv
+env
+
+# VCS / CI / editor.
+.git
+.github
+.circleci
+.idea
+.vscode
+
+# Runtime + report output (regenerated at runtime).
+Overflow_Graph
+reports
+test-results
+
+# Docs and the frozen legacy mirror are not needed at runtime.
+docs
+standalone_interface_legacy.html
+
+# Test suites are dead weight in the runtime image (QW25) — the app never
+# imports them, and `COPY expert_backend/` would otherwise carry tests/ along.
+expert_backend/tests
+expert_backend/test_backend.py

.editorconfig

@@ -0,0 +1,15 @@
+root = true
+
+[*]
+charset = utf-8
+end_of_line = lf
+insert_final_newline = true
+trim_trailing_whitespace = true
+indent_style = space
+indent_size = 4
+
+[*.{ts,tsx,js,jsx,mjs,cjs,json,yml,yaml,html,css,md}]
+indent_size = 2
+
+[Makefile]
+indent_style = tab

.env.example

@@ -0,0 +1,32 @@
+# Co-Study4Grid backend environment variables
+# Copy to `.env` (ignored by git) or export directly in your shell.
+
+# Comma-separated list of allowed CORS origins. Default (unset): the local
+# Vite dev/preview origins on loopback (localhost/127.0.0.1 :5173 and :4173).
+# Set to the browser origin of the frontend in non-local deployments, e.g.
+#   CORS_ALLOWED_ORIGINS=https://costudy.example.com,https://ops.example.com
+# Wide-open dev mode is now explicit opt-in (a wildcard lets any web page read
+# /api/* off a localhost backend):
+#   CORS_ALLOWED_ORIGINS=*
+# CORS_ALLOWED_ORIGINS=
+
+# Deployment lockdown (D7): when truthy (1/true/yes/on), disable the
+# desktop-era filesystem RPCs (custom config-file path, session
+# save/list/load, native file picker) with a 403 {code: LOCKED_DOWN}.
+# The Dockerfile sets this for the public HuggingFace Space; leave it
+# unset for local/dev installs. Read-only app config stays available.
+# COSTUDY4GRID_LOCKDOWN=1
+
+# pypowsybl load-flow fast mode toggle (also set per-study from the UI).
+# Unset or empty = default; "1" / "true" = enabled; "0" / "false" = disabled.
+# PYPOWSYBL_FAST_MODE=
+
+# Optional log level for the FastAPI process (DEBUG, INFO, WARNING, ERROR).
+# LOG_LEVEL=INFO
+
+# Persistent data root for the Game Mode shared solution base (retained
+# propositions + novelty/frequency stats). On a HuggingFace Space with
+# persistent storage, set it to /data. Unset = repo-local ./game_solutions.
+# COSTUDY4GRID_DATA_DIR=
+# Explicit override of the solution-base directory (wins over the data root).
+# COSTUDY4GRID_GAME_SOLUTIONS_DIR=

.gitattributes

@@ -0,0 +1,7 @@
+# Binary assets are stored via Git LFS / HuggingFace Xet so they can be pushed
+# to a HuggingFace Space (its git endpoint rejects non-LFS binary files).
+# Run `git lfs install` once; see deploy/huggingface/SETUP.md.
+*.zip filter=lfs diff=lfs merge=lfs -text
+*.png filter=lfs diff=lfs merge=lfs -text
+*.jpg filter=lfs diff=lfs merge=lfs -text
+*.jpeg filter=lfs diff=lfs merge=lfs -text

.github/workflows/canary.yml

@@ -0,0 +1,34 @@
+name: Recommender canary
+
+# QW8: PR/deploy installs pin expert_op4grid_recommender (recommender-pin.txt).
+# This weekly canary floats to the LATEST release and runs the backend suite,
+# so a breaking upstream release surfaces here (a red canary = "bump the pin
+# after checking") instead of turning an unrelated PR red or shipping a
+# regressed image on a zero-change rebuild.
+
+on:
+  schedule:
+    - cron: '0 6 * * 1'   # Mondays 06:00 UTC
+  workflow_dispatch: {}
+
+jobs:
+  canary:
+    name: Backend tests against latest recommender
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Set up Python 3.10
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.10"
+          cache: 'pip'
+      - name: Install dependencies (float recommender to latest)
+        run: |
+          python -m pip install --upgrade pip
+          pip install ".[test]"
+          # Deliberately NOT pinned: resolve the newest published release.
+          pip install --no-deps --no-cache-dir --upgrade "expert_op4grid_recommender"
+      - name: Show resolved recommender version
+        run: pip show expert_op4grid_recommender | grep -i version
+      - name: Run backend Pytest (excluding graphviz-dependent tests)
+        run: pytest --ignore=expert_backend/tests/test_overflow_html_dim_logic.py

.github/workflows/code-quality.yml

@@ -0,0 +1,64 @@
+name: Code Quality
+
+on:
+  push:
+    branches: [main]
+  # Run on every PR regardless of its base branch (e.g. PRs stacked onto a
+  # `claude/*` working branch, not just those targeting main).
+  pull_request:
+    branches: ['**']
+
+jobs:
+  gate:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python 3.10
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.10"
+
+      - name: Install quality tooling
+        run: |
+          python -m pip install --upgrade pip
+          pip install ".[quality]"
+          pip install pytest
+
+      - name: Run ruff (lightweight lint)
+        run: ruff check expert_backend scripts
+
+      - name: Run code-quality gate
+        run: python scripts/check_code_quality.py
+
+      - name: Run docs-tree gate (D9)
+        # Fails when a CLAUDE.md reference points at a file that no longer exists
+        # or reintroduces a rotting `file.py:NNN` line anchor. See
+        # docs/architecture/code-quality-analysis.md §23.
+        run: python scripts/check_docs_tree.py
+
+      - name: Run reporter + docs-tree unit tests
+        run: pytest scripts/test_code_quality_report.py scripts/test_check_docs_tree.py -q
+
+      - name: Run mypy (gate)
+        # GATES the build: the shared-state base (services/_recommender_state.py)
+        # makes the mixin composition type-check cleanly, so mypy is at 0 and
+        # any new type error fails CI (see pyproject [tool.mypy] + §19).
+        run: mypy
+
+      - name: Generate report artifacts
+        run: |
+          python scripts/code_quality_report.py \
+            --output reports/code-quality.json \
+            --markdown reports/code-quality.md
+
+      - name: Publish report to workflow summary
+        if: always()
+        run: cat reports/code-quality.md >> "$GITHUB_STEP_SUMMARY"
+
+      - name: Upload report
+        uses: actions/upload-artifact@v4
+        with:
+          name: code-quality-report
+          path: reports/
+          retention-days: 30

.github/workflows/deploy-huggingface.yml

@@ -0,0 +1,124 @@
+name: Deploy to HuggingFace Space
+
+# Redeploys the HuggingFace Docker Space on every merge to main (a merged
+# PR pushes to main). Mirrors the manual flow in deploy/huggingface/SETUP.md:
+# HF's git endpoint rejects the >10 MiB .xiidm blobs that sit in branch
+# *history*, so we push ONE squashed, history-free commit of the current
+# tree (large binaries ride along via Git LFS).
+#
+# Required repo configuration (Settings → Secrets and variables → Actions):
+#   - secret  HF_TOKEN     : a HuggingFace WRITE access token with access to the Space
+#   - variable HF_SPACE    : the Space path, e.g. "your-user/co-study4grid-game"
+#   - variable HF_USERNAME : (optional) the token owner's HF username — only
+#                            needed when the Space lives under an ORG and so
+#                            differs from the owner part of HF_SPACE.
+#
+# The job no-ops (does not fail) when HF_TOKEN / HF_SPACE are absent, so the
+# workflow is inert until you opt in by setting them.
+
+# Test-gated (D7): deploy runs ONLY after the "Tests" workflow completes
+# successfully on main — a green build is the gate, not just a merge. A
+# manual `workflow_dispatch` (optionally from an older commit) is the
+# rollback path; see deploy/huggingface/SETUP.md → "Rolling back".
+on:
+  workflow_run:
+    workflows: [ "Tests" ]
+    types: [ completed ]
+    branches: [ main ]
+  workflow_dispatch: {}
+
+# Never run two deploys at once; the latest merge wins.
+concurrency:
+  group: huggingface-space-deploy
+  cancel-in-progress: true
+
+permissions:
+  contents: write   # push the per-deploy rollback tag back to origin
+
+jobs:
+  deploy:
+    name: Push snapshot to HF Space
+    runs-on: ubuntu-latest
+    # workflow_run fires on completion regardless of result — only deploy a
+    # SUCCESSFUL Tests run. workflow_dispatch always proceeds (rollback).
+    if: >-
+      github.event_name == 'workflow_dispatch' ||
+      github.event.workflow_run.conclusion == 'success'
+    steps:
+      - name: Check the deploy is configured
+        id: guard
+        env:
+          HF_TOKEN: ${{ secrets.HF_TOKEN }}
+          HF_SPACE: ${{ vars.HF_SPACE }}
+        run: |
+          if [ -z "$HF_TOKEN" ] || [ -z "$HF_SPACE" ]; then
+            echo "::notice::HF_TOKEN secret and/or HF_SPACE variable not set — skipping deploy."
+            echo "configured=false" >> "$GITHUB_OUTPUT"
+          else
+            echo "configured=true" >> "$GITHUB_OUTPUT"
+          fi
+
+      # The tested commit: the head of the Tests run (workflow_run), or the
+      # dispatched ref (workflow_dispatch / rollback).
+      - name: Resolve the deployed commit
+        if: steps.guard.outputs.configured == 'true'
+        id: sha
+        run: echo "sha=${{ github.event.workflow_run.head_sha || github.sha }}" >> "$GITHUB_OUTPUT"
+
+      - name: Checkout the tested tree + LFS objects
+        if: steps.guard.outputs.configured == 'true'
+        uses: actions/checkout@v4
+        with:
+          ref: ${{ steps.sha.outputs.sha }}
+          lfs: true
+          fetch-depth: 1   # an orphan snapshot only needs the current tree
+
+      - name: Configure git + LFS
+        if: steps.guard.outputs.configured == 'true'
+        run: |
+          git lfs install --local
+          git config user.name  "github-actions[bot]"
+          git config user.email "github-actions[bot]@users.noreply.github.com"
+
+      - name: Build a history-free snapshot
+        if: steps.guard.outputs.configured == 'true'
+        env:
+          DEPLOY_SHA: ${{ steps.sha.outputs.sha }}
+        run: |
+          cp deploy/huggingface/README.md README.md   # HF needs the frontmatter at repo root
+          git checkout --orphan hf-deploy
+          git add -A
+          # Drop inert local dev artifacts from the deployed snapshot.
+          git rm -q --cached --ignore-unmatch \
+            .claude/plan.md profiling_patch_results.json || true
+          git commit -q -m "Deploy ${DEPLOY_SHA::7}"
+          test "$(git rev-list --count HEAD)" -eq 1   # sanity: exactly one commit
+
+      - name: Push to the HuggingFace Space
+        if: steps.guard.outputs.configured == 'true'
+        env:
+          HF_TOKEN: ${{ secrets.HF_TOKEN }}
+          HF_SPACE: ${{ vars.HF_SPACE }}
+          HF_USERNAME: ${{ vars.HF_USERNAME }}
+          DEPLOY_SHA: ${{ steps.sha.outputs.sha }}
+        run: |
+          user="${HF_USERNAME:-${HF_SPACE%%/*}}"
+          # The token is a GitHub secret → masked in logs even inside the URL.
+          git remote add space "https://${user}:${HF_TOKEN}@huggingface.co/spaces/${HF_SPACE}"
+          git -c protocol.version=0 push -f space hf-deploy:main
+          echo "::notice::Pushed snapshot of ${DEPLOY_SHA::7} to spaces/${HF_SPACE}; HF will rebuild."
+
+      # Rollback pointer (D7): tag the exact commit deployed to the Space,
+      # so a bad deploy can be reverted by re-dispatching this workflow from
+      # a prior `space-deploy-*` tag. The Space push itself is force-pushed
+      # and history-free, so this origin tag is the only durable record of
+      # what shipped. Never fails the deploy.
+      - name: Tag the deployed commit on origin
+        if: steps.guard.outputs.configured == 'true'
+        env:
+          DEPLOY_SHA: ${{ steps.sha.outputs.sha }}
+        run: |
+          tag="space-deploy-$(date -u +%Y%m%d-%H%M%S)-${DEPLOY_SHA::7}"
+          git tag -a "$tag" "$DEPLOY_SHA" -m "Deployed to HF Space" || { echo "::warning::tag create failed"; exit 0; }
+          git push origin "refs/tags/$tag" || echo "::warning::tag push failed (non-fatal)"
+          echo "::notice::Tagged deployed commit as $tag"

.github/workflows/parity.yml

@@ -0,0 +1,253 @@
+# Parity checks between the React frontend and standalone_interface.html,
+# plus the demo-scenario replay suite (config_small_grid coverage).
+#
+# See scripts/PARITY_README.md for the four-layer parity design and
+# scripts/parity_e2e/DEMO_REPLAY_README.md for the demo-replay layers.
+# Summary:
+#   Layer 1  — static inventory (events, API paths, settings, schema drift)
+#   Layer 2  — session-reload fidelity (save-vs-restore symmetry)
+#   Layer 3a — gesture-sequence static proxy (ordered event emission)
+#   Layer 3b — behavioural E2E + demo-replay (real DOM, mocked backend):
+#              * `e2e_parity.spec.ts`             — React ↔ standalone parity
+#              * `demo_replay.spec.ts`            — fiche-as-data scenario walker
+#              * `demo_visual_snapshots.spec.ts`  — normalised SVG/HTML diffs
+#              * `demo_meta_invariants.spec.ts`   — console errors, empty
+#                                                   text, pin-count sanity
+#   Layer 4  — user-observable invariants (static source patterns)
+#
+# Layers 1 + 2 + 3a + 4 run on every PR (fast, deterministic, no browser).
+# The cheap `demo_meta_invariants` slice runs on every PR too (~1 min
+# Chromium install + ~20 s test) — it catches console errors and
+# undefined-id leaks that no static pattern can see.
+# The full Layer 3b suite (parity + replay + snapshots) runs nightly +
+# on PRs labelled `e2e`. ~3 min per run.
+name: Parity
+
+on:
+  push:
+    branches: [main]
+  # Run on every PR regardless of its base branch (e.g. PRs stacked onto a
+  # `claude/*` working branch, not just those targeting main).
+  pull_request:
+    branches: ['**']
+  schedule:
+    # Nightly at 02:30 UTC — catches drift introduced between PRs
+    # (e.g. docs/features/interaction-logging.md updates without a code change).
+    - cron: '30 2 * * *'
+
+# Always allow a re-run to supersede an in-flight one for the same PR.
+concurrency:
+  group: parity-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  # -------------------------------------------------------------------
+  # Layer 1 — static inventory parity (events, API paths, settings,
+  # three-way spec diff).  No backend, no browser.
+  # -------------------------------------------------------------------
+  layer1-static-inventory:
+    name: 'Layer 1 · static inventory parity'
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: '3.11'
+      # The parity check needs an up-to-date standalone bundle to
+      # diff against. `frontend/dist-standalone/` is gitignored, so
+      # in CI we have to (re)build it from source — otherwise the
+      # script falls back to the frozen `standalone_interface_legacy.html`
+      # which lags behind the React source by design.
+      - uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+          cache: 'npm'
+          cache-dependency-path: frontend/package-lock.json
+      - name: Build standalone bundle
+        working-directory: frontend
+        run: |
+          npm ci
+          npm run build:standalone
+      - name: Run parity check
+        run: python scripts/check_standalone_parity.py
+      - name: Emit Markdown summary
+        if: always()
+        run: |
+          python scripts/check_standalone_parity.py --emit-markdown \
+            >> "$GITHUB_STEP_SUMMARY" || true
+
+  # -------------------------------------------------------------------
+  # Layer 2 — session-reload fidelity (save/restore symmetry).
+  # -------------------------------------------------------------------
+  layer2-session-fidelity:
+    name: 'Layer 2 · session-reload fidelity'
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: '3.11'
+      - uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+          cache: 'npm'
+          cache-dependency-path: frontend/package-lock.json
+      - name: Build standalone bundle
+        working-directory: frontend
+        run: |
+          npm ci
+          npm run build:standalone
+      - name: Run session-fidelity check
+        run: python scripts/check_session_fidelity.py
+
+  # -------------------------------------------------------------------
+  # Layer 3a — gesture-sequence static proxy.  Lightweight sequence-
+  # aware check; complements Layer 1's set-based diff.
+  # -------------------------------------------------------------------
+  layer3a-gesture-sequence:
+    name: 'Layer 3a · gesture-sequence static proxy'
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: '3.11'
+      - uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+          cache: 'npm'
+          cache-dependency-path: frontend/package-lock.json
+      - name: Build standalone bundle
+        working-directory: frontend
+        run: |
+          npm ci
+          npm run build:standalone
+      - name: Run gesture-sequence check
+        run: python scripts/check_gesture_sequence.py
+
+  # -------------------------------------------------------------------
+  # Layer 4 — user-observable invariants.  Static source-pattern
+  # assertions for the six bug classes Layers 1-3a cannot catch by
+  # construction (visual thresholds, conditional rendering,
+  # field semantics, auto-effects, loading-state, performance).
+  # -------------------------------------------------------------------
+  layer4-invariants:
+    name: 'Layer 4 · user-observable invariants'
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: '3.11'
+      - uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+          cache: 'npm'
+          cache-dependency-path: frontend/package-lock.json
+      - name: Build standalone bundle
+        working-directory: frontend
+        run: |
+          npm ci
+          npm run build:standalone
+      - name: Run invariants check
+        run: python scripts/check_invariants.py
+
+  # -------------------------------------------------------------------
+  # Demo meta-invariants — cheap Playwright slice that catches console
+  # errors, empty visible text, undefined-id leaks and pin-count
+  # inconsistencies on the small_grid demo flow. Runs on every PR
+  # because the signal-to-cost ratio is high (~1 min total: Chromium
+  # install + ~20 s test). The full Layer 3b suite still gates on
+  # the `e2e` label / nightly schedule.
+  # -------------------------------------------------------------------
+  demo-meta-invariants:
+    name: 'Demo · meta-invariants (Playwright, fast)'
+    runs-on: ubuntu-latest
+    timeout-minutes: 6
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+          cache: 'npm'
+          cache-dependency-path: |
+            frontend/package-lock.json
+            scripts/parity_e2e/package-lock.json
+      - name: Install frontend deps + build
+        working-directory: frontend
+        run: |
+          npm ci
+          npm run build
+      - name: Install E2E deps
+        working-directory: scripts/parity_e2e
+        run: npm ci
+      - name: Install Playwright Chromium
+        working-directory: scripts/parity_e2e
+        run: npx playwright install --with-deps chromium
+      - name: Run demo meta-invariants only
+        working-directory: scripts/parity_e2e
+        run: npx playwright test demo_meta_invariants.spec.ts
+      - name: Upload Playwright report on failure
+        if: failure()
+        uses: actions/upload-artifact@v4
+        with:
+          name: playwright-demo-meta-report
+          path: scripts/parity_e2e/playwright-report/
+          if-no-files-found: ignore
+          retention-days: 7
+
+  # -------------------------------------------------------------------
+  # Layer 3b — behavioural E2E + demo-replay full suite with
+  # Playwright. Runs every spec matched by `playwright.config.ts`'s
+  # testMatch (`*parity.spec.ts` + `demo_*.spec.ts`): the React ↔
+  # standalone parity check, the fiche-as-data scenario walker, the
+  # normalised SVG/HTML snapshot diffs, and the meta-invariants
+  # battery. Browser install + 4 specs ≈ 3 min per run, so this job
+  # only fires nightly or on PRs carrying the `e2e` label.
+  # -------------------------------------------------------------------
+  layer3b-behavioural-e2e:
+    name: 'Layer 3b · behavioural E2E + demo replay (Playwright)'
+    runs-on: ubuntu-latest
+    if: |
+      github.event_name == 'schedule'
+      || (github.event_name == 'pull_request'
+          && contains(github.event.pull_request.labels.*.name, 'e2e'))
+    timeout-minutes: 15
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+          cache: 'npm'
+          cache-dependency-path: |
+            frontend/package-lock.json
+            scripts/parity_e2e/package-lock.json
+
+      - name: Install frontend deps + build
+        working-directory: frontend
+        run: |
+          npm ci
+          npm run build
+
+      - name: Install E2E deps
+        working-directory: scripts/parity_e2e
+        run: npm ci
+
+      - name: Install Playwright browsers
+        working-directory: scripts/parity_e2e
+        run: npx playwright install --with-deps chromium
+
+      - name: Run E2E parity spec
+        working-directory: scripts/parity_e2e
+        run: npx playwright test
+
+      - name: Upload Playwright report + artefacts
+        if: always()
+        uses: actions/upload-artifact@v4
+        with:
+          name: playwright-report
+          path: |
+            scripts/parity_e2e/playwright-report/
+            scripts/parity_e2e/artefacts.json
+          if-no-files-found: ignore
+          retention-days: 14

.github/workflows/test.yml

@@ -0,0 +1,163 @@
+name: Tests
+
+on:
+  push:
+    branches: [ main ]
+  # Run on every PR regardless of its base branch (e.g. PRs stacked onto a
+  # `claude/*` working branch, not just those targeting main).
+  pull_request:
+    branches: [ '**' ]
+
+jobs:
+  # ------------------------------------------------------------------
+  # Fast lane: every backend test that does NOT need the graphviz
+  # `dot` binary. Skips the system-package install entirely (which
+  # used to hang for ~8 minutes on the Azure apt mirror) and runs the
+  # ~720 pytest items in ~15 seconds.
+  # ------------------------------------------------------------------
+  test-backend:
+    name: Backend tests (no graphviz)
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Set up Python 3.10
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.10"
+          cache: 'pip'
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install ".[test]"
+          # Pin expert_op4grid_recommender to the exact version in
+          # recommender-pin.txt (QW8) so an upstream release can't silently turn
+          # a green PR red; the weekly canary.yml floats to latest and flags
+          # regressions. --no-deps skips the recommender's heavy transitive
+          # stack (pypowsybl already comes from co_study4grid's own deps).
+          pip install --no-deps -r recommender-pin.txt
+      - name: Run Pytest (excluding graphviz-dependent tests)
+        # Coverage GATES at fail_under=72 (pyproject [tool.coverage.report]).
+        # See docs/architecture/code-quality-analysis.md §20.
+        run: >-
+          pytest --ignore=expert_backend/tests/test_overflow_html_dim_logic.py
+          --cov=expert_backend --cov-report=xml --cov-report=term-missing
+      - name: Upload backend coverage
+        if: always()
+        uses: actions/upload-artifact@v4
+        with:
+          name: backend-coverage
+          path: coverage.xml
+          if-no-files-found: ignore
+          retention-days: 30
+
+  # ------------------------------------------------------------------
+  # Data-pipeline + benchmark supply chain (D8). Runs the HERMETIC slice
+  # of the PyPSA-EUR pipeline suite (scripts/pypsa_eur) and the Codabench
+  # scorer parity guard (scripts/game_mode). These live outside
+  # pytest.ini's testpaths (expert_backend/tests), so they need an
+  # explicit path. Tests that require the uncommitted raw OSM CSVs skip
+  # gracefully (conftest osm_dir / regenerate_grid_layout guards), so the
+  # suite is green from a fresh clone. scripts/game_mode/test_score.py is
+  # pure stdlib and pins score.py to the shared golden fixture the
+  # frontend's scoring.test.ts also asserts — locking cross-language parity.
+  # ------------------------------------------------------------------
+  test-data-pipeline:
+    name: Data pipeline + scorer parity
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Set up Python 3.10
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.10"
+          cache: 'pip'
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install ".[test]"
+      - name: Run pipeline + scorer + config-consistency tests (hermetic slice)
+        run: >-
+          pytest scripts/pypsa_eur scripts/game_mode
+          scripts/test_recommender_pin_consistency.py
+          scripts/test_extract_network_zip.py -q
+
+  test-frontend:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Set up Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+          cache: 'npm'
+          cache-dependency-path: frontend/package-lock.json
+      - name: Install dependencies
+        run: |
+          cd frontend
+          npm install
+      - name: Run Vitest + coverage gate
+        # Runs the full suite WITH coverage and enforces the floor in
+        # vite.config.ts (coverage.thresholds). Replaces the plain run —
+        # same tests, plus the gate. See §19.
+        run: |
+          cd frontend
+          npm run test:coverage
+      - name: Upload frontend coverage
+        if: always()
+        continue-on-error: true
+        uses: actions/upload-artifact@v4
+        with:
+          name: frontend-coverage
+          path: frontend/coverage
+          if-no-files-found: ignore
+          retention-days: 30
+      - name: Run Linter
+        run: |
+          cd frontend
+          npm run lint
+
+  # ------------------------------------------------------------------
+  # Slow lane: the small subset of backend tests that exercise the
+  # upstream interactive-HTML viewer through pydot → graphviz `dot`.
+  # Gated behind the fast lanes so a regression in non-graphviz code
+  # is reported in ~1 minute, and only the prod/load-layer fixtures
+  # pay the (cached) apt install cost.
+  #
+  # `awalsh128/cache-apt-pkgs-action` caches the resolved .deb files
+  # across runs — first run is ~30 s, subsequent runs restore from
+  # cache in ~5 s, vs. the ~8 minutes the bare `apt-get update` was
+  # taking on the Azure mirror.
+  # ------------------------------------------------------------------
+  test-backend-graphviz:
+    name: Backend tests requiring graphviz
+    needs: [test-backend, test-frontend]
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Set up Python 3.10
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.10"
+          cache: 'pip'
+      - name: Install Graphviz
+        # Direct ``apt-get install`` skips the slow ``apt-get update``
+        # (the original 8-minute Azure-mirror hang) — the GH runner
+        # image already ships an up-to-date apt cache. We previously
+        # used ``awalsh128/cache-apt-pkgs-action`` but the cached
+        # ``.deb`` ended up out of sync with the runner's libstdc++
+        # / libltdl, making ``dot`` exit 1 on every render. A direct
+        # install lets apt resolve the packages against the current
+        # runner image so dot links cleanly every time.
+        run: sudo apt-get install -y --no-install-recommends graphviz
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install ".[test]"
+          # Pin expert_op4grid_recommender to the exact version in
+          # recommender-pin.txt (QW8) so an upstream release can't silently turn
+          # a green PR red; the weekly canary.yml floats to latest and flags
+          # regressions. --no-deps skips the recommender's heavy transitive
+          # stack (pypowsybl already comes from co_study4grid's own deps).
+          pip install --no-deps -r recommender-pin.txt
+      - name: Run graphviz-dependent Pytest subset
+        run: pytest expert_backend/tests/test_overflow_html_dim_logic.py

.gitignore

@@ -0,0 +1,50 @@
+session*
+# Anchor `data/` to the project root so it doesn't accidentally match
+# `docs/data/` (where pipeline / coordinate-scale design docs live).
+/data/
+__pycache__/
+*.pyc
+*.pyo
+
+# Build artifacts
+build/
+*.egg-info/
+dist/
+
+# Generated outputs
+Overflow_Graph/
+
+# Game Mode shared solution base (dev fallback of COSTUDY4GRID_DATA_DIR)
+/game_solutions/
+
+# Code-quality reports produced by scripts/code_quality_report.py
+reports/
+
+# Test-coverage artifacts (pytest-cov / vitest v8 — report-only, see
+# docs/architecture/code-quality-analysis.md §18)
+coverage.xml
+.coverage
+.coverage.*
+htmlcov/
+
+# Environment overrides (template is tracked as .env.example)
+.env
+
+# User config (default template is tracked as config.default.json)
+config.json
+config_path.txt
+
+# Node modules
+node_modules/
+
+# Virtual environments
+venv/
+venv*/
+.venv/
+env/
+.env/
+*.odt
+*.docx
+config_*.json
+.idea/
+*DS_Store

AUTHORS.txt

@@ -0,0 +1,15 @@
+Copyright (c) 2025-2026, RTE (https://www.rte-france.com)
+This Source Code Form is subject to the terms of the Mozilla Public License, version 2.0.
+If a copy of the Mozilla Public License, version 2.0 was not distributed with this file,
+you can obtain one at http://mozilla.org/MPL/2.0/.
+SPDX-License-Identifier: MPL-2.0
+This file is part of Co-Study4Grid a Power Grid Study tool Assistant Interface to help solve contigencies for a grid state under study.
+
+Lead Developers:
+    - Antoine Marot
+    
+Main Contributers:
+    - 
+  
+Further Contributions by:
+    - 

CLAUDE.md

@@ -0,0 +1,549 @@
+# CLAUDE.md - Co-Study4Grid
+
+## Project Overview
+
+Co-Study4Grid is a full-stack web application for **power grid contingency analysis and N-1 planning**. It provides an interface to the `expert_op4grid_recommender` library, allowing operators to simulate element disconnections, visualize network overflow graphs, and receive prioritized remedial action recommendations.
+
+## Architecture
+
+**Monorepo** with two main components plus a standalone HTML mirror:
+
+```
+Co-Study4Grid/
+├── CLAUDE.md                  # This file — project overview + standalone parity audit
+├── README.md                  # User-facing project description + quick start
+├── CHANGELOG.md               # Per-release changelog (current: 0.9.0)
+├── CONTRIBUTING.md            # Contributor setup, code-quality gate
+├── pyproject.toml             # Python project metadata + ruff config (E9/F ruleset)
+├── pytest.ini                 # Pytest config (testpaths = expert_backend/tests)
+├── expert_backend/            # Python FastAPI backend
+│   ├── CLAUDE.md              # Backend-scoped guide (singletons, mixins, lifecycle)
+│   ├── main.py                # FastAPI app: endpoints, CORS, gzip helpers, NDJSON streaming
+│   ├── test_backend.py        # Ad-hoc integration script (not part of pytest)
+│   ├── recommenders/          # Pluggable recommendation-model registry: registry.py,
+│   │   │                      # random_basic / random_overflow canonical examples,
+│   │   │                      # overflow_path_filter + network_existence sampling
+│   │   │                      # filters, synthetic_actions builders. Models are
+│   │   │                      # registered at package import; the service integration
+│   │   │                      # is EXPLICIT composition (RecommenderService inherits
+│   │   │                      # ModelSelectionMixin; AnalysisMixin.run_analysis_step2
+│   │   │                      # consumes the registry — no import-time patching).
+│   │   │                      # Full reference: docs/backend/recommender_models.md
+│   ├── services/
+│   │   ├── network_service.py     # pypowsybl Network singleton + metadata queries
+│   │   ├── recommender_service.py # Analysis orchestrator (composes the 4 mixins below)
+│   │   ├── diagram_mixin.py       # NAD/SLD orchestrator — delegates to services/diagram/
+│   │   ├── analysis_mixin.py      # Two-step analysis orchestrator (model-aware step-2
+│   │   │                          # dispatch through the recommenders registry) —
+│   │   │                          # delegates to services/analysis/
+│   │   ├── simulation_mixin.py    # Manual-action + superposition orchestrator
+│   │   ├── model_selection_mixin.py # Active recommender model + overflow-graph toggle
+│   │   ├── simulation_helpers.py  # Stateless helpers extracted from simulation_mixin (PR #104)
+│   │   ├── overflow_overlay.py    # Pin / filter overlay injector for the interactive
+│   │   │                          # HTML overflow viewer (PR #116, 0.7.0)
+│   │   ├── game_solutions.py      # Game Mode shared solution base (per-context
+│   │   │                          # JSON records, novelty/bonus + usage
+│   │   │                          # frequencies; root via COSTUDY4GRID_DATA_DIR)
+│   │   ├── sanitize.py            # NumPy → native-Python recursive coercion
+│   │   ├── analysis/              # PR #104 decomposition — action_enrichment,
+│   │   │                          # mw_start_scoring, analysis_runner, pdf_watcher,
+│   │   │                          # overflow_geo_transform (PR #116 — geo-layout SVG
+│   │   │                          # transform for /api/regenerate-overflow-graph)
+│   │   └── diagram/               # PR #104 decomposition — layout_cache, nad_params,
+│   │                              # nad_render, sld_render, overloads, flows, deltas,
+│   │                              # obs_prewarm (post-contingency obs cache prewarm
+│   │                              # that lets run_analysis_step1 skip the LF),
+│   │                              # action_patch (extracted action-variant patch
+│   │                              # pipeline — keeps diagram_mixin under the LoC
+│   │                              # ceiling)
+│   └── tests/                 # pytest suite — see tests/CLAUDE.md for the mock layer
+├── frontend/                  # React 19 + TypeScript 5.9 + Vite 7 frontend
+│   ├── CLAUDE.md              # Frontend-scoped guide (App.tsx hub, hooks, SVG levers)
+│   ├── package.json, vite.config.ts, vite.config.standalone.ts,
+│   │                          # eslint.config.js, tsconfig*.json
+│   └── src/
+│       ├── App.tsx                # State orchestration hub (~1400 lines)
+│       ├── api.ts                 # Axios HTTP client (base URL: 127.0.0.1:8000)
+│       ├── types.ts               # All TypeScript interfaces (one file)
+│       ├── styles/                # Design-token palette (PR #120, 0.7.0):
+│       │                          # tokens.css (CSS custom properties) +
+│       │                          # tokens.ts (typed colors / space / text /
+│       │                          # radius / pinColors* constants). Single
+│       │                          # source of truth for the entire UI; the
+│       │                          # code-quality gate enforces zero hex
+│       │                          # literals outside these two files.
+│       ├── hooks/                 # useSettings / useActions / useAnalysis / useDiagrams /
+│       │                          # useSession / useDetachedTabs / useTiedTabsSync /
+│       │                          # usePanZoom / useSldOverlay / useContingencyFetch (svgPatch fast-
+│       │                          # path + full fallback) / useDiagramHighlights (per-tab
+│       │                          # highlight pipeline + Flow/Impacts view-mode state) /
+│       │                          # useOverflowIframe (PR #116 — iframe lifecycle, layer
+│       │                          # toggles, postMessage bridge, pin overlay payload) /
+│       │                          # useSldTopologyEdit (interactive SLD switch-edit →
+│       │                          # manual action, 0.8.0) / useTheme (light/dark theme
+│       │                          # toggle + persistence, 0.8.0)
+│       ├── components/            # Header, ActionFeed, ActionCard, ActionCardPopover,
+│       │                          # ActionSearchDropdown (editable Δ MW column
+│       │                          # for redispatch in score table),
+│       │                          # ActionTypeFilterChips,
+│       │                          # ActionFilterRings (shared severity + action-type +
+│       │                          # Max-loading ring strip, 0.8.0), ActionTypeIcon /
+│       │                          # SeverityIcon (action-type + severity pictograms),
+│       │                          # AdditionalLinesPicker,
+│       │                          # ActionOverviewDiagram, AppSidebar (collapsible
+│       │                          # shell — readability-feed PR), SidebarSummary
+│       │                          # (sticky strip — hosts Clear button + overload
+│       │                          # info bubble that absorbed the legacy
+│       │                          # OverloadPanel affordances),
+│       │                          # NotificationHost (typed toast store —
+│       │                          # severity/dismiss/aria-live, PR D5),
+│       │                          # VisualizationPanel, OverloadPanel
+│       │                          # (kept on disk for unit-test backwards-compat;
+│       │                          # no longer rendered from App.tsx),
+│       │                          # CombinedActionsModal, ComputedPairsTable,
+│       │                          # ExplorePairsTab, SldOverlay, SldEditPanel
+│       │                          # (interactive maneuver list, 0.8.0),
+│       │                          # SldInjectionPopover (SLD load/gen active-
+│       │                          # power editor bubble), DetachableTabHost,
+│       │                          # MemoizedSvgContainer, ErrorBoundary, NoticesPanel
+│       │                          # (PR #122 tier system), DiagramLegend (PR #122),
+│       │                          # InspectSearchField + DetachedPlaceholder (PR #116
+│       │                          # — extracted from VisualizationPanel)
+│       │                          # + modals/ (SettingsModal, ReloadSessionModal,
+│       │                          #            ConfirmationDialog)
+│       ├── game/                  # Timed, scored Game Mode (0.8.0; active only
+│       │                          # with ?game=1) — GameShell / useGameSession /
+│       │                          # gameBridge / GameConfigScreen / GameHud /
+│       │                          # GameResults / GameNoveltyToast /
+│       │                          # GameHintsPanel (beginner assistance:
+│       │                          # community's most-used levers) / scoring /
+│       │                          # gameLog / solutionLog (solution
+│       │                          # capitalisation: levers + novelty bonus +
+│       │                          # usage-frequency feedback) / presets /
+│       │                          # types. See docs/features/game-mode-codabench.md
+│       └── utils/                 # svgUtils (barrel re-exporting utils/svg/*),
+│                                  # svgPatch (DOM-recycling patch applier),
+│                                  # overloadHighlights, sessionUtils, interactionLogger,
+│                                  # popoverPlacement, mergeAnalysisResult, actionTypes
+│                                  # (classifyActionType + DEFAULT_ACTION_OVERVIEW_FILTERS),
+│                                  # inspectables (filterInspectables — match an element
+│                                  # by its displayed name, not just its raw id),
+│                                  # ndjsonStream (single NDJSON reader, D5),
+│                                  # notifications (typed toast store, D5),
+│                                  # fileRegistry (structure regression guard)
+│           └── svg/               # PR #104 decomposition — idMap, metadataIndex,
+│                                  # svgBoost, fitRect, deltaVisuals, actionPinData,
+│                                  # actionPinRender, highlights, vlInteractions (VL-disk
+│                                  # hover name / click-to-inspect / dbl-click SLD),
+│                                  # overflowPinPayload
+│                                  # + overflowOverlayRender + pinGlyph (PR #116 —
+│                                  # iframe-overlay pin pipeline)
+├── standalone_interface_legacy.html  # DECOMMISSIONED 2026-04-20 — hand-maintained
+│                              # single-file mirror frozen at its last version and
+│                              # tracked here for reference only. Replaced by the
+│                              # auto-generated `frontend/dist-standalone/standalone.html`
+│                              # (`npm run build:standalone`). New UI changes land ONLY
+│                              # in `frontend/src/` — do NOT edit this file further.
+├── docs/                      # Design docs — organized into features/, performance/
+│                              # (+ history/), architecture/, proposals/, data/.
+│                              # See `docs/README.md` for the index.
+├── data/                      # Sample grids: bare_env_small_grid_test, pypsa_eur_fr400,
+│                              # pypsa_eur_fr225_400 (France 225/400 kV — its large
+│                              # network ships compressed as network.xiidm.zip,
+│                              # auto-decompressed by network_service on load)
+├── benchmarks/                # Perf scripts (bench_load_study, _bench_common)
+├── Overflow_Graph/            # Generated PDFs (created at runtime)
+├── overrides.txt              # Pinned versions for transitive Python deps
+├── requirements_py310.txt     # Python 3.10-pinned requirements superset
+├── scripts/                   # Integration / parity / build helpers —
+│                              # `check_standalone_parity.py`,
+│                              # `check_session_fidelity.py`,
+│                              # `check_gesture_sequence.py`,
+│                              # `check_invariants.py`, `check_code_quality.py`,
+│                              # `check_openapi_contract.py` (D2 — diffs the live
+│                              # app.openapi() against expert_backend/openapi.snapshot.json),
+│                              # `code_quality_report.py`, `profile_diagram_perf.py`,
+│                              # `test_code_quality_report.py`,
+│                              # `test_estimation_vs_simulation_small_grid.py`,
+│                              # `pypsa_eur/` (full PyPSA-EUR → XIIDM pipeline
+│                              # with its own pytest coverage; `build_pipeline.py`
+│                              # writes a per-bundle provenance.json, D8), and
+│                              # `game_mode/` (`e2e_game_session.py` — real-backend
+│                              # Game Mode replay; `scoring_program/score.py` —
+│                              # in-repo Codabench scorer twin of scoring.ts,
+│                              # pinned to `scoring_golden.json` by test_score.py
+│                              # + scoring.test.ts for cross-language parity, D8)
+├── Dockerfile                 # Single-container HuggingFace Docker Space image —
+│                              # same-origin SPA + FastAPI on :7860, game mode on
+├── .dockerignore
+├── deploy/                    # HuggingFace Space README + step-by-step SETUP.md
+├── config.default.json        # Bundled first-run settings (fr225_400 grid +
+│                              # per-action-type recommender minima)
+├── .editorconfig              # Cross-editor indent / EOL defaults
+├── .env.example               # Template for backend env vars (CORS, …)
+├── .gitattributes             # Git LFS tracking for *.zip / *.png / *.jpg(eg)
+│                              # (HuggingFace Space git endpoint requires LFS)
+└── .gitignore                 # Excludes __pycache__/, *.pyc, *.pyo, node_modules/
+```
+
+### Per-subtree docs
+
+| File | Scope |
+|------|-------|
+| `CLAUDE.md` (this file) | Project overview, API table, conventions, parity-audit pointer |
+| `frontend/PARITY_AUDIT.md` | Full standalone-parity audit: feature inventory, mirror-status table, Layer 1–4 conformity findings, gap-priority list, deltas. Split out of this file 2026-04-20. |
+| `expert_backend/CLAUDE.md` | Backend internals: singletons, mixin composition, state lifecycle, NDJSON streaming, gzip helpers, layout cache invariants, NAD prefetch |
+| `expert_backend/tests/CLAUDE.md` | Test conventions, the `conftest.py` mock layer for `pypowsybl` / `expert_op4grid_recommender`, frontend Vitest patterns |
+| `frontend/CLAUDE.md` | Frontend internals: hook split, data flow, state reset, SVG performance levers, detached/tied tabs, interaction logger contract |
+| `docs/README.md` | Index of design/feature/perf/architecture/proposal docs. Start here for any `docs/**` lookup. |
+| `docs/features/save-results.md` | Save / reload session contract (JSON schema, reload flow, regression-guard matrix) |
+| `docs/features/adding-action-type.md` | Cross-cutting checklist for adding/upgrading a remedial-action type (lib → backend → frontend → save/log/reload triad → regression specs) |
+| `docs/features/interaction-logging.md` | Replay-ready event log contract |
+| `docs/features/sld-topology-edit.md` | Interactive SLD topology edit → manual action card |
+| `docs/features/sld-diagram-feeder-labels.md` | SLD feeders relabelled by far-end VL name (+ parallel index), overload-halo friendly-name↔IIDM-id bridge, and the charging-current annotation explaining the "after" loading of a line opened at one end |
+| `docs/features/vl-disk-interactions.md` | Interactive VL disks on the NAD (hover name / click → Inspect / double-click → SLD) + delegation performance contract |
+| `docs/features/game-mode-codabench.md` | Timed, scored Game Mode (`?game=1`) + Codabench benchmark bundle |
+| `deploy/huggingface/` | HuggingFace Docker Space deployment (Space README + `SETUP.md`) |
+
+## Tech Stack
+
+### Backend
+- **Python** with **FastAPI** + **Uvicorn**
+- **pypowsybl** - Power system network loading, load flow, and diagram generation
+- **expert_op4grid_recommender** - Domain-specific grid optimization recommendations
+- **grid2op** / **pandapower** / **lightsim2grid** - Grid simulation backends
+
+### Frontend
+- **React 19** with **TypeScript 5.9**
+- **Vite 7** - Build tool and dev server
+- **axios** - HTTP client
+- **react-select** - Searchable dropdown for branch selection
+- **vite-plugin-singlefile** - Auto-generated single-file standalone bundle
+- **Vitest** + **React Testing Library** - Unit / integration tests
+
+## Development Workflow
+
+### Running the Backend
+
+```bash
+# From the project root:
+python -m expert_backend.main
+# Or:
+uvicorn expert_backend.main:app --host 0.0.0.0 --port 8000
+```
+
+The backend serves on `http://localhost:8000`. It expects `pypowsybl` and `expert_op4grid_recommender` to be available in the Python environment.
+
+### Running the Frontend
+
+```bash
+cd frontend
+npm install
+npm run dev      # Start Vite dev server with HMR
+```
+
+The frontend dev server proxies API calls to `http://localhost:8000` (hardcoded in `frontend/src/api.ts`).
+
+### Build & Lint
+
+```bash
+cd frontend
+npm run build    # TypeScript compilation (tsc -b) + Vite production build
+npm run lint     # ESLint
+npm run preview  # Preview production build
+```
+
+### Running Tests
+
+Backend unit tests use `pytest` and run against the in-repo mock layer
+(no live pypowsybl required):
+
+```bash
+pytest                                   # Full backend suite
+pytest expert_backend/tests/test_foo.py  # Single file
+```
+
+Ad-hoc integration scripts live in `scripts/` (and `scripts/pypsa_eur/`
+for the PyPSA-EUR → XIIDM pipeline). The pipeline scripts carry their
+own pytest coverage (`scripts/pypsa_eur/test_*.py`) alongside the
+backend suite; the rest require a running backend with real data:
+
+```bash
+pytest scripts/pypsa_eur                           # Pipeline unit tests
+python scripts/pypsa_eur/test_pipeline.py          # End-to-end smoke test
+python scripts/pypsa_eur/test_n1_calibration.py    # N-1 flow calibration check
+python scripts/pypsa_eur/test_grid_layout.py       # Layout loading sanity check
+python scripts/profile_diagram_perf.py             # NAD rendering profiler
+```
+
+Frontend unit tests use Vitest:
+
+```bash
+cd frontend
+npm run test         # Run Vitest test suite
+```
+
+### Code-Quality Checks (continuous reporting)
+
+```bash
+# Generate a full JSON + Markdown report (backend + frontend metrics)
+python scripts/code_quality_report.py --output reports/code-quality.json \
+                                      --markdown reports/code-quality.md
+
+# Gate a pull request: non-zero exit on threshold violation
+python scripts/check_code_quality.py
+```
+
+Both scripts run in CI (`.github/workflows/code-quality.yml`). The gate
+guards the reductions documented in
+[`docs/architecture/code-quality-analysis.md`](docs/architecture/code-quality-analysis.md)
+(no new `print()` / bare except, module-size ceilings, no `any` /
+`@ts-ignore` in frontend source).
+
+## API Endpoints
+
+| Method | Path | Description |
+|--------|------|-------------|
+| GET  | `/api/user-config` | Read persisted user configuration (paths, recommender params) |
+| POST | `/api/user-config` | Persist user configuration |
+| GET  | `/api/config-file-path` | Get the current user-config file path |
+| POST | `/api/config-file-path` | Set a custom user-config file path |
+| POST | `/api/config` | Set network path, action file path, and all recommender parameters (incl. `model` and `compute_overflow_graph`) |
+| GET  | `/api/models` | List registered recommendation models with their `params_spec()` and capability flags |
+| POST | `/api/recommender-model` | Lightweight swap of the active recommender model (no network reload) — fired by the model dropdowns in Settings and above Analyze & Suggest |
+| GET  | `/api/branches` | List disconnectable elements (lines + 2-winding transformers) |
+| GET  | `/api/voltage-levels` | List voltage levels in the network |
+| GET  | `/api/nominal-voltages` | Map voltage level IDs to nominal voltages (kV) |
+| GET  | `/api/element-voltage-levels` | Resolve equipment ID to its voltage level IDs |
+| GET  | `/api/voltage-level-substations` | Map voltage level IDs to their parent substation IDs (used by the SLD overlay and overflow pin pipeline) |
+| POST | `/api/run-analysis` | Run full N-1 contingency analysis (streaming NDJSON, legacy) |
+| POST | `/api/run-analysis-step1` | Two-step analysis Part 1: detect overloads |
+| POST | `/api/run-analysis-step2` | Two-step analysis Part 2: resolve with actions (streaming NDJSON) |
+| GET  | `/api/network-diagram` | Get N-state network SVG diagram (NAD) |
+| POST | `/api/contingency-diagram` | Get post-contingency N-1 diagram with flow deltas |
+| POST | `/api/contingency-diagram-patch` | SVG-less per-branch delta for DOM-recycling fast path (PR #108) |
+| POST | `/api/action-variant-diagram` | Get network state after applying a remedial action |
+| POST | `/api/action-variant-diagram-patch` | Per-branch delta + VL-subtree splice for action DOM recycling |
+| POST | `/api/focused-diagram` | Generate NAD sub-diagram focused on a specific element |
+| POST | `/api/action-variant-focused-diagram` | Focused NAD for specific VL in post-action state |
+| POST | `/api/n-sld` | Single Line Diagram for voltage level in N state. Response includes `switch_states` (per-switch open/closed map), `injections` (per-load/generator active-power baseline) used by the interactive SLD-edit feature, **and** `feeder_labels` (per-branch `{name, other_vl, label}` — `label` = far-end VL name + parallel index, used to relabel feeders and bridge friendly-named overloads to the SLD cell). |
+| POST | `/api/contingency-sld` | Single Line Diagram in N-1 state (with flow deltas + `switch_states` + `injections` + `feeder_labels`). |
+| POST | `/api/action-variant-sld` | SLD in post-action state (with flow deltas, `changed_switches`, `switch_states`, `injections`, `feeder_labels`). |
+| POST | `/api/sld-topology-preview` | Target-topology preview SLD for the interactive SLD-edit feature: applies staged switch overrides on a throwaway variant and re-renders with topological colouring (no load flow; `stale_flows: true`). |
+| GET  | `/api/actions` | Return all available action IDs and descriptions |
+| POST | `/api/regenerate-overflow-graph` | Regenerate (or serve from cache) the overflow graph in hierarchical / geo layout — drives the toggle on the Overflow Analysis tab |
+| POST | `/api/simulate-manual-action` | Simulate a specific action against a contingency. Accepts an optional `voltage_level_id` field used to auto-name switch-only user actions (interactive SLD-edit feature). |
+| POST | `/api/simulate-and-variant-diagram` | NDJSON stream: `{type:"metrics"}` then `{type:"diagram"}` so sidebar updates ahead of the SVG |
+| POST | `/api/compute-superposition` | Compute combined effect of two actions (superposition theorem) |
+| POST | `/api/game/log-solution` | Capitalise a Game Mode retained proposition into the shared solution base; returns the novelty verdict (+bonus points) and per-action usage frequencies |
+| GET  | `/api/game/lever-stats` | Most-used unitary levers of a (network, contingency) context in the shared solution base — the Game Mode beginner-assistance hints (top-N, tagged voltage_level / branch / generation / load) |
+| POST | `/api/save-session` | Save session folder with JSON snapshot + PDF copy |
+| GET  | `/api/list-sessions` | List available session folders in a directory |
+| POST | `/api/load-session` | Load session JSON and restore PDFs |
+| POST | `/api/restore-analysis-context` | Restore analysis context from saved session |
+| GET  | `/api/pick-path` | Open native OS file/directory picker (tkinter subprocess) |
+| GET  | `/results/pdf/{filename}` | Serve generated overflow-graph files from `Overflow_Graph/` — HTML (interactive viewer, current default via `config.VISUALIZATION_FORMAT="html"`) or PDF (legacy sessions). URL path kept for backward compatibility. |
+
+## Key Patterns & Conventions
+
+### Backend
+- **Singleton services**: `network_service` and `recommender_service` are module-level singleton instances
+- **Streaming responses**: Analysis uses `StreamingResponse` with NDJSON (`application/x-ndjson`), yielding `{"type": "pdf", ...}` then `{"type": "result", ...}` events
+- **AC/DC fallback**: Analysis first tries AC load flow; falls back to DC if AC does not converge
+- **Threaded analysis**: `run_analysis` runs the computation in a background thread and polls for PDF generation
+- **JSON sanitization**: NumPy types are recursively converted to native Python types via `sanitize_for_json()`
+- **Unified error contract (D2, 2026-07)**: every error is `{"detail", "code"}` produced in one place (`services/api_errors.py`, `install_error_handlers(app)`). Raise a plain `HTTPException` (code derived from status: 400/404/409/422/500) or `AppHTTPException(status, detail, code)` when the frontend branches on the failure (e.g. `ACTION_RESULT_UNAVAILABLE`, `STUDY_BUSY`). Uncaught exceptions → generic logged 500 (never `str(e)` — it leaks paths). The frontend reads it via `frontend/src/utils/apiError.ts`.
+- **Machine-checked API contract (D2, 2026-07)**: `app.openapi()` is snapshotted to `expert_backend/openapi.snapshot.json` and diffed in CI (`scripts/check_openapi_contract.py`, `test_openapi_contract.py`). Regenerate on any deliberate endpoint / model / status change: `python scripts/check_openapi_contract.py --write`.
+- **Concurrency ownership (D3, 2026-07)**: a service-level re-entrant lock (`services/service_lock.py`, `@with_network_lock[_stream]`) serializes the variant-switching entry points on the shared `Network`; overlapping study mutations (config load / analysis) get **HTTP 409**. See [`docs/architecture/shared-network-concurrency.md`](docs/architecture/shared-network-concurrency.md).
+- **Mixin → helper-package decomposition (PR #104 / #106)**: `DiagramMixin`, `AnalysisMixin` and `SimulationMixin` are thin orchestrators. Pure numerics live in `services/diagram/`, `services/analysis/` and `services/simulation_helpers.py` respectively — dependency-injected so existing `@patch` tests keep working.
+- **SVG DOM recycling (PR #108)**: patch endpoints (`/api/contingency-diagram-patch`, `/api/action-variant-diagram-patch`) return per-branch deltas + optional VL-subtree splices so the frontend can clone the already-mounted N-state SVG instead of re-downloading the full NAD (~80 % faster tab switches on large grids).
+- **Interactive overflow viewer (PR #116, 0.7.0)**: `services/overflow_overlay.py` injects a Co-Study4Grid pin / filter overlay (`<style>` + `<script>` block) into the upstream `expert_op4grid_recommender` HTML viewer before serving it from `/results/pdf/{filename}`. `services/analysis/overflow_geo_transform.py` is a pure lxml transform that rewrites the hierarchical-layout SVG to geographic coordinates for the `/api/regenerate-overflow-graph` toggle; the geo cache is per-study and cleared on `reset()`.
+- **Shared diagram helpers**: `RecommenderService` uses `_load_network()`, `_load_layout()`, `_default_nad_parameters()`, and `_generate_diagram()` to deduplicate diagram generation logic across endpoints
+- **Focused diagrams**: The `/api/focused-diagram` endpoint resolves an element to its voltage levels and generates a sub-diagram with configurable depth, useful for inspecting specific parts of large grids
+- **Ruff-gated**: `pyproject.toml` configures a narrow `E9` + `F` ruleset (real bugs only); stylistic rules deliberately off
+
+### Frontend
+- **Strict TypeScript**: `strict: true`, `noUnusedLocals`, `noUnusedParameters`, `noFallthroughCasesInSwitch`
+- **Functional components** with React hooks; no external state management library
+- **Inline styles**: Components use inline `style` objects rather than CSS modules or utility classes
+- **Design tokens (PR #120, 0.7.0)**: every colour / spacing / typography / radius value lives in `frontend/src/styles/tokens.{css,ts}`. Inline `style` objects import the typed `colors` / `space` / `text` / `radius` constants from `tokens.ts`; stylesheet rules use `var(--…)` from `tokens.css`. Raw SVG attribute setters (`element.setAttribute('fill', …)`) import the hex-valued `pinColors` / `pinChrome` constants because browsers don't reliably resolve `var(--…)` inside SVG presentation attributes. **The code-quality gate enforces zero hex literals outside the two token files.**
+- **Light / dark theme (0.8.0)**: theming is a token swap, not per-component overrides — the `useTheme` hook flips a theme attribute that re-points the `tokens.css` custom properties, with a tiny pre-mount script to avoid the first-paint flash. A legibility pass covers the pypowsybl NAD / SLD chrome and the injected overflow-viewer overlay. See [`docs/features/dark-mode.md`](docs/features/dark-mode.md).
+- **Component architecture (Phase 2 hook extraction, PR #109)**:
+  - `App.tsx` (~1400 lines) is the **state orchestration hub** — it wires all hooks together and handles cross-hook logic (e.g., `handleApplySettings`). It should NOT contain large JSX blocks.
+  - **Presentational components** live in `components/` and `components/modals/`. They receive data and callbacks via typed props; all business logic stays in `App.tsx` or in hooks.
+  - `hooks/useContingencyFetch.ts` owns the N-1 diagram fetch pipeline (svgPatch fast-path + `/api/contingency-diagram` fallback + contingency-change confirm routing).
+  - `hooks/useDiagramHighlights.ts` owns the per-tab SVG highlight pipeline (overload halos, contingency highlight, action targets, delta visuals) + per-tab Flow/Impacts view-mode state.
+  - `hooks/useOverflowIframe.ts` (PR #116, 0.7.0) owns the interactive overflow viewer — iframe lifecycle, layer-toggle state, hierarchical ↔ geo layout switch, postMessage bridge to the host, and the action-pin overlay payload computation.
+  - `hooks/useSldTopologyEdit.ts` (0.8.0) owns the interactive SLD edit flow — `editMode` (implicit while the SLD is open — no toggle button; read-only on close), staged `pendingStates` (switch toggles) + `pendingInjections` (load / generator active-power retunes), `toggle` / `removeSwitch(es)` / `setInjection` / `removeInjection` / `focusedSwitchId` — that turns clicked breakers AND injection retunes into one manual action card (`SldInjectionPopover` is the active-power editor bubble). See [`docs/features/sld-topology-edit.md`](docs/features/sld-topology-edit.md).
+  - `useSettings.ts` exposes `SettingsState` (all settings values + setters), which is passed wholesale to `SettingsModal` to avoid 30+ prop-drilling.
+- **SVG DOM recycling (PR #108)**: `utils/svgPatch.ts` clones the already-mounted N-state `SVGSVGElement` and patches only per-branch deltas on N-1 / action tab switches, saving a 12–28 MB SVG re-download and re-parse.
+- **Props-based data flow**: State lifted to `App.tsx`, passed down via props
+- **ESLint**: Flat config (v9+) with `typescript-eslint`, `react-hooks`, and `react-refresh` plugins
+- **Unit tests** use Vitest + React Testing Library. Isolated component tests (no backend mocking needed) live alongside their components as `*.test.tsx` files.
+
+### Data Flow
+1. User sets network path + action file path -> `POST /api/config` loads the network
+2. Frontend fetches disconnectable branches -> `GET /api/branches`
+3. User selects a contingency branch -> N-1 diagram fetched with overload highlighting
+4. User runs analysis (two-step flow):
+   - Step 1: `POST /api/run-analysis-step1` detects overloads in N-1 state
+   - User selects which overloads to resolve
+   - Step 2: `POST /api/run-analysis-step2` streams PDF event + action results
+5. Frontend displays overflow PDF and action cards in ActionFeed panel
+6. User can star/reject actions, manually simulate others, compute combined pairs
+7. Action selection triggers `POST /api/action-variant-diagram` -> post-action diagram
+8. Session save captures full snapshot to `session.json` + overflow PDF copy
+
+### Session Save/Load
+- **Save**: `buildSessionResult()` in `sessionUtils.ts` serializes all state (config, contingency, actions with status tags, combined pairs) -> `POST /api/save-session` writes to disk
+- **Load**: `POST /api/load-session` reads `session.json` -> frontend restores all state without re-simulating actions
+- **Output folder**: `<output_folder>/costudy4grid_session_<contingency>_<timestamp>/` contains `session.json` + overflow PDF
+- **Interaction logging**: Every user interaction is logged as a timestamped, replay-ready event via `interactionLogger`. Saved as `interaction_log.json` alongside `session.json`.
+- See `docs/features/save-results.md` for session save/load, `docs/features/interaction-logging.md` for the replay contract, and `docs/features/action-overview-diagram.md` for the Remedial Action overview (pin overlay on N-1 network)
+
+### SVG Visualization
+Both the React frontend and the auto-generated
+`frontend/dist-standalone/standalone.html` render pypowsybl
+NAD/SLD payloads:
+- **Dynamic text scaling** (`utils/svgUtils.ts:boostSvgForLargeGrid` /
+  standalone `boostSvgForLargeGrid`): font sizes for node labels, edge
+  info, and legends scale proportionally to diagram size via
+  `sqrt(diagramSize / referenceSize)`, so text is readable when zoomed
+  in and naturally invisible at full zoom-out. Engaged for grids
+  ≥ 500 voltage levels.
+- **Bus / transformer scaling**: circle radii for bus nodes and
+  transformer windings are boosted proportionally.
+- **Edge-info scaling**: flow values and arrow glyphs are scaled via
+  transform groups so they remain proportional to the line on which
+  they sit.
+- **ViewBox zoom**: auto-centers on selected contingency targets with
+  adjustable padding.
+- **Pan/zoom**: the `usePanZoom` hook writes the SVG `viewBox`
+  directly (rAF-batched, cached CTM) — no pan/zoom library — in both
+  the React dev build and the auto-generated standalone (they share
+  the same source tree).
+
+## Dependencies
+
+### Backend (`pyproject.toml` + `overrides.txt`)
+- `fastapi`, `uvicorn`, `python-multipart`
+- `pypowsybl`, `expert_op4grid_recommender` (expected in venv)
+- `pandas>=2.2.2`, `numpy>=2.0.0`, `grid2op>=1.12.2`, `pandapower>=2.14.0`
+- `lightsim2grid>=0.12.0`, `matplotlib>=3.10.6`, `scipy>=1.16.0`
+- `lxml>=6.0.0`, `contourpy>=1.2.0`, `tqdm>=4.65.0`
+
+### Frontend (`frontend/package.json`)
+- See `dependencies` and `devDependencies` in `frontend/package.json`
+
+## File Conventions
+
+- Network data files: `.xiidm` format (loaded by pypowsybl)
+- Action definitions: `.json` files with action IDs mapping to descriptions
+- Generated outputs: PDF files in `Overflow_Graph/` directory
+- Network layouts: `grid_layout.json` (node ID -> [x, y] coordinates)
+
+## Notes for AI Assistants
+
+- The backend API base URL defaults to `http://127.0.0.1:8000` in `frontend/src/api.ts` (`API_BASE_URL`), overridable at build time via `VITE_API_BASE_URL` — set it to `""` for **same-origin** hosting where the backend serves the SPA (the HuggingFace Docker Space), so requests become relative `/api/...`
+- CORS defaults to the local Vite dev/preview origins on loopback (`localhost`/`127.0.0.1` on `:5173` / `:4173`); a wildcard is explicit opt-in and any other set is configurable via the `CORS_ALLOWED_ORIGINS` env var (see `.env.example`)
+- **Frontend architecture (Phase 2 hook extraction, PR #109)**: `App.tsx` is the state orchestration hub; it must NOT contain large inline JSX blocks. Extracted presentational components live in `components/` and `components/modals/`; cross-cutting state pipelines live in `hooks/` (notably `useContingencyFetch` and `useDiagramHighlights`). When adding new UI sections, create a new component file (or hook for stateful pipelines) and wire it in `App.tsx`.
+- **`useSettings` hook**: Exposes a `SettingsState` object with all settings fields + setters. This is passed wholesale to `SettingsModal` to avoid excessive prop drilling. Adding a new setting means: (1) add to `useSettings.ts`, (2) add to `SettingsModal.tsx`. No manual standalone mirror is required — the legacy hand-maintained file has been decommissioned and the auto-generated bundle inherits from the React source automatically.
+- **Standalone bundle (auto-generated)**: `npm run build:standalone` in `frontend/` produces `frontend/dist-standalone/standalone.html` — a single-file HTML with React + CSS inlined via `vite-plugin-singlefile`. This is the canonical distribution artifact replacing the former `standalone_interface.html`. The legacy file remains on disk as `standalone_interface_legacy.html` (tracked as a frozen snapshot — do NOT edit).
+- **Online deployment (HuggingFace Docker Space, 0.8.0)**: `Dockerfile` builds the SPA with `VITE_API_BASE_URL=""` + `VITE_GAME_MODE=1` and serves it **same-origin** with the FastAPI backend on port 7860. `main.py` optionally mounts the built SPA via `COSTUDY4GRID_FRONTEND_DIST` (mounted LAST, after every `/api/*` and `/results/*` route; inert when the dist is absent, so local dev is unaffected). One Space instance serves one player (module-level singletons). See `deploy/huggingface/`.
+- **Deployment lockdown (D7, 2026-07)**: the `Dockerfile` sets `COSTUDY4GRID_LOCKDOWN=1`, which disables the desktop-era filesystem RPCs (custom config-file path, session save/list/load, native file picker) with a `403 {code: LOCKED_DOWN}` — they assume a local operator and would otherwise expose the container filesystem to an anonymous Space visitor. The read-only app config stays available so the SPA boots; unset locally so dev is unaffected. The HF deploy is **test-gated** (`workflow_run` on a green Tests run) and **tags each deploy** on origin (`space-deploy-*`) as the rollback pointer. See [`docs/architecture/deployment-trust.md`](docs/architecture/deployment-trust.md).
+- **Game Mode (0.8.0)**: a timed, scored session shell in `frontend/src/game/`, **additive and inert unless `?game=1`** — `main.tsx` mounts `GameShell` instead of `App`; App integration is three `gameBridge.isGameMode()`-guarded touch points. See `docs/features/game-mode-codabench.md`.
+- **Binary assets via Git LFS + transparent network decompression (0.8.0)**: `.gitattributes` tracks `*.zip` / `*.png` / `*.jpg` via Git LFS (the HuggingFace Space git endpoint rejects non-LFS binaries); the large France 225/400 kV grid ships as `network.xiidm.zip` and `network_service._resolve_network_file` / `_extract_network_zip` decompress it transparently on load.
+- **CI pipelines**: GitHub Actions only (`.github/workflows/`: `code-quality.yml`, `parity.yml`, `test.yml`, `canary.yml`, `deploy-huggingface.yml`) run the code-quality gate, ruff, the pytest + Vitest suites, the data-pipeline + scorer-parity slice, and the parity scripts. CircleCI was removed (QW23 — GitHub Actions is a strict superset). The backend test + the `Dockerfile` install `expert_op4grid_recommender` from **`recommender-pin.txt`** — one pinned, exact version (QW8) so an upstream release can't silently break a PR or a rebuild; the weekly `canary.yml` floats to the latest release and flags regressions, so upgrades are a deliberate bump of that file.
+- Root `.gitignore` excludes `__pycache__/`, `*.pyc`, `*.pyo`; `frontend/.gitignore` handles frontend build artifacts
+- Integration helpers and parity scripts live under `scripts/`. They are NOT part of the pytest suite — invoke them directly. The PyPSA-EUR pipeline scripts under `scripts/pypsa_eur/` DO carry pytest coverage (`test_build_pipeline.py`, `test_calibrate_thermal_limits.py`, `test_generate_n1_overloads.py`, `test_regenerate_grid_layout.py`).
+- `overrides.txt` contains pinned versions for transitive Python dependencies that need to be forced to specific versions
+- **Frontend unit tests** use Vitest + React Testing Library. Isolated component tests live as `*.test.tsx` files next to their component. Run with `cd frontend && npm run test`. No backend mocking is needed for component tests since they only use mocked props.
+- The two-step analysis flow (step1: detect overloads, step2: resolve) is the primary user workflow; the single-step `/api/run-analysis` is a legacy alternative
+- Session save/load is documented in `docs/features/save-results.md`
+- **`grid_layout.json` coordinate scale (2026-05-08)**: the on-disk layout MUST be in raw Mercator metres (span ≈ 1.4–1.6 M for the French grid). pypowsybl emits VL outer circles at a *fixed* `r = 27.5` user-space units, so any layout squashed below ~500 000 units forces overlap on dense regions (Paris/Lyon). `scripts/pypsa_eur/regenerate_grid_layout.py` defaults to raw metres; the legacy `--target-width 8000` flag is preserved but warns. Full rationale + operator-vs-PyPSA comparison in [`docs/data/grid-layout-coordinate-scale.md`](docs/data/grid-layout-coordinate-scale.md).
+
+---
+
+## Contributing & Pull Requests
+
+- **Upstream is `ainetus`; `marota` is the working fork.** Development branches
+  are pushed to `marota/Co-Study4Grid`, but **pull requests are opened directly
+  against the upstream `ainetus/Co-Study4Grid`** (base = its default branch,
+  head = `marota:<branch>`) — *not* against `marota`. The sibling library
+  `Expert_op4grid_recommender` follows the same rule against
+  `ainetus/Expert_op4grid_recommender`.
+- **Load `ainetus` as an initial source.** A cross-fork PR into `ainetus` can
+  only be created from a session/tool context that has the `ainetus` repo in
+  scope, so a new working session should be started with
+  **`ainetus/Co-Study4Grid` and `ainetus/Expert_op4grid_recommender` as the
+  initial sources** (they should always be auto-loaded). A session rooted only
+  at `marota` cannot target `ainetus` (cross-tier adds are blocked) and the PR
+  step fails with an access-denied error.
+- **Sync `marota` with `ainetus` before starting new work.** PRs merge into
+  `ainetus/main`, but development happens on `marota`, so `marota/main` drifts
+  behind `ainetus/main` after every merged PR (this applies to **both** repos —
+  Co-Study4Grid and Expert_op4grid_recommender). **At the start of a dev session,
+  bring `marota/main` up to date with `ainetus/main`** — GitHub "Sync fork", or
+  locally `git fetch ainetus main && git merge --ff-only ainetus/main` then push
+  `marota/main` — and branch from there. Skipping this makes a new branch collide
+  with the already-merged revisions when it is PR'd into `ainetus`. If the sync
+  was missed and the PR already shows conflicts, merge `ainetus/main` into the
+  branch (or rebase onto it) and resolve, then force-with-lease push.
+- **DCO sign-off is required on every commit.** The `ainetus` repos enforce the
+  [Developer Certificate of Origin](https://developercertificate.org/): every
+  commit must carry a `Signed-off-by: <Name> <amarot91@gmail.com>` trailer, and
+  because the DCO check matches the sign-off against the commit **author**, the
+  commit must also be *authored* under that same identity (author email =
+  `amarot91@gmail.com`):
+
+  ```bash
+  git config user.name  "<Name>"
+  git config user.email "amarot91@gmail.com"
+  git commit -s -m "..."          # -s appends the Signed-off-by trailer
+  ```
+
+  To sign off commits already made under a different identity, re-author and add
+  the trailer (`git rebase --exec 'git commit --amend --no-edit --reset-author \
+  -s' <base>`), then force-with-lease push.
+
+---
+
+## Standalone Interface Parity Audit
+
+The detailed audit — feature inventory, mirror-status table, Layer
+1–4 conformity findings, regression-guard matrix, gap-priority list
+and delta-vs-previous commits — lives in
+[`frontend/PARITY_AUDIT.md`](frontend/PARITY_AUDIT.md). That
+document is the working record of the parity project and is
+updated as fixes land.
+
+Quick status summary (2026-05-05):
+
+- Canonical distribution is now the auto-generated
+  `frontend/dist-standalone/standalone.html`
+  (`npm run build:standalone`). The hand-maintained
+  `standalone_interface.html` has been decommissioned and
+  renamed to `standalone_interface_legacy.html` — committed as
+  a frozen snapshot of its last version (commit `5d2b9d1` content),
+  do NOT edit further. Regenerate UI from `frontend/src/` via
+  `npm run build:standalone` instead. The standalone versioned
+  snapshot was bumped to v0.7 on `adae7ac` to include references
+  to the new `/api/*-diagram-patch` endpoints.
+- Four parity layers run against the React source + the
+  standalone of choice:
+  - **Layer 1 — static parity** (`scripts/check_standalone_parity.py`)
+  - **Layer 2 — session-reload fidelity** (`scripts/check_session_fidelity.py`)
+  - **Layer 3a — gesture-sequence static proxy** (`scripts/check_gesture_sequence.py`)
+  - **Layer 3b — behavioural E2E** (`scripts/parity_e2e/e2e_parity.spec.ts`)
+  - **Layer 4 — user-observable invariants** (`scripts/check_invariants.py`)
+- All parity scripts accept `COSTUDY4GRID_STANDALONE_PATH` to
+  re-target any artifact; they default to the auto-gen bundle
+  and fall back to the legacy file when the auto-gen is not
+  built.
+
+See [`frontend/PARITY_AUDIT.md`](frontend/PARITY_AUDIT.md) for
+the full gap list, the session-fidelity regression record, the
+honest-gap report of what each layer catches and misses, and the
+2026-04-20 delta that documents the `/api/restore-analysis-context`
+one-way API drift (now resolved) and the auto-generated-standalone
+viability confirmation.

CONTRIBUTING.md

@@ -0,0 +1,153 @@
+# Contributing to Co-Study4Grid
+
+Thanks for taking the time to contribute. This document captures the
+conventions that keep the codebase easy to work in. For the project
+overview and architecture see [`CLAUDE.md`](./CLAUDE.md).
+
+## Development setup
+
+### Backend
+
+```bash
+python -m pip install --upgrade pip
+pip install ".[test]"
+pip install --no-deps expert_op4grid_recommender
+uvicorn expert_backend.main:app --host 0.0.0.0 --port 8000
+```
+
+#### System prerequisite — Graphviz (`dot`)
+
+The overflow-graph rendering pipeline shells out to Graphviz's
+`dot` binary. `pip install` attempts a best-effort auto-install via
+the platform's package manager (apt / dnf / pacman / apk on Linux,
+Homebrew or MacPorts on macOS, Chocolatey / winget / Scoop on
+Windows); set `COSTUDY4GRID_SKIP_GRAPHVIZ_INSTALL=1` to opt out.
+Modern wheel-based installs may skip the `setup.py` post-install
+hook — re-run it manually with the bundled console script if
+`dot -V` fails:
+
+```bash
+costudy4grid-install-graphviz
+```
+
+If the auto-install can't elevate (no `sudo`, locked package DB,
+unsupported package manager), install Graphviz by hand:
+
+| Platform                | Command                                           |
+|-------------------------|---------------------------------------------------|
+| Debian / Ubuntu         | `sudo apt-get install graphviz`                   |
+| RHEL / Fedora           | `sudo dnf install graphviz` (or `yum`)            |
+| Arch                    | `sudo pacman -S graphviz`                         |
+| Alpine                  | `sudo apk add graphviz`                           |
+| macOS (Homebrew)        | `brew install graphviz`                           |
+| macOS (MacPorts)        | `sudo port install graphviz`                      |
+| Windows (Chocolatey)    | `choco install graphviz`                          |
+| Windows (winget)        | `winget install Graphviz.Graphviz`                |
+| Windows (Scoop)         | `scoop install graphviz`                          |
+
+### Frontend
+
+```bash
+cd frontend
+npm install
+npm run dev    # Vite dev server with HMR (default port 5173)
+```
+
+## Running tests
+
+```bash
+# Backend
+pytest
+
+# Frontend
+cd frontend
+npm run test
+npm run lint
+```
+
+## Code-quality checks
+
+Continuous quality metrics are generated by
+[`scripts/code_quality_report.py`](./scripts/code_quality_report.py) and
+enforced by [`scripts/check_code_quality.py`](./scripts/check_code_quality.py).
+Both run locally and in CI (see `.github/workflows/code-quality.yml`).
+
+```bash
+# Generate a full JSON + Markdown report
+python scripts/code_quality_report.py --output reports/code-quality.json \
+                                      --markdown reports/code-quality.md
+
+# Gate a pull request (non-zero exit on regression)
+python scripts/check_code_quality.py
+```
+
+The gate enforces (full table in
+[`scripts/check_code_quality.py`](./scripts/check_code_quality.py)):
+
+- No new `print()` or `traceback.print_exc()` calls in backend sources
+- No new bare `except Exception: pass` patterns
+- Backend modules stay under **1150 lines** (the "god-object" ceiling);
+  functions under **240**. The scan covers all of `expert_backend/`
+  except the test suite and the setup-time / ad-hoc scripts.
+- Backend functions also stay under **cyclomatic complexity 38** and
+  **nesting depth 8** (computed from the AST — no external tool).
+- Frontend components stay under **1450 lines** (`utils/**` under
+  **1000**); `App.tsx`, the orchestration hub, has a bounded **2100**
+  ceiling rather than a blanket exemption.
+- No `any` / `as any` annotations, and no `@ts-ignore` /
+  `@ts-expect-error` / `@ts-nocheck` in frontend sources
+- **Ratcheted** (frozen at today's count, may only go down): backend
+  `# noqa` / `# type: ignore` (**3**), `as unknown as` casts (**12**),
+  `Record<string, unknown>` usages (**45**)
+- **No hex color literals** in frontend source. The ceiling is zero —
+  every colour must come from a named token. Define new colours in
+  [`frontend/src/styles/tokens.css`](./frontend/src/styles/tokens.css)
+  (the canonical CSS variables) and re-export them from
+  [`frontend/src/styles/tokens.ts`](./frontend/src/styles/tokens.ts)
+  for inline-style consumers (`colors` / `space` / `text` / `radius`,
+  plus `pinColors` / `pinChrome` for SVG-attribute use cases). Both
+  token files are exempt from the gate; nothing else is.
+
+Lower the thresholds — don't raise them. Tightening the gate
+is how we protect the hard-won reductions documented in
+[`docs/architecture/code-quality-analysis.md`](./docs/architecture/code-quality-analysis.md).
+
+**mypy gates the build.** The shared-state base
+([`expert_backend/services/_recommender_state.py`](./expert_backend/services/_recommender_state.py))
+makes the mixin composition type-check cleanly, so mypy sits at 0 and any
+new type error fails CI. **Test coverage gates** on both ends: frontend
+via `frontend/vite.config.ts` (`coverage.thresholds`, enforced by
+`npm run test:coverage`) and backend via `pyproject.toml`
+(`[tool.coverage.report] fail_under = 72`, enforced by `pytest --cov`).
+Both floors sit a few points below the measured baseline — raise them as
+coverage climbs, don't lower them. All are wired into the GitHub Actions
+pipelines; see §§19–20 of the analysis doc.
+
+## Commit & PR conventions
+
+- **Conventional-commit prefixes**: `feat:`, `fix:`, `perf:`, `docs:`,
+  `test:`, `refactor:`, `build:`, `chore:`. Match the surrounding git log.
+- Keep PRs focused. One logical change per PR.
+- Run `pytest`, `npm run test`, `npm run lint`, and
+  `python scripts/check_code_quality.py` before opening a PR.
+- Update [`docs/architecture/code-quality-analysis.md`](./docs/architecture/code-quality-analysis.md)
+  when a fix resolves a documented issue.
+
+## Style
+
+- **Python**: PEP 8 manually (4-space indent, type hints where helpful,
+  snake_case). Use `logging`, not `print`. Ruff runs in CI with a light
+  ruleset — see `pyproject.toml`.
+- **TypeScript**: strict mode (`strict: true`, `noUnusedLocals`,
+  `noUnusedParameters`). No `any`. Functional components + hooks.
+  ESLint flat config enforces the rest.
+- **Editor defaults** live in `.editorconfig`.
+
+## Reporting bugs
+
+Open a GitHub issue with:
+
+1. Steps to reproduce (network path, action file, settings, contingency).
+2. Expected vs. actual behaviour.
+3. Browser console + backend stderr when UI-related.
+4. The attached session folder when reproducible via save/reload.

Dockerfile

@@ -0,0 +1,108 @@
+# Co-Study4Grid — single-container image for a HuggingFace Docker Space.
+#
+# The frontend (built same-origin) and the FastAPI backend are served by one
+# uvicorn process on port 7860. Bundled sample grids (data/) let the Game Mode
+# presets resolve out of the box. See deploy/huggingface/ for the Space README
+# and step-by-step setup.
+#
+# Build context = repo root:  docker build -t costudy4grid .
+
+# ---------------------------------------------------------------------------
+# Stage 1 — build the React SPA (same-origin API, game mode on by default).
+# ---------------------------------------------------------------------------
+FROM node:20-bookworm-slim AS frontend
+
+WORKDIR /build
+COPY frontend/package.json frontend/package-lock.json ./
+RUN npm ci
+
+COPY frontend/ ./
+# Empty base URL → relative `/api/...` requests, served by the backend below.
+# VITE_GAME_MODE=1 → the Space boots straight into the timed game shell.
+ENV VITE_API_BASE_URL="" \
+    VITE_GAME_MODE="1"
+RUN npm run build
+
+# ---------------------------------------------------------------------------
+# Stage 2 — Python runtime serving API + built SPA + bundled grids.
+# ---------------------------------------------------------------------------
+FROM python:3.11-slim-bookworm AS runtime
+
+# graphviz `dot`: overflow-graph rendering. libgomp1: OpenMP runtime that the
+# scientific wheels (numpy / scipy / lightsim2grid) link against.
+RUN apt-get update && apt-get install -y --no-install-recommends \
+        graphviz \
+        libgomp1 \
+    && rm -rf /var/lib/apt/lists/*
+
+# HuggingFace Spaces run the container as uid 1000 ("user"). Keep the app under
+# its home so runtime writes (Overflow_Graph/, config.json, session folders)
+# land on a writable path.
+RUN useradd -m -u 1000 user
+USER user
+ENV HOME=/home/user \
+    PATH=/home/user/.local/bin:$PATH \
+    PYTHONUNBUFFERED=1
+WORKDIR /home/user/app
+
+# --- Python dependencies (own layer for caching) ---------------------------
+# `pip install .` pulls the declared runtime deps (ExpertOp4Grid, pypowsybl,
+# fastapi, …). The recommender ships with `--no-deps` — mirroring CI — because
+# its own dependency tree is self-conflicting (it wants numpy>=2 while its
+# transitive `pypowsybl2grid` pins numpy==1.26.4); the working runtime deps
+# come from `pip install .`. It is pinned via recommender-pin.txt (QW8) — the
+# SAME file CI installs — so a zero-change rebuild can't drift to a new
+# release. overrides.txt forces the pinned transitive versions last.
+COPY --chown=user pyproject.toml README.md overrides.txt recommender-pin.txt ./
+COPY --chown=user expert_backend/ ./expert_backend/
+RUN pip install --no-cache-dir --upgrade pip \
+    && pip install --no-cache-dir . \
+    && pip install --no-cache-dir --no-deps -r recommender-pin.txt \
+    && pip install --no-cache-dir -r overrides.txt
+
+# --- Application code, bundled grids, built SPA ----------------------------
+# Seed the default user config (recommender params + the fr225_400 paths);
+# the backend copies it to config.json on first boot.
+COPY --chown=user config.default.json ./
+COPY --chown=user data/ ./data/
+COPY --chown=user scripts/ ./scripts/
+# The European grid ships compressed (its raw .xiidm exceeds HuggingFace's
+# 10 MiB git file limit, so it travels as a Git-LFS .zip). Validate + decompress
+# it so pypowsybl can load network.xiidm directly — the "Medium" game difficulty.
+# The helper FAILS LOUDLY on an un-smudged LFS pointer or a corrupt archive
+# (QW25) instead of silently baking a broken grid into the image.
+RUN python scripts/extract_network_zip.py data/pypsa_eur_eur220_225_380_400/network.xiidm.zip
+COPY --chown=user --from=frontend /build/dist ./frontend/dist
+# The overflow-viewer overlay (services/overflow_overlay.py) inlines this
+# shared pin-glyph source module at request time, so it must exist at the
+# path it expects even though the rest of frontend/src is not shipped.
+COPY --chown=user frontend/src/utils/svg/pinGlyph.js ./frontend/src/utils/svg/pinGlyph.js
+
+# The backend serves this directory at "/" (same origin as the API).
+#
+# EXPERT_OP4GRID_REASSESSMENT_PARALLEL=0 forces the per-action reassessment to
+# run SERIALLY. The Space runs on 2 vCPUs; the recommender's container-aware
+# detection already picks serial there, but pinning it makes the guarantee
+# explicit and independent of the host's cgroup exposure — parallel worker
+# threads each clone a full pypowsybl network, so on 2 vCPUs they over-subscribe
+# the CPU and are far SLOWER than serial (the 47 s → ~15 s assessment win).
+ENV COSTUDY4GRID_FRONTEND_DIST=/home/user/app/frontend/dist \
+    EXPERT_OP4GRID_REASSESSMENT_PARALLEL=0 \
+    PORT=7860 \
+    COSTUDY4GRID_LOCKDOWN=1
+# COSTUDY4GRID_LOCKDOWN=1 (D7): this is a public, anonymous-visitor
+# deployment, so the desktop-era filesystem RPCs (custom config path,
+# session save/list/load, native file picker) are disabled — see the
+# lockdown profile in expert_backend/main.py.
+
+EXPOSE 7860
+
+# Liveness probe (QW25): the read-only app-config endpoint stays available even
+# under lockdown (D7), so it's a safe heartbeat. The long start-period covers
+# the slow first network load. Uses $PORT so it tracks a non-default port.
+HEALTHCHECK --interval=30s --timeout=5s --start-period=120s --retries=3 \
+    CMD python -c "import os,sys,urllib.request; urllib.request.urlopen('http://127.0.0.1:%s/api/user-config' % os.environ.get('PORT','7860')).read(); sys.exit(0)"
+
+# Shell form so ${PORT} expands (QW25: PORT was decorative before); `exec`
+# keeps uvicorn as PID 1 so it receives SIGTERM directly for clean shutdown.
+CMD ["sh", "-c", "exec uvicorn expert_backend.main:app --host 0.0.0.0 --port ${PORT:-7860}"]

LICENSE.md

@@ -0,0 +1,373 @@
+Mozilla Public License Version 2.0
+==================================
+
+1. Definitions
+--------------
+
+1.1. "Contributor"
+    means each individual or legal entity that creates, contributes to
+    the creation of, or owns Covered Software.
+
+1.2. "Contributor Version"
+    means the combination of the Contributions of others (if any) used
+    by a Contributor and that particular Contributor's Contribution.
+
+1.3. "Contribution"
+    means Covered Software of a particular Contributor.
+
+1.4. "Covered Software"
+    means Source Code Form to which the initial Contributor has attached
+    the notice in Exhibit A, the Executable Form of such Source Code
+    Form, and Modifications of such Source Code Form, in each case
+    including portions thereof.
+
+1.5. "Incompatible With Secondary Licenses"
+    means
+
+    (a) that the initial Contributor has attached the notice described
+        in Exhibit B to the Covered Software; or
+
+    (b) that the Covered Software was made available under the terms of
+        version 1.1 or earlier of the License, but not also under the
+        terms of a Secondary License.
+
+1.6. "Executable Form"
+    means any form of the work other than Source Code Form.
+
+1.7. "Larger Work"
+    means a work that combines Covered Software with other material, in
+    a separate file or files, that is not Covered Software.
+
+1.8. "License"
+    means this document.
+
+1.9. "Licensable"
+    means having the right to grant, to the maximum extent possible,
+    whether at the time of the initial grant or subsequently, any and
+    all of the rights conveyed by this License.
+
+1.10. "Modifications"
+    means any of the following:
+
+    (a) any file in Source Code Form that results from an addition to,
+        deletion from, or modification of the contents of Covered
+        Software; or
+
+    (b) any new file in Source Code Form that contains any Covered
+        Software.
+
+1.11. "Patent Claims" of a Contributor
+    means any patent claim(s), including without limitation, method,
+    process, and apparatus claims, in any patent Licensable by such
+    Contributor that would be infringed, but for the grant of the
+    License, by the making, using, selling, offering for sale, having
+    made, import, or transfer of either its Contributions or its
+    Contributor Version.
+
+1.12. "Secondary License"
+    means either the GNU General Public License, Version 2.0, the GNU
+    Lesser General Public License, Version 2.1, the GNU Affero General
+    Public License, Version 3.0, or any later versions of those
+    licenses.
+
+1.13. "Source Code Form"
+    means the form of the work preferred for making modifications.
+
+1.14. "You" (or "Your")
+    means an individual or a legal entity exercising rights under this
+    License. For legal entities, "You" includes any entity that
+    controls, is controlled by, or is under common control with You. For
+    purposes of this definition, "control" means (a) the power, direct
+    or indirect, to cause the direction or management of such entity,
+    whether by contract or otherwise, or (b) ownership of more than
+    fifty percent (50%) of the outstanding shares or beneficial
+    ownership of such entity.
+
+2. License Grants and Conditions
+--------------------------------
+
+2.1. Grants
+
+Each Contributor hereby grants You a world-wide, royalty-free,
+non-exclusive license:
+
+(a) under intellectual property rights (other than patent or trademark)
+    Licensable by such Contributor to use, reproduce, make available,
+    modify, display, perform, distribute, and otherwise exploit its
+    Contributions, either on an unmodified basis, with Modifications, or
+    as part of a Larger Work; and
+
+(b) under Patent Claims of such Contributor to make, use, sell, offer
+    for sale, have made, import, and otherwise transfer either its
+    Contributions or its Contributor Version.
+
+2.2. Effective Date
+
+The licenses granted in Section 2.1 with respect to any Contribution
+become effective for each Contribution on the date the Contributor first
+distributes such Contribution.
+
+2.3. Limitations on Grant Scope
+
+The licenses granted in this Section 2 are the only rights granted under
+this License. No additional rights or licenses will be implied from the
+distribution or licensing of Covered Software under this License.
+Notwithstanding Section 2.1(b) above, no patent license is granted by a
+Contributor:
+
+(a) for any code that a Contributor has removed from Covered Software;
+    or
+
+(b) for infringements caused by: (i) Your and any other third party's
+    modifications of Covered Software, or (ii) the combination of its
+    Contributions with other software (except as part of its Contributor
+    Version); or
+
+(c) under Patent Claims infringed by Covered Software in the absence of
+    its Contributions.
+
+This License does not grant any rights in the trademarks, service marks,
+or logos of any Contributor (except as may be necessary to comply with
+the notice requirements in Section 3.4).
+
+2.4. Subsequent Licenses
+
+No Contributor makes additional grants as a result of Your choice to
+distribute the Covered Software under a subsequent version of this
+License (see Section 10.2) or under the terms of a Secondary License (if
+permitted under the terms of Section 3.3).
+
+2.5. Representation
+
+Each Contributor represents that the Contributor believes its
+Contributions are its original creation(s) or it has sufficient rights
+to grant the rights to its Contributions conveyed by this License.
+
+2.6. Fair Use
+
+This License is not intended to limit any rights You have under
+applicable copyright doctrines of fair use, fair dealing, or other
+equivalents.
+
+2.7. Conditions
+
+Sections 3.1, 3.2, 3.3, and 3.4 are conditions of the licenses granted
+in Section 2.1.
+
+3. Responsibilities
+-------------------
+
+3.1. Distribution of Source Form
+
+All distribution of Covered Software in Source Code Form, including any
+Modifications that You create or to which You contribute, must be under
+the terms of this License. You must inform recipients that the Source
+Code Form of the Covered Software is governed by the terms of this
+License, and how they can obtain a copy of this License. You may not
+attempt to alter or restrict the recipients' rights in the Source Code
+Form.
+
+3.2. Distribution of Executable Form
+
+If You distribute Covered Software in Executable Form then:
+
+(a) such Covered Software must also be made available in Source Code
+    Form, as described in Section 3.1, and You must inform recipients of
+    the Executable Form how they can obtain a copy of such Source Code
+    Form by reasonable means in a timely manner, at a charge no more
+    than the cost of distribution to the recipient; and
+
+(b) You may distribute such Executable Form under the terms of this
+    License, or sublicense it under different terms, provided that the
+    license for the Executable Form does not attempt to limit or alter
+    the recipients' rights in the Source Code Form under this License.
+
+3.3. Distribution of a Larger Work
+
+You may create and distribute a Larger Work under terms of Your choice,
+provided that You also comply with the requirements of this License for
+the Covered Software. If the Larger Work is a combination of Covered
+Software with a work governed by one or more Secondary Licenses, and the
+Covered Software is not Incompatible With Secondary Licenses, this
+License permits You to additionally distribute such Covered Software
+under the terms of such Secondary License(s), so that the recipient of
+the Larger Work may, at their option, further distribute the Covered
+Software under the terms of either this License or such Secondary
+License(s).
+
+3.4. Notices
+
+You may not remove or alter the substance of any license notices
+(including copyright notices, patent notices, disclaimers of warranty,
+or limitations of liability) contained within the Source Code Form of
+the Covered Software, except that You may alter any license notices to
+the extent required to remedy known factual inaccuracies.
+
+3.5. Application of Additional Terms
+
+You may choose to offer, and to charge a fee for, warranty, support,
+indemnity or liability obligations to one or more recipients of Covered
+Software. However, You may do so only on Your own behalf, and not on
+behalf of any Contributor. You must make it absolutely clear that any
+such warranty, support, indemnity, or liability obligation is offered by
+You alone, and You hereby agree to indemnify every Contributor for any
+liability incurred by such Contributor as a result of warranty, support,
+indemnity or liability terms You offer. You may include additional
+disclaimers of warranty and limitations of liability specific to any
+jurisdiction.
+
+4. Inability to Comply Due to Statute or Regulation
+---------------------------------------------------
+
+If it is impossible for You to comply with any of the terms of this
+License with respect to some or all of the Covered Software due to
+statute, judicial order, or regulation then You must: (a) comply with
+the terms of this License to the maximum extent possible; and (b)
+describe the limitations and the code they affect. Such description must
+be placed in a text file included with all distributions of the Covered
+Software under this License. Except to the extent prohibited by statute
+or regulation, such description must be sufficiently detailed for a
+recipient of ordinary skill to be able to understand it.
+
+5. Termination
+--------------
+
+5.1. The rights granted under this License will terminate automatically
+if You fail to comply with any of its terms. However, if You become
+compliant, then the rights granted under this License from a particular
+Contributor are reinstated (a) provisionally, unless and until such
+Contributor explicitly and finally terminates Your grants, and (b) on an
+ongoing basis, if such Contributor fails to notify You of the
+non-compliance by some reasonable means prior to 60 days after You have
+come back into compliance. Moreover, Your grants from a particular
+Contributor are reinstated on an ongoing basis if such Contributor
+notifies You of the non-compliance by some reasonable means, this is the
+first time You have received notice of non-compliance with this License
+from such Contributor, and You become compliant prior to 30 days after
+Your receipt of the notice.
+
+5.2. If You initiate litigation against any entity by asserting a patent
+infringement claim (excluding declaratory judgment actions,
+counter-claims, and cross-claims) alleging that a Contributor Version
+directly or indirectly infringes any patent, then the rights granted to
+You by any and all Contributors for the Covered Software under Section
+2.1 of this License shall terminate.
+
+5.3. In the event of termination under Sections 5.1 or 5.2 above, all
+end user license agreements (excluding distributors and resellers) which
+have been validly granted by You or Your distributors under this License
+prior to termination shall survive termination.
+
+************************************************************************
+*                                                                      *
+*  6. Disclaimer of Warranty                                           *
+*  -------------------------                                           *
+*                                                                      *
+*  Covered Software is provided under this License on an "as is"       *
+*  basis, without warranty of any kind, either expressed, implied, or  *
+*  statutory, including, without limitation, warranties that the       *
+*  Covered Software is free of defects, merchantable, fit for a        *
+*  particular purpose or non-infringing. The entire risk as to the     *
+*  quality and performance of the Covered Software is with You.        *
+*  Should any Covered Software prove defective in any respect, You     *
+*  (not any Contributor) assume the cost of any necessary servicing,   *
+*  repair, or correction. This disclaimer of warranty constitutes an   *
+*  essential part of this License. No use of any Covered Software is   *
+*  authorized under this License except under this disclaimer.         *
+*                                                                      *
+************************************************************************
+
+************************************************************************
+*                                                                      *
+*  7. Limitation of Liability                                          *
+*  --------------------------                                          *
+*                                                                      *
+*  Under no circumstances and under no legal theory, whether tort      *
+*  (including negligence), contract, or otherwise, shall any           *
+*  Contributor, or anyone who distributes Covered Software as          *
+*  permitted above, be liable to You for any direct, indirect,         *
+*  special, incidental, or consequential damages of any character      *
+*  including, without limitation, damages for lost profits, loss of    *
+*  goodwill, work stoppage, computer failure or malfunction, or any    *
+*  and all other commercial damages or losses, even if such party      *
+*  shall have been informed of the possibility of such damages. This   *
+*  limitation of liability shall not apply to liability for death or   *
+*  personal injury resulting from such party's negligence to the       *
+*  extent applicable law prohibits such limitation. Some               *
+*  jurisdictions do not allow the exclusion or limitation of           *
+*  incidental or consequential damages, so this exclusion and          *
+*  limitation may not apply to You.                                    *
+*                                                                      *
+************************************************************************
+
+8. Litigation
+-------------
+
+Any litigation relating to this License may be brought only in the
+courts of a jurisdiction where the defendant maintains its principal
+place of business and such litigation shall be governed by laws of that
+jurisdiction, without reference to its conflict-of-law provisions.
+Nothing in this Section shall prevent a party's ability to bring
+cross-claims or counter-claims.
+
+9. Miscellaneous
+----------------
+
+This License represents the complete agreement concerning the subject
+matter hereof. If any provision of this License is held to be
+unenforceable, such provision shall be reformed only to the extent
+necessary to make it enforceable. Any law or regulation which provides
+that the language of a contract shall be construed against the drafter
+shall not be used to construe this License against a Contributor.
+
+10. Versions of the License
+---------------------------
+
+10.1. New Versions
+
+Mozilla Foundation is the license steward. Except as provided in Section
+10.3, no one other than the license steward has the right to modify or
+publish new versions of this License. Each version will be given a
+distinguishing version number.
+
+10.2. Effect of New Versions
+
+You may distribute the Covered Software under the terms of the version
+of the License under which You originally received the Covered Software,
+or under the terms of any subsequent version published by the license
+steward.
+
+10.3. Modified Versions
+
+If you create software not governed by this License, and you want to
+create a new license for such software, you may create and use a
+modified version of this License if you rename the license and remove
+any references to the name of the license steward (except to note that
+such modified license differs from this License).
+
+10.4. Distributing Source Code Form that is Incompatible With Secondary
+Licenses
+
+If You choose to distribute Source Code Form that is Incompatible With
+Secondary Licenses under the terms of this version of the License, the
+notice described in Exhibit B of this License must be attached.
+
+Exhibit A - Source Code Form License Notice
+-------------------------------------------
+
+  This Source Code Form is subject to the terms of the Mozilla Public
+  License, v. 2.0. If a copy of the MPL was not distributed with this
+  file, You can obtain one at http://mozilla.org/MPL/2.0/.
+
+If it is not possible or desirable to put the notice in a particular
+file, then You may include the notice in a location (such as a LICENSE
+file in a relevant directory) where a recipient would be likely to look
+for such a notice.
+
+You may add additional accurate notices of copyright ownership.
+
+Exhibit B - "Incompatible With Secondary Licenses" Notice
+---------------------------------------------------------
+
+  This Source Code Form is "Incompatible With Secondary Licenses", as
+  defined by the Mozilla Public License, v. 2.0.

README.md

@@ -0,0 +1,64 @@
+---
+title: Co-Study4Grid Game
+emoji: ⚡
+colorFrom: blue
+colorTo: indigo
+sdk: docker
+app_port: 7860
+pinned: false
+license: mpl-2.0
+---
+
+# Co-Study4Grid — Game Mode
+
+A timed, scored power-grid contingency game built on
+[Co-Study4Grid](https://github.com/marota/Co-Study4Grid). Each **study** is a
+grid state with an N-1 line outage that pushes a line past 100 % loading. Your
+job: bring every monitored line back under 100 % with **at most 3 remedial
+actions** before the per-study timer runs out, then move to the next study.
+
+This Space boots straight into the game (the `VITE_GAME_MODE=1` build flag), so
+there is nothing to configure — pick or tweak the study list and play.
+
+## How to play
+
+1. **Configure** — name the session, set the per-study timer and the action cap
+   (≤ 3), and review the ordered study list. It is pre-filled with a warm-up
+   tour of the bundled PyPSA-EUR France 225/400 kV grid; add more presets or
+   custom studies as you like.
+2. **Play** — a HUD shows the current study, a live countdown, your action
+   counter (`X/3`) and the best resulting line loading. Explore the network,
+   simulate actions, and **star** the ones you commit to. Click **Next study →**
+   (or let the timer expire) to advance.
+3. **Results** — a per-study table plus your final score, with **⬇ JSON
+   (Codabench)** and **⬇ CSV** exports. Submit the JSON to the matching
+   [Codabench](https://www.codabench.org/) competition to be ranked.
+
+## Scoring
+
+Per study (0–100): `60·R + 25·R·A + 15·R·T` — **R** rewards remediation (worst
+line back under 100 %), **A** rewards using fewer actions, **T** rewards speed.
+Session score is the mean across studies. The in-browser scorer is a twin of the
+Codabench Python scorer, locked by unit tests on both sides.
+
+## One player per instance
+
+The backend keeps a **single active study** in memory (module-level
+singletons), so one running Space serves **one player at a time**. For multiple
+players, use the **Duplicate this Space** button (top-right) — each duplicate is
+an isolated instance. A genuinely concurrent multi-player deployment would need
+the backend refactored to be session-scoped; see the repo's deployment notes.
+
+## Resources
+
+Heavy scientific stack (pypowsybl + a JVM-free native lib, grid2op, pandapower,
+lightsim2grid). The free CPU tier (2 vCPU / 16 GB) handles the bundled small and
+fr225_400 grids; first load after a cold start is slow while the container
+boots. Storage is ephemeral — game results are downloaded client-side, so
+nothing important lives on the Space disk.
+
+One exception worth persisting: the **shared solution base** (every retained
+proposition, signed with the player name, that feeds the novelty bonus and the
+usage-frequency feedback). Enable **Settings → Persistent storage** and set the
+`COSTUDY4GRID_DATA_DIR=/data` variable so it survives restarts — without it the
+base still works but resets on every reboot. See `deploy/huggingface/SETUP.md`.

benchmarks/README.md

@@ -0,0 +1,123 @@
+# Co-Study4Grid — Performance benchmarks
+
+Consolidated micro-benchmarks that exercise the critical path of a
+Load Study on the reference **PyPSA-EUR France 400 kV** grid
+(~25 MB SVG, 6 835 VLs, 85 304 switches, 14 880 loads+generators,
+55 104 operational-limit entries).
+
+These scripts drive the same code paths as the web UI but without the
+HTTP stack, so they can be re-run after a patch to catch regressions
+before pushing.
+
+## Prerequisites
+
+```bash
+# Same venv as the backend (`expert_backend`) — needs:
+#   pypowsybl, expert_op4grid_recommender, pandas, numpy
+export PATH="$HOME/.asdf/shims:$PATH"
+python -c "import pypowsybl, expert_op4grid_recommender"
+```
+
+Override the reference grid / action file via env vars:
+
+```bash
+export BENCH_NETWORK_PATH=/path/to/grid_dir          # contains grid.xiidm + grid_layout.json
+export BENCH_ACTION_FILE=/path/to/reduced_actions.json
+export BENCH_CONTINGENCY=DISCO_NAME                  # only for bench_n1_diagram.py
+```
+
+## Scripts
+
+| Script | What it measures | Where the patch history lives |
+|---|---|---|
+| `bench_load_study.py` | Full `/api/config` + 4 parallel XHRs round-trip (reset + load_network + update_config + 4 response helpers). Cumulative target of every patch on the branch. | `docs/performance/history/loading-parallel.md` |
+| `bench_topology_cache.py` | Per-helper + full `NetworkTopologyCache(net)` init. Validates upstream vectorisation series (0.2.0.post3 → post8). | `docs/performance/history/vectorize-topology-cache.md`, `docs/performance/history/topology-cache-iter2.md` |
+| `bench_voltage_level_queries.py` | `/api/voltage-levels`, `/api/nominal-voltages`, `get_monitored_elements`, `_get_switches_with_topology` narrow-attr wins. | `docs/performance/history/narrow-voltage-level-queries.md` |
+| `bench_n1_diagram.py` | Full `get_n1_diagram(contingency)` cold + warm, per-sub-step breakdown. Validates the 3 N-1 fast-path patches. | `docs/performance/history/n1-diagram-fast-path.md` |
+| `bench_nad_n_state.py` | `get_network_diagram()` cold + warm on the N-state. Captures NAD / SVG / Meta sub-timings from the `[RECO]` log lines. | `docs/performance/nad-profile-bare-env.md` |
+| `bench_nad_toggles.py` | Matrix of `NadParameters` toggle combinations — quantifies per-flag impact on NAD gen + SVG size, surfaces the cost of `injections_added=True`. | `docs/performance/nad-profile-bare-env.md` |
+| `bench_analyze_suggest.py` | **Full "Analyze & Suggest" for a Game Mode study** — drives `/api/config` → `step1` → `step2` (streaming NDJSON) through the FastAPI `TestClient` and prints the UI's execution-time breakdown (step1 / overflow / prediction / **assessment** / enrichment / **Other**), with "Other" decomposed into discovery-overhead / result `sanitize_for_json` / transport. `--serial` forces serial reassessment; `--compare` runs parallel-vs-serial. This is the case the 30 s → 75 s regression was reported on. | `docs/performance/history/analyze-suggest-2vcpu.md` |
+| `bench_load_flow_modes.py` | **Per-LF knob sweep** — times a single `run_ac` on the N-1 state under each load-flow parameter variant (tap-changer control mode, shunt / reactive / phase-shifter toggles), reporting time / Newton iters / constrained-line current. Isolates the ~6x reassessment cost to `transformer_voltage_control_on` and shows `AFTER_GENERATOR_VOLTAGE_CONTROL` recovers it. `--contingency` / `--overload` / `--reps`. | `docs/performance/history/reassessment-fast-mode-tap-control.md` |
+| `run_all.py` | Drives every benchmark above sequentially. | — |
+
+### `bench_analyze_suggest.py`
+
+```bash
+# The reported "this case, first scenario": Pyrenees LANNEL61PRAGN on the
+# medium/European grid (its network.xiidm ships as a Git-LFS zip — run
+# `git lfs pull` first, or use --tier high for the uncompressed French grid).
+python benchmarks/bench_analyze_suggest.py                 # medium tier, first study
+python benchmarks/bench_analyze_suggest.py --tier high     # French grid, first study
+python benchmarks/bench_analyze_suggest.py --compare       # parallel vs serial, same case
+```
+
+Two levers this benchmark validates:
+
+- **Per-action reassessment goes serial on a CPU-limited host.** The tail line
+  reports `reassessment: serial|parallel — N worker(s) / M effective core(s)`.
+  On a 2-vCPU host the recommender's container-aware detection picks serial;
+  even on a 4-core dev box `--compare` shows parallel is no faster than serial
+  (each worker clones a full network), so over-subscribing 2 vCPUs with ~10
+  workers was the 47 s assessment in the regression.
+- **The step-2 result payload no longer ships full-grid per-branch arrays.**
+  Each combined-action pair used to carry `p_or_combined` / `p_ex_combined`
+  (one float per line × ~100 pairs ≈ **29 MB** on the European grid); the
+  frontend reads neither, so they are emptied at the API boundary. Watch
+  `payload=… KiB` and the `result sanitize_for_json` sub-line drop
+  (29 269 KiB / 2.57 s → 267 KiB / 0.01 s).
+
+## Reference measurements
+
+On a developer box with pypowsybl 1.14.0 + Python 3.12 + the full
+PyPSA-EUR France 400 kV grid, current branch tip:
+
+### `bench_load_study.py`
+
+| Segment | Measured |
+|---|---|
+| `reset()` | ~0 ms |
+| `load_network` | ~2 200 ms |
+| `update_config` | ~5 900 ms |
+| 4 response XHRs | ~330 ms |
+| **Total** | **~8.5 s** |
+
+This maps to ~8.8 s end-to-end wall-clock on Chrome DevTools traces —
+see v18 row of `docs/performance/history/loading-parallel.md` (-63 % vs v6 baseline).
+
+### `bench_voltage_level_queries.py`
+
+| Endpoint | Before | After |
+|---|---|---|
+| `/api/voltage-levels` | 7.5 ms | 4.5 ms |
+| `/api/nominal-voltages` | **144 ms** | **5.7 ms** (~25×) |
+| `get_monitored_elements` | 265 ms | 175 ms |
+| `_get_switches_with_topology` | 174 ms | 141 ms |
+
+### `bench_n1_diagram.py` (contingency `ARGIAL71CANTE`)
+
+| Call | Before | After |
+|---|---|---|
+| COLD (first view) | 18 125 ms | **4 159 ms** (-77 %) |
+| WARM (repeat view) | 11 906 ms | **3 200 ms** (-73 %) |
+
+## When to run them
+
+- **Before pushing a perf patch** on the backend or on
+  `expert_op4grid_recommender`: run the benchmark closest to the
+  change and confirm no regression on the rest via `run_all.py`.
+- **When a DevTools trace suggests slowdown**: map the hot span to
+  one of the four scripts to isolate it from web-layer variance.
+- **When upstream bumps** `expert_op4grid_recommender`: re-run
+  `bench_topology_cache.py` + `bench_voltage_level_queries.py` to
+  catch behavioural changes in pypowsybl / numpy / pandas upgrades.
+
+## Notes
+
+- These scripts import `expert_backend.services.*` directly, so they
+  need to run inside the Co-Study4Grid venv.
+- Each benchmark is idempotent — running one does not alter global
+  state in a way that would affect the next (each call to
+  `setup_service` resets the recommender).
+- The scripts intentionally use real data paths rather than mocks:
+  the goal is to measure the full pypowsybl + JNI + pandas stack.
+  Unit tests in `expert_backend/tests/` cover the mock path.

benchmarks/_bench_common.py

@@ -0,0 +1,137 @@
+# Copyright (c) 2025-2026, RTE (https://www.rte-france.com)
+# This Source Code Form is subject to the terms of the Mozilla Public License, version 2.0.
+# If a copy of the Mozilla Public License, version 2.0 was not distributed with this file,
+# you can obtain one at http://mozilla.org/MPL/2.0/.
+# SPDX-License-Identifier: MPL-2.0
+
+"""Shared helpers for the Co-Study4Grid performance benchmarks.
+
+Each script in this directory measures a distinct slice of the Load
+Study critical path so that regressions can be caught on the real
+PyPSA-EUR France 400 kV grid without standing up the full web stack.
+
+Usage from each benchmark:
+
+    from _bench_common import bench, setup_service, NETWORK_PATH, ACTION_FILE
+
+    net = pn.load(NETWORK_PATH + "/grid.xiidm")
+    bench("my op", lambda: my_op(net))
+"""
+from __future__ import annotations
+
+import os
+import sys
+import time
+from pathlib import Path
+from types import SimpleNamespace
+from typing import Callable, Iterable
+
+# Make `expert_backend` importable when running a benchmark directly.
+_REPO_ROOT = Path(__file__).resolve().parent.parent
+if str(_REPO_ROOT) not in sys.path:
+    sys.path.insert(0, str(_REPO_ROOT))
+
+# Default reference grid — overridable via env var so benchmarks can
+# also run on smaller test cases in CI.
+NETWORK_PATH = os.environ.get(
+    "BENCH_NETWORK_PATH",
+    "/home/marotant/dev/Expert_op4grid_recommender/data/bare_env_20240828T0100Z",
+)
+ACTION_FILE = os.environ.get(
+    "BENCH_ACTION_FILE",
+    "/home/marotant/dev/Expert_op4grid_recommender/data/action_space/"
+    "reduced_model_actions_20240828T0100Z_dijon.json",
+)
+
+
+def bench(label: str, fn: Callable, reps: int = 5, width: int = 60) -> object:
+    """Time `fn` over `reps` runs and print median/min.
+
+    Returns the last call's return value so the caller can assert
+    semantic equivalence across variants.
+    """
+    dts: list[float] = []
+    ret = None
+    for _ in range(reps):
+        t0 = time.perf_counter()
+        ret = fn()
+        dts.append((time.perf_counter() - t0) * 1000)
+    dts.sort()
+    med = dts[len(dts) // 2]
+    mn = dts[0]
+    print(f"  {label:<{width}} median={med:>7.1f} ms  min={mn:>7.1f}")
+    return ret
+
+
+def setup_service(
+    network_path: str = NETWORK_PATH,
+    action_file: str = ACTION_FILE,
+    wait_for_nad_prefetch: bool = True,
+) -> tuple[object, object, float]:
+    """Prepare `network_service` + `recommender_service` with a
+    realistic config, mimicking `/api/config` from the UI.
+
+    Returns `(network_service, recommender_service, dt_setup_ms)`.
+    """
+    from expert_backend.services.network_service import network_service
+    from expert_backend.services.recommender_service import recommender_service
+
+    settings = SimpleNamespace(
+        network_path=network_path,
+        action_file_path=action_file,
+        layout_path=f"{network_path}/grid_layout.json",
+        min_line_reconnections=2.0,
+        min_close_coupling=3.0,
+        min_open_coupling=2.0,
+        min_line_disconnections=3.0,
+        n_prioritized_actions=10,
+        monitoring_factor=0.95,
+        pre_existing_overload_threshold=0.02,
+        ignore_reconnections=False,
+        pypowsybl_fast_mode=True,
+        min_pst=1.5,
+        min_load_shedding=2.5,
+        min_renewable_curtailment_actions=1,
+        lines_monitoring_path=None,
+        do_visualization=True,
+    )
+
+    t0 = time.perf_counter()
+    recommender_service.reset()
+    network_service.load_network(network_path)
+    recommender_service.update_config(settings)
+    if wait_for_nad_prefetch:
+        ev = getattr(recommender_service, "_prefetched_base_nad_event", None)
+        if ev is not None:
+            ev.wait(timeout=30)
+    dt_setup = (time.perf_counter() - t0) * 1000
+    return network_service, recommender_service, dt_setup
+
+
+def timed(name: str, orig: Callable, store: dict) -> Callable:
+    """Wrap `orig` so every call appends its duration to `store[name]`.
+
+    Used to instrument a live service method without changing its code:
+
+        steps = {}
+        mixin._generate_diagram = timed("generate", mixin._generate_diagram, steps)
+        mixin.get_n1_diagram(...)
+        print(steps)
+    """
+    def wrapped(*a, **kw):
+        t0 = time.perf_counter()
+        try:
+            return orig(*a, **kw)
+        finally:
+            store.setdefault(name, []).append((time.perf_counter() - t0) * 1000)
+    return wrapped
+
+
+def print_step_summary(steps: dict, header: str = "Step timings") -> None:
+    print(f"\n--- {header} ---")
+    for k, dts in steps.items():
+        if not dts:
+            continue
+        total = sum(dts)
+        last = dts[-1]
+        print(f"  {k:<55}  last={last:>8.1f} ms  count={len(dts)}  total={total:>8.1f} ms")

benchmarks/bench_analyze_suggest.py

@@ -0,0 +1,390 @@
+#!/usr/bin/env python3
+# Copyright (c) 2025-2026, RTE (https://www.rte-france.com)
+# This Source Code Form is subject to the terms of the Mozilla Public License, version 2.0.
+# If a copy of the Mozilla Public License, version 2.0 was not distributed with this file,
+# you can obtain one at http://mozilla.org/MPL/2.0/.
+# SPDX-License-Identifier: MPL-2.0
+
+"""Full "Analyze & Suggest" benchmark for a Game Mode study.
+
+Drives the exact code path the Game Mode UI runs for one study —
+``POST /api/config`` → ``/api/run-analysis-step1`` → ``/api/run-analysis-step2``
+(streaming NDJSON) — through the FastAPI ``TestClient`` (in-process, no port),
+and reports the **same per-stage breakdown the UI shows** in its
+"Execution time breakdown" tooltip:
+
+    Step 1 (contingency simulation) ... step1_time
+    Overflow analysis ................. overflow_graph_time
+    Action prediction ................. action_prediction_time
+    Action assessment ................. assessment_time   (per-action reassessment)
+    Enrichment / post-process ......... enrichment_time
+    Other (network / streaming) ....... wall − sum(the five above)
+    Total (wall-clock, click → display) wall
+
+Unlike the UI, it further **decomposes "Other"** into the server-side pieces
+that fall outside the reported stages (discovery overhead = expert-rule filter
++ input building; result-payload ``sanitize_for_json``; NDJSON size), so a
+regression there can be attributed instead of hiding in a single bucket.
+
+This is the case the perf work targets: the Game "first scenario" run that
+regressed from ~30 s to ~75 s on the 2-vCPU HuggingFace Space. Use it to:
+
+- confirm the per-action reassessment goes **serial** on a CPU-limited host
+  (``--serial`` forces it; the tail line reports workers / effective cores);
+- compare parallel vs serial assessment (``--compare``);
+- watch the "Other" residual after a serialization / filtering change.
+
+Usage (from the repo root, backend venv active)::
+
+    python benchmarks/bench_analyze_suggest.py                 # medium tier, first study
+    python benchmarks/bench_analyze_suggest.py --tier high     # French grid, first study
+    python benchmarks/bench_analyze_suggest.py --study s3      # a specific study id
+    python benchmarks/bench_analyze_suggest.py --serial        # force serial reassessment
+    python benchmarks/bench_analyze_suggest.py --compare       # parallel vs serial, same case
+
+Path overrides (when the study's grid is not on disk — e.g. the medium/European
+grid ships as a Git-LFS ``network.xiidm.zip`` that must be pulled first)::
+
+    BENCH_NETWORK_PATH=data/pypsa_eur_fr225_400/network.xiidm \\
+    BENCH_ACTION_FILE=data/pypsa_eur_fr225_400/actions.json \\
+    BENCH_LAYOUT=data/pypsa_eur_fr225_400/grid_layout.json \\
+    BENCH_CONTINGENCY=way_109818602-225 \\
+    python benchmarks/bench_analyze_suggest.py
+"""
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import sys
+import time
+from pathlib import Path
+from typing import Any
+
+_REPO_ROOT = Path(__file__).resolve().parent.parent
+if str(_REPO_ROOT) not in sys.path:
+    sys.path.insert(0, str(_REPO_ROOT))
+
+# ---------------------------------------------------------------------------
+# Study presets — a Python mirror of the two tiers in
+# `frontend/src/game/presets.ts` (kept in sync). The default is the medium
+# tier's FIRST study, matching the Game Config screen's default and the case
+# the perf regression was reported on. The medium/European grid ships as a
+# Git-LFS zip; if it is not pulled, pass --tier high (the French grid ships
+# uncompressed) or set the BENCH_* path overrides.
+# ---------------------------------------------------------------------------
+_EUR = {
+    "network": "data/pypsa_eur_eur220_225_380_400/network.xiidm",
+    "actions": "data/pypsa_eur_eur220_225_380_400/actions.json",
+    "layout": "data/pypsa_eur_eur220_225_380_400/grid_layout.json",
+}
+_FR = {
+    "network": "data/pypsa_eur_fr225_400/network.xiidm",
+    "actions": "data/pypsa_eur_fr225_400/actions.json",
+    "layout": "data/pypsa_eur_fr225_400/grid_layout.json",
+}
+
+TIERS: dict[str, dict[str, Any]] = {
+    "medium": {
+        "paths": _EUR,
+        "studies": [
+            {"id": "eu-pyrenees", "label": "Pyrenees 225 kV — LANNEL61PRAGN",
+             "contingency": "relation_8423570-225"},
+            {"id": "eu-italy", "label": "Campania 380 kV — Santa Sofia",
+             "contingency": "relation_13164355-380"},
+            {"id": "eu-spain", "label": "Hinojosa 400 kV double line",
+             "contingency": "way_170479605-400"},
+        ],
+    },
+    "high": {
+        "paths": _FR,
+        "studies": [
+            {"id": "s1", "label": "Toulouse 225 kV — Saint-Orens - Verfeil",
+             "contingency": "way_109818602-225"},
+            {"id": "s2", "label": "Biancon 225 kV — way/121500507",
+             "contingency": "way_121500507-225"},
+            {"id": "s3", "label": "Valence 225 kV — B.MONL61VALE8",
+             "contingency": "relation_6028666_c-225"},
+            {"id": "s4", "label": "Breuil 225 kV — BREUIL63CHAST",
+             "contingency": "relation_8307566_d-225"},
+            {"id": "s5", "label": "way/1463717755 225 kV",
+             "contingency": "way_1463717755-225"},
+            {"id": "s6", "label": "Échalas 225 kV — Échalas - Le Soleil",
+             "contingency": "way_130969307-225"},
+            {"id": "s7", "label": "Génissiat 400 kV — Cornier - Génissiat",
+             "contingency": "merged_way_100497456-400_1"},
+            {"id": "s8", "label": "Villejust 225 kV — Liers - Villejust",
+             "contingency": "way_204035714-225"},
+        ],
+    },
+}
+
+# Recommender config mirrors config.default.json (the bundled first-run
+# settings the HuggingFace Space boots with).
+CONFIG_MINIMA = {
+    "min_line_reconnections": 2.0,
+    "min_close_coupling": 3.0,
+    "min_open_coupling": 2.0,
+    "min_line_disconnections": 3.0,
+    "min_pst": 1.0,
+    "min_load_shedding": 2.0,
+    "min_renewable_curtailment_actions": 2,
+    "min_redispatch": 2,
+    "n_prioritized_actions": 15,
+    "monitoring_factor": 0.95,
+    "pre_existing_overload_threshold": 0.02,
+    "ignore_reconnections": False,
+    "pypowsybl_fast_mode": True,
+}
+
+
+def _resolve_case(args) -> tuple[dict, dict]:
+    """Return ``(paths, study)`` after applying tier/study selection + env
+    overrides."""
+    tier = TIERS[args.tier]
+    paths = dict(tier["paths"])
+    studies = tier["studies"]
+    if args.study:
+        match = [s for s in studies if s["id"] == args.study]
+        if not match:
+            raise SystemExit(
+                f"study '{args.study}' not in tier '{args.tier}'. "
+                f"Available: {', '.join(s['id'] for s in studies)}"
+            )
+        study = dict(match[0])
+    else:
+        study = dict(studies[0])
+
+    # Env overrides let the benchmark run when a study's grid is not on disk.
+    paths["network"] = os.environ.get("BENCH_NETWORK_PATH", paths["network"])
+    paths["actions"] = os.environ.get("BENCH_ACTION_FILE", paths["actions"])
+    paths["layout"] = os.environ.get("BENCH_LAYOUT", paths["layout"])
+    study["contingency"] = os.environ.get("BENCH_CONTINGENCY", study["contingency"])
+    return paths, study
+
+
+class _Instrument:
+    """Monkeypatches that attribute the server-side share of "Other".
+
+    - ``sanitize_for_json`` (result-payload coercion at the NDJSON yield)
+    - ``run_analysis_step2_discovery`` wall time (so the discovery overhead —
+      expert-rule filter + recommender-input build, which is NOT part of the
+      reported prediction / assessment split — can be isolated).
+    """
+
+    def __init__(self):
+        self.sanitize_s = 0.0
+        self.discovery_wall_s = 0.0
+        self._patches = []
+
+    def __enter__(self):
+        # The model-aware step2 generator lives on AnalysisMixin (explicit
+        # composition since the 2026-07 D1 revision), so both patches
+        # target the analysis_mixin module namespace.
+        from expert_backend.services import analysis_mixin as am
+        si = am
+
+        orig_sanitize = si.sanitize_for_json
+
+        def timed_sanitize(obj):
+            t0 = time.perf_counter()
+            try:
+                return orig_sanitize(obj)
+            finally:
+                self.sanitize_s += time.perf_counter() - t0
+
+        orig_disc = am.run_analysis_step2_discovery
+
+        def timed_discovery(*a, **kw):
+            t0 = time.perf_counter()
+            try:
+                return orig_disc(*a, **kw)
+            finally:
+                self.discovery_wall_s += time.perf_counter() - t0
+
+        si.sanitize_for_json = timed_sanitize
+        am.run_analysis_step2_discovery = timed_discovery
+        self._patches = [
+            (si, "sanitize_for_json", orig_sanitize),
+            (am, "run_analysis_step2_discovery", orig_disc),
+        ]
+        return self
+
+    def __exit__(self, *exc):
+        for mod, name, orig in self._patches:
+            setattr(mod, name, orig)
+        return False
+
+
+def run_once(client, paths, study, reset_between=True) -> dict:
+    """Drive config→step1→step2 for one study; return a metrics dict."""
+    cfg = {
+        "network_path": paths["network"],
+        "action_file_path": paths["actions"],
+        "layout_path": paths["layout"],
+        "model": "expert",
+        "compute_overflow_graph": True,
+        **CONFIG_MINIMA,
+    }
+    t_cfg = time.perf_counter()
+    r = client.post("/api/config", json=cfg)
+    r.raise_for_status()
+    t_cfg = time.perf_counter() - t_cfg
+
+    contingency = study["contingency"]
+    t_s1 = time.perf_counter()
+    r = client.post("/api/run-analysis-step1",
+                    json={"disconnected_elements": [contingency]})
+    r.raise_for_status()
+    t_s1 = time.perf_counter() - t_s1
+    step1 = r.json()
+    overloads = step1.get("lines_overloaded", [])
+    if not (step1.get("can_proceed") and overloads):
+        return {"error": f"no actionable overload (can_proceed={step1.get('can_proceed')}, "
+                         f"{len(overloads)} overload(s))"}
+
+    with _Instrument() as inst:
+        t_s2 = time.perf_counter()
+        r = client.post("/api/run-analysis-step2",
+                        json={"selected_overloads": overloads, "all_overloads": overloads})
+        r.raise_for_status()
+        payload_text = r.text
+        t_s2 = time.perf_counter() - t_s2
+
+    result = {}
+    for line in payload_text.splitlines():
+        line = line.strip()
+        if not line:
+            continue
+        ev = json.loads(line)
+        if ev.get("type") == "result":
+            result = ev
+        elif ev.get("type") == "error":
+            return {"error": ev.get("message")}
+
+    # Per-stage timings reported by the backend (the UI tooltip buckets).
+    step1_t = result.get("step1_time") or 0.0
+    overflow_t = result.get("overflow_graph_time") or 0.0
+    prediction_t = result.get("action_prediction_time") or 0.0
+    assessment_t = result.get("assessment_time") or 0.0
+    enrichment_t = result.get("enrichment_time") or 0.0
+    backend_sum = step1_t + overflow_t + prediction_t + assessment_t + enrichment_t
+
+    # Wall-clock "click → display" proxy: step1 + step2 request wall time.
+    wall = t_s1 + t_s2
+    other = max(0.0, wall - backend_sum)
+    discovery_overhead = max(0.0, inst.discovery_wall_s - prediction_t - assessment_t)
+
+    reassess = result.get("reassessment_parallelism")
+    if reassess is None:
+        from expert_backend.services.recommender_service import recommender_service
+        reassess = (getattr(recommender_service, "_last_result", None) or {}).get(
+            "reassessment_parallelism")
+
+    return {
+        "n_actions": len(result.get("actions", {})),
+        "n_overloads": len(overloads),
+        "payload_bytes": len(payload_text),
+        "t_config": t_cfg,
+        "t_step1_http": t_s1,
+        "t_step2_http": t_s2,
+        "wall": wall,
+        "step1": step1_t,
+        "overflow": overflow_t,
+        "prediction": prediction_t,
+        "assessment": assessment_t,
+        "enrichment": enrichment_t,
+        "backend_sum": backend_sum,
+        "other": other,
+        "other_discovery_overhead": discovery_overhead,
+        "other_sanitize": inst.sanitize_s,
+        "other_residual": max(0.0, other - discovery_overhead - inst.sanitize_s),
+        "reassessment": reassess,
+    }
+
+
+def _fmt(s: float) -> str:
+    return f"{s:6.2f}s"
+
+
+def _print_breakdown(m: dict, title: str) -> None:
+    if "error" in m:
+        print(f"\n{title}: SKIPPED — {m['error']}")
+        return
+    total = m["wall"]
+
+    def pct(x):
+        return f"{100 * x / total:4.0f}%" if total else "   -"
+    print(f"\n=== {title} ===")
+    print(f"  actions={m['n_actions']}  overloads={m['n_overloads']}  "
+          f"payload={m['payload_bytes'] / 1024:.0f} KiB  config-load={_fmt(m['t_config'])}")
+    print(f"  {'Step 1 (contingency simulation)':<34} {_fmt(m['step1'])}  {pct(m['step1'])}")
+    print(f"  {'Overflow analysis':<34} {_fmt(m['overflow'])}  {pct(m['overflow'])}")
+    print(f"  {'Action prediction':<34} {_fmt(m['prediction'])}  {pct(m['prediction'])}")
+    print(f"  {'Action assessment (reassessment)':<34} {_fmt(m['assessment'])}  {pct(m['assessment'])}")
+    print(f"  {'Enrichment / post-process':<34} {_fmt(m['enrichment'])}  {pct(m['enrichment'])}")
+    print(f"  {'Other (network / streaming)':<34} {_fmt(m['other'])}  {pct(m['other'])}")
+    print(f"    ├─ {'discovery overhead (filter+inputs)':<29} {_fmt(m['other_discovery_overhead'])}")
+    print(f"    ├─ {'result sanitize_for_json':<29} {_fmt(m['other_sanitize'])}")
+    print(f"    └─ {'transport / frontend residual':<29} {_fmt(m['other_residual'])}")
+    print(f"  {'─' * 46}")
+    print(f"  {'Total (wall-clock, click → display)':<34} {_fmt(total)}")
+    if m.get("reassessment"):
+        ra = m["reassessment"]
+        mode = "parallel" if ra.get("parallel") else "serial"
+        print(f"  reassessment: {mode} — {ra.get('workers')} worker(s) / "
+              f"{ra.get('cores_available')} effective core(s), "
+              f"{ra.get('n_actions')} action(s)")
+
+
+def main() -> None:
+    ap = argparse.ArgumentParser(description=__doc__,
+                                 formatter_class=argparse.RawDescriptionHelpFormatter)
+    ap.add_argument("--tier", choices=list(TIERS), default="medium",
+                    help="difficulty tier (default: medium = European grid)")
+    ap.add_argument("--study", default=None,
+                    help="study id within the tier (default: first study)")
+    ap.add_argument("--reps", type=int, default=1,
+                    help="repetitions (median reported); a fresh config load per rep")
+    ap.add_argument("--serial", action="store_true",
+                    help="force serial per-action reassessment (EXPERT_OP4GRID_REASSESSMENT_PARALLEL=0)")
+    ap.add_argument("--compare", action="store_true",
+                    help="run the same case twice — parallel then serial — and print both")
+    args = ap.parse_args()
+
+    os.chdir(_REPO_ROOT)
+    from fastapi.testclient import TestClient
+
+    from expert_backend.main import app
+    from expert_op4grid_recommender import config as eo_config
+
+    paths, study = _resolve_case(args)
+    net_ok = Path(paths["network"]).is_file() and Path(paths["network"]).stat().st_size > 1024
+    print(f"Case: tier={args.tier} study={study['id']} ({study['label']})")
+    print(f"  network={paths['network']}  contingency={study['contingency']}")
+    if not net_ok:
+        print(f"\nWARNING: {paths['network']} is missing or a Git-LFS pointer.\n"
+              f"  Pull LFS (git lfs pull) or use --tier high / the BENCH_* path overrides.")
+
+    def _run(force_serial: bool, label: str) -> dict:
+        eo_config.REASSESSMENT_PARALLEL = False if force_serial else None
+        samples = []
+        with TestClient(app) as client:
+            for _ in range(max(1, args.reps)):
+                samples.append(run_once(client, paths, study))
+        ok = [s for s in samples if "error" not in s]
+        if not ok:
+            return samples[0]
+        ok.sort(key=lambda s: s["wall"])
+        return ok[len(ok) // 2]  # median by wall-clock
+
+    if args.compare:
+        _print_breakdown(_run(False, "parallel"), "PARALLEL (auto)")
+        _print_breakdown(_run(True, "serial"), "SERIAL (forced)")
+    else:
+        _print_breakdown(_run(args.serial, "run"),
+                         f"{'SERIAL (forced)' if args.serial else 'AUTO'}")
+
+
+if __name__ == "__main__":
+    main()

benchmarks/bench_load_flow_modes.py

@@ -0,0 +1,132 @@
+#!/usr/bin/env python3
+# Copyright (c) 2025-2026, RTE (https://www.rte-france.com)
+# This Source Code Form is subject to the terms of the Mozilla Public License, version 2.0.
+# If a copy of the Mozilla Public License, version 2.0 was not distributed with this file,
+# you can obtain one at http://mozilla.org/MPL/2.0/.
+# SPDX-License-Identifier: MPL-2.0
+
+"""Per-load-flow micro-benchmark: what makes "slow mode" 6x slower than "fast".
+
+Isolates a SINGLE ``run_ac`` on the post-contingency (N-1) state and times it
+under each load-flow parameter variant, so the cost of the per-action
+reassessment (`utils/reassessment.py` re-simulates every prioritized action
+with one AC LF each) can be attributed to a specific knob rather than guessed.
+
+Key result on the full France grid (`bare_env_20240828T0100Z`, contingency
+``P.SAOL31RONCI`` → overload ``BEON L31CPVAN``): the entire slow/fast gap is
+the **transformer tap-changer voltage-control mode**. The provider default
+(incremental outer loop) needs ~57 Newton iterations/LF; switching to
+``AFTER_GENERATOR_VOLTAGE_CONTROL`` converges in ~20 for the same branch
+current (<0.5 % delta). Disabling tap control entirely (the *old* fast mode)
+is only marginally faster still but changes the currents. See
+``docs/performance/history/reassessment-fast-mode-tap-control.md``.
+
+Usage (from repo root, backend venv active)::
+
+    python benchmarks/bench_load_flow_modes.py
+    python benchmarks/bench_load_flow_modes.py --contingency P.SAOL31RONCI \
+                                               --overload "BEON L31CPVAN" --reps 3
+
+Override the grid with ``BENCH_NETWORK_PATH`` (see ``_bench_common``).
+"""
+from __future__ import annotations
+
+import argparse
+import time
+
+import pypowsybl as pp
+import pypowsybl.loadflow as lf
+
+from _bench_common import NETWORK_PATH
+
+
+def _base_params(**override):
+    """The recommender's slow-mode default (NetworkManager._create_default_lf_parameters).
+
+    ``override`` accepts any ``lf.Parameters`` attribute plus a special
+    ``provider`` dict that is merged into ``provider_parameters``.
+    """
+    provider = {
+        "useActiveLimits": "true",
+        "svcVoltageMonitoring": "false",
+        "voltageRemoteControl": "false",
+        "writeReferenceTerminals": "false",
+        "slackBusSelectionMode": "MOST_MESHED",
+        "maxOuterLoopIterations": "100",
+    }
+    provider.update(override.pop("provider", {}))
+    p = lf.Parameters(
+        read_slack_bus=False,
+        write_slack_bus=False,
+        voltage_init_mode=override.pop("voltage_init_mode", lf.VoltageInitMode.PREVIOUS_VALUES),
+        transformer_voltage_control_on=override.pop("transformer_voltage_control_on", True),
+        use_reactive_limits=override.pop("use_reactive_limits", True),
+        shunt_compensator_voltage_control_on=override.pop("shunt_compensator_voltage_control_on", True),
+        phase_shifter_regulation_on=override.pop("phase_shifter_regulation_on", True),
+        distributed_slack=True,
+        dc_use_transformer_ratio=False,
+        twt_split_shunt_admittance=True,
+        provider_parameters=provider,
+    )
+    for k, v in override.items():
+        setattr(p, k, v)
+    return p
+
+
+def main() -> None:
+    ap = argparse.ArgumentParser(description=__doc__)
+    ap.add_argument("--contingency", default="P.SAOL31RONCI")
+    ap.add_argument("--overload", default="BEON L31CPVAN")
+    ap.add_argument("--reps", type=int, default=3)
+    args = ap.parse_args()
+
+    net = pp.network.load(f"{NETWORK_PATH}/grid.xiidm")
+
+    # Seed a valid state (DC_VALUES init — no previous voltages exist yet),
+    # then apply the contingency on a fresh variant and seed it too, so every
+    # timed config below starts from a converged PREVIOUS_VALUES baseline.
+    seed = _base_params(voltage_init_mode=lf.VoltageInitMode.DC_VALUES)
+    lf.run_ac(net, parameters=seed)
+    net.clone_variant(net.get_variant_ids()[0], "n1")
+    net.set_working_variant("n1")
+    try:
+        net.update_lines(id=args.contingency, connected1=False, connected2=False)
+    except Exception:
+        net.update_2_windings_transformers(id=args.contingency, connected1=False, connected2=False)
+    lf.run_ac(net, parameters=seed)
+
+    def run(label: str, params) -> None:
+        ts = []
+        res = None
+        for _ in range(args.reps):
+            t = time.perf_counter()
+            try:
+                res = lf.run_ac(net, parameters=params)
+            except Exception as e:  # noqa: BLE001
+                print(f"  {label:<44s} FAILED ({str(e)[:50]})")
+                return
+            ts.append(time.perf_counter() - t)
+        r0 = res[0]
+        try:
+            ln = net.get_lines(attributes=["i1", "i2"]).loc[args.overload]
+            imax = f"{max(abs(ln.i1), abs(ln.i2)):.1f}A"
+        except Exception:
+            imax = "n/a"
+        print(f"  {label:<44s} {min(ts):6.3f}s  {r0.status.name:<10s} "
+              f"nr={getattr(r0, 'iteration_count', '?'):>3}  I={imax}")
+
+    print(f"Grid={NETWORK_PATH}  contingency={args.contingency}  overload={args.overload}")
+    print(f"Per-LF run_ac ({args.reps} reps, min):")
+    run("SLOW default (incremental tap control)", _base_params())
+    run("FAST-old (transformer+shunt ctrl OFF)", _base_params(
+        transformer_voltage_control_on=False, shunt_compensator_voltage_control_on=False))
+    run("FAST-new (tap ctrl AFTER_GENERATOR)", _base_params(
+        provider={"transformerVoltageControlMode": "AFTER_GENERATOR_VOLTAGE_CONTROL"}))
+    run("slow, shunt ctrl OFF only", _base_params(shunt_compensator_voltage_control_on=False))
+    run("slow, transformer ctrl OFF only", _base_params(transformer_voltage_control_on=False))
+    run("slow, reactive_limits OFF", _base_params(use_reactive_limits=False))
+    run("slow, phase_shifter_reg OFF", _base_params(phase_shifter_regulation_on=False))
+
+
+if __name__ == "__main__":
+    main()

benchmarks/bench_load_study.py

@@ -0,0 +1,103 @@
+#!/usr/bin/env python3
+# Copyright (c) 2025-2026, RTE (https://www.rte-france.com)
+# SPDX-License-Identifier: MPL-2.0
+
+"""End-to-end profile of a Load Study backend round-trip.
+
+Mimics what `/api/config` + the 4 subsequent parallel XHRs do on a
+real UI click, without the HTTP stack. Used to track the cumulative
+wall-clock gains documented in `docs/performance/history/loading-parallel.md`
+(v6 → v18+ trace entries).
+
+Usage:
+
+    BENCH_NETWORK_PATH=/path/to/grid_dir python benchmarks/bench_load_study.py
+"""
+from __future__ import annotations
+
+import time
+from types import SimpleNamespace
+
+from _bench_common import ACTION_FILE, NETWORK_PATH
+
+
+def main() -> None:
+    print(f"Network:    {NETWORK_PATH}")
+    print(f"Action file: {ACTION_FILE}")
+
+    from expert_backend.services.network_service import network_service
+    from expert_backend.services.recommender_service import recommender_service
+
+    settings = SimpleNamespace(
+        network_path=NETWORK_PATH,
+        action_file_path=ACTION_FILE,
+        layout_path=f"{NETWORK_PATH}/grid_layout.json",
+        min_line_reconnections=2.0,
+        min_close_coupling=3.0,
+        min_open_coupling=2.0,
+        min_line_disconnections=3.0,
+        n_prioritized_actions=10,
+        monitoring_factor=0.95,
+        pre_existing_overload_threshold=0.02,
+        ignore_reconnections=False,
+        pypowsybl_fast_mode=True,
+        min_pst=1.5,
+        min_load_shedding=2.5,
+        min_renewable_curtailment_actions=1,
+        lines_monitoring_path=None,
+        do_visualization=True,
+    )
+
+    # Step 1 — recommender_service.reset() (clears all caches; drains
+    # any stale NAD prefetch from the previous run).
+    t0 = time.perf_counter()
+    recommender_service.reset()
+    dt_reset = (time.perf_counter() - t0) * 1000
+
+    # Step 2 — pypowsybl network parse (~2 s on the PyPSA-EUR France
+    # 118 MB xiidm, dominated by JNI serialisation).
+    t0 = time.perf_counter()
+    network_service.load_network(NETWORK_PATH)
+    dt_load = (time.perf_counter() - t0) * 1000
+
+    # Step 3 — update_config: the big one. Spawns the base-NAD
+    # prefetch worker early (see docs/performance/history/nad-prefetch-earlier-spawn.md),
+    # runs enrich_actions_lazy (NetworkTopologyCache — now ~700 ms
+    # since 0.2.0.post5+post6), sets up SimulationEnvironment.
+    t0 = time.perf_counter()
+    recommender_service.update_config(settings)
+    dt_update = (time.perf_counter() - t0) * 1000
+
+    # Step 4 — the 4 post-config XHRs fired in parallel by the frontend.
+    t0 = time.perf_counter()
+    total_lines = len(network_service.get_disconnectable_elements())
+    monitored = len(network_service.get_monitored_elements())
+    vls = len(network_service.get_voltage_levels())
+    nominals = len(network_service.get_nominal_voltages())
+    dt_resp = (time.perf_counter() - t0) * 1000
+
+    total = dt_reset + dt_load + dt_update + dt_resp
+
+    print(f"\n{'reset()':<32} {dt_reset:>8.1f} ms")
+    print(f"{'load_network':<32} {dt_load:>8.1f} ms")
+    print(f"{'update_config':<32} {dt_update:>8.1f} ms")
+    print(f"{'response XHRs (4)':<32} {dt_resp:>8.1f} ms")
+    print(f"{'TOTAL':<32} {total:>8.1f} ms ({total / 1000:.1f} s)")
+    print(
+        f"\nCounts: lines={total_lines}  monitored={monitored}  "
+        f"vls={vls}  nominals={nominals}"
+    )
+
+    # Step 5 — NAD prefetch overflow: time spent AFTER the 4 XHRs
+    # waiting for the background worker to finish. Should be ~0 ms
+    # if the prefetch was spawned early enough in update_config.
+    ev = getattr(recommender_service, "_prefetched_base_nad_event", None)
+    if ev is not None:
+        t0 = time.perf_counter()
+        ev.wait(timeout=30)
+        dt_wait = (time.perf_counter() - t0) * 1000
+        print(f"\nNAD worker overflow after endpoint: {dt_wait:.1f} ms")
+
+
+if __name__ == "__main__":
+    main()

benchmarks/bench_n1_diagram.py

@@ -0,0 +1,110 @@
+#!/usr/bin/env python3
+# Copyright (c) 2025-2026, RTE (https://www.rte-france.com)
+# SPDX-License-Identifier: MPL-2.0
+
+"""Profile a full `get_n1_diagram(contingency)` call end-to-end.
+
+Covers the three fast-path patches documented in
+`docs/performance/history/n1-diagram-fast-path.md`:
+
+  1. `_get_asset_flows` vectorised   (1 168 ms → 75 ms)
+  2. `_get_overloaded_lines` vect.   (1 161 ms → 98 ms)
+  3. LF-status cache per variant     (600-1000 ms saved per view)
+
+Measures both the COLD call (N-1 variant created + AC LF) and the
+WARM call (variant cached + LF status cached), which is what the
+user experiences when re-visiting the same contingency.
+
+Usage:
+
+    python benchmarks/bench_n1_diagram.py              # default ARGIAL71CANTE
+    BENCH_CONTINGENCY='DISCO_X' python bench_n1_diagram.py
+"""
+from __future__ import annotations
+
+import os
+import time
+
+from _bench_common import NETWORK_PATH, print_step_summary, setup_service, timed
+
+CONTINGENCY = os.environ.get("BENCH_CONTINGENCY", "ARGIAL71CANTE")
+
+
+def _instrument(recommender_service):
+    """Wrap each hot method with the `timed` helper.
+
+    Returns `(steps_dict, restore_fn)`. The caller should invoke
+    `restore_fn()` after benchmarking so the service goes back to
+    normal behaviour.
+    """
+    from expert_backend.services import diagram_mixin as _dm
+
+    steps: dict = {}
+
+    originals = {
+        "_generate_diagram": (_dm.DiagramMixin, "_generate_diagram"),
+        "_run_ac_with_fallback": (recommender_service, "_run_ac_with_fallback"),
+        "_get_n1_variant": (recommender_service, "_get_n1_variant"),
+        "_get_network_flows": (_dm.DiagramMixin, "_get_network_flows"),
+        "_get_asset_flows": (_dm.DiagramMixin, "_get_asset_flows"),
+        "_compute_deltas": (_dm.DiagramMixin, "_compute_deltas"),
+        "_compute_asset_deltas": (_dm.DiagramMixin, "_compute_asset_deltas"),
+        "_get_overloaded_lines": (_dm.DiagramMixin, "_get_overloaded_lines"),
+    }
+
+    backup = {}
+    for label, (obj, attr) in originals.items():
+        orig = getattr(obj, attr)
+        backup[label] = (obj, attr, orig)
+        setattr(obj, attr, timed(label, orig, steps))
+
+    def restore() -> None:
+        for _label, (obj, attr, orig) in backup.items():
+            setattr(obj, attr, orig)
+
+    return steps, restore
+
+
+def main() -> None:
+    print(f"Network:    {NETWORK_PATH}")
+    print(f"Contingency: {CONTINGENCY}")
+
+    _ns, recommender_service, dt_setup = setup_service()
+    print(f"Setup done in {dt_setup:.0f} ms\n")
+
+    steps, restore = _instrument(recommender_service)
+
+    try:
+        # --- COLD call ---
+        print(f"=== Call 1 (COLD: creates N-1 variant + LF status) ===")
+        t0 = time.perf_counter()
+        d1 = recommender_service.get_n1_diagram(CONTINGENCY)
+        dt_cold = (time.perf_counter() - t0) * 1000
+        print(f"Total: {dt_cold:.1f} ms")
+        print(f"  SVG size: {len(d1['svg']):,} bytes")
+        print(f"  overloaded lines: {len(d1['lines_overloaded'])}")
+        print(f"  flow_deltas: {len(d1['flow_deltas'])}")
+        print(f"  asset_deltas: {len(d1['asset_deltas'])}")
+        print_step_summary(steps, "COLD call step timings")
+
+        # Reset counters for warm call
+        for key in steps:
+            steps[key] = []
+
+        # --- WARM call (variant + LF status both cached) ---
+        print(f"\n=== Call 2 (WARM: variant cached + LF status cached) ===")
+        t0 = time.perf_counter()
+        d2 = recommender_service.get_n1_diagram(CONTINGENCY)
+        dt_warm = (time.perf_counter() - t0) * 1000
+        print(f"Total: {dt_warm:.1f} ms")
+        print_step_summary(steps, "WARM call step timings")
+
+        print(f"\n=== Summary ===")
+        print(f"  COLD: {dt_cold/1000:.2f} s")
+        print(f"  WARM: {dt_warm/1000:.2f} s  (Δ = {(dt_cold-dt_warm)/1000:+.2f} s)")
+    finally:
+        restore()
+
+
+if __name__ == "__main__":
+    main()

benchmarks/bench_n1_diagram_patch.py

@@ -0,0 +1,152 @@
+#!/usr/bin/env python3
+# Copyright (c) 2025-2026, RTE (https://www.rte-france.com)
+# SPDX-License-Identifier: MPL-2.0
+
+"""Profile the N-1 patch endpoint (SVG-less payload) vs the full-SVG
+endpoint, end-to-end on the reference bare_env_20240828T0100Z grid.
+
+The patch endpoint skips pypowsybl's `get_network_area_diagram` call
+and the ~12 MB SVG serialisation entirely. The frontend then clones
+the already-loaded N-state SVG DOM and applies the patch in-place,
+avoiding the 20-28 MB transfer and re-parse on each contingency
+selection.
+
+See `docs/performance/history/svg-dom-recycling.md` for the wider
+context and payload schema; this script captures the backend cost
+delta alone (wire + client parse are measured in the frontend).
+
+Usage:
+    python benchmarks/bench_n1_diagram_patch.py                 # default contingency
+    BENCH_CONTINGENCY='DISCO_X' python bench_n1_diagram_patch.py
+"""
+from __future__ import annotations
+
+import json
+import os
+import time
+
+from _bench_common import NETWORK_PATH, setup_service
+
+CONTINGENCY = os.environ.get("BENCH_CONTINGENCY", "ARGIAL71CANTE")
+RESULTS_FILE = os.environ.get(
+    "BENCH_RESULTS_FILE",
+    os.path.join(
+        os.path.dirname(os.path.dirname(os.path.abspath(__file__))),
+        "profiling_patch_results.json",
+    ),
+)
+
+
+def _payload_bytes(payload: dict) -> int:
+    """Rough on-wire size of a JSON payload, pre-gzip."""
+    return len(json.dumps(payload, default=str).encode("utf-8"))
+
+
+def _measure(fn, reps: int = 3) -> tuple[float, list[float]]:
+    """Run `fn` `reps` times, return (median_ms, all_dts_ms)."""
+    dts: list[float] = []
+    for _ in range(reps):
+        t0 = time.perf_counter()
+        fn()
+        dts.append((time.perf_counter() - t0) * 1000)
+    dts_sorted = sorted(dts)
+    return dts_sorted[len(dts_sorted) // 2], dts
+
+
+def main() -> None:
+    print(f"Network:     {NETWORK_PATH}")
+    print(f"Contingency: {CONTINGENCY}")
+
+    _ns, recommender_service, dt_setup = setup_service()
+    print(f"Setup done in {dt_setup:.0f} ms\n")
+
+    # --- COLD full fetch (sets up N-1 variant, AC LF, overload cache) ---
+    print("=== Full /api/n1-diagram (COLD) ===")
+    t0 = time.perf_counter()
+    full_cold = recommender_service.get_n1_diagram(CONTINGENCY)
+    full_cold_ms = (time.perf_counter() - t0) * 1000
+    full_cold_size = _payload_bytes(full_cold)
+    full_cold_svg_mb = len(full_cold["svg"]) / 1_000_000
+    print(f"  total:             {full_cold_ms:>8.1f} ms")
+    print(f"  full payload size: {full_cold_size / 1_000_000:>8.2f} MB")
+    print(f"  SVG size:          {full_cold_svg_mb:>8.2f} MB")
+    print(f"  flow_deltas:       {len(full_cold.get('flow_deltas', {}))}")
+
+    # --- WARM full fetch (variant + LF cached) — median of 3 ---
+    print("\n=== Full /api/n1-diagram (WARM median of 3) ===")
+    full_warm_ms, full_warm_all = _measure(
+        lambda: recommender_service.get_n1_diagram(CONTINGENCY), reps=3
+    )
+    print(f"  median:            {full_warm_ms:>8.1f} ms")
+    print(f"  all runs:          {[f'{d:.0f}' for d in full_warm_all]}")
+
+    # --- COLD patch (expected to reuse LF cache already populated by
+    #    the full-fetch call above; still avoids the ~2-4 s
+    #    `_generate_diagram` NAD call + ~12 MB SVG serialisation) ---
+    print("\n=== Patch /api/n1-diagram-patch (COLD) ===")
+    t0 = time.perf_counter()
+    patch_cold = recommender_service.get_n1_diagram_patch(CONTINGENCY)
+    patch_cold_ms = (time.perf_counter() - t0) * 1000
+    patch_cold_size = _payload_bytes(patch_cold)
+    print(f"  total:             {patch_cold_ms:>8.1f} ms")
+    print(f"  patch payload:     {patch_cold_size / 1_000_000:>8.3f} MB")
+    print(f"  patchable:         {patch_cold['patchable']}")
+    print(f"  flow_deltas:       {len(patch_cold.get('flow_deltas', {}))}")
+    print(f"  absolute_flows:    {sum(len(patch_cold.get('absolute_flows', {}).get(k, {})) for k in ('p1','p2','q1','q2'))}")
+
+    # --- WARM patch — median of 3 ---
+    print("\n=== Patch /api/n1-diagram-patch (WARM median of 3) ===")
+    patch_warm_ms, patch_warm_all = _measure(
+        lambda: recommender_service.get_n1_diagram_patch(CONTINGENCY), reps=3
+    )
+    print(f"  median:            {patch_warm_ms:>8.1f} ms")
+    print(f"  all runs:          {[f'{d:.0f}' for d in patch_warm_all]}")
+
+    # --- Summary ---
+    print(f"\n=== Summary (lower is better) ===")
+    print(f"  FULL  cold: {full_cold_ms/1000:>5.2f} s   warm: {full_warm_ms/1000:>5.2f} s")
+    print(f"  PATCH cold: {patch_cold_ms/1000:>5.2f} s   warm: {patch_warm_ms/1000:>5.2f} s")
+    warm_savings = full_warm_ms - patch_warm_ms
+    cold_savings = full_cold_ms - patch_cold_ms
+    print(f"  Δ cold:    -{cold_savings/1000:>5.2f} s "
+          f"({-100 * cold_savings / full_cold_ms:>5.1f}%)")
+    print(f"  Δ warm:    -{warm_savings/1000:>5.2f} s "
+          f"({-100 * warm_savings / full_warm_ms:>5.1f}%)")
+    print(f"  Payload reduction: "
+          f"{(full_warm_all[0] and full_cold_size) and full_cold_size / 1_000_000:>5.2f} MB → "
+          f"{patch_cold_size / 1_000_000:>5.3f} MB "
+          f"({100 * patch_cold_size / max(full_cold_size, 1):.1f}% of full)")
+
+    # --- Persist to JSON for the perf retrospective doc ---
+    out = {
+        "network_path": NETWORK_PATH,
+        "contingency": CONTINGENCY,
+        "full": {
+            "cold_ms": full_cold_ms,
+            "warm_ms_median": full_warm_ms,
+            "warm_ms_all": full_warm_all,
+            "payload_bytes": full_cold_size,
+            "svg_mb": full_cold_svg_mb,
+        },
+        "patch": {
+            "cold_ms": patch_cold_ms,
+            "warm_ms_median": patch_warm_ms,
+            "warm_ms_all": patch_warm_all,
+            "payload_bytes": patch_cold_size,
+            "patchable": patch_cold["patchable"],
+        },
+        "savings": {
+            "cold_ms": cold_savings,
+            "cold_pct": 100 * cold_savings / max(full_cold_ms, 1),
+            "warm_ms": warm_savings,
+            "warm_pct": 100 * warm_savings / max(full_warm_ms, 1),
+            "payload_ratio_pct": 100 * patch_cold_size / max(full_cold_size, 1),
+        },
+    }
+    with open(RESULTS_FILE, "w", encoding="utf-8") as f:
+        json.dump(out, f, indent=2)
+    print(f"\n  JSON: {RESULTS_FILE}")
+
+
+if __name__ == "__main__":
+    main()

benchmarks/bench_nad_n_state.py

@@ -0,0 +1,140 @@
+#!/usr/bin/env python3
+# Copyright (c) 2025-2026, RTE (https://www.rte-france.com)
+# SPDX-License-Identifier: MPL-2.0
+
+"""Profile N-state NAD generation times (Load Study base diagram).
+
+Runs 3 iterations in a single Python process against the reference
+grid defined by ``BENCH_NETWORK_PATH``. Iteration 1 is cold (fresh
+JVM / pypowsybl caches), iterations 2-3 are warm.
+
+Wraps ``recommender_service.get_network_diagram()`` with
+``time.perf_counter()`` and captures the three sub-timings already
+emitted by ``diagram_mixin._generate_diagram`` via a logging.Handler
+parsing ``[RECO] Diagram generated: NAD Xs, SVG Ys, Meta Zs …``.
+
+Outputs ``profiling_results.json`` at the project root + a stdout
+summary. See ``docs/performance/nad-profile-bare-env.md``.
+
+Usage:
+
+    BENCH_NETWORK_PATH=/path/to/grid_dir \
+        python benchmarks/bench_nad_n_state.py
+"""
+from __future__ import annotations
+
+import json
+import logging
+import re
+import time
+from pathlib import Path
+from statistics import median
+
+from _bench_common import NETWORK_PATH, setup_service
+
+_REPO_ROOT = Path(__file__).resolve().parent.parent
+
+_DIAG_LINE_RE = re.compile(
+    r"\[RECO\] Diagram generated: NAD ([\d.]+)s, SVG ([\d.]+)s, Meta ([\d.]+)s "
+    r"\(SVG length=(\d+)\)"
+)
+
+
+class _DiagramTimingCapture(logging.Handler):
+    """Capture the latest ``[RECO] Diagram generated: …`` log line."""
+
+    def __init__(self) -> None:
+        super().__init__(level=logging.INFO)
+        self.last_match: dict | None = None
+
+    def emit(self, record: logging.LogRecord) -> None:
+        m = _DIAG_LINE_RE.search(record.getMessage())
+        if m:
+            self.last_match = {
+                "nad_s": float(m.group(1)),
+                "svg_s": float(m.group(2)),
+                "meta_s": float(m.group(3)),
+                "svg_len": int(m.group(4)),
+            }
+
+
+def _run(iteration: int, cold: bool, capture: _DiagramTimingCapture) -> dict:
+    capture.last_match = None
+    _, recommender_service, _ = setup_service(wait_for_nad_prefetch=False)
+
+    t0 = time.perf_counter()
+    res = recommender_service.get_network_diagram()
+    total = time.perf_counter() - t0
+
+    if capture.last_match is None:
+        raise RuntimeError(
+            "Did not capture `[RECO] Diagram generated` log line. "
+            "Is diagram_mixin.py still emitting it at INFO level?"
+        )
+
+    svg_bytes = len(res["svg"])
+    row = {
+        "run": iteration,
+        "cold": cold,
+        "total_s": round(total, 3),
+        "nad_s": capture.last_match["nad_s"],
+        "svg_s": capture.last_match["svg_s"],
+        "meta_s": capture.last_match["meta_s"],
+        "svg_bytes": svg_bytes,
+        "svg_mb": round(svg_bytes / (1024 * 1024), 2),
+    }
+    print(
+        f"  run {iteration} ({'cold' if cold else 'warm'}): "
+        f"total={row['total_s']}s  NAD={row['nad_s']}s  "
+        f"SVG={row['svg_s']}s  Meta={row['meta_s']}s  "
+        f"size={row['svg_mb']} MB"
+    )
+    return row
+
+
+def main(iterations: int = 3) -> None:
+    logging.basicConfig(
+        level=logging.INFO,
+        format="%(asctime)s %(levelname)s %(name)s %(message)s",
+    )
+    capture = _DiagramTimingCapture()
+    logging.getLogger().addHandler(capture)
+
+    print(f"Network: {NETWORK_PATH}")
+    print(f"Iterations: {iterations}\n")
+
+    rows = [
+        _run(i, cold=(i == 1), capture=capture)
+        for i in range(1, iterations + 1)
+    ]
+
+    warm = [r for r in rows if not r["cold"]]
+    warm_median = (
+        {
+            "nad_s": round(median(r["nad_s"] for r in warm), 3),
+            "svg_s": round(median(r["svg_s"] for r in warm), 3),
+            "meta_s": round(median(r["meta_s"] for r in warm), 3),
+            "total_s": round(median(r["total_s"] for r in warm), 3),
+        }
+        if warm
+        else None
+    )
+
+    out_file = _REPO_ROOT / "profiling_results.json"
+    out_file.write_text(
+        json.dumps(
+            {"network_path": NETWORK_PATH, "runs": rows, "warm_median": warm_median},
+            indent=2,
+        )
+    )
+    print(f"\nSaved: {out_file}")
+    if warm_median:
+        print(
+            f"Warm median: NAD={warm_median['nad_s']}s  "
+            f"SVG={warm_median['svg_s']}s  Meta={warm_median['meta_s']}s  "
+            f"total={warm_median['total_s']}s"
+        )
+
+
+if __name__ == "__main__":
+    main()

benchmarks/bench_nad_toggles.py

@@ -0,0 +1,189 @@
+#!/usr/bin/env python3
+# Copyright (c) 2025-2026, RTE (https://www.rte-france.com)
+# SPDX-License-Identifier: MPL-2.0
+
+"""Benchmark a matrix of ``NadParameters`` toggle combinations.
+
+Drives ``recommender_service.get_network_diagram()`` with several
+``NadParameters`` overrides (applied via monkey-patching
+``DiagramMixin._default_nad_parameters``) to quantify the per-toggle
+impact on NAD generation time and SVG size.
+
+The matrix below validates the "minimal-render" choices documented in
+``docs/performance/nad-profile-bare-env.md`` (section "Results — after #6")
+and surfaces the cost of ``injections_added=True`` so the trade-off
+can be revisited later.
+
+Outputs ``profiling_toggles_results.json`` at the project root +
+a comparison table on stdout.
+
+Usage:
+
+    BENCH_NETWORK_PATH=/path/to/grid_dir \
+        python benchmarks/bench_nad_toggles.py
+"""
+from __future__ import annotations
+
+import json
+import logging
+import re
+import time
+from pathlib import Path
+from statistics import median
+
+from _bench_common import NETWORK_PATH, setup_service
+
+from expert_backend.services.diagram_mixin import DiagramMixin
+from pypowsybl.network import NadLayoutType, NadParameters
+
+_REPO_ROOT = Path(__file__).resolve().parent.parent
+
+_DIAG_LINE_RE = re.compile(
+    r"\[RECO\] Diagram generated: NAD ([\d.]+)s, SVG ([\d.]+)s, Meta ([\d.]+)s "
+    r"\(SVG length=(\d+)\)"
+)
+
+# Mirror the actual production defaults in
+# `DiagramMixin._default_nad_parameters` so any override below is a
+# pure diff. Keep this dict in sync if that method changes.
+_PROD_KWARGS = dict(
+    edge_name_displayed=False,
+    id_displayed=False,
+    edge_info_along_edge=True,
+    power_value_precision=0,
+    angle_value_precision=0,
+    current_value_precision=1,
+    voltage_value_precision=0,
+    bus_legend=False,
+    substation_description_displayed=False,
+    voltage_level_details=False,
+    injections_added=False,
+    layout_type=NadLayoutType.GEOGRAPHICAL,
+)
+
+
+class _DiagramTimingCapture(logging.Handler):
+    def __init__(self) -> None:
+        super().__init__(level=logging.INFO)
+        self.last_match: dict | None = None
+
+    def emit(self, record: logging.LogRecord) -> None:
+        m = _DIAG_LINE_RE.search(record.getMessage())
+        if m:
+            self.last_match = {
+                "nad_s": float(m.group(1)),
+                "svg_s": float(m.group(2)),
+                "meta_s": float(m.group(3)),
+                "svg_len": int(m.group(4)),
+            }
+
+
+def _make_factory(overrides: dict):
+    """Return a bound-method replacement for `_default_nad_parameters`."""
+    kwargs = dict(_PROD_KWARGS)
+    kwargs.update(overrides)
+
+    def _override(_self):
+        return NadParameters(**kwargs)
+
+    return _override
+
+
+def _run_config(name, overrides, capture, iterations=3):
+    DiagramMixin._default_nad_parameters = _make_factory(overrides)
+
+    print(f"\n>>> Config: {name}")
+    print(f"    overrides: {overrides or '(prod defaults)'}")
+
+    rows = []
+    for i in range(1, iterations + 1):
+        capture.last_match = None
+        _, recommender_service, _ = setup_service(wait_for_nad_prefetch=False)
+
+        t0 = time.perf_counter()
+        res = recommender_service.get_network_diagram()
+        total = time.perf_counter() - t0
+
+        if capture.last_match is None:
+            raise RuntimeError("Did not capture [RECO] Diagram generated line")
+
+        svg_bytes = len(res["svg"])
+        rows.append({
+            "run": i,
+            "total_s": round(total, 3),
+            "nad_s": capture.last_match["nad_s"],
+            "svg_bytes": svg_bytes,
+            "svg_mb": round(svg_bytes / (1024 * 1024), 2),
+        })
+        print(
+            f"  run {i}: total={rows[-1]['total_s']}s  "
+            f"NAD={rows[-1]['nad_s']}s  size={rows[-1]['svg_mb']} MB"
+        )
+
+    # Warm median excludes run 1 (JVM/pypowsybl warm-up absorbed there).
+    warm = rows[1:]
+    return {
+        "config": name,
+        "overrides": overrides,
+        "runs": rows,
+        "warm_median": {
+            "nad_s": round(median(r["nad_s"] for r in warm), 3),
+            "total_s": round(median(r["total_s"] for r in warm), 3),
+            "svg_mb": round(median(r["svg_mb"] for r in warm), 2),
+        },
+    }
+
+
+def main(iterations: int = 3) -> None:
+    logging.basicConfig(
+        level=logging.INFO,
+        format="%(asctime)s %(levelname)s %(name)s %(message)s",
+    )
+    capture = _DiagramTimingCapture()
+    logging.getLogger().addHandler(capture)
+
+    # Revert each toggle individually from the production minimal-render
+    # defaults to quantify its contribution. Plus two "regress" rows for
+    # `injections_added=True` which was measured and *rejected*.
+    configs = [
+        ("prod defaults (minimal-render)", {}),
+        ("+ bus_legend=True (pre-#6 default)", {"bus_legend": True}),
+        (
+            "+ substation_description_displayed=True (pre-#6 default)",
+            {"substation_description_displayed": True},
+        ),
+        ("+ voltage_level_details=True (pypowsybl default)", {"voltage_level_details": True}),
+        ("+ injections_added=True (NOT APPLIED, cost check)", {"injections_added": True}),
+    ]
+
+    print(f"Network: {NETWORK_PATH}")
+    results = [_run_config(n, o, capture, iterations) for n, o in configs]
+
+    out_file = _REPO_ROOT / "profiling_toggles_results.json"
+    out_file.write_text(
+        json.dumps({"network_path": NETWORK_PATH, "configs": results}, indent=2)
+    )
+
+    print("\n" + "=" * 100)
+    print(f"{'Config':<65} | {'NAD(s)':>8} | {'Total(s)':>9} | {'SVG(MB)':>8}")
+    print("-" * 100)
+    baseline = results[0]["warm_median"]
+    for res in results:
+        wm = res["warm_median"]
+        suffix = ""
+        if res["config"] != "prod defaults (minimal-render)":
+            suffix = (
+                f"  Δ nad={wm['nad_s'] - baseline['nad_s']:+.2f}  "
+                f"total={wm['total_s'] - baseline['total_s']:+.2f}  "
+                f"mb={wm['svg_mb'] - baseline['svg_mb']:+.1f}"
+            )
+        print(
+            f"{res['config']:<65} | {wm['nad_s']:>8.3f} | "
+            f"{wm['total_s']:>9.3f} | {wm['svg_mb']:>8.2f}{suffix}"
+        )
+    print("=" * 100)
+    print(f"\nSaved: {out_file}")
+
+
+if __name__ == "__main__":
+    main()

benchmarks/bench_topology_cache.py

@@ -0,0 +1,70 @@
+#!/usr/bin/env python3
+# Copyright (c) 2025-2026, RTE (https://www.rte-france.com)
+# SPDX-License-Identifier: MPL-2.0
+
+"""Breakdown of `NetworkTopologyCache(n)` initialisation.
+
+Validates the cumulative gains of the upstream vectorisation series
+(`expert_op4grid_recommender` 0.2.0.post3 → post8) documented in
+`docs/performance/history/vectorize-topology-cache.md` and
+`docs/performance/history/topology-cache-iter2.md`. Also exercises the narrow
+`_get_switches_with_topology` / `_get_branch_with_bus_breaker_info`
+variants (post6 / post8).
+
+Usage:
+
+    BENCH_NETWORK_PATH=/path/to/grid_dir python benchmarks/bench_topology_cache.py
+"""
+from __future__ import annotations
+
+import pypowsybl as pp
+import pypowsybl.network as pn
+
+from _bench_common import NETWORK_PATH, bench
+
+
+def main() -> None:
+    grid = f"{NETWORK_PATH}/grid.xiidm"
+    print(f"pypowsybl {pp.__version__}")
+    print(f"Grid: {grid}")
+    net = pn.load(grid)
+
+    from expert_op4grid_recommender.utils.conversion_actions_repas import (
+        NetworkTopologyCache,
+        _is_node_breaker_network,
+        _get_switches_with_topology,
+        _get_injection_with_bus_breaker_info,
+        _get_branch_with_bus_breaker_info,
+    )
+
+    is_nb = _is_node_breaker_network(net)
+    print(f"node_breaker: {is_nb}")
+
+    print("\n=== Individual helpers ===")
+    bench(
+        "_get_switches_with_topology",
+        lambda: _get_switches_with_topology(net, node_breaker=is_nb),
+    )
+    bench(
+        "_get_injection_with_bus_breaker_info (loads)",
+        lambda: _get_injection_with_bus_breaker_info(net, "get_loads", node_breaker=is_nb),
+    )
+    bench(
+        "_get_injection_with_bus_breaker_info (gens)",
+        lambda: _get_injection_with_bus_breaker_info(net, "get_generators", node_breaker=is_nb),
+    )
+    bench(
+        "_get_branch_with_bus_breaker_info (branches)",
+        lambda: _get_branch_with_bus_breaker_info(net, "get_branches", node_breaker=is_nb),
+    )
+    bench(
+        "_get_branch_with_bus_breaker_info (lines)",
+        lambda: _get_branch_with_bus_breaker_info(net, "get_lines", node_breaker=is_nb),
+    )
+
+    print("\n=== Full NetworkTopologyCache(net) init ===")
+    bench("NetworkTopologyCache(net)", lambda: NetworkTopologyCache(net), reps=3)
+
+
+if __name__ == "__main__":
+    main()

benchmarks/bench_voltage_level_queries.py

@@ -0,0 +1,73 @@
+#!/usr/bin/env python3
+# Copyright (c) 2025-2026, RTE (https://www.rte-france.com)
+# SPDX-License-Identifier: MPL-2.0
+
+"""Benchmark `/api/voltage-levels`, `/api/nominal-voltages` and the
+operational-limits query used by `/api/branches::get_monitored_elements`.
+
+Documents the narrow-query + vectorisation gains from
+`docs/performance/history/narrow-voltage-level-queries.md`:
+
+  - `/api/voltage-levels`   7.5 ms →  4.5 ms    (attributes=[])
+  - `/api/nominal-voltages` 144 ms  →  5.7 ms   (narrow + no iterrows, ~25×)
+  - get_monitored_elements  265 ms  → 175 ms    (attributes=[])
+  - _get_switches_with_topology 174 ms → 141 ms (drop `kind` attr)
+
+Usage:
+
+    BENCH_NETWORK_PATH=/path/to/grid_dir python benchmarks/bench_voltage_level_queries.py
+"""
+from __future__ import annotations
+
+import pypowsybl.network as pn
+
+from _bench_common import NETWORK_PATH, bench
+
+
+def main() -> None:
+    from expert_backend.services.network_service import NetworkService
+
+    grid = f"{NETWORK_PATH}/grid.xiidm"
+    net = pn.load(grid)
+    svc = NetworkService()
+    svc.network = net
+
+    print(f"Grid: {grid}")
+
+    print("\n=== /api/voltage-levels ===")
+    bench("default get_voltage_levels()", lambda: net.get_voltage_levels())
+    bench("narrow get_voltage_levels(attributes=[])", lambda: net.get_voltage_levels(attributes=[]))
+    vl_list = bench("NetworkService.get_voltage_levels", svc.get_voltage_levels)
+    print(f"  returned {len(vl_list)} VLs")
+
+    print("\n=== /api/nominal-voltages ===")
+    nv = bench("NetworkService.get_nominal_voltages", svc.get_nominal_voltages)
+    print(f"  returned {len(nv)} mappings, unique kV: {sorted(set(nv.values()))}")
+
+    print("\n=== /api/branches::get_monitored_elements ===")
+    bench(
+        "default get_operational_limits()",
+        lambda: net.get_operational_limits(),
+    )
+    bench(
+        "narrow get_operational_limits(attributes=[])",
+        lambda: net.get_operational_limits(attributes=[]),
+    )
+    mon = bench("NetworkService.get_monitored_elements", svc.get_monitored_elements)
+    print(f"  returned {len(mon)} monitored elements")
+
+    print("\n=== _get_switches_with_topology ===")
+    from expert_op4grid_recommender.utils.conversion_actions_repas import (
+        _get_switches_with_topology,
+        _is_node_breaker_network,
+    )
+    is_nb = _is_node_breaker_network(net)
+    sw = bench(
+        "_get_switches_with_topology (post8 narrow, no `kind`)",
+        lambda: _get_switches_with_topology(net, node_breaker=is_nb),
+    )
+    print(f"  shape={sw.shape}  cols={list(sw.columns)}")
+
+
+if __name__ == "__main__":
+    main()

benchmarks/interaction_paint/.gitignore

@@ -0,0 +1,8 @@
+# Generated benchmark artifacts
+nad.svg
+nad.stats.json
+result.json
+# Real pypowsybl NAD fetched from the backend (9 MB; regenerate via
+# GET /api/network-diagram?format=text) — don't track the heavy artifact.
+real_nad.svg
+real_nad.html

benchmarks/interaction_paint/FLUIDITY_FINDINGS.md

@@ -0,0 +1,75 @@
+# Pan/zoom fluidity — empirical evaluation of the "Smooth pan/zoom (GPU)" toggle
+
+Grid: **pypsa_eur_eur220_225_380_400** (5247 VL / 8205 branches; real pypowsybl NAD
+9.1 MB, ~99k–104k DOM nodes). Hardware: **Apple M4 Pro (Metal), Chrome 149, 120 Hz, dpr=1**.
+Metric: **median rAF frame interval during a sustained 2.5 s gesture** (lower = smoother;
+8.3 ms = 120 fps = idle ceiling). 100% "dropped" = never reaches the 120 Hz budget.
+
+Harness: `bench_fluidity.html` driven over CDP (`cdp_driver.mjs`) in a Chrome launched
+with anti-throttle flags so an occluded window still renders at full speed. The real-app
+end-to-end numbers come from driving the actual `usePanZoom` handlers + the real Settings
+toggle (`app_toggle_driver.mjs`, `app_n1_driver.mjs`).
+
+## Results
+
+| Measurement | gesture | plain (no cull) | **cull = toggle OFF** | **gpu transform = toggle ON** | toggle gain |
+|---|---|---|---|---|---|
+| Synthetic NAD (isolated) | pan | 91.7 | 58.3 | 49.8 | 1.17× |
+| Synthetic NAD (isolated) | zoom | 108.6 | 65.0 | 49.6 | 1.31× |
+| **Real pypowsybl NAD (isolated)** | pan | 100.0 | 58.0 | 41.9 | 1.38× |
+| **Real pypowsybl NAD (isolated)** | zoom | 126.7 (p95 1008!) | 65.1 | 43.3 | 1.50× |
+| **Real app, N tab (live usePanZoom)** | pan | — | 60.1 | 50.0 | 1.20× |
+| **Real app, N tab (live usePanZoom)** | zoom | — | 75.0 | 50.1 | 1.50× |
+| **Real app, N-1/Contingency tab** | pan | — | 82.6 | 58.4 | 1.41× |
+| **Real app, N-1/Contingency tab** | zoom | — | 83.9 | 66.7 | 1.26× |
+
+(N-1/action share the identical render path — `MemoizedSvgContainer` + `usePanZoom` +
+`.svg-interacting`; the action tab differs only by a few highlight elements, so its
+fluidity equals N/N-1.)
+
+### Verdict on the toggle
+- The toggle delivers a **real but modest ~1.2–1.5×** over the default. All four arms still
+  drop **100% of frames** — even ON, pan/zoom sit at **~15–24 fps**, never near 60/120.
+- **Why it's small (proven):** a pure ±2 px CSS translate of the `will-change`'d `<svg>` layer
+  is *still* ~42–48 ms/frame (`micro_translate`). Chrome **re-rasterizes the ~100k-node vector
+  SVG on every transform** → `will-change:transform` never yields a reusable GPU texture, so
+  the gesture only saves the viewBox-attribute recompute + non-scaling-stroke re-eval.
+
+## What WOULD make it fluid (proven)
+**Rasterize the NAD to a `<canvas>` once at gesture start, transform the bitmap per frame,
+bake back to viewBox on settle:** **8.3 ms = 120 fps, 0 dropped frames** — on both the
+synthetic and the real NAD. That is **~6× over the toggle** and **~7–8× over the default**,
+and it composites cheaply even on software/VDI (the case the GPU toggle deliberately skips).
+
+### The catch (verified in code, Phase C)
+The bitmap is rasterized via `new Image()`, which renders the SVG in isolation → **App.css
+class-based styling is dropped**. On the **N-1 / action** tabs that means overload halos,
+the contingency glow, and flow-delta colors **vanish** (they come from
+`.nad-overloaded`/`.nad-contingency-highlight`/`.nad-action-target`/`.nad-delta-*` rules,
+not inline attributes — `highlights.ts`). The N tab is bare, which is exactly why the
+8.3 ms held there. → A production bitmap mode must **inline the highlight/delta computed
+styles into the clone** before serializing, and fix cursor-anchored wheel-zoom (the
+`getScreenCTM()` source moves from the live SVG to the canvas).
+
+## Recommendations (ranked)
+1. **(big bet) Bitmap-snapshot mode** as a 3rd `usePanZoom` mode (`'off' | 'gpu' | 'bitmap'`),
+   opt-in/default-OFF. Prereqs: inline halo/delta styles into the clone (fixes N-1/action
+   fidelity), strip `<foreignObject>` (canvas taint — bench already does), dpr-scale the
+   canvas, fix wheel-zoom CTM. Effort L–XL. Reference impl: `bench_fluidity.html`
+   `snapshotCanvas`/`runBitmap`.
+2. **(quick win — REJECTED after measurement) Drop `vector-effect:non-scaling-stroke` during
+   `.svg-interacting`.** Phase C measured ~1.15× on the *synthetic* NAD, but a direct A/B on the
+   **real** pypowsybl NAD (`__runNss` arm, vector-effect verified flipping `none`↔`non-scaling-stroke`)
+   gave **1.00× — zero gain — on both GPU and software rendering** (`--disable-gpu`): pan 50/50 ms,
+   zoom 58.3/58.3 ms. The real bottleneck is pure SVG raster; the stroke recompute is negligible.
+   **Not shipped** — ~60 lines of CSS + a halo/delta protection block for a measured no-op. The
+   synthetic 1.15× did not transfer. [IMPLEMENTED then reverted.]
+3. **(SHIPPED) `commitViewBox` equality guard** (`usePanZoom.ts`) — free, avoids a settle-frame
+   React re-render when the viewBox nets back unchanged (the ~100k nodes are outside React's vdom
+   via `React.memo`+`replaceChildren`, so it's a tiny App-level saving, not a fps mover).
+4. **(SHIPPED, hygiene) Clear `will-change` promptly** on settle in `endInteraction`
+   (smooth-mode only); does NOT shorten the 150 ms wheel debounce. Drops a promoted multi-MB
+   compositor layer between gestures. 0 fps, pure hygiene.
+5. **Reject:** geometry-count culling (≤1.15×, some regress; `content-visibility:auto` is
+   0.89×; `.nad-edge` selectors don't even match the real grid) and a full canvas/WebGL
+   rewrite (same 8.3 ms ceiling at XL effort + breaks svgPatch/inspect/SLD/highlights).

benchmarks/interaction_paint/README.md

@@ -0,0 +1,65 @@
+# Interaction paint benchmark (pan/zoom fluidity)
+
+A browser-driven micro-benchmark for the **frontend** pan/zoom paint cost
+on a large Network Area Diagram. Unlike the Python benchmarks in the parent
+directory (which measure the backend critical path), this one measures what
+the browser actually repaints per frame while the operator pans/zooms.
+
+It needs **no pypowsybl backend**: `generate_nad.mjs` synthesises a
+structurally-faithful NAD straight from a grid's real `grid_layout.json`
+(voltage-level coordinates), reproducing the paint workload — polyline
+strokes, bus circles, edge-info flow `<text>` + arrows, and the expensive
+HTML `<foreignObject>` voltage-level labels — at the true scale of the grid.
+
+## What it shows
+
+The cost (per painted frame) of a viewBox pan/zoom **with vs without** the
+interaction-time culling rule (`.svg-interacting` in
+`frontend/src/App.css`). See
+[`docs/performance/history/interaction-paint-culling.md`](../../docs/performance/history/interaction-paint-culling.md)
+for the analysis and headline numbers.
+
+## Requirements
+
+- Node ≥ 18.
+- A local Playwright install reachable from `frontend/`
+  (`cd frontend && npm i -D playwright`).
+- A Chromium/Chrome binary. The benchmark defaults to the Playwright build
+  at `/opt/pw-browsers/chromium-1194/chrome-linux/chrome`; override with
+  `PW_CHROME=/path/to/chrome`.
+
+> Not wired into CI: the Playwright browser-download host is outside the
+> CI network egress allowlist, so the browser must already be present.
+
+## Run
+
+```bash
+cd benchmarks/interaction_paint
+
+# 1. Build the synthetic NAD from a committed grid layout
+#    (default grid: pypsa_eur_eur220_225_380_400 — 5247 voltage levels)
+node generate_nad.mjs
+#    or pick another grid that has data/<grid>/grid_layout.json:
+# node generate_nad.mjs pypsa_eur_fr225_400
+
+# 2. Benchmark plain vs culled pan/zoom (interleaved, 6 reps)
+PW_CHROME=/path/to/chrome node bench_pan_zoom.mjs
+```
+
+Output (example, headless software-GL — relative numbers, not absolute fps):
+
+```
+pan      plain  mean 290.1ms  median 297.6ms  p95 407.3ms
+pan      cull   mean 188.2ms  median 183.8ms  p95 244ms
+         => culling speedup: mean 1.5x   median 1.6x
+```
+
+## Caveats
+
+- **Headless = software rendering** (SwiftShader, no GPU). Absolute frame
+  times are far higher than on a real GPU desktop; only the *relative*
+  plain-vs-cull comparison is meaningful here. On GPU the culling win is
+  expected to be larger (the CPU-side `<foreignObject>` raster dominates
+  the residual cost relatively more).
+- Always interleave A/B (this script does): back-to-back passes over the
+  same viewBoxes reuse warm raster tiles and overstate the speedup.

benchmarks/interaction_paint/app_bitmap_driver.mjs

@@ -0,0 +1,60 @@
+// Verify the bitmap pan/zoom mode end-to-end in the real app: set each mode
+// via the Settings select, measure sustained drag/wheel fps on the N tab, then
+// load a contingency and capture a MID-gesture screenshot to confirm the bitmap
+// keeps the overload/contingency halos (the N-1/action fidelity prerequisite).
+import { writeFileSync } from 'fs';
+const PORT = 9444;
+const sleep = (ms) => new Promise(r => setTimeout(r, ms));
+async function findTarget(){for(let i=0;i<40;i++){const l=await (await fetch(`http://127.0.0.1:${PORT}/json/list`)).json();const t=l.find(x=>x.type==='page'&&/localhost:5173/.test(x.url));if(t&&t.webSocketDebuggerUrl)return t;await sleep(250);}throw new Error('no app target');}
+function connect(wsUrl){return new Promise(res=>{const ws=new WebSocket(wsUrl);let id=0;const p=new Map();
+  ws.addEventListener('message',ev=>{const m=JSON.parse(ev.data);if(m.id&&p.has(m.id)){const{r,j}=p.get(m.id);p.delete(m.id);m.error?j(new Error(JSON.stringify(m.error))):r(m.result);}});
+  ws.addEventListener('open',()=>{const send=(method,params={})=>new Promise((r,j)=>{const mid=++id;p.set(mid,{r,j});ws.send(JSON.stringify({id:mid,method,params}));});
+    const evalJs=async(e,a=false)=>{const r=await send('Runtime.evaluate',{expression:e,returnByValue:true,awaitPromise:a});if(r.exceptionDetails)throw new Error('eval:'+JSON.stringify(r.exceptionDetails).slice(0,400));return r.result.value;};res({send,evalJs});});});}
+const { send, evalJs } = await connect((await findTarget()).webSocketDebuggerUrl);
+await send('Runtime.enable'); await send('Page.enable');
+const log=(...a)=>console.error(...a);
+
+await evalJs(`
+window.__setInput=(sel,val)=>{const el=document.querySelector(sel);if(!el)return 'no';const s=Object.getOwnPropertyDescriptor(window.HTMLInputElement.prototype,'value').set;s.call(el,val);el.dispatchEvent(new Event('input',{bubbles:true}));return el.value;};
+window.__btn=(txt)=>{const b=[...document.querySelectorAll('button')].find(b=>b.textContent.trim()===txt);if(b){b.click();return true;}return false;};
+window.__summarize=(a)=>{if(!a.length)return null;const s=a.slice().sort((x,y)=>x-y);const n=s.length,mean=a.reduce((p,v)=>p+v,0)/n;const pct=p=>s[Math.min(n-1,Math.floor(p*n))];const drop=a.filter(d=>d>14).length;return{frames:n,median:+pct(0.5).toFixed(2),p95:+pct(0.95).toFixed(2),max:+s[n-1].toFixed(0),fps_median:+(1000/pct(0.5)).toFixed(1),dropPct:+(100*drop/n).toFixed(1)};};
+window.__canvasMounted=()=>!!document.querySelector('.svg-container canvas');
+// first-frame latency: time from mousedown to the first rAF frame (a sync
+// serialize freeze would make this large).
+window.__downToFirstFrame=()=>new Promise(resolve=>{const c=[...document.querySelectorAll('.svg-container')].find(e=>e.offsetParent!==null&&e.querySelector('svg'));if(!c)return resolve(-1);const r=c.getBoundingClientRect(),cx=r.left+r.width/2,cy=r.top+r.height/2;const t0=performance.now();c.dispatchEvent(new MouseEvent('mousedown',{bubbles:true,clientX:cx,clientY:cy,button:0}));window.dispatchEvent(new MouseEvent('mousemove',{bubbles:true,clientX:cx+5,clientY:cy,button:0}));requestAnimationFrame(()=>{const dt=performance.now()-t0;window.dispatchEvent(new MouseEvent('mousemove',{bubbles:true,clientX:cx+10,clientY:cy,button:0}));setTimeout(()=>window.dispatchEvent(new MouseEvent('mouseup',{bubbles:true,clientX:cx+10,clientY:cy,button:0})),50);resolve(+dt.toFixed(1));});});
+window.__dragPan=(d)=>new Promise(resolve=>{const c=[...document.querySelectorAll('.svg-container')].find(e=>e.offsetParent!==null&&e.querySelector('svg'));if(!c)return resolve({error:'no-container'});const r=c.getBoundingClientRect(),cx=r.left+r.width/2,cy=r.top+r.height/2;c.dispatchEvent(new MouseEvent('mousedown',{bubbles:true,clientX:cx,clientY:cy,button:0}));const iv=[];let last=performance.now();const t0=last;function f(now){iv.push(now-last);last=now;const e=now-t0,t=e/d,dx=Math.sin(t*Math.PI*4)*250;window.dispatchEvent(new MouseEvent('mousemove',{bubbles:true,clientX:cx+dx,clientY:cy,button:0}));if(e<d)requestAnimationFrame(f);else{window.dispatchEvent(new MouseEvent('mouseup',{bubbles:true,clientX:cx+dx,clientY:cy,button:0}));iv.shift();resolve(window.__summarize(iv));}}requestAnimationFrame(f);});
+window.__setMode=async(mode)=>{window.__btn('⚙');await new Promise(r=>setTimeout(r,400));window.__btn('Configurations');await new Promise(r=>setTimeout(r,300));const sel=document.querySelector('[data-testid=pan-zoom-mode-select]');if(!sel)return'NO-SELECT';const s=Object.getOwnPropertyDescriptor(window.HTMLSelectElement.prototype,'value').set;s.call(sel,mode);sel.dispatchEvent(new Event('change',{bubbles:true}));const ls=localStorage.getItem('cs4g-smooth-pan-zoom');if(!window.__btn('✕')){const fb=[...document.querySelectorAll('button')].find(b=>/cancel|close/i.test(b.textContent));if(fb)fb.click();}await new Promise(r=>setTimeout(r,400));return ls;};
+'ok';`);
+
+// Configure + load N if needed.
+const mounted0 = await evalJs(`document.querySelector('.svg-container svg')?.querySelectorAll('*').length||0`);
+if (mounted0 < 5000) {
+  if (!(await evalJs(`!!document.querySelector('#networkPathInput')`))) { await evalJs(`window.__btn('⚙')`); await sleep(600); }
+  await evalJs(`window.__setInput('#networkPathInput','data/pypsa_eur_eur220_225_380_400/network.xiidm')`);
+  await evalJs(`window.__setInput('#actionPathInput','data/pypsa_eur_eur220_225_380_400/actions.json')`);
+  await evalJs(`(()=>{const l=[...document.querySelectorAll('label')].find(x=>/layout/i.test(x.textContent));const inp=l&&(l.parentElement.querySelector('input[type=text]')||l.closest('div').querySelector('input[type=text]'));if(inp){const s=Object.getOwnPropertyDescriptor(window.HTMLInputElement.prototype,'value').set;s.call(inp,'data/pypsa_eur_eur220_225_380_400/grid_layout.json');inp.dispatchEvent(new Event('input',{bubbles:true}));}})()`);
+  await evalJs(`window.__btn('Apply')`); log('loading NAD…');
+  for (let i=0;i<120;i++){ const n=await evalJs(`document.querySelector('.svg-container svg')?.querySelectorAll('*').length||0`).catch(()=>0); if(n>5000)break; await sleep(1000); }
+}
+log('N nodes:', await evalJs(`document.querySelector('.svg-container svg')?.querySelectorAll('*').length||0`));
+await sleep(800);
+
+// fps per mode on the N tab.
+const out = {};
+for (const mode of ['off', 'gpu', 'bitmap']) {
+  const ls = await evalJs(`window.__setMode('${mode}')`, true);
+  await sleep(400);
+  // mousedown→first-frame latency (a sync serialize freeze would spike this).
+  const firstFrameMs = await evalJs(`window.__downToFirstFrame()`, true);
+  await sleep(300);
+  // prime gesture (warms the bitmap serialisation cache on idle), then pause so
+  // the idle prewarm completes, then measure the steady state.
+  await evalJs(`window.__dragPan(1500)`, true);
+  await sleep(2500);
+  const pan = await evalJs(`window.__dragPan(2500)`, true);
+  const canvasMounted = await evalJs(`window.__canvasMounted()`);
+  out[mode] = { ls, firstFrameMs, canvasMounted, pan };
+  log(mode, 'ls=' + ls, 'firstFrameMs=' + firstFrameMs, 'canvas=' + canvasMounted, JSON.stringify(pan));
+}
+console.log(JSON.stringify(out));
+process.exit(0);

benchmarks/interaction_paint/app_bitmap_n1_driver.mjs

@@ -0,0 +1,56 @@
+// On the N-1 (Contingency) tab in BITMAP mode, capture a MID-gesture screenshot
+// (live SVG hidden, canvas bitmap showing) and a static one, to confirm the
+// overload/contingency halos + flow-delta colours survive in the rasterised
+// bitmap — the N-1/action fidelity prerequisite (App.css class paint inlined).
+import { writeFileSync } from 'fs';
+const PORT = 9444;
+const BRANCH = process.env.BRANCH || 'T_relation_13260100-400-225';
+const sleep = (ms) => new Promise(r => setTimeout(r, ms));
+async function findTarget(){for(let i=0;i<40;i++){const l=await (await fetch(`http://127.0.0.1:${PORT}/json/list`)).json();const t=l.find(x=>x.type==='page'&&/localhost:5173/.test(x.url));if(t&&t.webSocketDebuggerUrl)return t;await sleep(250);}throw new Error('no app target');}
+function connect(wsUrl){return new Promise(res=>{const ws=new WebSocket(wsUrl);let id=0;const p=new Map();
+  ws.addEventListener('message',ev=>{const m=JSON.parse(ev.data);if(m.id&&p.has(m.id)){const{r,j}=p.get(m.id);p.delete(m.id);m.error?j(new Error(JSON.stringify(m.error))):r(m.result);}});
+  ws.addEventListener('open',()=>{const send=(method,params={})=>new Promise((r,j)=>{const mid=++id;p.set(mid,{r,j});ws.send(JSON.stringify({id:mid,method,params}));});
+    const evalJs=async(e,a=false)=>{const r=await send('Runtime.evaluate',{expression:e,returnByValue:true,awaitPromise:a});if(r.exceptionDetails)throw new Error('eval:'+JSON.stringify(r.exceptionDetails).slice(0,400));return r.result.value;};res({send,evalJs});});});}
+const { send, evalJs } = await connect((await findTarget()).webSocketDebuggerUrl);
+await send('Runtime.enable'); await send('Page.enable');
+const log=(...a)=>console.error(...a);
+const shot = async (path) => { const { data } = await send('Page.captureScreenshot', { format: 'jpeg', quality: 82 }); writeFileSync(path, Buffer.from(data, 'base64')); log('saved', path); };
+
+await evalJs(`
+window.__btn=(txt)=>{const b=[...document.querySelectorAll('button')].find(b=>b.textContent.trim()===txt);if(b){b.click();return true;}return false;};
+window.__setMode=async(mode)=>{window.__btn('⚙');await new Promise(r=>setTimeout(r,400));window.__btn('Configurations');await new Promise(r=>setTimeout(r,300));const sel=document.querySelector('[data-testid=pan-zoom-mode-select]');if(sel){const s=Object.getOwnPropertyDescriptor(window.HTMLSelectElement.prototype,'value').set;s.call(sel,mode);sel.dispatchEvent(new Event('change',{bubbles:true}));}const ls=localStorage.getItem('cs4g-smooth-pan-zoom');if(!window.__btn('✕')){const fb=[...document.querySelectorAll('button')].find(b=>/cancel|close/i.test(b.textContent));if(fb)fb.click();}await new Promise(r=>setTimeout(r,300));return ls;};
+// hold a drag for durationMs (mousedown + rAF mousemoves + mouseup); exposes state.
+window.__holdDrag=(d)=>{const c=[...document.querySelectorAll('.svg-container')].find(e=>e.offsetParent!==null&&e.querySelector('svg'));if(!c){window.__drag={error:'no-container'};return;}const r=c.getBoundingClientRect(),cx=r.left+r.width/2,cy=r.top+r.height/2;c.dispatchEvent(new MouseEvent('mousedown',{bubbles:true,clientX:cx,clientY:cy,button:0}));window.__dragDone=false;const t0=performance.now();function f(now){const e=now-t0;const dx=Math.sin(e/400)*180;window.dispatchEvent(new MouseEvent('mousemove',{bubbles:true,clientX:cx+dx,clientY:cy,button:0}));if(e<d)requestAnimationFrame(f);else{window.dispatchEvent(new MouseEvent('mouseup',{bubbles:true,clientX:cx+dx,clientY:cy,button:0}));window.__dragDone=true;}}requestAnimationFrame(f);};
+'ok';`);
+
+log('mode:', await evalJs(`window.__setMode('bitmap')`, true));
+
+// Select contingency + trigger (react-select then Trigger button).
+await evalJs(`(()=>{const inp=document.querySelector('#react-select-3-input');if(!inp)return;inp.focus();const s=Object.getOwnPropertyDescriptor(window.HTMLInputElement.prototype,'value').set;s.call(inp,${JSON.stringify(BRANCH)});inp.dispatchEvent(new Event('input',{bubbles:true}));})()`);
+await sleep(1300);
+await evalJs(`(()=>{const o=document.querySelector('[class*=cs4g-contingency__option]');if(o){o.dispatchEvent(new MouseEvent('mousedown',{bubbles:true}));o.click();}})()`);
+await sleep(600);
+await evalJs(`(()=>{const b=[...document.querySelectorAll('button')].find(b=>/trigger/i.test(b.textContent));if(b)b.click();})()`);
+await sleep(5000);
+await evalJs(`window.__btn('Contingency')`);
+let st=null;
+for(let i=0;i<60;i++){st=await evalJs(`(()=>{const c=[...document.querySelectorAll('.svg-container')].find(e=>e.offsetParent!==null&&e.querySelector('svg'));return c?{nodes:c.querySelector('svg').querySelectorAll('*').length,halos:c.querySelectorAll('.nad-contingency-highlight,.nad-overloaded,.nad-delta-positive,.nad-delta-negative').length}:null;})()`).catch(()=>null);if(st&&st.nodes>5000)break;await sleep(1000);}
+log('N-1 visible svg:', JSON.stringify(st));
+await sleep(800);
+
+// Zoom into the contingency area so halos are visible, then static screenshot.
+await evalJs(`(()=>{const svg=document.querySelector('.svg-container svg');const hl=svg.querySelector('.nad-contingency-highlight, .nad-delta-positive');const v=svg.getAttribute('viewBox').split(/\\s+/).map(Number);let cx=v[0]+v[2]/2, cy=v[1]+v[3]/2;if(hl){try{const b=hl.getBBox();cx=b.x+b.width/2;cy=b.y+b.height/2;}catch{}}const W=v[2]*0.05,H=W*0.66;svg.setAttribute('viewBox',(cx-W/2)+' '+(cy-H/2)+' '+W+' '+H);const c=svg.closest('.svg-container');if(c)c.setAttribute('data-zoom-tier','detail');})()`);
+await sleep(800);
+await shot('/tmp/cs4g_bitmap_n1_static.jpg');
+
+// Start a held drag; mid-gesture (canvas mounted) capture, then let it finish.
+await evalJs(`window.__holdDrag(3000)`);
+await sleep(1500); // raster + mount window
+const midState = await evalJs(`(()=>{const c=document.querySelector('.svg-container canvas');const svg=document.querySelector('.svg-container svg');return {canvasMounted:!!c, svgHidden: svg? getComputedStyle(svg).visibility==='hidden':null};})()`);
+log('mid-gesture:', JSON.stringify(midState));
+await shot('/tmp/cs4g_bitmap_n1_mid.jpg');
+// wait for the drag to finish + settle
+for(let i=0;i<30;i++){ if(await evalJs(`window.__dragDone===true`)) break; await sleep(200); }
+await sleep(500);
+console.log(JSON.stringify({ n1: st, midState }));
+process.exit(0);

benchmarks/interaction_paint/app_gesture_driver.mjs

@@ -0,0 +1,126 @@
+// Drive the REAL Co-Study4Grid app (localhost:5173) end-to-end on the
+// isolated port-9444 Chrome: open Settings, point at pypsa_eur_eur220_225_380_400,
+// Apply, wait for the N NAD, then measure a REAL drag-pan + wheel-zoom gesture
+// through the app's own usePanZoom handlers, with the GPU toggle OFF then ON.
+const PORT = 9444;
+const sleep = (ms) => new Promise(r => setTimeout(r, ms));
+
+async function findTarget() {
+  for (let i = 0; i < 40; i++) {
+    const list = await (await fetch(`http://127.0.0.1:${PORT}/json/list`)).json();
+    const t = list.find(x => x.type === 'page' && /^https?:/.test(x.url));
+    if (t && t.webSocketDebuggerUrl) return t;
+    await sleep(250);
+  }
+  throw new Error('no page target');
+}
+function connect(wsUrl) {
+  return new Promise((resolve) => {
+    const ws = new WebSocket(wsUrl); let id = 0; const pending = new Map();
+    ws.addEventListener('message', (ev) => { const m = JSON.parse(ev.data); if (m.id && pending.has(m.id)) { const { r, j } = pending.get(m.id); pending.delete(m.id); m.error ? j(new Error(JSON.stringify(m.error))) : r(m.result); } });
+    ws.addEventListener('open', () => {
+      const send = (method, params = {}) => new Promise((r, j) => { const mid = ++id; pending.set(mid, { r, j }); ws.send(JSON.stringify({ id: mid, method, params })); });
+      const evalJs = async (expr, awaitPromise = false) => { const res = await send('Runtime.evaluate', { expression: expr, returnByValue: true, awaitPromise }); if (res.exceptionDetails) throw new Error('eval: ' + JSON.stringify(res.exceptionDetails).slice(0, 300)); return res.result.value; };
+      resolve({ send, evalJs });
+    });
+  });
+}
+
+const { send, evalJs } = await connect((await findTarget()).webSocketDebuggerUrl);
+await send('Runtime.enable');
+const log = (...a) => console.error(...a);
+
+// Helper expressions injected into the page.
+const HELPERS = `
+window.__setInput = (sel, val) => {
+  const el = document.querySelector(sel); if (!el) return 'no-el:' + sel;
+  const setter = Object.getOwnPropertyDescriptor(window.HTMLInputElement.prototype, 'value').set;
+  setter.call(el, val);
+  el.dispatchEvent(new Event('input', { bubbles: true }));
+  return el.value;
+};
+window.__btn = (txt) => { const b = [...document.querySelectorAll('button')].find(b => b.textContent.trim() === txt); if (b) { b.click(); return true; } return false; };
+window.__summarize = (a) => { if(!a.length) return null; const s=a.slice().sort((x,y)=>x-y); const n=s.length, mean=a.reduce((p,v)=>p+v,0)/n; const pct=p=>s[Math.min(n-1,Math.floor(p*n))]; const drop=a.filter(d=>d>14).length; return {frames:n, mean:+mean.toFixed(2), median:+pct(0.5).toFixed(2), p95:+pct(0.95).toFixed(2), max:+s[n-1].toFixed(2), fps_median:+(1000/pct(0.5)).toFixed(1), dropPct:+(100*drop/n).toFixed(1)}; };
+// Real drag-pan through the app's usePanZoom (mousedown on container, mousemove on window).
+window.__dragPan = (durationMs) => new Promise(resolve => {
+  const c = [...document.querySelectorAll('.svg-container')].find(e => e.offsetParent !== null && e.querySelector('svg'));
+  if (!c) return resolve({error:'no visible svg-container'});
+  const r = c.getBoundingClientRect();
+  const cx = r.left + r.width/2, cy = r.top + r.height/2;
+  const md = new MouseEvent('mousedown', {bubbles:true, clientX:cx, clientY:cy, button:0});
+  c.dispatchEvent(md);
+  const intervals=[]; let last=performance.now(); const t0=last;
+  function frame(now){
+    intervals.push(now-last); last=now;
+    const e=now-t0; const t=(e/durationMs); const dx=Math.sin(t*Math.PI*4)*250;
+    window.dispatchEvent(new MouseEvent('mousemove',{bubbles:true, clientX:cx+dx, clientY:cy, button:0}));
+    if(e<durationMs) requestAnimationFrame(frame);
+    else { window.dispatchEvent(new MouseEvent('mouseup',{bubbles:true, clientX:cx+dx, clientY:cy, button:0})); intervals.shift(); resolve(window.__summarize(intervals)); }
+  }
+  requestAnimationFrame(frame);
+});
+// Real wheel-zoom through usePanZoom (wheel on container, alternating in/out).
+window.__wheelZoom = (durationMs) => new Promise(resolve => {
+  const c = [...document.querySelectorAll('.svg-container')].find(e => e.offsetParent !== null && e.querySelector('svg'));
+  if (!c) return resolve({error:'no visible svg-container'});
+  const r = c.getBoundingClientRect(); const cx=r.left+r.width/2, cy=r.top+r.height/2;
+  const intervals=[]; let last=performance.now(); const t0=last;
+  function frame(now){
+    intervals.push(now-last); last=now;
+    const e=now-t0;
+    const dir = Math.sin(e/250) > 0 ? -1 : 1; // zoom in/out
+    c.dispatchEvent(new WheelEvent('wheel',{bubbles:true, cancelable:true, clientX:cx, clientY:cy, deltaY: dir*100}));
+    if(e<durationMs) requestAnimationFrame(frame);
+    else { intervals.shift(); resolve(window.__summarize(intervals)); }
+  }
+  requestAnimationFrame(frame);
+});
+'ok';`;
+await evalJs(HELPERS);
+
+// 1. Open Settings if not open.
+let settingsOpen = await evalJs(`!!document.querySelector('#networkPathInput')`);
+if (!settingsOpen) { await evalJs(`window.__btn('��')`); await sleep(600); }
+log('settings open:', await evalJs(`!!document.querySelector('#networkPathInput')`));
+
+// 2. Set paths.
+log('net:', await evalJs(`window.__setInput('#networkPathInput','data/pypsa_eur_eur220_225_380_400/network.xiidm')`));
+log('act:', await evalJs(`window.__setInput('#actionPathInput','data/pypsa_eur_eur220_225_380_400/actions.json')`));
+// layout input: 3rd path input (no id). Set by locating label "Layout".
+await evalJs(`(()=>{const labs=[...document.querySelectorAll('label')];const l=labs.find(x=>/layout/i.test(x.textContent));if(l){const inp=l.parentElement.querySelector('input[type=text]')||l.closest('div').querySelector('input[type=text]');if(inp){const s=Object.getOwnPropertyDescriptor(window.HTMLInputElement.prototype,'value').set;s.call(inp,'data/pypsa_eur_eur220_225_380_400/grid_layout.json');inp.dispatchEvent(new Event('input',{bubbles:true}));return inp.value;}}return 'no-layout-input';})()`).then(v=>log('layout:',v));
+
+// 3. Ensure GPU toggle is OFF for the first run.
+await evalJs(`(()=>{const t=document.querySelector('[data-testid=smooth-pan-zoom-toggle]');if(t&&t.checked){t.click();} return t?('checked='+document.querySelector('[data-testid=smooth-pan-zoom-toggle]').checked):'no-toggle';})()`).then(v=>log('toggle pre:',v));
+
+// 4. Apply.
+await evalJs(`window.__btn('Apply')`); log('clicked Apply');
+
+// 5. Wait for the N NAD to mount with many nodes.
+let mounted = 0;
+for (let i = 0; i < 120; i++) { mounted = await evalJs(`(()=>{const s=document.querySelector('.svg-container svg');return s?s.querySelectorAll('*').length:0;})()`).catch(()=>0); if (mounted > 5000) break; await sleep(1000); }
+log('NAD nodes mounted:', mounted, 'tab:', await evalJs(`document.querySelector('.svg-container svg')?.getAttribute('viewBox')?.slice(0,30)`));
+if (mounted < 5000) { console.log(JSON.stringify({error:'NAD did not mount', mounted})); process.exit(1); }
+await sleep(800);
+
+// 6. Measure OFF.
+const off_pan = await evalJs(`window.__dragPan(2500)`, true);
+await sleep(300);
+const off_zoom = await evalJs(`window.__wheelZoom(2500)`, true);
+log('OFF pan', JSON.stringify(off_pan), 'zoom', JSON.stringify(off_zoom));
+
+// 7. Flip GPU toggle ON via Settings (open, click toggle, close WITHOUT Apply).
+await evalJs(`window.__btn('⚙')`); await sleep(500);
+const onState = await evalJs(`(()=>{const t=document.querySelector('[data-testid=smooth-pan-zoom-toggle]');if(t&&!t.checked){t.click();} return document.querySelector('[data-testid=smooth-pan-zoom-toggle]')?.checked;})()`);
+log('toggle now ON:', onState, 'localStorage:', await evalJs(`localStorage.getItem('cs4g-smooth-pan-zoom')`));
+// Close settings without Apply: click ✕ or Cancel.
+await evalJs(`(()=>{if(!window.__btn('✕')){const fb=[...document.querySelectorAll('button')].find(b=>/cancel|close|annul/i.test(b.textContent));if(fb)fb.click();}})()`); await sleep(500);
+log('settings closed:', !(await evalJs(`!!document.querySelector('#networkPathInput')`)));
+
+// 8. Measure ON.
+const on_pan = await evalJs(`window.__dragPan(2500)`, true);
+await sleep(300);
+const on_zoom = await evalJs(`window.__wheelZoom(2500)`, true);
+log('ON pan', JSON.stringify(on_pan), 'zoom', JSON.stringify(on_zoom));
+
+console.log(JSON.stringify({ off:{pan:off_pan,zoom:off_zoom}, on:{pan:on_pan,zoom:on_zoom} }));
+process.exit(0);

benchmarks/interaction_paint/app_measure_snapshot.mjs

@@ -0,0 +1,41 @@
+// Measure where the bitmap-mode snapshot cost goes (clone / serialize / decode
+// / draw) on the live N NAD — to size the gesture-start blocking problem.
+const PORT = 9444; const sleep = (ms) => new Promise(r => setTimeout(r, ms));
+async function findTarget(){for(let i=0;i<40;i++){const l=await (await fetch(`http://127.0.0.1:${PORT}/json/list`)).json();const t=l.find(x=>x.type==='page'&&/localhost:5173/.test(x.url));if(t&&t.webSocketDebuggerUrl)return t;await sleep(250);}throw new Error('no app target');}
+function connect(wsUrl){return new Promise(res=>{const ws=new WebSocket(wsUrl);let id=0;const p=new Map();ws.addEventListener('message',ev=>{const m=JSON.parse(ev.data);if(m.id&&p.has(m.id)){const{r,j}=p.get(m.id);p.delete(m.id);m.error?j(new Error(JSON.stringify(m.error))):r(m.result);}});ws.addEventListener('open',()=>{const send=(method,params={})=>new Promise((r,j)=>{const mid=++id;p.set(mid,{r,j});ws.send(JSON.stringify({id:mid,method,params}));});const evalJs=async(e,a=false)=>{const r=await send('Runtime.evaluate',{expression:e,returnByValue:true,awaitPromise:a});if(r.exceptionDetails)throw new Error('eval:'+JSON.stringify(r.exceptionDetails).slice(0,300));return r.result.value;};res({send,evalJs});});});}
+const { evalJs, send } = await connect((await findTarget()).webSocketDebuggerUrl);
+await send('Runtime.enable');
+const log=(...a)=>console.error(...a);
+await evalJs(`window.__setInput=(s,v)=>{const el=document.querySelector(s);if(!el)return;const x=Object.getOwnPropertyDescriptor(window.HTMLInputElement.prototype,'value').set;x.call(el,v);el.dispatchEvent(new Event('input',{bubbles:true}));};window.__btn=(t)=>{const b=[...document.querySelectorAll('button')].find(b=>b.textContent.trim()===t);if(b){b.click();return true;}return false;};'ok';`);
+const mounted0 = await evalJs(`document.querySelector('.svg-container svg')?.querySelectorAll('*').length||0`);
+if (mounted0 < 5000) {
+  if (!(await evalJs(`!!document.querySelector('#networkPathInput')`))) { await evalJs(`window.__btn('⚙')`); await sleep(600); }
+  await evalJs(`window.__setInput('#networkPathInput','data/pypsa_eur_eur220_225_380_400/network.xiidm')`);
+  await evalJs(`window.__setInput('#actionPathInput','data/pypsa_eur_eur220_225_380_400/actions.json')`);
+  await evalJs(`(()=>{const l=[...document.querySelectorAll('label')].find(x=>/layout/i.test(x.textContent));const inp=l&&(l.parentElement.querySelector('input[type=text]')||l.closest('div').querySelector('input[type=text]'));if(inp){const s=Object.getOwnPropertyDescriptor(window.HTMLInputElement.prototype,'value').set;s.call(inp,'data/pypsa_eur_eur220_225_380_400/grid_layout.json');inp.dispatchEvent(new Event('input',{bubbles:true}));}})()`);
+  await evalJs(`window.__btn('Apply')`); log('loading…');
+  for (let i=0;i<120;i++){ const n=await evalJs(`document.querySelector('.svg-container svg')?.querySelectorAll('*').length||0`).catch(()=>0); if(n>5000)break; await sleep(1000); }
+}
+await sleep(800);
+const m = await evalJs(`(async()=>{
+  const svg=document.querySelector('.svg-container svg');
+  const W=svg.clientWidth, H=svg.clientHeight, dpr=window.devicePixelRatio||1;
+  const t0=performance.now();
+  const clone=svg.cloneNode(true);
+  const t1=performance.now();
+  clone.querySelectorAll('foreignObject').forEach(n=>n.remove());
+  clone.setAttribute('width',W); clone.setAttribute('height',H);
+  const xml=new XMLSerializer().serializeToString(clone);
+  const t2=performance.now();
+  const url=URL.createObjectURL(new Blob([xml],{type:'image/svg+xml;charset=utf-8'}));
+  const img=new Image(); img.width=W; img.height=H;
+  const t3=performance.now();
+  try{ await new Promise((res,rej)=>{img.onload=res;img.onerror=()=>rej(new Error('decode fail'));img.src=url;}); }catch(e){ return {error:String(e)}; }
+  const t4=performance.now();
+  const cv=document.createElement('canvas'); cv.width=Math.round(W*dpr); cv.height=Math.round(H*dpr); const ctx=cv.getContext('2d'); ctx.setTransform(dpr,0,0,dpr,0,0); ctx.drawImage(img,0,0,W,H);
+  const t5=performance.now();
+  URL.revokeObjectURL(url);
+  return {W,H,dpr, cloneMs:+(t1-t0).toFixed(0), stripSerializeMs:+(t2-t1).toFixed(0), decodeMs:+(t4-t3).toFixed(0), drawMs:+(t5-t4).toFixed(0), syncBlockMs:+(t2-t0).toFixed(0), totalMs:+(t5-t0).toFixed(0), xmlMB:+(xml.length/1e6).toFixed(1)};
+})()`, true);
+console.log(JSON.stringify(m));
+process.exit(0);

benchmarks/interaction_paint/app_n1_driver.mjs

@@ -0,0 +1,51 @@
+// Select a contingency via the react-select picker, switch to the Contingency
+// tab, and measure real pan/zoom OFF vs ON on the N-1 diagram.
+const PORT = 9444;
+const BRANCH = process.env.BRANCH || 'T_relation_13260100-400-225';
+const sleep = (ms) => new Promise(r => setTimeout(r, ms));
+async function findTarget(){for(let i=0;i<40;i++){const l=await (await fetch(`http://127.0.0.1:${PORT}/json/list`)).json();const t=l.find(x=>x.type==='page'&&/localhost:5173/.test(x.url));if(t&&t.webSocketDebuggerUrl)return t;await sleep(250);}throw new Error('no app target');}
+function connect(wsUrl){return new Promise(res=>{const ws=new WebSocket(wsUrl);let id=0;const p=new Map();ws.addEventListener('message',ev=>{const m=JSON.parse(ev.data);if(m.id&&p.has(m.id)){const{r,j}=p.get(m.id);p.delete(m.id);m.error?j(new Error(JSON.stringify(m.error))):r(m.result);}});ws.addEventListener('open',()=>{const send=(method,params={})=>new Promise((r,j)=>{const mid=++id;p.set(mid,{r,j});ws.send(JSON.stringify({id:mid,method,params}));});const evalJs=async(e,a=false)=>{const r=await send('Runtime.evaluate',{expression:e,returnByValue:true,awaitPromise:a});if(r.exceptionDetails)throw new Error('eval:'+JSON.stringify(r.exceptionDetails).slice(0,300));return r.result.value;};res({send,evalJs});});});}
+const { send, evalJs } = await connect((await findTarget()).webSocketDebuggerUrl);
+await send('Runtime.enable');
+const log=(...a)=>console.error(...a);
+
+const HELPERS=`
+window.__btn=(txt)=>{const b=[...document.querySelectorAll('button')].find(b=>b.textContent.trim()===txt);if(b){b.click();return true;}return false;};
+window.__summarize=(a)=>{if(!a.length)return null;const s=a.slice().sort((x,y)=>x-y);const n=s.length,mean=a.reduce((p,v)=>p+v,0)/n;const pct=p=>s[Math.min(n-1,Math.floor(p*n))];const drop=a.filter(d=>d>14).length;return{frames:n,mean:+mean.toFixed(2),median:+pct(0.5).toFixed(2),p95:+pct(0.95).toFixed(2),max:+s[n-1].toFixed(2),fps_median:+(1000/pct(0.5)).toFixed(1),dropPct:+(100*drop/n).toFixed(1)};};
+window.__visSvg=()=>{const c=[...document.querySelectorAll('.svg-container')].find(e=>e.offsetParent!==null&&e.querySelector('svg'));return c?{nodes:c.querySelector('svg').querySelectorAll('*').length, halos:c.querySelectorAll('.nad-overloaded,.nad-contingency-highlight,.nad-delta-positive,.nad-delta-negative').length}:null;};
+window.__dragPan=(d)=>new Promise(resolve=>{const c=[...document.querySelectorAll('.svg-container')].find(e=>e.offsetParent!==null&&e.querySelector('svg'));if(!c)return resolve({error:'no-container'});const r=c.getBoundingClientRect(),cx=r.left+r.width/2,cy=r.top+r.height/2;c.dispatchEvent(new MouseEvent('mousedown',{bubbles:true,clientX:cx,clientY:cy,button:0}));const iv=[];let last=performance.now();const t0=last;function f(now){iv.push(now-last);last=now;const e=now-t0,t=e/d,dx=Math.sin(t*Math.PI*4)*250;window.dispatchEvent(new MouseEvent('mousemove',{bubbles:true,clientX:cx+dx,clientY:cy,button:0}));if(e<d)requestAnimationFrame(f);else{window.dispatchEvent(new MouseEvent('mouseup',{bubbles:true,clientX:cx+dx,clientY:cy,button:0}));iv.shift();resolve(window.__summarize(iv));}}requestAnimationFrame(f);});
+window.__wheelZoom=(d)=>new Promise(resolve=>{const c=[...document.querySelectorAll('.svg-container')].find(e=>e.offsetParent!==null&&e.querySelector('svg'));if(!c)return resolve({error:'no-container'});const r=c.getBoundingClientRect(),cx=r.left+r.width/2,cy=r.top+r.height/2;const iv=[];let last=performance.now();const t0=last;function f(now){iv.push(now-last);last=now;const e=now-t0;const dir=Math.sin(e/250)>0?-1:1;c.dispatchEvent(new WheelEvent('wheel',{bubbles:true,cancelable:true,clientX:cx,clientY:cy,deltaY:dir*100}));if(e<d)requestAnimationFrame(f);else{iv.shift();resolve(window.__summarize(iv));}}requestAnimationFrame(f);});
+window.__setToggle=async(desired)=>{window.__btn('⚙');await new Promise(r=>setTimeout(r,400));window.__btn('Configurations');await new Promise(r=>setTimeout(r,300));const t=document.querySelector('[data-testid=smooth-pan-zoom-toggle]');if(!t)return'NO-TOGGLE';if(t.checked!==desired)t.click();const st={checked:document.querySelector('[data-testid=smooth-pan-zoom-toggle]').checked,ls:localStorage.getItem('cs4g-smooth-pan-zoom')};if(!window.__btn('✕')){const fb=[...document.querySelectorAll('button')].find(b=>/cancel|close/i.test(b.textContent));if(fb)fb.click();}await new Promise(r=>setTimeout(r,400));return st;};
+window.__pickContingency=(branch)=>{const inp=document.querySelector('#react-select-3-input');if(!inp)return'no-input';inp.focus();const s=Object.getOwnPropertyDescriptor(window.HTMLInputElement.prototype,'value').set;s.call(inp,branch);inp.dispatchEvent(new Event('input',{bubbles:true}));return 'typed';};
+window.__enter=()=>{const inp=document.querySelector('#react-select-3-input');if(!inp)return'no-input';['keydown','keypress','keyup'].forEach(t=>inp.dispatchEvent(new KeyboardEvent(t,{key:'Enter',code:'Enter',keyCode:13,which:13,bubbles:true})));return 'enter';};
+'ok';`;
+await evalJs(HELPERS);
+
+// Select contingency.
+log('pick:', await evalJs(`window.__pickContingency(${JSON.stringify(BRANCH)})`));
+await sleep(1200);
+// dump menu options count to confirm filtering worked
+log('menu opts:', await evalJs(`document.querySelectorAll('[class*=cs4g-contingency__option]').length`));
+log('enter:', await evalJs(`window.__enter()`));
+await sleep(1000);
+// Confirm dialog? click confirm if present.
+await evalJs(`(()=>{const b=[...document.querySelectorAll('button')].find(b=>/confirm|oui|yes|proceed|continuer/i.test(b.textContent));if(b){b.click();return 'confirmed';}return 'no-confirm';})()`).then(v=>log('confirm:',v));
+// Switch to Contingency tab.
+await sleep(500); await evalJs(`window.__btn('Contingency')`);
+// Poll for the N-1 diagram to render.
+let st=null;
+for(let i=0;i<90;i++){ st=await evalJs(`window.__visSvg()`).catch(()=>null); if(st&&st.nodes>5000) break; await sleep(1000); }
+log('N-1 svg:', JSON.stringify(st));
+if(!st||st.nodes<5000){console.log(JSON.stringify({error:'no N-1 diagram',st}));process.exit(1);}
+await sleep(800);
+
+const out={contingency:BRANCH, svg:st};
+for(const mode of ['off','on']){
+  const t=await evalJs(`window.__setToggle(${mode==='on'})`,true); log(mode,'toggle',JSON.stringify(t));
+  await sleep(400); await evalJs(`window.__btn('Contingency')`); await sleep(300);
+  const pan=await evalJs(`window.__dragPan(2500)`,true); await sleep(300);
+  const zoom=await evalJs(`window.__wheelZoom(2500)`,true);
+  out[mode]={pan,zoom}; log(mode,'pan',JSON.stringify(pan),'zoom',JSON.stringify(zoom));
+}
+console.log(JSON.stringify(out));
+process.exit(0);

benchmarks/interaction_paint/app_render_driver.mjs

@@ -0,0 +1,75 @@
+// Configure the app, load N, capture the de-clutter log, auto-zoom to the
+// densest substation cluster, and screenshot it (visual check of flow labels).
+import { writeFileSync } from 'fs';
+const PORT = 9444;
+const OUT = process.env.OUT || '/tmp/cs4g_flowlabels.jpg';
+const sleep = (ms) => new Promise(r => setTimeout(r, ms));
+async function findTarget(){for(let i=0;i<40;i++){const l=await (await fetch(`http://127.0.0.1:${PORT}/json/list`)).json();const t=l.find(x=>x.type==='page'&&/localhost:5173/.test(x.url));if(t&&t.webSocketDebuggerUrl)return t;await sleep(250);}throw new Error('no app target');}
+function connect(wsUrl){return new Promise(res=>{const ws=new WebSocket(wsUrl);let id=0;const p=new Map();const logs=[];
+  ws.addEventListener('message',ev=>{const m=JSON.parse(ev.data);
+    if(m.method==='Runtime.consoleAPICalled'){try{logs.push(m.params.args.map(a=>a.value??a.description??'').join(' '));}catch{}}
+    if(m.id&&p.has(m.id)){const{r,j}=p.get(m.id);p.delete(m.id);m.error?j(new Error(JSON.stringify(m.error))):r(m.result);}});
+  ws.addEventListener('open',()=>{const send=(method,params={})=>new Promise((r,j)=>{const mid=++id;p.set(mid,{r,j});ws.send(JSON.stringify({id:mid,method,params}));});
+    const evalJs=async(e,a=false)=>{const r=await send('Runtime.evaluate',{expression:e,returnByValue:true,awaitPromise:a});if(r.exceptionDetails)throw new Error('eval:'+JSON.stringify(r.exceptionDetails).slice(0,300));return r.result.value;};
+    res({send,evalJs,logs});});});}
+const { send, evalJs, logs } = await connect((await findTarget()).webSocketDebuggerUrl);
+await send('Runtime.enable'); await send('Page.enable');
+const log=(...a)=>console.error(...a);
+
+await evalJs(`
+window.__setInput=(sel,val)=>{const el=document.querySelector(sel);if(!el)return 'no:'+sel;const s=Object.getOwnPropertyDescriptor(window.HTMLInputElement.prototype,'value').set;s.call(el,val);el.dispatchEvent(new Event('input',{bubbles:true}));return el.value;};
+window.__btn=(txt)=>{const b=[...document.querySelectorAll('button')].find(b=>b.textContent.trim()===txt);if(b){b.click();return true;}return false;};
+'ok';`);
+
+// Configure if a fresh NAD is needed.
+const mounted0 = await evalJs(`document.querySelector('.svg-container svg')?.querySelectorAll('*').length||0`);
+if (mounted0 < 5000) {
+  if (!(await evalJs(`!!document.querySelector('#networkPathInput')`))) { await evalJs(`window.__btn('⚙')`); await sleep(600); }
+  await evalJs(`window.__setInput('#networkPathInput','data/pypsa_eur_eur220_225_380_400/network.xiidm')`);
+  await evalJs(`window.__setInput('#actionPathInput','data/pypsa_eur_eur220_225_380_400/actions.json')`);
+  await evalJs(`(()=>{const l=[...document.querySelectorAll('label')].find(x=>/layout/i.test(x.textContent));const inp=l&&(l.parentElement.querySelector('input[type=text]')||l.closest('div').querySelector('input[type=text]'));if(inp){const s=Object.getOwnPropertyDescriptor(window.HTMLInputElement.prototype,'value').set;s.call(inp,'data/pypsa_eur_eur220_225_380_400/grid_layout.json');inp.dispatchEvent(new Event('input',{bubbles:true}));}})()`);
+  await evalJs(`window.__btn('Apply')`); log('applied; loading NAD…');
+  for (let i=0;i<120;i++){ const n=await evalJs(`document.querySelector('.svg-container svg')?.querySelectorAll('*').length||0`).catch(()=>0); if(n>5000)break; await sleep(1000); }
+}
+const nodes = await evalJs(`document.querySelector('.svg-container svg')?.querySelectorAll('*').length||0`);
+log('NAD nodes:', nodes);
+await sleep(1000);
+log('declutter log:', logs.filter(l=>/De-cluttered|Boosted|declutter pass/.test(l)).slice(-3).join(' || ') || '(none captured)');
+
+// Optionally hide VL-name labels (🏷 VL) to isolate the flow values.
+if (process.env.HIDE_VL === '1') { await evalJs(`window.__btn('🏷 VL')`).catch(()=>{}); await sleep(400);
+  await evalJs(`(()=>{const c=document.querySelector('.svg-container');if(c)c.classList.add('nad-hide-vl-labels');})()`); await sleep(300); }
+
+const FORCED_VB = process.env.VB || '';
+// Find the densest substation cluster and zoom the SVG viewBox onto it.
+const vb = await evalJs(`(()=>{
+  const FORCED=${JSON.stringify(FORCED_VB)};
+  const svg=document.querySelector('.svg-container svg');
+  const circles=[...svg.querySelectorAll('.nad-vl-nodes g[transform]')];
+  const pts=[];
+  for(const g of circles){const m=/translate\\(\\s*([-0-9.eE+]+)\\s*[, ]\\s*([-0-9.eE+]+)/.exec(g.getAttribute('transform')||'');if(m)pts.push([+m[1],+m[2]]);}
+  if(!pts.length) return null;
+  // grid density
+  let minx=1e18,miny=1e18,maxx=-1e18,maxy=-1e18;
+  for(const[x,y]of pts){if(x<minx)minx=x;if(x>maxx)maxx=x;if(y<miny)miny=y;if(y>maxy)maxy=y;}
+  const span=Math.max(maxx-minx,maxy-miny);
+  const cell=span/120;
+  const grid=new Map();let best=null;
+  for(const[x,y]of pts){const k=Math.floor(x/cell)+','+Math.floor(y/cell);const c=(grid.get(k)||0)+1;grid.set(k,c);if(!best||c>best.c){best={k,c,x,y};}}
+  // Tight window (~2.2% of full width) over the densest cell so individual
+  // flow values render. Force the detail zoom-tier on the container (we set
+  // the viewBox directly, bypassing usePanZoom which normally maintains it).
+  let nvb;
+  if(FORCED){const p=FORCED.split(/\\s+/).map(Number);nvb={x:p[0],y:p[1],w:p[2],h:p[3]};}
+  else{const W=(maxx-minx)*0.022, H=W*0.66;nvb={x:best.x-W/2,y:best.y-H/2,w:W,h:H};}
+  svg.setAttribute('viewBox',\`\${nvb.x} \${nvb.y} \${nvb.w} \${nvb.h}\`);
+  const cont=svg.closest('.svg-container'); if(cont){cont.setAttribute('data-zoom-tier','detail');cont.classList.remove('svg-interacting');}
+  return {densest:best.c, vb:nvb};
+})()`);
+log('zoomed to densest cluster:', JSON.stringify(vb));
+await sleep(1200);
+
+const { data } = await send('Page.captureScreenshot', { format: 'jpeg', quality: 80 });
+writeFileSync(OUT, Buffer.from(data, 'base64'));
+log('saved', OUT);
+process.exit(0);

benchmarks/interaction_paint/app_toggle_driver.mjs

@@ -0,0 +1,48 @@
+// Assumes the N NAD is already loaded in the app. For each mode (off/on),
+// set the real "Smooth pan/zoom (GPU)" toggle via Settings -> Configurations,
+// then measure a real drag-pan + wheel-zoom through usePanZoom.
+const PORT = 9444;
+const sleep = (ms) => new Promise(r => setTimeout(r, ms));
+async function findTarget() { for (let i=0;i<40;i++){const l=await (await fetch(`http://127.0.0.1:${PORT}/json/list`)).json();const t=l.find(x=>x.type==='page'&&/localhost:5173/.test(x.url));if(t&&t.webSocketDebuggerUrl)return t;await sleep(250);} throw new Error('no app target'); }
+function connect(wsUrl){return new Promise(res=>{const ws=new WebSocket(wsUrl);let id=0;const p=new Map();ws.addEventListener('message',ev=>{const m=JSON.parse(ev.data);if(m.id&&p.has(m.id)){const{r,j}=p.get(m.id);p.delete(m.id);m.error?j(new Error(JSON.stringify(m.error))):r(m.result);}});ws.addEventListener('open',()=>{const send=(method,params={})=>new Promise((r,j)=>{const mid=++id;p.set(mid,{r,j});ws.send(JSON.stringify({id:mid,method,params}));});const evalJs=async(e,a=false)=>{const r=await send('Runtime.evaluate',{expression:e,returnByValue:true,awaitPromise:a});if(r.exceptionDetails)throw new Error('eval:'+JSON.stringify(r.exceptionDetails).slice(0,300));return r.result.value;};res({send,evalJs});});});}
+const { send, evalJs } = await connect((await findTarget()).webSocketDebuggerUrl);
+await send('Runtime.enable');
+const log=(...a)=>console.error(...a);
+
+const HELPERS=`
+window.__btn=(txt)=>{const b=[...document.querySelectorAll('button')].find(b=>b.textContent.trim()===txt);if(b){b.click();return true;}return false;};
+window.__summarize=(a)=>{if(!a.length)return null;const s=a.slice().sort((x,y)=>x-y);const n=s.length,mean=a.reduce((p,v)=>p+v,0)/n;const pct=p=>s[Math.min(n-1,Math.floor(p*n))];const drop=a.filter(d=>d>14).length;return{frames:n,mean:+mean.toFixed(2),median:+pct(0.5).toFixed(2),p95:+pct(0.95).toFixed(2),max:+s[n-1].toFixed(2),fps_median:+(1000/pct(0.5)).toFixed(1),dropPct:+(100*drop/n).toFixed(1)};};
+window.__dragPan=(d)=>new Promise(resolve=>{const c=[...document.querySelectorAll('.svg-container')].find(e=>e.offsetParent!==null&&e.querySelector('svg'));if(!c)return resolve({error:'no-container'});const r=c.getBoundingClientRect(),cx=r.left+r.width/2,cy=r.top+r.height/2;c.dispatchEvent(new MouseEvent('mousedown',{bubbles:true,clientX:cx,clientY:cy,button:0}));const iv=[];let last=performance.now();const t0=last;function f(now){iv.push(now-last);last=now;const e=now-t0,t=e/d,dx=Math.sin(t*Math.PI*4)*250;window.dispatchEvent(new MouseEvent('mousemove',{bubbles:true,clientX:cx+dx,clientY:cy,button:0}));if(e<d)requestAnimationFrame(f);else{window.dispatchEvent(new MouseEvent('mouseup',{bubbles:true,clientX:cx+dx,clientY:cy,button:0}));iv.shift();resolve(window.__summarize(iv));}}requestAnimationFrame(f);});
+window.__wheelZoom=(d)=>new Promise(resolve=>{const c=[...document.querySelectorAll('.svg-container')].find(e=>e.offsetParent!==null&&e.querySelector('svg'));if(!c)return resolve({error:'no-container'});const r=c.getBoundingClientRect(),cx=r.left+r.width/2,cy=r.top+r.height/2;const iv=[];let last=performance.now();const t0=last;function f(now){iv.push(now-last);last=now;const e=now-t0;const dir=Math.sin(e/250)>0?-1:1;c.dispatchEvent(new WheelEvent('wheel',{bubbles:true,cancelable:true,clientX:cx,clientY:cy,deltaY:dir*100}));if(e<d)requestAnimationFrame(f);else{iv.shift();resolve(window.__summarize(iv));}}requestAnimationFrame(f);});
+// open Settings -> Configurations tab, set toggle to desired, read state, close.
+window.__setToggle=async(desired)=>{
+  window.__btn('⚙'); await new Promise(r=>setTimeout(r,400));
+  window.__btn('Configurations'); await new Promise(r=>setTimeout(r,300));
+  const t=document.querySelector('[data-testid=smooth-pan-zoom-toggle]');
+  if(!t) return 'NO-TOGGLE';
+  if(t.checked!==desired) t.click();
+  const state={checked:document.querySelector('[data-testid=smooth-pan-zoom-toggle]').checked, ls:localStorage.getItem('cs4g-smooth-pan-zoom')};
+  if(!window.__btn('✕')){const fb=[...document.querySelectorAll('button')].find(b=>/cancel|close/i.test(b.textContent));if(fb)fb.click();}
+  await new Promise(r=>setTimeout(r,400));
+  return state;
+};
+'ok';`;
+await evalJs(HELPERS);
+const TAB = process.env.TAB || 'Network (N)';
+await evalJs(`window.__btn(${JSON.stringify(TAB)})`); await sleep(600);
+log('tab:', TAB, 'visible svg:', await evalJs(`(()=>{const c=[...document.querySelectorAll('.svg-container')].find(e=>e.offsetParent!==null&&e.querySelector('svg'));return c?{nodes:c.querySelector('svg').querySelectorAll('*').length, halos:c.querySelectorAll('.nad-overloaded,.nad-contingency-highlight,.nad-delta-positive,.nad-delta-negative,.nad-action-target').length}:null;})()`));
+
+const out={};
+for (const mode of ['off','on']) {
+  const st = await evalJs(`window.__setToggle(${mode==='on'})`, true);
+  log(mode,'toggle state:', JSON.stringify(st));
+  await sleep(400);
+  await evalJs(`window.__btn(${JSON.stringify(TAB)})`); await sleep(400);
+  const pan = await evalJs(`window.__dragPan(2500)`, true);
+  await sleep(300);
+  const zoom = await evalJs(`window.__wheelZoom(2500)`, true);
+  out[mode]={toggle:st, pan, zoom};
+  log(mode,'pan',JSON.stringify(pan),'zoom',JSON.stringify(zoom));
+}
+console.log(JSON.stringify(out));
+process.exit(0);

benchmarks/interaction_paint/bench_candidates.html

@@ -0,0 +1,145 @@
+<!doctype html>
+<html>
+<head>
+<meta charset="utf-8">
+<title>pan/zoom candidate-optimization bench</title>
+<style>
+  html,body{margin:0;padding:0;background:#fff;font:13px monospace}
+  #stage{width:1400px;height:900px;position:relative;overflow:hidden;border:1px solid #ccc}
+  #out{padding:8px;white-space:pre}
+  /* Candidate-only CSS rules toggled by class on #c. Mirrors what a
+     real-app change would do — additive to App.css culling. */
+  /* C1: drop the 2nd polyline of every edge during gesture */
+  #c.cand-half-poly.svg-interacting .nad-edge > polyline:nth-of-type(2) { display:none !important; }
+  /* C2: content-visibility:auto on edge groups (skip off-screen raster) */
+  #c.cand-cv .nad-edge { content-visibility:auto; contain-intrinsic-size:1px 1px; }
+  /* C3: hide ALL edges during gesture, keep only bus nodes */
+  #c.cand-nodes-only.svg-interacting .nad-branch-edges { display:none !important; }
+  /* C4: hide bus circles during gesture, keep only edges */
+  #c.cand-edges-only.svg-interacting .nad-vl-nodes { display:none !important; }
+  /* C5: hide BOTH 2nd polyline AND bus circles (combined skeleton) */
+  #c.cand-skeleton.svg-interacting .nad-edge > polyline:nth-of-type(2),
+  #c.cand-skeleton.svg-interacting .nad-vl-nodes { display:none !important; }
+  /* C6: drop non-scaling-stroke during gesture (scaled stroke = cheaper raster?) */
+  #c.cand-no-nss.svg-interacting svg path,
+  #c.cand-no-nss.svg-interacting svg line,
+  #c.cand-no-nss.svg-interacting svg polyline,
+  #c.cand-no-nss.svg-interacting svg rect { vector-effect: none !important; }
+  /* C7: optimizeSpeed shape/text rendering during gesture (no AA) */
+  #c.cand-optspeed.svg-interacting svg { shape-rendering: optimizeSpeed; text-rendering: optimizeSpeed; }
+  /* C8: skeleton + optimizeSpeed + no-nss combined */
+  #c.cand-max.svg-interacting .nad-edge > polyline:nth-of-type(2),
+  #c.cand-max.svg-interacting .nad-vl-nodes { display:none !important; }
+  #c.cand-max.svg-interacting svg { shape-rendering: optimizeSpeed; }
+  #c.cand-max.svg-interacting svg polyline { vector-effect: none !important; }
+  /* C9: containment hint on the svg root during gesture */
+  #c.cand-contain.svg-interacting svg { contain: strict; }
+  /* C10: no-nss + half-poly (does dropping 2nd poly stack on top of no-nss?) */
+  #c.cand-nss-half.svg-interacting svg polyline { vector-effect: none !important; }
+  #c.cand-nss-half.svg-interacting .nad-edge > polyline:nth-of-type(2) { display:none !important; }
+</style>
+<style id="appcss"></style>
+</head>
+<body>
+<div id="stage"><div class="svg-container" id="c"></div></div>
+<div id="out">loading…</div>
+<script>
+const meetLocal = (vb, W, H) => { const a = Math.min(W / vb.w, H / vb.h); return { a, cx: (W - a * vb.w) / 2 - a * vb.x, cy: (H - a * vb.h) / 2 - a * vb.y }; };
+let svg, base, baseSize, paths;
+const c = document.getElementById('c');
+const out = document.getElementById('out');
+
+async function setup() {
+  const css = await (await fetch('/frontend/src/App.css')).text();
+  document.getElementById('appcss').textContent = css;
+  const svgText = await (await fetch('/benchmarks/interaction_paint/nad.svg')).text();
+  c.innerHTML = svgText;
+  svg = c.querySelector('svg');
+  const v = svg.getAttribute('viewBox').split(/\s+/).map(Number);
+  base = { x: v[0], y: v[1], w: v[2], h: v[3] };
+  baseSize = { w: c.clientWidth, h: c.clientHeight };
+  const bCx = base.x + base.w / 2, bCy = base.y + base.h / 2;
+  const pX = base.x + base.w * 0.60, pY = base.y + base.h * 0.42;
+  const DETAIL = base.w * 0.12;
+  const lerp = (a, b, t) => a + (b - a) * t, geom = (a, b, t) => a * Math.pow(b / a, t);
+  const vbAt = (cx, cy, w) => { const h = w * (base.h / base.w); return { x: cx - w / 2, y: cy - h / 2, w, h }; };
+  paths = {
+    pan: (t) => { const tt = 0.5 - 0.5 * Math.cos(2 * Math.PI * t); return vbAt(lerp(base.x + base.w*0.30, base.x + base.w*0.72, tt), pY, base.w * 0.22); },
+    zoom: (t) => { const tt = 0.5 - 0.5 * Math.cos(2 * Math.PI * t); return vbAt(lerp(bCx, pX, tt), lerp(bCy, pY, tt), geom(base.w * 0.9, DETAIL, tt)); },
+  };
+  out.textContent = 'ready: ' + JSON.stringify(base);
+}
+
+const applyVb = (vb) => svg.setAttribute('viewBox', `${vb.x} ${vb.y} ${vb.w} ${vb.h}`);
+const CAND_CLASSES = ['cand-half-poly','cand-cv','cand-nodes-only','cand-edges-only','cand-skeleton','cand-no-nss','cand-optspeed','cand-max','cand-contain','cand-nss-half'];
+function reset() {
+  c.classList.remove('svg-interacting', ...CAND_CLASSES);
+  svg.style.transform = ''; svg.style.willChange = ''; svg.style.transformOrigin = '';
+  applyVb(base);
+}
+
+let DROP_THRESH = 12;
+// mode: 'cull' (baseline) or a candidate class name. All apply .svg-interacting
+// (so App.css culling is active) PLUS the candidate class.
+function runArm(mode, gesture, durationMs) {
+  return new Promise((resolve) => {
+    reset();
+    c.classList.add('svg-interacting');
+    if (mode !== 'cull') c.classList.add(mode);
+    const path = paths[gesture];
+    requestAnimationFrame(() => {
+      const intervals = []; let last = performance.now(); const t0 = last;
+      function frame(now) {
+        const dt = now - last; last = now; intervals.push(dt);
+        const elapsed = now - t0; const t = (elapsed / durationMs) % 1;
+        applyVb(path(t));
+        if (elapsed < durationMs) requestAnimationFrame(frame);
+        else { reset(); intervals.shift(); resolve(summarize(intervals)); }
+      }
+      requestAnimationFrame(frame);
+    });
+  });
+}
+function summarize(a) {
+  if (!a.length) return null;
+  const s = a.slice().sort((x, y) => x - y);
+  const n = s.length, mean = a.reduce((p, v) => p + v, 0) / n;
+  const pct = (p) => s[Math.min(n - 1, Math.floor(p * n))];
+  const dropped = a.filter(d => d > DROP_THRESH).length;
+  return { frames: n, mean: +mean.toFixed(2), median: +pct(0.5).toFixed(2), p95: +pct(0.95).toFixed(2), max: +s[n-1].toFixed(2), fps_median: +(1000/pct(0.5)).toFixed(1), dropPct: +(100*dropped/n).toFixed(1) };
+}
+function idleBaseline(durationMs) {
+  return new Promise((resolve) => {
+    reset();
+    const intervals = []; let last = performance.now(); const t0 = last;
+    function frame(now) { intervals.push(now - last); last = now; if (now - t0 < durationMs) requestAnimationFrame(frame); else { intervals.shift(); resolve(summarize(intervals)); } }
+    requestAnimationFrame(frame);
+  });
+}
+
+window.__runCandidates = async function (durationMs = 2500, reps = 3) {
+  const idle = await idleBaseline(1000);
+  DROP_THRESH = idle.median * 1.5;
+  const modes = ['cull', 'cand-no-nss', 'cand-nss-half'];
+  const result = { idle, dropThresh: +DROP_THRESH.toFixed(2), gestures: {} };
+  for (const g of ['pan', 'zoom']) {
+    const acc = {}; for (const m of modes) acc[m] = [];
+    for (let r = 0; r < reps; r++) {
+      for (const m of modes) { acc[m].push(await runArm(m, g, durationMs)); await new Promise(r => setTimeout(r, 150)); }
+    }
+    const agg = {};
+    for (const m of modes) {
+      const reps_ = acc[m];
+      const med = (k) => { const v = reps_.map(x => x[k]).sort((a, b) => a - b); return +v[Math.floor(v.length / 2)].toFixed(2); };
+      agg[m] = { median: med('median'), p95: med('p95'), mean: med('mean'), max: med('max'), fps_median: +(1000/med('median')).toFixed(1), dropPct: med('dropPct') };
+    }
+    result.gestures[g] = agg;
+  }
+  window.__candResult = result;
+  out.textContent = JSON.stringify(result, null, 2);
+  return result;
+};
+setup();
+</script>
+</body>
+</html>

benchmarks/interaction_paint/bench_fluidity.html

@@ -0,0 +1,308 @@
+<!doctype html>
+<html>
+<head>
+<meta charset="utf-8">
+<title>pan/zoom fluidity bench</title>
+<style>
+  html,body{margin:0;padding:0;background:#fff;font:13px monospace}
+  #stage{width:1400px;height:900px;position:relative;overflow:hidden;border:1px solid #ccc}
+  #out{padding:8px;white-space:pre}
+</style>
+<!-- App.css is injected at runtime from the served copy so the .svg-interacting
+     culling rules are byte-identical to the app. -->
+<style id="appcss"></style>
+<!-- Simulates the PRE-#2 state: re-force non-scaling-stroke on equipment during
+     a gesture (higher specificity than App.css #2's override) so we can A/B the
+     #2 quick win. Active only when the container also carries .nss-force. -->
+<style id="nssforce">
+.svg-container.svg-interacting.nss-force .nad-branch-edges path,
+.svg-container.svg-interacting.nss-force .nad-branch-edges line,
+.svg-container.svg-interacting.nss-force .nad-branch-edges polyline,
+.svg-container.svg-interacting.nss-force .nad-branch-edges rect,
+.svg-container.svg-interacting.nss-force .nad-vl-nodes path,
+.svg-container.svg-interacting.nss-force .nad-vl-nodes line,
+.svg-container.svg-interacting.nss-force .nad-vl-nodes polyline,
+.svg-container.svg-interacting.nss-force .nad-vl-nodes rect {
+    vector-effect: non-scaling-stroke !important;
+}
+</style>
+</head>
+<body>
+<div id="stage"><div class="svg-container" id="c"></div></div>
+<div id="out">loading…</div>
+<script>
+// ---- exact port of usePanZoom's smooth-mode math (commit b451ee3) ----
+const meetLocal = (vb, W, H) => {
+  const a = Math.min(W / vb.w, H / vb.h);
+  return { a, cx: (W - a * vb.w) / 2 - a * vb.x, cy: (H - a * vb.h) / 2 - a * vb.y };
+};
+const interactionTransform = (base, target, W, H) => {
+  if (!(W > 0 && H > 0 && base.w > 0 && base.h > 0 && target.w > 0 && target.h > 0)) return null;
+  const lb = meetLocal(base, W, H), lt = meetLocal(target, W, H);
+  const s = lt.a / lb.a, tx = lt.cx - s * lb.cx, ty = lt.cy - s * lb.cy;
+  if (!Number.isFinite(s) || !Number.isFinite(tx) || !Number.isFinite(ty)) return null;
+  return `translate(${tx}px, ${ty}px) scale(${s})`;
+};
+
+let svg, base, baseSize, paths;
+const c = document.getElementById('c');
+const out = document.getElementById('out');
+
+async function setup() {
+  const css = await (await fetch('/frontend/src/App.css')).text();
+  document.getElementById('appcss').textContent = css;
+  const svgFile = new URLSearchParams(location.search).get('svg') || 'nad.svg';
+  const svgText = await (await fetch('/benchmarks/interaction_paint/' + svgFile)).text();
+  c.innerHTML = svgText;
+  svg = c.querySelector('svg');
+  const v = svg.getAttribute('viewBox').split(/\s+/).map(Number);
+  base = { x: v[0], y: v[1], w: v[2], h: v[3] };
+  baseSize = { w: c.clientWidth, h: c.clientHeight };
+  // Build pan & zoom parametric paths (viewBox as a function of t in [0,1]).
+  const bCx = base.x + base.w / 2, bCy = base.y + base.h / 2;
+  const pX = base.x + base.w * 0.60, pY = base.y + base.h * 0.42;
+  const DETAIL = base.w * 0.12;
+  const lerp = (a, b, t) => a + (b - a) * t, geom = (a, b, t) => a * Math.pow(b / a, t);
+  const vbAt = (cx, cy, w) => { const h = w * (base.h / base.w); return { x: cx - w / 2, y: cy - h / 2, w, h }; };
+  paths = {
+    // pan at a fixed "region" zoom level, sweeping across the grid and back
+    pan: (t) => { const tt = 0.5 - 0.5 * Math.cos(2 * Math.PI * t); return vbAt(lerp(base.x + base.w*0.30, base.x + base.w*0.72, tt), pY, base.w * 0.22); },
+    // zoom from overview into detail and back out (ping-pong)
+    zoom: (t) => { const tt = 0.5 - 0.5 * Math.cos(2 * Math.PI * t); return vbAt(lerp(bCx, pX, tt), lerp(bCy, pY, tt), geom(base.w * 0.9, DETAIL, tt)); },
+  };
+  out.textContent = 'ready: ' + JSON.stringify(base);
+}
+
+const applyVb = (vb) => svg.setAttribute('viewBox', `${vb.x} ${vb.y} ${vb.w} ${vb.h}`);
+function reset() {
+  c.classList.remove('svg-interacting');
+  c.classList.remove('nss-force');
+  svg.style.transform = ''; svg.style.willChange = ''; svg.style.transformOrigin = '';
+  applyVb(base);
+}
+
+// Run one arm: mode in {plain, cull, gpu}; gesture in {pan, zoom}.
+// Drives a time-parametrised animation for durationMs and records the
+// real per-frame rAF interval distribution (the fluidity metric).
+let DROP_THRESH = 24;
+function runArm(mode, gesture, durationMs) {
+  return new Promise((resolve) => {
+    reset();
+    const cull = (mode === 'cull' || mode === 'gpu' || mode === 'cull_nss');
+    if (cull) c.classList.add('svg-interacting');
+    if (mode === 'cull_nss') c.classList.add('nss-force');
+    if (mode === 'gpu') { svg.style.transformOrigin = '0 0'; svg.style.willChange = 'transform'; }
+    const path = paths[gesture];
+    // settle on first frame, then measure
+    requestAnimationFrame(() => {
+      const intervals = [];
+      let last = performance.now();
+      const t0 = last;
+      function frame(now) {
+        const dt = now - last; last = now;
+        intervals.push(dt);
+        const elapsed = now - t0;
+        const t = (elapsed / durationMs) % 1;
+        const vb = path(t);
+        if (mode === 'gpu') {
+          const tr = interactionTransform(base, vb, baseSize.w, baseSize.h);
+          if (tr) svg.style.transform = tr; else applyVb(vb);
+        } else {
+          applyVb(vb);
+        }
+        if (elapsed < durationMs) requestAnimationFrame(frame);
+        else {
+          // settle (bake) like endInteraction
+          if (mode === 'gpu') { svg.style.transform = ''; svg.style.willChange = ''; applyVb(vb); }
+          c.classList.remove('svg-interacting');
+          applyVb(base);
+          intervals.shift(); // drop first (warm-up)
+          resolve(summarize(intervals));
+        }
+      }
+      requestAnimationFrame(frame);
+    });
+  });
+}
+
+function summarize(a) {
+  if (!a.length) return null;
+  const s = a.slice().sort((x, y) => x - y);
+  const n = s.length, mean = a.reduce((p, v) => p + v, 0) / n;
+  const pct = (p) => s[Math.min(n - 1, Math.floor(p * n))];
+  const dropped = a.filter(d => d > DROP_THRESH).length;
+  return {
+    frames: n,
+    mean: +mean.toFixed(2),
+    median: +pct(0.5).toFixed(2),
+    p95: +pct(0.95).toFixed(2),
+    max: +s[n - 1].toFixed(2),
+    fps_median: +(1000 / pct(0.5)).toFixed(1),
+    dropped, dropPct: +(100 * dropped / n).toFixed(1),
+  };
+}
+
+// Idle baseline: measure the display refresh period with no work.
+function idleBaseline(durationMs) {
+  return new Promise((resolve) => {
+    reset();
+    const intervals = []; let last = performance.now(); const t0 = last;
+    function frame(now) { intervals.push(now - last); last = now; if (now - t0 < durationMs) requestAnimationFrame(frame); else { intervals.shift(); resolve(summarize(intervals)); } }
+    requestAnimationFrame(frame);
+  });
+}
+
+// Full interleaved suite. Returns a JSON-able result object.
+window.__runSuite = async function (durationMs = 2500, reps = 4) {
+  const idle = await idleBaseline(1000);
+  DROP_THRESH = idle.median * 1.5;
+  const result = { idle, dropThresh: +DROP_THRESH.toFixed(2), gestures: {} };
+  for (const g of ['pan', 'zoom']) {
+    const acc = { plain: [], cull: [], gpu: [] };
+    for (let r = 0; r < reps; r++) {
+      for (const mode of ['plain', 'cull', 'gpu']) {
+        const s = await runArm(mode, g, durationMs);
+        acc[mode].push(s);
+        await new Promise(r => setTimeout(r, 150));
+      }
+    }
+    // aggregate medians across reps
+    const agg = {};
+    for (const mode of ['plain', 'cull', 'gpu']) {
+      const reps_ = acc[mode];
+      const med = (k) => { const v = reps_.map(x => x[k]).sort((a, b) => a - b); return +v[Math.floor(v.length / 2)].toFixed(2); };
+      // dropped-frame %: re-derive from intervals not stored; approximate via median/p95 vs thresh per rep
+      agg[mode] = {
+        median: med('median'), p95: med('p95'), mean: med('mean'), max: med('max'),
+        fps_median: +(1000 / med('median')).toFixed(1),
+        dropPct: med('dropPct'),
+        reps: reps_,
+      };
+    }
+    result.gestures[g] = agg;
+  }
+  window.__result = result;
+  out.textContent = JSON.stringify(result, null, 2);
+  return result;
+};
+
+// ---- Diagnostic arms for "why isn't GPU compositing free?" ----
+
+// Pure ±2px translate of the will-change'd SVG layer: if the layer is truly
+// composited and reused, this should run at display refresh; if Chrome
+// re-rasters the vector layer anyway, it stays slow.
+function runMicro(durationMs) {
+  return new Promise((resolve) => {
+    reset();
+    c.classList.add('svg-interacting');
+    svg.style.transformOrigin = '0 0'; svg.style.willChange = 'transform';
+    requestAnimationFrame(() => {
+      const intervals = []; let last = performance.now(); const t0 = last;
+      function frame(now) {
+        intervals.push(now - last); last = now;
+        const e = now - t0;
+        const dx = 2 * Math.sin(e / 30);
+        svg.style.transform = `translate(${dx}px, 0px) scale(1)`;
+        if (e < durationMs) requestAnimationFrame(frame);
+        else { svg.style.transform = ''; svg.style.willChange = ''; c.classList.remove('svg-interacting'); intervals.shift(); resolve(summarize(intervals)); }
+      }
+      requestAnimationFrame(frame);
+    });
+  });
+}
+
+// Bitmap-snapshot arm: rasterise the SVG to a canvas ONCE at gesture start,
+// transform the (small) bitmap layer during the gesture, restore the live
+// SVG on settle. This is the "snapshot during gesture" optimisation — if it
+// hits refresh rate it proves the bottleneck is vector re-raster, not compositing.
+async function snapshotCanvas() {
+  const clone = svg.cloneNode(true);
+  // Drop the HTML <foreignObject> labels: they taint the canvas (SecurityError
+  // on drawImage) and are culled mid-gesture anyway.
+  clone.querySelectorAll('foreignObject, .nad-label-nodes').forEach(n => n.remove());
+  clone.setAttribute('width', baseSize.w);
+  clone.setAttribute('height', baseSize.h);
+  clone.setAttribute('viewBox', `${base.x} ${base.y} ${base.w} ${base.h}`);
+  const xml = new XMLSerializer().serializeToString(clone);
+  const url = URL.createObjectURL(new Blob([xml], { type: 'image/svg+xml;charset=utf-8' }));
+  const img = new Image();
+  await new Promise((res, rej) => { img.onload = res; img.onerror = rej; img.src = url; });
+  const dpr = window.devicePixelRatio || 1;
+  let cv = document.getElementById('snap');
+  if (!cv) { cv = document.createElement('canvas'); cv.id = 'snap'; cv.style.position = 'absolute'; cv.style.left = '0'; cv.style.top = '0'; cv.style.width = baseSize.w + 'px'; cv.style.height = baseSize.h + 'px'; document.getElementById('stage').appendChild(cv); }
+  cv.width = Math.round(baseSize.w * dpr); cv.height = Math.round(baseSize.h * dpr);
+  const ctx = cv.getContext('2d');
+  ctx.setTransform(dpr, 0, 0, dpr, 0, 0);
+  ctx.clearRect(0, 0, baseSize.w, baseSize.h);
+  ctx.drawImage(img, 0, 0, baseSize.w, baseSize.h);
+  URL.revokeObjectURL(url);
+  return cv;
+}
+
+async function runBitmap(gesture, durationMs) {
+  reset();
+  const cv = await snapshotCanvas();
+  svg.style.visibility = 'hidden';
+  cv.style.display = 'block'; cv.style.transformOrigin = '0 0'; cv.style.willChange = 'transform';
+  const path = paths[gesture];
+  return await new Promise((resolve) => {
+    requestAnimationFrame(() => {
+      const intervals = []; let last = performance.now(); const t0 = last;
+      function frame(now) {
+        intervals.push(now - last); last = now;
+        const e = now - t0; const t = (e / durationMs) % 1; const vb = path(t);
+        const tr = interactionTransform(base, vb, baseSize.w, baseSize.h);
+        if (tr) cv.style.transform = tr;
+        if (e < durationMs) requestAnimationFrame(frame);
+        else { cv.style.display = 'none'; cv.style.transform = ''; cv.style.willChange = ''; svg.style.visibility = ''; applyVb(base); intervals.shift(); resolve(summarize(intervals)); }
+      }
+      requestAnimationFrame(frame);
+    });
+  });
+}
+
+window.__runExtra = async function (durationMs = 2500, reps = 3) {
+  const idle = await idleBaseline(1000);
+  DROP_THRESH = idle.median * 1.5;
+  const micro = []; for (let r = 0; r < reps; r++) { micro.push(await runMicro(durationMs)); await new Promise(r => setTimeout(r, 150)); }
+  const bmp = { pan: [], zoom: [] };
+  for (const g of ['pan', 'zoom']) for (let r = 0; r < reps; r++) { bmp[g].push(await runBitmap(g, durationMs)); await new Promise(r => setTimeout(r, 150)); }
+  const med = (arr, k) => { const v = arr.map(x => x[k]).sort((a, b) => a - b); return +v[Math.floor(v.length / 2)].toFixed(2); };
+  const result = {
+    idle, dropThresh: +DROP_THRESH.toFixed(2),
+    micro_translate: { median: med(micro, 'median'), p95: med(micro, 'p95'), fps_median: +(1000 / med(micro, 'median')).toFixed(1), dropPct: med(micro, 'dropPct'), reps: micro },
+    bitmap_pan: { median: med(bmp.pan, 'median'), p95: med(bmp.pan, 'p95'), fps_median: +(1000 / med(bmp.pan, 'median')).toFixed(1), dropPct: med(bmp.pan, 'dropPct'), reps: bmp.pan },
+    bitmap_zoom: { median: med(bmp.zoom, 'median'), p95: med(bmp.zoom, 'p95'), fps_median: +(1000 / med(bmp.zoom, 'median')).toFixed(1), dropPct: med(bmp.zoom, 'dropPct'), reps: bmp.zoom },
+  };
+  window.__extra = result; out.textContent = JSON.stringify(result, null, 2);
+  return result;
+};
+
+// A/B for the #2 quick win: cull_nss (pre-#2, non-scaling-stroke re-forced)
+// vs cull (current App.css with #2 dropping it). Same cull window otherwise.
+window.__runNss = async function (durationMs = 2500, reps = 4) {
+  const idle = await idleBaseline(1000);
+  DROP_THRESH = idle.median * 1.5;
+  const result = { idle, dropThresh: +DROP_THRESH.toFixed(2), gestures: {} };
+  for (const g of ['pan', 'zoom']) {
+    const acc = { cull_nss: [], cull: [] };
+    for (let r = 0; r < reps; r++) {
+      for (const mode of ['cull_nss', 'cull']) {
+        acc[mode].push(await runArm(mode, g, durationMs));
+        await new Promise(r => setTimeout(r, 150));
+      }
+    }
+    const med = (arr, k) => { const v = arr.map(x => x[k]).sort((a, b) => a - b); return +v[Math.floor(v.length / 2)].toFixed(2); };
+    const agg = {};
+    for (const mode of ['cull_nss', 'cull']) agg[mode] = { median: med(acc[mode], 'median'), p95: med(acc[mode], 'p95'), fps_median: +(1000 / med(acc[mode], 'median')).toFixed(1), reps: acc[mode] };
+    agg.speedup = +(agg.cull_nss.median / agg.cull.median).toFixed(2);
+    result.gestures[g] = agg;
+  }
+  window.__nss = result; out.textContent = JSON.stringify(result, null, 2);
+  return result;
+};
+
+setup();
+</script>
+</body>
+</html>

benchmarks/interaction_paint/bench_pan_zoom.mjs

@@ -0,0 +1,111 @@
+// Copyright (c) 2025-2026, RTE (https://www.rte-france.com)
+// This Source Code Form is subject to the terms of the Mozilla Public License, version 2.0.
+// If a copy of the Mozilla Public License, version 2.0 was not distributed with this file,
+// you can obtain one at http://mozilla.org/MPL/2.0/.
+// SPDX-License-Identifier: MPL-2.0
+//
+// Measure pan/zoom paint cost of the large-grid NAD with and without the
+// interaction-time culling rule (`.svg-interacting` in App.css), driving a
+// real (headless) Chromium. Primary metric: time-to-painted-frame via
+// double-rAF, with `--run-all-compositor-stages-before-draw` so each
+// frame's full raster+composite cost is captured synchronously.
+//
+// "plain"  = no class            (labels + flow infos painted every frame)
+// "cull"   = `.svg-interacting`  (App.css culls the expensive paint
+//                                 elements for the gesture window)
+//
+// The two modes are interleaved across reps to cancel ordering / raster-
+// cache effects. See README.md for setup + the software-GL caveat.
+//
+//   node bench_pan_zoom.mjs            # uses ./nad.svg + ../../frontend/src/App.css
+import { readFileSync, writeFileSync } from 'fs';
+import { createRequire } from 'module';
+import { fileURLToPath } from 'url';
+import { dirname, resolve } from 'path';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const require = createRequire(resolve(__dirname, '../../frontend/'));
+const { chromium } = require('playwright');
+
+// A pre-installed Chromium (Playwright build or system Chrome). Override
+// with PW_CHROME=/path/to/chrome when the default is absent.
+const CHROME = process.env.PW_CHROME || '/opt/pw-browsers/chromium-1194/chrome-linux/chrome';
+const ARGS = ['--no-sandbox', '--enable-unsafe-swiftshader', '--ignore-gpu-blocklist',
+    '--enable-gpu-rasterization', '--disable-frame-rate-limit',
+    '--run-all-compositor-stages-before-draw', '--disable-renderer-backgrounding'];
+
+const W = 1400, H = 900, REPS = 6, APPLIES = 20;
+const svg = readFileSync(resolve(__dirname, 'nad.svg'), 'utf8');
+const css = readFileSync(resolve(__dirname, '../../frontend/src/App.css'), 'utf8');
+const stats = JSON.parse(readFileSync(resolve(__dirname, 'nad.stats.json'), 'utf8'));
+
+const html = `<!doctype html><html><head><meta charset="utf-8"><style>
+html,body{margin:0;padding:0;background:#fff}#stage{width:${W}px;height:${H}px;position:relative}
+${css}
+</style></head><body><div id="stage"><div class="svg-container" id="c">${svg}</div></div></body></html>`;
+
+const summarize = (a) => {
+    if (!a || !a.length) return null;
+    a = a.slice().sort((x, y) => x - y);
+    const n = a.length, mean = a.reduce((s, v) => s + v, 0) / n;
+    const pct = (p) => a[Math.min(n - 1, Math.floor(p * n))];
+    return { n, mean: +mean.toFixed(1), median: +pct(0.5).toFixed(1), p95: +pct(0.95).toFixed(1) };
+};
+const withTimeout = (p, ms, t) => Promise.race([p, new Promise((_, r) => setTimeout(() => r(new Error('timeout ' + t)), ms))]);
+
+const browser = await chromium.launch({ executablePath: CHROME, headless: true, args: ARGS });
+const page = await browser.newPage({ viewport: { width: W, height: H }, deviceScaleFactor: 1 });
+page.on('pageerror', (e) => console.error('PAGEERR', e.message));
+await page.setContent(html, { waitUntil: 'load' });
+await page.waitForTimeout(600);
+
+await page.evaluate(([APPLIES]) => {
+    const c = document.getElementById('c'), svg = c.querySelector('svg');
+    const W = c.clientWidth, H = c.clientHeight;
+    const v = svg.getAttribute('viewBox').split(/\s+/).map(Number);
+    const base = { x: v[0], y: v[1], w: v[2], h: v[3] };
+    const vbAt = (cx, cy, w) => { const h = w * (base.h / base.w); return { x: cx - w / 2, y: cy - h / 2, w, h }; };
+    const lerp = (a, b, t) => a + (b - a) * t, geom = (a, b, t) => a * Math.pow(b / a, t);
+    const bCx = base.x + base.w / 2, bCy = base.y + base.h / 2;
+    const pX = base.x + base.w * 0.62, pY = base.y + base.h * 0.45, DETAIL = base.w * 0.12;
+    const zin = [], pan = [];
+    for (let i = 0; i < APPLIES; i++) {
+        const t = i / (APPLIES - 1);
+        zin.push(vbAt(lerp(bCx, pX, t), lerp(bCy, pY, t), geom(base.w, DETAIL, t)));
+        pan.push(vbAt(pX + base.w * 0.5 * t, pY, DETAIL));
+    }
+    window.__g = { zoomIn: zin, pan };
+    const applyVb = (vb) => svg.setAttribute('viewBox', `${vb.x} ${vb.y} ${vb.w} ${vb.h}`);
+    const reset = () => { c.classList.remove('svg-interacting'); applyVb(base); };
+    const nextPaint = () => new Promise((r) => requestAnimationFrame(() => requestAnimationFrame(() => r())));
+    window.__one = async (interacting, key) => {
+        reset();
+        if (interacting) c.classList.add('svg-interacting');
+        await nextPaint();
+        const times = [];
+        for (const vb of window.__g[key]) { const t0 = performance.now(); applyVb(vb); await nextPaint(); times.push(performance.now() - t0); }
+        reset();
+        return times;
+    };
+}, [APPLIES]);
+
+console.log('grid ' + stats.voltageLevels + ' VL / ' + stats.branches + ' branches / ' + stats.bytesMB + ' MB SVG | viewport ' + W + 'x' + H);
+console.log('time-to-painted-frame (double-rAF), interleaved plain vs cull, ' + REPS + ' reps, headless software-GL\n');
+const result = { grid: stats, phases: {} };
+for (const g of ['pan', 'zoomIn']) {
+    const plain = [], cull = [];
+    for (let r = 0; r < REPS; r++) {
+        try { plain.push(...await withTimeout(page.evaluate(([i, k]) => window.__one(i, k), [false, g]), 90000, 'plain')); } catch (e) { console.error('plain fail', e.message); }
+        await page.waitForTimeout(80);
+        try { cull.push(...await withTimeout(page.evaluate(([i, k]) => window.__one(i, k), [true, g]), 90000, 'cull')); } catch (e) { console.error('cull fail', e.message); }
+        await page.waitForTimeout(80);
+    }
+    const sp = summarize(plain), sc = summarize(cull);
+    result.phases[g] = { plain: sp, cull: sc };
+    console.log(g.padEnd(8) + ' plain  mean ' + sp.mean + 'ms  median ' + sp.median + 'ms  p95 ' + sp.p95 + 'ms');
+    console.log(g.padEnd(8) + ' cull   mean ' + sc.mean + 'ms  median ' + sc.median + 'ms  p95 ' + sc.p95 + 'ms');
+    console.log('         => culling speedup: mean ' + (sp.mean / sc.mean).toFixed(1) + 'x   median ' + (sp.median / sc.median).toFixed(1) + 'x\n');
+}
+writeFileSync(resolve(__dirname, 'result.json'), JSON.stringify(result, null, 2));
+await browser.close();
+console.log('done');

benchmarks/interaction_paint/capture.mjs

@@ -0,0 +1,13 @@
+const PORT=9444; const sleep=ms=>new Promise(r=>setTimeout(r,ms));
+import { writeFileSync } from 'fs';
+const list=await (await fetch(`http://127.0.0.1:${PORT}/json/list`)).json();
+const t=list.find(x=>x.type==='page'&&/localhost:5173/.test(x.url));
+const ws=new WebSocket(t.webSocketDebuggerUrl); let id=0; const p=new Map();
+ws.addEventListener('message',ev=>{const m=JSON.parse(ev.data);if(m.id&&p.has(m.id)){const{r}=p.get(m.id);p.delete(m.id);r(m.result);}});
+await new Promise(r=>ws.addEventListener('open',r));
+const send=(method,params={})=>new Promise(r=>{const mid=++id;p.set(mid,{r});ws.send(JSON.stringify({id:mid,method,params}));});
+await send('Page.enable');
+const {data}=await send('Page.captureScreenshot',{format:'jpeg',quality:72});
+writeFileSync('/tmp/cs4g_app_n1.jpg', Buffer.from(data,'base64'));
+console.log('saved /tmp/cs4g_app_n1.jpg');
+process.exit(0);

benchmarks/interaction_paint/cdp_driver.mjs

@@ -0,0 +1,76 @@
+// Drive the bench_fluidity.html harness in a headed Chrome via the DevTools
+// Protocol (Node 22 global WebSocket + fetch — no npm deps). Chrome must be
+// running with --remote-debugging-port=9333 and the no-throttle flags so the
+// page keeps rendering at full GPU speed even while occluded.
+const PORT = process.env.CDP_PORT || 9333;
+const URLMATCH = 'bench_fluidity.html';
+const DURATION = +(process.env.DUR || 2500);
+const REPS = +(process.env.REPS || 3);
+
+const sleep = (ms) => new Promise(r => setTimeout(r, ms));
+
+async function findTarget() {
+  const wantAny = !!process.env.NAV || process.env.ANYPAGE === '1';
+  for (let i = 0; i < 60; i++) {
+    try {
+      const list = await (await fetch(`http://127.0.0.1:${PORT}/json/list`)).json();
+      const t = wantAny
+        ? list.find(x => x.type === 'page' && /^https?:|^about:|chrome:\/\/newtab/.test(x.url))
+        : list.find(x => x.type === 'page' && x.url.includes(URLMATCH));
+      if (t && t.webSocketDebuggerUrl) return t;
+    } catch { /* port not up yet */ }
+    await sleep(500);
+  }
+  throw new Error('no page target found (wantAny=' + wantAny + ')');
+}
+
+function connect(wsUrl) {
+  return new Promise((resolve, reject) => {
+    const ws = new WebSocket(wsUrl);
+    let id = 0;
+    const pending = new Map();
+    ws.addEventListener('message', (ev) => {
+      const msg = JSON.parse(ev.data);
+      if (msg.id && pending.has(msg.id)) {
+        const { resolve: r, reject: j } = pending.get(msg.id);
+        pending.delete(msg.id);
+        if (msg.error) j(new Error(JSON.stringify(msg.error))); else r(msg.result);
+      }
+    });
+    ws.addEventListener('error', (e) => reject(new Error('ws error ' + (e.message || ''))));
+    ws.addEventListener('open', () => {
+      const send = (method, params = {}) => new Promise((r, j) => {
+        const mid = ++id; pending.set(mid, { resolve: r, reject: j });
+        ws.send(JSON.stringify({ id: mid, method, params }));
+      });
+      const evalJs = async (expr, awaitPromise = false) => {
+        const res = await send('Runtime.evaluate', { expression: expr, returnByValue: true, awaitPromise });
+        if (res.exceptionDetails) throw new Error('eval: ' + JSON.stringify(res.exceptionDetails));
+        return res.result.value;
+      };
+      resolve({ send, evalJs, ws });
+    });
+  });
+}
+
+const EXPR = process.env.EXPR || `window.__runSuite(${DURATION}, ${REPS})`;
+const { evalJs, send } = await connect((await findTarget()).webSocketDebuggerUrl);
+await send('Runtime.enable');
+await send('Page.enable');
+if (process.env.NAV) { await send('Page.navigate', { url: process.env.NAV }); await sleep(2500); }
+else if (process.env.RELOAD === '1') { await send('Page.reload', { ignoreCache: true }); await sleep(1500); }
+
+// Wait for harness readiness.
+for (let i = 0; i < 60 && process.env.SKIPREADY !== '1'; i++) {
+  const ready = await evalJs(`(typeof window.__runSuite === 'function' && typeof window.__runExtra === 'function' && document.getElementById('out') && document.getElementById('out').textContent.startsWith('ready'))`);
+  if (ready) break;
+  await sleep(500);
+}
+
+const env = await evalJs(`(()=>{return {visibility:document.visibilityState, dpr:window.devicePixelRatio, url:location.href};})()`);
+console.error('ENV', JSON.stringify(env));
+if (env.visibility !== 'visible') console.error('WARNING: visibility=' + env.visibility + ' — rAF may be throttled. Anti-throttle flags should keep it running anyway.');
+
+const result = await evalJs(EXPR, true);
+console.log(JSON.stringify(result));
+process.exit(0);

benchmarks/interaction_paint/cdp_pipe_driver.mjs

@@ -0,0 +1,73 @@
+// Launch a headed Chrome via --remote-debugging-pipe (CDP over stdio fds 3/4,
+// NO TCP port — so the IDE's preview/live-reload can't discover and hijack it)
+// and run the fluidity harness. Fully isolated + real GPU (headed on macOS).
+import { spawn } from 'child_process';
+import { openSync } from 'fs';
+
+const CHROME = '/Applications/Google Chrome.app/Contents/MacOS/Google Chrome';
+const URL = process.env.URL || 'http://127.0.0.1:8901/real.html';
+const EXPR = process.env.EXPR || `window.__runSuite(${+(process.env.DUR || 2500)}, ${+(process.env.REPS || 3)})`;
+const sleep = (ms) => new Promise(r => setTimeout(r, ms));
+
+const log = openSync('/tmp/cs4g_pipe_chrome.log', 'a');
+const child = spawn(CHROME, [
+  '--user-data-dir=/tmp/cs4g-bench-pipe',
+  '--remote-debugging-pipe',
+  '--no-first-run', '--no-default-browser-check', '--no-startup-window=false',
+  '--disable-backgrounding-occluded-windows', '--disable-renderer-backgrounding',
+  '--disable-background-timer-throttling', '--disable-features=CalculateNativeWinOcclusion',
+  '--window-size=1500,1000', URL,
+], { stdio: ['ignore', log, log, 'pipe', 'pipe'] });
+
+const wr = child.stdio[3], rd = child.stdio[4];
+let id = 0; const pending = new Map();
+const events = [];
+let buf = Buffer.alloc(0);
+rd.on('data', (chunk) => {
+  buf = Buffer.concat([buf, chunk]);
+  let i;
+  while ((i = buf.indexOf(0)) !== -1) {
+    const msg = JSON.parse(buf.slice(0, i).toString('utf8'));
+    buf = buf.slice(i + 1);
+    if (msg.id && pending.has(msg.id)) { const { res, rej } = pending.get(msg.id); pending.delete(msg.id); msg.error ? rej(new Error(JSON.stringify(msg.error))) : res(msg.result); }
+    else if (msg.method) events.push(msg);
+  }
+});
+const send = (method, params = {}, sessionId) => new Promise((res, rej) => {
+  const mid = ++id; pending.set(mid, { res, rej });
+  const m = { id: mid, method, params }; if (sessionId) m.sessionId = sessionId;
+  wr.write(JSON.stringify(m) + '\0');
+});
+
+// Discover the page target and attach (flattened sessions).
+await send('Target.setDiscoverTargets', { discover: true });
+let targetId = null;
+for (let i = 0; i < 80 && !targetId; i++) {
+  const { targetInfos } = await send('Target.getTargets');
+  const t = targetInfos.find(x => x.type === 'page' && /^https?:/.test(x.url));
+  if (t) targetId = t.targetId; else await sleep(250);
+}
+if (!targetId) { console.error('no page target'); child.kill(); process.exit(1); }
+const { sessionId } = await send('Target.attachToTarget', { targetId, flatten: true });
+const evalJs = async (expr, awaitPromise = false) => {
+  const r = await send('Runtime.evaluate', { expression: expr, returnByValue: true, awaitPromise }, sessionId);
+  if (r.exceptionDetails) throw new Error('eval: ' + JSON.stringify(r.exceptionDetails).slice(0, 400));
+  return r.result.value;
+};
+await send('Runtime.enable', {}, sessionId);
+
+// If the page isn't on our URL yet (fresh profile may show a default), navigate once.
+const cur = await evalJs('location.href');
+if (!cur.includes(URL.split('/').pop())) { await send('Page.enable', {}, sessionId); await send('Page.navigate', { url: URL }, sessionId); await sleep(2500); }
+
+for (let i = 0; i < 80; i++) {
+  const ready = await evalJs(`(typeof window.__runSuite==='function' && typeof window.__runExtra==='function' && document.getElementById('out') && document.getElementById('out').textContent.startsWith('ready'))`).catch(() => false);
+  if (ready) break; await sleep(500);
+}
+const env = await evalJs(`(()=>{const gl=document.createElement('canvas').getContext('webgl');const d=gl&&gl.getExtension('WEBGL_debug_renderer_info');return {visibility:document.visibilityState,dpr:window.devicePixelRatio,gpu:d?gl.getParameter(d.UNMASKED_RENDERER_WEBGL):'n/a',svgChildren:document.querySelectorAll('#c svg *').length, url:location.href};})()`);
+console.error('ENV', JSON.stringify(env));
+
+const result = await evalJs(EXPR, true);
+console.log(JSON.stringify(result));
+child.kill();
+process.exit(0);

benchmarks/interaction_paint/fluidity_result.phaseA.json

@@ -0,0 +1,3 @@
+{"env":{"gpu":"Apple M4 Pro (ANGLE Metal)","dpr":1,"display_hz":120,"idle_median_ms":8.3,"svgChildren":132905,"grid":"pypsa_eur_eur220_225_380_400 synthetic NAD (5247 VL / 8205 br / 7.26MB)"},
+"main":{"pan":{"plain":91.7,"cull":58.3,"gpu":49.8},"zoom":{"plain":108.6,"cull":65.0,"gpu":49.6}},
+"diagnostic":{"micro_translate_median_ms":48.0,"bitmap_pan_median_ms":8.3,"bitmap_zoom_median_ms":8.3}}

benchmarks/interaction_paint/fluidity_result.realApp.json

@@ -0,0 +1,3 @@
+{"env":{"app":"localhost:5173 + backend:8000","gpu":"Apple M4 Pro Metal","dpr":1,"hz":120},
+ "N_tab":{"off":{"pan":60.1,"zoom":75.0},"on":{"pan":50.0,"zoom":50.1}},
+ "N1_tab":{"off":{"pan":82.6,"zoom":83.9},"on":{"pan":58.4,"zoom":66.7},"contingency":"T_relation_13260100-400-225 (HAVRE LE CENTRALE)","svgNodes":104213}}

benchmarks/interaction_paint/fluidity_result.realNAD.json

@@ -0,0 +1,4 @@
+{"env":{"gpu":"Apple M4 Pro (ANGLE Metal)","dpr":1,"display_hz":120,"idle_median_ms":8.3,"svgChildren":98959,"svgMB":9.1,"labels":"<text> (15706), not foreignObject","grid":"pypsa_eur_eur220_225_380_400 REAL pypowsybl NAD"},
+"main":{"pan":{"plain":100.0,"cull":58.0,"gpu":41.9},"zoom":{"plain":126.7,"cull":65.1,"gpu":43.3}},
+"diagnostic":{"micro_translate_median_ms":41.7,"bitmap_pan_median_ms":8.3,"bitmap_zoom_median_ms":8.3},
+"notes":"zoom plain p95 spikes to ~1008ms (text-label re-raster). bitmap=120fps/0-drop on real NAD too."}