DEV Community: artydev

How to Embed a Photino Project into a Single Executable with wrap_photino.py

artydev — Wed, 12 Aug 2026 18:28:13 +0000

📦 wrap_photino.py — Photino AOT Single-File Bundler

look at bottom for the code.

Bundle an entire Photino AOT desktop application into a single, standalone executable — with optional debug-output suppression.

What Is This?
How It Works (Deep Dive)
- Step 1 — File Discovery & Embedding
- Step 2 — C Wrapper Generation
- Step 3 — Compilation
- Step 4 — Runtime Behaviour
Prerequisites
Basic Usage
Command-Line Reference
Examples
- Minimal Bundle
- Custom Binary & Library Names
- Suppress All Debug Output
- Fully Static Build
- Keep the Intermediate C File
Output Structure
Performance & Overhead
Use Cases
Troubleshooting
How the Generated C Code Works
Security Considerations
License

🧠 What Is This?

wrap_photino.py is a Python build-time tool that takes a compiled Photino AOT (Ahead-of-Time) desktop application — consisting of a native binary, a shared library (.so), and a wwwroot web assets folder — and bundles everything into a single, portable executable.

The resulting executable:

✅ Self-contained — no external files needed at runtime.
✅ Portable — extract-and-run on any compatible Linux system.
✅ Clean — automatically cleans up temporary files after exit.
✅ Silent — can optionally suppress both stdout and stderr (ideal for kiosks, embedded systems, or production deployments).

⚙️ How It Works (Deep Dive)

Step 1 — File Discovery & Embedding

The script scans the project directory for three categories of files:

Component	Default Path	Purpose
Main binary	`PhotinoAOT`	The compiled .NET AOT executable
Native library	`Photino.Native.so`	The Photino native bridge (WebView backend)
Web root	`wwwroot/`	HTML, CSS, JS, images, and other frontend assets

Each file is read into memory as raw bytes. The script then:

Tracks file permissions (executable 0o755 for the binary, 0o644 for everything else).
Calculates total embedded payload size.
Reports each file and its size to the console.

Step 2 — C Wrapper Generation

The script generates a single C source file that:

Embeds every file as a static byte array using a bin2c() converter.
Generates a main() function that:
- Creates a temporary directory (/tmp/photino_wrapper_XXXXXX).
- Recreates the original directory structure inside it.
- Writes all embedded files to disk with correct permissions.
- Sets LD_LIBRARY_PATH to include the temp directory.
- Changes the working directory to the temp directory.
- Forks a child process to run the actual application.
- Waits for the child to finish.
- Cleans up all temporary files and directories.
- Returns the child's exit code.

Step 3 — Compilation

The generated C code is compiled with gcc:

gcc -O2 -s -o PhotinoWrapper photino_wrapper_XXXXXX.c

-O2 — Optimise for speed/size.
-s — Strip debug symbols from the final binary.
--static (optional) — Link everything statically for maximum portability.

Step 4 — Runtime Behaviour

When the wrapper is executed:

┌─────────────────────────────────────────────────┐
│  ./PhotinoWrapper                               │
│                                                 │
│  1. Create /tmp/photino_wrapper_XXXXXX          │
│  2. Write all embedded files                    │
│  3. Set LD_LIBRARY_PATH                         │
│  4. chdir to temp dir                           │
│  5. fork()                                      │
│     ├─ CHILD: execv("PhotinoAOT", argv)         │
│     └─ PARENT: waitpid(), cleanup, exit         │
└─────────────────────────────────────────────────┘

If --suppress-debug is enabled, the child process has its stdout and stderr redirected to /dev/null before execv, silencing all output.

✅ Prerequisites

Requirement	Notes
Python 3.6+	For running the script
GCC	To compile the generated C wrapper
Linux	The wrapper uses Linux-specific APIs (`fork`, `execv`, `mkdtemp`, `dup2`)
A compiled Photino AOT project	Must contain the binary, `.so`, and `wwwroot/`

Install GCC if missing:

# Debian / Ubuntu
sudo apt install build-essential

# Fedora / RHEL
sudo dnf install gcc

# Arch Linux
sudo pacman -S gcc

🚀 Basic Usage

python3 wrap_photino.py /path/to/photino/project

This will:

Scan /path/to/photino/project for PhotinoAOT, Photino.Native.so, and wwwroot/.
Generate a C wrapper.
Compile it into ./PhotinoWrapper.

📋 Command-Line Reference

usage: wrap_photino.py [-h] [--output OUTPUT] [--binary BINARY]
                       [--native NATIVE] [--wwwroot WWWROOT]
                       [--static] [--keep-c] [--suppress-debug]
                       [project_dir]

Argument	Short	Default	Description
`project_dir`	—	`.` (current dir)	Path to the compiled Photino project
`--output`	`-o`	`PhotinoWrapper`	Name of the output executable
`--binary`	`-b`	`PhotinoAOT`	Name of the main AOT binary inside the project
`--native`	`-n`	`Photino.Native.so`	Name of the native shared library
`--wwwroot`	`-w`	`wwwroot`	Name of the web assets directory
`--static`	`-s`	off	Statically link the wrapper (adds `-static` to GCC)
`--keep-c`	—	off	Keep the intermediate `.c` file after compilation
`--suppress-debug`	—	off	Redirect both stdout and stderr to `/dev/null` at runtime

🧪 Examples

Example 1: Minimal Bundle

# Navigate to your published Photino project
cd ~/my-app/publish

# Bundle everything
python3 ~/tools/wrap_photino.py .

# Run the result
./PhotinoWrapper

Example 2: Custom Binary & Library Names

python3 wrap_photino.py ./publish \
    --binary MyApp \
    --native libphotino.so \
    --wwwroot assets \
    --output MyAppWrapper

Example 3: Suppress All Debug Output

Perfect for production deployments, kiosks, or CI/CD pipelines where console noise is unwanted:

python3 wrap_photino.py ./publish --suppress-debug

Now ./PhotinoWrapper will run completely silently — no stdout, no stderr.

Example 4: Fully Static Build

For maximum portability across Linux distributions (no dependency on specific shared library versions):

python3 wrap_photino.py ./publish --static

⚠️ Note: This only statically links the wrapper itself, not the embedded Photino binary or its dependencies. The embedded Photino.Native.so is still dynamically loaded.

Example 5: Keep the Intermediate C File

If you want to inspect or manually tweak the generated C code:

python3 wrap_photino.py ./publish --keep-c
# The .c file will be in /tmp/ or the current directory

📁 Output Structure

After running the script, you'll get a single file:

./PhotinoWrapper          # The bundled executable (e.g., 15 MB)

At runtime, the wrapper recreates this structure inside /tmp/photino_wrapper_XXXXXX/:

/tmp/photino_wrapper_XXXXXX/
├── PhotinoAOT            # Main binary (executable)
├── Photino.Native.so     # Native library
└── wwwroot/              # Web assets
    ├── index.html
    ├── style.css
    ├── app.js
    └── ...

Everything is automatically deleted when the application exits.

📊 Performance & Overhead

The script reports overhead after compilation:

Total embedded data: 14,582,880 bytes
Overhead: 48,128 bytes (0.3%)

The overhead is typically < 1% and comes from:

The C wrapper code itself.
ELF headers and section alignment.
GCC optimisation padding.

The startup cost is minimal — just fork() + file writes to a tmpfs (usually RAM-backed).

🎯 Use Cases

Scenario	Why This Tool
Distribution	Ship a single file instead of a directory tree
Kiosk / Embedded	`--suppress-debug` keeps the display clean
CI/CD Pipelines	Single artifact, easy to copy and deploy
End-User Simplicity	No "extract to folder" step — just run
Cross-Platform Packaging	Combine with AppImage or similar
Security	No writable application directory needed at runtime

🔧 Troubleshooting

"main binary not found"

Error: main binary not found: ./PhotinoAOT

Fix: Specify the correct binary name with --binary:

python3 wrap_photino.py . --binary MyCustomBinary

"compilation failed"

Error: compilation failed:
gcc: command not found

Fix: Install GCC (see Prerequisites).

"no files to embed"

Error: no files to embed!

Fix: Make sure your project directory contains at least the main binary. The native library and wwwroot are optional.

Permission denied when running the wrapper

chmod +x PhotinoWrapper
./PhotinoWrapper

The application crashes at startup

Check that all required shared libraries are available on the target system.
Try running without --suppress-debug first to see error messages.
Verify the embedded binary works standalone: ./PhotinoAOT (from the original project dir).

🧬 How the Generated C Code Works

The generated C file is a self-extracting archive. Here's the anatomy:

1. Embedded Data

Each file becomes a static byte array:

static unsigned char file_PhotinoAOT[] = {
    0x7f, 0x45, 0x4c, 0x46, 0x02, 0x01, 0x01, 0x00,
    // ... thousands of bytes ...
};
static unsigned int file_PhotinoAOT_len = 14582880;

2. Helper Functions

write_file() — Writes binary data to a file and sets permissions.
mkdir_p() — Recursively creates directories (like mkdir -p).
cleanup_files() — Removes all extracted files and directories in reverse order.

3. Main Logic

int main(int argc, char *argv[]) {
    // 1. Create temp directory
    mkdtemp("/tmp/photino_wrapper_XXXXXX");

    // 2. Write all embedded files
    write_file("...", file_xxx, file_xxx_len, 0755);

    // 3. Set LD_LIBRARY_PATH
    setenv("LD_LIBRARY_PATH", tmpdir, 1);

    // 4. chdir to temp directory
    chdir(tmpdir);

    // 5. Fork and execute
    pid = fork();
    if (pid == 0) {
        // Child: optionally suppress output, then exec
        if (suppress_debug) {
            dup2(devnull, STDOUT_FILENO);
            dup2(devnull, STDERR_FILENO);
        }
        execv("PhotinoAOT", argv);
    } else {
        // Parent: wait, cleanup, return exit code
        waitpid(pid, &status, 0);
        cleanup_files(tmpdir);
        return exit_code;
    }
}

Why `fork()`?

The wrapper uses fork() so that:

The parent process can clean up the temporary directory after the child exits.
The child inherits the modified environment (LD_LIBRARY_PATH, working directory).
The child's exit code is propagated back to the caller.

🔒 Security Considerations

Temporary files are created in /tmp/ with a random suffix (XXXXXX), making name collisions extremely unlikely.
Cleanup is guaranteed — the parent process always calls cleanup_files() after the child exits, regardless of the child's exit status.
No setuid/setgid bits are preserved on extracted files.
--suppress-debug discards all output — useful for hiding sensitive paths or debug info in production.

⚠️ Note: The embedded binary runs with the same privileges as the user who launches the wrapper. There is no sandboxing.

📄 License

This script is provided as-is. Use it freely in your own projects.

🏁 Summary

Feature	Supported
Single-file output	✅
Preserves file permissions	✅
Automatic cleanup	✅
Debug output suppression	✅
Static linking (wrapper)	✅
Custom file names	✅
Cross-distro portable	✅ (with `--static`)
Windows / macOS	❌ (Linux only)

Pro tip: Combine --suppress-debug with --static for a production-ready, silent, portable kiosk application in one command:
python3 wrap_photino.py ./publish --static --suppress-debug -o MyKioskApp

wrap_photino.py

#!/usr/bin/env python3
"""
wrap_photino.py - Bundle Photino AOT into single executable with debug suppression.
Final version: suppresses both stdout and stderr.

Usage:
    python3 wrap_photino_final.py <project_dir> [--output <name>] [--suppress-debug]
"""

import os
import sys
import subprocess
import tempfile
import argparse


def bin2c(data, varname):
    """Convert binary data to a C byte array."""
    lines = [f"static unsigned char {varname}[] = {{"]
    for i in range(0, len(data), 12):
        chunk = data[i:i+12]
        hex_bytes = ", ".join(f"0x{b:02x}" for b in chunk)
        lines.append(f"    {hex_bytes},")
    lines.append("};")
    lines.append(f"static unsigned int {varname}_len = {len(data)};")
    return "\n".join(lines)


def generate_c_wrapper(files, suppress_debug=False):
    """Generate C source code for wrapper."""
    parts = []
    parts.append("""/*
 * Photino Single-File Wrapper
 * Suppresses both stdout and stderr if --suppress-debug is used
 */

#define _GNU_SOURCE
#include <stdio.h>
#include <stdlib.h>
#include <string.h>
#include <unistd.h>
#include <sys/stat.h>
#include <sys/types.h>
#include <sys/wait.h>
#include <errno.h>
#include <libgen.h>
#include <fcntl.h>

""")

    # Generate embedded data
    var_names = {}
    for rel_path, (data, mode) in sorted(files.items()):
        varname = "file_" + rel_path.replace("/", "_").replace(".", "_").replace("-", "_")
        var_names[rel_path] = (varname, mode)
        parts.append(bin2c(data, varname))
        parts.append("")

    parts.append("""
static int write_file(const char *path,
                      const unsigned char *data,
                      unsigned int len, int mode)
{
    FILE *f = fopen(path, "wb");
    if (!f) {
        fprintf(stderr, "Error: cannot write %s: %s\\n",
                path, strerror(errno));
        return -1;
    }
    if (fwrite(data, 1, len, f) != len) {
        fprintf(stderr, "Error: short write to %s\\n", path);
        fclose(f);
        return -1;
    }
    fclose(f);
    if (chmod(path, mode) != 0) {
        fprintf(stderr, "Error: chmod %s: %s\\n",
                path, strerror(errno));
        return -1;
    }
    return 0;
}

static int mkdir_p(const char *dir) {
    char tmp[4096];
    char *p = NULL;
    size_t len;

    snprintf(tmp, sizeof(tmp), "%s", dir);
    len = strlen(tmp);
    if (tmp[len - 1] == '/')
        tmp[len - 1] = 0;
    for (p = tmp + 1; *p; p++) {
        if (*p == '/') {
            *p = 0;
            mkdir(tmp, 0755);
            *p = '/';
        }
    }
    return mkdir(tmp, 0755);
}

static void cleanup_files(const char *tmpdir)
{
    char path[4096];
""")

    # Cleanup code
    parts.append("    /* Clean up all embedded files */")
    for rel_path in reversed(sorted(files.keys(), key=lambda x: -x.count('/'))):
        parts.append(f'    snprintf(path, sizeof(path), "%s/{rel_path}", tmpdir);')
        parts.append('    (void)unlink(path);')

    dirs = set()
    for rel_path in files:
        d = os.path.dirname(rel_path)
        if d:
            dirs.add(d)

    parts.append("    /* Clean up directory structure */")
    for d in reversed(sorted(dirs, key=lambda x: -x.count('/'))):
        parts.append(f'    snprintf(path, sizeof(path), "%s/{d}", tmpdir);')
        parts.append('    (void)rmdir(path);')

    parts.append('    (void)rmdir(tmpdir);')
    parts.append('}')
    parts.append('')

    parts.append("""int main(int argc, char *argv[]) {
    char tmpdir[4096];
    char path[4096];
    char *env;
    char new_ld_path[8192];
    const char *main_binary;
    pid_t pid;
    int status;
    int devnull = -1;

    /* Create a temporary directory */
    snprintf(tmpdir, sizeof(tmpdir), "/tmp/photino_wrapper_XXXXXX");
    if (mkdtemp(tmpdir) == NULL) {
        fprintf(stderr, "Error: mkdtemp failed: %s\\n", strerror(errno));
        return 1;
    }

""")

    # Find main binary
    main_binary_name = None
    for rel_path, (data, mode) in sorted(files.items()):
        if mode & 0o111:
            main_binary_name = rel_path
            break
    if not main_binary_name:
        main_binary_name = "PhotinoAOT"

    # Collect directories
    dirs = set()
    for rel_path in files:
        d = os.path.dirname(rel_path)
        if d:
            dirs.add(d)

    # Create directories
    parts.append("    /* Create directory structure */")
    for d in sorted(dirs):
        parts.append(f'    snprintf(path, sizeof(path), "%s/{d}", tmpdir);')
        parts.append('    mkdir_p(path);')
    parts.append("")

    # Write files
    parts.append("    /* Write all files */")
    for rel_path, (data, mode) in sorted(files.items()):
        varname, file_mode = var_names[rel_path]
        parts.append(f'    snprintf(path, sizeof(path), "%s/{rel_path}", tmpdir);')
        parts.append(f'    if (write_file(path, {varname}, {varname}_len, 0{oct(mode)[2:]}) != 0) {{')
        parts.append('        cleanup_files(tmpdir);')
        parts.append('        return 1;')
        parts.append('    }')
    parts.append("")

    # Set LD_LIBRARY_PATH
    parts.append("    /* Set LD_LIBRARY_PATH */")
    parts.append('    env = getenv("LD_LIBRARY_PATH");')
    parts.append('    if (env && env[0]) {')
    parts.append('        snprintf(new_ld_path, sizeof(new_ld_path), "%s:%s", tmpdir, env);')
    parts.append('    } else {')
    parts.append('        snprintf(new_ld_path, sizeof(new_ld_path), "%s", tmpdir);')
    parts.append('    }')
    parts.append('    setenv("LD_LIBRARY_PATH", new_ld_path, 1);')
    parts.append("")

    # Change directory
    parts.append("    /* Change to temp directory */")
    parts.append('    if (chdir(tmpdir) != 0) {')
    parts.append('        fprintf(stderr, "Error: chdir to %s: %s\\n", tmpdir, strerror(errno));')
    parts.append('        cleanup_files(tmpdir);')
    parts.append('        return 1;')
    parts.append('    }')
    parts.append("")

    # If suppressing debug, open /dev/null now (before fork)
    if suppress_debug:
        parts.append('    /* Suppress output: open /dev/null */')
        parts.append('    devnull = open("/dev/null", O_WRONLY);')
        parts.append('    if (devnull < 0) {')
        parts.append('        devnull = open("/dev/null", O_WRONLY | O_CREAT, 0666);')
        parts.append('    }')
        parts.append('')

    # Fork and execute
    parts.append('    /* Fork child process */')
    parts.append('    pid = fork();')
    parts.append('    if (pid < 0) {')
    parts.append('        fprintf(stderr, "Error: fork failed: %s\\n", strerror(errno));')
    parts.append('        cleanup_files(tmpdir);')
    parts.append('        return 1;')
    parts.append('    }')
    parts.append('')
    parts.append('    if (pid == 0) {')
    parts.append('        /* Child process */')

    if suppress_debug:
        parts.append('        /* Suppress BOTH stdout and stderr */')
        parts.append('        if (devnull >= 0) {')
        parts.append('            fflush(stdout);')
        parts.append('            fflush(stderr);')
        parts.append('            dup2(devnull, STDOUT_FILENO);  /* Redirect stdout */')
        parts.append('            dup2(devnull, STDERR_FILENO);  /* Redirect stderr */')
        parts.append('            close(devnull);')
        parts.append('        }')
        parts.append('')

    parts.append(f'        execv("{main_binary_name}", argv);')
    parts.append('        fprintf(stderr, "Error: execv failed: %s\\n", strerror(errno));')
    parts.append('        exit(127);')
    parts.append('    } else {')
    parts.append('        /* Parent process */')
    if suppress_debug:
        parts.append('        if (devnull >= 0) close(devnull);')
    parts.append('        int exit_code;')
    parts.append('        waitpid(pid, &status, 0);')
    parts.append('        exit_code = WIFEXITED(status) ? WEXITSTATUS(status) : 1;')
    parts.append('        cleanup_files(tmpdir);')
    parts.append('        return exit_code;')
    parts.append('    }')
    parts.append('}')

    return "\n".join(parts)


