refac

An updated and more comprehensive section on using custom animation scripts, including a guide for converting standard JavaScript animations to be compatible with the Open WebUI theme engine.

Author: silentoplayz

docs/tutorials/theming.mdx

@@ -125,7 +125,7 @@ Here are the available toggles:
 
 ### CodeMirror Themes
 
-You can customize the appearance of the code editor in Open WebUI by specifying a CodeMirror theme in the `codeMirrorTheme` property of your `theme.json`. A wide variety of themes are available to choose from.
+You can customize the appearance of the code editor in Open WebUI by specifying a `codeMirrorTheme` property of your `theme.json`. A wide variety of themes are available to choose from.
 
 Here is a list of the available CodeMirror themes:
 
@@ -288,37 +288,152 @@ Let's break down the `starfield` example:
 
 #### 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.
+This section provides a step-by-step guide on how to convert a standard JavaScript canvas animation into a format that is compatible with the Open WebUI theme system.
 
-**The Web Worker Environment**
+##### Understanding the Open WebUI Theme Engine
 
-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.
+The Open WebUI theme engine runs custom animation scripts in a **Web Worker**. This is a crucial point to understand, as it imposes several restrictions on the code you can write.
 
-**Receiving Messages**
+**Key characteristics of the Web Worker environment:**
 
-Your script should include an `onmessage` handler to receive data and events from the main application.
+*   **No DOM Access:** You do not have access to the `document` or `window` objects. This means you cannot create or manipulate DOM elements (like `<canvas>`) directly from the animation script.
+*   **Communication via Messaging:** The only way to communicate between the main application and the animation script (the worker) is through the `self.onmessage` and `postMessage` APIs.
+*   **Canvas is an `OffscreenCanvas`:** The main application will create a `<canvas>` element and transfer it to the worker as an `OffscreenCanvas`. You will receive this canvas object in the `init` message.
+
+##### The Conversion Process
+
+Here is a step-by-step guide to converting a typical JavaScript canvas animation.
+
+###### 1. Identify and Isolate the Core Animation Logic
+
+Most canvas animations have the following components:
+
+*   **Setup/Initialization Code:** This code runs once at the beginning to set up the canvas, create initial objects, etc. In a typical script, this might be at the top level of the script.
+*   **Animation Loop:** This is a function that is called repeatedly to draw each frame of the animation. It usually uses `requestAnimationFrame` or `setTimeout`.
+*   **Helper Functions:** These are utility functions for things like math, color manipulation, etc.
+*   **Object Definitions:** These are classes or constructor functions for the objects in the animation (e.g., `Particle`).
+*   **Event Listeners:** These are functions that respond to user input, like `mousemove` or `resize`.
+
+Your goal is to separate these components and adapt them to the worker environment.
+
+###### 2. Adapt the Code for the Worker Environment
+
+Here is a template for a converted animation script. You will need to move the code from the original script into the appropriate sections of this template.
 
 ```javascript
-self.onmessage = (e) => {
+// 1. Paste all helper functions and object definitions here.
+//    (e.g., randomIntFromRange, Particle, etc.)
+
+// 2. Define global variables for the worker script.
+let canvas;
+let ctx;
+let w, h;
+// ... any other global variables your animation needs
+
+// 3. The main message handler for the worker.
+self.onmessage = function(e) {
   if (e.data.type === 'init') {
-    // Initialization logic
+    // This is where the setup/initialization code goes.
+    canvas = e.data.canvas;
+    ctx = canvas.getContext('2d');
+    w = canvas.width = e.data.width;
+    h = canvas.height = e.data.height;
+
+    // Call your initialization function here.
+    init();
+    // Start the animation loop.
+    animate();
+
   } else if (e.data.type === 'resize') {
-    // Resize logic
+    // This is where the resize handling code goes.
+    w = canvas.width = e.data.width;
+    h = canvas.height = e.data.height;
+    // You might need to re-initialize your animation on resize.
+    init();
+
   } else if (e.data.type === 'mousemove') {
-    // Mouse move logic
+    // This is where the mouse move handling code goes.
+    // Update your mouse coordinates object here.
+    mouse.x = e.data.x;
+    mouse.y = e.data.y;
   }
 };
+
+// 4. Your initialization function.
+function init() {
+  // ... your init code here ...
+}
+
+// 5. Your animation loop.
+function animate() {
+  // ... your drawing code here ...
+  requestAnimationFrame(animate);
+}
+```
+
+###### 3. Conversion Checklist
+
+Here is a checklist of common things to look for and change in the original script:
+
+*   **`document.querySelector('canvas')` or `document.getElementById('canvas')`:** Remove these lines. The canvas is provided to you.
+*   **`canvas.getContext('2d')`:** Move this line inside the `init` message handler.
+*   **`canvas.width = window.innerWidth` and `canvas.height = window.innerHeight`:** Remove these lines from the top level of the script. The canvas dimensions are provided in the `init` and `resize` messages.
+*   **`addEventListener('mousemove', ...)` and `addEventListener('resize', ...)`:** Remove these event listeners. This functionality is now handled by the `self.onmessage` handler.
+*   **`requestAnimationFrame(animate)` or `setTimeout(animate, ...)`:** Make sure the animation loop is started by calling `animate()` once from within the `init` message handler. The loop itself should use `requestAnimationFrame(animate)`.
+*   **Global variables:** Make sure any global variables from the original script are defined at the top level of your worker script (outside the `self.onmessage` handler).
+
+###### Example: Before and After
+
+Here is an example of a simple animation before and after conversion.
+
+**Before:**
+```javascript
+const canvas = document.querySelector('canvas');
+const ctx = canvas.getContext('2d');
+canvas.width = window.innerWidth;
+canvas.height = window.innerHeight;
+
+let x = 0;
+
+function animate() {
+  ctx.clearRect(0, 0, canvas.width, canvas.height);
+  ctx.fillRect(x, 100, 50, 50);
+  x += 1;
+  requestAnimationFrame(animate);
+}
+
+animate();
+```
+
+**After:**
+```javascript
+let canvas;
+let ctx;
+let w, h;
+let x = 0;
+
+self.onmessage = function(e) {
+  if (e.data.type === 'init') {
+    canvas = e.data.canvas;
+    ctx = canvas.getContext('2d');
+    w = canvas.width = e.data.width;
+    h = canvas.height = e.data.height;
+    animate();
+  }
+};
+
+function animate() {
+  ctx.clearRect(0, 0, w, h);
+  ctx.fillRect(x, 100, 50, 50);
+  x += 1;
+  if (x > w) {
+    x = 0;
+  }
+  requestAnimationFrame(animate);
+}
 ```
 
--   **`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.
+By following these instructions, you should be able to convert most JavaScript canvas animations to work with the Open WebUI theme system.
 
 ### Example 4: The `Matrix Rain` theme
 
@@ -360,4 +475,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.