Limits & Compatibility

1. When Melker is wrong

Cases where another tool is the better choice.

If your use case isn't in this list, Melker is probably fine. The rest of this page is about what happens at the edges.

For a detailed feature-by-feature comparison with other TUI frameworks, see the TUI Comparison.

2. What Melker doesn't have

Feature gaps visible in the ecosystem. Stated plainly.

These are design choices, not bugs. Melker trades fine-grained reactivity for a simpler model (createState + bind handles most cases without a dependency graph), and trades grid layout for a smaller layout engine. If any of these are dealbreakers, the table in Section 1 points to frameworks that have them.

3. Terminal compatibility

What works where. Graphics modes, color depth, and resolution.

Graphics mode support

Color depth

Mode resolution comparison

4. Degraded rendering

Same app rendered under different graphics modes and color depths. The image degrades. The text stays sharp.

Graphics mode degradation

                  ┌────────────────────────────┐
   🬞🬵🬚🬋🬋🬋🬩🬋🬋🬩🬱🬭🬏  │                            │
 🬞🬻🬹🬭🬭🬭🬭🬱🬹🬭🬭🬭🬭🬱🬹🬏 │ System Status              │
 🬻🬻🬦🬦🬹🬹🬏🬏🬭🬞🬵🬹🬓🬓▌🬴 │ CPU: 42% Mem: 3.1 GB       │
 🬬🬨▐▐🬊🬕🬬🬱🬵🬍🬆🬂▌▌🬕🬕 │ Uptime: 14d 6h             │
 🬹🬹🬹▐🬹▌🬍🬬🬝🬄▐🬹▌🬓🬹🬹 │ Load: 1.2 0.8 0.5          │
 🬨🬊▐▐🬻▌🬆🬂🬂🬊▐🬵▌▌🬄🬎 │                            │
 🬊🬬🬂🬁🬂🬀🬂🬂🬂🬂🬁🬂🬀🬂🬆🬆 │                            │
  🬁🬊🬎🬎🬊🬂🬎🬎🬎🬊🬆🬎🬎🬂  │                            │
                  │                            │
                  │                            │
                  └────────────────────────────┘

                  ┌────────────────────────────┐
  ▗▄▟▀▀▛▀▛▜▀▀▙▄▖  │                            │
 ▗▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄ │ System Status              │
 ▀▀▀▐▀▀▄▖▜▗▟▀▌▌▀▀ │ CPU: 42% Mem: 3.1 GB       │
 ▄▄▄▐▄▌▜▙▟▌▘▄▌▄▄▄ │ Uptime: 14d 6h             │
 ▀▀▀▐▀▌▀▀▀▘▐▀▌▀▀▀ │ Load: 1.2 0.8 0.5          │
 ▄▄▄▐▄▌▄▄▄▄▐▄▌▙▄▄ │                            │
 ▝▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀ │                            │
  ▝▀▀▀▀▀▀▀▀▀▀▀▀▘  │                            │
                  │                            │
                  │                            │
                  └────────────────────────────┘

                  ┌────────────────────────────┐
   ▄▄▀▀▀▀▀▀▀▀▀▄▄  │                            │
  ▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀ │ System Status              │
 ▀██▀▀▀▀▀▀▀▀▀▀▀▀▀ │ CPU: 42% Mem: 3.1 GB       │
 ▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀ │ Uptime: 14d 6h             │
 ▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀ │ Load: 1.2 0.8 0.5          │
 ▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀ │                            │
 ▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀ │                            │
  ▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀ │                            │
                  │                            │
                  │                            │
                  └────────────────────────────┘

                                                
                                                
                    System Status               
                    CPU: 42% Mem: 3.1 GB        
                    Uptime: 14d 6h              
                    Load: 1.2 0.8 0.5           
                                                
                                                
                                                
                                                
                                                
                                                

