fix(website): refresh IronRust WinForms examples

Author: fffonion

content/docs/reference/ironrust/internals.md

@@ -1,6 +1,6 @@
 <!-- docs-title: Internals -->
 
-IronRust compiles RustScript bytecode into a CLR assembly and executes a generated `IPdVmProgram`. The WinForms path adds metadata-derived CLR bindings, object handles, a dedicated STA dispatcher, and an event queue.
+IronRust compiles RustScript bytecode into a CLR assembly and executes a generated `IPdVmProgram`. The WinForms path adds metadata-derived CLR bindings, object handles, callable RSS functions, and a main-form application session on the Runner's STA thread.
 
 ## Components
 
@@ -12,12 +12,14 @@ IronRust compiles RustScript bytecode into a CLR assembly and executes a generat
 | `PdVm.Compiler.PdVmVmbcReader` | Decodes VMBC into `PdVmProgramModel`. |
 | `PdVm.Compiler.PdVmStackAnalyzer` | Computes reachable operand-stack depths before IL emission. |
 | `PdVm.Compiler.PdVmClrCompiler` | Emits and saves the generated CLR program assembly. |
-| `PdVm.Runtime.PdVmProgramBase` | Stores resumable program state and implements shared host-call behavior. |
+| `PdVm.Runtime.PdVmProgramBase` | Stores resumable program state, real call frames, callable values, and the serialized callback queue. |
+| `PdVm.Runtime.IPdVmCallableProgram` | Exposes exported and runtime callable values, managed callback creation, reset, and shutdown. |
+| `PdVm.Runtime.PdVmScriptCallback` | Converts managed event arguments, posts RSS callable invocations, and optionally schedules them on a synchronization context. |
 | `PdVm.Runtime.PdVmAssemblyLoader` | Loads the generated assembly and creates its concrete `IPdVmProgram`. |
 | `PdVm.Runtime.PdVmExecution` | Drives `RunStep`, instruction budgets, yield, and asynchronous host completion. |
 | `PdVm.Runtime.PdVmDotNetHost` | Decodes exact CLR binding descriptors, converts values, and invokes CLR members. |
-| `PdVm.Runtime.PdVmWinFormsDispatcher` | Owns the WinForms STA thread and marshals UI work onto it. |
-| `PdVm.Runtime.PdVmWinFormsEventLoop` | Converts WinForms events into RustScript action strings and tracks form state. |
+| `PdVm.Runtime.PdVmWinFormsApplication` | Attaches a callable program to the current STA context, owns callback resources, registers the main form, and runs its message loop. |
+| `PdVm.Runtime.PdVmWinFormsEventLoop` | Binds WinForms events directly to RSS callable values and tracks close permission. |
 
 ## Source-to-assembly pipeline
 
@@ -99,9 +101,11 @@ The operand stack normally lives in generated CLR locals. IronRust materializes
 
 For a saved DLL, `PdVmAssemblyLoader.LoadProgram` registers the output directory for dependency resolution, loads the assembly, finds a non-abstract parameterless type implementing `IPdVmProgram`, and creates it.
 
-For direct `.rss` execution, the Runner compiles to a temporary DLL and calls `PdVmAssemblyLoader.CreateProgram` on an in-memory assembly. Both paths then create the console host, register `PdVmDotNetHost.Call` as fallback host dispatch, and call `PdVmExecution.RunAsync`.
+For direct `.rss` execution, the Runner compiles to a temporary DLL and calls `PdVmAssemblyLoader.CreateProgram` on an in-memory assembly. Both paths then create the console host and register `PdVmDotNetHost.Call` as fallback host dispatch.
 
-`PdVmExecution.RunAsync` repeatedly calls `RunStep` until the program halts. A waiting status is completed through `IAsyncPdVmHost.WaitAsync`, then passed back with `ResumePending`. `--max-steps` supplies the total instruction limit, while checks inside generated CLR code enforce the remaining budget during a single `RunStep` call.
+For non-WinForms profiles, `PdVmExecution.RunAsync` repeatedly calls `RunStep` until the program halts. A waiting status is completed through `IAsyncPdVmHost.WaitAsync`, then passed back with `ResumePending`. `--max-steps` supplies the total instruction limit, while checks inside generated CLR code enforce the remaining budget during a single `RunStep` call.
+
+The WinForms profile requires a callable VMBC v10 program implementing `IPdVmCallableProgram`. The Runner sets a callback error observer, attaches `PdVmWinFormsApplication`, executes top-level RSS setup with `PdVmExecution.Run`, then calls `RunMessageLoop` when `Ui::Show` registered a main form.
 
 ## CLR values and object handles
 