def main():
    parser = argparse.ArgumentParser(
        description="Bundle Photino AOT project into single executable."
    )
    parser.add_argument("project_dir", nargs="?", default=".",
                        help="Directory containing Photino project files")
    parser.add_argument("--output", "-o", default=None,
                        help="Output executable name (default: PhotinoWrapper)")
    parser.add_argument("--binary", "-b", default="PhotinoAOT",
                        help="Name of main executable (default: PhotinoAOT)")
    parser.add_argument("--native", "-n", default="Photino.Native.so",
                        help="Name of native library (default: Photino.Native.so)")
    parser.add_argument("--wwwroot", "-w", default="wwwroot",
                        help="Name of web root directory (default: wwwroot)")
    parser.add_argument("--static", "-s", action="store_true",
                        help="Statically link wrapper")
    parser.add_argument("--keep-c", action="store_true",
                        help="Keep generated .c file")
    parser.add_argument("--suppress-debug", action="store_true",
                        help="Suppress ALL output (stdout + stderr)")

    args = parser.parse_args()
    project_dir = args.project_dir

    files = {}

    # Main binary
    binary_path = os.path.join(project_dir, args.binary)
    if not os.path.isfile(binary_path):
        print(f"Error: main binary not found: {binary_path}", file=sys.stderr)
        sys.exit(1)

    with open(binary_path, "rb") as f:
        files[args.binary] = (f.read(), 0o755)
    print(f"  {args.binary}: {len(files[args.binary][0])} bytes")

    # Native library
    native_path = os.path.join(project_dir, args.native)
    if os.path.isfile(native_path):
        with open(native_path, "rb") as f:
            files[args.native] = (f.read(), 0o644)
        print(f"  {args.native}: {len(files[args.native][0])} bytes")

    # wwwroot
    wwwroot_path = os.path.join(project_dir, args.wwwroot)
    if os.path.isdir(wwwroot_path):
        for root, dirs, filenames in os.walk(wwwroot_path):
            for fn in filenames:
                full_path = os.path.join(root, fn)
                rel_path = os.path.relpath(full_path, project_dir)
                with open(full_path, "rb") as f:
                    files[rel_path] = (f.read(), 0o644)
                print(f"  {rel_path}: {len(files[rel_path][0])} bytes")

    if not files:
        print("Error: no files to embed!", file=sys.stderr)
        sys.exit(1)

    total_size = sum(len(d) for d, _ in files.values())
    print(f"\nTotal embedded data: {total_size} bytes")

    print("\nGenerating C wrapper...")
    c_source = generate_c_wrapper(files, args.suppress_debug)

    output_name = args.output or "PhotinoWrapper"

    c_fd, c_path = tempfile.mkstemp(suffix=".c", prefix="photino_wrapper_")
    os.close(c_fd)
    with open(c_path, "w") as f:
        f.write(c_source)

    print(f"Generated C source: {len(c_source)} bytes")
    if args.suppress_debug:
        print("Output suppression: ENABLED (stdout + stderr)")

    print("Compiling...")
    compile_cmd = ["gcc", "-O2", "-s", "-o", output_name, c_path]
    if args.static:
        compile_cmd.append("-static")

    result = subprocess.run(compile_cmd, capture_output=True, text=True)
    if result.returncode != 0:
        print(f"Error: compilation failed:\n{result.stderr}", file=sys.stderr)
        os.unlink(c_path)
        sys.exit(1)

    if not args.keep_c:
        os.unlink(c_path)

    wrapper_size = os.path.getsize(output_name)
    overhead = wrapper_size - total_size
    print(f"\nOutput: {output_name} ({wrapper_size} bytes)")
    print(f"Overhead: {overhead} bytes ({overhead * 100 / total_size:.1f}%)")
    print("Done!")


if __name__ == "__main__":
    main()

TerminaReactive TUI Framework for .NET

artydev — Fri, 07 Aug 2026 08:43:28 +0000

Termina is a stupend library to create wonderfull TUI apps.

Here a llm.txt to use it:

Termina: Reactive Terminal UI Framework for .NET

Overview

Termina is a reactive terminal UI (TUI) framework for .NET that enables developers to build beautiful, interactive terminal applications with declarative layouts and reactive state management. It provides an MVVM architecture with automatic UI updates, ASP.NET Core-style routing, and seamless integration with Microsoft.Extensions.DependencyInjection and Microsoft.Extensions.Hosting.

Version: 0.15.1 (at documentation time)
License: Apache 2.0
Repository: https://github.com/Aaronontheweb/Termina
Documentation: https://aaronstannard.com/termina/
NuGet Package: https://www.nuget.org/packages/Termina

Key Features

Reactive MVVM Architecture

ViewModels use ReactiveProperty<T> for observable state management
Source-generated reactive properties with no boilerplate required
ReactiveProperty<T> is both a value holder and an Observable<T> for automatic UI updates
Full integration with R3 observables library (migrated from System.Reactive in v0.7.0)

Declarative Layouts

Tree-based layout system for composing complex UIs
Fluent API with .WithChild() for clean composition
Support for Vertical, Horizontal, Grid, and Stack layouts
Size constraints: Fixed, Fill, Auto, and Percent
Nesting layouts for complex UI composition
Responsive design with terminal resize support

Surgical Region-Based Rendering

Only changed regions re-render, not the entire screen
Enables smooth streaming updates for real-time content
Direct ANSI rendering with zero external rendering dependencies
Surgical updates for efficient terminal performance

ASP.NET Core-Style Routing

Type-safe route parameters with templates like /tasks/{id:int}
Route parameter injection via [FromRoute] attribute
Navigation via Navigate() and NavigateWithParams()
Full type constraint support for route parameters

Source Generators

AOT (Ahead-of-Time) compatible code generation
Native AOT publishing support with single-file executables
Zero reflection approach for performance

Streaming Support

Native StreamingTextNode for token-by-token content rendering
Ideal for LLM output, real-time logs, and live data streams
Character-level subscription updates for smooth rendering

Dependency Injection

Full integration with Microsoft.Extensions.DependencyInjection
Works seamlessly with Microsoft.Extensions.Hosting
Allows clean lifecycle management and service composition

Testing Support

VirtualInputSource for automated testing with scripted input
Test mode detection for CI/CD integration
Deterministic input replay for regression testing

Installation

Requirements

.NET 10.0 SDK or later
Terminal emulator with ANSI support (Windows Terminal, iTerm2, etc.)

Package Installation

dotnet add package Termina
dotnet add package Microsoft.Extensions.Hosting

Core Architecture

The Three-Part Pattern

Termina applications follow an MVVM pattern with three key components:

1. ViewModel

Inherits from ReactiveViewModel
Manages application state using ReactiveProperty<T>
Handles keyboard input via Input.OfType<KeyPressed>()
Provides navigation and shutdown actions
Must dispose all ReactiveProperty<T> instances in Dispose() method
Implements OnActivated() for initialization logic

2. Page

Inherits from ReactivePage<TViewModel>
Builds UI layout in BuildLayout() method
Implements reactive bindings via .Select(...).AsLayout() pattern
Manages focus for modals and interactive controls
Optionally implements OnBound() for additional initialization

3. Host Configuration

Uses Microsoft.Extensions.Hosting for lifecycle management
Registers routes via AddTermina() and RegisterRoute<TPage, TViewModel>()
Supports virtual input for testing

Reactive Property Pattern

ReactiveProperty<T> is the foundation of Termina's reactivity:

Holds a value accessible via .Value property
Emits observables when value changes
Built-in DistinctUntilChanged behavior (only emits on actual value change)
Used in layout bindings: ViewModel.Count.Select(...).AsLayout()
Must be disposed properly to prevent memory leaks

Layout System

How Layout Works

The layout system processes node trees in two phases:

1. Measure Phase: Starting from root, each node calculates how much space it needs given available space. Container nodes recursively measure children.

2. Render Phase: Once measurements are complete, each node receives final bounds and renders to the terminal.

Layout Nodes vs. Container Nodes

Layout Nodes (render content):

TextNode - Styled text with word wrapping
PanelNode - Bordered container with title
SpinnerNode - Animated loading indicator
StreamingTextNode - Streaming content with scrolling
GraphNode - Live scrolling graph with gradient coloring
ProgressBarNode - Progress bar with gradient fill and label
TextInputNode - Single-line text input with cursor
TextAreaNode - Multi-line text input with word wrap
CopyableTextNode - Read-only text with clipboard support
SelectionListNode - Interactive list selection
FilePickerNode - File/folder picker

Container Nodes (arrange children):

VerticalLayout - Stack children top-to-bottom
HorizontalLayout - Stack children left-to-right
GridNode - 2D grid with consistent column/row sizing
StackLayout - Overlay children (z-stack)
ScrollableContainer - Scrollable content area
ModalNode - Modal overlay with backdrop

Size Constraints

Four constraint types control sizing:

Constraint	Description	Example
`Fixed(n)`	Exactly n rows/columns	`.Height(3)`
`Fill(weight)`	Take remaining space	`.Fill()` or `.Fill(2)`
`Auto`	Size to content	`.HeightAuto()`
`Percent(n)`	n% of available space	`.Height(SizeConstraint.Percent(50))`

Common Layout Patterns

Vertical stacking with header, content, footer:

Layouts.Vertical()
    .WithChild(header.Height(3))      // Fixed height
    .WithChild(content.Fill())        // Take remaining space
    .WithChild(footer.Height(1));

Horizontal layout with weighted fills:

Layouts.Horizontal()
    .WithChild(menu.Width(30))
    .WithChild(main.Fill(2))          // 2x weight
    .WithChild(aside.Fill(1));        // 1x weight

Nested layouts:

Layouts.Vertical()
    .WithChild(
        Layouts.Horizontal()
            .WithChild(sidebar.Width(20))
            .WithChild(content.Fill())
    )
    .WithChild(footer.Height(1));

Component Library

Display Components

TextNode

Renders styled text with word wrapping
Supports foreground/background colors
Methods: .Bold(), .Dim(), .Italic(), .Underline(), .Strike(), .WithForeground(), .NoWrap()

PanelNode

Bordered container with optional title
Border styles: BorderStyle.Single, BorderStyle.Double, BorderStyle.Rounded
Methods: .WithTitle(), .WithBorder(), .WithBorderColor(), .WithTitleColor(), .WithContent()

SpinnerNode

Animated loading indicator
Various spinner styles available

StreamingTextNode

For real-time, token-by-token content rendering
Created via StreamingTextNode.Create()
Add content: .Append(chunk)
Subscription pattern for ViewModel observables

GraphNode

Live scrolling graph with gradient coloring

ProgressBarNode

Progress bar with gradient fill and label

Input Components

TextInputNode

Single-line text input with cursor
Keyboard input handling

TextAreaNode

Multi-line text input
Word wrap and vertical scrolling

SelectionListNode

Interactive list selection
Keyboard navigation

FilePickerNode

File/folder picker with directory navigation

CopyableTextNode

Read-only text with keyboard selection and clipboard support

Container Components

ScrollableContainer

Vertical scrolling container for overflow content

StackLayout

Overlapping children (z-stack) for layering

ModalNode

Modal overlay with backdrop

Reactive Components

ReactiveLayoutNode

Updates content from observables

ConditionalNode

Show/hide content based on condition

DynamicLayoutNode

Re-evaluates factory on invalidation

KeyedDynamicLayoutNode

Key-based content switching with caching

WizardNode

Multi-step wizard with progress, navigation, and focus

Utility Components

EmptyNode

Placeholder that renders nothing

DeferredNode

Delegates to node without owning it

Input Handling

Keyboard Input

Input is accessed via Input.OfType<IInputEvent, KeyPressed>() in ViewModels:

public override void OnActivated()
{
    Input.OfType<IInputEvent, KeyPressed>()
        .Subscribe(HandleKeyPress)
        .DisposeWith(Subscriptions);
}

