opendss-designer 0.1.0__tar.gz

opendss_designer-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,64 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  backend:
+    name: Backend (pytest)
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: '3.12'
+          cache: pip
+      - run: pip install -e ".[dev]"
+      - run: pytest -q
+
+  frontend:
+    name: Frontend (tsc + vitest)
+    runs-on: ubuntu-latest
+    defaults:
+      run:
+        working-directory: frontend
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: '24'
+          cache: npm
+          cache-dependency-path: frontend/package-lock.json
+      - run: npm ci
+      - run: npm run build
+      - run: npm test
+
+  e2e:
+    name: End-to-end (Playwright)
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: '3.12'
+          cache: pip
+      - uses: actions/setup-node@v4
+        with:
+          node-version: '24'
+          cache: npm
+          cache-dependency-path: frontend/package-lock.json
+      - run: pip install -e ".[dev]"
+      - run: npm ci
+        working-directory: frontend
+      - run: npx playwright install --with-deps chromium
+        working-directory: frontend
+      - run: npm run e2e
+        working-directory: frontend
+      - uses: actions/upload-artifact@v4
+        if: failure()
+        with:
+          name: playwright-traces
+          path: frontend/test-results/
+          retention-days: 7

opendss_designer-0.1.0/.github/workflows/docs.yml