@@ -116,19 +120,12 @@ A generated release call removes both mappings. If the CLR object implements `ID
 
 ## WinForms threading and events
 
-`PdVmWinFormsDispatcher` starts one background thread named `PdVm WinForms UI`, sets it to STA, initializes per-monitor-v2 DPI awareness and WinForms visual styles, creates a hidden `Form` as an invoker, and enters `Application.Run()`.
-
-UI-bound exact calls are sent to that thread with `BeginInvoke`. `PdVmDotNetHost.RequiresWinFormsDispatcher` dispatches members from the `System.Windows.Forms` assembly and most `PdVmWinFormsEventLoop` methods there. `Wait` and `WaitTimeout` are deliberately excluded because they block while waiting for queued work.
-
-`PdVmWinFormsEventLoop` stores one `FormState` per form in a `ConditionalWeakTable`. Each state contains:
+`Program.Main` carries `[STAThread]` and initializes WinForms before entering the Runner. `PdVmWinFormsApplication.Attach` records the callable program and host in an application session bound to that thread. `Ui::Show(form)` registers one main form; after top-level RSS setup completes, `RunMessageLoop` invokes `Application.Run(form)` on the same thread.
 
-- `ConcurrentQueue<QueuedEvent>` for action strings and optional pointer snapshots
-- `AutoResetEvent` to wake `Wait` or `WaitTimeout`
-- the close-permission flag
-- the most recently dequeued pointer snapshot
+Every `BindClick`, `BindShown`, `BindClosing`, pointer, and timer binding accepts an RSS callable value. The application session converts that value into a `PdVmScriptCallback`, schedules it on a `ControlSynchronizationContext` backed by the form's `BeginInvoke`, and tracks both callback and event subscription for disposal.
 
-A click or pointer event runs on the UI thread, enqueues a small record, and signals the waiter. The RustScript VM waits on its execution thread, so the WinForms message loop remains available.
+The CLR event handler calls `Post` and returns without running RustScript inside the managed event stack. `PdVmProgramBase` serializes callback work, restores the callable's function or closure environment, executes it through the generated program, and reports asynchronous failures through `CallbackErrorObserver`.
 
-`BindClosing` installs a delegate matching the form's `FormClosing` event. Before an explicit close is allowed, the handler sets the event argument's `Cancel` property and queues the configured action. `Close` sets `AllowClose`, then invokes the form's `Close` method on the dispatcher thread.
+`BindClosing` installs a delegate matching the form's `FormClosing` event. Until an explicit close is allowed, the handler sets the event argument's `Cancel` property and posts the bound RSS callable. `Ui::Close` sets `AllowClose` and invokes the form's `Close` method from that callback.
 
-This division keeps window creation and application behavior in `examples/dotnet-typed-winforms.rss`; the C# event adapter only provides thread marshalling, action delivery, dialog invocation, pointer snapshots, and close coordination.
+This division keeps window creation and application behavior in `examples/dotnet-typed-winforms.rss`; the C# layer supplies callable adaptation, UI-thread scheduling, dialog invocation, pointer payload conversion, timer subscriptions, and close coordination.

content/docs/reference/ironrust/winforms-example.md

@@ -30,7 +30,7 @@ dotnet run --project PdVm.Runner -- run `
   --profile winforms
 ```
 
-The process remains active until the RustScript event loop handles the close action.
+The Runner executes the top-level RustScript setup, then keeps the process active with the main form's WinForms message loop until the form closes.
 
 ## Keep the compiled assembly
 
@@ -81,7 +81,7 @@ CLR objects cross the RustScript boundary as integer handles. Strings, booleans,
 
 Overloaded members receive generated suffixes such as `String`, `Bool`, or `Array`. Use the exact name accepted by the generated module; the example demonstrates names selected from the current .NET metadata, including `NewToolStripMenuItemString`.
 
-## Event-loop methods
+## Callable event handlers
 
 The example imports the IronRust adapter as `Ui`:
 
@@ -91,38 +91,37 @@ use System::Windows::EventLoop as Ui;
 
 | Method | What it does |
 | --- | --- |
-| `Ui::Show(form)` | Shows the form on IronRust's WinForms dispatcher thread. |
-| `Ui::BindClick(form, control, action)` | Subscribes to `Click` and queues the supplied action string. |
-| `Ui::BindDialog(form, control, dialog, action)` | Uses the control's click event to queue an action. The RustScript handler decides when to call `ShowDialog`. |
-| `Ui::BindClosing(form, action)` | Intercepts `FormClosing`, cancels that close attempt, and queues the action until RustScript calls `Ui::Close`. |
-| `Ui::Wait(form)` | Waits on the VM execution thread until an action is queued. The UI thread remains available to process Windows messages. |
-| `Ui::WaitTimeout(form, milliseconds)` | Returns a queued action, or an empty string after the timeout. |
+| `Ui::Show(form)` | Registers the main form. After top-level RSS setup halts, the Runner enters `Application.Run(form)` on its STA thread. |
+| `Ui::BindClick(form, control, callable)` | Subscribes to `Click` and posts a zero-argument RSS callable. |
+| `Ui::BindDialog(form, control, dialog, callable)` | Convenience click binding for a zero-argument RSS callable; the handler can call `ShowDialog`. |
+| `Ui::BindShown(form, callable)` | Posts a zero-argument RSS callable when the main form is shown. |
+| `Ui::BindClosing(form, callable)` | Cancels the close attempt and posts a zero-argument RSS callable until that handler calls `Ui::Close`. |
+| `Ui::BindMouseDown/Up/DoubleClick/Leave(form, control, callable)` | Posts an RSS callable with a map containing pointer-event data. |
+| `Ui::BindTimer(form, milliseconds, callable)` | Starts a WinForms timer and posts a zero-argument RSS callable on each tick. |
 | `Ui::ShowDialog(form, dialog)` | Calls `ShowDialog(IWin32Window)` with the form as owner and returns the dialog result name. |
-| `Ui::Close(form)` | Allows closing, then calls `Close` on the dispatcher thread. |
-| `Ui::BindPointer(form, control, prefix)` | Queues `<prefix>_down`, `_up`, `_double`, and `_leave` actions. |
-| `Ui::GetPointerButton/X/Y/Clicks(form)` | Reads the pointer snapshot attached to the most recently dequeued pointer event. |
+| `Ui::Close(form)` | Permits the pending close and closes the form. |
 
-The application's behavior remains in RustScript:
+The checked-in Notepad example defines ordinary RSS functions, then binds closures directly to CLR events:
 
 ```rustscript
