Skip to content

Commit 938d44e

Browse files
BrainInBlackBrainInBlack
committed
Initial commit
0 parents  commit 938d44e

91 files changed

Lines changed: 14553 additions & 0 deletions

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎.editorconfig‎

Lines changed: 18 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,18 @@
1+
root = true
2+
3+
[*]
4+
charset = utf-8
5+
end_of_line = lf
6+
insert_final_newline = true
7+
trim_trailing_whitespace = true
8+
indent_style = space
9+
indent_size = 2
10+
11+
[*.md]
12+
trim_trailing_whitespace = false
13+
14+
[*.{sh,bash}]
15+
indent_size = 2
16+
17+
[Makefile]
18+
indent_style = tab

‎.gitattributes‎

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,10 @@
1+
# Normalize line endings: LF in the repo, auto-converted on checkout.
2+
* text=auto eol=lf
3+
4+
# Binary assets — never touch these.
5+
*.png binary
6+
*.jpg binary
7+
*.ico binary
8+
9+
# Keep generated/vendored files out of diffs and language stats.
10+
package-lock.json -diff linguist-generated

‎.github/CODE_OF_CONDUCT.md‎

Lines changed: 133 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,133 @@
1+
# Contributor Covenant Code of Conduct
2+
3+
## Our Pledge
4+
5+
We as members, contributors, and leaders pledge to make participation in our
6+
community a harassment-free experience for everyone, regardless of age, body
7+
size, visible or invisible disability, ethnicity, sex characteristics, gender
8+
identity and expression, level of experience, education, socio-economic status,
9+
nationality, personal appearance, race, caste, color, religion, or sexual
10+
identity and orientation.
11+
12+
We pledge to act and interact in ways that contribute to an open, welcoming,
13+
diverse, inclusive, and healthy community.
14+
15+
## Our Standards
16+
17+
Examples of behavior that contributes to a positive environment for our
18+
community include:
19+
20+
- Demonstrating empathy and kindness toward other people
21+
- Being respectful of differing opinions, viewpoints, and experiences
22+
- Giving and gracefully accepting constructive feedback
23+
- Accepting responsibility and apologizing to those affected by our mistakes,
24+
and learning from the experience
25+
- Focusing on what is best not just for us as individuals, but for the overall
26+
community
27+
28+
Examples of unacceptable behavior include:
29+
30+
- The use of sexualized language or imagery, and sexual attention or advances of
31+
any kind
32+
- Trolling, insulting or derogatory comments, and personal or political attacks
33+
- Public or private harassment
34+
- Publishing others' private information, such as a physical or email address,
35+
without their explicit permission
36+
- Other conduct which could reasonably be considered inappropriate in a
37+
professional setting
38+
39+
## Enforcement Responsibilities
40+
41+
Community leaders are responsible for clarifying and enforcing our standards of
42+
acceptable behavior and will take appropriate and fair corrective action in
43+
response to any behavior that they deem inappropriate, threatening, offensive,
44+
or harmful.
45+
46+
Community leaders have the right and responsibility to remove, edit, or reject
47+
comments, commits, code, wiki edits, issues, and other contributions that are
48+
not aligned to this Code of Conduct, and will communicate reasons for moderation
49+
decisions when appropriate.
50+
51+
## Scope
52+
53+
This Code of Conduct applies within all community spaces, and also applies when
54+
an individual is officially representing the community in public spaces.
55+
Examples of representing our community include using an official email address,
56+
posting via an official social media account, or acting as an appointed
57+
representative at an online or offline event.
58+
59+
## Enforcement
60+
61+
Instances of abusive, harassing, or otherwise unacceptable behavior may be
62+
reported to the community leaders responsible for enforcement at
63+
**braininblack@gmail.com**.
64+
65+
All complaints will be reviewed and investigated promptly and fairly.
66+
67+
All community leaders are obligated to respect the privacy and security of the
68+
reporter of any incident.
69+
70+
## Enforcement Guidelines
71+
72+
Community leaders will follow these Community Impact Guidelines in determining
73+
the consequences for any action they deem in violation of this Code of Conduct:
74+
75+
### 1. Correction
76+
77+
**Community Impact**: Use of inappropriate language or other behavior deemed
78+
unprofessional or unwelcome in the community.
79+
80+
**Consequence**: A private, written warning from community leaders, providing
81+
clarity around the nature of the violation and an explanation of why the
82+
behavior was inappropriate. A public apology may be requested.
83+
84+
### 2. Warning
85+
86+
**Community Impact**: A violation through a single incident or series of
87+
actions.
88+
89+
**Consequence**: A warning with consequences for continued behavior. No
90+
interaction with the people involved, including unsolicited interaction with
91+
those enforcing the Code of Conduct, for a specified period of time. This
92+
includes avoiding interactions in community spaces as well as external channels
93+
like social media. Violating these terms may lead to a temporary or permanent
94+
ban.
95+
96+
### 3. Temporary Ban
97+
98+
**Community Impact**: A serious violation of community standards, including
99+
sustained inappropriate behavior.
100+
101+
**Consequence**: A temporary ban from any sort of interaction or public
102+
communication with the community for a specified period of time. No public or
103+
private interaction with the people involved, including unsolicited interaction
104+
with those enforcing the Code of Conduct, is allowed during this period.
105+
Violating these terms may lead to a permanent ban.
106+
107+
### 4. Permanent Ban
108+
109+
**Community Impact**: Demonstrating a pattern of violation of community
110+
standards, including sustained inappropriate behavior, harassment of an
111+
individual, or aggression toward or disparagement of classes of individuals.
112+
113+
**Consequence**: A permanent ban from any sort of public interaction within the
114+
community.
115+
116+
## Attribution
117+
118+
This Code of Conduct is adapted from the [Contributor Covenant][homepage],
119+
version 2.1, available at
120+
[https://www.contributor-covenant.org/version/2/1/code_of_conduct.html][v2.1].
121+
122+
Community Impact Guidelines were inspired by
123+
[Mozilla's code of conduct enforcement ladder][mozilla].
124+
125+
For answers to common questions about this code of conduct, see the FAQ at
126+
[https://www.contributor-covenant.org/faq][faq]. Translations are available at
127+
[https://www.contributor-covenant.org/translations][translations].
128+
129+
[homepage]: https://www.contributor-covenant.org
130+
[v2.1]: https://www.contributor-covenant.org/version/2/1/code_of_conduct.html
131+
[mozilla]: https://github.com/mozilla/diversity
132+
[faq]: https://www.contributor-covenant.org/faq
133+
[translations]: https://www.contributor-covenant.org/translations

‎.github/CONTRIBUTING.md‎

Lines changed: 109 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,109 @@
1+
# Contributing to NetGraph
2+
3+
NetGraph is a vanilla-TypeScript single-page app — no framework. It's built with
4+
[Vite](https://vitejs.dev/), styled with SCSS, and stores everything in the
5+
browser's `localStorage`; there's no backend. State lives in module-scope
6+
variables and the DOM is the renderer.
7+
8+
This file covers building and developing NetGraph. For end-user instructions,
9+
see [README.md](../README.md). For the full architecture and conventions, see
10+
[docs/ARCHITECTURE.md](../docs/ARCHITECTURE.md).
11+
12+
## Prerequisites
13+
14+
- [Node.js](https://nodejs.org/) 18 or newer.
15+
16+
Node is only needed to **build or develop** NetGraph — not to run a built copy.
17+
The output is plain static files (and a single self-contained HTML file) that
18+
run in any modern browser.
19+
20+
## Setup
21+
22+
```sh
23+
npm install
24+
```
25+
26+
`lucide-static` and `sass` are required peer dependencies; both are pinned in
27+
`package.json`.
28+
29+
## Development
30+
31+
```sh
32+
npm run dev # Vite dev server at http://localhost:5173 with hot reload
33+
```
34+
35+
> If you commit a change that deletes or renames a module, restart `npm run dev`
36+
> — Vite's HMR can't always reconcile a moved module graph and the page may go
37+
> blank until a fresh start. It's not a code bug; `tsc` and the tests stay green.
38+
39+
## Building
40+
41+
```sh
42+
npm run build # type-check, then build BOTH outputs
43+
npm run build:web # multi-file build only → dist/
44+
npm run build:single # single-file build only → dist/download/netgraph.html
45+
npm run preview # serve the production build locally
46+
```
47+
48+
There are two build outputs:
49+
50+
- A **multi-file build** for hosting on a webserver (split JS/CSS for caching).
51+
- A **single self-contained `netgraph.html`** with JS, CSS, and the favicon all
52+
inlined — one file to move around, run from disk, or put on a USB stick.
53+
54+
```
55+
dist/
56+
├── index.html ← multi-file build (serve this from a webserver)
57+
├── assets/ ← JS, CSS, favicon
58+
└── download/
59+
└── netgraph.html ← single-file standalone build
60+
```
61+
62+
## Tests & quality bar
63+
64+
```sh
65+
npm test # vitest, single pass
66+
npm run test:watch # vitest in watch mode
67+
npx tsc --noEmit # type-check
68+
```
69+
70+
The bar for any change is a **clean `npx tsc --noEmit`** and **passing
71+
`npm test`**. There's no separate linter — `tsconfig.json` runs with `strict`,
72+
`noUnusedLocals`, `noUnusedParameters`, and `noFallthroughCasesInSwitch`, so the
73+
compiler is the linter.
74+
75+
Tests run on vitest with the happy-dom environment; test files are
76+
`src/**/*.test.ts`. Coverage focuses on the pure / pure-ish modules
77+
(`parse-shapes`, `svg-sanitizer`, `path-geometry`, `collision`, `route`,
78+
`import-export`, `storage`, `graph/layout`, and the `util` helpers). DOM- and
79+
pointer-heavy code (renderer, zoom, connect-mode, UI) is verified by hand rather
80+
than unit-tested.
81+
82+
## Project layout
83+
84+
Single entry point at `src/ts/main.ts`. The detailed map — state flow, the
85+
render pipeline, connection routing, and the data-validation / SVG-sanitizer
86+
security model — lives in [docs/ARCHITECTURE.md](../docs/ARCHITECTURE.md). Start there before changing
87+
routing, persistence, or anything that ingests untrusted data (imports, custom
88+
icons).
89+
90+
## Branches & pull requests
91+
92+
The repo has two long-lived branches:
93+
94+
- `main` — stable releases
95+
- `develop` — active development
96+
97+
Create your own branch for your work, then open a pull request into `develop`
98+
(or `main` for an urgent fix). Before you open it:
99+
100+
- `npx tsc --noEmit` is clean and `npm test` passes,
101+
- `npm run build` succeeds (both the multi-file and single-file outputs),
102+
- you've added a note under `## [Unreleased]` in [CHANGELOG.md](../CHANGELOG.md).
103+
104+
The [pull request template](PULL_REQUEST_TEMPLATE.md) has the full checklist.
105+
106+
## License
107+
108+
By contributing you agree your contributions are licensed under
109+
[PolyForm Noncommercial 1.0.0](../LICENSE).

‎.github/FUNDING.yml‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,4 @@
1+
# Drives the "Sponsor" button on the NetGraph repo.
2+
ko_fi: braininblack
3+
patreon: braininblack
4+
# custom: ["https://netgraph.khemul.de"]

‎.github/ISSUE_TEMPLATE/bug_report.yml‎

Lines changed: 92 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,92 @@
1+
name: Bug report
2+
description: Something in NetGraph doesn't work as expected.
3+
labels: ["bug"]
4+
body:
5+
- type: markdown
6+
attributes:
7+
value: |
8+
Thanks for taking the time to file a bug. Please don't report security
9+
issues here — see the [security policy](../blob/main/.github/SECURITY.md)
10+
for private reporting.
11+
12+
NetGraph stores everything in your browser's `localStorage`. If the app
13+
won't load at all, a corrupt saved state is a common cause — exporting a
14+
bundle (map dropdown → Export) before you try anything destructive is a
15+
good idea.
16+
- type: textarea
17+
id: what-happened
18+
attributes:
19+
label: What happened?
20+
description: What did you do, what did you expect, and what happened instead?
21+
placeholder: |
22+
I dragged a device onto another card and ...
23+
I expected ... but ...
24+
validations:
25+
required: true
26+
- type: textarea
27+
id: repro
28+
attributes:
29+
label: Steps to reproduce
30+
description: The exact steps to trigger it, starting from a fresh load if you can.
31+
placeholder: |
32+
1. Add two devices
33+
2. Connect them
34+
3. Drag one on top of the other
35+
4. ...
36+
validations:
37+
required: true
38+
- type: input
39+
id: version
40+
attributes:
41+
label: NetGraph version
42+
description: Shown next to the wordmark in the top-left corner.
43+
placeholder: "1.3.0"
44+
validations:
45+
required: true
46+
- type: dropdown
47+
id: build
48+
attributes:
49+
label: Which build are you running?
50+
options:
51+
- Hosted (netgraph.khemul.de)
52+
- Self-hosted (multi-file build)
53+
- Offline single-file copy (netgraph.html)
54+
- Local dev (npm run dev)
55+
validations:
56+
required: true
57+
- type: input
58+
id: browser
59+
attributes:
60+
label: Browser & version
61+
description: e.g. "Firefox 142", "Chrome 141", "Safari 18".
62+
placeholder: "Chrome 141"
63+
validations:
64+
required: true
65+
- type: dropdown
66+
id: platform
67+
attributes:
68+
label: Operating system
69+
options:
70+
- Linux
71+
- macOS
72+
- Windows
73+
- iOS / iPadOS
74+
- Android
75+
- Other
76+
validations:
77+
required: true
78+
- type: textarea
79+
id: console
80+
attributes:
81+
label: Console output
82+
description: Open the browser devtools console (F12) and paste any errors or warnings.
83+
render: shell
84+
- type: checkboxes
85+
id: checks
86+
attributes:
87+
label: Before submitting
88+
options:
89+
- label: I searched existing issues and this isn't a duplicate.
90+
required: true
91+
- label: This is not a security vulnerability (those go through the security policy).
92+
required: true

‎.github/ISSUE_TEMPLATE/config.yml‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,8 @@
1+
blank_issues_enabled: false
2+
contact_links:
3+
- name: Report a security vulnerability
4+
url: https://github.com/BrainInBlack/NetGraph/security/advisories/new
5+
about: Please report security issues privately, not as public issues. See the security policy.
6+
- name: Question or usage help
7+
url: https://github.com/BrainInBlack/NetGraph/discussions
8+
about: For questions and general discussion, use Discussions instead of an issue.

0 commit comments

Comments
 (0)