glorylab · RockerFlower · Jul 8, 2026 · Jul 8, 2026 · Jul 8, 2026
diff --git a/.github/workflows/publish.yml b/.github/workflows/publish.yml
@@ -8,11 +8,31 @@ on:
 
 jobs:
   publish:
+    name: Publish to pub.dev
     permissions:
       contents: read
       id-token: write
-    uses: dart-lang/setup-dart/.github/workflows/publish.yml@v1
-    with:
-      # Specify the github actions deployment environment
-      environment: pub.dev
-      # working-directory: path/to/package/within/repository
+    runs-on: ubuntu-latest
+    environment: pub.dev
+
+    steps:
+      - uses: actions/checkout@v6
+
+      - name: Set up Dart OIDC
+        uses: dart-lang/setup-dart@v1
+
+      - name: Set up Flutter
+        uses: subosito/flutter-action@v2
+        with:
+          flutter-version: "3.7.12"
+          channel: stable
+          cache: true
+
+      - name: Install dependencies
+        run: dart pub get
+
+      - name: Publish - dry run
+        run: dart pub publish --dry-run
+
+      - name: Publish to pub.dev
+        run: dart pub publish --force
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -1,10 +1,14 @@
 # CHANGELOG
 
-## 0.2.4-dev.1
+## 0.2.4
 
 * Expand Dart SDK compatibility to allow Dart 3.
 * Add CI coverage for both Flutter 3.7.12 and the latest stable Flutter.
 * Avoid deprecated color opacity APIs on current Flutter.
+* Add dartdoc coverage for the main public API.
+* Replace the reusable publish workflow with Node 24 compatible publish steps.
+* Expand README usage guidance with minimal examples, parameter tables, and common errors.
+* Refresh the example app with a Material 3 generator, live performance metrics, and copyable code output.
 
 ## 0.2.3
 

