comet-go

# Comet Go — Single-File App Development Comet Go is a single-file app experience for .NET MAUI using the Comet MVU framework. The user writes ONE `.cs` file, runs `maui go`, and it live-reloads on their device. ## How It Works 1. User writes a single `.cs` file with a `MainPage : View` class 2. `maui go` starts GoDevServer → Roslyn compiles to DLL (OutputKind.DynamicallyLinkedLibrary) 3. DLL is sent over WebSocket to the companion app 4. Companion app loads via `Assembly.Load` → `MetadataUpdater.ApplyUpdate` for hot reload 5. Scaffold new apps with: `maui go create <AppName>` ## Required Imports Every Comet Go file MUST start with: ```csharp #:package Comet using Comet; using Microsoft.Maui; using Microsoft.Maui.Graphics; using static Comet.CometControls; ``` - `using static Comet.CometControls;` enables `VStack(...)`, `Text(...)`, `Button(...)` etc. as top-level functions - Add `using System;` if you need `Math`, `Convert`, `DateTime`, or `TimeSpan` directly - `Action` and `Func<T>` resolve without `using System;` via implicit usings ## App Structure ```csharp namespace MyApp; public class MainPage : View { readonly Reactive<int> count = new(0); [Body] View body() => VStack(spacing: 16f, Text(() => $"Count: {count.Value}"), Button("Tap", () => count.Value++) ); } ``` ## CRITICAL: VStack/HStack Spacing Parameter `VStack(0, ...)` is **ambiguous** between `VStack(float?, params View[])` and `VStack(LayoutAlignment, params View[])`. - ✅ `VStack(spacing: 0f, ...)` — named parameter (clearest) - ✅ `VStack(16f, ...)` — float literal with `f` suffix - ❌ `VStack(0, ...)` — CS0121 ambiguous call - ❌ `VStack(16, ...)` — may be ambiguous Always use `f` suffix or `spacing:` named parameter. ## Available Controls (via `using static Comet.CometControls`) ### Layout ```csharp VStack(float? spacing, params View[] children) // vertical stack HStack(float? spacing, params View[] children) // horizontal stack ZStack(params View[] children) // overlay stack Grid(object[] columns, object[] rows, params View[] children) ScrollView(View content) Border(View content) Spacer() // flexible space ``` ### Display & Input ```csharp // Text display Text("static text") Text(() => $"dynamic {reactive.Value}") // auto-updates when reactive changes Text(() => reactive.Value) // simple reactive binding // Buttons — MUST use lambda, not method group Button("label", () => DoSomething()) // ✅ lambda wrapper Button("label", DoSomething) // ❌ CS1503 — method groups don't work // Text input — requires Signal<string>, NOT Reactive<string> TextField(signal, "placeholder") // two-way binding with Signal<string> SecureField(signal, "Password") // Toggle / Switch Toggle(reactiveBool) // Slider Slider(value: 0.5, minimum: 0, maximum: 1) // Image Image("https://example.com/image.png") // Picker Picker(0, "Option A", "Option B", "Option C") // Others: ProgressBar, ActivityIndicator, DatePicker, TimePicker, Stepper ``` ### Grid Layout ```csharp Grid( columns: new object[] { "*", "*", "*", "*" }, // 4 equal columns rows: new object[] { 70, 70, 70 }, // 3 rows @ 70px Button("1", () => {}).Cell(row: 0, column: 0), Button("2", () => {}).Cell(row: 0, column: 1), Button("wide", () => {}).Cell(row: 1, column: 0, colSpan: 2) ) .ColumnSpacing(10).RowSpacing(10) ``` Column/row definitions: `"*"` (star), `"2*"` (weighted), `"Auto"`, or integer pixels. ## Fluent Styling API Chain these after any control: ```csharp // Typography .FontSize(24) .FontWeight(FontWeight.Bold) // Bold, Medium, Semibold, Regular, Light, Heavy, Thin .Color(Colors.White) // text/foreground color .HorizontalTextAlignment(TextAlignment.End) // Background & shape .Background(new SolidPaint(myColor)) // use SolidPaint for Color values .Background(Colors.Blue) // convenience overload .CornerRadius(12) // ⚠️ BUTTON ONLY — does NOT work on VStack/HStack/etc .RoundedBorder(radius: 12, color: Colors.Gray, width: 1) // rounded corners on ANY view // Layout & spacing .Frame(width: 100, height: 50) // fixed size .Padding(new Thickness(16)) .Margin(new Thickness(8)) .FillHorizontal() // expand to fill horizontal space .FillVertical() // expand to fill vertical space .IgnoreSafeArea() // extend past safe area (root layout) // Other .Alignment(Alignment.Center) .Opacity(0.8) .IsVisible(true) .AutomationId("my-button") // accessibility / test identifier ``` > ⚠️ **`.CornerRadius()` works on Button and Border but NOT on layout views (VStack, HStack, TextField, etc.).** Using it on unsupported views is silently ignored or crashes. Use `.RoundedBorder()` instead for rounded corners on containers and other views. ## Reactive State: Reactive<T> vs Signal<T> ### Reactive<T> — Display binding (read in UI, write in code) ```csharp readonly Reactive<int> count = new(0); readonly Reactive<string> display = new("0"); // Read in reactive lambda — UI auto-updates when .Value changes Text(() => $"Count: {count.Value}") // Write to trigger UI update Button("Add", () => count.Value++) ``` ### Signal<T> — Two-way binding (for text input) ```csharp using Comet.Reactive; // needed for Signal<T> readonly Signal<string> username = new Signal<string>(""); // TextField REQUIRES Signal<string>, not Reactive<string> TextField(username, "Enter name") // Read signal value reactively Text(() => $"Hello, {username.Value}!") ``` > 🔑 Use `Reactive<T>` for display-only state. Use `Signal<T>` (from `Comet.Reactive`) for `TextField` two-way binding. ## FontWeight Values Available: `Bold`, `Semibold`, `Medium`, `Regular`, `Light`, `Heavy`, `Thin`, `UltraLight`, `UltraBold`, `Black` > ❌ `FontWeight.SemiBold` (capital B) does NOT exist — use `FontWeight.Semibold` (lowercase b). ## Color Reference `Colors.*` from `Microsoft.Maui.Graphics`: ``` Colors.White, Colors.Black, Colors.Red, Colors.Green, Colors.Blue, Colors.Orange, Colors.Yellow, Colors.Purple, Colors.Pink, Colors.Grey, Colors.Gray, Colors.DarkGray, Colors.LightGray, Colors.Transparent, Colors.DodgerBlue, Colors.Crimson, Colors.Teal, Colors.Coral, Colors.Gold, Colors.Indigo, Colors.Lime, Colors.Navy ``` Custom hex colors: `Color.FromArgb("#FF9F0A")` ## Hot Reload Constraints The Go dev server uses Edit-and-Continue (EnC). Know what works and what doesn't: ### ✅ Works — delta produced, UI updates - Method body changes (text, colors, layout, logic) - Field initializer value changes - New methods in existing types - Lambda expression changes ### ⚠️ Unreliable — sometimes works, sometimes crashes - Adding new fields or properties to existing classes ### ❌ Restart required (`Ctrl+C` and re-run `maui go`) - Adding new classes or types - Changing constructor signatures - Changing method signatures (parameters, return type) - Changing base classes or interfaces ### Design Principle Design your initial file with all methods you'll need. During hot reload, modify method *bodies* freely. If you need structural changes (new types, new fields), restart. ```csharp // ✅ SAFE: Multiple methods defined at initial compile. Bodies can change freely. void Append(string digit) { /* body can change via hot reload */ } void SetOp(string op) { /* body can change via hot reload */ } void Calculate() { /* body can change via hot reload */ } ``` ## Anti-Patterns That Cause Crashes 1. **Unicode operators in switch expressions** — `"÷"`, `"×"`, `"−"` cause encoding issues in the hot reload pipeline. Use ASCII: `"/"`, `"x"`, `"-"`. 2. **`.CornerRadius()` on non-Button views** — silently ignored or crashes. Use `.RoundedBorder()` for containers. 3. **`Button("Go", MyMethod)`** — CS1503 error. Method groups don't work. Must be `Button("Go", () => MyMethod())`. 4. **`Reactive<string>` for TextField** — won't bind two-way. TextField requires `Signal<string>`. 5. **`FontWeight.SemiBold`** (capital B) — doesn't exist. Use `FontWeight.Semibold`. 6. **String interpolation lambdas to string params** — `SomeHelper(() => $"val {x}")` fails if the method takes `string`. Inline the interpolation in `body()` since the whole body is reactive. 7. **`using new VStack { ... }`** collection initializer syntax — use `VStack(spacing: 8f, child1, child2)`. ## Common Mistakes to Avoid 1. Missing `using static Comet.CometControls;` — `VStack`, `Text`, `Button` won't resolve 2. Using `VStack(0, ...)` without `f` suffix — ambiguous overload 3. Using `new Text(...)` instead of `Text(...)` — use the clean static API 4. Forgetting `() =>` wrapper for reactive text — `Text(() => $"{x.Value}")` not `Text($"{x.Value}")` 5. Using MAUI Controls APIs (Shell, NavigationPage) — Comet has its own navigation 6. Using `Reactive<string>` for TextField — use `Signal<string>` from `Comet.Reactive` ## Example: Calculator App (E2E Verified) Built from template, hot-reloaded, and interactively tested with button taps and arithmetic verification. ```csharp #:package Comet using Comet; using Microsoft.Maui; using Microsoft.Maui.Graphics; using static Comet.CometControls; namespace Calculator; public class MainPage : View { readonly Reactive<string> display = new("0"); readonly Reactive<string> subDisplay = new(""); double accumulator = 0; string pendingOp = ""; bool resetOnNext = false; void Append(string digit) { if (resetOnNext) { display.Value = "0"; resetOnNext = false; } if (display.Value == "0" && digit != ".") display.Value = digit; else if (digit == "." && display.Value.Contains(".")) return; else display.Value += digit; } void SetOp(string op) { if (pendingOp != "") DoCalculate(); accumulator = double.Parse(display.Value); pendingOp = op; subDisplay.Value = $"{accumulator} {op}"; resetOnNext = true; } void DoCalculate() { if (pendingOp == "") return; double current = double.Parse(display.Value); double result = pendingOp switch { "+" => accumulator + current, "-" => accumulator - current, "x" => accumulator * current, "/" => current != 0 ? accumulator / current : 0, _ => current }; display.Value = result.ToString(); subDisplay.Value = ""; accumulator = result; pendingOp = ""; resetOnNext = true; } [Body] View body() { var darkBg = Color.FromArgb("#1C1C1E"); var numBg = Color.FromArgb("#3A3A3C"); var opBg = Color.FromArgb("#FF9F0A"); var fnBg = Color.FromArgb("#636366"); var eqBg = Color.FromArgb("#30D158"); return VStack(spacing: 0f, new Spacer(), Text(() => subDisplay.Value) .FontSize(18).Color(Colors.Grey) .HorizontalTextAlignment(TextAlignment.End) .Margin(new Thickness(20, 0)), Text(() => display.Value) .FontSize(56).FontWeight(FontWeight.Bold) .Color(Colors.White) .HorizontalTextAlignment(TextAlignment.End) .Margin(new Thickness(20, 0, 20, 16)), Grid(