DEV Community: artydev

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; }
}

Multi-Session AI Multiplexer That Runs Entirely in Your Browser

artydev — Wed, 27 May 2026 12:12:26 +0000

Use this script to chat and launch commands given an MCP server running on localhost:3000

<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
<title>OllamaTerminal — Dracula</title>
<link rel="preconnect" href="https://fonts.googleapis.com" />
<link rel="preconnect" href="https://fonts.gstatic.com" crossorigin />
<link href="https://fonts.googleapis.com/css2?family=JetBrains+Mono:wght@300;400;500;600;700&family=Fira+Code:wght@300;400;500;600&display=swap" rel="stylesheet" />

<style>
/* ─── DRACULA PALETTE ─────────────────────────────────────────── */
:root {
  --bg:          #282a36;
  --bg-dark:     #1e1f29;
  --bg-darker:   #191a24;
  --surface:     #21222c;
  --surface2:    #2d2f3d;
  --border:      #44475a;
  --comment:     #6272a4;
  --fg:          #f8f8f2;
  --fg-dim:      #c8c8c0;

  --cyan:        #8be9fd;
  --green:       #50fa7b;
  --orange:      #ffb86c;
  --pink:        #ff79c6;
  --purple:      #bd93f9;
  --red:         #ff5555;
  --yellow:      #f1fa8c;

  --accent:      #bd93f9;
  --accent-glow: rgba(189,147,249,0.25);
  --green-glow:  rgba(80,250,123,0.2);
  --cyan-glow:   rgba(139,233,253,0.2);

  --radius:      4px;
  --font-mono:   'JetBrains Mono', 'Fira Code', monospace;
}

*, *::before, *::after { box-sizing: border-box; margin: 0; padding: 0; }

html, body {
  height: 100%;
  background: var(--bg-darker);
  color: var(--fg);
  font-family: var(--font-mono);
  font-size: 13px;
  line-height: 1.55;
  overflow: hidden;
}

/* ─── SCANLINE OVERLAY ────────────────────────────────────────── */
body::before {
  content: '';
  position: fixed; inset: 0; z-index: 9999;
  pointer-events: none;
  background: repeating-linear-gradient(
    0deg,
    transparent,
    transparent 2px,
    rgba(0,0,0,0.07) 2px,
    rgba(0,0,0,0.07) 4px
  );
}

/* ─── CHROME / WINDOW ─────────────────────────────────────────── */
#app {
  display: flex;
  flex-direction: column;
  height: 100vh;
  border: 1px solid var(--border);
  background: var(--bg);
  position: relative;
}

/* ─── TITLE BAR ───────────────────────────────────────────────── */
#titleBar {
  display: flex;
  align-items: center;
  gap: 8px;
  padding: 6px 14px;
  background: var(--bg-darker);
  border-bottom: 1px solid var(--border);
  flex-shrink: 0;
  user-select: none;
}

.traffic-lights { display: flex; gap: 6px; align-items: center; }
.tl { width: 12px; height: 12px; border-radius: 50%; cursor: pointer; transition: filter .15s; }
.tl:hover { filter: brightness(1.3); }
.tl-red    { background: var(--red); }
.tl-yellow { background: var(--yellow); }
.tl-green  { background: var(--green); }

#titleText {
  flex: 1;
  text-align: center;
  font-size: 11px;
  font-weight: 500;
  color: var(--comment);
  letter-spacing: 0.12em;
  text-transform: uppercase;
}

.title-badge {
  font-size: 10px;
  padding: 1px 7px;
  background: var(--surface2);
  border: 1px solid var(--border);
  border-radius: 10px;
  color: var(--purple);
  letter-spacing: 0.08em;
}

/* ─── SESSION / MULTIPLEXER BAR ───────────────────────────────── */
#sessionBar {
  display: flex;
  align-items: stretch;
  gap: 2px;
  padding: 4px 8px 0;
  background: var(--bg-darker);
  border-bottom: 1px solid var(--border);
  flex-shrink: 0;
  min-height: 34px;
  flex-wrap: wrap;
}

.session-wrapper {
  display: flex;
  align-items: center;
  position: relative;
}

.session-tab {
  display: inline-flex;
  align-items: center;
  padding: 4px 12px;
  font-size: 11.5px;
  font-weight: 500;
  cursor: pointer;
  color: var(--comment);
  border: 1px solid transparent;
  border-bottom: none;
  border-radius: var(--radius) var(--radius) 0 0;
  background: transparent;
  transition: color .15s, background .15s, border-color .15s;
  white-space: nowrap;
  letter-spacing: 0.03em;
  position: relative;
  top: 1px;
}

.session-tab:hover {
  color: var(--fg-dim);
  background: var(--surface);
  border-color: var(--border);
}

.session-tab.active {
  color: var(--purple);
  background: var(--bg);
  border-color: var(--border);
  border-bottom-color: var(--bg);
  font-weight: 600;
}

.session-tab.active::before {
  content: '▸ ';
  color: var(--pink);
  font-size: 10px;
}

.delete-btn {
  font-size: 9px;
  color: var(--comment);
  cursor: pointer;
  padding: 0 4px;
  transition: color .15s;
  opacity: 0.5;
}
.session-wrapper:hover .delete-btn { opacity: 1; }
.delete-btn:hover { color: var(--red); }

.rename-input {
  background: var(--surface2);
  border: 1px solid var(--purple);
  border-radius: var(--radius);
  color: var(--fg);
  font-family: var(--font-mono);
  font-size: 11.5px;
  padding: 2px 8px;
  outline: none;
  width: 110px;
  box-shadow: 0 0 6px var(--accent-glow);
}

/* ─── BAR ACTIONS (right-side controls) ──────────────────────── */
.bar-actions-group {
  display: flex;
  align-items: center;
  gap: 8px;
  margin-left: auto;
  padding: 0 4px 4px;
}

