feat: Extend devtools with error box

Author: mirkobrombin

docs/articles/devtools.md

@@ -10,6 +10,39 @@ RFW_DEVTOOLS=1 rfw dev --debug
 
 Avoid enabling it for production builds where the overlay is unnecessary.
 
+## Runtime error overlay
+
+### Why
+Surface uncaught panics and JavaScript errors directly in the browser.
+
+### When to use
+Available in development when `RFW_DEVTOOLS=1` is set.
+
+### How
+1. Trigger an error, e.g. `panic("boom")`.
+2. The overlay shows the message and stack trace.
+3. Use the arrow buttons to navigate multiple errors or reload the page.
+
+### API
+The overlay hooks `window` error events through the [`js` package](../api/js) and requires no application code.
+
+### Example
+```go
+func broken() {
+    panic("boom")
+}
+```
+
+@include:ExampleFrame:{code:"/examples/components/runtime_error_component.go", uri:"/examples/runtime-error"}
+
+### Notes
+- Active only in debug builds.
+- Closing the overlay clears captured errors.
+- Stores at most 15 errors per page; additional ones are ignored.
+
+### Related links
+- [js package](../api/js)
+
 ## Development Server
 
 The `rfw dev` command launches a file‑watching server that recompiles your project into WebAssembly on every change. It also serves the generated assets over an HTTP server so you can iterate quickly without leaving the terminal. Any files placed in a top-level `static/` directory are available at the root URL during development, and requests to `/static/*` are transparently served as `/*`. When a `host/` directory is present, `rfw dev` builds and runs the host binary from `build/host/host` so host components can be exercised locally.

docs/examples/components/runtime_error_component.go

@@ -0,0 +1,36 @@
+//go:build js && wasm
+
+package components
+
+import (
+	_ "embed"
+
+	"github.com/rfwlab/rfw/v1/composition"
+	core "github.com/rfwlab/rfw/v1/core"
+	"github.com/rfwlab/rfw/v1/js"
+)
+
+//go:embed templates/runtime_error_component.rtml
+var runtimeErrorComponentTpl []byte
+
+// NewRuntimeErrorComponent demonstrates the runtime error overlay by
+// triggering a JavaScript error followed by a Go panic.
+func NewRuntimeErrorComponent() *core.HTMLComponent {
+	cmp := composition.Wrap(core.NewComponent("RuntimeErrorComponent", runtimeErrorComponentTpl, nil))
+
+	cmp.SetOnMount(func(*core.HTMLComponent) {
+		// Schedule a JavaScript error asynchronously so the overlay captures it
+		// without crashing the Go runtime.
+		js.Window().Call("setTimeout", "throw new Error('js example error')", 0)
+
+		var panicFn js.Func
+		panicFn = js.FuncOf(func(this js.Value, args []js.Value) any {
+			panicFn.Release()
+			panic("example panic")
+			return nil
+		})
+		js.Window().Call("setTimeout", panicFn, 100)
+	})
+
+	return cmp.Unwrap()
+}

docs/examples/components/templates/runtime_error_component.rtml

@@ -0,0 +1,4 @@
+<div class="p-4">
+  <h1>Runtime Error Example</h1>
+  <p>This page triggers a JavaScript error followed by a panic.</p>
+</div>

docs/main.go

@@ -214,6 +214,10 @@ func main() {
 		Path:      "/examples/netcode",
 		Component: func() core.Component { return excomponents.NewNetcodeComponent() },
 	})
+	router.RegisterRoute(router.Route{
+		Path:      "/examples/runtime-error",
+		Component: func() core.Component { return excomponents.NewRuntimeErrorComponent() },
+	})
 
 	router.InitRouter()
 	select {}

v1/composition/node.go

@@ -2,7 +2,11 @@
 
 package composition
 
-import "github.com/rfwlab/rfw/v1/dom"
+import (
+	"fmt"
+
+	"github.com/rfwlab/rfw/v1/dom"
+)
 
 // Node represents a DOM node that can be appended to other nodes.
 type Node interface {
@@ -384,3 +388,62 @@ func (b *buttonNode) Group(g *Elements) *buttonNode {
 	}
 	return b
 }
+
+// headingNode builds an <h1>..<h6> element.
+type headingNode struct{ el dom.Element }
+
+// H creates a new heading node builder for level 1..6 (out-of-range coerced to 1..6).
+func H(level int) *headingNode {
+	if level < 1 {
+		level = 1
+	} else if level > 6 {
+		level = 6
+	}
+	tag := fmt.Sprintf("h%d", level)
+	return &headingNode{el: dom.Doc().CreateElement(tag)}
+}
+
+// Element returns the underlying DOM element.
+func (h *headingNode) Element() dom.Element { return h.el }
+
+// Class adds a class to the element.
+func (h *headingNode) Class(name string) *headingNode {
+	h.el.AddClass(name)
+	return h
+}
+
+// Classes adds multiple classes to the element.
+func (h *headingNode) Classes(names ...string) *headingNode {
+	for _, name := range names {
+		h.el.AddClass(name)
+	}
+	return h
+}
+
+// Style sets an inline style property on the element.
+func (h *headingNode) Style(prop, value string) *headingNode {
+	h.el.SetStyle(prop, value)
+	return h
+}
+
+// Styles adds multiple inline style properties to the element.
+func (h *headingNode) Styles(props ...string) *headingNode {
+	for i := 0; i < len(props); i += 2 {
+		h.el.SetStyle(props[i], props[i+1])
+	}
+	return h
+}
+
+// Text sets the text content of the element.
+func (h *headingNode) Text(t string) *headingNode {
+	h.el.SetText(t)
+	return h
+}
+
+// Group adds the node to the provided group.
+func (h *headingNode) Group(g *Elements) *headingNode {
+	if g != nil {
+		g.add(h)
+	}
+	return h
+}

v1/devtools/errorbox.go

@@ -0,0 +1,62 @@
+package devtools
+
+// runtimeError represents a captured runtime error.
+type runtimeError struct {
+	Message string
+	Stack   string
+	Path    string
+}
+
+var (
+	errList []runtimeError
+	errIdx  int = -1
+)
+
+const (
+	maxRuntimeErrors = 15
+)
+
+// addRuntimeError appends a new runtime error and sets it as current.
+func addRuntimeError(e runtimeError) {
+	if len(errList) >= maxRuntimeErrors {
+		return
+	}
+	errList = append(errList, e)
+	errIdx = len(errList) - 1
+}
+
+// currentRuntimeError returns the active error.
+func currentRuntimeError() (runtimeError, bool) {
+	if errIdx < 0 || errIdx >= len(errList) {
+		return runtimeError{}, false
+	}
+	return errList[errIdx], true
+}
+
+// prevRuntimeError moves to the previous error if available.
+func prevRuntimeError() (runtimeError, bool) {
+	if errIdx > 0 {
+		errIdx--
+	}
+	return currentRuntimeError()
+}
+
+// nextRuntimeError moves to the next error if available.
+func nextRuntimeError() (runtimeError, bool) {
+	if errIdx < len(errList)-1 {
+		errIdx++
+	}
+	return currentRuntimeError()
+}
+
+// resetRuntimeErrors clears all tracked errors.
+func resetRuntimeErrors() {
+	errList = nil
+	errIdx = -1
+}
+
+// runtimeErrorCount returns the number of stored errors.
+func runtimeErrorCount() int { return len(errList) }
+
+// runtimeErrorIndex returns the current error index.
+func runtimeErrorIndex() int { return errIdx }