Repository navigation
docs: Update CLAUDE.md, README.md, and backend/frontend guides for 0.6.5 - #115
Merged
Merged
Conversation
The four top-level docs had drifted since their last respective updates (root from PR #104, frontend from PR #109, backend + README from PR #103). Bring them in line with the main branch as of 0.6.5. Root CLAUDE.md: - Architecture tree now lists services/analysis, services/diagram and simulation_helpers.py (PR #104 / #106 decomposition), plus frontend/src/utils/svg/ modules, svgPatch.ts, actionTypes.ts, fileRegistry.ts, and the new hooks (useN1Fetch, useDiagramHighlights) and components (AppSidebar, SidebarSummary, StatusToasts, …). - Tech Stack drops framer-motion + lucide-react (removed in PR #104) and surfaces vite-plugin-singlefile + Vitest. - API table adds /api/n1-diagram-patch, /api/action-variant-diagram-patch, /api/simulate-and-variant-diagram, /api/user-config and /api/config-file-path. - Integration-script paths moved under scripts/pypsa_eur/; App.tsx size bumped to ~1150 lines to match the hook extraction. Frontend CLAUDE.md: - Layout tree now enumerates utils/svg/* submodules, utils/svgPatch.ts, utils/actionTypes.ts, utils/fileRegistry.ts and the new shared ActionTypeFilterChips component. - SVG-handling section gains the DOM-recycling fast path. Backend CLAUDE.md: - services/ tree now includes the diagram/ (7 modules) and analysis/ (4 modules) subpackages plus simulation_helpers.py, with a new paragraph describing the mixin → helper-package decomposition and @patch-compatibility contract. - API surface adds the new patch endpoints. - Conventions note the narrow E9/F ruff ruleset and the CORS_ALLOWED_ORIGINS env var; drops the manual standalone mirror requirement. README.md: - Release badge 0.5.0 → 0.6.5. - Frontend engineering section replaces Phase 2 state-management wording with the Phase 2 hook extraction + SVG DOM recycling highlights; drops framer-motion / lucide-react. - Performance Highlights gains a dedicated 0.6.5 table (patch endpoints, cold/warm/payload) above the 0.5.0 one. - Architecture snippet updated with the new subfolders and new frontend components. - Backend test-command block replaced with the real test story (pytest + code-quality gate + profiling scripts + pypsa_eur pipeline) — the previous block referenced files that no longer exist (test_api_stream.py, test_n1_api.py, …). - API Reference gains the three new endpoints from the patch flow. - Standalone section rewritten to describe the auto-generated dist-standalone/standalone.html bundle + the four parity layers. https://claude.ai/code/session_01RsvHjjFbAauF3NvD9BNT5V
The kV filter is a vertical dual-range slider with two stacked <input type="range"> elements. The high handle sits on top by default (zIndex 4 above zIndex 3). When the user pulls both handles together at the top of the scale — e.g. voltageRange = [400, 400] with maxV = 400 — the range becomes inescapable: - The high handle is clamped by `snapped >= voltageRange[0] = maxV`, so it cannot move up (already at max) and cannot move down (the low handle blocks it at maxV). - The low handle, which could still be dragged down to expand the range, is hidden beneath the high handle and unreachable. Swap the z-order exactly when the range collapses at maxV: raise the low handle to zIndex 5 so the user can grab it and drag it back down. Every other state (open range, collapsed at minV, collapsed at an intermediate value where the high handle can still move up) keeps the default z-order. Added three regression tests in VisualizationPanel.test.tsx covering the default, maxV-collapse and minV-collapse cases. https://claude.ai/code/session_01RsvHjjFbAauF3NvD9BNT5V
… when range reopens
`applyVoltageFilter` had an early-return when the current range was
"fully open" (minKv ≤ uniqueVoltages[0] && maxKv ≥ uniqueVoltages[last]):
if (minKv <= uniqueVoltages[0] && maxKv >= ...) return;
That short-circuited the reset pass whenever the user expanded a
previously narrow range back out. Scenario that motivated this fix
(PyPSA-EUR fr225_400, uniqueVoltages = [225, 400]):
1. User collapses the filter to [225, 225] — every 400 kV node, legend
entry and edge gets `display:none`.
2. User drags the low handle back down to 225 (range becomes
[225, 400], i.e. fully open).
3. Effect fires, applyVoltageFilter early-returns, and the 400 kV
elements stay hidden. The map only shows 225 kV lines — the user
sees a broken redraw even though "no filter is applied".
Fix: track per-tab whether the last applied filter actually hid
anything (`prevFilterHadHidden`). The fully-open short-circuit now
only fires when the PREVIOUS range was also fully open — otherwise we
run the loop once to reset `display` back to '' on everything and
clear the flag. Filter still skips the redundant DOM walk on the
normal "never filtered" startup path, so there's no perf regression.
Added two regression tests in useDiagrams.test.ts covering the
narrow-range hide and the reopen-resets-display paths.
https://claude.ai/code/session_01RsvHjjFbAauF3NvD9BNT5V
Follow-up to the root/frontend/backend CLAUDE.md + README refresh. Audits the remaining project docs against PRs merged 2026-04-21 → 2026-04-23 and updates the eight that had actually drifted. frontend/README.md (HIGH) Replaced the stock Vite-template boilerplate with a real frontend orientation: npm scripts, source-tree map (hooks, components, utils incl. the utils/svg/* split from PR #104), pointer to the auto-generated standalone bundle, testing + lint commands, and cross-refs to CLAUDE.md / PARITY_AUDIT.md / docs/README.md. expert_backend/tests/CLAUDE.md (MEDIUM) Full rewrite of the test-file inventory: added the PR #104 decomposition suites (test_simulation_helpers.py, test_analysis_helpers.py, test_diagram_helpers.py), the patch- endpoint coverage (test_diagram_patch_helpers.py, test_n1_diagram_fast_path.py) from PR #108, the regression guards (test_resimulate_regression.py, test_second_contingency_reset.py, test_get_n1_variant_clones_from_n_state.py, test_configurable_mw.py) that were added since 2026-04-11, and the dynamic reco_* reconnection path from PR #110. Replaced the frontend inventory with a structural summary matching the current ~60-file Vitest layout, listed the scripts/pypsa_eur pytest coverage, and documented the tests removed by PR #103 / #104 (test_ui_regressions.py, standaloneInterface.test.ts, cssRegression.test.ts). docs/features/combined-actions.md (MEDIUM) Added a "Recent updates (PR #114, release 0.6.5)" section covering LS/curtailment in combined pairs, Simulate Combined moved out of the card + clickable sub-action badges, target_max_rho on the user-selected overload set, and Explore- Pairs re-estimation aligned with the pre-computed betas. Rewrote the "Standalone Interface" section to describe the auto-generated bundle, and dropped the checklist line that required manual standalone_interface.html mirroring. Added a row to the key-files table for the ActionCard sub-action badges and the ComputedPairsTable / ExplorePairsTab split. docs/features/state-reset-and-confirmation-dialogs.md (MEDIUM) Replaced the standalone_interface.html section with a pointer to the auto-generated bundle, and expanded the "What reset() clears" list to match the current RecommenderService.reset() implementation (drain order + fast-path caches + _layout_cache + NAD-prefetch state, with the add-a-new-cache-goes-here guardrail). docs/features/detachable-viz-tabs.md (MEDIUM) Removed the "standalone_interface.html mirror" row and the follow-up caveat that said the single-file interface doesn't support detaching — both are obsolete now that the bundle is auto-generated from the React tree. docs/architecture/app-refactoring-plan.md (MEDIUM) Added a "Status: SHIPPED" banner at the top summarising both refactor waves (Phase 1 via PR #74, Phase 2 hook extraction via PR #109) and pointing readers at the current source of truth (frontend/CLAUDE.md + CHANGELOG.md 0.6.5). Preserved the original plan below the banner for historical value. docs/architecture/phase2-state-management-optimization.md (LOW) Added a "Status: Partially shipped" banner — memoization + React.memo pass shipped under PR #75, superseded in part by PR #109 (useN1Fetch / useDiagramHighlights extractions), orchestrator hooks still deferred. docs/features/frontend-ui-improvements.md (LOW) Scope header now names `frontend/dist-standalone/standalone.html` (auto-generated, PR #101) instead of the decommissioned hand-maintained file. https://claude.ai/code/session_01RsvHjjFbAauF3NvD9BNT5V
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
This PR updates project documentation to reflect the current state of Co-Study4Grid at release 0.6.5, including recent architectural decompositions (PR #104/#106), SVG DOM recycling optimization (PR #108), hook extraction (PR #109), and the auto-generated standalone UI (PR #101).
Key Changes
CLAUDE.md (root project overview)
services/diagram/,services/analysis/,services/simulation_helpers.py,frontend/src/utils/svg/, andscripts/pypsa_eur/DiagramMixin,AnalysisMixin, andSimulationMixinare now thin orchestrators delegating to helper packages/api/n1-diagram-patchand/api/action-variant-diagram-patchendpoints andutils/svgPatch.tsfast-pathframer-motionandlucide-reactwithvite-plugin-singlefileandVitest/api/simulate-and-variant-diagramE9+Fruleset only)npm run build:standaloneand decommissioning of hand-maintainedstandalone_interface.htmlscripts/pypsa_eur/with their own pytest coverageREADME.md (user-facing guide)
useN1Fetch,useDiagramHighlights), SVG DOM recycling performance gains (~80% faster), and code-quality gate/api/n1-diagram-patchspeedup (−83.8% cold, −79.1% warm) vs. full endpointdist-standalone/,benchmarks/, andscripts/with PyPSA-EUR pipelinenpm run build:standaloneoutput and parity guards/api/simulate-and-variant-diagramexpert_backend/CLAUDE.md (backend guide)
diagram/,analysis/subdirectories andsimulation_helpers.py@patchtest compatibility/api/n1-diagram-patchand/api/action-variant-diagram-patchwith performance contextprint()/ bare except /any/@ts-ignoreCORS_ALLOWED_ORIGINSenv var configuration (PR Code-quality gate + decomposition sweep (5 modules) #104)frontend/CLAUDE.md (frontend guide)
svg/subdirectory with 8 focused modules (idMap, metadataIndex, svgBoost, fitRect, deltaVisuals, actionPin*, highlights)https://claude.ai/code/session_01RsvHjjFbAauF3NvD9BNT5V