.model-selector-wrapper {
  display: flex;
  align-items: center;
  gap: 5px;
  font-size: 10.5px;
  color: var(--comment);
}

.model-select-native {
  background: var(--surface2);
  border: 1px solid var(--border);
  border-radius: var(--radius);
  color: var(--cyan);
  font-family: var(--font-mono);
  font-size: 10.5px;
  padding: 2px 22px 2px 7px;
  cursor: pointer;
  outline: none;
  transition: border-color .15s;
  appearance: none;
  background-image: url("data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' width='10' height='6' viewBox='0 0 10 6'%3E%3Cpath fill='%236272a4' d='M0 0l5 6 5-6z'/%3E%3C/svg%3E");
  background-repeat: no-repeat;
  background-position: right 6px center;
}
.model-select-native:hover,
.model-select-native:focus { border-color: var(--purple); }
.model-select-native option { background: var(--surface); }

.bar-btn {
  font-family: var(--font-mono);
  font-size: 10.5px;
  padding: 3px 9px;
  border-radius: var(--radius);
  border: 1px solid;
  cursor: pointer;
  transition: background .15s, color .15s, box-shadow .15s;
  letter-spacing: 0.04em;
  font-weight: 500;
}

.new-session-btn {
  color: var(--green);
  border-color: var(--green);
  background: transparent;
}
.new-session-btn:hover {
  background: rgba(80,250,123,0.12);
  box-shadow: 0 0 8px var(--green-glow);
}

.wipe-workspace-btn {
  color: var(--red);
  border-color: var(--red);
  background: transparent;
}
.wipe-workspace-btn:hover {
  background: rgba(255,85,85,0.12);
  box-shadow: 0 0 8px rgba(255,85,85,0.3);
}

/* ─── STATUS BAR ──────────────────────────────────────────────── */
#statusBar {
  display: flex;
  align-items: center;
  gap: 14px;
  padding: 3px 14px;
  background: var(--bg-darker);
  border-bottom: 1px solid var(--border);
  flex-shrink: 0;
  font-size: 10px;
  color: var(--comment);
  letter-spacing: 0.04em;
}

.status-dot {
  width: 6px; height: 6px;
  border-radius: 50%;
  display: inline-block;
  margin-right: 4px;
}
.status-dot.online  { background: var(--green); box-shadow: 0 0 5px var(--green); animation: pulse-green 2s infinite; }
.status-dot.offline { background: var(--red); }

@keyframes pulse-green {
  0%,100% { opacity: 1; }
  50%      { opacity: 0.4; }
}

.status-item { display: flex; align-items: center; }
.status-sep { color: var(--border); }
#mcpStatus { color: var(--green); }
#mcpStatus.offline { color: var(--red); }

/* ─── LOG / OUTPUT AREA ───────────────────────────────────────── */
#log {
  flex: 1;
  overflow-y: auto;
  padding: 14px 18px;
  background: var(--bg);
  scroll-behavior: smooth;
}

#log::-webkit-scrollbar { width: 6px; }
#log::-webkit-scrollbar-track { background: transparent; }
#log::-webkit-scrollbar-thumb { background: var(--border); border-radius: 3px; }
#log::-webkit-scrollbar-thumb:hover { background: var(--comment); }

/* ─── LOG LINE TYPES ──────────────────────────────────────────── */
.line {
  display: block;
  padding: 1.5px 0;
  white-space: pre-wrap;
  word-break: break-word;
  animation: fadein .12s ease-out;
}

@keyframes fadein {
  from { opacity: 0; transform: translateY(2px); }
  to   { opacity: 1; transform: none; }
}

.line.user {
  color: var(--green);
  font-weight: 500;
}

.line.ai {
  color: var(--fg);
  padding-left: 0;
  position: relative;
}

.line.ai span {
  color: var(--purple);
  font-weight: 600;
}

.line.sys {
  color: var(--comment);
  font-size: 11.5px;
  font-style: italic;
}

.line.err {
  color: var(--red);
  font-weight: 600;
}

.line.tool {
  color: var(--orange);
  border-left: 2px solid var(--orange);
  padding-left: 10px;
  margin: 2px 0;
  background: rgba(255,184,108,0.04);
  border-radius: 0 var(--radius) var(--radius) 0;
}

/* welcome banner */
.banner-line {
  color: var(--pink);
  font-size: 11px;
  letter-spacing: 0.08em;
}

/* ─── DIVIDER ─────────────────────────────────────────────────── */
.log-divider {
  border: none;
  border-top: 1px solid var(--surface2);
  margin: 8px 0;
}

/* ─── INPUT ROW ───────────────────────────────────────────────── */
#inputRow {
  display: flex;
  align-items: center;
  gap: 0;
  padding: 8px 14px 10px;
  background: var(--bg-dark);
  border-top: 1px solid var(--border);
  flex-shrink: 0;
}

#terminalPrompt {
  color: var(--green);
  font-weight: 600;
  font-size: 13px;
  white-space: nowrap;
  margin-right: 8px;
  flex-shrink: 0;
  text-shadow: 0 0 8px var(--green-glow);
}

#input {
  flex: 1;
  background: transparent;
  border: none;
  outline: none;
  color: var(--fg);
  font-family: var(--font-mono);
  font-size: 13px;
  caret-color: var(--purple);
}

#input::placeholder { color: var(--border); }

.input-cursor-hint {
  width: 8px; height: 15px;
  background: var(--purple);
  animation: blink .9s step-start infinite;
  border-radius: 1px;
  flex-shrink: 0;
  opacity: 0.7;
}

@keyframes blink {
  50% { opacity: 0; }
}

