micronomicon/CLAUDE.md

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:

cd backend
source .venv/bin/activate
PAGES_DIR=~/.nomadnetwork/storage/pages \
SOURCES_DIR=~/.micron-editor/sources \
uvicorn main:app --reload --port 8080

Frontend:

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