private void HandleKeyPress(KeyPressed key)
{
    switch (key.KeyInfo.Key)
    {
        case ConsoleKey.UpArrow:
            // Handle up arrow
            break;
        case ConsoleKey.Enter:
            // Handle enter
            break;
        case ConsoleKey.Escape:
            Shutdown();
            break;
        default:
            // Handle printable characters
            if (key.KeyInfo.KeyChar >= 32 && key.KeyInfo.KeyChar < 127)
            {
                // Character input
            }
            break;
    }
}

Printable Character Handling

Access the character via key.KeyInfo.KeyChar property.

Shutdown

Call Shutdown() to exit the application.

Routing

Route Registration

Routes are registered during host configuration:

builder.Services.AddTermina("/", termina =>
{
    termina.RegisterRoute<HomePage, HomeViewModel>("/");
    termina.RegisterRoute<TasksPage, TasksViewModel>("/tasks");
    termina.RegisterRoute<TaskDetailPage, TaskDetailViewModel>("/tasks/{id:int}");
    termina.RegisterRoute<UserPage, UserViewModel>("/users/{name}");
});

Route Parameters

Routes support type-safe parameters with type constraints:

// Route template with parameter
"/tasks/{id:int}"

// ViewModel with route parameter injection
public partial class TaskDetailViewModel : ReactiveViewModel
{
    [FromRoute] private int _id;  // Injected from route

    public override void OnActivated()
    {
        LoadTask(Id);  // Id is already populated
    }
}

Navigation

Navigate between routes programmatically:

// Simple navigation
Navigate("/tasks/42");

// With parameters
NavigateWithParams("/tasks/{id}", new { id = 42 });

// Exit application
Shutdown();

Styling and Colors

Color System

Termina supports ANSI colors:

Basic colors: Color.Black, Color.Red, Color.Green, Color.Yellow, Color.Blue, Color.Magenta, Color.Cyan, Color.White, Color.Gray
Bright variants: Color.BrightRed, Color.BrightGreen, etc.

Text Styling

Apply styling via fluent API:

.WithForeground(Color.Cyan) - Text color
.WithBackground(Color.Black) - Background color
.Bold() - Bold text
.Dim() - Dimmed text
.Italic() - Italic text
.Underline() - Underlined text
.Strike() - Strikethrough text

Word Wrapping

Control text wrapping:

.NoWrap() - Disable word wrapping, truncate at edge

Reactive Bindings

Observable to Layout Pattern

Convert observables to layout nodes:

ViewModel.Count
    .Select<int, ILayoutNode>(count => new TextNode($"Count: {count}")
        .WithForeground(Color.BrightCyan))
    .AsLayout()

Multiple Observable Bindings

Combine multiple observables:

Observable.CombineLatest(
    ViewModel.Title,
    ViewModel.Message
)
.Select(x => new TextNode($"{x[0]}: {x[1]}").WithForeground(Color.Cyan))
.AsLayout()

Streaming Content Pattern

For real-time content like LLM output:

// In Page
private StreamingTextNode _output = null!;

protected override void OnBound()
{
    _output = StreamingTextNode.Create();
    ViewModel.StreamOutput.Subscribe(chunk => _output.Append(chunk));
}

// In ViewModel
public Observable<string> StreamOutput => _streamOutput;
private readonly Subject<string> _streamOutput = new();

private async Task StreamResponse()
{
    await foreach (var chunk in GetStreamingData())
    {
        _streamOutput.OnNext(chunk);  // Character-level updates
    }
}

Testing

VirtualInputSource

Use VirtualInputSource for automated testing with scripted input:

var scriptedInput = new VirtualInputSource();
builder.Services.AddTerminaVirtualInput(scriptedInput);

// Queue input
scriptedInput.EnqueueKey(ConsoleKey.UpArrow);
scriptedInput.EnqueueString("Hello World");
scriptedInput.EnqueueKey(ConsoleKey.Enter);
scriptedInput.Complete();

await host.RunAsync();

Test Mode Detection

Detect test mode with command-line flag:

var testMode = args.Contains("--test");

if (testMode)
{
    var scriptedInput = new VirtualInputSource();
    builder.Services.AddTerminaVirtualInput(scriptedInput);

    // Queue test inputs
    scriptedInput.EnqueueKey(ConsoleKey.UpArrow);
    // ... more inputs
    scriptedInput.Complete();
}

Complete Application Template

Step 1: Define ViewModel

using R3;
using Termina.Input;
using Termina.Reactive;

public class CounterViewModel : ReactiveViewModel
{
    public ReactiveProperty<int> Count { get; } = new(0);
    public ReactiveProperty<string> Message { get; } = new("Press Up/Down");

    public override void OnActivated()
    {
        Input.OfType<IInputEvent, KeyPressed>()
            .Subscribe(HandleKey)
            .DisposeWith(Subscriptions);
    }

    private void HandleKey(KeyPressed key)
    {
        switch (key.KeyInfo.Key)
        {
            case ConsoleKey.UpArrow:
                Count.Value++;
                Message.Value = $"Count: {Count.Value}";
                break;
            case ConsoleKey.DownArrow:
                Count.Value--;
                Message.Value = $"Count: {Count.Value}";
                break;
            case ConsoleKey.Escape:
                Shutdown();
                break;
        }
    }

    public override void Dispose()
    {
        Count.Dispose();
        Message.Dispose();
        base.Dispose();
    }
}

Step 2: Define Page

using R3;
using Termina.Extensions;
using Termina.Layout;
using Termina.Reactive;
using Termina.Rendering;
using Termina.Terminal;

public class CounterPage : ReactivePage<CounterViewModel>
{
    public override ILayoutNode BuildLayout()
    {
        return Layouts.Vertical()
            .WithChild(
                new PanelNode()
                    .WithTitle("Counter Demo")
                    .WithBorder(BorderStyle.Rounded)
                    .WithBorderColor(Color.Cyan)
                    .WithContent(
                        ViewModel.Count
                            .Select<int, ILayoutNode>(count => new TextNode($"Count: {count}")
                                .WithForeground(Color.BrightCyan))
                            .AsLayout())
                    .Height(5))
            .WithChild(
                ViewModel.Message
                    .Select<string, ILayoutNode>(msg => new TextNode(msg))
                    .AsLayout()
                    .Height(1));
    }
}

Step 3: Configure Host

using Microsoft.Extensions.Hosting;
using Termina.Hosting;

var builder = Host.CreateApplicationBuilder(args);

// Optional: suppress host logging
builder.Logging.SetMinimumLevel(LogLevel.Warning);

// Register Termina
builder.Services.AddTermina("/counter", termina =>
{
    termina.RegisterRoute<CounterPage, CounterViewModel>("/counter");
});

var host = builder.Build();
await host.RunAsync();

Common Patterns

List Display

ViewModel.Items
    .Select<List<string>, ILayoutNode>(items => new TextNode(
        string.Join("\n", items.Take(10))  // Show first 10 items
    ))
    .AsLayout()

Status Display with Reactive Updates

new PanelNode()
    .WithTitle("Status")
    .WithContent(
        Observable.CombineLatest(
            ViewModel.Status,
            ViewModel.Progress
        )
        .Select(x => new TextNode($"{x[0]} - {x[1]}%"))
        .AsLayout()
    )

Modal Dialog

new ModalNode()
    .WithTitle("Confirm")
    .WithContent(new TextNode("Are you sure?"))
    .WithBackdrop(true)

Scrollable Content

new ScrollableContainer()
    .WithChild(contentNode)
    .Height(20)

Loading Indicator

new SpinnerNode()
    .WithLabel("Loading...")

Performance Considerations

Surgical Rendering: Only changed regions re-render automatically
ReactiveProperty Disposal: Always dispose in ViewModel.Dispose()
Subscription Management: Use .DisposeWith(Subscriptions) in OnActivated()
String Concatenation: For frequently updated content, consider StringBuilder
Observable Subscriptions: Subscribe only to properties that change in BuildLayout()

Breaking Changes

Version 0.7.0

Migrated from System.Reactive to R3
R3 observable syntax may differ slightly from System.Reactive
See migration guide at https://aaronstannard.com/termina/guide/migration-0.7.html

Version 0.11.0

Changes to render loop threading
See upgrade guide at https://aaronstannard.com/termina/guide/upgrade-0.11.html

Resources