/* ─── THINKING INDICATOR ──────────────────────────────────────── */
.thinking-dots {
  display: inline-flex;
  gap: 3px;
  margin-left: 6px;
  vertical-align: middle;
}
.thinking-dots span {
  width: 4px; height: 4px;
  background: var(--purple);
  border-radius: 50%;
  animation: bounce .8s ease-in-out infinite;
}
.thinking-dots span:nth-child(2) { animation-delay: .15s; }
.thinking-dots span:nth-child(3) { animation-delay: .30s; }

@keyframes bounce {
  0%,100% { transform: translateY(0); opacity: .4; }
  50%      { transform: translateY(-4px); opacity: 1; }
}

/* ─── SCROLLBAR ───────────────────────────────────────────────── */
* { scrollbar-width: thin; scrollbar-color: var(--border) transparent; }

/* ─── GLOW FOCUS INPUT ROW ────────────────────────────────────── */
#inputRow:focus-within {
  border-top-color: var(--purple);
  box-shadow: 0 -1px 0 0 var(--accent-glow);
}

/* ─── STOP BUTTON ─────────────────────────────────────────────── */
#stopBtn {
  display: none;
  align-items: center;
  gap: 5px;
  font-family: var(--font-mono);
  font-size: 11px;
  font-weight: 600;
  padding: 3px 10px;
  border-radius: var(--radius);
  border: 1px solid var(--red);
  color: var(--red);
  background: rgba(255,85,85,0.08);
  cursor: pointer;
  letter-spacing: 0.06em;
  transition: background .15s, box-shadow .15s;
  flex-shrink: 0;
  animation: fadein .15s ease-out;
}
#stopBtn:hover {
  background: rgba(255,85,85,0.18);
  box-shadow: 0 0 10px rgba(255,85,85,0.35);
}
#stopBtn.visible { display: inline-flex; }

.stop-icon {
  width: 8px; height: 8px;
  background: var(--red);
  border-radius: 1px;
  flex-shrink: 0;
}

/* ─── COLLAPSIBLE TOOL BLOCK ──────────────────────────────────── */
.tool-block {
  margin: 4px 0;
  border-left: 2px solid var(--orange);
  border-radius: 0 var(--radius) var(--radius) 0;
  background: rgba(255,184,108,0.04);
  overflow: hidden;
  animation: fadein .12s ease-out;
}

.tool-block-header {
  display: flex;
  align-items: center;
  gap: 8px;
  padding: 5px 10px;
  cursor: pointer;
  color: var(--orange);
  font-size: 12px;
  font-weight: 500;
  user-select: none;
  transition: background .12s;
}
.tool-block-header:hover { background: rgba(255,184,108,0.08); }

.tool-chevron {
  font-size: 9px;
  transition: transform .2s;
  opacity: 0.7;
  flex-shrink: 0;
}
.tool-block.open .tool-chevron { transform: rotate(90deg); }

.tool-block-label { flex: 1; }

.tool-block-badge {
  font-size: 9px;
  padding: 1px 6px;
  border-radius: 8px;
  border: 1px solid var(--orange);
  color: var(--orange);
  opacity: 0.6;
  flex-shrink: 0;
}
.tool-block.tool-error .tool-block-badge { border-color: var(--red); color: var(--red); }

.tool-block-body {
  display: none;
  padding: 0 10px 8px 10px;
  border-top: 1px solid rgba(255,184,108,0.12);
}
.tool-block.open .tool-block-body { display: block; }

.tool-block-section {
  margin-top: 6px;
}
.tool-block-section-label {
  font-size: 9px;
  color: var(--comment);
  letter-spacing: 0.1em;
  text-transform: uppercase;
  margin-bottom: 3px;
}
.tool-block-code {
  background: var(--bg-darker);
  border: 1px solid var(--border);
  border-radius: var(--radius);
  padding: 6px 8px;
  font-size: 11px;
  color: var(--cyan);
  white-space: pre-wrap;
  word-break: break-all;
  max-height: 180px;
  overflow-y: auto;
  line-height: 1.5;
}
.tool-block-code.result-text { color: var(--fg-dim); }
.tool-block.tool-error .tool-block-code.result-text { color: var(--red); }

/* history hint in input row */
.hist-hint {
  font-size: 9.5px;
  color: var(--border);
  flex-shrink: 0;
  padding-right: 4px;
  white-space: nowrap;
  transition: color .15s;
}
#inputRow:focus-within .hist-hint { color: var(--comment); }

/* ─── RESPONSIVE ──────────────────────────────────────────────── */
@media (max-width: 600px) {
  #titleText { display: none; }
  .bar-actions-group { gap: 5px; }
  .hist-hint { display: none; }
}
</style>
</head>
<body>

<div id="app">

  <!-- Title Bar -->
  <div id="titleBar">
    <div class="traffic-lights">
      <div class="tl tl-red"    title="Close"></div>
      <div class="tl tl-yellow" title="Minimize"></div>
      <div class="tl tl-green"  title="Maximize"></div>
    </div>
    <span id="titleText">ollama-terminal — dracula edition</span>
    <span class="title-badge">MCP</span>
  </div>

  <!-- Session / Multiplexer Bar -->
  <div id="sessionBar"></div>

  <!-- Status Bar -->
  <div id="statusBar">
    <span class="status-item">
      <span class="status-dot offline" id="mcpDot"></span>
      <span id="mcpStatus" class="offline">MCP offline</span>
    </span>
    <span class="status-sep">│</span>
    <span class="status-item">model: <span id="statusModel" style="color:var(--cyan);margin-left:4px;">—</span></span>
    <span class="status-sep">│</span>
    <span class="status-item" id="toolCount" style="color:var(--orange);">0 tools</span>
    <span class="status-sep">│</span>
    <span class="status-item" id="msgCount" style="color:var(--comment);">0 msgs</span>
  </div>

  <!-- Output Log -->
  <div id="log"></div>

  <!-- Input Row -->
  <div id="inputRow">
    <span id="terminalPrompt">user@ollama:~$</span>
    <input id="input" type="text" autocomplete="off" spellcheck="false" placeholder="enter a prompt or /help…" />
    <span class="hist-hint" title="↑↓ history">↑↓</span>
    <span id="stopBtn" title="Stop generation (Esc)">
      <span class="stop-icon"></span>Stop
    </span>
    <div class="input-cursor-hint"></div>
  </div>

