Webui overhaul

.github/copilot-instructions.md

@@ -204,6 +204,79 @@ The repository runs these workflows:
 - Ensure all required JSON files exist at each hierarchy level
 - Use illegal character list: `#%&{}\\<>*?/$!'":@+\`|=` (see `ofd/validation/validators.py`)
 
+## WebUI Architecture Patterns
+
+### Entity Actions (Copy/Duplicate/Paste/Delete)
+
+All entity actions (copy, duplicate, paste, delete) are centralized through **shared composables** in `webui/src/lib/utils/useEntityActions.svelte.ts`. These ensure that both detail-page dropdowns AND list-view card menus go through the exact same code path.
+
+**Key composables:**
+- `createCopyAction(entityType, loadChildrenFn?)` - Handles copy with optional "with/without children" modal
+- `createDuplicateAction(entityType, hasChildren, openFormFn)` - Handles duplicate with optional children modal
+- `createPasteHandler(entityType, openFormFn, hasConflict?)` - Handles paste with conflict-aware name suffixing
+
+**Critical rule:** Never create inline copy/duplicate/paste handlers directly in page components. Always use these composables to avoid action inconsistencies between detail-page dropdowns and list-view card menus.
+
+**Clipboard service** (`webui/src/lib/services/clipboardService.ts`):
+- Uses localStorage as primary store, system clipboard as secondary
+- `ClipboardEntry` includes optional `children` field for nested data
+- `prepareDuplicateData()` clears identity fields and appends "(Copy)" to names
+- Uses `JSON.parse(JSON.stringify())` instead of `structuredClone` (Svelte 5 proxies can't be structuredCloned)
+
+**Duplicate service** (`webui/src/lib/services/duplicateService.ts`):
+- `loadXxxChildren()` - loads nested children into clipboard-compatible structure
+- `pasteXxxChildren()` - creates children from clipboard data under a new parent
+- `duplicateXxxChildren()` - duplicates children from one parent to another via DB
+
+### Schema Filtering & Supplementary Keys
+
+The change store (`webui/src/lib/stores/changes.ts`) filters entity data through JSON schemas via `filterToSchema()`. Fields not in the schema are stripped. For fields that are needed for change tracking but aren't in the schema (like `materialType` for materials, `sizes` for variants), add them to `SUPPLEMENTARY_KEYS`:
+
+```typescript
+const SUPPLEMENTARY_KEYS: Partial<Record<EntityType, string[]>> = {
+    variant: ['sizes'],
+    material: ['id', 'materialType']
+};
+```
+
+**Warning:** If you add a field to entity data that needs to survive change tracking but isn't in the JSON schema, you MUST add it to `SUPPLEMENTARY_KEYS` or it will be silently stripped.
+
+### Submitted Changes Buffer (Pending Merge)
+
+When a user submits changes (creating a PR), the changes are archived into a **submitted buffer** (`webui/src/lib/stores/submitted.ts`) before being cleared from the pending change store. This keeps submitted entities visible in the UI with a purple "Submitted" badge until the buffer entries expire (7-day TTL).
+
+**Key files:**
+- `webui/src/lib/stores/submitted.ts` - Submitted store (localStorage-backed, key `ofd_submitted_changes`)
+- `webui/src/lib/types/changes.ts` - `SubmittedEntry` and `SubmittedBuffer` types
+
+**Data layering precedence:** pending changes > submitted changes > API data. The `DatabaseService` applies submitted changes via `layerSubmittedChanges()` before `layerChanges()`.
+
+**Visual indicators:** Submitted entities show `border-l-4 border-l-purple-500` border and a purple "Submitted" badge on EntityCards. Detail pages show a "Submitted - awaiting merge" info banner.
+
+**Integration points:** The `getChildChangeProps()` function in `deletedStubs.ts` accepts an optional `submitted` parameter. All list pages pass `submittedStore` to this function and to `withDeletedStubs()`. The `entityState` composable exposes `hasSubmittedChanges` for detail pages.
+
+### Entity Detail Page Structure
+
+Each entity detail page follows this pattern:
+1. **Shared action composables** at the top (via `createCopyAction`, `createDuplicateAction`, `createPasteHandler`)
+2. **Data loading** via `$effect` watching route params
+3. **Edit/Delete/Duplicate/Paste handlers** as async functions
+4. **Template** with `EntityDetails` (showing fields + Edit button + `EntityActionDropdown`) and `ChildListPanel` (showing child cards with actions)
+5. **Modals** at the bottom: Edit, Delete, DuplicateOptions, CopyOptions, Duplicate form, Paste form, CloudCompare
+
+### UI Components
+
+- `DropdownMenu.svelte` - Reusable kebab dropdown (auto-strips empty separators)
+- `ContextMenu.svelte` - Right-click menu positioned at pointer
+- `EntityActionDropdown.svelte` - Entity-specific dropdown with Duplicate/Copy/Paste/View/Delete
+- `DuplicateOptionsModal.svelte` - "With children" / "Without children" / "Cancel" chooser
+- `CloudCompareModal.svelte` - Side-by-side JSON diff (cloud mode only)
+- `EntityCard.svelte` - Cards with inline dropdown + right-click context menu
+
+### Form Create vs Update Detection
+
+Forms determine their submit button label ("Create X" vs "Update X") by checking `entity?.id`. Since `prepareDuplicateData()` strips `id`, duplicate/paste forms correctly show "Create". If you add a new form, use `?.id` for this check, not just truthiness of the entity prop.
+
 ## Critical Configuration Files
 
 **Root Level:**
@@ -219,8 +292,8 @@ The repository runs these workflows:
 **WebUI Configuration:**
 - `webui/package.json` - npm scripts and dependencies
 - `webui/svelte.config.js` - SvelteKit configuration
-- `webui/vite.config.js` - Vite build configuration (Tailwind 4 is configured here via `@tailwindcss/vite`, no separate `tailwind.config.js`)
-- `webui/playwright.config.js` - Test configuration (baseURL: localhost:4173)
+- `webui/vite.config.ts` - Vite build configuration (Tailwind 4 is configured here via `@tailwindcss/vite`, no separate `tailwind.config.js`)
+- `webui/playwright.config.ts` - E2E test configuration (baseURL: localhost:4173)
 
 **Validation Schemas:**
 - `schemas/brand_schema.json` - Brand metadata validation

README.md

@@ -8,119 +8,63 @@
 </div>
 
 # Open Filament Database
-The Open Filament Database, hosted by the new "Open Filament Collective" group, currently facilitated by SimplyPrint.
-
-## ✅ Contributing: how to add to the database
-The beautiful thing about the database is that it's open source so anyone can contribute, whether you're a hobbyist, print farm or brand.
-
-The steps to contribute to the database are simple but may get technical at times depending on how you want to do it, don't worry if you don't all understand terms, we'll guide you through it.
-
-### So what are the steps?
-1. **Create a GitHub account**
-2. **Create a copy of the database** (called "forking" this repository)
-3. **Install a few small applications** (Git, Python, Node.js)
-4. **Download your copy of the database** (called "cloning" it).
-5. **Use either our simple web editor or use the manual method**
-6. **Check if your data has errors**
-7. **Upload your data and make what's called a pull request**
-
-## Let's do it!
-
-### 1. Sign up for a GitHub Account
-If you don’t have one already, [create a free GitHub account](https://github.com/join).
-
-### 2. Fork the Project (Two-Click)
-Click the **Fork** button in the top right of this page, a guide is [available here if needed](docs/forking.md)
-![Fork button getting pressed](docs/img/forking01.png)
-### 3. Install our requirements
-If you don't have Git installed, [follow this guide](docs/installing-software.md#git). The OFD wrapper script will help you install Python and Node.js automatically (see step 5).
-
-### 4. Download the database
-Download the database using either [this guide](docs/cloning.md) or by just using the command below, with `YOUR_USERNAME` replaced ofc!
-```bash
-git clone https://github.com/YOUR_USERNAME/open-filament-database.git
-cd open-filament-database
-```
-### 5. Make your changes!
-Use the web editor (recommended) or edit files manually:
-
-**Using the OFD Wrapper (Recommended - handles setup automatically):**
-
-Linux/macOS:
-```bash
-./ofd.sh webui
-```
-
-Windows:
-```cmd
-ofd.bat webui
-```
-
-On first run, the wrapper will:
-- Check if Python 3.10+ and Node.js are installed (and help install them if not)
-- Create a Python virtual environment
-- Install all required dependencies
-- Start the WebUI development server
-
-Then access it in your browser at http://localhost:5173
-
-The WebUI includes built-in validation and data sorting features to help ensure your changes are correct. [Full WebUI guide](docs/webui.md)
-
-**Manual setup:** If you prefer to set things up manually, [install our requirements](docs/installing-software.md) and then:
-```bash
-cd webui
-npm ci
-npm run dev
-```
-
-**Manual editing:** If you prefer to edit files directly, [follow this guide](docs/manual.md)
-
-### 6. Validate and sort your changes
-The WebUI can validate and sort your data automatically:
-
-1. Click the "Validate" button in the top-right corner to check for errors
-2. Click the "Sort Data" button to organize your JSON files consistently
-3. Fix any validation errors that appear (they'll be highlighted in red)
-
-Alternatively, you can use the command-line validation scripts ([see guide](docs/validation.md)):
-
-Linux/macOS:
-```bash
-./ofd.sh validate                 # Run all validations
-./ofd.sh validate --folder-names  # Validate folder names
-./ofd.sh validate --json-files    # Validate JSON files against schemas
-./ofd.sh validate --logos         # Validate logo files (size, naming, format)
-./ofd.sh validate --store-ids     # Validate store IDs in purchase links
-./ofd.sh validate --gtin          # Validate GTIN/EAN fields
-```
-
-Windows:
-```cmd
-ofd.bat validate                  # Run all validations
-ofd.bat validate --folder-names   # Validate folder names
-ofd.bat validate --json-files     # Validate JSON files against schemas
-ofd.bat validate --logos          # Validate logo files (size, naming, format)
-ofd.bat validate --store-ids      # Validate store IDs in purchase links
-ofd.bat validate --gtin           # Validate GTIN/EAN fields
-```
-### 7. Submit your changes
-Before submitting, make sure your data is sorted consistently:
-- **In the WebUI:** Click the "Sort Data" button in the top-right corner
-- **Or via command line:** Run `./ofd.sh script style_data` (Linux/macOS) or `ofd.bat script style_data` (Windows)
-
-Then add your changes:
-```bash
-git add .
-```
-
-Create a commit with a descriptive message (e.g., "Added Elegoo Red PLA variant"):
-```bash
-git commit -m "COMMIT_MESSAGE"
-```
-
-Upload your changes to GitHub:
-```bash
-git push -u origin YOUR_BRANCHNAME
-```
-
-Finally, make a pull request [using this guide](docs/pull-requesting.md)
+
+An open, community-maintained database of 3D-printing filaments — brands, materials, filament product lines, colour variants, spool sizes, and the stores that sell them. Hosted by the **Open Filament Collective**, currently facilitated by SimplyPrint.
+
+The data is free to use under MIT — slicers, print farm software, NFC spool tags ([OpenPrintTag](https://specs.openprinttag.org/)), inventory apps, and price-comparison tools can all read it directly.
+
+---
+
+## ✍️ Contributing
+
+The fastest way to add, fix, or correct data is the cloud editor — no install required:
+
+> 👉 **<http://ofd-webui-vv73c.ondigitalocean.app/>**
+
+Browse brands → materials → filaments → variants → sizes, edit fields, upload logos, and submit your changes as a pull request straight from the browser. The editor validates schema, logos, and store references in-page before submitting, so most mistakes are caught up front.
+
+You can sign in two ways:
+
+- **GitHub** — your edits become a pull request opened **from your own fork**, attributed to you on your GitHub profile.
+- **SimplyPrint** — your edits become a pull request opened by our **bot account**, with attribution back to you in the PR body. No GitHub account needed. Rate-limited per IP (default 5 submissions/hour).
+
+### Editing locally instead
+
+If you'd rather work from a clone — for offline edits, running the Python validator against your own data, bulk imports, or developing the WebUI itself — see [docs/contributing-locally.md](docs/contributing-locally.md). For editing JSON files by hand without the WebUI, see the [manual editing guide](docs/manual.md).
+
+---
+
+## 🔌 Using the data (API)
+
+The full dataset is published as a static REST API, with bulk JSON / NDJSON / SQLite / CSV downloads alongside it. The landing page documents the URL shape, endpoints, and examples:
+
+> 👉 **<https://api.openfilamentdatabase.org/>**
+
+Address entities by **path**, e.g. `/api/v1/brands/{brand}/materials/{MATERIAL}/filaments/{filament}/variants/{variant}.json`.
+
+> ℹ️ UUID-based lookups are still supported for integrations that need stable opaque identifiers (NFC tags, slicer profiles), but path-based addressing is what we recommend for everyone else — it's human-readable and stable across cosmetic renames.
+
+---
+
+## 📚 More documentation
+
+- [WebUI guide](docs/webui.md) — features, modes, configuration
+- [Manual editing guide](docs/manual.md) — editing JSON files by hand
+- [Validation guide](docs/validation.md) — running the validator, understanding errors
+- [Local contributing guide](docs/contributing-locally.md) — full fork → clone → PR walkthrough
+- [Pull request guide](docs/pull-requesting.md) — opening a PR from your fork
+- [Software installation](docs/installing-software.md) — Git, Python, Node.js setup (local route only)
+
+---
+
+## 📜 License
+
+MIT. See [`LICENSE`](LICENSE). The data is free to use, redistribute, and embed in commercial products; attribution is appreciated but not required.
+
+---
+
+## 🔗 Related projects
+
+- [OpenPrintTag spec](https://specs.openprinttag.org/) — NFC data format that consumes OFD UUIDs
+- [`slicer-profiles-db`](https://github.com/SimplyPrint/slicer-profiles-db) — separate repo mapping OFD filaments to slicer profiles
+- [SimplyPrint](https://simplyprint.io/) — 3D printer management platform; facilitator of the Open Filament Collective

docs/contributing-locally.md

@@ -0,0 +1,122 @@
+# Contributing from a Local Clone
+
+Most contributors don't need this guide — the [hosted web editor](http://ofd-webui-vv73c.ondigitalocean.app/) lets you add or fix data straight from the browser and opens the pull request for you. See the main [README](../README.md) and the [WebUI guide](webui.md) for that route.
+
+This document is for contributors who want to work from a local clone instead — for offline editing, running the Python validator against your own data, bulk imports, or developing the WebUI itself.
+
+## Steps at a glance
+
+1. [Create a GitHub account](#1-sign-up-for-a-github-account)
+2. [Fork the repository](#2-fork-the-project-two-click)
+3. [Install the requirements](#3-install-our-requirements)
+4. [Clone the database](#4-download-the-database)
+5. [Make your changes](#5-make-your-changes)
+6. [Validate and sort your changes](#6-validate-and-sort-your-changes)
+7. [Submit your changes](#7-submit-your-changes)
+
+---
+
+## 1. Sign up for a GitHub Account
+If you don't have one already, [create a free GitHub account](https://github.com/join).
+
+## 2. Fork the Project (Two-Click)
+Click the **Fork** button in the top right of [the repo page](https://github.com/OpenFilamentCollective/open-filament-database); a guide is [available here if needed](forking.md).
+
+![Fork button getting pressed](img/forking01.png)
+
+## 3. Install our requirements
+If you don't have Git installed, [follow this guide](installing-software.md#git). The OFD wrapper script will help you install Python and Node.js automatically (see step 5).
+
+## 4. Download the database
+Download the database using either [this guide](cloning.md) or by just using the command below, with `YOUR_USERNAME` replaced ofc!
+
+```bash
+git clone https://github.com/YOUR_USERNAME/open-filament-database.git
+cd open-filament-database
+```
+
+## 5. Make your changes
+You have two options:
+
+**Option A — Run the WebUI locally (recommended):**
+
+The OFD wrapper handles all setup automatically:
+
+Linux/macOS:
+```bash
+./ofd.sh webui
+```
+
+Windows:
+```cmd
+ofd.bat webui
+```
+
+On first run, the wrapper will:
+- Check if Python 3.10+ and Node.js are installed (and help install them if not)
+- Create a Python virtual environment
+- Install all required dependencies
+- Start the WebUI development server
+
+Then access it in your browser at <http://localhost:5173>. The WebUI includes built-in validation and data sorting features — see the [full WebUI guide](webui.md).
+
+If you'd rather run things by hand, [install our requirements](installing-software.md) and then:
+
+```bash
+cd webui
+npm ci
+npm run dev
+```
+
+**Option B — Edit JSON files directly:** follow the [manual editing guide](manual.md).
+
+## 6. Validate and sort your changes
+The WebUI can validate and sort your data automatically:
+
+1. Click the "Validate" button in the top-right corner to check for errors
+2. Click the "Sort Data" button to organize your JSON files consistently
+3. Fix any validation errors that appear (they'll be highlighted in red)
+
+Alternatively, you can use the command-line validator ([full guide](validation.md)):
+
+Linux/macOS:
+```bash
+./ofd.sh validate                 # Run all validations
+./ofd.sh validate --folder-names  # Validate folder names
+./ofd.sh validate --json-files    # Validate JSON files against schemas
+./ofd.sh validate --logos         # Validate logo files (size, naming, format)
+./ofd.sh validate --store-ids     # Validate store IDs in purchase links
+./ofd.sh validate --gtin          # Validate GTIN/EAN fields
+```
+
+Windows:
+```cmd
+ofd.bat validate                  # Run all validations
+ofd.bat validate --folder-names   # Validate folder names
+ofd.bat validate --json-files     # Validate JSON files against schemas
+ofd.bat validate --logos          # Validate logo files (size, naming, format)
+ofd.bat validate --store-ids      # Validate store IDs in purchase links
+ofd.bat validate --gtin           # Validate GTIN/EAN fields
+```
+
+## 7. Submit your changes
+Before submitting, make sure your data is sorted consistently:
+- **In the WebUI:** Click the "Sort Data" button in the top-right corner
+- **Or via command line:** Run `./ofd.sh script style_data` (Linux/macOS) or `ofd.bat script style_data` (Windows)
+
+Then add your changes:
+```bash
+git add .
+```
+
+Create a commit with a descriptive message (e.g., "Added Elegoo Red PLA variant"):
+```bash
+git commit -m "COMMIT_MESSAGE"
+```
+
+Upload your changes to GitHub:
+```bash
+git push -u origin YOUR_BRANCHNAME
+```
+
+Finally, make a pull request [using this guide](pull-requesting.md).