-Ui::BindDialog(form, open_item, open_dialog, "open");
-Ui::BindClick(form, wrap_item, "wrap");
-Ui::BindClosing(form, "close");
-Ui::Show(form);
-
-while true {
-    let action = Ui::Wait(form);
-    if action == "open" {
-        if Ui::ShowDialog(form, open_dialog) == "OK" {
-            let path = OpenFileDialog::GetOpenFileDialogFileName(open_dialog);
-            RichTextBox::SetRichTextBoxText(editor, File::ReadAllText(path));
-        }
-    }
-    if action == "close" || action == "__closed" {
-        Ui::Close(form);
-        break;
+fn on_open() -> null {
+    if Ui::ShowDialog(form, open_dialog) == "OK" {
+        let current_path = OpenFileDialog::GetOpenFileDialogFileName(open_dialog);
+        SaveFileDialog::SetSaveFileDialogFileName(save_dialog, current_path.copy());
+        RichTextBox::SetRichTextBoxText(editor, File::ReadAllText(current_path.copy()));
     }
+    null
 }
+
+fn on_close() -> null {
+    Ui::Close(form);
+    null
+}
+
+Ui::BindClick(form, open_item, || on_open());
+Ui::BindClick(form, wrap_item, || on_wrap());
+Ui::BindClosing(form, || on_close());
+Ui::Show(form);
 ```
 
-`BindDialog` does not display a dialog itself. It queues the action, then the RustScript branch opens the dialog and handles its result.
+The CLR event adapter returns immediately after posting the callback. IronRust serializes callbacks through the callable program and schedules each handler through the main form's synchronization context, so UI operations execute on the owning STA thread. The application no longer needs a polling loop: each click, close request, pointer event, or timer tick invokes its bound RSS handler directly.

index.html

@@ -315,18 +315,24 @@ <h2>Embedding references.</h2>
             repo: "https://github.com/rustscript-lang/IronRust",
             code: [
               'use System::Windows::Forms::Form;',
+              'use System::Windows::Forms::Button;',
+              'use System::Windows::Forms::Control::ControlCollection;',
               'use System::Windows::EventLoop as Ui;',
               '',
               'let form = Form::NewForm();',
-              'Form::SetFormText(form, "RustScript on .NET");',
-              'Form::SetFormWidth(form, 960);',
-              'Form::SetFormHeight(form, 640);',
-              'Form::SetFormStartPosition(form, "CenterScreen");',
+              'let button = Button::NewButton();',
+              'Button::SetButtonText(button, "Update title");',
+              'ControlCollection::Add(Form::GetFormControls(form), button);',
               '',
-              'Ui::UiBindClosing(form, "close");',
-              'Ui::UiShow(form);',
-              'Ui::UiWait(form);',
-              'Ui::UiClose(form);',
+              'fn on_click() -> null {',
+              '    Form::SetFormText(form, "Handled by RustScript");',
+              '    null',
+              '}',
+              'fn on_close() -> null { Ui::Close(form); null }',
+              '',
+              'Ui::BindClick(form, button, || on_click());',
+              'Ui::BindClosing(form, || on_close());',
+              'Ui::Show(form);',
             ].join("\n"),
           },
           {

tests/carousel.test.mjs

@@ -86,6 +86,28 @@ const examples = [
   ["blinky.rss", "Embedded", "https://github.com/rustscript-lang/micro-rustscript"],
 ];
 
+test("WinForms carousel uses direct RSS callable event handlers", () => {
+  const page = createCarouselPage();
+  const buttons = [...page.window.document.querySelectorAll(".example-dot")];
+
+  buttons[4].click();
+  page.flushTimeouts();
+  const code = page.window.document.getElementById("example-code").textContent;
+
+  for (const expected of [
+    "fn on_close() -> null",
+    "Ui::BindClosing(form, || on_close())",
+    "Ui::Show(form)",
+  ]) {
+    assert.ok(code.includes(expected), `WinForms carousel missing ${expected}`);
+  }
+  for (const retired of ["Ui::Ui", "Ui::Wait", "dispatcher"]) {
+    assert.equal(code.includes(retired), false, `WinForms carousel still contains ${retired}`);
+  }
+
+  page.window.close();
+});
+
 test("carousel renders each example with its exact hardened GitHub action", () => {
   const page = createCarouselPage();
   const { document } = page.window;

tests/docs-build.test.mjs

@@ -236,15 +236,19 @@ test("IronRust documents the checked-in WinForms example and its implementation
     "examples/dotnet-typed-winforms.rss",
     "--profile winforms",
     "System::Windows::EventLoop",
-    "Ui::BindClick",
-    "Ui::BindDialog",
-    "Ui::BindClosing",
-    "Ui::Wait",
+    "fn on_open() -> null",
+    "fn on_close() -> null",
+    "Ui::BindClick(form, open_item, || on_open())",
+    "Ui::BindClosing(form, || on_close())",
+    "Ui::Show(form)",
     "Ui::ShowDialog",
     "Ui::Close",
   ]) {
     assert.ok(exampleText.includes(expected), `WinForms guide missing ${expected}`);
   }
+  for (const retired of ["PdVmWinFormsDispatcher", "Ui::Wait(", "Ui::WaitTimeout(", "action string"]) {
+    assert.equal(exampleText.includes(retired), false, `WinForms guide still contains ${retired}`);
+  }
   exampleWindow.close();
 
   const internalsHtml = await readFile(new URL("../public/docs/reference/ironrust/internals/index.html", import.meta.url), "utf8");
@@ -261,13 +265,18 @@ test("IronRust documents the checked-in WinForms example and its implementation
     "PdVmAssemblyLoader",
     "PdVmExecution",
     "PdVmDotNetHost",
-    "PdVmWinFormsDispatcher",
+    "IPdVmCallableProgram",
+    "PdVmScriptCallback",
+    "PdVmWinFormsApplication",
     "PdVmWinFormsEventLoop",
-    "ConcurrentQueue",
-    "AutoResetEvent",
+    "ControlSynchronizationContext",
+    "RunMessageLoop",
   ]) {
     assert.ok(internalsText.includes(expected), `IronRust internals missing ${expected}`);
   }
+  for (const retired of ["PdVmWinFormsDispatcher", "Ui::Wait", "Ui::WaitTimeout", "AutoResetEvent"]) {
+    assert.equal(internalsText.includes(retired), false, `IronRust internals still contains ${retired}`);
+  }
 
   const ironRustLink = [...window.document.querySelectorAll(".docs-nav-item a")]
     .find((link) => link.textContent === "IronRust");