dtoro/micronomicon
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

feat: preview

Browse Source
This commit is contained in:
authentik Default Admin
2026-04-01 10:13:14 +02:00
parent 8776459ffb
commit 0316e50233
13 changed files with 590 additions and 538 deletions
Download Patch File Download Diff File Expand all files Collapse all files

465
CLAUDE.md
View File

@@ -1,290 +1,321 @@
# Micronomicon → µFrame
# µFrame (Micronomicon)
A self-hosted web IDE for building rich terminal UIs that publish as `.mu` pages to a NomadNet node.
A self-hosted web IDE and CLI for building rich terminal UIs using a declarative DSL. Compiles `.uf` source files into both plain ASCII art and styled Micron `.mu` pages for NomadNet — a decentralized communication platform running on the Reticulum mesh network.
> **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
## What It Does
Write this:
```
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)
page "Node Status" 60
box double "Relay Alpha-7"
align center
text "Reticulum Network Node"
gauge "CPU" 62 100 28 warn=75 crit=90
status "East Relay" online
table "Routes"
columns "Dest" 20 | "Hops" 6 | "Status" 10
row "relay-east" | "2" | "@color{0f0}{alive}"
```
## Local Development
Get this (ASCII):
```
╔═ Relay Alpha-7 ════════════════════════════════════════════╗
║ Reticulum Network Node ║
╚════════════════════════════════════════════════════════════╝
CPU ████████████████████░░░░░░░░ 62%
● East Relay
┌────────────────────┬──────┬──────────┐
│Dest │Hops │Status │
├────────────────────┼──────┼──────────┤
│relay-east │2 │● alive │
└────────────────────┴──────┴──────────┘
```
And the same content as Micron `.mu` with color tags, bold, links, and interactive form fields — ready to serve on NomadNet.
## Quick Start
### Web IDE
**Backend:**
```bash
# Backend
cd backend
source .venv/bin/activate
PAGES_DIR=~/.nomadnetwork/storage/pages \
SOURCES_DIR=~/.micron-editor/sources \
uvicorn main:app --reload --port 8080
```
**Frontend:**
```bash
# Frontend (separate terminal)
cd frontend
npm run dev # proxies /api -> localhost:8080
npm run dev
```
Frontend at http://localhost:5173, backend at http://localhost:8080.
Open http://localhost:5173 → click **New Page** → click **Examples** → pick a template.
### CLI
```bash
cd backend
source .venv/bin/activate
# Render to terminal
python -m uframe render page.uf
# Render Micron only
python -m uframe render page.uf --micron
# Compile to .mu file
python -m uframe compile page.uf --out page.mu
# Validate without output
python -m uframe check page.uf
# Compile and deploy to NomadNet
python -m uframe deploy page.uf
```
## Tech Stack
| Layer | Technology |
|------------|-------------------------------------------------|
| Backend | Python 3.13 + FastAPI + uvicorn |
| µFrame | Pure Python (zero deps): parser → IR → CharGrid → emitters |
| Frontend | React 19 + Vite + TypeScript |
| UI | shadcn/ui + Tailwind CSS v4 |
| Editor | CodeMirror 6 (custom µFrame syntax mode) |
| Graph | React Flow (@xyflow/react) + dagre |
| State | Zustand |
| Container | Docker + Compose |
## Project Structure
```
micronomicon/
├── backend/
│ ├── main.py # FastAPI app + static file serving
│ ├── converter.py # POST /api/compile endpoint
│ ├── pages.py # CRUD /api/pages (.uf sources + .mu publish)
│ ├── graph.py # GET /api/graph (link parser)
│ ├── docker_utils.py # POST /api/restart (NomadNet container)
│ └── uframe/ # µFrame engine (16 modules, ~3800 LOC)
│ ├── __init__.py # compile(source, width) → CompileResult
│ ├── parser.py # .uf DSL → IR tree (indentation-based)
│ ├── ir.py # 30+ IR node dataclasses
│ ├── grid.py # CharGrid — 2D char + style buffer
│ ├── chars.py # Unicode tables (box-drawing, braille)
│ ├── measure.py # Bottom-up size computation
│ ├── layout.py # Top-down position assignment
│ ├── paint.py # IR nodes → CharGrid rendering
│ ├── borders.py # Junction merging post-pass
│ ├── emit_ascii.py # CharGrid → plain text
│ ├── emit_micron.py # CharGrid → Micron with style tags
│ ├── codegen.py # Dynamic page → executable Python script
│ ├── cli.py # CLI: render / compile / check / deploy
│ ├── errors.py # ParseError, LayoutError, CompileWarning
│ └── tests/ # 42 tests (compile, dynamic, components)
├── frontend/src/
│ ├── routes/ # DashboardView, EditorView, GraphView
│ ├── components/editor/
│ │ ├── EditorPane.tsx # CodeMirror 6 host
│ │ ├── PreviewPane.tsx # ASCII / Micron / Raw / Script tabs
│ │ ├── ToolBar.tsx # Save, Publish, Examples, Backlinks
│ │ ├── uframeHighlight.ts # µFrame syntax highlighting
│ │ ├── uframeCommands.ts # "/" slash command palette
│ │ ├── micronRenderer.ts # Micron → HTML preview renderer
│ │ └── examples.ts # 9 built-in example templates
│ ├── hooks/
│ │ ├── useCompile.ts # Debounced POST /api/compile
│ │ └── useUnsavedGuard.ts # Prevent accidental navigation
│ └── stores/
│ ├── editorStore.ts # Zustand: source, compiled output, preview mode
│ └── pagesStore.ts # Zustand: page list, delete, unpublish
└── docs/
├── framework-design-v3.md # Full DSL spec + rendering model
└── dynamic-templates.md # Dynamic page addendum
```
## API Endpoints
| Method | Path | Description |
|--------|---------------------|------------------------------------------------------|
| GET | /api/health | Health check |
| POST | /api/compile | Compile `.uf` → `{ascii, micron, warnings}` |
| POST | /api/compile | Compile `.uf` → `{ascii, micron, script, is_dynamic}` |
| 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 }` |
| GET | /api/pages/{name} | Read page source |
| POST | /api/pages/{name} | Save page — `{ source, publish }` |
| DELETE | /api/pages/{name} | Delete source and/or .mu file |
| GET | /api/graph | Graph nodes + edges (parsed from links in source) |
| GET | /api/graph | Page link graph (nodes + edges) |
| POST | /api/restart | Restart NomadNet Docker container |
## Storage
```
~/.micron-editor/sources/ ← .uf source files (draft + published)
~/.micron-editor/sources/ ← .uf source files (drafts + published)
~/.nomadnetwork/storage/pages/ ← Compiled .mu files served by NomadNet
```
On publish: `.uf` is compiled to `.mu` and copied to the NomadNet pages directory.
- **Save Draft**: writes `.uf` to sources dir only
- **Publish (static)**: compiles `.uf` → `.mu`, writes to pages dir (chmod 644)
- **Publish (dynamic)**: compiles `.uf` → executable Python script, writes to pages dir (chmod 755)
## 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
NomadNet auto-detects the execute bit: static pages are served as-is, dynamic pages are executed and their stdout is served.
## µFrame DSL Reference
Full spec: `docs/framework-design-v3.md`
### Layout primitives
### Layout
```
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
page "Title" [width] # root (default width 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
### Content
```
heading [1|2|3] "Text" # styled heading
heading [1|2|3] "Text" # styled heading
text "Content with @bold{inline} @color{hex}{modifiers}"
label "Key" "Value" # aligned key-value pair
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
link "Display text" "/dest.mu" # clickable in Micron
divider [light|heavy|double|dash|dot] # horizontal rule
# comment # ignored in output
```
### Data visualization (Phase 4)
### Data Visualization
```
gauge "Label" $val $max $width warn=N crit=N
sparkline "Label" $values $width # braille patterns
status "Label" [online|offline|degraded] # ●○◐ indicators
gauge "Label" value max width [warn=N crit=N] # ████░░░░ bar with thresholds
sparkline "Label" "1,3,5,8,7,5" width # ⣀⣤⣶⣿⣷⣤ braille chart
status "Label" [online|offline|degraded] # ●○◐ colored indicators
table "Title"
columns "Name" 24 | "Hops" 6 | "Status" 10
row "value" | "value" | "value"
columns "Name" 20 | "Hops" 6 | "Status" 10
row "relay" | "2" | "@color{0f0}{● alive}"
```
### Forms (Phase 5)
### Forms
```
form "name"
field "name" [width] "placeholder"
radio "group" "Opt A" | "Opt B"
checkbox "name" "Label"
button "Label" "/action/path"
field "name" [width] "placeholder" # text input
password "name" [width] "placeholder" # masked input
radio "group" "Opt A" | "Opt B" | "Opt C" # radio buttons
checkbox "name" "Label" # checkbox
button "Label" "/action/path" # submit link
```
### Dynamic features (Phase 6)
### Dynamic Features
```
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)
cache 0 # never cache (re-execute)
source cpu : shell "cat /proc/loadavg" # live data at render time
source config : json "/path/config.json" # JSON file read
source ts : python "datetime.now().isoformat()" # Python expression
let name = "Relay Alpha" # variable assignment
if $cpu > 90
text "ALERT: CPU critical"
elif $cpu > 75
text "Warning: elevated"
for peer in $peers
status "$peer.name" $peer.state
on_submit "search"
source results : shell "search.py '$query'"
text "$results"
state "counter" "/tmp/counter.json" # persistent JSON store
```
### Rendering pipeline
### Components
```
.uf source → Parse → IR Tree → Measure → Layout → Paint → CharGrid
├→ ASCII emitter (plain text)
└→ Micron emitter (styled .mu)
# Define a reusable component
component stat(label, value, max)
gauge "$label" $value $max 20
# Use it
stat "CPU" 62 100
stat "MEM" 84 100
# Import standard library
use std/dashboard
banner "My Node" "Mesh Network"
resources 62 84
```
### Micron syntax (legacy raw editor, still used for compiled output)
### Standard Libraries
| Library | Components |
|---------|-----------|
| `std/dashboard` | `banner(title, subtitle)`, `resources(cpu, mem)`, `peer_status(name, state)` |
| `std/status-bar` | `status_bar(label, value, max)`, `status_item(name, state)` |
| `std/nav` | `nav_link(label, dest)`, `nav_divider()` |
## Rendering Pipeline
```
>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
.uf source
│
▼
Parse ──→ IR Tree (30+ node types)
│
▼
Measure (bottom-up: compute sizes)
│
▼
Layout (top-down: assign positions)
│
▼
Paint (depth-first: write chars into CharGrid)
│
▼
Merge Borders (fix junction characters)
│
├──→ ASCII emitter → plain text
├──→ Micron emitter → styled .mu (with colors, links, form tags)
└──→ Codegen (if dynamic) → executable Python script
```
## Roadmap
## Web IDE Features
### Phase 1 — Core Editor + Dashboard + Graph ✅
- **Split-pane editor**: µFrame DSL source (left) / live preview (right)
- **Syntax highlighting**: keywords, strings, variables, comments in distinct colors
- **`/` command palette**: type `/` to insert layout, content, data viz, form, and style primitives
- **4 preview tabs**: ASCII | Micron (rendered) | Raw (Micron source) | Script (dynamic pages only)
- **`⚡ dynamic` badge**: auto-detected when source contains `source`, `if`, `for`, etc.
- **Examples dropdown**: 9 built-in templates (Hello World → Full Node Page → Dynamic Dashboard)
- **Pages dashboard**: table view with Published/Draft/Orphan status badges
- **Page graph**: React Flow visualization of inter-page links
- **Keyboard shortcuts**: `Ctrl+S` save draft, `Ctrl+P` publish
- **Unsaved changes guard**: warns before navigating away
- **Backlink indicator**: shows which pages link to the current page
- 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
## Running Tests
### Phase 2 — Linking + Editor Enhancements ✅
```bash
cd backend
source .venv/bin/activate
python -m pytest uframe/tests/ -v
```
- `[[` 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
42 tests covering:
- Static compilation (boxes, headings, text, gauges, tables, links, lists, spacers, dividers)
- Form elements (field, radio, checkbox, button)
- Dynamic pages (source, if/for, let, state, on_submit, codegen)
- Components (inline definitions, standard library, parameter substitution)
### Phase 3 — µFrame Core Engine (next)
## Conventions
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
- µFrame engine is **pure Python stdlib** — zero external dependencies
- Backend is FastAPI; no ORM, flat file storage
- Frontend uses shadcn/ui components in `frontend/src/components/ui/`
- Feature components grouped by domain: `dashboard/`, `editor/`, `shared/`
- State management via Zustand stores
- All `.uf` sources stored in `SOURCES_DIR`, compiled `.mu` in `PAGES_DIR`
## 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/
- µFrame design spec: `docs/framework-design-v3.md`
- Dynamic templates spec: `docs/dynamic-templates.md`
- NomadNet: https://github.com/markqvist/NomadNet
- md2txt (legacy): https://codeberg.org/randogoth/md2txt
- Micron syntax: https://github.com/fr33n0w/micron-composer
- Reticulum: https://github.com/markqvist/Reticulum