All four are the same app. Melker picks the best mode your terminal supports, or you override with MELKER_GFX_MODE or the gfxMode prop. The image degrades. The box-drawing and text stay sharp in all modes.

Color depth degradation

Same app, same sextant mode, three color depths. This is the constraint that catches people off guard: you think the limit is character-grid resolution, but it's actually color depth.

                  ┌────────────────────────────┐
   🬞🬵🬚🬋🬋🬋🬩🬋🬋🬩🬱🬭🬏  │                            │
 🬞🬻🬹🬭🬭🬭🬭🬱🬹🬭🬭🬭🬭🬱🬹🬏 │ System Status              │
 🬻🬻🬦🬦🬹🬹🬏🬏🬭🬞🬵🬹🬓🬓▌🬴 │ CPU: 42% Mem: 3.1 GB       │
 🬬🬨▐▐🬊🬕🬬🬱🬵🬍🬆🬂▌▌🬕🬕 │ Uptime: 14d 6h             │
 🬹🬹🬹▐🬹▌🬍🬬🬝🬄▐🬹▌🬓🬹🬹 │ Load: 1.2 0.8 0.5          │
 🬨🬊▐▐🬻▌🬆🬂🬂🬊▐🬵▌▌🬄🬎 │                            │
 🬊🬬🬂🬁🬂🬀🬂🬂🬂🬂🬁🬂🬀🬂🬆🬆 │                            │
  🬁🬊🬎🬎🬊🬂🬎🬎🬎🬊🬆🬎🬎🬂  │                            │
                  │                            │
                  │                            │
                  └────────────────────────────┘

                  ┌────────────────────────────┐
   🬭🬞🬇🬖🬞🬃🬓🬋🬖🬦🬹🬏🬏  │                            │
 🬦🬖🬷🬹🬶🬺🬻🬻🬻🬻🬻🬺🬷🬱▌🬏 │ System Status              │
 ▐🬲🬄🬻🬹🬹🬏🬹🬷🬞🬵🬹🬓🬓🬟🬤 │ CPU: 42% Mem: 3.1 GB       │
 🬉🬷🬗▐🬊🬕🬬🬱🬵🬜🬆🬂▌🬀🬝🬐 │ Uptime: 14d 6h             │
 🬹🬺🬞▐🬹▌🬫🬬🬝🬄🬻🬹▌🬚🬉🬹 │ Load: 1.2 0.8 0.5          │
 🬴🬗🬇▐█▌🬣🬎🬥🬗🬬🬦▌🬛🬉🬞 │                            │
 🬨🬇🬒🬁🬂🬀🬕🬥🬅🬕🬬🬂🬀🬣🬉🬝 │                            │
  🬂🬁🬎🬄🬉🬎🬄🬉🬁🬃🬈🬁🬎🬀  │                            │
                  │                            │
                  │                            │
                  └────────────────────────────┘

                  ┌────────────────────────────┐
   ▄▄ ▀▀▀▀▀░░ ▄▄  │                            │
  ▀▀░░░░░░░░░░░▀▀ │ System Status              │
 ░░░░▀▀▀▀░▓▀▀▀░░░ │ CPU: 42% Mem: 3.1 GB       │
 ▀░░▀▀▀▀▀▒▀▀▀▀▀░░ │ Uptime: 14d 6h             │
 ▀░░▀▀▀▓▀▀▀▓▀▀▀░░ │ Load: 1.2 0.8 0.5          │
 ░░░▀█▀▀░▀▀▓██░░░ │                            │
 ▀▀▀░▀▀░░░░▀▀▀░▀▀ │                            │
  ▀▀░░░░░░░░░░░░▀ │                            │
                  │                            │
                  │                            │
                  └────────────────────────────┘

Same sextant mode, same resolution. The 256-color version uses dithering to approximate truecolor gradients. The 16-color version (what you get on TERM=linux) uses shade characters (░▒▓) to simulate tonal range with only 16 colors. Override with COLORTERM=truecolor if your terminal actually supports it.