</div>

<script type="module">
import { get, set, del } from 'https://cdn.jsdelivr.net/npm/idb-keyval@6/+esm';

/* ──────────────────────────────────────────────────────────────
   DOM REFS
────────────────────────────────────────────────────────────── */
const log            = document.getElementById("log");
const input          = document.getElementById("input");
const sessionBar     = document.getElementById("sessionBar");
const terminalPrompt = document.getElementById("terminalPrompt");
const mcpDot         = document.getElementById("mcpDot");
const mcpStatusEl    = document.getElementById("mcpStatus");
const statusModelEl  = document.getElementById("statusModel");
const toolCountEl    = document.getElementById("toolCount");
const msgCountEl     = document.getElementById("msgCount");
const stopBtn        = document.getElementById("stopBtn");

/* ──────────────────────────────────────────────────────────────
   CONSTANTS
────────────────────────────────────────────────────────────── */
const OLLAMA_URL    = "http://localhost:11434/api/chat";
const MCP_SERVER_URL = "http://localhost:3000";
const REGISTRY_KEY   = "multiplexer_registry_config";
const SESSION_PREFIX = "multiplexer_session_";

const POPULAR_MODELS = [
  "gemma4:e4b",
  "gemma4:latest",
  "qwen2.5-coder:14b"
];

const SYSTEM_PROMPT = {
  role: "system",
  content: "You are a helpful local terminal intelligence agent. You have real-time access to advanced local host platform systems tools. Invoke them whenever required to answer questions accurately."
};

/* ──────────────────────────────────────────────────────────────
   STATE
────────────────────────────────────────────────────────────── */
let registry = { currentActiveId: null, activeModel: "gemma4:latest", list: [] };
let activeMessages       = [SYSTEM_PROMPT];
let fullPersistentHistory = [];
let RUNTIME_AVAILABLE_TOOLS = [];

// ── Command History ──────────────────────────────────────────────
const CMD_HISTORY_MAX = 50;
let cmdHistory    = [];   // array of strings, oldest→newest
let historyIndex  = -1;   // -1 = not browsing; 0 = oldest
let historyDraft  = "";   // saves current typed text while browsing

// ── Abort Controller ────────────────────────────────────────────
let currentAbortController = null;

function setGenerating(on) {
  if (on) {
    stopBtn.classList.add("visible");
    input.disabled = true;
    input.placeholder = "generating… (Esc to stop)";
  } else {
    stopBtn.classList.remove("visible");
    input.disabled = false;
    input.placeholder = "enter a prompt or /help…";
    input.focus();
    currentAbortController = null;
  }
}

/* ──────────────────────────────────────────────────────────────
   STATUS BAR HELPERS
────────────────────────────────────────────────────────────── */
function setMcpStatus(online, toolCount = 0) {
  if (online) {
    mcpDot.className = "status-dot online";
    mcpStatusEl.className = "";
    mcpStatusEl.style.color = "var(--green)";
    mcpStatusEl.textContent = "MCP online";
  } else {
    mcpDot.className = "status-dot offline";
    mcpStatusEl.className = "offline";
    mcpStatusEl.style.color = "var(--red)";
    mcpStatusEl.textContent = "MCP offline";
  }
  toolCountEl.textContent = `${toolCount} tool${toolCount !== 1 ? 's' : ''}`;
}

function updateStatusBar() {
  statusModelEl.textContent = registry.activeModel || "—";
  const userMsgs = activeMessages.filter(m => m.role === "user").length;
  msgCountEl.textContent = `${userMsgs} msg${userMsgs !== 1 ? 's' : ''}`;
}

/* ──────────────────────────────────────────────────────────────
   MCP CLIENT
────────────────────────────────────────────────────────────── */
async function fetchToolsFromMcpServer() {
  try {
    print(`connecting to MCP gateway at ${MCP_SERVER_URL}…`, "sys");
    const response = await fetch(MCP_SERVER_URL, {
      method: "POST",
      headers: { "Content-Type": "application/json" },
      body: JSON.stringify({ jsonrpc: "2.0", method: "tools/list", params: {}, id: 1 })
    });
    if (!response.ok) throw new Error(`HTTP ${response.status}`);
    const data = await response.json();
    if (data.result?.tools) {
      RUNTIME_AVAILABLE_TOOLS = data.result.tools.map(t => ({
        type: "function",
        function: {
          name: t.name,
          description: t.description,
          parameters: {
            type: t.inputSchema?.type || "object",
            properties: t.inputSchema?.properties || {},
            required: t.inputSchema?.required || []
          }
        }
      }));
      setMcpStatus(true, RUNTIME_AVAILABLE_TOOLS.length);
      print(`🟢 MCP connected — ${RUNTIME_AVAILABLE_TOOLS.length} tools loaded`, "sys");
    }
  } catch (err) {
    setMcpStatus(false, 0);
    print(`🔴 MCP offline (${err.message}) — text-only mode`, "sys");
    RUNTIME_AVAILABLE_TOOLS = [];
  }
}

