docs: Refactor API and introduce Dev Goodies

Author: mirkobrombin

docs/articles/api/animation.md

@@ -1,26 +1,12 @@
 # animation
 
-Helpers for driving simple animations and for leveraging the Web Animations API.
+Helpers for driving simple animations and leveraging the Web Animations API.
 
-- `Translate(sel, from, to, dur)` moves elements.
-- `Fade(sel, from, to, dur)` adjusts opacity.
-- `Scale(sel, from, to, dur)` scales elements.
-- `ColorCycle(sel, colors, dur)` cycles background colors.
-- `Keyframes(sel, frames, opts)` runs a Web Animations API sequence and
-  returns the underlying `Animation` object.
+| Function | Description |
+| --- | --- |
+| `Translate(sel, from, to, dur)` | Moves elements. |
+| `Fade(sel, from, to, dur)` | Adjusts opacity. |
+| `Scale(sel, from, to, dur)` | Scales elements. |
+| `ColorCycle(sel, colors, dur)` | Cycles background colors. |
+| `Keyframes(sel, frames, opts)` | Runs a Web Animations API sequence and returns the underlying `Animation` object. |
 
-## Usage
-
-Call the animation helpers with a CSS selector, starting and ending values,
-and a duration. They can be invoked from event handlers registered in the DOM.
-`Keyframes` accepts arrays of frame definitions and option maps that are
-passed directly to the browser's `Element.animate` API.
-
-> **Note**
-> Prefer RFW APIs like `animation`, `cinema`, and `dom` over direct browser
-> globals. These abstractions improve portability and testability. If an API is
-> missing, fall back to a `js` alias but avoid `js.Global`.
-
-The following example animates elements using these helpers.
-
-@include:ExampleFrame:{code:"/examples/components/animation_component.go", uri:"/examples/animations"}

docs/articles/api/assets.md

@@ -2,52 +2,10 @@
 
 Load images, JSON data, and binary models at runtime with caching and suspense-style loading.
 
-## Context
-
-Applications often need to pull in external resources after the initial page load. The `assets` package provides non-blocking loaders so components remain responsive while files download.
-
-## When to Use
-
-Use these helpers whenever your component requires images, configuration JSON, or binary model data that isn't embedded in the initial bundle.
-
-## How
-
-1. Import the package: `import "github.com/rfwlab/rfw/v1/assets"`.
-2. Call a loader with the asset URL.
-3. Handle `http.ErrPending` while the request completes.
-
-## API
-
 | Function | Description |
 | --- | --- |
 | `LoadImage(url string) (js.Value, error)` | Asynchronously fetches an image and caches it by URL. |