@@ -0,0 +1,42 @@
+name: Docs
+
+on:
+  push:
+    branches: [main]
+    paths:
+      - docs/**
+      - mkdocs.yml
+      - .github/workflows/docs.yml
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+concurrency:
+  group: pages
+  cancel-in-progress: true
+
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: '3.12'
+          cache: pip
+      - run: pip install mkdocs-material
+      - run: mkdocs build --strict
+      - uses: actions/configure-pages@v5
+        with:
+          enablement: true
+      - uses: actions/upload-pages-artifact@v3
+        with:
+          path: site
+      - id: deployment
+        uses: actions/deploy-pages@v4

opendss_designer-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,51 @@
+name: Publish to PyPI
+
+on:
+  release:
+    types: [published]
+  workflow_dispatch:
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: '24'
+          cache: npm
+          cache-dependency-path: frontend/package-lock.json
+      - uses: actions/setup-python@v5
+        with:
+          python-version: '3.12'
+          cache: pip
+      - run: python scripts/build_frontend.py
+      - run: pip install build
+      - run: python -m build
+      # The frontend must ship inside the wheel; fail loudly if it didn't.
+      - name: Verify wheel contains the frontend
+        run: |
+          python - <<'EOF'
+          import glob, sys, zipfile
+          wheel = glob.glob("dist/*.whl")[0]
+          names = zipfile.ZipFile(wheel).namelist()
+          assert "opendss_designer/static/index.html" in names, names
+          print(f"OK: {wheel} contains the built frontend")
+          EOF
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    needs: build
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write   # PyPI trusted publishing (OIDC) — no API token needed
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+      - uses: pypa/gh-action-pypi-publish@release/v1

opendss_designer-0.1.0/.gitignore

@@ -0,0 +1,20 @@
+__pycache__/
+*.pyc
+.pytest_cache/
+dist/
+build/
+*.egg-info/
+
+frontend/node_modules/
+frontend/dist/
+
+# built frontend copied into the package (regenerate with scripts/build_frontend.py)
+src/opendss_designer/static/
+frontend/*.tsbuildinfo
+
+# MkDocs build output
+site/
+
+# Playwright output
+frontend/test-results/
+frontend/playwright-report/

opendss_designer-0.1.0/FUTURE_IMPROVEMENTS.md

@@ -0,0 +1,109 @@
+# Roadmap
+
+Features deferred from v1, organized into milestones. Each milestone leaves the app
+in a coherent, working state. Ordering rationale: foundation first (tests/CI protect
+everything after), then balanced passes across editor UX, new components, analysis,
+and platform. Sizing is rough (working sessions).
+
+## M1 — Foundation & hardening — ✅ DONE (2026-08-30)
+
+No visible features; protects everything after.
+
+- **Frontend test harness** (vitest) for the pure logic: `circuitStore.ts`
+  (`validateConnection`, `toCircuitJSON`/`fromCircuitJSON`, busbar handle remapping),
+  `lib/layout.ts` geometry, `lib/fields.tsx` winding get/patch
+- **Playwright smoke e2e**: place source → line → load, solve, assert voltage overlay;
+  export/import round-trip
+- **CI** (GitHub Actions): pytest + `tsc -b` + vitest + Playwright on push
+- **Schema-drift guard**: round-trip test with every node/edge type, catching
+  `types/circuit.ts` ↔ `core/model.py` divergence (revisit codegen if it keeps biting)
+- **Error UX cleanup**: replace `alert()` call sites with the existing `flash` toast;
+  surface errors from `lib/solve.ts`; narrow the bare `except Exception` in `routes.py`
+  so server bugs return 500, not 400
+- Housekeeping: remove stray root screenshot, drop unused `react-hook-form`
+
+## M2 — Editor UX quick wins — ✅ DONE (2026-08-30)
+
+All frontend-only; the M1 vitest harness covers the store changes.
+
+- ~~**Copy/paste** and duplicate (Ctrl+C/V/D)~~ — collision-safe renaming, cascading offsets
+- ~~**Keyboard palette shortcuts**~~ — S/B/T/K/L place, W/E switch wire/line mode
+- ~~**Rotate symbols** (R key)~~ — params.rotation, handles follow; busbars excluded
+- ~~**Right-click context menus**~~ — open/close breaker, rotate, duplicate, delete,
+  straighten edge
+- ~~**Result tooltips** on hover~~ — per-phase V/angle (backend now returns `vangDeg`),
+  currents, power, loading
+- ~~**Finer undo granularity**~~ — per-gesture grouping via begin/endGesture; selection
+  changes excluded from history
+- Still open from this bucket: **multi-select property editing** (deferred to a later
+  milestone; single-element editing plus spreadsheet fill-down covers most of it)
+
+## M3 — Component pack 1: real-feeder essentials — ✅ DONE (2026-08-30)
+
+- ~~**Capacitor banks**~~ — shunt kvar, delta/wye, numsteps; imports/exports/solves
+- ~~**Generators**~~ — kW/pf with model 1 (const PQ) or 3 (PV, holds vpu); circle-G symbol
+- ~~**Line codes**~~ — built-in conductor preset library (`lib/lineCodes.ts`, 8 typical
+  OH/UG constructions) that stamps editable Ω/km values; imported linecode names kept
+  as reference tags. True LineCode entity round-trip stays in M7.
+- ~~Importer support~~ — capacitors and generators read back; `docs/adding-an-element.md`
+  checklist written so remaining component types are mechanical
+
+## M4 — Analysis pack 1 — ✅ DONE (2026-08-30)
+
+- ~~**Fault study**~~ — `/api/faultstudy` (mode=faultstudy → per-bus Zsc1/Zsc0);
+  "Fault" overlay shows 3φ kA badges on busbars, tooltip adds 1φ/SC-MVA/Z1;
+  runs lazily on overlay select, invalidated by any circuit edit
+- ~~**Losses breakdown**~~ — per-series-element kW/kvar losses (shunt elements
+  deliberately report none) in a sortable Losses tab with % of total
+- ~~**Voltage profile plot**~~ — grew into a general **Graph tab**: pick Y
+  (bus V min/max, or per-element P/Q flow, current, loading, losses) vs X
+  (km from source via solver `busDistances`, or bus voltage); classic
+  OpenDSS plot styling — per-phase traces (black/red/blue), bold red
+  0.95/1.05 limit lines, framed white plot — with zoom buttons, drag-pan,
+  Shift+drag zoom box, wheel zoom, and phase toggles. Bottom panel is
+  drag-resizable (persisted height).
+
+## M5 — DER pack + time series (~3–4 sessions)
+
+The biggest single milestone; the M3 checklist makes the components mechanical.
+
+- **PV systems** (`PVSystem`) — irradiance/temperature curves, inverter kVA
+- **Storage** (`Storage`) — kWh rating, charge/discharge dispatch
+- **LoadShape editor** (CSV paste + curve editor), assignable to loads/PV/storage
+- **Daily/yearly time series** — energy meters and monitors, progress streaming
+  (websocket/SSE), result plots over time (add a charting dependency here)
+
+## M6 — Regulation, protection & phases (~2–3 sessions)
+
+- **Voltage regulators** (`RegControl` on an autotransformer) — band, PT ratio, LDC
+- **3-winding transformers** — third handle; the per-winding editor already generalizes
+- **Fuses, reclosers, relays** (`Fuse`, `Recloser`, `Relay`) — pairs with M4's fault study
+- **Phase pinning** — connect 1-phase elements to a chosen phase (`.2`, `.3` suffixes;
+  `compiler.py` already accepts explicit suffixes, so this is mostly UI)
+- **Per-phase display** — phase labels on wires, per-phase voltage readouts
+
+## M7 — Platform & polish (~2–3 sessions, pick-and-choose)
+
+- **Smarter .dss import layout**: elkjs layered layout; keep 2-terminal pass-through
+  buses as plain wires instead of busbars
+- **Automatic wire routing** (elkjs edge routing — shares the elkjs dependency)
+- **File System Access API** in-place saves (localStorage autosave already shipped)
+- **Dark mode**, printable/exportable diagram (SVG/PNG export)
+- **Round-trip preservation** of comments and unsupported elements on export
+- **Split line**: drop a bus in the middle of an existing Line edge
+
+## Parking lot (deferred until actually needed)
+
+- **Incremental solve** — reuse the compiled circuit when only parameter values changed;
+  matters once circuits reach thousands of elements (v1 rebuilds every solve)
+- **Multi-circuit tabs** / compare two scenarios side by side — big architectural change;
+  wait until the single-circuit workflow is mature
+- **Explicit grounding elements** (`Reactor` to ground, grounding transformer symbols)
+
+## Done since v1
+
+- Project autosave to browser storage (debounced localStorage save + restore in `App.tsx`)
+- M1 (2026-08-30): vitest unit tests (`frontend/src/**/*.test.ts`), Playwright e2e
+  (`frontend/e2e/`), GitHub Actions CI, schema-drift guard
+  (`tests/fixtures/full-circuit.oneline.json` round-tripped by both pytest and vitest),
+  flash-toast error surfacing (no more `alert()`), import bugs now 500 not 400

opendss_designer-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ryan Sparks
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

opendss_designer-0.1.0/PKG-INFO

@@ -0,0 +1,126 @@
+Metadata-Version: 2.5
+Name: opendss-designer
+Version: 0.1.0
+Summary: A graphical user interface (GUI) for OpenDSS: draw one-line diagrams in your browser, run power flows, import and export .dss files
+Project-URL: Homepage, https://opendssdesigner.ryanmsparks.com
+Project-URL: Documentation, https://opendssdesigner.ryanmsparks.com
+Project-URL: Repository, https://github.com/rsparks3/opendss-designer
+Project-URL: Issues, https://github.com/rsparks3/opendss-designer/issues
+Author-email: Ryan Sparks <ryan@ryanmsparks.com>
+License: MIT
+License-File: LICENSE
+Keywords: distribution-system,electrical-engineering,epri,graphical-interface,gui,one-line-diagram,opendss,opendssdirect,power-flow,power-systems,single-line-diagram
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Scientific/Engineering
+Classifier: Topic :: Scientific/Engineering :: Visualization
+Requires-Python: >=3.10
+Requires-Dist: fastapi>=0.115
+Requires-Dist: opendssdirect-py>=0.9
+Requires-Dist: pydantic>=2.9
+Requires-Dist: uvicorn[standard]>=0.30
+Provides-Extra: dev
+Requires-Dist: httpx; extra == 'dev'
+Requires-Dist: pytest>=8; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# OpenDSS Designer
+
+A free, open-source **graphical user interface (GUI) for
+[OpenDSS](https://www.epri.com/pages/sa/opendss)**, EPRI's distribution system
+simulator — built on [OpenDSSDirect.py](https://github.com/dss-extensions/OpenDSSDirect.py).
+Draw a substation-style one-line (single-line) diagram in your browser — the
+drawing **is** the circuit model — then run a power flow and see voltages,
+loading, and violations right on the diagram. Import existing `.dss` files,
+edit visually or in a spreadsheet view, and export runnable OpenDSS scripts.
+
+📖 **Documentation: [opendssdesigner.ryanmsparks.com](https://opendssdesigner.ryanmsparks.com)**
+
+![screenshot](docs/screenshot.png)
+
+## Features (v1)
+
+- **Click-and-place palette**: Source (Vsource), Busbar, 2-winding Transformer, Breaker/Switch, Load —
+  placement is sticky, so keep clicking to drop several; Esc to stop
+- **Drag-to-wire**: drag between terminals; choose **Wire** (ideal connection, merges buses) or
+  **Line** (a real OpenDSS Line with impedance and length). Illegal connections (busbar-to-busbar
+  wires, self-connections, duplicates) are refused with an explanation
+- **Stretchable busbars** with connection points along both edges (top and bottom rows), plus
+  implicit junction buses when you wire elements directly together
+- **Double-click a breaker** to open/close it; **double-click a wire or line** to add a draggable
+  routing point and shape the run yourself (double-click a point to remove it)
+- **Properties panel** with the OpenDSS parameters for each element (kV, kVA, impedances,
+  phases 1/2/3, wye/delta, load model…)
+- **Solve** button → snapshot power flow → overlays on the diagram:
+  bus voltages (pu), element loading as pie charts + %, power flows, with color-coded
+  violations (undervoltage blue, overvoltage/overload red) and total losses in the
+  status bar — or toggle **Auto** to re-solve automatically on every circuit change
+- **Live validation**: unconnected terminals, missing source, islands, duplicate names,
+  kV mismatches — errors disable Solve and halo the offending element
+- **Spreadsheet view**: an Elements tab in the bottom panel lists every source, busbar,
+  transformer, line, breaker, and load in an editable table (plus a read-only bus-results
+  table after a solve) — edit values in bulk with an Excel-style fill-down handle,
+  click ⌖ to locate an element on the diagram
+- **Undo/redo** (Ctrl+Z / Ctrl+Y), delete key, grid snapping, pan/zoom, minimap
+- **Save/Open** projects as JSON; **Export** a runnable `.dss` file;
+  **Import** existing `.dss` files (select the main file plus anything it redirects to)
+  with a hierarchical auto-layout — source at top, loads beneath their buses
+
+## Install & run
+
+Requires Python 3.10+.
+
+```bash
+pip install opendss-designer
+opendss-designer            # starts a local server and opens your browser
+```
+
+(Or from a clone of this repo: `pip install -e .` — see Development below for
+building the frontend.)
+
+Options: `--port 8721`, `--no-browser`.
+
+Try it: **Open** `examples/demo-substation.oneline.json`, press **Solve**.
+
+## Development
+
+Backend (FastAPI + OpenDSSDirect.py):
+
+```bash
+pip install -e .[dev]
+pytest                      # backend test suite
+PYTHONPATH=src python -m opendss_designer.cli --no-browser   # serve API + built frontend
+```
+
+Frontend (React + Vite + React Flow), in a second terminal:
+
+```bash
+cd frontend
+npm install
+npm run dev                 # http://localhost:5173, proxies /api to :8721
+```
+
+To bundle the frontend into the Python package (before building a wheel):
+
+```bash
+python scripts/build_frontend.py
+```
+
+### Architecture
+
+- `frontend/` — React + Vite app. React Flow canvas with custom ANSI-symbol nodes;
+  zustand store is the canonical circuit model (zundo for undo history).
+  `window.opendssDesigner` exposes the stores for console scripting.
+- `src/opendss_designer/core/connectivity.py` — union-find translation of the drawn graph
+  into OpenDSS bus names (wires merge terminals; Line edges are series elements).
+- `src/opendss_designer/core/compiler.py` — circuit JSON → ordered OpenDSS Text commands;
+  the same commands back both `/api/solve` and `.dss` export.
+- `src/opendss_designer/core/engine.py` — solves and extracts per-bus voltages and
+  per-element loading through the OpenDSSDirect API. Full rebuild per solve; no engine
+  state persists between requests.
+- `src/opendss_designer/core/importer.py` — imports `.dss` by compiling it with OpenDSS's
+  own parser and reading the model back out.
+
+See `FUTURE_IMPROVEMENTS.md` for the roadmap.

opendss_designer-0.1.0/README.md

@@ -0,0 +1,98 @@
+# OpenDSS Designer
+
+A free, open-source **graphical user interface (GUI) for
+[OpenDSS](https://www.epri.com/pages/sa/opendss)**, EPRI's distribution system
+simulator — built on [OpenDSSDirect.py](https://github.com/dss-extensions/OpenDSSDirect.py).
+Draw a substation-style one-line (single-line) diagram in your browser — the
+drawing **is** the circuit model — then run a power flow and see voltages,
+loading, and violations right on the diagram. Import existing `.dss` files,
+edit visually or in a spreadsheet view, and export runnable OpenDSS scripts.
+
+📖 **Documentation: [opendssdesigner.ryanmsparks.com](https://opendssdesigner.ryanmsparks.com)**
+
+![screenshot](docs/screenshot.png)
+
+## Features (v1)
+
+- **Click-and-place palette**: Source (Vsource), Busbar, 2-winding Transformer, Breaker/Switch, Load —
+  placement is sticky, so keep clicking to drop several; Esc to stop
+- **Drag-to-wire**: drag between terminals; choose **Wire** (ideal connection, merges buses) or
+  **Line** (a real OpenDSS Line with impedance and length). Illegal connections (busbar-to-busbar
+  wires, self-connections, duplicates) are refused with an explanation
+- **Stretchable busbars** with connection points along both edges (top and bottom rows), plus
+  implicit junction buses when you wire elements directly together
+- **Double-click a breaker** to open/close it; **double-click a wire or line** to add a draggable
+  routing point and shape the run yourself (double-click a point to remove it)
+- **Properties panel** with the OpenDSS parameters for each element (kV, kVA, impedances,
+  phases 1/2/3, wye/delta, load model…)
+- **Solve** button → snapshot power flow → overlays on the diagram:
+  bus voltages (pu), element loading as pie charts + %, power flows, with color-coded
+  violations (undervoltage blue, overvoltage/overload red) and total losses in the
+  status bar — or toggle **Auto** to re-solve automatically on every circuit change
+- **Live validation**: unconnected terminals, missing source, islands, duplicate names,
+  kV mismatches — errors disable Solve and halo the offending element
+- **Spreadsheet view**: an Elements tab in the bottom panel lists every source, busbar,
+  transformer, line, breaker, and load in an editable table (plus a read-only bus-results
+  table after a solve) — edit values in bulk with an Excel-style fill-down handle,
+  click ⌖ to locate an element on the diagram
+- **Undo/redo** (Ctrl+Z / Ctrl+Y), delete key, grid snapping, pan/zoom, minimap
+- **Save/Open** projects as JSON; **Export** a runnable `.dss` file;
+  **Import** existing `.dss` files (select the main file plus anything it redirects to)
+  with a hierarchical auto-layout — source at top, loads beneath their buses
+
+## Install & run
+
+Requires Python 3.10+.
+
+```bash
+pip install opendss-designer
+opendss-designer            # starts a local server and opens your browser
+```
+
+(Or from a clone of this repo: `pip install -e .` — see Development below for
+building the frontend.)
+
+Options: `--port 8721`, `--no-browser`.
+
+Try it: **Open** `examples/demo-substation.oneline.json`, press **Solve**.
+
+## Development
+
+Backend (FastAPI + OpenDSSDirect.py):
+
+```bash
+pip install -e .[dev]
+pytest                      # backend test suite
+PYTHONPATH=src python -m opendss_designer.cli --no-browser   # serve API + built frontend
+```
+
+Frontend (React + Vite + React Flow), in a second terminal:
+
+```bash
+cd frontend
+npm install
+npm run dev                 # http://localhost:5173, proxies /api to :8721
+```
+
+To bundle the frontend into the Python package (before building a wheel):
+
+```bash
+python scripts/build_frontend.py
+```
+
+### Architecture
+
+- `frontend/` — React + Vite app. React Flow canvas with custom ANSI-symbol nodes;
+  zustand store is the canonical circuit model (zundo for undo history).
+  `window.opendssDesigner` exposes the stores for console scripting.
+- `src/opendss_designer/core/connectivity.py` — union-find translation of the drawn graph
+  into OpenDSS bus names (wires merge terminals; Line edges are series elements).
+- `src/opendss_designer/core/compiler.py` — circuit JSON → ordered OpenDSS Text commands;
+  the same commands back both `/api/solve` and `.dss` export.
+- `src/opendss_designer/core/engine.py` — solves and extracts per-bus voltages and
+  per-element loading through the OpenDSSDirect API. Full rebuild per solve; no engine
+  state persists between requests.
+- `src/opendss_designer/core/importer.py` — imports `.dss` by compiling it with OpenDSS's
+  own parser and reading the model back out.
+
+See `FUTURE_IMPROVEMENTS.md` for the roadmap.

opendss_designer-0.1.0/config/linecodes.csv

@@ -0,0 +1,26 @@
+# OpenDSS Designer - line conductor preset library
+#
+# Each row becomes a "Conductor preset" option on Line elements. Edit freely
+# (add, remove, or tune rows); the server re-reads this file on every request,
+# so changes appear after a browser refresh - no rebuild or restart needed.
+#
+# Columns:
+#   code     - short unique id (stored on the line as a reference tag)
+#   label    - text shown in the preset dropdown
+#   units    - length unit for the impedances (km, m, mi, kft, ft)
+#   r1,x1    - positive-sequence resistance/reactance, ohms per unit length
+#   r0,x0    - zero-sequence resistance/reactance, ohms per unit length
+#   normamps - normal ampacity rating, amps
+#
+# Values shipped here are REPRESENTATIVE of typical distribution construction
+# (overhead: flat crossarm spacing; UG: 3-1/c XLPE, trefoil). Replace with
+# your utility's data for real studies.
+code,label,units,r1,x1,r0,x0,normamps
+acsr-1/0,OH ACSR 1/0 (Raven),km,0.696,0.494,0.874,1.482,230
+acsr-4/0,OH ACSR 4/0 (Penguin),km,0.35,0.468,0.528,1.456,340
+acsr-336,OH ACSR 336.4 (Linnet),km,0.19,0.451,0.368,1.439,530
+acsr-556,OH ACSR 556.5 (Dove),km,0.118,0.427,0.296,1.415,730
+acsr-795,OH ACSR 795 (Drake),km,0.084,0.412,0.262,1.4,900
+ug-1/0-al,UG XLPE 1/0 Al,km,0.552,0.156,1.06,0.52,175
+ug-4/0-al,UG XLPE 4/0 Al,km,0.277,0.14,0.6,0.44,260
+ug-750-al,UG XLPE 750 Al,km,0.081,0.122,0.28,0.35,475

opendss_designer-0.1.0/docs/adding-an-element.md

@@ -0,0 +1,54 @@
+# Adding a new element type
+
+Checklist for adding a component to the palette (as done for `capacitor` and
+`generator` in M3 — diff those commits for a worked example). Items marked ⚡
+break loudly if forgotten (schema-drift tests); the rest fail quietly, so walk
+the whole list.
+
+## Backend (`src/opendss_designer/`)
+
+1. ⚡ `core/model.py` — add the type to the `NodeType` literal and its handles
+   to `NODE_TERMINALS` (skip `NODE_TERMINALS` only for dynamic-handle nodes
+   like busbar).
+2. `core/compiler.py` — emission block in `compile_circuit`: filter nodes by
+   type, build the `new <class>.<name> ...` command via `element_name()` (which
+   registers the element_map entry for results/issue mapping), use
+   `conn.node_buses[n.id]` + `_bus_suffix` for bus connections, and
+   `kv_bases.add()` any rated kV.
+3. `core/importer.py` — add the OpenDSS class prefix to `SUPPORTED_PREFIXES`
+   and a read-back block in `_read_model_back` (iterate `dss.<Class>.First()/
+   Next()`, preserve `busNodes` suffixes, `wire()` terminals to `busbar_for()`).
+4. `core/validate.py` — extend the kV-consistency check if the element declares
+   a voltage; add any element-specific structural checks.
+
+## Frontend (`frontend/src/`)
+
+5. ⚡ `types/circuit.ts` — add to the `NodeType` union (mirror of model.py).
+6. `lib/defaults.ts` — `defaultParams()` case (name prefix + sensible params)
+   and `NODE_SIZE` entry.
+7. `lib/fields.tsx` — `FIELDS` entry; drives both the properties panel and the
+   spreadsheet tab.
+8. `components/nodes/<X>Node.tsx` — symbol component: use `useSymbolRotation`,
+   `rotatedBox`, `SymbolSvg`, `rotatePosition` from `nodes/common.tsx` so
+   rotation works; add `VoltageBadge` (bus-connected) or `ElementBadge`
+   (series/shunt with element results).
+9. `components/EditorCanvas.tsx` — register in `nodeTypes` and add a letter to
+   `PLACE_KEYS`.
+10. `components/Palette.tsx` — palette item with icon + the same `kbd` letter.
+11. `lib/layout.ts` — if it's a 1-terminal shunt device, add it to
+    `SHUNT_TYPES` so imports hang it under its busbar; 2-terminal series
+    devices need `orientedEdges` / `alignDevicesBetweenBuses` handling.
+12. `store/circuitStore.ts` — add the name prefix to `NAME_PREFIX`
+    (copy/paste renaming).
+
+## Tests
+
+13. ⚡ `tests/fixtures/full-circuit.oneline.json` — add a wired, solvable
+    instance of the element. `test_schema_fixture.py::
+    test_fixture_covers_every_type` fails until you do; the same fixture
+    drives the frontend round-trip test and the e2e solve test.
+14. `tests/test_schema_fixture.py` — add the expected `new <class>.<name>`
+    fragment to `test_fixture_compiles_cleanly`.
+15. `tests/test_import_roundtrip.py` — extend the round-trip coverage.
+
+Then: `pytest`, `npm test`, `npm run e2e`, and update `FUTURE_IMPROVEMENTS.md`.