async function executeMcpToolCall(name, args) {
  try {
    const response = await fetch(MCP_SERVER_URL, {
      method: "POST",
      headers: { "Content-Type": "application/json" },
      body: JSON.stringify({ jsonrpc: "2.0", method: "tools/call", params: { name, arguments: args }, id: Date.now() })
    });
    if (!response.ok) {
      const errData = await response.json().catch(() => ({}));
      throw new Error(errData.error?.message || `HTTP ${response.status}`);
    }
    const rpcResult = await response.json();
    if (rpcResult.error) throw new Error(rpcResult.error.message);
    const content = rpcResult.result;
    if (content?.content && Array.isArray(content.content)) {
      return content.content.filter(c => c.type === "text").map(c => c.text).join("\n") || "No output.";
    }
    return JSON.stringify(content);
  } catch (err) {
    return `Tool error: ${err.message}`;
  }
}

/* ──────────────────────────────────────────────────────────────
   CONTEXT PRUNING
────────────────────────────────────────────────────────────── */
function pruneActiveMemory() {
  const sys = activeMessages[0];
  let hist = activeMessages.slice(1);
  while (hist.length > 16) hist.shift();
  while (hist.length > 0 && (hist[0].role === "tool" || hist[0].content === "")) hist.shift();
  activeMessages = [sys, ...hist];
  updateStatusBar();
}

/* ──────────────────────────────────────────────────────────────
   PERSISTENCE
────────────────────────────────────────────────────────────── */
async function saveAllToBrowser() {
  try {
    await set(REGISTRY_KEY, registry);
    if (registry.currentActiveId) await set(SESSION_PREFIX + registry.currentActiveId, fullPersistentHistory);
  } catch (err) { console.error("Storage write error:", err); }
}

async function loadSessionData(sessionId) {
  try {
    const saved = await get(SESSION_PREFIX + sessionId);
    fullPersistentHistory = saved || [];
    activeMessages = [SYSTEM_PROMPT, ...fullPersistentHistory.filter(m => !m.isToolActivityLog)];
    pruneActiveMemory();
    renderTerminalScreen();
    renderTopMultiplexerBar();
  } catch (err) { print("DB error: " + err.message, "err"); }
}

/* ──────────────────────────────────────────────────────────────
   RENDERING
────────────────────────────────────────────────────────────── */
function renderTopMultiplexerBar() {
  sessionBar.innerHTML = "";

  registry.list.forEach((session, index) => {
    const wrapper = document.createElement("div");
    wrapper.className = "session-wrapper";

    const tab = document.createElement("span");
    const isActive = session.id === registry.currentActiveId;
    tab.className = `session-tab ${isActive ? 'active' : ''}`;
    tab.textContent = `${index}: ${session.name}`;

    tab.addEventListener("click", () => { if (!isActive) switchSession(index); });

    tab.addEventListener("dblclick", (e) => {
      e.stopPropagation();
      const editorInput = document.createElement("input");
      editorInput.type = "text";
      editorInput.className = "rename-input";
      editorInput.value = session.name;

      const finishRename = async () => {
        const fresh = editorInput.value.trim();
        if (fresh && fresh !== session.name) { session.name = fresh; await saveAllToBrowser(); renderTerminalScreen(); }
        renderTopMultiplexerBar();
      };

      editorInput.addEventListener("keydown", (ke) => {
        if (ke.key === "Enter") finishRename();
        if (ke.key === "Escape") renderTopMultiplexerBar();
      });
      editorInput.addEventListener("blur", finishRename);
      wrapper.replaceChild(editorInput, tab);
      editorInput.focus(); editorInput.select();
    });

    wrapper.appendChild(tab);

    const del = document.createElement("span");
    del.className = "delete-btn";
    del.textContent = "✕";
    del.title = "Delete session";
    del.addEventListener("click", (e) => { e.stopPropagation(); handleDeleteSessionConfirmation(index); });
    wrapper.appendChild(del);
    sessionBar.appendChild(wrapper);
  });

  // Right-side controls
  const actions = document.createElement("div");
  actions.className = "bar-actions-group";

  const modelWrap = document.createElement("div");
  modelWrap.className = "model-selector-wrapper";
  modelWrap.innerHTML = `<span>⚙ model:</span>`;

  const sel = document.createElement("select");
  sel.className = "model-select-native";
  const models = [...new Set([registry.activeModel, ...POPULAR_MODELS])];
  models.forEach(m => {
    const opt = document.createElement("option");
    opt.value = m; opt.textContent = m;
    if (m === registry.activeModel) opt.selected = true;
    sel.appendChild(opt);
  });
  sel.addEventListener("change", e => switchActiveModel(e.target.value));
  modelWrap.appendChild(sel);
  actions.appendChild(modelWrap);

  const newBtn = document.createElement("span");
  newBtn.className = "bar-btn new-session-btn";
  newBtn.textContent = "+ New";
  newBtn.title = "Create new session";
  newBtn.addEventListener("click", () => handleCreateSession());
  actions.appendChild(newBtn);

  const wipeBtn = document.createElement("span");
  wipeBtn.className = "bar-btn wipe-workspace-btn";
  wipeBtn.textContent = "Wipe All";
  wipeBtn.title = "Erase all sessions";
  wipeBtn.addEventListener("click", () => handleWipeAllSessionsConfirmation());
  actions.appendChild(wipeBtn);

  sessionBar.appendChild(actions);
  updateStatusBar();
}

