tiny-essentials 1.26.4 → 1.27.0

package/docs/v1/basics/mediaContent.md

@@ -0,0 +1,131 @@
+# 🎵 Media Content Module
+
+Welcome to the documentation for the media content module! This module is the heart of the media processing pipeline, responsible for downloading audio, extracting rich metadata (ID3 tags), managing memory for image blobs, and preparing finalized `MediaContent` objects for the radio system. 🚀
+
+---
+
+## 📦 Data Structures & Types
+
+These definitions ensure type safety and provide a clear blueprint for how media information is structured throughout the application.
+
+### 🎼 Core Metadata Types
+
+| Type | Description |
+| :--- | :--- |
+| `MediaContent` | **The Final Object.** A combination of `MediaContentBase` and `MediaContentMetadata`. This is what the system uses for playback. |
+| `MediaContentBase` | The essential properties: `id`, `title`, `artist`, `duration`, `url`, and `weight`. |
+| `MediaContentMetadata` | Rich metadata modeled after `music-metadata`. Includes `album`, `genre`, `year`, `track` info, etc. |
+| `MediaNumber` | A structure for indexing: `{ no: number \| null, of: number \| null }`. |
+| `UnknownArtistGetter` | A type that can be a `string` or a function returning a `string`. |
+
+### 🖼️ Image & Picture Types
+
+| Type | Description |
+| :--- | :--- |
+| `IPicture` | Represents an image attachment (like album art). |
+| `IPictureTemplate<T>` | A generic template for pictures, where `T` is the data type (`Uint8Array` or `string`). |
+
+### 🚦 Progress & Error Types
+
+| Type | Description |
+| :--- | :--- |
+| `LoadingMediaProgress` | Tracks the current state: `status` ('loading' or 'success'), `stage`, and the `url`. |
+| `LoadingProgressStage` | Stages: `INITIALIZING` ➡️ `DOWNLOADING` ➡️ `METADATA_LOADED` ➡️ `EXTRACTING_ID3` ➡️ `COMPLETE`. |
+| `LoadingErrorStage` | Error stages: `INITIALIZING`, `DOWNLOADING`, `METADATA`, `ID3`, or `UNKNOWN`. |
+
+---
+
+## ❌ Custom Errors
+
+### `MediaLoadingError`
+Used to provide specific context when something goes wrong during the media preparation lifecycle.
+
+*   **Properties:**
+    *   `message`: Human-readable error description.
+    *   `url`: The URL that caused the failure.
+    *   `stage`: The `LoadingErrorStage` where the error occurred.
+
+---
+
+## 🛠️ Utility Functions
+
+### Factory & Validation
+
+| Function | Description |
+| :--- | :--- |
+| `getMediaContentBase` | Returns a fresh, empty `MediaContentBase` object. |
+| `getMediaContentMetadata` | Returns a fresh, empty `MediaContentMetadata` object. |
+| `valMediaContentMetadata` | Performs strict validation on a full `MediaContentMetadata` object. |
+| `valMediaContentMetadataPartial` | Performs validation on a partial metadata object (useful for patches/updates). |
+
+### Data & Memory Management
+
+| Function | Description |
+| :--- | :--- |
+| `generateSimpleHash` | Generates a deterministic 8-character ID from a string using SHA-1. |
+| `convertToBlobUrl` | Converts `Uint8Array` or Base64 strings into high-performance Blob URLs. It also tracks usage to prevent memory leaks. |
+| `blobUrlToBase64` | Converts a `blob:` URL back into a Base64 Data URL. Useful for exporting data. |
+| `revokeContentUrls` | Safely cleans up memory by revoking Blob URLs associated with a `MediaContent` object. **Call this when media is no longer needed!** 🧹 |
+
+---
+
+## 🚀 Main Operations
+
+### `extractMediaId3Tags`
+Downloads an audio file and uses a provided parser to extract its internal metadata.
+
+*   **Parameters:**
+    *   `url` (string): The full URL of the audio file.
+    *   `parseFile` (Function): A callback that accepts a `Blob` and returns a promise with metadata.
+*   **Returns:** `Promise<MediaContentMetadata>`
+*   **Throws:** `TypeError` for invalid arguments or `Error` for network/parsing failures.
+
+---
+
+### `parseMediaMetadata`
+**The Primary Factory Method.** This is the main entry point for turning a URL or an Audio element into a fully prepared `MediaContent` object. It handles the heavy lifting: downloading, metadata extraction, fallback logic, and progress reporting.
+
+#### 📝 Parameters
+
+| Parameter | Type | Description |
+| :--- | :--- | :--- |
+| `source` | `string \| HTMLMediaElement` | The audio source (URL or Audio object). |
+| `defaultMetadata` | `Partial<MediaContent>` | Default data for the metadata. |
+| `metadata` | `Partial<MediaContent>` | Manual overrides for the metadata (highest priority). |
+| `parseFile` | `ParseMediaContentMetadata` | The library function used to parse the file. |
+| `callbacks` | `Object` | Contains `onProgress` and `onError` listeners. |
+| `unknownArtist` | `UnknownArtistGetter` | Logic to determine the artist if none is found. |
+
+#### 💡 Usage Examples
+
+**1. Using a simple URL with manual overrides:**
+```javascript
+import { parseMediaMetadata } from './mediaContent.mjs';
+import { parseBlob } from 'music-metadata';
+
+// Note: We pass empty objects for default/manual if we want to jump straight to the parser
+const track = await parseMediaMetadata(
+  '/assets/song.mp3', 
+  {}, 
+  { title: 'Manual Override' }, 
+  parseBlob
+);
+
+console.log(track.title); // "Manual Override"
+```
+
+**2. Using an existing Audio object with progress tracking:**
+```javascript
+const audio = new Audio('/assets/song.mp3');
+
+const track = await parseMediaMetadata(
+  audio,
+  {},
+  {},
+  parseBlob,
+  {
+    onProgress: (p) => console.log(`[${p.stage}] ${p.status}`),
+    onError: (e) => console.error(`Error at ${e.stage}: ${e.error.message}`)
+  }
+);
+```

