Skip to content

Commit eeba2f6

Browse files
loumalouomegaloumalouomega
committed
Add Playwright configuration and screenshot capture tests for documentation
- Created a Playwright configuration file to set up testing environment for capturing documentation screenshots. - Implemented screenshot capture tests for various scenarios in the litegraph editor, including: - Empty editor view - Context menu for adding nodes - Constitutive law material node - Connected graph representation - JSON side viewer functionality
1 parent fb32a08 commit eeba2f6

34 files changed

Lines changed: 1698 additions & 34 deletions

‎.github/workflows/docs.yml‎

Lines changed: 59 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,59 @@
1+
name: Deploy Docs
2+
3+
# Builds the VitePress documentation and deploys it to GitHub Pages on every
4+
# push to master. Screenshots are committed to the repository, so this build
5+
# never needs to launch the application.
6+
#
7+
# One-time setup: enable GitHub Pages with the "GitHub Actions" source under
8+
# Settings -> Pages.
9+
on:
10+
push:
11+
branches: [master]
12+
workflow_dispatch:
13+
14+
# Allow only one concurrent deployment.
15+
concurrency:
16+
group: pages
17+
cancel-in-progress: false
18+
19+
permissions:
20+
contents: read
21+
pages: write
22+
id-token: write
23+
24+
jobs:
25+
build:
26+
runs-on: ubuntu-latest
27+
steps:
28+
- name: Checkout
29+
uses: actions/checkout@v4
30+
31+
- name: Setup Node.js
32+
uses: actions/setup-node@v4
33+
with:
34+
node-version: 20
35+
36+
- name: Install dependencies
37+
run: npm install
38+
39+
- name: Build docs
40+
run: npm run docs:build
41+
42+
- name: Setup Pages
43+
uses: actions/configure-pages@v5
44+
45+
- name: Upload artifact
46+
uses: actions/upload-pages-artifact@v3
47+
with:
48+
path: doc/.vitepress/dist
49+
50+
deploy:
51+
needs: build
52+
runs-on: ubuntu-latest
53+
environment:
54+
name: github-pages
55+
url: ${{ steps.deployment.outputs.page_url }}
56+
steps:
57+
- name: Deploy to GitHub Pages
58+
id: deployment
59+
uses: actions/deploy-pages@v4

‎.github/workflows/publish.yml‎

Lines changed: 32 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,32 @@
1+
name: Publish to NPM
2+
3+
# Publishes the `kratos-flowgraph` package to the NPM registry whenever a
4+
# GitHub Release is published. Bump the `version` field in package.json and
5+
# create a Release (with a tag such as `v1.2.3`) to trigger a publish.
6+
on:
7+
release:
8+
types: [published]
9+
10+
jobs:
11+
publish:
12+
runs-on: ubuntu-latest
13+
permissions:
14+
contents: read
15+
id-token: write # required for npm provenance
16+
steps:
17+
- name: Checkout
18+
uses: actions/checkout@v4
19+
20+
- name: Setup Node.js
21+
uses: actions/setup-node@v4
22+
with:
23+
node-version: 20
24+
registry-url: 'https://registry.npmjs.org'
25+
26+
- name: Install dependencies
27+
run: npm install
28+
29+
- name: Publish package
30+
run: npm publish --provenance --access public
31+
env:
32+
NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}

‎.gitignore‎