function renderTerminalScreen() {
  log.innerHTML = "";
  const cur = registry.list.find(s => s.id === registry.currentActiveId);
  const name = cur ? cur.name : "none";
  terminalPrompt.textContent = `user@ollama:[${name}]~$`;

  if (!cur) {
    printBanner();
    print("No active session. Click '+ New' or type /new to begin.", "sys");
    return;
  }

  if (fullPersistentHistory.length === 0) {
    printBanner();
    print(`Session [${name}] ready — model: ${registry.activeModel}`, "sys");
    print("Type /help for available commands.", "sys");
    return;
  }

  // Replay history — group tool activity log pairs into collapsed blocks
  let i = 0;
  while (i < fullPersistentHistory.length) {
    const msg = fullPersistentHistory[i];

    if (msg.role === "user") {
      print(`user@ollama:[${name}]~$ ${msg.content}`, "user");
      i++; continue;
    }

    if (msg.role === "assistant" && !msg.isInternalToolCall && msg.content?.trim()) {
      print(`assistant: ${msg.content}`, "ai");
      i++; continue;
    }

    // Tool activity log pair: "🔧 executing" followed by "📦 result"
    if (msg.isToolActivityLog && msg.content?.startsWith("🔧")) {
      const execMsg   = msg.content;                          // "🔧 [MCP] executing → toolName"
      const resultMsg = fullPersistentHistory[i + 1];        // "📦 [MCP] result: ..."

      const tName   = execMsg.replace("🔧 [MCP] executing → ", "").trim();
      const outcome = resultMsg?.content?.replace(/^📦 \[MCP\] result: /, "") ?? "";
      const isError = outcome.startsWith("Tool error:");

      // Reconstruct collapsed tool block
      const block = document.createElement("div");
      block.className = "tool-block" + (isError ? " tool-error" : "");

      const header = document.createElement("div");
      header.className = "tool-block-header";
      header.innerHTML = `
        <span class="tool-chevron">▶</span>
        <span class="tool-block-label">🔧 ${tName}</span>
        <span class="tool-block-badge">${isError ? "error" : "done"}</span>`;
      block.appendChild(header);

      const body = document.createElement("div");
      body.className = "tool-block-body";
      body.innerHTML = `
        <div class="tool-block-section">
          <div class="tool-block-section-label">result</div>
          <div class="tool-block-code result-text${isError ? "" : ""}">${outcome}</div>
        </div>`;
      block.appendChild(body);
      header.addEventListener("click", () => block.classList.toggle("open"));
      if (isError) block.classList.add("open");
      log.appendChild(block);

      i += 2; // skip both the exec and result log entries
      // also skip the isInternalToolCall assistant entry that follows
      if (fullPersistentHistory[i]?.isInternalToolCall) i++;
      continue;
    }

    i++; // skip anything else (isInternalToolCall, blank, etc.)
  }
}

function printBanner() {
  const lines = [
    "╔══════════════════════════════════════════╗",
    "║   🧛  OLLAMA TERMINAL  ·  DRACULA       ║",
    "║       MCP-powered local AI multiplexer   ║",
    "╚══════════════════════════════════════════╝",
  ];
  lines.forEach(l => print(l, "banner-line"));
  const hr = document.createElement("hr");
  hr.className = "log-divider";
  log.appendChild(hr);
}

function print(text, cls = "sys") {
  const div = document.createElement("div");
  div.className = "line " + cls;
  div.textContent = text;
  log.appendChild(div);
  log.scrollTop = log.scrollHeight;
  return div;
}

/* ──────────────────────────────────────────────────────────────
   MULTIPLEXER OPERATIONS
────────────────────────────────────────────────────────────── */
async function switchActiveModel(name) {
  if (!name?.trim()) return;
  registry.activeModel = name.trim();
  await saveAllToBrowser();
  updateStatusBar();
  print(`⚙ Model switched → ${registry.activeModel}`, "sys");
  renderTopMultiplexerBar();
}

async function handleCreateSession(customName = null) {
  // 1. Flush the current session to IndexedDB BEFORE switching away
  if (registry.currentActiveId) {
    try {
      await set(SESSION_PREFIX + registry.currentActiveId, fullPersistentHistory);
    } catch (e) { console.error("Failed to save current session before switching:", e); }
  }

  // 2. Now create and switch to the new session
  const id   = "s_" + Date.now();
  const name = customName?.trim() || `session-${registry.list.length}`;
  registry.list.push({ id, name });
  registry.currentActiveId = id;
  fullPersistentHistory = [];
  activeMessages = [SYSTEM_PROMPT];
  await saveAllToBrowser();
  renderTopMultiplexerBar();
  renderTerminalScreen();
}

async function switchSession(index) {
  const t = registry.list[index];
  if (!t || t.id === registry.currentActiveId) return;

  // Flush current session first, then switch
  if (registry.currentActiveId) {
    try {
      await set(SESSION_PREFIX + registry.currentActiveId, fullPersistentHistory);
    } catch (e) { console.error("Failed to save session before switch:", e); }
  }

  registry.currentActiveId = t.id;
  await set(REGISTRY_KEY, registry);
  await loadSessionData(t.id);
}

async function handleDeleteSessionConfirmation(index) {
  const s = registry.list[index];
  if (!s) return;
  if (confirm(`Delete session "${s.name}"?`)) {
    await del(SESSION_PREFIX + s.id);
    registry.list.splice(index, 1);
    if (registry.currentActiveId === s.id) {
      if (registry.list.length > 0) {
        registry.currentActiveId = registry.list[Math.max(0, index - 1)].id;
        await set(REGISTRY_KEY, registry);
        await loadSessionData(registry.currentActiveId);
      } else {
        registry.currentActiveId = null;
        fullPersistentHistory = [];
        activeMessages = [SYSTEM_PROMPT];
        await set(REGISTRY_KEY, registry);
        renderTopMultiplexerBar();
        renderTerminalScreen();
      }
    } else {
      await set(REGISTRY_KEY, registry);
      renderTopMultiplexerBar();
    }
  }
}