diff --git a/README.md b/README.md
@@ -8,90 +8,157 @@
 [![Pub](https://img.shields.io/pub/v/wave.svg?logo=flutter&style=flat-square)](https://pub.dev/packages/wave)
 ![GitHub](https://img.shields.io/github/license/mashape/apistatus.svg?longCache=true&style=flat-square)
 
-A Flutter package for displaying waves.
+A Flutter package for displaying animated wave backgrounds.
 
 ## Demo
 
 | Platform | URL |
 | -: | -: |
 | Web | [wave.glorylab.xyz](https://wave.glorylab.xyz "The demo page of the wave package.") |
 
+The web demo is an interactive generator. Adjust the config mode, palette,
+layer count, height, amplitude, speed, and loop behavior, then copy the
+generated `WaveWidget` code into your app.
+
+<img src="assets/wave_generator_demo.png" width="1000" alt="Wave Generator web demo with live preview, controls, performance metrics, and generated code dialog entry" />
+
 ## Deployment
 
 The web demo is built from `example/` and deployed with Cloudflare Workers Static Assets. See [docs/cloudflare-workers.md](docs/cloudflare-workers.md) for the GitHub Actions and migration setup.
 
+## Install
 
+```yaml
+dependencies:
+  wave: ^0.2.4
+```
 
-## Getting Started
+## Minimal Example
 
-``` Dart
+```dart
+import 'package:flutter/material.dart';
+import 'package:wave/wave.dart';
 
-static const _backgroundColor = Color(0xFFF15BB5);
+class WaveBackground extends StatelessWidget {
+  const WaveBackground({Key? key}) : super(key: key);
 
-static const _colors = [
-    Color(0xFFFEE440),
-    Color(0xFF00BBF9),
-];
+  @override
+  Widget build(BuildContext context) {
+    return WaveWidget(
+      config: SingleConfig(
+        color: Color(0xFF00BBF9),
+        layers: 3,
+      ),
+      size: Size(double.infinity, double.infinity),
+    );
+  }
+}
+```
 
-static const _durations = [
-    5000,
-    4000,
-];
+Use `WaveWidget` anywhere a normal widget can be painted. Give it a bounded
+parent, such as `SizedBox.expand`, `Positioned.fill`, or a fixed-height
+container.
 
-static const _heightPercentages = [
-    0.65,
-    0.66,
-];
+## Config Modes
 
+### Single color
+
+`SingleConfig` creates layered waves from one base color.
+
+```dart
 WaveWidget(
-    config: CustomConfig(
-        colors: _colors,
-        durations: _durations,
-        heightPercentages: _heightPercentages,
-    ),
-    backgroundColor: _backgroundColor,
-    size: Size(double.infinity, double.infinity),
-    waveAmplitude: 0,
-),
+  config: SingleConfig(
+    color: const Color(0xFF00BBF9),
+    layers: 3,
+  ),
+  size: const Size(double.infinity, double.infinity),
+)
 ```
 
-## Config modes
+### Seeded random colors
 
-`CustomConfig` is the most explicit mode. Use it when you want full control over
-each wave layer's colors or gradients, duration, and height.
+`RandomConfig` creates generated colors for each layer. Provide `seed` when
+deterministic output is useful for tests, demos, or copyable examples. Omit
+`seed` only when you really want a new generated palette for each config
+construction.
 
-``` Dart
+```dart
 WaveWidget(
-    config: CustomConfig(
-        gradients: [
-            [Color(0xFF00BBF9), Color(0xFF9B5DE5)],
-            [Color(0xFFFEE440), Color(0xFFF15BB5)],
-        ],
-        durations: [5000, 4000],
-        heightPercentages: [0.65, 0.66],
-    ),
-    size: Size(double.infinity, double.infinity),
+  config: RandomConfig(
+    seed: 7,
+    layers: 4,
+  ),
+  size: const Size(double.infinity, double.infinity),
 )
 ```
 
-`SingleConfig` creates layered waves from one color. `RandomConfig` creates
-layer colors for you, with an optional `seed` when deterministic output is
-useful for tests or demos.
+### Custom colors or gradients
 
-``` Dart
+`CustomConfig` is the most explicit mode. Use it when you want full control over
+each layer's color or gradient, duration, and height.
+
+```dart
 WaveWidget(
-    config: SingleConfig(
-        color: Color(0xFF00BBF9),
-        layers: 3,
-    ),
-    size: Size(double.infinity, double.infinity),
+  config: CustomConfig(
+    gradients: const [
+      [Color(0xFF00BBF9), Color(0xFF9B5DE5)],
+      [Color(0xFFFEE440), Color(0xFFF15BB5)],
+    ],
+    durations: const [5000, 4000],
+    heightPercentages: const [0.65, 0.66],
+  ),
+  size: const Size(double.infinity, double.infinity),
 )
+```
 
-WaveWidget(
-    config: RandomConfig(
-        seed: 7,
-        layers: 4,
-    ),
-    size: Size(double.infinity, double.infinity),
+## Parameters
+
+### WaveWidget
+
+| Parameter | Type | Default | Description |
+| --- | --- | --- | --- |
+| `config` | `Config` | required | Layer colors, durations, heights, and blur. |
+| `size` | `Size` | required | Paint size for the wave stack. |
+| `waveAmplitude` | `double` | `20.0` | Base vertical movement of the wave path. |
+| `wavePhase` | `double` | `10.0` | Initial phase offset for the animation. |
+| `waveFrequency` | `double` | `1.6` | Horizontal frequency of the wave path. |
+| `duration` | `int?` | `6000` | Total runtime in milliseconds when `isLoop` is false. |
+| `backgroundColor` | `Color?` | `null` | Background color behind the waves. |
+| `backgroundImage` | `DecorationImage?` | `null` | Background image behind the waves. |
+| `isLoop` | `bool` | `true` | Whether animations repeat indefinitely. |
+
+### Config classes
+
+| Class | Best for | Key parameters |
+| --- | --- | --- |
+| `SingleConfig` | One-color layered waves | `color`, `layers`, `opacityPercentages`, `durations`, `heightPercentages` |
+| `RandomConfig` | Fast generated palettes | `layers`, `seed`, `colors`, `durations`, `heightPercentages` |
+| `CustomConfig` | Exact colors or gradients | `colors` or `gradients`, `durations`, `heightPercentages`, `gradientBegin`, `gradientEnd` |
+
+## Common Errors
+
+`CustomConfig` requires exactly one of `colors` or `gradients`.
+
+```dart
+CustomConfig(
+  colors: const [Color(0xFF00BBF9)],
+  gradients: const [
+    [Color(0xFF00BBF9), Color(0xFF9B5DE5)],
+  ],
+  durations: const [5000],
+  heightPercentages: const [0.65],
 )
 ```
+
+All per-layer lists must have the same length.
+
+```dart
+CustomConfig(
+  colors: const [Color(0xFF00BBF9), Color(0xFF9B5DE5)],
+  durations: const [5000],
+  heightPercentages: const [0.65, 0.66],
+)
+```
+
+`heightPercentages` and `opacityPercentages` values must be between `0` and
+`1`, and every `duration` must be positive.
diff --git a/assets/wave_generator_demo.png b/assets/wave_generator_demo.png
diff --git a/example/README.md b/example/README.md
@@ -1,52 +1,30 @@
-# Wave
+# Wave Generator Example
 
-<img src='https://github.com/glorylab/wave/blob/master/assets/wave_banner.png?raw=true' width="1000" height="auto" alt="Flutter package: tm - WAVE" />
+This example is an interactive generator for the `wave` package.
 
----
+Use the controls to adjust:
 
-[![Awesome: Flutter](https://img.shields.io/badge/⌐◨─◨-AwesomeFlutter-blue.svg?logo=flutter&longCache=true&style=flat-square)](https://github.com/Solido/awesome-flutter#effect) 
-[![Pub](https://img.shields.io/pub/v/wave.svg?logo=flutter&style=flat-square)](https://pub.dev/packages/wave)
-![GitHub](https://img.shields.io/github/license/mashape/apistatus.svg?longCache=true&style=flat-square)
+- config mode: `SingleConfig`, seeded `RandomConfig`, or `CustomConfig`
+- palette
+- layer count
+- wave height
+- amplitude
+- animation speed
+- loop behavior
 
-A Flutter package for displaying waves.
+The preview updates immediately, and the top bar shows live frame metrics for
+the current animation. Use **Code** to inspect and copy the complete generated
+Flutter widget from a dialog.
 
 ## Demo
 
 | Platform | URL |
 | -: | -: |
 | Web | [wave.glorylab.xyz](https://wave.glorylab.xyz "The demo page of the wave package.") |
 
+## Run Locally
 
-
-## Getting Started
-
-``` Dart
-
-static const _backgroundColor = Color(0xFFF15BB5);
-
-static const _colors = [
-    Color(0xFFFEE440),
-    Color(0xFF00BBF9),
-];
-
-static const _durations = [
-    5000,
-    4000,
-];
-
-static const _heightPercentages = [
-    0.65,
-    0.66,
-];
-
-WaveWidget(
-    config: CustomConfig(
-        colors: _colors,
-        durations: _durations,
-        heightPercentages: _heightPercentages,
-    ),
-    backgroundColor: _backgroundColor,
-    size: Size(double.infinity, double.infinity),
-    waveAmplitude: 0,
-),
+```sh
+flutter pub get
+flutter run -d chrome
 ```
diff --git a/example/lib/generated_plugin_registrant.dart b/example/lib/generated_plugin_registrant.dart