package/docs/v1/libs/TinyClassManager/TinyPluginInliner.md

@@ -0,0 +1,107 @@
+# 🛠️ TinyPluginInliner
+
+`TinyPluginInliner` is a powerful **build-time utility** designed specifically to complement the `TinyClassManager`. 
+
+When using `TinyClassManager`, you compose classes using a mixin pattern via the `.insert()` method. While this is incredibly flexible for development, it creates a challenge for deployment: you end up with many small, interconnected files and complex import paths. 
+
+**`TinyPluginInliner` solves this by "inlining" your plugins directly into a single, self-contained bundle.** It automates the process of fetching plugin code, rewriting their internal import paths, and hoisting dependencies to the top of your final file. 🚀
+
+---
+
+## ✨ Key Features
+
+* **📦 Automatic Inlining:** It scans your entry file for `.insert(PluginName)` calls and replaces them with the actual source code of the plugin.
+* **🔗 Smart Path Rewriting:** It automatically corrects `import` statements inside your plugins so they point to the correct relative locations in your `dist` folder.
+* **📚 JSDoc Support:** It doesn't just fix code; it also rewrites `import()` calls and `@typedef` paths inside JSDoc comments, ensuring your IDE (like VS Code) keeps providing perfect autocomplete in the bundled version.
+* **🌐 NPM Integration:** It can reach into your `node_modules`, grab an NPM package used by a plugin, and inline it into your bundle, even fixing that package's internal relative paths!
+* **🔄 Root Remapping:** Through `rootReplacement`, you can tell the inliner to automatically swap directory names (e.g., changing all `src/` imports to `dist/` imports).
+* **🔝 Dependency Hoisting:** It collects all necessary imports and type definitions from all plugins and moves them to the very top of the generated file for a clean, valid structure.
+
+---
+
+## ⚙️ Configuration
+
+When creating an instance of `TinyPluginInliner`, you provide an `InlinerConfig` object:
+
+| Property | Type | Description |
+| :--- | :--- | :--- |
+| `entryPoint` | `string` | The absolute or relative path to your main file (where you call `.insert()`). |
+| `outDir` | `string` | The directory where the final bundle will be saved. |
+| `outFileName` | `string` | The name of the generated bundle file (e.g., `bundle.mjs`). |
+| `rootReplacement` | `Object` | *(Optional)* An object `{ from: string, to: string }` to remap project roots. |
+
+---
+
+## 🚀 How to Use
+
+### 1. Develop your Plugins
+Your plugins must follow the `TinyClassManager` requirement of having static properties for identification.
+
+```javascript
+// src/plugins/LoggerPlugin.mjs
+export class LoggerPlugin {
+  static _tinyDepName = 'Logger';
+  static _tinyDeps = [];
+
+  constructor(Base) {
+    super();
+    this.log = (msg) => console.log(`[LOG]: ${msg}`);
+  }
+}
+```
+
+### 2. Create your Entry Point
+This is the file that uses the `TinyClassManager` to compose your final class.
+
+```javascript
+// src/main.mjs
+import TinyClassManager from './libs/TinyClassManager.mjs';
+import { LoggerPlugin } from './plugins/LoggerPlugin.mjs';
+
+class BaseUser {}
+
+// The Inliner will look for this specific pattern!
+const User = new TinyClassManager(BaseUser)
+  .insert(LoggerPlugin) 
+  .build();
+
+export default User;
+```
+
+### 3. Run the Inliner
+Create a build script (e.g., `build.mjs`) to trigger the process.
+
+```javascript
+import TinyPluginInliner from './libs/TinyClassManager/TinyPluginInliner.mjs';
+
+const builder = new TinyPluginInliner({
+  entryPoint: 'src/main.mjs',
+  outDir: 'dist',
+  outFileName: 'app.bundle.mjs',
+  // This ensures that if a plugin imports from 'src/utils', 
+  // it will be rewritten to 'dist/utils' in the bundle.
+  rootReplacement: {
+    from: 'src',
+    to: 'dist',
+  },
+});
+
+builder.build();
+```
+
+---
+
+## 🔄 Before vs. After
+
+### 📝 Before (Development)
+Your project is a web of files:
+* `src/main.mjs` $\rightarrow$ imports `LoggerPlugin`
+* `src/plugins/LoggerPlugin.mjs` $\rightarrow$ imports `src/utils/helper.mjs`
+
+### 📦 After (Production Bundle)
+The `dist/app.bundle.mjs` is a single, massive, but perfectly valid file:
+1. **Top:** All imports from `main.mjs`, `LoggerPlugin.mjs`, and `helper.mjs` are hoisted here.
+2. **Middle:** All `@typedef` definitions are gathered here.
+3. **Bottom:** The logic of `main.mjs` runs, but the `.insert(LoggerPlugin)` call has been replaced by the actual code of the `LoggerPlugin` class, which now correctly references the hoisted helper functions.
+
+**Everything is ready to be shipped!** 🚢💨

