# 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