View source

5. Debugging layout

Common layout problems, what causes them, and how to fix them.

<img src="photo.png" style="width: fill; height: fill" />

<img src="photo.png" width="fill" height="fill" />

<container style="overflow: scroll">
  <text>Long content...</text>
</container>

<container style="overflow: scroll; flex: 1; width: fill">
  <text style="text-wrap: wrap; width: fill">Long content...</text>
</container>

6. Debugging state

State binding, exported value copies, and two-way binding traps.

<input id="query" bind="searchTerm" />
<text bind="count" bind-mode="one-way" />

<script>
  const state = $melker.createState({ searchTerm: '', count: 0 });
  // state.searchTerm auto-updates as the user types (two-way)
  // state.count pushes to the text element (one-way)
</script>

.isEmpty #empty-message { display: flex; }

<script>
  export let count = 0;
  export function setCount(n) { count = n; }
</script>

<script async="ready">
  $app.setCount(10);  // modifies the original
</script>

<input bind="query" bind-mode="one-way" onInput="$app.normalize()" />
<script>
  const state = $melker.createState({ query: '' });
  export function normalize() {
    state.query = $melker.getElementById('query').getValue().trim().toLowerCase();
  }
</script>

7. Debugging permissions

Silent failures from missing policy entries.

<policy>{"permissions": {"net": ["api.example.com"]}}</policy>

8. Debugging terminal

Font issues, protocol fallback, and sandbox detection.

melker --test-sextant

MELKER_GFX_MODE=quadrant melker app.melker

9. Limits in practice: earthquake dashboard

A real app that hit several limits from sections 1-8. What happened, what worked around it.

The earthquake dashboard is a 431-line single-file app that fetches live USGS earthquake data, renders it in a sortable table with sparklines and distribution bars, and plots quakes on a world map. It was built across 8 commits over three weeks (Feb 12 to Mar 7 2026). This section traces which limits from the rest of this page showed up during development, and how they were handled.

What was easy

• Layout. The initial 431-line dashboard was a single session. Getting the flex layout correct (split panes, table + sparkline + distribution bars) was surprisingly straightforward.
• Data binding. data-table.setValue() with fetched JSON, one line per component.
• Policy. Declaring net: ["earthquake.usgs.gov"] and getting sandboxed fetch with no extra code.
• Incremental polish. UTC timestamps, toast alerts for M7+ quakes, bar label alignment. Small targeted commits.

What was awkward

• The hand-drawn canvas map. Intended as a quick "get something on screen" approach, the hardcoded COASTLINES polyline array bloated the .melker file and took more time than expected. This directly drove the creation of the <tile-map> component (commit 476), which replaced ~35 lines of coordinate data with a single element.
• Engine primitives that didn't exist. The canvas map required building fillPolyColor, drawCircleCorrected, the tooltip system, and canvas hit-testing. The dashboard was driving engine development, not using existing features.
• The coordinate swap bug. SVG path coordinates for tectonic plate boundaries were in lat/lon order instead of lon/lat. Discovered because the AI assistant (via an OpenRouter model) insisted on the coordinate order it was trained on, not what was specified. A reminder that AI-assisted code still needs visual verification.
• The cache API. Tectonic plate boundaries were the third feature that needed caching. One too many for a framework without a cache primitive. This pushed the creation of $melker.cache.read/write in the engine.
• Permissions grew. Started with just "net": ["earthquake.usgs.gov"], then needed "map": true and "raw.githubusercontent.com" for tile maps and plate data. Each new data source is a policy change discovered at runtime.

What surprised

Color resolution matters more than spatial resolution. The dashboard looks good in truecolor terminals, but under TERM=linux (16 colors) the map and magnitude coloring lose most of their information density. You think the limit is character-grid resolution, but it's actually color depth.

Deep dive: How It Works · Dashboard source