-| `LoadJSON(url string, v any) error` | Fetches JSON into `v` using [`http.FetchJSON`](http#usage). |
+| `LoadJSON(url string, v any) error` | Fetches JSON into `v` using `http.FetchJSON`. |
 | `LoadModel(url string) ([]byte, error)` | Downloads binary data such as glTF models, caching results. |
 | `ClearCache(url string)` | Removes a cached entry for `url`. |
 
-## Example
-
-```go
-var img js.Value
-if v, err := assets.LoadImage("/static/logo.png"); err != nil {
-    if errors.Is(err, http.ErrPending) {
-        return core.Text("loading...")
-    }
-    return core.Text("failed")
-} else {
-    img = v
-}
-return core.Img().Attr("src", img.Get("src").String())
-```
-
-## Notes and Limitations
-
-- Only available in WebAssembly builds.
-- `LoadModel` returns raw bytes; parsing formats like glTF is left to the caller.
-- Clearing the cache is manual via `assets.ClearCache`.
-- Remote URLs may be blocked by CORS; prefer serving images from the same origin.
-
-## Related
-
-- [Assets guide](../guide/assets)
-- [http package](http)

docs/articles/api/cinema.md

@@ -2,67 +2,36 @@
 
 An advanced animation builder for orchestrating scenes, keyframes, and media playback.
 
-- `NewCinemaBuilder(sel)` creates a builder rooted at a DOM element.
-- `AddScene(sel, opts)` sets up a new scene with keyframes and timing.
-- `AddKeyFrame(frame, offset)` appends a keyframe to the current scene using a `KeyFrameMap`.
-- `AddKeyFrameMap(frame, offset)` appends a raw map for advanced cases.
-- `NewKeyFrame()` creates an empty `KeyFrameMap` with chainable `Add` and `Delete` helpers.
-- `AddTransition(props, duration)` generates keyframes for property transitions.
-- `AddSequence(fn)` runs a sequence of builder operations.
-- `AddParallel(fn)` executes builder operations in a goroutine.
-- `AddPause(d)` inserts pauses between steps.
-- `AddLoop(count)` repeats the whole script.
-- `AddVideo(sel)` binds a video element for playback control.
-- `PlayVideo()` starts the bound video.
-- `PauseVideo()` pauses the video.
-- `StopVideo()` stops and rewinds the video.
-- `SeekVideo(t)` jumps to a timestamp.
-- `SetPlaybackRate(rate)` adjusts video speed.
-- `SetVolume(v)` updates volume.
-- `MuteVideo()` silences the audio.
-- `UnmuteVideo()` restores audio.
-- `AddSubtitle(kind, label, srcLang, src)` appends a subtitle track.
-- `AddAudio(src)` injects an audio element.
-- `PlayAudio()` starts the bound audio from the beginning.
-- `PauseAudio()` pauses the audio.
-- `StopAudio()` pauses and rewinds the audio.
-- `SetAudioVolume(v)` updates audio volume.
-- `MuteAudio()` silences the audio.
-- `UnmuteAudio()` restores audio.
-- `AddScripted(fn)` runs custom scripts.
-- `OnStart(fn)` and `OnEnd(fn)` register lifecycle callbacks.
-
-## Usage
-
-Build sequences with keyframes and media controls for rich presentations.
-
-@include:ExampleFrame:{code:"/examples/components/cinema_component.go", uri:"/examples/cinema"}
-
-## Audio playback
-
-### Why
-Supplement animations with sound effects or music cues.
-
-### When
-Use for lightweight audio playback without building a full Web Audio graph.
-
-### How
-1. Call `AddAudio(src)` to attach an audio element.
-2. Trigger `PlayAudio()` when a sound should play.
-3. Adjust output via `SetAudioVolume`, `MuteAudio` or `UnmuteAudio`.
-
-### Example: RTS unit selection
-
-```go
-cinema := animation.NewCinemaBuilder("#root").AddAudio("/sounds/select.mp3")
-dom.RegisterHandlerFunc("selectUnit", func() {
-        cinema.PlayAudio()
-})
-```
-
-### Limitations
-- only a single audio element is tracked; call `AddAudio` with a new source for different sounds
-
-### Related
-[animation](animation), [dom](dom)
+| Function | Description |
+| --- | --- |
+| `NewCinemaBuilder(sel)` | Create a builder rooted at a DOM element. |
+| `AddScene(sel, opts)` | Set up a new scene with keyframes and timing. |
+| `AddKeyFrame(frame, offset)` | Append a keyframe to the current scene using a `KeyFrameMap`. |
+| `AddKeyFrameMap(frame, offset)` | Append a raw map for advanced cases. |
+| `NewKeyFrame()` | Create an empty `KeyFrameMap` with chainable `Add` and `Delete` helpers. |
+| `AddTransition(props, duration)` | Generate keyframes for property transitions. |
+| `AddSequence(fn)` | Run a sequence of builder operations. |
+| `AddParallel(fn)` | Execute builder operations in a goroutine. |
+| `AddPause(d)` | Insert pauses between steps. |
+| `AddLoop(count)` | Repeat the whole script. |
+| `AddVideo(sel)` | Bind a video element for playback control. |
+| `PlayVideo()` | Start the bound video. |
+| `PauseVideo()` | Pause the video. |
+| `StopVideo()` | Stop and rewind the video. |
+| `SeekVideo(t)` | Jump to a timestamp. |
+| `SetPlaybackRate(rate)` | Adjust video speed. |
+| `SetVolume(v)` | Update volume. |
+| `MuteVideo()` | Silence the audio. |
+| `UnmuteVideo()` | Restore audio. |
+| `AddSubtitle(kind, label, srcLang, src)` | Append a subtitle track. |
+| `AddAudio(src)` | Inject an audio element. |
+| `PlayAudio()` | Start the bound audio from the beginning. |
+| `PauseAudio()` | Pause the audio. |
+| `StopAudio()` | Pause and rewind the audio. |
+| `SetAudioVolume(v)` | Update audio volume. |
+| `MuteAudio()` | Silence the audio. |
+| `UnmuteAudio()` | Restore audio. |
+| `AddScripted(fn)` | Run custom scripts. |
+| `OnStart(fn)` | Register a start callback. |
+| `OnEnd(fn)` | Register an end callback. |
 

docs/articles/api/component.md

@@ -0,0 +1,10 @@
+# component
+
+Types and helpers for building reactive components.
+
+| Item | Description |
+| --- | --- |
+| `Component` | Interface implemented by all rfw components. |
+| `HTMLComponent` | Base struct for RTML-backed components. |
+| `ComponentRegistry` | Thread-safe registry for components loaded via `rt-is`. |
+

docs/articles/api/components.md

@@ -0,0 +1,18 @@
+# composition
+
+Utilities for composing DOM nodes and binding elements.
+
+| Function | Description |
+| --- | --- |
+| `Wrap(c *core.HTMLComponent) *Component` | Wrap an `HTMLComponent` to access composition helpers. |
+| `FromProp[T any](c *Component, key string, def T) *state.Signal[T]` | Create a signal from a component prop. |
+| `Group(nodes ...Node) *Elements` | Collect multiple nodes. |
+| `Bind(selector string, fn func(El))` | Apply a function to elements matching a selector. |
+| `BindEl(el dom.Element, fn func(El))` | Apply a function to a specific element. |
+| `For(selector string, fn func() Node)` | Repeat node creation for matching elements. |
+| `Div()` | Build a `<div>` element node. |
+| `A()` | Build an `<a>` element node. |
+| `Span()` | Build a `<span>` element node. |
+| `Button()` | Build a `<button>` element node. |
+| `H(level int)` | Build a heading element. |
+