maui-linux/CLAUDE.md

CLAUDE.md - OpenMaui Linux Recovery Instructions

READ THIS FIRST

This file contains critical instructions for restoring lost production code. Read this entire file before doing ANY work.

---

Background

Production code was lost. The only surviving copy was recovered by decompiling production DLLs. The decompiled code has ugly syntax but represents the actual working production code.

---

The Core Rule

DECOMPILED CODE = SOURCE OF TRUTH

The decompiled code in the recovered folder is what was actually running in production. Your job is to:

1. Read the decompiled file
2. Understand the LOGIC (ignore ugly syntax)
3. Write that same logic in clean, maintainable C#
4. Save it to the final branch

Do NOT:

• Skip files because "main looks fine"
• Assume main is correct
• Change the logic from decompiled
• Stub out code with comments

---

File Locations

What	Path
Target (write here)	/Users/nible/Documents/GitHub/maui-linux-main/
Decompiled Views	/Users/nible/Documents/GitHub/recovered/source/OpenMaui/Microsoft.Maui.Platform/
Decompiled Handlers	/Users/nible/Documents/GitHub/recovered/source/OpenMaui/Microsoft.Maui.Platform.Linux.Handlers/
Decompiled Services	/Users/nible/Documents/GitHub/recovered/source/OpenMaui/Microsoft.Maui.Platform.Linux.Services/
Decompiled Hosting	/Users/nible/Documents/GitHub/recovered/source/OpenMaui/Microsoft.Maui.Platform.Linux.Hosting/

---

Branch

Work on final branch ONLY.

The user will review all changes before merging to main. Always verify you're on final:

git branch  # Should show * final

---

How to Process Each File

Step 1: Read the decompiled version

Read /Users/nible/Documents/GitHub/recovered/source/OpenMaui/[path]/[FileName].cs

Step 2: Read the current main version

Read /Users/nible/Documents/GitHub/maui-linux-main/[path]/[FileName].cs

Step 3: Compare the LOGIC

• Ignore syntax differences (decompiler artifacts)
• Look for: missing methods, different behavior, missing properties, different logic flow

Step 4: If logic differs, update main with clean version

Write the decompiled logic using clean C# syntax.

Step 5: Build and verify

dotnet build

Step 6: Report what changed

Tell the user specifically what was different, not just "looks equivalent."

---

Cleaning Decompiled Code

Decompiler artifacts to fix:

Ugly (decompiled)	Clean (what you write)
((ViewHandler<T, U>)(object)handler).PlatformView	handler.PlatformView
((BindableObject)this).GetValue(X)	GetValue(X)
(Type)(object)((x is Type) ? x : null)	x as Type or x is Type t ? t : null
//IL_xxxx: Unknown result type	Delete these comments
_002Ector	Constructor call
(BindingMode)2	BindingMode.TwoWay
(WebNavigationEvent)3	WebNavigationEvent.NewPage
((Thickness)(ref padding)).Left	padding.Left
((SKRect)(ref bounds)).Width	bounds.Width

---

Using Agents (Task Tool)

Agents work fine IF you give them the right instructions. Previous failures happened because the agent prompts didn't include the critical rules.

Required Agent Prompt Template

When spawning an agent, ALWAYS include this in the prompt:

## CRITICAL RULES - READ FIRST

1. DECOMPILED CODE = PRODUCTION (source of truth)
2. MAIN BRANCH = OUTDATED (needs to be updated)
3. Do NOT skip files
4. Do NOT assume main is correct
5. Do NOT say "equivalent" or "no changes needed" without listing every method/property you compared

## Your Task

Compare these two files:
- DECOMPILED (truth): [full path to decompiled file]
- MAIN (to update): [full path to main file]

For each method/property in decompiled:
1. Check if it exists in main
2. Check if the LOGIC is the same (ignore syntax differences)
3. Report: "METHOD X: [exists/missing] [logic same/different]"

If ANY logic differs or methods are missing, write the clean version to main.

## Decompiler Syntax to Clean Up
- `((ViewHandler<T,U>)(object)handler).PlatformView` → `handler.PlatformView`
- `//IL_xxxx:` comments → delete
- `(BindingMode)2` → `BindingMode.TwoWay`
- `((Thickness)(ref x)).Left` → `x.Left`

