refac

Author: silentoplayz

docs/tutorials/theming.mdx

@@ -166,9 +166,17 @@ This theme adds a subtle, animated gradient to the background.
 }
 ```
 
-### Example 3: tsParticles Theme
+### Animations
 
-This theme uses `tsParticles` to create an interactive particle background. Paste a valid `tsParticles` JSON config into the `tsparticlesConfig` property.
+Open WebUI supports two powerful methods for creating dynamic, animated backgrounds for your themes: **tsParticles** for easy-to-configure particle effects, and **Custom Animation Scripts** for full control over a canvas element.
+
+#### Using tsParticles
+
+[tsParticles](https://particles.js.org/) is a lightweight library for creating particle animations. You can create a wide variety of effects, from falling snow to interactive starfields.
+
+To use tsParticles, you need to provide a valid configuration object in the `tsparticlesConfig` property of your `theme.json`. The easiest way to get started is to use the [official tsParticles editor](https://particles.js.org/samples/#twinkle) to create your desired effect and then export the JSON configuration.
+
+Let's break down the `starfield` example:
 
 ```json
 {
@@ -190,20 +198,68 @@ This theme uses `tsParticles` to create an interactive particle background. Past
 }
 ```
 
-### Example 4: Custom Animation Theme
+-   **`particles.number`**: Controls the number of particles. `density` makes the number of particles responsive to the screen size.
+-   **`particles.color`**: Sets the color of the particles.
+-   **`particles.shape`**: Defines the shape of the particles (e.g., `circle`, `square`, `triangle`).
+-   **`particles.opacity`**: Controls the transparency of the particles.
+-   **`particles.size`**: Controls the size of the particles.
+-   **`particles.move`**: Defines the movement of the particles, including their `speed` and `direction`.
+
+#### Using a Custom Animation Script
+
+For complete control over your theme's animation, you can provide a JavaScript script in the `animationScript` property. This script runs in a separate Web Worker to ensure the main application remains responsive.
+
+**The Web Worker Environment**
+
+Because the script runs in a Web Worker, it has a few unique characteristics:
+- It does not have access to the `window` or `document` objects.
+- The global scope is `self`.
+- It communicates with the main application via messages.
+
+**Receiving Messages**
+
+Your script should include an `onmessage` handler to receive data and events from the main application.
+
+```javascript
+self.onmessage = (e) => {
+  if (e.data.type === 'init') {
+    // Initialization logic
+  } else if (e.data.type === 'resize') {
+    // Resize logic
+  } else if (e.data.type === 'mousemove') {
+    // Mouse move logic
+  }
+};
+```
+
+-   **`init` message**: This is the first message your script will receive. The `e.data` object will contain:
+    -   `canvas`: An `OffscreenCanvas` object that you can draw on.
+    -   `width`: The initial width of the canvas.
+    -   `height`: The initial height of the canvas.
+-   **`resize` message**: This message is sent whenever the application window is resized. The `e.data` object will contain the new `width` and `height`. You should use this to update your animation's dimensions.
+-   **`mousemove` message**: This message is sent when the user moves their mouse over the application. The `e.data` object will contain the `x` and `y` coordinates of the mouse relative to the canvas.
 
-For complete control, you can provide JavaScript for a custom canvas animation. This script runs in a separate worker thread for performance.
+### Example 4: The `Matrix Rain` theme
+
+The following is an example of a `Matrix Rain` theme.
 
 ```json
 {
   "id": "matrix-rain",
   "name": "Matrix Rain",
   "base": "oled-dark",
   "emoji": "🔢",
-  "animationScript": "const canvas = self.canvas; const ctx = canvas.getContext('2d'); let columns; let drops; function setup() { const width = self.width; const height = self.height; canvas.width = width; canvas.height = height; columns = Math.floor(width / 20); drops = []; for (let i = 0; i < columns; i++) { drops[i] = 1; } } function draw() { ctx.fillStyle = 'rgba(0, 0, 0, 0.05)'; ctx.fillRect(0, 0, canvas.width, canvas.height); ctx.fillStyle = '#0F0'; ctx.font = '15px monospace'; for (let i = 0; i < drops.length; i++) { const text = String.fromCharCode(0x30A0 + Math.random() * 96); ctx.fillText(text, i * 20, drops[i] * 20); if (drops[i] * 20 > canvas.height && Math.random() > 0.975) { drops[i] = 0; } drops[i]++; } } self.onmessage = (e) => { if (e.data.type === 'init') { self.canvas = e.data.canvas; setup(); setInterval(draw, 33); } else if (e.data.type === 'resize') { self.width = e.data.width; self.height = e.data.height; setup(); } };"
+  "css": "#main-container.matrix-rain-bg { background-color: transparent !important; isolation: isolate; position: relative; } #matrix-rain-canvas { position: absolute; top: 0; left: 0; width: 100%; height: 100%; z-index: -1; }",
+  "animationScript": "let animationFrameId;let canvas;let ctx;let columns;let rainDrops=[];const alphabet='アァカサタナハマヤャラワガザダバパイィキシチニヒミリヰギジヂビピウゥクスツヌフムユュルグズブプエェケセテネヘメレヱゲゼデベペオォコソトノホモヨョロヲゴゾドボポヴッンABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789';const fontSize=16;const setup=(width,height)=>{if(!canvas)return;canvas.width=width;canvas.height=height;columns=canvas.width/fontSize;rainDrops=[];for(let x=0;x<columns;x++){rainDrops[x]=1}};const draw=()=>{if(!ctx)return;ctx.fillStyle='rgba(0, 0, 0, 0.05)';ctx.fillRect(0,0,canvas.width,canvas.height);ctx.fillStyle='#06F0BF';ctx.font=`${fontSize}px monospace`;for(let i=0;i<rainDrops.length;i++){const text=alphabet.charAt(Math.floor(Math.random()*alphabet.length));ctx.fillText(text,i*fontSize,rainDrops[i]*fontSize);if(rainDrops[i]*fontSize>canvas.height&&Math.random()>0.975){rainDrops[i]=0}rainDrops[i]++}};let lastTime=0;const fps=15;const interval=1000/fps;const animate=(timestamp)=>{if(timestamp-lastTime>interval){draw();lastTime=timestamp}animationFrameId=requestAnimationFrame(animate)};self.onmessage=(event)=>{if(event.data.type==='init'){canvas=event.data.canvas;ctx=canvas.getContext('2d');setup(event.data.width,event.data.height);animate(0)}else if(event.data.type==='resize'){setup(event.data.width,event.data.height)}};"
 }
 ```
 
+- In the `init` handler, the script gets the `canvas` object, calls a `setup()` function, and then kicks off a performant animation loop using `requestAnimationFrame`.
+- The `animate` function is throttled to run at a specific FPS (15 frames per second) for efficiency.
+- The `draw()` function is where the actual drawing happens, filling the canvas with random characters from a large alphabet to create the Matrix effect.
+- The `resize` handler updates the canvas dimensions and re-runs the `setup()` function to adapt the animation to the new size.
+- The theme also includes a `css` property to make the main container transparent and correctly position the animation canvas behind all other content.
+
 ### Example 5: Background Image Theme
 
 This theme adds a background image to the chat and the overall system.
@@ -223,4 +279,4 @@ This theme adds a background image to the chat and the overall system.
 
 ### Sharing Your Theme
 
-To make your theme easily shareable and updatable, host the `theme.json` file somewhere with a raw file link (like GitHub Gist or a public repository) and set the `sourceUrl` property to that link. This allows others to install your theme with one click and receive updates automatically.
+To make your theme easily shareable and updatable, host the `theme.json` file somewhere with a raw file link (like GitHub Gist or a public repository) and set the `sourceUrl` property to that link. This allows others to install your theme with one click and receive updates automatically.