feat: added a twist

2026-04-01 00:53:55 +02:00
parent 0b7deee59e
commit b40c6436cd
76 changed files with 15121 additions and 64 deletions
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -0,0 +1,290 @@
+# Micronomicon → µFrame
+
+A self-hosted web IDE for building rich terminal UIs that publish as `.mu` pages to a NomadNet node.
+
+> **Evolution:** Started as a raw Micron text editor (Phases 1–2, complete).
+> Now pivoting to **µFrame** — a declarative DSL that compiles `.uf` files into
+> both plain ASCII art and styled Micron `.mu` output from the same source.
+
+## Status
+
+Phases 1–2 complete (raw Micron editor). Phase 3 (µFrame engine) is next.
+
+## Tech Stack
+
+| Layer      | Technology                                       |
+|------------|--------------------------------------------------|
+| Backend    | Python 3.13 + FastAPI + uvicorn                  |
+| µFrame     | Pure Python: parser → IR → CharGrid → emitters   |
+| Frontend   | React 19 + Vite + TypeScript                     |
+| UI         | shadcn/ui + Tailwind CSS v4 + tw-animate-css     |
+| Editor     | CodeMirror 6                                     |
+| Graph      | React Flow (@xyflow/react) + dagre               |
+| State      | Zustand                                          |
+| Container  | Docker + Compose                                 |
+
+## Directory Layout
+
+```
+micronomicon/
+  Dockerfile
+  compose.yml
+  docs/
+    framework-design-v3.md    # µFrame DSL spec + rendering model
+    dynamic-templates.md      # Dynamic page addendum (Phases 5–6)
+  backend/
+    main.py                   # FastAPI app + static file serving
+    converter.py              # POST /api/compile (µFrame → ASCII + Micron)
+    pages.py                  # file management (CRUD /api/pages)
+    graph.py                  # link parser (GET /api/graph)
+    docker_utils.py           # container restart (POST /api/restart)
+    requirements.txt
+    uframe/                   # µFrame engine (Phase 3+)
+      __init__.py             # compile(source, width) → CompileResult
+      errors.py               # ParseError, LayoutError
+      ir.py                   # IR node dataclasses
+      parser.py               # .uf DSL → IR tree
+      grid.py                 # CharGrid (2D char + style buffer)
+      chars.py                # Unicode lookup tables (box-drawing, braille)
+      measure.py              # bottom-up size computation
+      layout.py               # top-down position assignment
+      paint.py                # IR → CharGrid rendering
+      borders.py              # junction merging post-pass
+      emit_ascii.py           # CharGrid → plain text
+      emit_micron.py          # CharGrid → Micron with style tags
+      viz.py                  # gauge, sparkline, status (Phase 4)
+      table.py                # table layout + box-drawn grid (Phase 4)
+  frontend/
+    src/
+      App.tsx
+      routes/                 # DashboardView, EditorView, GraphView
+      components/
+        dashboard/            # page list, status badges
+        editor/
+          EditorPane.tsx      # CodeMirror host
+          PreviewPane.tsx     # ASCII + Micron + Raw preview tabs
+          ToolBar.tsx         # save/publish + backlinks
+          uframeHighlight.ts  # CM6 .uf syntax highlighting (Phase 3+)
+          uframeCommands.ts   # "/" command palette for .uf (Phase 3+)
+          micronRenderer.ts   # Micron → HTML (renders compiled output)
+          BacklinkIndicator.tsx
+        shared/
+        ui/                   # shadcn components
+      stores/                 # editorStore, pagesStore (Zustand)
+      hooks/                  # useCompile, useGraph, useUnsavedGuard
+      lib/                    # utils (cn)
+```
+
+## Local Development
+
+**Backend:**
+```bash
+cd backend
+source .venv/bin/activate
+PAGES_DIR=~/.nomadnetwork/storage/pages \
+SOURCES_DIR=~/.micron-editor/sources \
+uvicorn main:app --reload --port 8080
+```
+
+**Frontend:**
+```bash
+cd frontend
+npm run dev   # proxies /api -> localhost:8080
+```
+
+Frontend at http://localhost:5173, backend at http://localhost:8080.
+
+## API Endpoints
+
+| Method | Path                | Description                                          |
+|--------|---------------------|------------------------------------------------------|
+| GET    | /api/health         | Health check                                         |
+| POST   | /api/compile        | Compile `.uf` → `{ascii, micron, warnings}`          |
+| GET    | /api/pages          | List all pages with metadata                         |
+| GET    | /api/pages/{name}   | Read page source (`.uf` or legacy `.mu`)             |
+| POST   | /api/pages/{name}   | Save page — body `{ source, publish: bool }`         |
+| DELETE | /api/pages/{name}   | Delete source and/or .mu file                        |
+| GET    | /api/graph          | Graph nodes + edges (parsed from links in source)    |
+| POST   | /api/restart        | Restart NomadNet Docker container                    |
+
+## Storage
+
+```
+~/.micron-editor/sources/       ← .uf source files (draft + published)
+~/.nomadnetwork/storage/pages/  ← Compiled .mu files served by NomadNet
+```
+
+On publish: `.uf` is compiled to `.mu` and copied to the NomadNet pages directory.
+
+## Conventions
+
+- Frontend UI components live in `frontend/src/components/ui/` (shadcn)
+- Feature components grouped by domain: `dashboard/`, `editor/`, `shared/`
+- State management via Zustand stores in `frontend/src/stores/`
+- Backend is pure FastAPI; no ORM, flat file storage
+- µFrame engine is pure Python stdlib — no external dependencies
+
+## µFrame DSL Reference
+
+Full spec: `docs/framework-design-v3.md`
+
+### Layout primitives
+```
+page "Title" [width]                      # root container (default 64)
+  box [light|heavy|double|rounded] "Title"  # bordered panel
+  row [gap]                               # horizontal layout
+    col [width]                           # column in a row
+  spacer [lines]                          # vertical whitespace
+  pad [t] [r] [b] [l]                    # inner margin
+```
+
+### Content primitives
+```
+heading [1|2|3] "Text"                    # styled heading
+text "Content with @bold{inline} @color{hex}{modifiers}"
+label "Key" "Value"                       # aligned key-value pair
+list [bullet|dash]
+  item "Entry"
+link "Display text" "/dest.mu"            # clickable in Micron
+divider [light|heavy|double|dash|dot]     # horizontal rule
+# comment                                # ignored in output
+```
+
+### Data visualization (Phase 4)
+```
+gauge "Label" $val $max $width warn=N crit=N
+sparkline "Label" $values $width          # braille patterns
+status "Label" [online|offline|degraded]  # ●○◐ indicators
+table "Title"
+  columns "Name" 24 | "Hops" 6 | "Status" 10
+  row "value" | "value" | "value"
+```
+
+### Forms (Phase 5)
+```
+form "name"
+  field "name" [width] "placeholder"
+  radio "group" "Opt A" | "Opt B"
+  checkbox "name" "Label"
+  button "Label" "/action/path"
+```
+
+### Dynamic features (Phase 6)
+```
+source cpu : shell "cat /proc/loadavg"
+on_submit "form_name"
+  # handle form data
+if $val > threshold
+  # conditional rendering
+for item in $collection
+  # iteration
+state "store" "/path.json"
+cache 0                                   # never cache (re-execute per request)
+```
+
+### Rendering pipeline
+```
+.uf source → Parse → IR Tree → Measure → Layout → Paint → CharGrid
+                                                              ├→ ASCII emitter (plain text)
+                                                              └→ Micron emitter (styled .mu)
+```
+
+### Micron syntax (legacy raw editor, still used for compiled output)
+```
+>H1  >>H2  >>>H3                        headings
+`!bold`!  `*italic`*  `_underline`_     formatting
+`Fhex text`f   `Bhex text`b            colors (3-digit hex)
+`c text`a  `r text`a  `l text`a        alignment
+[label`slug]                            links
+-─  -━  -═  -★                          dividers
+`=  ...  `=                             literal mode
+# comment                               hidden in output
+```
+
+## Roadmap
+
+### Phase 1 — Core Editor + Dashboard + Graph ✅
+
+- Split-pane Micron editor with live preview
+- Save draft / publish to NomadNet pages dir
+- Pages dashboard with status badges
+- Page graph (React Flow + dagre)
+- NomadNet restart, dark/light theme, keyboard shortcuts
+
+### Phase 2 — Linking + Editor Enhancements ✅
+
+- `[[` page link autocomplete
+- Backlink indicator with popover
+- Pivot to direct Micron editor (removed Markdown pipeline)
+- `/` slash command palette for Micron syntax
+- Micron syntax highlighting + HTML preview renderer
+- Syntax completeness per micron-composer spec
+
+### Phase 3 — µFrame Core Engine (next)
+
+Build `backend/uframe/` — the rendering pipeline:
+
+1. `errors.py` + `ir.py` — data structures
+2. `chars.py` — Unicode lookup tables (box-drawing, blocks, braille)
+3. `parser.py` — `.uf` DSL → IR tree (indentation-based, line-oriented)
+4. `grid.py` — CharGrid class (2D char + style buffer)
+5. `measure.py` + `layout.py` — size computation + position assignment
+6. `paint.py` — IR nodes → CharGrid
+7. `borders.py` — junction merging post-pass
+8. `emit_ascii.py` + `emit_micron.py` — CharGrid → output strings
+9. `__init__.py` — public `compile()` API
+10. Update `converter.py` → `POST /api/compile` endpoint
+11. Update `pages.py` — `.uf` sources, compile-on-publish
+12. Update `graph.py` — parse `.uf` for links
+
+### Phase 4 — Data Visualization
+
+- gauge, meter, bar_h, bar_v (block elements)
+- sparkline (braille sub-cell rendering)
+- heatmap (shade blocks with per-cell color)
+- status indicators (●○◐ with color)
+- table (box-drawn with header separator)
+- Border merging across nested tables
+
+### Phase 5 — Web IDE Integration
+
+- Replace Micron editor with µFrame DSL editor
+- CodeMirror `.uf` syntax highlighting + autocomplete
+- `useCompile` hook (debounced API calls)
+- Triple preview: ASCII | Micron rendered | Raw Micron
+- Page storage: `.uf` sources, `.mu` compiled output
+- Migration script for legacy `.mu` sources
+
+### Phase 6 — Forms & Interactivity
+
+- Form primitives: field, password, radio, checkbox, button
+- ASCII: visual placeholders; Micron: live fields
+- @modifier inline syntax
+- Variables and `let` bindings
+
+### Phase 7 — Dynamic Pages
+
+- `source` blocks for live data (shell, file, json, python, rns)
+- Compile to executable Python scripts with embedded runtime
+- `on_submit` form handling via `FIELD_*` env vars
+- Conditionals (`if`/`elif`/`else`) and loops (`for`)
+- State persistence (`state` + JSON store)
+- Cache control headers
+- CLI: `uframe compile` / `uframe deploy`
+
+### Phase 8 — Components & Standard Library
+
+- `component` definitions with argument bindings
+- Standard library: `std/dashboard`, `std/filebrowser`, `std/board`
+- Themes (`.uf-theme` color palette files)
+- `uframe check` linter
+- Production deployment: systemd + Tailscale
+
+## References
+
+- µFrame design: `docs/framework-design-v3.md`
+- µFrame dynamic: `docs/dynamic-templates.md`
+- micron-composer: https://github.com/fr33n0w/micron-composer
+- micron-parser-js: https://rfnexus.github.io/micron-parser-js/
+- NomadNet: https://github.com/markqvist/NomadNet
+- md2txt (legacy): https://codeberg.org/randogoth/md2txt