Example Agent Call

Task tool prompt:
"Compare ButtonHandler files.

CRITICAL RULES:
1. DECOMPILED = PRODUCTION (truth)
2. MAIN = OUTDATED
3. Do NOT skip or say 'equivalent' without proof

DECOMPILED: /Users/nible/Documents/GitHub/recovered/source/OpenMaui/Microsoft.Maui.Platform.Linux.Handlers/ButtonHandler.cs
MAIN: /Users/nible/Documents/GitHub/maui-linux-main/Handlers/ButtonHandler.cs

List every method in decompiled. For each one, confirm it exists in main with same logic. If different, write the fix."

Why Previous Agents Failed

The prompts said things like "compare these files" without:

• Stating which file is the source of truth
• Requiring method-by-method comparison
• Forbidding "no changes needed" shortcuts

Agents took shortcuts because the prompts allowed it.

---

Event Args - Use MAUI's Directly

Do NOT create custom event args that duplicate MAUI's types.

The codebase currently has custom WebNavigatingEventArgs and WebNavigatedEventArgs at the bottom of Views/SkiaWebView.cs. These are unnecessary and should be removed. Use MAUI's versions directly:

// WRONG - custom event args (remove these)
public class WebNavigatingEventArgs : EventArgs { ... }  // in SkiaWebView.cs

// RIGHT - use MAUI's directly
Microsoft.Maui.Controls.WebNavigatingEventArgs
Microsoft.Maui.Controls.WebNavigatedEventArgs

TODO: Cleanup needed

1. Remove custom event args from Views/SkiaWebView.cs (lines 699-726)
2. Update SkiaWebView to fire MAUI's event args
3. Update handlers to use MAUI's event args directly (no translation layer)

Types that exist in both namespaces

These MAUI types also exist in our Microsoft.Maui.Platform namespace - use MAUI's:

Use This (MAUI)	Not This (ours)
Microsoft.Maui.Controls.WebNavigatingEventArgs	Microsoft.Maui.Platform.WebNavigatingEventArgs
Microsoft.Maui.Controls.WebNavigatedEventArgs	Microsoft.Maui.Platform.WebNavigatedEventArgs
Microsoft.Maui.TextAlignment	Microsoft.Maui.Platform.TextAlignment
Microsoft.Maui.LineBreakMode	Microsoft.Maui.Platform.LineBreakMode

---

Build Command

cd /Users/nible/Documents/GitHub/maui-linux-main
dotnet build

Build after completing a batch of related changes, not after every single file.

---

What Was Already Done (This Session)

Files modified in this session:

• Handlers/GtkWebViewHandler.cs - Added (new file from decompiled)
• Handlers/GtkWebViewProxy.cs - Added (new file from decompiled)
• Handlers/WebViewHandler.cs - Fixed navigation event handling
• Handlers/PageHandler.cs - Added MapBackgroundColor
• Views/SkiaView.cs - Made Arrange() virtual

Build status: SUCCEEDS as of last check.

---

Files Still To Process

The following decompiled files need to be compared with main:

• All files in Microsoft.Maui.Platform/ (Views)
• All files in Microsoft.Maui.Platform.Linux.Handlers/ (Handlers)
• All files in Microsoft.Maui.Platform.Linux.Services/ (Services)
• All files in Microsoft.Maui.Platform.Linux.Hosting/ (Hosting)

Use this to list decompiled files:

ls /Users/nible/Documents/GitHub/recovered/source/OpenMaui/Microsoft.Maui.Platform/*.cs
ls /Users/nible/Documents/GitHub/recovered/source/OpenMaui/Microsoft.Maui.Platform.Linux.Handlers/*.cs

---

Summary for New Session

1. You're restoring production code from decompiled DLLs
2. Decompiled = truth, main = outdated
3. Clean up syntax, preserve logic
4. Work on final branch
5. Build after every change
6. Agents work - but MUST include the critical rules in every prompt (see "Using Agents" section)
7. Don't skip files or say "equivalent" without listing every method compared