package/docs/v1/libs/TinyDragDropDetector.md

@@ -21,7 +21,6 @@ A lightweight JavaScript utility for detecting drag-and-drop file operations on
 import TinyDragDropDetector from './TinyDragDropDetector.js';
 
 const dnd = new TinyDragDropDetector({
-  fullscreen: false,
   target: document.getElementById('drop-area'),
   hoverClass: 'hover-effect',
   onDrop: (files, event) => {
@@ -50,19 +49,19 @@ A drag-and-drop detector instance.
 ### Constructor
 
 ```javascript
-new TinyDragDropDetector(options)
+new TinyDragDropDetector(target, options)
 ```
 
 #### Parameters:
 
-| Name      | Type                                        | Default | Description           |
-| --------- | ------------------------------------------- | ------- | --------------------- |
-| `options` | [`DragAndDropOptions`](#draganddropoptions) | `{}`    | Configuration object. |
+| Name      | Type                                        | Description           |
+| --------- | ------------------------------------------- | ------------------------------------------------------- |
+| `target`  | `HTMLElement`                               | The DOM element where drag listeners will be attached.  |
+| `options` | [`DragAndDropOptions`](#draganddropoptions) | Configuration object.                                   |
 
 #### Throws:
 
 * `TypeError` if `target` is not an `HTMLElement`.
-* `TypeError` if `fullscreen` is not a boolean.
 * `TypeError` if `hoverClass` is not a string.
 * `TypeError` if `onDrop` is not a function.
 * `TypeError` if `onEnter` is defined but not a function.
@@ -76,7 +75,6 @@ new TinyDragDropDetector(options)
 | ----------------- | ------------- | ------------------------------------------------------------------------ |
 | `getTarget()`     | `HTMLElement` | Returns the DOM element where listeners are attached.                    |
 | `getHoverClass()` | `string`      | Returns the CSS class applied during drag hover.                         |
-| `isFullScreen()`  | `boolean`     | Indicates whether the detector is in fullscreen mode (`document.body`).  |
 | `isDragging()`    | `boolean`     | Returns whether a drag operation is currently active over the target.    |
 | `bound()`         | `boolean`     | Returns whether the event listeners are currently bound to the target.   |
 | `destroy()`       | `void`        | Destroys the detector, unbinding all events and cleaning up CSS classes. |
@@ -98,8 +96,6 @@ new TinyDragDropDetector(options)
 ```javascript
 /**
  * @typedef {Object} DragAndDropOptions
- * @property {HTMLElement} [target=document.body] - The DOM element where drag listeners will be attached. Defaults to `document.body` if `fullscreen` is true or no target is provided.
- * @property {boolean} [fullscreen=true] - If true, listeners are attached to the entire page (`document.body`). If false, the `target` must be specified.
  * @property {string} [hoverClass="dnd-hover"] - CSS class applied to the target element while files are being dragged over it.
  * @property {(files: FileList, event: DragEvent) => void} onDrop - Callback function executed when files are dropped onto the target.
  * @property {(event: DragEvent) => void} [onEnter] - Optional callback triggered when dragging enters the target area.

package/docs/v1/libs/TinyElementObserver.md

@@ -22,14 +22,13 @@ type ElementDetectorsFn = (
 ## 🔹 Constructor
 
 ```ts
-new TinyElementObserver({
-  el?: Element,
+new TinyElementObserver(el, {
   initDetectors?: Array<[string, ElementDetectorsFn]>,
   initCfg?: MutationObserverInit
 })
 ```
 
-* **`el`** *(optional)* → Initial element to observe 🏷️
+* **`el`** → Initial element to observe 🏷️
 * **`initDetectors`** *(optional)* → Array of detectors to register on creation 🎛️
 * **`initCfg`** *(optional)* → Initial `MutationObserverInit` configuration ⚙️
 
@@ -39,7 +38,6 @@ new TinyElementObserver({
 
 | Property    | Type                                  | Description                                               |
 | ----------- | ------------------------------------- | --------------------------------------------------------- |
-| `el`        | `Element \| undefined`                | The DOM element being observed. Can only be set once. 🏗️ |
 | `settings`  | `MutationObserverInit`                | Observer configuration object. 🔧                         |
 | `observer`  | `MutationObserver \| null`            | Internal observer instance.                               |
 | `detectors` | `Array<[string, ElementDetectorsFn]>` | List of registered detectors.                             |
@@ -85,8 +83,7 @@ const logDetector = (mutation, index, mutations) => {
 };
 
 // Create instance
-const observer = new TinyElementObserver({
-  el: document.querySelector('#target'),
+const observer = new TinyElementObserver(document.querySelector('#target'), {
   initDetectors: [['logger', logDetector]],
   initCfg: { childList: true, subtree: true }
 });

package/docs/v1/libs/TinyHtml.md

@@ -767,32 +767,6 @@ Finds elements by tag name in a namespace (defaults to XHTML).
 
 ## 🔍 Element Observer
 
-### ⚡ `autoStartElemObserver`
-
-A **flag** that determines whether the internal element observer should automatically start when some library code initializes.
-
-* **Type** 🔘 — `boolean`
-* **Default** 🏁 — `true`
-
-#### 📥 Getter
-
-```js
-TinyHtml.autoStartElemObserver; // returns true or false
-```
-
-Returns the current state of the auto-start flag.
-
-#### 📤 Setter
-
-```js
-TinyHtml.autoStartElemObserver = false;
-```
-
-Updates the flag.
-⚠️ Throws a `TypeError` if the value is not a boolean.
-
----
-
 ### 👀 `tinyObserver`
 
 The internal **[`TinyElementObserver`](./TinyElementObserver.md)** instance used by TinyHtml to track DOM changes.
@@ -857,9 +831,6 @@ document.addEventListener('tinyhtml.classchanged', (e) => {
   console.log('🏷️ Class changed:', e.detail);
 });
 
-// Disable auto-start (if needed)
-TinyHtml.autoStartElemObserver = false;
-
 // Manually start the observer
 TinyHtml.tinyObserver.start();
 ```

package/docs/v1/libs/TinyMediaPlayer.md

@@ -0,0 +1,100 @@
+# 🎧 TinyMediaPlayer Documentation
+
+`TinyMediaPlayer` is a robust, universal media player manager designed to orchestrate playback across multiple different media providers (such as YouTube, Spotify, etc.) using an **Adapter Pattern**.
+
+---
+
+## 🧩 Core Architecture: The Adapter Pattern
+
+To support different media platforms, `TinyMediaPlayer` relies on **Adapters**. You must create a class that extends `BaseMediaAdapter` for every new service you wish to support.
+
+### 🛠️ `BaseMediaAdapter` (Abstract Class)
+*This class cannot be instantiated directly. It serves as an interface.*
+
+| Method | Description | Parameters | Returns |
+| :--- | :--- | :--- | :--- |
+| `canHandle` | Checks if the adapter supports a specific content item. | `content: MediaContent` | `boolean` |
+| `play` | Starts or resumes playback. | `content: MediaContent` | `Promise<void>` |
+| `pause` | Pauses the current playback. | None | `Promise<void>` |
+| `stop` | Stops playback and resets the platform state. | None | `Promise<void>` |
+| `seek` | Jumps to a specific time. | `timeMs: number` | `Promise<void>` |
+| `getCurrentTime` | Gets the current playback position. | None | `number` (ms) |
+| `setVolume` | Sets the volume level. | `volume: number` (0.0 to 1.0) | `void` |
+
+---
+
+## 🚀 `TinyMediaPlayer` Class
+
+The main controller for managing playlists, playback state, and adapters.
+
+### ⚙️ Configuration (Constructor Options)
+When initializing `new TinyMediaPlayer(options)`, you can pass the following:
+
+*   **`persistVolume`** (`boolean`): If `true`, the volume level is automatically saved to and loaded from `localStorage`. (Default: `false`).
+*   **`volumeStorageKey`** (`string`): The key name used in `localStorage` to store the volume. (Default: `'tiny_media_player_volume'`).
+
+---
+
+### 🏗️ Static Members
+
+#### Properties
+*   **`unknownArtist`**: A global setting for when an artist's name is unavailable.
+    *   **Type**: `string` | `function` (returns a string).
+    *   **Getter/Setter**: Allows you to define a custom string or a logic-based function.
+
+#### Methods
+*   **`parseContent(source, defaultMetadata, metadata, parseFile, callbacks)`**: 
+    *   A static factory method to prepare a `MediaContent` object by extracting metadata from a URL or HTMLMediaElement.
+    *   **Returns**: `Promise<MediaContent>`.
+
+---
+
+### 📊 Instance Properties (Getters & Setters)
+
+| Property | Type | Description |
+| :--- | :--- | :--- |
+| `playlist` | `MediaContent[]` | Returns a shallow copy of the current playlist. |
+| `currentIndex` | `number` | The index of the currently playing track. |
+| `loopMode` | `'NONE' \| 'TRACK' \| 'PLAYLIST'` | Defines how the player behaves at the end of a track. |
+| `isRandom` | `boolean` | Enables or disables shuffle mode. |
+| `isPlaying` | `boolean` | Indicates if media is currently playing. |
+| `volume` | `number` | The current volume (constrained between `0.0` and `1.0`). |
+| `persistVolume` | `boolean` | Enables/disables volume saving to `localStorage`. |
+| `volumeStorageKey`| `string` | The key used for volume persistence. |
+
+---
+
+### 🕹️ Methods
+
+#### 🔌 Adapter Management
+*   **`registerAdapter(id, adapter)`**: Registers a new provider.
+    *   `id`: A unique string (e.g., `'youtube'`).
+    *   `adapter`: An instance of a class extending `BaseMediaAdapter`.
+
+#### 📋 Playlist Management
+*   **`addTrack(content)`**: Adds a new `MediaContent` object to the end of the playlist.
+*   **`existsTrack(index)`**: Returns `true` if a track exists at the given index.
+*   **`getTrack(index)`**: Retrieves the track at the specified index.
+*   **`removeTrack(index)`**: Removes a track. If the current track is removed, playback stops or adjusts.
+*   **`searchTrack(query)`**: Searches the playlist.
+    *   `query`: A `string` (searches title, artist, or album) or a `function` (custom logic).
+    *   **Returns**: `SearchResult[]` (array of objects containing the track and its index).
+*   **`clearPlaylist()`**: Stops playback and empties the playlist.
+
+#### ⏯️ Playback Controls
+*   **`play()`**: Starts playback of the current track.
+*   **`pause()`**: Pauses the current track.
+*   **`stop()`**: Stops the current track completely.
+*   **`next()`**: Advances to the next track (respects `loopMode` and `isRandom`).
+*   **`prev()`**: Returns to the previous track (respects `loopMode` and `isRandom`).
+*   **`seek(timeMs)`**: Jumps to a specific millisecond in the current track.
+*   **`step(stepMs)`**: Moves the timeline forward (positive) or backward (negative) by a specific amount.
+
+---
+
+## ⚠️ Error Handling
+
+The class uses strict validation. The following errors may be thrown:
+*   **`TypeError`**: Thrown when an argument is of the wrong type (e.g., passing a string to `volume`).
+*   **`RangeError`**: Thrown when a number is out of allowed bounds (e.g., an index that doesn't exist or volume > 1.0).
+*   **`Error`**: Thrown if no compatible adapter is found for the current content.

package/docs/v1/libs/TinyRadioFm.md

@@ -0,0 +1,141 @@
+# 📻 TinyRadioFm Documentation
+
+`TinyRadioFm` is a powerful, deterministic, and seed-based radio management system. It is designed to handle complex playback sequences, including music and voice playlists, scheduled timeline mutations, and custom content injections, all while maintaining absolute reproducibility through a mathematical seed. 🎯
+
+> **Beta Status:** This engine is currently in beta.
+
+---
+
+## ✨ Key Features
+
+* **🎯 Deterministic Playback:** Uses a `Mulberry32` PRNG to ensure that the same seed always produces the exact same radio sequence.
+* **🎵 Dual-Stream Logic:** Manages separate playlists for `music` and `voice`, with configurable interaction rules (e.g., playing voices after music).
+* **📅 Scheduled Mutations:** Schedule tasks to `add`, `remove`, or `move` items in the playlist at specific future timestamps.
+* **⚡ Custom Injections:** Inject "Custom Positions" into the timeline that interrupt the standard cycle.
+* **🧠 Smart Queuing:** Intelligent logic to prevent audio overlaps by automatically adjusting timestamps to the end of currently playing content.
+* **💾 State Persistence:** Full export/import capabilities, including automatic conversion of Blob URLs to Base64 for easy storage.
+* **🧹 Memory Management:** Proactive cleanup of Blob URLs and event listeners to prevent memory leaks.
+
+---
+
+## ⚙️ Configuration
+
+The behavior of the engine is controlled via the `RadioConfig` object.
+
+| Property | Type | Default | Description |
+| :--- | :--- | :--- | :--- |
+| `mode` | `'playlist' \| 'random'` | `'playlist'` | Sequence logic for the music playlist. |
+| `voiceMode` | `'playlist' \| 'random'` | `'playlist'` | Sequence logic for the voice playlist. |
+| `silenceDuration` | `number` | `0` | Gap in milliseconds between tracks. |
+| `queryLimit` | `number` | `100000` | Safety lock for maximum items processed during queries. |
+| `voiceAfterMusic` | `boolean` | `true` | If `true`, voice messages play after music tracks. |
+| `voiceMin` | `number` | `0` | Minimum number of voice messages to play in a cycle. |
+| `voiceMax` | `number` | `1` | Maximum number of voice messages to play in a cycle. |
+| `musicMaxConsecutive`| `number` | `0` | Max consecutive music repeats (`-1` = unlimited, `0` = no repeats). |
+| `voiceMaxConsecutive`| `number` | `0` | Max consecutive voice repeats (`-1` = unlimited, `0` = no repeats). |
+
+---
+
+## 🛠️ Core API Reference
+
+### 🏗️ Static Methods
+
+#### `static parseContent(source, defaultMetadata, metadata, parseFile, callbacks)`
+Prepares a `MediaContent` object by extracting metadata from an audio source.
+* **Parameters:**
+    * `source`: A URL string or an existing `HTMLMediaElement`.
+    * `defaultMetadata`: Optional base metadata.
+    * `metadata`: Optional manual overrides.
+    * `parseFile`: Internal helper for file parsing.
+    * `callbacks`: Object containing `onProgress` and `onError` handlers.
+* **Returns:** `Promise<MediaContent>`
+* **Throws:** `MediaLoadingError`
+
+---
+
+### 📥 Content Management
+
+#### `add(type, data, smartQueue = true)`
+Adds new content to the engine immediately.
+* **Parameters:**
+    * `type`: `'music' | 'voice' | 'custom'`.
+    * `data`: The `MediaContent` object (must include `id` and `duration`).
+    * `smartQueue`: If `true`, delays insertion until the current content ends (primarily for `custom`).
+* **Emits:** `contentAdded`
+
+#### `remove(id)`
+Instantly removes content by its unique ID across all lists, custom positions, and pending tasks. It also revokes associated Blob URLs.
+* **Parameters:** `id` (string)
+* **Emits:** `contentRemoved`
+
+---
+
+### 📅 Task & Config Management
+
+#### `scheduleTask(timestamp, action, type, payload, smartQueue = true)`
+Schedules a modification to the playlists at a specific point in time.
+* **Parameters:**
+    * `timestamp`: Target epoch timestamp (ms).
+    * `action`: `'add' | 'remove' | 'move'`.
+    * `type`: `'music' | 'voice'`.
+    * `payload`: Data required for the action (`MediaContent` for add, `string` for remove, or `ScheduledMovePayload` for move).
+    * `smartQueue`: If `true`, aligns the task to the end of the current event.
+* **Emits:** `taskScheduled`
+
+#### `setConfig(config)`
+Performs a partial or full update of the engine configuration.
+* **Parameters:** `config` (Partial or full `RadioConfig` object).
+* **Emits:** `configChanged`
+
+---
+
+### 🔍 Timeline & Querying
+
+#### `getCurrentEvent()`
+Retrieves the exact event currently playing at the system's current time.
+* **Returns:** `RadioEvent | null`
+
+#### `queryTimeline(targetDate, limit = 10)`
+Predicts upcoming events from a specific date forward using a virtual sandbox to prevent state mutation.
+* **Parameters:**
+    * `targetDate`: Starting epoch timestamp.
+    * `limit`: Maximum number of events to return.
+* **Returns:** `RadioEvent[]`
+* **Throws:** `TypeError` or `RangeError` if limit is invalid.
+
+---
+
+### 💾 Persistence & Lifecycle
+
+#### `async exportState()`
+Exports the entire radio state (playlists, tasks, seed, config) as a JSON string. Automatically converts all image Blob URLs to **Base64** for portability.
+* **Returns:** `Promise<string>`
+
+#### `importState(json)`
+Hydrates the engine with a previously exported state.
+* **Parameters:** `json` (A JSON string or a state object).
+* **Emits:** `stateImported`
+
+#### `destroy(destroyThumbs = true)`
+Performs a complete cleanup. It wipes all lists, clears the cache, removes all listeners, and revokes all Blob URLs to free up system memory.
+* **Parameters:** `destroyThumbs` (boolean) - Whether to revoke image Blob URLs.
+* **Emits:** `destroyed`
+
+---
+
+## 📊 Data Models (Summary)
+
+### `RadioEvent` 📡
+The standardized object returned when querying the timeline.
+* `id`, `title`, `artist`, `url`, `duration`
+* `absoluteStart`, `absoluteEnd`
+* `elapsedTime`, `remainingTime`
+* `progress` (0 to 1)
+* `isCustom` (boolean)
+
+### `ScheduledTask` 📝
+An instruction to change the radio state.
+* `timestamp`: Execution time.
+* `action`: `'add' | 'remove' | 'move'`.
+* `type`: `'music' | 'voice'`.
+* `payload`: Action-specific data.

package/docs/v1/libs/TinySmartScroller.md

@@ -358,15 +358,15 @@ scroller._listenLoadEvents(imgElement);
 
 ## 🧱 DOM and Element Accessors
 
-### 🎯 `target`
+### 🎯 `targetElement`
 
 Returns the internal scroll container element being monitored.
 
 ```js
-const container = scroller.target;
+const container = scroller.targetElement;
 ```
 
-* 🔙 Returns the target DOM element (or `window` if in window mode).
+* 🔙 Returns the target DOM element.
 
 ### 🕵️‍♀️ `getOldSize(el)`