291 lines
11 KiB
Markdown
291 lines
11 KiB
Markdown
# 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
|