async function handleWipeAllSessionsConfirmation() {
  if (prompt("Type WIPE to erase all sessions:") === "WIPE") {
    for (const s of registry.list) await del(SESSION_PREFIX + s.id);
    await del(REGISTRY_KEY);
    registry.list = [];
    registry.currentActiveId = null;
    fullPersistentHistory = [];
    activeMessages = [SYSTEM_PROMPT];
    await handleCreateSession("general");
  }
}

async function handleSlashCommand(raw) {
  const parts = raw.trim().split(" ");
  const cmd   = parts[0].toLowerCase();
  const args  = parts.slice(1).join(" ");

  if (cmd === "/new") {
    await handleCreateSession(args || null);
  } else if (cmd === "/clear") {
    log.innerHTML = "";
    printBanner();
  } else if (cmd === "/help") {
    const cmds = [
      ["  /new [name]", "create a new session tab"],
      ["  /clear",      "clear the terminal output"],
      ["  /help",       "show this help message"],
    ];
    const keys = [
      ["  ↑ / ↓",       "cycle through command history"],
      ["  Esc",         "stop current generation"],
      ["  Enter",       "send prompt"],
    ];
    print("── commands ──────────────────────────────────", "sys");
    cmds.forEach(([c, d]) => print(`${c.padEnd(18)} — ${d}`, "sys"));
    print("── keyboard shortcuts ────────────────────────", "sys");
    keys.forEach(([c, d]) => print(`${c.padEnd(18)} — ${d}`, "sys"));
    print("──────────────────────────────────────────────", "sys");
  } else {
    print(`unknown command: ${cmd}  (try /help)`, "err");
  }
}

/* ──────────────────────────────────────────────────────────────
   STREAM / AGENTIC CORE
────────────────────────────────────────────────────────────── */
async function callModel() {
  currentAbortController = new AbortController();
  const payload = { model: registry.activeModel, stream: true, messages: activeMessages };
  if (RUNTIME_AVAILABLE_TOOLS.length > 0) payload.tools = RUNTIME_AVAILABLE_TOOLS;
  return await fetch(OLLAMA_URL, {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify(payload),
    signal: currentAbortController.signal
  });
}

async function askAI(promptText) {
  const cur   = registry.list.find(s => s.id === registry.currentActiveId);
  const label = cur ? cur.name : "~";

  print(`user@ollama:[${label}]~$ ${promptText}`, "user");
  const userMsg = { role: "user", content: promptText };
  activeMessages.push(userMsg);
  fullPersistentHistory.push(userMsg);
  updateStatusBar();
  setGenerating(true);

  let guard = 6;
  let isProcessing = true;
  let aborted = false;

  try {
    while (isProcessing && guard-- > 0) {

      // Show thinking indicator for this iteration
      const thinkLine = document.createElement("div");
      thinkLine.className = "line sys";
      thinkLine.innerHTML = `<span style="color:var(--purple)">assistant</span> is thinking<div class="thinking-dots"><span></span><span></span><span></span></div>`;
      log.appendChild(thinkLine);
      log.scrollTop = log.scrollHeight;

      let stream;
      try {
        stream = await callModel();
      } catch (fetchErr) {
        thinkLine.remove();
        if (fetchErr.name === "AbortError") { aborted = true; break; }
        throw fetchErr;
      }

      const reader  = stream.body.getReader();
      const decoder = new TextDecoder();

      let displayEl  = null;
      let textNode   = null;
      let buf        = "";
      let fullText   = "";
      let toolCalls  = [];

      // Remove think line as soon as first chunk arrives
      let thinkRemoved = false;
      const removeThink = () => { if (!thinkRemoved) { thinkLine.remove(); thinkRemoved = true; } };

      try {
        while (true) {
          const { value, done } = await reader.read();
          if (done) break;
          buf += decoder.decode(value, { stream: true });
          const lines = buf.split("\n");
          buf = lines.pop();

          for (const line of lines) {
            if (!line.trim()) continue;
            try {
              const json = JSON.parse(line);
              const msg  = json.message;
              if (msg?.tool_calls?.length) {
                removeThink();
                msg.tool_calls.forEach(c => toolCalls.push(c));
              } else if (msg?.content) {
                removeThink();
                fullText += msg.content;
                if (!displayEl) {
                  displayEl = document.createElement("div");
                  displayEl.className = "line ai";
                  displayEl.innerHTML = `<span>assistant: </span>`;
                  textNode = document.createTextNode("");
                  displayEl.appendChild(textNode);
                  log.appendChild(displayEl);
                }
                textNode.nodeValue += msg.content;
                log.scrollTop = log.scrollHeight;
              }
            } catch {}
          }
        }
      } catch (readErr) {
        removeThink();
        if (readErr.name === "AbortError") { aborted = true; break; }
        throw readErr;
      }

      removeThink(); // guarantee removal even on empty stream

      if (aborted) break;

      if (toolCalls.length > 0) {
        // Discard any streamed text that was just the raw tool-call JSON Ollama leaked
        if (displayEl) displayEl.remove();
        displayEl = null;
        fullText  = "";   // never save tool-call JSON as visible assistant content

        const tc     = toolCalls[0];
        const tName  = tc.function.name;
        const tArgs  = tc.function.arguments || {};

        // ── Collapsible tool block ──────────────────────────────
        const block = document.createElement("div");
        block.className = "tool-block";

        const header = document.createElement("div");
        header.className = "tool-block-header";
        header.innerHTML = `
          <span class="tool-chevron">▶</span>
          <span class="tool-block-label">🔧 ${tName}</span>
          <span class="tool-block-badge">executing…</span>`;
        block.appendChild(header);

        const body = document.createElement("div");
        body.className = "tool-block-body";

        // Args section
        const argsSection = document.createElement("div");
        argsSection.className = "tool-block-section";
        argsSection.innerHTML = `<div class="tool-block-section-label">arguments</div>
          <div class="tool-block-code">${JSON.stringify(tArgs, null, 2)}</div>`;
        body.appendChild(argsSection);

        // Result placeholder
        const resultSection = document.createElement("div");
        resultSection.className = "tool-block-section";
        resultSection.innerHTML = `<div class="tool-block-section-label">result</div>
          <div class="tool-block-code result-text" id="tool-result-${Date.now()}">running…</div>`;
        body.appendChild(resultSection);
        block.appendChild(body);
        log.appendChild(block);
        log.scrollTop = log.scrollHeight;

        // Toggle open/close
        header.addEventListener("click", () => block.classList.toggle("open"));

        // Persist to history (compact)
        const logMsg = `🔧 [MCP] executing → ${tName}`;
        fullPersistentHistory.push({ role: "system", content: logMsg, isToolActivityLog: true });
        fullPersistentHistory.push({ role: "assistant", content: JSON.stringify(tc), isInternalToolCall: true });

        const outcome = await executeMcpToolCall(tName, tArgs);
        const isError = outcome.startsWith("Tool error:");

        // Update block with result
        const resultCode = resultSection.querySelector(".result-text");
        resultCode.textContent = outcome;
        const badge = header.querySelector(".tool-block-badge");
        badge.textContent = isError ? "error" : "done";
        if (isError) block.classList.add("tool-error");
        // Auto-open on error, auto-collapse on success
        if (isError) block.classList.add("open");

        const resultMsg = `📦 [MCP] result: ${outcome.substring(0, 400)}${outcome.length > 400 ? '…' : ''}`;
        fullPersistentHistory.push({ role: "system", content: resultMsg, isToolActivityLog: true });

        activeMessages.push({ role: "assistant", content: fullText || "", tool_calls: toolCalls });
        activeMessages.push({ role: "tool", content: outcome });

      } else {
        isProcessing = false;
        const finalMsg = { role: "assistant", content: fullText };
        activeMessages.push(finalMsg);
        // Only persist messages that have visible text content
        if (fullText.trim()) {
          fullPersistentHistory.push(finalMsg);
        }
      }
    }

    if (aborted) {
      print("⚠ Generation stopped by user.", "sys");
    }

    await saveAllToBrowser();
    pruneActiveMemory();

  } catch (err) {
    print(`runtime error: ${err.message}`, "err");
  } finally {
    setGenerating(false);
  }
}