Lines changed: 11 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,13 @@
11
node_modules
22
package-lock.json
3-
simulations/*
3+
simulations/*
4+
5+
# Playwright
6+
test-results
7+
playwright-report
8+
blob-report
9+
.cache
10+
11+
# VitePress
12+
doc/.vitepress/cache
13+
doc/.vitepress/dist

‎CLAUDE.md‎

Lines changed: 100 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,100 @@
1+
# CLAUDE.md
2+
3+
Guidance for Claude Code (and other AI assistants) working in this repository.
4+
5+
## Project overview
6+
7+
**Kratos FlowGraph** is a browser-based, node-graph editor for configuring
8+
[KratosMultiphysics](https://github.com/KratosMultiphysics/Kratos) simulations. Users wire nodes
9+
(analysis stages, solvers, materials, processes, model parts, outputs) on a canvas, and FlowGraph
10+
generates the Kratos `ProjectParameters.json` (and material files).
11+
12+
It is **not** a bundled SPA. It is:
13+
14+
- a small **Express + EJS** server (`app.js`) that serves a single canvas page and optionally
15+
launches Kratos, plus
16+
- a large library of plain-ESM **[litegraph.js](https://github.com/jagenjo/litegraph.js)** node
17+
modules served statically from `public/js/nodes/`.
18+
19+
There is **no build step** for the application itself. The published NPM package is
20+
`kratos-flowgraph`, exposed as a runnable CLI.
21+
22+
## Run / develop
23+
24+
```sh
25+
npm install
26+
npm start # node app.js — serves the editor on http://localhost:8182
27+
npm run devstart # nodemon app.js — auto-reload during development
28+
```
29+
30+
- Port and Kratos paths come from `config/default.json` (via the `config` package). Switch config
31+
files with `NODE_ENV` (e.g. `NODE_ENV=debug` → `config/debug.json`).
32+
- The CLI entry point is `bin/kratos-flowgraph.js`; it `chdir`s to the package root (so
33+
CWD-relative lookups in `src/module_importer.js` and `config` work) and then imports `app.js`.
34+
- The editor UI needs **no Kratos install**; `kratos_root` / `working_dir` / `python_binary` are
35+
only used by the optional `/run_simulation` route.
36+
37+
## Architecture map
38+
39+
| Path | Role |
40+
| --- | --- |
41+
| `app.js` | Express server: serves `public/`, renders `views/index.ejs`, routes `/upload_json`, `/run_simulation`. |
42+
| `bin/kratos-flowgraph.js` | CLI launcher (chdir to package root, then run app). |
43+
| `src/module_importer.js` | Auto-discovers node/widget files under `public/js/nodes` & `public/js/widgets`. |
44+
| `views/index.ejs` | The entire UI: toolbar, `<canvas class="graphcanvas">`, JSON side panel. |
45+
| `public/js/code.js` | Bootstraps the litegraph editor; wires the toolbar; exposes `window.graph`/`window.graphcanvas`. |
46+
| `public/js/side.js` | Side panel toggle (`openNav`), `addViewerNode`, experimental LLM hook. |
47+
| `public/js/litegraph/litegraph.core.js` | Vendored litegraph engine. |
48+
| `public/js/extensions/*.js` | Core customisations: `extended_menu` (categorized add-node menu), `draw_node`/`draw_widget`, `compute_size`, `remove_node`/`remove_widget`, `custom_node_panel`, `selection_import`, `load_project_parameters` (import ProjectParameters → graph). |
49+
| `public/js/nodes/**` | The node library, organized by Kratos domain (see the docs Node Reference). |
50+
| `public/js/model_manager.js`, `problem_manager.js` | Track model parts / global problem state across connections. |
51+
| `config/default.json` | Runtime config (host, port, kratos_root, working_dir, python_binary). |
52+
| `doc/` | VitePress documentation (see below). |
53+
| `scripts/screenshots/capture.spec.js` | Playwright screenshot capture for the docs. |
54+
55+
## Adding a node
56+
57+
Drop a `.js` file under `public/js/nodes/<category>/` that defines a class and calls
58+
`LiteGraph.registerNodeType("Category/Sub/Name", Class)`. It is **auto-discovered** — no manifest to
59+
edit. The registered type path drives the context-menu category. Reuse existing slot types so the
60+
node connects to the rest of the library. See `doc/development/adding-a-node.md` for a template.
61+
62+
## Documentation & screenshots
63+
64+
The docs live in `doc/` (VitePress) with screenshots under `doc/public/screenshots/`.
65+
66+
```sh
67+
npm run docs:dev # local docs dev server
68+
npm run docs:build # build static docs into doc/.vitepress/dist
69+
npm run docs:screenshots # Playwright: boot the app, capture UI screenshots (needs `npx playwright install chromium` once)
70+
```
71+
72+
## Publishing
73+
74+
- **NPM**: bump `version` in `package.json`, push, then create a **GitHub Release**. The
75+
`.github/workflows/publish.yml` workflow publishes `kratos-flowgraph` using the `NPM_TOKEN` secret.
76+
Verify the tarball with `npm pack --dry-run`.
77+
- **Docs**: pushing to `master` triggers `.github/workflows/docs.yml`, which builds and deploys the
78+
VitePress site to GitHub Pages (requires Pages source = "GitHub Actions", one-time).
79+
80+
## ⚠️ Mandatory documentation sync clause
81+
82+
> **Whenever a new feature, node, or user-facing change is added, you MUST update `CLAUDE.md`,
83+
> `README.md`, and the `doc/` VitePress documentation in the same change. If the change alters the
84+
> UI, regenerate the Playwright screenshots with `npm run docs:screenshots`. A feature is NOT
85+
> complete until these are updated.**
86+
87+
Concretely, when you change behaviour:
88+
89+
1. Update `CLAUDE.md` if the architecture, commands or workflow changed.
90+
2. Update `README.md` if the quick-start, features or install steps changed.
91+
3. Update the relevant page(s) under `doc/` (guide, node reference, or development).
92+
4. Re-run `npm run docs:screenshots` if the UI changed, and commit the updated images.
93+
94+
## Conventions & notes
95+
96+
- Node names, slot types and emitted JSON should match the Kratos schema for the concept modelled.
97+
- Runtime dependencies (`express`, `cors`, `ejs`, `config`) live under `dependencies` — do **not**
98+
move them back to `devDependencies`, or the published CLI will not run.
99+
- `package-lock.json` is gitignored; there is no committed lockfile.
100+
- Prefer extending existing base classes (`Material`, `AnalysisStage`, `Process`, …) for new nodes.

‎README.md‎

Lines changed: 103 additions & 29 deletions
Original file line numberDiff line numberDiff line change
@@ -1,56 +1,130 @@
1-
# FlowGraph
1+
# Kratos FlowGraph
22

3-
A node editor for Kratos Problemtypes
3+
[![npm version](https://img.shields.io/npm/v/kratos-flowgraph.svg)](https://www.npmjs.com/package/kratos-flowgraph)
4+
[![npm downloads](https://img.shields.io/npm/dm/kratos-flowgraph.svg)](https://www.npmjs.com/package/kratos-flowgraph)
5+
[![Publish to NPM](https://github.com/KratosMultiphysics/Flowgraph/actions/workflows/publish.yml/badge.svg)](https://github.com/KratosMultiphysics/Flowgraph/actions/workflows/publish.yml)
6+
[![Deploy Docs](https://github.com/KratosMultiphysics/Flowgraph/actions/workflows/docs.yml/badge.svg)](https://github.com/KratosMultiphysics/Flowgraph/actions/workflows/docs.yml)
7+
[![Documentation](https://img.shields.io/badge/docs-vitepress-42b883.svg)](https://kratosmultiphysics.github.io/Flowgraph/)
8+
[![License: AGPL-3.0-or-later](https://img.shields.io/badge/license-AGPL--3.0--or--later-blue.svg)](LICENSE)
9+
[![Node.js](https://img.shields.io/badge/node-%3E%3D18-brightgreen.svg)](https://nodejs.org/)
10+
11+
**A visual node editor for configuring [KratosMultiphysics](https://github.com/KratosMultiphysics/Kratos) simulations.**
12+
13+
Instead of authoring a Kratos `ProjectParameters.json` by hand, you wire together nodes — analysis
14+
stages, solvers, materials, processes, model parts and outputs — on a canvas, and FlowGraph
15+
generates the JSON (and material files) for you.
16+
17+
![The Kratos FlowGraph editor](doc/public/screenshots/connected-graph.png)
18+
19+
## Quick start
20+
21+
Run the editor without installing anything:
22+
23+
```sh
24+
npx kratos-flowgraph
25+
```
26+
27+
Then open **<http://localhost:8182>** in your browser.
28+
29+
> 📖 **Full documentation:** <https://kratosmultiphysics.github.io/Flowgraph/>
30+
31+
## Features
32+
33+
- 🧩 **Visual, node-based configuration** — build a Kratos case by connecting nodes; the graph *is*
34+
the configuration.
35+
- ⚙️ **Rich Kratos node library** (~85 node types) — analysis stages & orchestrators, fluid /
36+
structural / thermal / potential-flow solvers, serial & MPI linear solvers, constitutive laws
37+
(elastic, plasticity, damage), boundary-condition processes, modelers and output processes.
38+
- 🔁 **Round-trip** — import an existing `ProjectParameters.json` and FlowGraph reconstructs the
39+
graph, or export the current graph as a zipped, ready-to-run case.
40+
- 🖥️ **Live JSON viewer** — inspect the generated JSON as you build.
41+
- 🚀 **No build step** — a small Node/Express server serves the editor; launch it with one command.
442

543
## Installation
6-
Install [node.js](https://nodejs.org/en/download/package-manager)
744

8-
Ej. Ubuntu
9-
```console
10-
sudo apt install nodejs npm
11-
```
45+
### Run instantly (recommended)
1246

13-
Clone this repo
47+
```sh
48+
npx kratos-flowgraph
49+
```
1450

15-
```console
16-
git clone https://github.com/KratosMultiphysics/Flowgraph.git
51+
### Global install
52+
53+
```sh
54+
npm install -g kratos-flowgraph
55+
kratos-flowgraph
1756
```
1857

19-
Navigate into the Flowgraph directory and install packages
58+
### From source
2059

21-
```console
60+
```sh
61+
git clone https://github.com/KratosMultiphysics/Flowgraph.git
2262
cd Flowgraph
2363
npm install
24-
sudo npm install -g nodemon
64+
npm start # node app.js
65+
# or
66+
npm run devstart # nodemon app.js (auto-reload)
2567
```
2668

27-
## How to run
69+
Requires **Node.js 18+**.
2870

29-
For users use either
71+
## Configuration
3072

31-
```console
32-
npm run start
73+
Configuration lives in `config/default.json` (via the [`config`](https://www.npmjs.com/package/config)
74+
package):
75+
76+
```json
77+
{
78+
"host" : "127.0.0.1",
79+
"port" : "8182",
80+
"kratos_root": "/path/to/Kratos/bin/Release",
81+
"working_dir": "/path/to/working_dir",
82+
"python_binary": "python3"
83+
}
3384
```
3485

35-
```console
36-
node app.js
37-
```
86+
Switch config files with `NODE_ENV`, e.g. `NODE_ENV=debug npm start` loads `config/debug.json`.
3887

39-
For developers
88+
> The editor UI needs **no Kratos installation**. `kratos_root`, `working_dir` and `python_binary`
89+
> are only used by the optional "run simulation" backend route.
4090
41-
```console
42-
npm run devstart
43-
```
91+
## Documentation
4492

45-
## Configuration
93+
The full documentation — installation, a getting-started walkthrough, the complete node reference,
94+
and developer/architecture guides — is published with VitePress at:
95+
96+
**<https://kratosmultiphysics.github.io/Flowgraph/>**
4697

47-
You can change the configuration file used by setting the `NODE_ENV` variable. For example
98+
The sources live in [`doc/`](doc/):
4899

49-
```console
50-
export NODE_ENV=debug
100+
```sh
101+
npm run docs:dev # local docs dev server
102+
npm run docs:build # build the static docs
103+
npm run docs:screenshots # regenerate UI screenshots with Playwright
51104
```
52105

53-
will use `confg/debug.json` configure file.
106+
## Contributing
107+
108+
Contributions are welcome! When adding a feature or node, please keep the documentation in sync —
109+
this is a project rule (see [CLAUDE.md](CLAUDE.md)):
110+
111+
> Whenever a new feature, node, or user-facing change is added, update **CLAUDE.md**, **README.md**
112+
> and the **`doc/`** documentation in the same change (and regenerate screenshots if the UI
113+
> changed). A feature is not complete until the docs reflect it.
114+
115+
Adding a node is easy: drop a `.js` file under `public/js/nodes/<category>/` that calls
116+
`LiteGraph.registerNodeType(...)` — it is auto-discovered. See
117+
[the developer guide](https://kratosmultiphysics.github.io/Flowgraph/development/adding-a-node).
118+
119+
## Publishing
120+
121+
Publishing to NPM is automated: bump `version` in `package.json` and create a **GitHub Release** —
122+
the [`publish.yml`](.github/workflows/publish.yml) workflow publishes `kratos-flowgraph` using the
123+
`NPM_TOKEN` secret. Docs deploy to GitHub Pages on every push to `master`.
124+
125+
## License
126+
127+
[AGPL-3.0-or-later](LICENSE).
54128

55129
<!-- ## Description
56130

‎bin/kratos-flowgraph.js‎

Lines changed: 24 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,24 @@
1+
#!/usr/bin/env node
2+
3+
/**
4+
* kratos-flowgraph CLI launcher.
5+
*
6+
* The application resolves several paths relative to the current working
7+
* directory:
8+
* - `src/module_importer.js` walks `./public/js/nodes` and
9+
* `./public/js/widgets` to auto-discover node/widget files.
10+
* - the `config` package reads configuration from `./config`.
11+
*
12+
* When the package is installed globally or run through `npx` from an
13+
* arbitrary directory, that CWD is not the package root, so those lookups
14+
* would fail. We therefore change into the package root before importing
15+
* the Express app.
16+
*/
17+
18+
import { fileURLToPath } from 'url';
19+
import path from 'path';
20+
21+
const packageRoot = path.dirname(path.dirname(fileURLToPath(import.meta.url)));
22+
process.chdir(packageRoot);
23+
24+
await import('../app.js');

‎doc/.gitignore‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
cache
2+
.vitepress/cache
3+
.vitepress/dist

0 commit comments

Comments
 (0)