Official Documentation: https://aaronstannard.com/termina/
GitHub Repository: https://github.com/Aaronontheweb/Termina
NuGet Package: https://www.nuget.org/packages/Termina
Author: Aaron Stannard (https://aaronstannard.com/)
License: Apache 2.0

Akka.NET Integration Potential

While Termina doesn't have a hard dependency on Akka.NET, the framework was created by Aaron Stannard, who also founded Akka.NET. This creates significant architectural synergy opportunities:

Observable-to-Observable Bridge

Termina's R3 observables can integrate with Akka.NET's streaming infrastructure:

// Termina observable to Akka.Streams
public ReactiveProperty<string> MessageStream { get; } = new("");

// Bridge to Akka.Streams
Source.FromObservable(ViewModel.MessageStream)
    .RunForEach(msg => {
        // Process Akka.NET actor messages into Termina UI
    });

Actor-Based Backend with Termina UI

Use Akka.NET actors for backend logic and Termina for the TUI frontend:

// Host configuration with both Akka.NET and Termina
var builder = Host.CreateApplicationBuilder(args);

// Register Akka.NET
builder.Services.AddAkka("termina-app", configBuilder => {
    configBuilder.AddActorSystem();
});

// Register Termina
builder.Services.AddTermina("/dashboard", termina => {
    termina.RegisterRoute<DashboardPage, DashboardViewModel>("/dashboard");
});

Real-Time Dashboard Pattern

Common use case: Use Akka.NET actors to process distributed data and Termina to display it:

Akka.NET: Handles concurrent data aggregation, event sourcing, clustering
Termina: Displays real-time metrics with surgical rendering and responsive UI
Integration: R3 observables bridge actor state to UI bindings

Streaming Architecture

Akka.Streams integrates with observables (since version 1.3.2):

// Expose Akka.Streams as observable
IObservable<T> observable = akkaStream.RunWith(Sink.AsObservable<T>(), materializer);

// Use in Termina UI
observable
    .Select(item => new TextNode($"{item}"))
    .AsLayout()

Backpressure and Flow Control

Akka.Streams offers backpressure awareness that R3 observables can leverage:

Prevents UI from being overwhelmed by rapid state changes
Buffers with configurable overflow strategies
Maintains responsiveness under high-volume actor message streams

Testing Distributed Systems

Combine Akka.TestKit with Termina's VirtualInputSource for end-to-end testing:

// Test Akka actors and their UI representation
var probe = CreateTestProbe();
var actorRef = ActorOf<MyActor>();

// Verify UI behavior with scripted input
var scriptedInput = new VirtualInputSource();
builder.Services.AddTerminaVirtualInput(scriptedInput);

// Send messages to actor, verify UI updates
actorRef.Tell(new MyMessage());
scriptedInput.EnqueueKey(ConsoleKey.Enter);

Deployment Scenarios

Single-Node Monitor:

Termina TUI for local terminal-based dashboards
Akka.NET local actors for data collection

Distributed Monitoring:

Akka.Cluster processes data on multiple nodes
Termina TUI on each node for local monitoring
Akka.Remote for inter-node communication

CLI Tools with Actor Backend:

Termina provides interactive CLI interface
Akka.NET handles long-running background tasks
Observable streams bridge progress/status updates

Related Concepts

MVVM Pattern: Model-View-ViewModel architectural pattern
Reactive Programming: Using observables for state management
Terminal UI (TUI): Text-based user interfaces in terminal/console
ANSI Escape Codes: Terminal formatting and color codes
Dependency Injection: Microsoft.Extensions.DependencyInjection
Async/Await: Asynchronous programming model for .NET
R3 Observables: Modern reactive extensions library for .NET
Akka.NET: Actor model framework for distributed/concurrent systems
Akka.Streams: Stream processing with backpressure on top of actors
Microsoft.Extensions.Hosting: Host lifecycle management

Summary

Termina is a production-ready, modern terminal UI framework that brings ASP.NET Core patterns to terminal applications. Its reactive architecture, surgical rendering, and declarative layout system make it ideal for building interactive CLI tools, dashboards, monitoring applications, and any text-based UI that needs real-time updates. The framework's AOT compatibility ensures you can deploy single-file executables for any platform.

Complementary Technologies

Aaron Stannard (Termina's creator) is also the founder of Akka.NET, which creates natural architectural synergy:

Termina: Excellent for responsive, declarative TUI layer
Akka.NET: Ideal for concurrent, distributed, fault-tolerant backend
Observable Bridge: R3 observables seamlessly connect actor state to UI updates

For systems requiring both sophisticated backend logic (actor model, distributed processing, event sourcing) and interactive terminal interfaces (dashboards, monitoring, real-time displays), combining Akka.NET and Termina provides a cohesive, modern development experience across the full stack.

TerminaReactive TUI Framework for .NET

artydev — Fri, 07 Aug 2026 08:37:59 +0000

Termina is a stupend library to create wonderfull TUI apps.

Here a llm.txt to use it:

Termina: Reactive Terminal UI Framework for .NET

Overview

Key Features

Reactive MVVM Architecture

ViewModels use ReactiveProperty<T> for observable state management
Source-generated reactive properties with no boilerplate required
ReactiveProperty<T> is both a value holder and an Observable<T> for automatic UI updates
Full integration with R3 observables library (migrated from System.Reactive in v0.7.0)

Declarative Layouts

Tree-based layout system for composing complex UIs
Fluent API with .WithChild() for clean composition
Support for Vertical, Horizontal, Grid, and Stack layouts
Size constraints: Fixed, Fill, Auto, and Percent
Nesting layouts for complex UI composition
Responsive design with terminal resize support

Surgical Region-Based Rendering

Only changed regions re-render, not the entire screen
Enables smooth streaming updates for real-time content
Direct ANSI rendering with zero external rendering dependencies
Surgical updates for efficient terminal performance

ASP.NET Core-Style Routing

Type-safe route parameters with templates like /tasks/{id:int}
Route parameter injection via [FromRoute] attribute
Navigation via Navigate() and NavigateWithParams()
Full type constraint support for route parameters

Source Generators

AOT (Ahead-of-Time) compatible code generation
Native AOT publishing support with single-file executables
Zero reflection approach for performance

Streaming Support

Native StreamingTextNode for token-by-token content rendering
Ideal for LLM output, real-time logs, and live data streams
Character-level subscription updates for smooth rendering

Dependency Injection

Full integration with Microsoft.Extensions.DependencyInjection
Works seamlessly with Microsoft.Extensions.Hosting
Allows clean lifecycle management and service composition

Testing Support

VirtualInputSource for automated testing with scripted input
Test mode detection for CI/CD integration
Deterministic input replay for regression testing

Installation

Requirements

.NET 10.0 SDK or later
Terminal emulator with ANSI support (Windows Terminal, iTerm2, etc.)

Package Installation

dotnet add package Termina
dotnet add package Microsoft.Extensions.Hosting

Core Architecture

The Three-Part Pattern

Termina applications follow an MVVM pattern with three key components:

1. ViewModel

Inherits from ReactiveViewModel
Manages application state using ReactiveProperty<T>
Handles keyboard input via Input.OfType<KeyPressed>()
Provides navigation and shutdown actions
Must dispose all ReactiveProperty<T> instances in Dispose() method
Implements OnActivated() for initialization logic

2. Page

Inherits from ReactivePage<TViewModel>
Builds UI layout in BuildLayout() method
Implements reactive bindings via .Select(...).AsLayout() pattern
Manages focus for modals and interactive controls
Optionally implements OnBound() for additional initialization

3. Host Configuration

Uses Microsoft.Extensions.Hosting for lifecycle management
Registers routes via AddTermina() and RegisterRoute<TPage, TViewModel>()
Supports virtual input for testing

Reactive Property Pattern

ReactiveProperty<T> is the foundation of Termina's reactivity:

Holds a value accessible via .Value property
Emits observables when value changes
Built-in DistinctUntilChanged behavior (only emits on actual value change)
Used in layout bindings: ViewModel.Count.Select(...).AsLayout()
Must be disposed properly to prevent memory leaks

Layout System

How Layout Works

The layout system processes node trees in two phases:

1. Measure Phase: Starting from root, each node calculates how much space it needs given available space. Container nodes recursively measure children.

2. Render Phase: Once measurements are complete, each node receives final bounds and renders to the terminal.

Layout Nodes vs. Container Nodes

Layout Nodes (render content):

TextNode - Styled text with word wrapping
PanelNode - Bordered container with title
SpinnerNode - Animated loading indicator
StreamingTextNode - Streaming content with scrolling
GraphNode - Live scrolling graph with gradient coloring
ProgressBarNode - Progress bar with gradient fill and label
TextInputNode - Single-line text input with cursor
TextAreaNode - Multi-line text input with word wrap
CopyableTextNode - Read-only text with clipboard support
SelectionListNode - Interactive list selection
FilePickerNode - File/folder picker

Container Nodes (arrange children):

VerticalLayout - Stack children top-to-bottom
HorizontalLayout - Stack children left-to-right
GridNode - 2D grid with consistent column/row sizing
StackLayout - Overlay children (z-stack)
ScrollableContainer - Scrollable content area
ModalNode - Modal overlay with backdrop

Size Constraints

Four constraint types control sizing:

Constraint	Description	Example
`Fixed(n)`	Exactly n rows/columns	`.Height(3)`
`Fill(weight)`	Take remaining space	`.Fill()` or `.Fill(2)`
`Auto`	Size to content	`.HeightAuto()`
`Percent(n)`	n% of available space	`.Height(SizeConstraint.Percent(50))`

Common Layout Patterns

Vertical stacking with header, content, footer:

Layouts.Vertical()
    .WithChild(header.Height(3))      // Fixed height
    .WithChild(content.Fill())        // Take remaining space
    .WithChild(footer.Height(1));

Horizontal layout with weighted fills:

Layouts.Horizontal()
    .WithChild(menu.Width(30))
    .WithChild(main.Fill(2))          // 2x weight
    .WithChild(aside.Fill(1));        // 1x weight

Nested layouts:

Layouts.Vertical()
    .WithChild(
        Layouts.Horizontal()
            .WithChild(sidebar.Width(20))
            .WithChild(content.Fill())
    )
    .WithChild(footer.Height(1));

Component Library

Display Components

TextNode

Renders styled text with word wrapping
Supports foreground/background colors
Methods: .Bold(), .Dim(), .Italic(), .Underline(), .Strike(), .WithForeground(), .NoWrap()

PanelNode

Bordered container with optional title
Border styles: BorderStyle.Single, BorderStyle.Double, BorderStyle.Rounded
Methods: .WithTitle(), .WithBorder(), .WithBorderColor(), .WithTitleColor(), .WithContent()

SpinnerNode

Animated loading indicator
Various spinner styles available

StreamingTextNode

For real-time, token-by-token content rendering
Created via StreamingTextNode.Create()
Add content: .Append(chunk)
Subscription pattern for ViewModel observables

GraphNode

Live scrolling graph with gradient coloring

ProgressBarNode

Progress bar with gradient fill and label

Input Components

TextInputNode

Single-line text input with cursor
Keyboard input handling

TextAreaNode

Multi-line text input
Word wrap and vertical scrolling

SelectionListNode

Interactive list selection
Keyboard navigation

FilePickerNode

File/folder picker with directory navigation

CopyableTextNode

Read-only text with keyboard selection and clipboard support

Container Components

ScrollableContainer

Vertical scrolling container for overflow content

StackLayout

Overlapping children (z-stack) for layering

ModalNode

Modal overlay with backdrop

Reactive Components

ReactiveLayoutNode

Updates content from observables

ConditionalNode

Show/hide content based on condition

DynamicLayoutNode

Re-evaluates factory on invalidation

KeyedDynamicLayoutNode

Key-based content switching with caching

WizardNode

Multi-step wizard with progress, navigation, and focus

Utility Components

EmptyNode

Placeholder that renders nothing

DeferredNode

Delegates to node without owning it

Input Handling

Keyboard Input

Input is accessed via Input.OfType<IInputEvent, KeyPressed>() in ViewModels:

public override void OnActivated()
{
    Input.OfType<IInputEvent, KeyPressed>()
        .Subscribe(HandleKeyPress)
        .DisposeWith(Subscriptions);
}

private void HandleKeyPress(KeyPressed key)
{
    switch (key.KeyInfo.Key)
    {
        case ConsoleKey.UpArrow:
            // Handle up arrow
            break;
        case ConsoleKey.Enter:
            // Handle enter
            break;
        case ConsoleKey.Escape:
            Shutdown();
            break;
        default:
            // Handle printable characters
            if (key.KeyInfo.KeyChar >= 32 && key.KeyInfo.KeyChar < 127)
            {
                // Character input
            }
            break;
    }
}

Printable Character Handling

Access the character via key.KeyInfo.KeyChar property.

Shutdown

Call Shutdown() to exit the application.

Routing

Route Registration

Routes are registered during host configuration:

builder.Services.AddTermina("/", termina =>
{
    termina.RegisterRoute<HomePage, HomeViewModel>("/");
    termina.RegisterRoute<TasksPage, TasksViewModel>("/tasks");
    termina.RegisterRoute<TaskDetailPage, TaskDetailViewModel>("/tasks/{id:int}");
    termina.RegisterRoute<UserPage, UserViewModel>("/users/{name}");
});

Route Parameters

Routes support type-safe parameters with type constraints:

// Route template with parameter
"/tasks/{id:int}"

// ViewModel with route parameter injection
public partial class TaskDetailViewModel : ReactiveViewModel
{
    [FromRoute] private int _id;  // Injected from route

    public override void OnActivated()
    {
        LoadTask(Id);  // Id is already populated
    }
}

Navigation

Navigate between routes programmatically:

// Simple navigation
Navigate("/tasks/42");

// With parameters
NavigateWithParams("/tasks/{id}", new { id = 42 });

// Exit application
Shutdown();

Styling and Colors

Color System

Termina supports ANSI colors:

Basic colors: Color.Black, Color.Red, Color.Green, Color.Yellow, Color.Blue, Color.Magenta, Color.Cyan, Color.White, Color.Gray
Bright variants: Color.BrightRed, Color.BrightGreen, etc.

Text Styling

Apply styling via fluent API:

.WithForeground(Color.Cyan) - Text color
.WithBackground(Color.Black) - Background color
.Bold() - Bold text
.Dim() - Dimmed text
.Italic() - Italic text
.Underline() - Underlined text
.Strike() - Strikethrough text

Word Wrapping

Control text wrapping:

.NoWrap() - Disable word wrapping, truncate at edge

Reactive Bindings

Observable to Layout Pattern

Convert observables to layout nodes:

ViewModel.Count
    .Select<int, ILayoutNode>(count => new TextNode($"Count: {count}")
        .WithForeground(Color.BrightCyan))
    .AsLayout()

Multiple Observable Bindings

Combine multiple observables:

Observable.CombineLatest(
    ViewModel.Title,
    ViewModel.Message
)
.Select(x => new TextNode($"{x[0]}: {x[1]}").WithForeground(Color.Cyan))
.AsLayout()

Streaming Content Pattern

For real-time content like LLM output:

// In Page
private StreamingTextNode _output = null!;

protected override void OnBound()
{
    _output = StreamingTextNode.Create();
    ViewModel.StreamOutput.Subscribe(chunk => _output.Append(chunk));
}

// In ViewModel
public Observable<string> StreamOutput => _streamOutput;
private readonly Subject<string> _streamOutput = new();

private async Task StreamResponse()
{
    await foreach (var chunk in GetStreamingData())
    {
        _streamOutput.OnNext(chunk);  // Character-level updates
    }
}

Testing

VirtualInputSource

Use VirtualInputSource for automated testing with scripted input:

var scriptedInput = new VirtualInputSource();
builder.Services.AddTerminaVirtualInput(scriptedInput);

// Queue input
scriptedInput.EnqueueKey(ConsoleKey.UpArrow);
scriptedInput.EnqueueString("Hello World");
scriptedInput.EnqueueKey(ConsoleKey.Enter);
scriptedInput.Complete();

await host.RunAsync();

Test Mode Detection

Detect test mode with command-line flag:

var testMode = args.Contains("--test");

if (testMode)
{
    var scriptedInput = new VirtualInputSource();
    builder.Services.AddTerminaVirtualInput(scriptedInput);

    // Queue test inputs
    scriptedInput.EnqueueKey(ConsoleKey.UpArrow);
    // ... more inputs
    scriptedInput.Complete();
}

Complete Application Template

Step 1: Define ViewModel

using R3;
using Termina.Input;
using Termina.Reactive;

public class CounterViewModel : ReactiveViewModel
{
    public ReactiveProperty<int> Count { get; } = new(0);
    public ReactiveProperty<string> Message { get; } = new("Press Up/Down");

    public override void OnActivated()
    {
        Input.OfType<IInputEvent, KeyPressed>()
            .Subscribe(HandleKey)
            .DisposeWith(Subscriptions);
    }

    private void HandleKey(KeyPressed key)
    {
        switch (key.KeyInfo.Key)
        {
            case ConsoleKey.UpArrow:
                Count.Value++;
                Message.Value = $"Count: {Count.Value}";
                break;
            case ConsoleKey.DownArrow:
                Count.Value--;
                Message.Value = $"Count: {Count.Value}";
                break;
            case ConsoleKey.Escape:
                Shutdown();
                break;
        }
    }

    public override void Dispose()
    {
        Count.Dispose();
        Message.Dispose();
        base.Dispose();
    }
}

Step 2: Define Page

using R3;
using Termina.Extensions;
using Termina.Layout;
using Termina.Reactive;
using Termina.Rendering;
using Termina.Terminal;

public class CounterPage : ReactivePage<CounterViewModel>
{
    public override ILayoutNode BuildLayout()
    {
        return Layouts.Vertical()
            .WithChild(
                new PanelNode()
                    .WithTitle("Counter Demo")
                    .WithBorder(BorderStyle.Rounded)
                    .WithBorderColor(Color.Cyan)
                    .WithContent(
                        ViewModel.Count
                            .Select<int, ILayoutNode>(count => new TextNode($"Count: {count}")
                                .WithForeground(Color.BrightCyan))
                            .AsLayout())
                    .Height(5))
            .WithChild(
                ViewModel.Message
                    .Select<string, ILayoutNode>(msg => new TextNode(msg))
                    .AsLayout()
                    .Height(1));
    }
}

Step 3: Configure Host

using Microsoft.Extensions.Hosting;
using Termina.Hosting;

var builder = Host.CreateApplicationBuilder(args);

// Optional: suppress host logging
builder.Logging.SetMinimumLevel(LogLevel.Warning);

// Register Termina
builder.Services.AddTermina("/counter", termina =>
{
    termina.RegisterRoute<CounterPage, CounterViewModel>("/counter");
});

var host = builder.Build();
await host.RunAsync();

Common Patterns

List Display

ViewModel.Items
    .Select<List<string>, ILayoutNode>(items => new TextNode(
        string.Join("\n", items.Take(10))  // Show first 10 items
    ))
    .AsLayout()

Status Display with Reactive Updates

new PanelNode()
    .WithTitle("Status")
    .WithContent(
        Observable.CombineLatest(
            ViewModel.Status,
            ViewModel.Progress
        )
        .Select(x => new TextNode($"{x[0]} - {x[1]}%"))
        .AsLayout()
    )

Modal Dialog

new ModalNode()
    .WithTitle("Confirm")
    .WithContent(new TextNode("Are you sure?"))
    .WithBackdrop(true)

Scrollable Content

new ScrollableContainer()
    .WithChild(contentNode)
    .Height(20)

Loading Indicator

new SpinnerNode()
    .WithLabel("Loading...")

Performance Considerations

Surgical Rendering: Only changed regions re-render automatically
ReactiveProperty Disposal: Always dispose in ViewModel.Dispose()
Subscription Management: Use .DisposeWith(Subscriptions) in OnActivated()
String Concatenation: For frequently updated content, consider StringBuilder
Observable Subscriptions: Subscribe only to properties that change in BuildLayout()

Breaking Changes

Version 0.7.0

Migrated from System.Reactive to R3
R3 observable syntax may differ slightly from System.Reactive
See migration guide at https://aaronstannard.com/termina/guide/migration-0.7.html

Version 0.11.0

Changes to render loop threading
See upgrade guide at https://aaronstannard.com/termina/guide/upgrade-0.11.html

Resources

Official Documentation: https://aaronstannard.com/termina/
GitHub Repository: https://github.com/Aaronontheweb/Termina
NuGet Package: https://www.nuget.org/packages/Termina
Author: Aaron Stannard (https://aaronstannard.com/)
License: Apache 2.0

Akka.NET Integration Potential

While Termina doesn't have a hard dependency on Akka.NET, the framework was created by Aaron Stannard, who also founded Akka.NET. This creates significant architectural synergy opportunities:

Observable-to-Observable Bridge

Termina's R3 observables can integrate with Akka.NET's streaming infrastructure:

// Termina observable to Akka.Streams
public ReactiveProperty<string> MessageStream { get; } = new("");

// Bridge to Akka.Streams
Source.FromObservable(ViewModel.MessageStream)
    .RunForEach(msg => {
        // Process Akka.NET actor messages into Termina UI
    });

Actor-Based Backend with Termina UI

Use Akka.NET actors for backend logic and Termina for the TUI frontend:

// Host configuration with both Akka.NET and Termina
var builder = Host.CreateApplicationBuilder(args);

// Register Akka.NET
builder.Services.AddAkka("termina-app", configBuilder => {
    configBuilder.AddActorSystem();
});

// Register Termina
builder.Services.AddTermina("/dashboard", termina => {
    termina.RegisterRoute<DashboardPage, DashboardViewModel>("/dashboard");
});

Real-Time Dashboard Pattern

Common use case: Use Akka.NET actors to process distributed data and Termina to display it:

Akka.NET: Handles concurrent data aggregation, event sourcing, clustering
Termina: Displays real-time metrics with surgical rendering and responsive UI
Integration: R3 observables bridge actor state to UI bindings

Streaming Architecture

Akka.Streams integrates with observables (since version 1.3.2):

// Expose Akka.Streams as observable
IObservable<T> observable = akkaStream.RunWith(Sink.AsObservable<T>(), materializer);

// Use in Termina UI
observable
    .Select(item => new TextNode($"{item}"))
    .AsLayout()

Backpressure and Flow Control

Akka.Streams offers backpressure awareness that R3 observables can leverage:

Prevents UI from being overwhelmed by rapid state changes
Buffers with configurable overflow strategies
Maintains responsiveness under high-volume actor message streams

Testing Distributed Systems

Combine Akka.TestKit with Termina's VirtualInputSource for end-to-end testing:

// Test Akka actors and their UI representation
var probe = CreateTestProbe();
var actorRef = ActorOf<MyActor>();

// Verify UI behavior with scripted input
var scriptedInput = new VirtualInputSource();
builder.Services.AddTerminaVirtualInput(scriptedInput);

// Send messages to actor, verify UI updates
actorRef.Tell(new MyMessage());
scriptedInput.EnqueueKey(ConsoleKey.Enter);

Deployment Scenarios

Single-Node Monitor:

Termina TUI for local terminal-based dashboards
Akka.NET local actors for data collection

Distributed Monitoring:

Akka.Cluster processes data on multiple nodes
Termina TUI on each node for local monitoring
Akka.Remote for inter-node communication

CLI Tools with Actor Backend:

Termina provides interactive CLI interface
Akka.NET handles long-running background tasks
Observable streams bridge progress/status updates

Related Concepts

MVVM Pattern: Model-View-ViewModel architectural pattern
Reactive Programming: Using observables for state management
Terminal UI (TUI): Text-based user interfaces in terminal/console
ANSI Escape Codes: Terminal formatting and color codes
Dependency Injection: Microsoft.Extensions.DependencyInjection
Async/Await: Asynchronous programming model for .NET
R3 Observables: Modern reactive extensions library for .NET
Akka.NET: Actor model framework for distributed/concurrent systems
Akka.Streams: Stream processing with backpressure on top of actors
Microsoft.Extensions.Hosting: Host lifecycle management

Summary

Complementary Technologies

Aaron Stannard (Termina's creator) is also the founder of Akka.NET, which creates natural architectural synergy:

Termina: Excellent for responsive, declarative TUI layer
Akka.NET: Ideal for concurrent, distributed, fault-tolerant backend
Observable Bridge: R3 observables seamlessly connect actor state to UI updates

Understanding Rust's Borrowing Concept: A JavaScript Problem Story

artydev — Thu, 30 Jul 2026 08:15:49 +0000

The Problem: Multiple References Gone Wrong

Let me show you a common problem that JavaScript developers face every day—but don't always realize it's a problem.

The JavaScript Scenario

Imagine you have an array, and you create multiple references to it:

const x = [1, 2, 3]
const y = x  // another reference to same array
const z = x  // and another

function sleep(ms) {
  return new Promise((res) => setTimeout(res, ms))
}

function* geny() {
  let i = 0
  while (1) {
    yield y[i]  // iterating through y
    i = (i + 1) % 3
  }
}

const iterY = geny()

async function displayData() {
  while (1) {
    await sleep(1000)
    console.log(iterY.next())
  }
}

// After 5 seconds, mutate the array through z
setTimeout(() => { z[0] = 90 }, 5000)
displayData()

The Output

{ value: 1, done: false }
{ value: 2, done: false }
{ value: 3, done: false }
{ value: 1, done: false }
{ value: 2, done: false }
// ... 5 seconds pass ...
{ value: 90, done: false }  // 😱 SURPRISE! The value changed!
{ value: 2, done: false }
{ value: 3, done: false }

What Went Wrong?

The problem is subtle but dangerous:

Multiple references to the same data (x, y, z all point to [1, 2, 3])
Mutation through one reference (z[0] = 90) silently affects all others
No way to track where the mutation came from
Hard to reason about — the code iterating through y suddenly sees different values

This is called aliasing and mutation — a notoriously difficult bug to track down in large codebases.

The Rust Solution: Borrowing

Rust prevents this problem entirely by enforcing strict borrowing rules at compile time. Let's see how:

Rust's Approach

fn main() {
    let mut x = vec![1, 2, 3];

    // This creates an immutable borrow
    let y = &x;

    // ❌ ERROR: Cannot borrow as mutable while y exists!
    // let z = &mut x;
    // z[0] = 90;

    println!("{:?}", y);  // y is still in use here
}

The compiler says: NO! ✋

error[E0502]: cannot borrow `x` as mutable because it is also borrowed as immutable

The Borrowing Rules (Rust's Safety Guarantee)

Rust enforces these rules:

Scenario	Allowed?	Why?
Multiple immutable borrows (`&x`, `&x`, `&x`)	✅ YES	Readers never conflict
One mutable borrow (`&mut x`)	✅ YES	Single writer, no conflicts
Immutable + Mutable (`&x` and `&mut x`)	❌ NO	Writer and readers = data race

Correct Rust Code

If you want to mutate the data, you must release all other references first:

fn main() {
    let mut x = vec![1, 2, 3];

    // Immutable borrow
    let y = &x;
    println!("y: {:?}", y);

    // y is no longer used, borrow ends here

    // Now we can create a mutable borrow
    let z = &mut x;
    z[0] = 90;

    println!("z: {:?}", z);
}

Output:

y: [1, 2, 3]
z: [90, 2, 3]

Comparing the Languages

JavaScript: Trust and Hope 🙏

const x = [1, 2, 3]
const y = x
const z = x

z[0] = 90

console.log(y)  // [90, 2, 3] ← Surprise! You have to remember to check

Relies on:

Developer discipline
Code reviews
Runtime testing
Hope that you didn't miss anything 😅

Rust: Compile-Time Guarantees 🦀

let mut x = vec![1, 2, 3];
let y = &x;
let z = &mut x;  // ❌ Compiler error BEFORE runtime!
z[0] = 90;

Guarantees:

Checked at compile time
No runtime surprises
Clear ownership semantics
Safe by default

Why This Matters

JavaScript Problems (Real-World Scenarios)

Shared state bugs — State changes in unexpected places
Iterator invalidation — Data changes while iterating
Race conditions — Concurrent modifications
Difficult debugging — Hard to trace where mutation happened

Rust Solutions

// Rust FORCES you to be explicit about access patterns

// Read-only access (shared)
let reader1 = &data;
let reader2 = &data;
let reader3 = &data;
// All readers are safe!

// Exclusive access (mutation)
let writer = &mut data;
// Only one writer, guaranteed no conflicts

Key Takeaways

✅ JavaScript allows multiple mutable references — flexible but error-prone

✅ Rust prevents multiple mutable references — strict but safe

✅ The JavaScript code showed a *real problem* that Rust's borrowing solves

✅ Borrowing is not a limitation — it's a feature that catches bugs at compile time

✅ Trade-off: Less flexibility for more safety and predictability

The Bigger Picture

This is why Rust is gaining traction in systems programming:

Memory safety without garbage collection
No runtime overhead for safety checks
Concurrency without fear (data races are impossible)
Performance + Reliability together

While JavaScript's flexibility is great for rapid development, Rust's borrowing system is invaluable for:

Large codebases
Concurrent systems
Performance-critical code
Safety-critical applications

Try It Yourself

Want to experiment?

JavaScript: Run the code in your browser console and watch the mutation happen silently. TryTheSample

Rust: Head to play.rust-lang.org and try violating the borrowing rules—the compiler will teach you! 🦀

fn main() {
    let mut data = vec![1, 2, 3];
    let immutable_ref = &data;
    let mutable_ref = &mut data;  // Try this!
    mutable_ref[0] = 99;
}

Conclusion

Rust's borrowing system might seem restrictive at first, but it solves real problems that JavaScript developers face daily. By catching aliasing-and-mutation bugs at compile time, Rust gives you confidence that your code is correct before it ever runs.

The JavaScript example above isn't a flaw in JavaScript—it's a feature. The flaw is when that feature leads to subtle bugs. Rust simply chose a different trade-off: less flexibility, zero surprises.

Happy coding! 🦀✨

Have you encountered aliasing-and-mutation bugs in your code? Share your war stories in the comments! And if you're curious about Rust, the borrowing rules might just be the best investment you make in understanding systems programming.

JavaScript References vs Rust Ownership

artydev — Thu, 30 Jul 2026 05:31:14 +0000

JavaScript References vs Rust Ownership

JavaScript variables that hold arrays or objects store references (pointers to the data). When you assign one variable to another, you copy the reference, not the actual data itself. This means multiple variables can point to the same object.

JavaScript Example

let x = [1, 2, 3];
let y = x;
let z = x;

y[0] = 90;

console.log(x); // [90, 2, 3]
console.log(y); // [90, 2, 3]
console.log(z); // [90, 2, 3]

What's happening in memory:

All three variables (x, y, z) point to the same array:

Initial state:

x points to: [1, 2, 3]
y points to: 1, 2, 3
z points to: 1, 2, 3

After y[0] = 90:

x points to: [90, 2, 3]
y points to: 90, 2, 3
z points to: 90, 2, 3

The Problem: All three variables point to the identical array in memory. When you modify the array through one variable, every other variable that points to it sees the change. This silent sharing can cause unexpected bugs.

How Rust Prevents This

Rust uses an ownership and borrowing system to prevent accidental shared changes to data. The compiler checks your code and prevents dangerous patterns before the program even runs.

❌ Not Allowed: Multiple Variables Can Change the Same Data

let mut x = vec![1, 2, 3];
let y = &mut x;  // y can modify x
let z = &mut x;  // ERROR: z cannot also modify x!

Rust compiler error:

cannot borrow x as mutable more than once at a time

Rust refuses to compile this because it prevents the exact problem we saw in JavaScript.

✅ Allowed: Multiple Variables Can Read the Same Data

let x = vec![1, 2, 3];
let y = &x;  // y can read x (but not change it)
let z = &x;  // z can also read x (but not change it)

println!("{:?}", y);
println!("{:?}", z);

Why this is safe: Since nobody can modify the data, it's safe for many variables to read it at once. No unexpected changes can happen.

✅ Allowed: One Variable Can Change the Data

let mut x = vec![1, 2, 3];

{
  let y = &mut x;  // y can modify x
  y[0] = 90;
}  // y goes out of scope here

println!("{:?}", x);  // x is now [90, 2, 3]

How it works: The variable y has exclusive access to modify x. Once y goes out of scope (exits the block), x is available again. There's no shared mutable state.

You Can Create a New Mutable Variable After the First One Ends

let mut x = vec![1, 2, 3];

{
  let y = &mut x;  // y can modify x
  y[0] = 90;
}  // y's access ends here

{
  let z = &mut x;  // NOW z can modify x (y is gone)
  z[1] = 50;
}  // z's access ends here

println!("{:?}", x);  // x is now [90, 50, 3]

Why this is safe: Each variable (y, then z) gets exclusive access to x for its turn. They never overlap. Once y exits its scope, z can safely take over. This prevents simultaneous mutations but allows sequential access.

Without the inner scopes (also allowed):

let mut x = vec![1, 2, 3];

let y = &mut x;
y[0] = 90;
// y is no longer used after this point

let z = &mut x;  // z can now borrow x (y isn't used anymore)
z[1] = 50;

println!("{:?}", x);  // x is now [90, 50, 3]

How this works: Rust is smart enough to know when a variable is no longer being used. Even though y is still "in scope," once you stop using it, z can take over and get mutable access. This is called "non-lexical lifetimes" or NLL—the compiler looks at actual usage, not just scope boundaries.

Rust's Borrowing Rules (Simple Version)

What You're Trying to Do	Is It Allowed?	Why?
Many variables reading (immutable borrows)	✅ Yes	Safe. Nothing can change the data.
One variable changing (mutable borrow)	✅ Yes	Safe. Only one writer, no readers.
Multiple variables changing at once	❌ No	Dangerous. Could cause unpredictable bugs.
Some reading and one changing at the same time	❌ No	Dangerous. Readers might see incomplete changes.

When You Really Need Shared Ownership in Rust

If your program actually needs multiple owners (like passing data to multiple parts of your code), Rust makes you use special containers that make this explicit and safe.

Simple shared ownership (single-threaded):

use std::rc::Rc;

let x = Rc::new(vec![1, 2, 3]);
let y = Rc::clone(&x);  // y also owns the vector
let z = Rc::clone(&x);  // z also owns the vector
// All three own it, but only one can modify it

Shared ownership that can be modified (single-threaded):

Rc<RefCell<T>>

Translation: A shared container that allows interior mutation (changing the contents through shared references).

Shared ownership that can be modified (multi-threaded):

Arc<Mutex<T>>

Translation: A thread-safe shared container with a mutual exclusion lock (only one thread at a time can modify).

The point: When Rust allows shared mutable state, it's explicit and safe. You must opt-in with special types that prevent data races.

Side-by-Side Comparison

Feature	JavaScript	Rust
How variables store objects	As references (pointers)	Through ownership rules
Can multiple variables modify the same data?	Yes, silently and automatically	No, only one at a time
When are problems caught?	At runtime (if you're lucky)	At compile time (always)
Can you share data intentionally?	Yes, by default (sometimes accidentally)	Yes, but you must use explicit types (Rc, Arc, etc.)
Shared mutations	Happen without any warnings	Require explicit safe containers (RefCell, Mutex)

The Bottom Line

JavaScript: Multiple variables can freely reference and modify the same object. This flexibility is convenient but can hide bugs.

Rust: The compiler enforces strict ownership rules. Only one variable can modify data at a time, and this is checked before your program runs. You get safety without sacrificing performance.

In short: JavaScript gives you freedom but less safety. Rust gives you safety but requires you to be explicit about how data is shared. Both approaches have trade-offs, but Rust prevents entire categories of memory-related bugs that JavaScript developers have to debug manually.

Reminder on 'borrowing' and 'moving' in Rust

artydev — Wed, 29 Jul 2026 14:23:46 +0000

Juste a reminder:

Just aanother note:

Assignment (let y = x) moves ownership by default, unless the type implements the Copy trait, in which case the value is copied instead.

Testing Freya - Rust desktop GUI

artydev — Wed, 29 Jul 2026 13:50:56 +0000

I runned the demo from Freya's site on WSL and intalled a X11 server on windows with the followings settings in WSL:

python:/tmp/demo/freya$ export DISPLAY=:0
python:/tmp/demo/freya$ unset WAYLAND_DISPLAY
python:/tmp/demo/freya$ export QT_QPA_PLATFORM=xcb
pytho:/tmp/demo/freya$ cargo run

file: Cargo.toml

[package]
name = "counter"
version = "1.0.0"
edition = "2026"

[dependencies]
freya = "0.4.0"

file: main.rs

use freya::prelude::*;

fn main() {
    launch(LaunchConfig::new().with_window(WindowConfig::new(app)));
}



fn app() -> impl IntoElement {
    let mut count = use_state(|| 4);

    let counter = rect()
        .width(Size::fill())
        .height(Size::percent(50.))
        .center()
        .color((255, 255, 255))
        .background((15, 163, 242))
        .font_weight(FontWeight::BOLD)
        .font_size(75.)
        .shadow((0., 4., 20., 4., (0, 0, 0, 80)))
        .child(count.read().to_string());

    let actions = rect()
        .horizontal()
        .width(Size::fill())
        .height(Size::percent(50.))
        .center()
        .spacing(8.0)
        .child(
            Button::new()
                .on_press(move |_| {
                    *count.write() += 1;
                })
                .child("Increase"),
        )
        .child(
            Button::new()
                .on_press(move |_| {
                    *count.write() -= 1;
                })
                .child("Decrease"),
        );

    rect().child(counter).child(actions)
}

Here is the result :

Links for Rust and Family

artydev — Wed, 29 Jul 2026 11:26:23 +0000

I will put here some links I find interesting :

Docs.rs
Rust by Example
Medium - Dioxus
Leptos
Loco
Freya
Building Native GUIs with Rust & Freya
iced — A Cross-Platform GUI Library for Rust
egui - Gui library
Code Your Own Desktop App with Iced

Fetching data with Rust

artydev — Tue, 28 Jul 2026 21:52:07 +0000

use serde::Deserialize;

#[derive(Deserialize)]
struct Product {
    id: u32,
    title: String,
    brand: Option<String>,
    price: f64,
    rating: f64,
    stock: u32,
    category: String,
}

#[derive(Deserialize)]
struct ApiResponse {
    products: Vec<Product>,
    total: u64,
}

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {

    let response = reqwest::get("https://dummyjson.com/products")
        .await?
        .json::<ApiResponse>()
        .await?;

    // Display the products in a formatted table
    println!("\n{:<5} {:<30} {:<15} {:<10} {:<8} {:<8} {:<10}",
             "ID", "Title", "Brand", "Price", "Rating", "Stock", "Category");
    println!("{}", "=".repeat(100));

    for product in response.products.iter().take(60) {
        let brand = product.brand.as_deref().unwrap_or("Unknown");

        println!("{:<5} {:<30} {:<15} ${:<9.2} {:<8.1} {:<8} {:<10}",
                 product.id,
                 truncate_string(&product.title, 30),
                 truncate_string(brand, 15),
                 product.price,
                 product.rating,
                 product.stock,
                 truncate_string(&product.category, 10));
    }

    println!("\nTotal products fetched: {}", response.total);
    println!("Showing first {} out of {} products", response.products.len().min(60), response.total);

    Ok(())
}

fn truncate_string(s: &str, max_len: usize) -> String {
    if s.chars().count() <= max_len {
        s.to_string()
    } else {
        let truncated: String = s.chars().take(max_len - 3).collect();
        format!("{}...", truncated)
    }
}

A very nice Rust intro

artydev — Mon, 27 Jul 2026 14:25:00 +0000

Sovereign Dev Agent — .NET 10 single-file port (Native AOT compatible)

artydev — Sun, 21 Jun 2026 21:51:20 +0000

A nice .net agent:

// ==========================================================================
// Sovereign Dev Agent — .NET 10 single-file port (Native AOT compatible)
// ==========================================================================
// Run with:     dotnet run Program.cs
// Publish AOT: dotnet publish -p:PublishAot=true
//
// Requires: ALBERT_API_KEY environment variable.
// ==========================================================================

using System;
using System.Collections.Generic;
using System.Diagnostics;
using System.IO;
using System.Net.Http;
using System.Net.Http.Headers;
using System.Text;
using System.Text.Json;
using System.Text.RegularExpressions;
using System.Threading.Tasks;

// --------------------------------------------------------------------
// Configuration
// --------------------------------------------------------------------
string albertApiKey = Environment.GetEnvironmentVariable("OPENROUTER_API_KEY") ?? "VOTRE_CLE_ALBERT";
const string BaseUrl = "https://openrouter.ai/api/v1/chat/completions";
const string ModelName = "openai/gpt-oss-120b";

if (string.IsNullOrWhiteSpace(albertApiKey) || albertApiKey == "VOTRE_CLE_ALBERT")
{
    Console.Error.WriteLine("❌ Error: Please define your ALBERT_API_KEY environment variable.");
    Environment.Exit(1);
}

// --------------------------------------------------------------------
// Persistent state
// --------------------------------------------------------------------
string currentWorkingDir = Directory.GetCurrentDirectory();
var httpClient = new HttpClient();
httpClient.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Bearer", albertApiKey);

// --------------------------------------------------------------------
// DRY helper: path resolution & validation
// --------------------------------------------------------------------
string ResolveAndValidatePath(string relativeOrAbsolutePath, bool checkExists = true)
{
    string resolvedPath = Path.GetFullPath(Path.Combine(currentWorkingDir, relativeOrAbsolutePath));
    if (checkExists && !File.Exists(resolvedPath) && !Directory.Exists(resolvedPath))
    {
        throw new FileNotFoundException($"Target path does not exist: {resolvedPath}");
    }
    return resolvedPath;
}

// --------------------------------------------------------------------
// JsonElement helpers (AOT-safe: no reflection, no serializer)
// --------------------------------------------------------------------
static string? GetStringProp(JsonElement obj, string name)
{
    if (obj.ValueKind == JsonValueKind.Object && obj.TryGetProperty(name, out var prop) && prop.ValueKind == JsonValueKind.String)
    {
        return prop.GetString();
    }
    return null;
}

// --------------------------------------------------------------------
// Local tools — updated to support async tool invocation naturally
// --------------------------------------------------------------------
Task<ToolResult> ListDirectoryAsync(JsonElement args)
{
    try
    {
        string dirPath = GetStringProp(args, "dirPath") ?? ".";
        string targetPath = ResolveAndValidatePath(dirPath);

        // EnumerateFileSystemInfos surfaces directory-vs-file via Attributes from the
        // same underlying syscall as enumeration, avoiding a second per-entry stat
        // call that Directory.Exists(entry) would otherwise require.
        var files = new List<(string, string)>();
        foreach (var entry in new DirectoryInfo(targetPath).EnumerateFileSystemInfos())
        {
            bool isFolder = (entry.Attributes & FileAttributes.Directory) == FileAttributes.Directory;
            files.Add((entry.Name, isFolder ? "folder" : "file"));
        }

        return Task.FromResult(ToolResult.Ok(currentWorkingDir: currentWorkingDir, files: files));
    }
    catch (Exception err)
    {
        return Task.FromResult(ToolResult.Fail(err.Message));
    }
}

async Task<ToolResult> ReadProjectFileAsync(JsonElement args)
{
    try
    {
        string? filePath = GetStringProp(args, "filePath");
        if (string.IsNullOrEmpty(filePath))
            return ToolResult.Fail("filePath is required");

        string targetPath = ResolveAndValidatePath(filePath);

        // Optimize: Check file size before reading to avoid blowing out memory limits
        var fileInfo = new FileInfo(targetPath);
        const int MaxAllowedReadBytes = 120_000; // ~120KB maximum chunk threshold

        if (fileInfo.Length > MaxAllowedReadBytes)
        {
            // Stream only the head block of the huge target file seamlessly
            using var fs = new FileStream(targetPath, FileMode.Open, FileAccess.Read, FileShare.Read, 4096, useAsync: true);
            byte[] buffer = new byte[MaxAllowedReadBytes];
            int readBytes = await fs.ReadAsync(buffer, 0, MaxAllowedReadBytes);

            string partialContent = Encoding.UTF8.GetString(buffer, 0, readBytes);
            return ToolResult.Ok(content: partialContent + $"\n\n[... TRUNCATED SYSTEM OPTIMIZATION: File size is {fileInfo.Length} bytes. Read limit capped at {MaxAllowedReadBytes} bytes to prevent network latency loops ...] ");
        }

        string content = await File.ReadAllTextAsync(targetPath, Encoding.UTF8);
        return ToolResult.Ok(content: content);
    }
    catch (Exception err)
    {
        return ToolResult.Fail(err.Message);
    }
}

async Task<ToolResult> WriteProjectFileAsync(JsonElement args)
{
    try
    {
        string? filePath = GetStringProp(args, "filePath");
        string content = GetStringProp(args, "content") ?? "";
        if (string.IsNullOrEmpty(filePath))
            return ToolResult.Fail("filePath is required");

        string targetPath = ResolveAndValidatePath(filePath, checkExists: false);
        string? dir = Path.GetDirectoryName(targetPath);

        if (!string.IsNullOrEmpty(dir) && !Directory.Exists(dir))
            Directory.CreateDirectory(dir);

        await File.WriteAllTextAsync(targetPath, content, Encoding.UTF8);
        return ToolResult.Ok(message: $"Successfully wrote file to {targetPath}");
    }
    catch (Exception err)
    {
        return ToolResult.Fail(err.Message);
    }
}

Task<ToolResult> ChangeDirectoryAsync(JsonElement args)
{
    try
    {
        string? targetPathArg = GetStringProp(args, "targetPath");
        if (string.IsNullOrEmpty(targetPathArg))
            return Task.FromResult(ToolResult.Fail("targetPath is required"));

        string newPath = ResolveAndValidatePath(targetPathArg);
        if (!Directory.Exists(newPath))
            return Task.FromResult(ToolResult.Fail($"Not a directory: {newPath}"));

        currentWorkingDir = newPath;
        return Task.FromResult(ToolResult.Ok(currentWorkingDir: currentWorkingDir));
    }
    catch (Exception err)
    {
        return Task.FromResult(ToolResult.Fail(err.Message));
    }
}

async Task<ToolResult> ExecuteTerminalCommandAsync(JsonElement args)
{
    try
    {
        string? command = GetStringProp(args, "command");
        if (string.IsNullOrEmpty(command))
            return ToolResult.Fail("command is required");

        Console.WriteLine($"\n   [Terminal Executing]: {command}");

        var psi = new ProcessStartInfo
        {
            FileName = OperatingSystem.IsWindows() ? "cmd.exe" : "/bin/bash",
            ArgumentList = { OperatingSystem.IsWindows() ? "/c" : "-c", command },
            WorkingDirectory = currentWorkingDir,
            RedirectStandardOutput = true,
            RedirectStandardError = true,
            UseShellExecute = false,
            CreateNoWindow = true
        };

        using var process = new Process { StartInfo = psi };

        var stdoutBuilder = new StringBuilder();
        var stderrBuilder = new StringBuilder();

        process.OutputDataReceived += (s, e) => { if (e.Data != null) stdoutBuilder.AppendLine(e.Data); };
        process.ErrorDataReceived += (s, e) => { if (e.Data != null) stderrBuilder.AppendLine(e.Data); };

        process.Start();
        process.BeginOutputReadLine();
        process.BeginErrorReadLine();

        await process.WaitForExitAsync();

        string stdout = stdoutBuilder.ToString();
        string stderr = stderrBuilder.ToString();

        if (process.ExitCode != 0)
        {
            return ToolResult.Fail($"Command exited with code {process.ExitCode}", stderr: stderr);
        }

        return ToolResult.Ok(stdout: stdout);
    }
    catch (Exception err)
    {
        return ToolResult.Fail(err.Message);
    }
}

// Map of tool name -> asynchronous function execution targets
var localToolsMap = new Dictionary<string, Func<JsonElement, Task<ToolResult>>>
{
    ["listDirectory"] = ListDirectoryAsync,
    ["readProjectFile"] = ReadProjectFileAsync,
    ["writeProjectFile"] = WriteProjectFileAsync,
    ["changeDirectory"] = ChangeDirectoryAsync,
    ["executeTerminalCommand"] = ExecuteTerminalCommandAsync
};

// --------------------------------------------------------------------
// Tool schema sent to the model — written directly with Utf8JsonWriter.
// --------------------------------------------------------------------
void WriteToolsSchema(Utf8JsonWriter w)
{
    w.WriteStartArray();

    void WriteTool(string name, string description, Action<Utf8JsonWriter> writeProperties, string[] required)
    {
        w.WriteStartObject();
        w.WriteString("type", "function");
        w.WriteStartObject("function");
        w.WriteString("name", name);
        w.WriteString("description", description);
        w.WriteStartObject("parameters");
        w.WriteString("type", "object");
        w.WriteStartObject("properties");
        writeProperties(w);
        w.WriteEndObject();
        if (required.Length > 0)
        {
            w.WriteStartArray("required");
            foreach (var r in required) w.WriteStringValue(r);
            w.WriteEndArray();
        }
        w.WriteEndObject();
        w.WriteEndObject();
        w.WriteEndObject();
    }

    void WriteStringParam(Utf8JsonWriter writer, string name, string? description = null)
    {
        writer.WriteStartObject(name);
        writer.WriteString("type", "string");
        if (description is not null) writer.WriteString("description", description);
        writer.WriteEndObject();
    }

    WriteTool(
        "listDirectory",
        "List files and folders in a target directory",
        wr => WriteStringParam(wr, "dirPath", "Relative or absolute directory path"),
        required: Array.Empty<string>());

    WriteTool(
        "readProjectFile",
        "Read contents of a file",
        wr => WriteStringParam(wr, "filePath"),
        required: new[] { "filePath" });

    WriteTool(
        "writeProjectFile",
        "Write content to a file, creates directory branches recursively if missing",
        wr =>
        {
            WriteStringParam(wr, "filePath");
            WriteStringParam(wr, "content");
        },
        required: new[] { "filePath", "content" });

    WriteTool(
        "changeDirectory",
        "Change current working directory path context",
        wr => WriteStringParam(wr, "targetPath"),
        required: new[] { "targetPath" });

    WriteTool(
        "executeTerminalCommand",
        "Execute arbitrary bash shell commands natively with a 60s timeout.",
        wr => WriteStringParam(wr, "command"),
        required: new[] { "command" });

    w.WriteEndArray();
}

// --------------------------------------------------------------------
// Conversation history storage helpers
// --------------------------------------------------------------------
string BuildUserOrSystemMessage(string role, string content)
{
    using var ms = new MemoryStream();
    using (var w = new Utf8JsonWriter(ms))
    {
        w.WriteStartObject();
        w.WriteString("role", role);
        w.WriteString("content", content);
        w.WriteEndObject();
    }
    return Encoding.UTF8.GetString(ms.ToArray());
}

string BuildToolMessage(string toolCallId, string toolName, string contentJson)
{
    using var ms = new MemoryStream();
    using (var w = new Utf8JsonWriter(ms))
    {
        w.WriteStartObject();
        w.WriteString("role", "tool");
        w.WriteString("tool_call_id", toolCallId);
        w.WriteString("name", toolName);
        w.WriteString("content", contentJson);
        w.WriteEndObject();
    }
    return Encoding.UTF8.GetString(ms.ToArray());
}

// --------------------------------------------------------------------
// Shared payload builder (avoids re-parsing each history entry's JSON
// on every loop turn — history strings are already well-formed JSON
// produced by our own builders, so we splice their raw bytes directly
// instead of round-tripping through JsonDocument.Parse + WriteTo).
// --------------------------------------------------------------------
byte[] BuildChatPayload(List<string> history, bool stream)
{
    using var ms = new MemoryStream();
    using (var w = new Utf8JsonWriter(ms))
    {
        w.WriteStartObject();
        w.WriteString("model", ModelName);

        w.WriteStartArray("messages");
        foreach (var msgJson in history)
        {
            w.WriteRawValue(msgJson, skipInputValidation: true);
        }
        w.WriteEndArray();

        w.WritePropertyName("tools");
        WriteToolsSchema(w);

        w.WriteString("tool_choice", "auto");
        if (stream) w.WriteBoolean("stream", true);
        w.WriteEndObject();
    }

    return ms.ToArray();
}

// --------------------------------------------------------------------
// Albert Non-Streaming API call (Used exclusively for Tool Dispatch evaluations)
// --------------------------------------------------------------------
async Task<JsonElement> QueryAlbertAsync(List<string> history)
{
    byte[] payloadBytes = BuildChatPayload(history, stream: false);

    using var content = new ByteArrayContent(payloadBytes);
    content.Headers.ContentType = new MediaTypeHeaderValue("application/json") { CharSet = "utf-8" };
    using var response = await httpClient.PostAsync(BaseUrl, content);

    string body = await response.Content.ReadAsStringAsync();
    if (!response.IsSuccessStatusCode)
    {
        throw new Exception($"Albert API Error ({(int)response.StatusCode}): {body}");
    }

    using var responseDoc = JsonDocument.Parse(body);
    var message = responseDoc.RootElement.GetProperty("choices")[0].GetProperty("message");
    return message.Clone();
}

// --------------------------------------------------------------------
// Albert Streaming API call (AOT-Safe real-time streaming evaluator)
// --------------------------------------------------------------------
async Task<string> QueryAlbertStreamAsync(List<string> history, AnsiStreamParser streamParser)
{
    byte[] payloadBytes = BuildChatPayload(history, stream: true);

    using var request = new HttpRequestMessage(HttpMethod.Post, BaseUrl)
    {
        Content = new ByteArrayContent(payloadBytes)
    };
    request.Content.Headers.ContentType = new MediaTypeHeaderValue("application/json") { CharSet = "utf-8" };

    using var response = await httpClient.SendAsync(request, HttpCompletionOption.ResponseHeadersRead);

    if (!response.IsSuccessStatusCode)
    {
        string errorBody = await response.Content.ReadAsStringAsync();
        throw new Exception($"Albert API Error ({(int)response.StatusCode}): {errorBody}");
    }

    using var stream = await response.Content.ReadAsStreamAsync();
    using var reader = new StreamReader(stream, Encoding.UTF8);

    var fullContentBuilder = new StringBuilder();

    while (await reader.ReadLineAsync() is string line)
    {
        if (string.IsNullOrWhiteSpace(line)) continue;
        if (line.StartsWith("data: [DONE]")) break;

        if (line.StartsWith("data: "))
        {
            string jsonChunk = line[6..].Trim();
            if (string.IsNullOrEmpty(jsonChunk)) continue;

            byte[] chunkBytes = Encoding.UTF8.GetBytes(jsonChunk);
            var jsonReader = new Utf8JsonReader(chunkBytes);

            while (jsonReader.Read())
            {
                if (jsonReader.TokenType == JsonTokenType.PropertyName && jsonReader.ValueTextEquals("content"))
                {
                    jsonReader.Read();
                    string? token = jsonReader.GetString();
                    if (!string.IsNullOrEmpty(token))
                    {
                        fullContentBuilder.Append(token);
                        string formattedToken = streamParser.AppendChunk(token);
                        Console.Write(formattedToken);
                    }
                }
            }
        }
    }

    Console.WriteLine();
    return fullContentBuilder.ToString();
}

// --------------------------------------------------------------------
// Runtime engine
// --------------------------------------------------------------------
async Task HandleChatAsync(string userInput)
{
    string cleanInput = userInput.Trim();

    if (string.IsNullOrEmpty(cleanInput))
    {
        PromptUser();
        return;
    }

    // 2. Fast-Track File Viewers (Bypasses LLM network loops entirely with Instant Pipeline)
    if (cleanInput.StartsWith("cat ", StringComparison.OrdinalIgnoreCase) || 
        cleanInput.StartsWith("type ", StringComparison.OrdinalIgnoreCase) ||
        cleanInput.StartsWith("gc ", StringComparison.OrdinalIgnoreCase))
    {
        try
        {
            string filename = cleanInput.Split(' ', 2)[1].Trim();
            string targetPath = ResolveAndValidatePath(filename);

            Console.WriteLine($"\n\x1b[1;35m📄 Local File Stream ({filename}):\x1b[0m");
            var streamParser = new AnsiStreamParser();

            Console.Write(streamParser.ForceEnterCodeBlock());

            using var fileStream = new FileStream(targetPath, FileMode.Open, FileAccess.Read, FileShare.Read, 4096, useAsync: true);
            using var reader = new StreamReader(fileStream, Encoding.UTF8);

            string? lineStr;
            while ((lineStr = await reader.ReadLineAsync()) != null)
            {
                Console.Write(streamParser.AppendChunk(lineStr + "\n"));
            }

            Console.Write(streamParser.ForceExitCodeBlock());
            PromptUser();
            return; 
        }
        catch (Exception ex)
        {
            Console.WriteLine($"❌ Local file read failed: {ex.Message}");
            PromptUser();
            return;
        }
    }

    // 3. Application Exit Commands
    if (string.Equals(cleanInput, "exit", StringComparison.OrdinalIgnoreCase) ||
        string.Equals(cleanInput, "quit", StringComparison.OrdinalIgnoreCase))
    {
        Console.WriteLine("\nSovereign Dev Agent closed.");
        return;
    }

const string SystemPrompt =
@"You are an expert, senior full-stack software engineer and local development agent, and also a capable, friendly general-purpose conversational assistant. Decide for yourself, per message, which mode the user actually needs — most messages will be one or the other, not both.

MODE SELECTION:
- Use tools (listDirectory, readProjectFile, writeProjectFile, changeDirectory, executeTerminalCommand) only when the user's request requires touching the filesystem, running commands, or inspecting/modifying the actual project — e.g. ""fix this bug"", ""add a function to X"", ""run the tests"", ""what's in this folder"".
- Answer directly in conversation, with no tool calls, for everything else — explanations, opinions, brainstorming, general knowledge, casual chat, conceptual or ""should I use X or Y"" questions, or anything where you already have what you need to answer. Do not call a tool just to look busy or thorough if the user's question doesn't actually require touching the workspace.
- If you're unsure which mode fits, default to answering conversationally first; only reach for tools once it's clear the user wants you to act on the project.

WHEN ACTING AS A DEV AGENT (tool calling), follow these OPERATIONAL PRINCIPLES:
1. ANALYSIS FIRST: Before writing files or executing scripts, inspect the existing directory structure and relevant files to understand the project architecture.
2. DEFENSIVE CODING: Implement comprehensive error handling, type checks, and edge-case validations in all code you generate. Do not write placeholder code or ""TODOs"".
3. STEP-BY-STEP EXECUTION: Break down complex engineering objectives into deliberate, sequential tool calls. Verify the outcome of a step (e.g., compile or test results) before moving to the next.
4. ATOMICITY: Keep file modifications precise. Avoid rewriting massive files if only a single function needs optimization.
5. SELF-CORRECTION: If a terminal command returns a standard error (stderr) or a compilation failure, analyze the output, fix the root cause, and re-run the process immediately.
6. PROFESSIONAL PRESENTATION OF THE WORK — consistent naming and formatting conventions for the language/stack in use, clear and minimal comments only where they add real value, sensible project structure, no leftover debug prints or commented-out dead code, and meaningful commit-quality messages if you generate any.

FINAL RESPONSE FORMATTING (applies once you're done with tool calls, if any, and are giving your concluding answer):
- If the turn involved tool calls: structure your concluding answer like a polished engineering handoff, not a raw log dump.
  - Open with a one- or two-sentence summary of what was accomplished.
  - Use clear Markdown structure: short headings or bold labels for sections, bullet points or numbered lists for steps/changes, and fenced code blocks with the correct language tag for any code, commands, or file paths.
  - If you changed or created files, list them explicitly (e.g. as a short table or bullet list of path → purpose).
  - If you ran commands, summarize the outcome in plain language rather than pasting raw terminal output verbatim; quote only the specific error or result line if it's relevant.
  - End with next steps, caveats, or follow-up suggestions when relevant (e.g. ""run the test suite"", ""set the FOO env var before deploying"").
  - Never present a final answer as an unformatted wall of text when the content has any structure to it (multiple files, multiple steps, comparisons, etc.).
- If the turn was purely conversational (no tool calls): just answer naturally, like a normal chat response. Use Markdown structure (headings, bullets, code blocks) only when the content actually has that kind of structure — a short answer or a casual remark should stay a short, plain response, not be forced into a report format.
- In both cases, keep tone confident, concise, and free of filler — no rambling, no unnecessary apologies, no exposing internal reasoning or tool mechanics.

You have total technical authority to manipulate files and execute shell strings within this workspace to achieve the user's goal, and full latitude to talk about anything else the user brings up as a normal conversational partner.";

    var localHistory = new List<string>
    {
        BuildUserOrSystemMessage("system", SystemPrompt),
        BuildUserOrSystemMessage("user", $"Current Working Directory Context: {currentWorkingDir}\nUser Query: {cleanInput}")
    };

    bool keepLooping = true;
    int loopsCounter = 0;
    const int MaxLoops = 12;

    try
    {
        while (keepLooping && loopsCounter < MaxLoops)
        {
            loopsCounter++;

            JsonElement message = await QueryAlbertAsync(localHistory);

            bool hasToolCalls = message.TryGetProperty("tool_calls", out var toolCallsEl) &&
                                 toolCallsEl.ValueKind == JsonValueKind.Array &&
                                 toolCallsEl.GetArrayLength() > 0;

            if (hasToolCalls)
            {
                using (var ms = new MemoryStream())
                {
                    using (var w = new Utf8JsonWriter(ms))
                    {
                        message.WriteTo(w);
                    }
                    localHistory.Add(Encoding.UTF8.GetString(ms.ToArray()));
                }

                var toolCall = toolCallsEl[0];
                var function = toolCall.GetProperty("function");
                string toolName = function.GetProperty("name").GetString() ?? "";
                string toolCallId = toolCall.TryGetProperty("id", out var idEl) ? (idEl.GetString() ?? "") : "";
                string argumentsJson = function.TryGetProperty("arguments", out var argsEl)
                    ? (argsEl.GetString() ?? "{}")
                    : "{}";

                Console.WriteLine($"\n🤖 [Agent Step {loopsCounter}]: Executing {toolName}");

                if (localToolsMap.TryGetValue(toolName, out var executionFunction))
                {
                    JsonDocument argsDoc = JsonDocument.Parse(string.IsNullOrEmpty(argumentsJson) ? "{}" : argumentsJson);
                    ToolResult toolResult;
                    using (argsDoc)
                    {
                        toolResult = await executionFunction(argsDoc.RootElement);
                    }

                    string resultStr = toolResult.ToJson();

                    string preview = resultStr.Length > 150 ? resultStr.Substring(0, 150) + "..." : resultStr;
                    Console.WriteLine($"⚙️ [Result]: {preview}");

                    localHistory.Add(BuildToolMessage(toolCallId, toolName, resultStr));
                }
                else
                {
                    Console.WriteLine($"❌ Tool {toolName} missing implementation.");
                    keepLooping = false;
                }
            }
            else
            {
                Console.Write("\n\x1b[1;35m🤖 Agent Albert:\x1b[0m\n");

                var streamParser = new AnsiStreamParser();
                string streamedContent = await QueryAlbertStreamAsync(localHistory, streamParser);

                localHistory.Add(BuildUserOrSystemMessage("assistant", streamedContent));
                keepLooping = false;
            }
        }

        if (loopsCounter >= MaxLoops)
        {
            Console.WriteLine($"\n⚠️ Safety Loop Cap reached ({MaxLoops} actions).");
        }
    }
    catch (Exception error)
    {
        Console.Error.WriteLine($"\n❌ Runtime Engine Error: {error.Message}");
    }

    PromptUser();
}

void PromptUser()
{
    Console.WriteLine($"\n[{currentWorkingDir}]");
    Console.Write("You: ");
}

// --------------------------------------------------------------------
// Entry point loop
// --------------------------------------------------------------------
Console.WriteLine("=========================================================");
Console.WriteLine("🔓 Unrestricted Multi-Turn State-Streaming Agent — .NET 10");
Console.WriteLine("=========================================================");

PromptUser();
string? inputLine;
while ((inputLine = Console.ReadLine()) != null)
{
    await HandleChatAsync(inputLine);

    if (string.Equals(inputLine.Trim(), "exit", StringComparison.OrdinalIgnoreCase) ||
        string.Equals(inputLine.Trim(), "quit", StringComparison.OrdinalIgnoreCase))
    {
        break;
    }
}

// ==========================================================================
// Type declarations (Placed last to satisfy Top-Level Statements constraint)
// ==========================================================================

sealed class ToolResult
{
    public bool Success { get; init; }
    public string? Error { get; init; }
    public string? CurrentWorkingDir { get; init; }
    public string? Message { get; init; }
    public string? Content { get; init; }
    public string? Stdout { get; init; }
    public string? Stderr { get; init; }
    public List<(string Name, string Type)>? Files { get; init; }

    public static ToolResult Ok(string? currentWorkingDir = null, string? message = null,
        string? content = null, string? stdout = null, List<(string, string)>? files = null) =>
        new()
        {
            Success = true,
            CurrentWorkingDir = currentWorkingDir,
            Message = message,
            Content = content,
            Stdout = stdout,
            Files = files
        };

    public static ToolResult Fail(string error, string? stderr = null) =>
        new() { Success = false, Error = error, Stderr = stderr };

    public string ToJson()
    {
        using var ms = new MemoryStream();
        using (var w = new Utf8JsonWriter(ms))
        {
            w.WriteStartObject();

            if (Error is not null)
            {
                w.WriteBoolean("success", false);
                w.WriteString("error", Error);
                if (Stderr is not null) w.WriteString("stderr", Stderr);
            }
            else
            {
                w.WriteBoolean("success", true);
                if (CurrentWorkingDir is not null) w.WriteString("currentWorkingDir", CurrentWorkingDir);
                if (Message is not null) w.WriteString("message", Message);
                if (Content is not null) w.WriteString("content", Content);
                if (Stdout is not null) w.WriteString("stdout", Stdout);
                if (Files is not null)
                {
                    w.WriteStartArray("files");
                    foreach (var (name, type) in Files)
                    {
                        w.WriteStartObject();
                        w.WriteString("name", name);
                        w.WriteString("type", type);
                        w.WriteEndObject();
                    }
                    w.WriteEndArray();
                }
            }

            w.WriteEndObject();
        }

        return Encoding.UTF8.GetString(ms.ToArray());
    }
}

sealed class AnsiStreamParser
{
    private const string Reset = "\x1b[0m";
    private const string Green = "\x1b[32m";
    private const string DarkGray = "\x1b[90m";
    private const string CodeBg = "\x1b[48;5;235m";
    private const string CodeFg = "\x1b[38;5;250m";

    private enum ParserState { Text, CodeBlock, InlineCode }
    private ParserState _state = ParserState.Text;

    private readonly StringBuilder _buffer = new();

    public string ForceEnterCodeBlock()
    {
        _state = ParserState.CodeBlock;
        _buffer.Clear();
        return $"\n{DarkGray}----------------------------------{Reset}\n{CodeBg}{CodeFg}";
    }

    public string ForceExitCodeBlock()
    {
        _state = ParserState.Text;
        _buffer.Clear();
        return $"{Reset}\n{DarkGray}----------------------------------{Reset}\n";
    }

    public string AppendChunk(string chunk)
    {
        if (string.IsNullOrEmpty(chunk))
            return string.Empty;

        var output = new StringBuilder();

        foreach (char c in chunk)
        {
            switch (_state)
            {
                case ParserState.Text:
                    if (c == '`')
                    {
                        _state = ParserState.InlineCode;
                        output.Append(Green);
                    }
                    else
                    {
                        output.Append(c);
                    }
                    break;

                case ParserState.InlineCode:
                    if (c == '`')
                    {
                        _state = ParserState.Text;
                        output.Append(Reset);
                    }
                    else
                    {
                        output.Append(c);
                    }
                    break;

                case ParserState.CodeBlock:
                    if (c == '`')
                    {
                        // naive fence detection: ```
{% endraw %}
 ends block
                        if (_buffer.Length >= 2 && _buffer[^1] == '{% raw %}`' && _buffer[^2] == '`{% endraw %}')
                        {
                            _buffer.Clear();
                            output.Append(ForceExitCodeBlock());
                            continue;
                        }

                        _buffer.Append(c);
                        output.Append(c);
                    }
                    else
                    {
                        _buffer.Clear();
                        output.Append(c);
                    }
                    break;
            }
        }

        return output.ToString();
    }
}

{% raw %}

Native AOT-Compatible C# Local AI Agent with Ollama Tool Calling

artydev — Sun, 14 Jun 2026 12:36:23 +0000

Nice tool for personal usage:

using System;
using System.Collections.Generic;
using System.IO;
using System.Linq;
using System.Net.Http;
using System.Text;
using System.Text.Json;
using System.Text.Json.Serialization;
using System.Text.RegularExpressions;
using System.Threading;
using System.Threading.Tasks;

// ─────────────────────────────────────────────────────────────
// AOT SERIALIZATION CONTEXT
// ─────────────────────────────────────────────────────────────
[JsonSourceGenerationOptions(PropertyNamingPolicy = JsonKnownNamingPolicy.CamelCase)]
[JsonSerializable(typeof(OllamaRequest))]
[JsonSerializable(typeof(OllamaResponse))]
[JsonSerializable(typeof(OllamaOptions))]
internal partial class OllamaJsonContext : JsonSerializerContext { }


// ─────────────────────────────────────────────────────────────
// TOOL REGISTRY
// ─────────────────────────────────────────────────────────────

public record ToolParam(string Name, string Type, string Description);

public record ToolDefinition(
    string Name,
    string Description,
    IReadOnlyList<ToolParam> Params,
    Func<Dictionary<string, string>, string> Handler
);

public static class ToolRegistry
{
    public static readonly IReadOnlyList<ToolDefinition> Tools = new List<ToolDefinition>
    {
        // ── greet_user ────────────────────────────────────────
        new(
            Name: "greet_user",
            Description: "MUST be called whenever the user introduces themselves or provides their name " +
                         "(e.g. 'I am John', 'my name is Alice', 'hi I'm Marco', 'call me Sam'). " +
                         "Extract the name and call this tool immediately — do NOT reply in plain text.",
            Params: new[] { new ToolParam("name", "string", "The user's first name as stated") },
            Handler: args => args.TryGetValue("name", out var name) ? $"Bonjour {name}!" : "Error: 'name' parameter not found."
        ),

        // ── add_numbers ───────────────────────────────────────
        new(
            Name: "add_numbers",
            Description: "Add two numbers together and return the result.",
            Params: new[]
            {
                new ToolParam("a", "number", "First operand"),
                new ToolParam("b", "number", "Second operand")
            },
            Handler: args =>
            {
                if (args.TryGetValue("a", out var strA) && args.TryGetValue("b", out var strB) &&
                    double.TryParse(strA, System.Globalization.NumberStyles.Any, System.Globalization.CultureInfo.InvariantCulture, out double a) &&
                    double.TryParse(strB, System.Globalization.NumberStyles.Any, System.Globalization.CultureInfo.InvariantCulture, out double b))
                {
                    return (a + b).ToString(System.Globalization.CultureInfo.InvariantCulture);
                }
                return "Error: Could not parse 'a' or 'b' as valid numbers.";
            }
        )
    };

    private static readonly Dictionary<string, ToolDefinition> _index =
        Tools.ToDictionary(t => t.Name, StringComparer.OrdinalIgnoreCase);

    public static bool TryGet(string name, out ToolDefinition? tool) => _index.TryGetValue(name, out tool);
}


// ─────────────────────────────────────────────────────────────
// PROMPT BUILDER
// ─────────────────────────────────────────────────────────────
public static class PromptBuilder
{
private const string BasePrompt = """
        You are a precise, helpful assistant with access to a dynamic set of tools.
        Your primary job is to have natural, useful conversations. Tools exist only to augment
        your responses when genuinely needed — never as a reflex.

        ══════════════════════════════════════════
        TOOL CALL FORMAT
        ══════════════════════════════════════════
        All tools are called using self-closing XML tags:
          <call:TOOL_NAME param1="value1" param2="value2" />

        Rules for values:
          • Strings  → quote as-is:          name="Alice"
          • Numbers  → raw value, no units:  a="12"  b="7.5"
          • Booleans → lowercase string:     enabled="true"
          • Lists    → comma-separated:      items="a,b,c"

        ══════════════════════════════════════════
        AVAILABLE TOOLS
        ══════════════════════════════════════════
        {TOOLS_BLOCK}

        ══════════════════════════════════════════
        DECISION FRAMEWORK
        ══════════════════════════════════════════
        STEP 1 — THINK silently before every response:
          a) What is the user actually asking for?
          b) Does any listed tool directly serve that need?
          c) Would the tool's output be the core of my answer?

        STEP 2 — Use a tool ONLY when ALL of these are true:
          ✔ A listed tool exists that matches the user's intent
          ✔ The tool's output is the primary value of the response
          ✔ The required parameters can be extracted unambiguously from the input

        STEP 3 — Do NOT use a tool when:
          ✘ The question is answerable directly from your internal general knowledge
          ✘ A tool exists but its output is peripheral to the answer
          ✘ Parameters are missing or ambiguous — ask the user to clarify instead (CASE D)
          ✘ No listed tool matches — IMMEDIATELY drop all tool logic and answer naturally

        ══════════════════════════════════════════
        OUTPUT FORMAT — FOUR STRICT CASES
        ══════════════════════════════════════════
        CASE A — No tool matches / General Knowledge → Respond naturally using your own brain. 
          *CRITICAL:* Do not mention tools, do not apologize about missing tools, and do not explain what you can or cannot do. Just give the answer directly.
          User:  "Who invented the telephone?"
          You:   "Alexander Graham Bell is credited with inventing the telephone in 1876."
          User:  "Who was Albert Einstein?"
          You:   "Albert Einstein was a theoretical physicist who developed the theory of relativity..."

        ──────────────────────────────────────────
        CASE B — Tool matches → output ONLY the XML tag. Zero preamble. Zero trailing text.
          User:  "Add 15 and 27"
          You:   <call:add_numbers a="15" b="27" />

          User:  "Hey, I'm Sophie!"
          You:   <call:greet_user name="Sophie" />

        ──────────────────────────────────────────
        CASE C — After a tool result is returned → incorporate it naturally. Be concise and friendly.
          Result: "[Result for add_numbers]: 42"
          You:    "15 + 27 equals 42."

        ──────────────────────────────────────────
        CASE D — Parameters missing or ambiguous → ask ONE targeted clarifying question. No tool call yet.
          User:  "Add the numbers"
          You:   "I'd be happy to add them — which two numbers should I use?"

        ══════════════════════════════════════════
        CHAINING & MULTIPLE TOOLS
        ══════════════════════════════════════════
        If a task requires multiple tools:
          • You MAY output multiple <call:...> tags in a single response if independent actions are needed.
          • Wait for the results, then synthesize all outputs into one coherent answer.

        ══════════════════════════════════════════
        ABSOLUTE PROHIBITIONS
        ══════════════════════════════════════════
          ✘ NEVER use the words "tool", "XML", "tag", "parameter", or "framework" in your conversation with the user.
          ✘ Never invent tool names not listed in AVAILABLE TOOLS above.
          ✘ Never output partial, nested, or malformed XML.
          ✘ Never mix tool XML with surrounding prose in the same response.
          ✘ Never guess parameter values — if uncertain, trigger CASE D.
          ✘ Never say "I don't have a tool for that" — if no tool applies, just act like a normal AI assistant.
          ✘ Never use a tool for rhetorical, emotional, or illustrative purposes.
        """;

    public static string Build(IReadOnlyList<ToolDefinition> tools)
    {
        var block = new StringBuilder();
        foreach (var tool in tools)
        {
            var paramStr = string.Join(" ", tool.Params.Select(p => $"{p.Name}=\"{{{p.Type}}}\""));
            block.AppendLine($"• {tool.Name}: {tool.Description}");
            block.AppendLine($"  Signature: <call:{tool.Name} {paramStr} />");
            block.AppendLine($"  Parameters:");
            foreach (var p in tool.Params)
                block.AppendLine($"    - {p.Name} ({p.Type}): {p.Description}");
            block.AppendLine();
        }
        return BasePrompt.Replace("{TOOLS_BLOCK}", block.ToString().TrimEnd());
    }
}


// ─────────────────────────────────────────────────────────────
// TOOL EXECUTOR — 100% Native AOT Source-Generated Parser
// ─────────────────────────────────────────────────────────────
public static partial class ToolExecutor
{
    [GeneratedRegex(@"<call:\s*([a-zA-Z0-9_]+)\s*(.*?)/?>", RegexOptions.Singleline)]
    private static partial Regex ToolTagRx();

    [GeneratedRegex(@"([a-zA-Z0-9_]+)\s*=\s*(?:""([^""]*)""|'([^']*)'|([^\s/>]+))")]
    private static partial Regex AttrRx();

    public static List<string> ExecuteAll(string raw)
    {
        var results = new List<string>();
        var matches = ToolTagRx().Matches(raw);

        foreach (Match match in matches)
        {
            string toolName = match.Groups[1].Value;
            string attrsString = match.Groups[2].Value;

            if (!ToolRegistry.TryGet(toolName, out var tool))
            {
                results.Add($"Error: Unknown tool '{toolName}'.");
                continue;
            }

            var args = new Dictionary<string, string>(StringComparer.OrdinalIgnoreCase);
            foreach (Match attrMatch in AttrRx().Matches(attrsString))
            {
                string key = attrMatch.Groups[1].Value;
                string value = attrMatch.Groups[2].Success ? attrMatch.Groups[2].Value
                             : attrMatch.Groups[3].Success ? attrMatch.Groups[3].Value
                             : attrMatch.Groups[4].Value;

                args[key] = value;
            }

            try
            {
                string output = tool!.Handler(args);
                results.Add($"[Result for {toolName}]: {output}");
            }
            catch (Exception ex)
            {
                results.Add($"[Error in {toolName}]: {ex.Message}");
            }
        }

        return results;
    }
}


// ─────────────────────────────────────────────────────────────
// MAIN CHAT LOOP
// ─────────────────────────────────────────────────────────────
public class OllamaChat
{
    const string OllamaUrl = "http://localhost:11434/api/chat";
    const string ModelName = "qwen2.5:3b";

    static readonly HttpClient Http = new();

    static async Task Main()
    {
        string modelName = args.Length > 0 ? args[0] : "qwen2.5:3b";

        string systemPrompt = PromptBuilder.Build(ToolRegistry.Tools);
        var history = new List<OllamaMessage> { new() { Role = "system", Content = systemPrompt } };

        Console.WriteLine($"=== Engine Ready ({ModelName}) — {ToolRegistry.Tools.Count} tool(s) loaded ===");
        foreach (var t in ToolRegistry.Tools) Console.WriteLine($"  • {t.Name}");
        Console.WriteLine();

        while (true)
        {
            Console.Write("You: ");
            string? input = Console.ReadLine();
            if (string.IsNullOrEmpty(input) || input == "exit") break;

            history.Add(new OllamaMessage { Role = "user", Content = input });

            // Step 1: Manage context windows prior to execution
            ManageContextWindow(history);

            Console.Write("AI: ");
            string reply;

            try
            {
                // Step 2 & 3: Stream and intercept with an associated 30s timeout execution window
                using var cts = new CancellationTokenSource(TimeSpan.FromSeconds(30));
                reply = await StreamAndCapture(history, cts.Token);
            }
            catch (OperationCanceledException)
            {
                Console.WriteLine("\n⚠️ [Error: Ollama took too long to respond. Request aborted.]\n");
                history.RemoveAt(history.Count - 1); 
                continue;
            }

            List<string> toolResults = ToolExecutor.ExecuteAll(reply);

            if (toolResults.Any())
            {
                string combinedResults = string.Join("\n", toolResults);
                Console.WriteLine("⚙️  [Executing System Tools...]");

                history.Add(new OllamaMessage { Role = "assistant", Content = reply });
                history.Add(new OllamaMessage { Role = "user",      Content = combinedResults });

                // Step 1: Manage window space again in case of massive tool outputs
                ManageContextWindow(history);

                Console.Write("AI: ");
                try
                {
                    using var cts = new CancellationTokenSource(TimeSpan.FromSeconds(30));
                    string finalReply = await StreamAndCapture(history, cts.Token);
                    Console.WriteLine();
                    history.Add(new OllamaMessage { Role = "assistant", Content = finalReply });
                }
                catch (OperationCanceledException)
                {
                    Console.WriteLine("\n⚠️ [Error: Ollama timed out while processing tool results.]\n");
                    history.RemoveRange(history.Count - 2, 2); 
                }
            }
            else
            {
                // Defensive Edge-Case: If the stream was muted because it started with '<' 
                // but no valid tools were processed, print the raw output so information isn't lost.
                if (reply.StartsWith("<"))
                {
                    Console.Write(reply);
                }
                Console.WriteLine();
                history.Add(new OllamaMessage { Role = "assistant", Content = reply });
            }
        }
    }

    // Step 3: Implements In-Stream Interception & Muting
    static async Task<string> StreamAndCapture(List<OllamaMessage> history, CancellationToken cancellationToken)
    {
        var sb = new StringBuilder();
        var req = new OllamaRequest
        {
            Model   = ModelName,
            Stream  = true,
            Messages = history,
            Options = new OllamaOptions { Temperature = 0.0f }
        };

        var json = JsonSerializer.Serialize(req, OllamaJsonContext.Default.OllamaRequest);
        using var resp = await Http.PostAsync(
            OllamaUrl, new StringContent(json, Encoding.UTF8, "application/json"), cancellationToken);

        using var stream = await resp.Content.ReadAsStreamAsync(cancellationToken);
        using var reader = new StreamReader(stream);

        bool isToolCall = false;
        bool checkedFirstChar = false;

        while (await reader.ReadLineAsync(cancellationToken) is { } line)
        {
            var chunk = JsonSerializer.Deserialize(line, OllamaJsonContext.Default.OllamaResponse);
            if (chunk?.Message?.Content != null)
            {
                string content = chunk.Message.Content;
                sb.Append(content);

                // Instantly evaluate the first incoming byte chunk
                if (!checkedFirstChar && sb.Length > 0)
                {
                    if (sb[0] == '<')
                    {
                        isToolCall = true; // Mute console pipeline
                    }
                    checkedFirstChar = true;
                }

                if (!isToolCall)
                {
                    Console.Write(content);
                }
            }
            if (chunk?.Done == true) break;
        }
        return sb.ToString();
    }

    // Step 1: Implements Context Window Management
    static void ManageContextWindow(List<OllamaMessage> history)
    {
        const int MaxContextChars = 12000; // Safe allocation headroom threshold (~3000 tokens)
        while (history.Count > 1 && history.Sum(m => m.Content?.Length ?? 0) > MaxContextChars)
        {
            history.RemoveAt(1); // Safely drop index 1 (oldest turn), keeping system prompt intact at index 0
        }
    }
}


// ─────────────────────────────────────────────────────────────
// OLLAMA DATA MODELS
// ─────────────────────────────────────────────────────────────
public class OllamaOptions
{
    [JsonPropertyName("temperature")] public float Temperature { get; set; }
}

public class OllamaRequest
{
    [JsonPropertyName("model")]    public string             Model    { get; set; } = "";
    [JsonPropertyName("stream")]   public bool               Stream   { get; set; }
    [JsonPropertyName("messages")] public List<OllamaMessage> Messages { get; set; } = new();
    [JsonPropertyName("options")]  public OllamaOptions?     Options  { get; set; }
}

public class OllamaMessage
{
    [JsonPropertyName("role")]    public string Role    { get; set; } = "";
    [JsonPropertyName("content")] public string Content { get; set; } = "";
}

public class OllamaResponse
{
    [JsonPropertyName("message")] public OllamaMessage? Message { get; set; }
    [JsonPropertyName("done")]    public bool           Done    { get; set; }
}

DEV Community: artydev

How to Embed a Photino Project into a Single Executable with wrap_photino.py

Table of Contents

🧠 What Is This?

⚙️ How It Works (Deep Dive)

Step 1 — File Discovery & Embedding

Step 2 — C Wrapper Generation

Step 3 — Compilation

Step 4 — Runtime Behaviour

✅ Prerequisites

🚀 Basic Usage

📋 Command-Line Reference

🧪 Examples

Example 1: Minimal Bundle

Example 2: Custom Binary & Library Names

Example 3: Suppress All Debug Output

Example 4: Fully Static Build

Example 5: Keep the Intermediate C File

📁 Output Structure

📊 Performance & Overhead

🎯 Use Cases

🔧 Troubleshooting

"main binary not found"

"compilation failed"

"no files to embed"

Permission denied when running the wrapper

The application crashes at startup

🧬 How the Generated C Code Works

1. Embedded Data

2. Helper Functions

3. Main Logic

Why fork()?

🔒 Security Considerations

📄 License

🏁 Summary

wrap_photino.py

TerminaReactive TUI Framework for .NET

Termina: Reactive Terminal UI Framework for .NET

Overview

Key Features

Reactive MVVM Architecture

Declarative Layouts

Surgical Region-Based Rendering

ASP.NET Core-Style Routing

Source Generators

Streaming Support

Dependency Injection

Testing Support

Installation

Requirements

Package Installation

Core Architecture

The Three-Part Pattern

1. ViewModel

2. Page

3. Host Configuration

Reactive Property Pattern

Layout System

How Layout Works

Layout Nodes vs. Container Nodes

Size Constraints

Common Layout Patterns

Component Library

Display Components

Input Components

Container Components

Reactive Components

Utility Components

Input Handling

Keyboard Input

Printable Character Handling

Shutdown

Routing

Route Registration

Route Parameters

Navigation

Styling and Colors

Color System

Text Styling

Word Wrapping

Why `fork()`?