/* ──────────────────────────────────────────────────────────────
   STOP BUTTON
────────────────────────────────────────────────────────────── */
stopBtn.addEventListener("click", () => {
  if (currentAbortController) {
    currentAbortController.abort();
  }
});

/* ──────────────────────────────────────────────────────────────
   INPUT HANDLER  (command history + stop on Esc)
────────────────────────────────────────────────────────────── */
input.addEventListener("keydown", async (e) => {

  // ── Esc → stop generation ──────────────────────────────────
  if (e.key === "Escape") {
    if (currentAbortController) {
      currentAbortController.abort();
    }
    return;
  }

  // ── ↑ → older history ─────────────────────────────────────
  if (e.key === "ArrowUp") {
    e.preventDefault();
    if (cmdHistory.length === 0) return;
    if (historyIndex === -1) {
      historyDraft   = input.value;   // save current draft
      historyIndex   = cmdHistory.length - 1;
    } else if (historyIndex > 0) {
      historyIndex--;
    }
    input.value = cmdHistory[historyIndex];
    // move cursor to end
    requestAnimationFrame(() => { input.selectionStart = input.selectionEnd = input.value.length; });
    return;
  }

  // ── ↓ → newer history / back to draft ─────────────────────
  if (e.key === "ArrowDown") {
    e.preventDefault();
    if (historyIndex === -1) return;
    if (historyIndex < cmdHistory.length - 1) {
      historyIndex++;
      input.value = cmdHistory[historyIndex];
    } else {
      historyIndex = -1;
      input.value  = historyDraft;
    }
    requestAnimationFrame(() => { input.selectionStart = input.selectionEnd = input.value.length; });
    return;
  }

  // ── Any other key resets history browsing ─────────────────
  if (e.key !== "Enter") {
    if (historyIndex !== -1) {
      // user started editing a history entry — detach
      historyIndex = -1;
    }
    return;
  }

  // ── Enter → submit ─────────────────────────────────────────
  const value = input.value.trim();
  if (!value) return;
  input.value  = "";
  historyIndex = -1;
  historyDraft = "";

  // Push to history (dedupe consecutive identical entries)
  if (cmdHistory[cmdHistory.length - 1] !== value) {
    cmdHistory.push(value);
    if (cmdHistory.length > CMD_HISTORY_MAX) cmdHistory.shift();
  }

  if (value.startsWith("/")) {
    print(`client:[cmd]~$ ${value}`, "user");
    await handleSlashCommand(value);
  } else {
    if (!registry.currentActiveId) {
      print("No active session. Type /new to start one.", "err");
      return;
    }
    await askAI(value);
  }
});

/* ──────────────────────────────────────────────────────────────
   BOOT
────────────────────────────────────────────────────────────── */
async function boot() {
  try {
    const saved = await get(REGISTRY_KEY);
    if (saved?.list?.length) {
      registry = saved;
    } else {
      const id = "s_" + Date.now();
      registry.list.push({ id, name: "general" });
      registry.currentActiveId = id;
    }
  } catch {
    const id = "s_" + Date.now();
    registry.list.push({ id, name: "general" });
    registry.currentActiveId = id;
  }

  renderTopMultiplexerBar();
  await loadSessionData(registry.currentActiveId);
  updateStatusBar();
  await fetchToolsFromMcpServer();

  // Focus input
  input.focus();
}

boot();
</script>
</body>
</html>