From 622c4c5eccc900eb6c2b0c42dddcb886659387cf Mon Sep 17 00:00:00 2001
From: tiago <70700766+tiagozip@users.noreply.github.com>
Date: Tue, 23 Sep 2025 17:26:56 +0100
Subject: [PATCH] docs: better widget docs

---
 docs/guide/widget.md | 56 +++++++++++++++++++++-----------------------
 1 file changed, 27 insertions(+), 29 deletions(-)

diff --git a/docs/guide/widget.md b/docs/guide/widget.md
index 880bfcc..4d61f77 100644
--- a/docs/guide/widget.md
+++ b/docs/guide/widget.md
@@ -1,39 +1,37 @@
 # @cap.js/widget
 
-> [!NOTE]
->
-> **Requirements:** All modern browsers should be supported, but the build script specifically targets the last 10 versions of Chrome, Firefox, Safari and Edge.
-
 `@cap.js/widget` is Cap's client-side library. It includes the `cap-widget` web component, the invisible mode and the CAPTCHA solver. First, add it to your client-side code:
 
 ::: code-group
 
-```html
+```html[jsdelivr]
 <script src="https://cdn.jsdelivr.net/npm/@cap.js/widget"></script>
+
+<!-- we're using the latest version of the library here for simplicity, but you should optimally pin a specific version to avoid breaking changes in the future. -->
 ```
 
-```html
+```html[unpkg]
 <script src="https://unpkg.com/@cap.js/widget"></script>
+
+<!-- we're using the latest version of the library here for simplicity, but you should optimally pin a specific version to avoid breaking changes in the future. -->
 ```
 
-```html
-<script src="https://<server url>/assets/widget.js"></script>
+```js[bundler]
+// npm:  npm i @cap.js/widget
+// pnpm: pnpm install @cap.js/widget
+// bun:  bun add @cap.js/widget
 
-<!-- tip: make sure to set the wasm endpoint too! -->
-```
-
-:::
-
-You can also import it if you're using a bundler:
-
-```js
 import Cap from '@cap.js/widget';
+
+// ...
 ```
 
-::: warning
-
-We're using the latest version of the library here for simplicity, but you should optimally pin a specific version to avoid breaking changes in the future.
-
+```html[standalone server]
+<script>
+  window.CAP_CUSTOM_WASM_URL = "https://<server url>/assets/cap_wasm.js";
+</script>
+<script src="https://<server url>/assets/widget.js"></script>
+```
 :::
 
 You can now use the `<cap-widget>` component in your HTML.
@@ -42,24 +40,24 @@ You can now use the `<cap-widget>` component in your HTML.
 <cap-widget id="cap" data-cap-api-endpoint="<your cap endpoint>"></cap-widget>
 ```
 
-> [!NOTE]
->
-> You'll need to start a server with an API exposing the Cap methods running at the same URL as specified in the `data-cap-api-endpoint` attribute.
+**Note:** You'll need to start a server with an API exposing the Cap methods running at the same URL as specified in the `data-cap-api-endpoint` attribute.
 
-> [!TIP] The following attributes are supported:
->
-> - `data-cap-api-endpoint`: API endpoint (required if not using custom fetch)
-> - `data-cap-worker-count`: Number of workers to use (defaults to `navigator.hardwareConcurrency || 8`)
+The following attributes are supported:
+
+- `data-cap-api-endpoint`: API endpoint (required if not using custom fetch)
+- `data-cap-worker-count`: Number of workers to use (defaults to `navigator.hardwareConcurrency || 8`)
+- `onsolve=""`: Event listener for the `solve` event
+- [i18n attributes](#i18n)
 
 Then, in your JavaScript, listen for the `solve` event to capture the token when generated:
 
-```js{3}
+```js
 const widget = document.querySelector("#cap");
 
 widget.addEventListener("solve", function (e) {
   const token = e.detail.token;
 
-  // Handle the token as needed
+  // handle the token as needed
 });
 ```