tiny-essentials 1.26.3 → 1.27.0

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)`
 

package/package.json

@@ -1,13 +1,13 @@
 {
   "name": "tiny-essentials",
-  "version": "1.26.3",
+  "version": "1.27.0",
   "description": "Collection of small, essential scripts designed to be used across various projects. These simple utilities are crafted for speed, ease of use, and versatility.",
   "bin": {
     "tiny-essentials-fork": "./TinyFork.mjs"
   },
   "scripts": {
     "test": "npm run test:mjs && npm run test:cjs && npm run test:js",
-    "test:js": "npx babel-node test/index.js",
+    "test:js": "node -r @babel/register test/index.js",
     "test:cjs": "node test/index.cjs",
     "test:mjs": "node test/index.mjs",
     "test:mjs:web": "node test/express.mjs",
@@ -60,6 +60,10 @@
       "require": "./dist/v1/basics/index.cjs",
       "import": "./dist/v1/basics/index.mjs"
     },
+    "./basics/mediaContent": {
+      "require": "./dist/v1/basics/mediaContent.cjs",
+      "import": "./dist/v1/basics/mediaContent.mjs"
+    },
     "./basics/array": {
       "require": "./dist/v1/basics/array.cjs",
       "import": "./dist/v1/basics/array.mjs"
@@ -112,6 +116,14 @@
       "require": "./dist/v1/libs/ColorSafeStringify.cjs",
       "import": "./dist/v1/libs/ColorSafeStringify.mjs"
     },
+    "./libs/TinyMediaPlayer": {
+      "require": "./dist/v1/libs/TinyMediaPlayer.cjs",
+      "import": "./dist/v1/libs/TinyMediaPlayer.mjs"
+    },
+    "./libs/TinyRadioFm": {
+      "require": "./dist/v1/libs/TinyRadioFm.cjs",
+      "import": "./dist/v1/libs/TinyRadioFm.mjs"
+    },
     "./libs/UltraRandomMsgGen": {
       "require": "./dist/v1/libs/UltraRandomMsgGen.cjs",
       "import": "./dist/v1/libs/UltraRandomMsgGen.mjs"
@@ -268,6 +280,10 @@
       "require": "./dist/v1/libs/TinyAdvancedRaffle.cjs",
       "import": "./dist/v1/libs/TinyAdvancedRaffle.mjs"
     },
+    "./libs/TinyClassManager/TinyPluginInliner": {
+      "require": "./dist/v1/libs/TinyClassManager/TinyPluginInliner.cjs",
+      "import": "./dist/v1/libs/TinyClassManager/TinyPluginInliner.mjs"
+    },
     "./libs/TinyClassManager": {
       "require": "./dist/v1/libs/TinyClassManager.cjs",
       "import": "./dist/v1/libs/TinyClassManager.mjs"
@@ -501,36 +517,38 @@
   },
   "homepage": "https://github.com/Tiny-Essentials/Tiny-Essentials#readme",
   "devDependencies": {
-    "@babel/cli": "^7.28.6",
-    "@babel/core": "^7.29.0",
-    "@babel/generator": "^7.29.1",
-    "@babel/node": "^7.29.0",
-    "@babel/parser": "^7.29.2",
-    "@babel/preset-env": "^7.29.2",
-    "@babel/traverse": "^7.29.0",
-    "@babel/types": "^7.29.0",
-    "@rollup/plugin-commonjs": "^28.0.3",
+    "@babel/cli": "^8.0.1",
+    "@babel/core": "^8.0.1",
+    "@babel/generator": "^8.0.0",
+    "@babel/node": "^8.0.1",
+    "@babel/parser": "^8.0.0",
+    "@babel/preset-env": "^8.0.2",
+    "@babel/register": "^8.0.1",
+    "@babel/traverse": "^8.0.0",
+    "@babel/types": "^8.0.0",
+    "@rollup/plugin-commonjs": "^29.0.3",
     "@rollup/plugin-json": "^6.1.0",
-    "@rollup/plugin-node-resolve": "^16.0.1",
-    "@rollup/plugin-typescript": "^12.1.2",
+    "@rollup/plugin-node-resolve": "^16.0.3",
+    "@rollup/plugin-typescript": "^12.3.0",
     "@types/lodash": "^4.17.16",
-    "@types/md5": "^2.3.5",
+    "@types/md5": "^2.3.6",
+    "@types/node": "^26.1.0",
     "@types/node-fetch": "^2.6.12",
     "babel-preset-es2015": "^6.24.1",
-    "esbuild": "^0.25.5",
+    "esbuild": "^0.28.1",
     "express": "^5.1.0",
     "lodash": "^4.17.21",
-    "marked": "^16.0.0",
+    "marked": "^18.0.5",
     "node-polyfill-webpack-plugin": "^4.1.0",
-    "prettier": "3.6.2",
-    "rollup": "^4.40.0",
+    "prettier": "^3.9.4",
+    "rollup": "^4.62.2",
     "rollup-preserve-directives": "^1.1.3",
     "safe-stable-stringify": "^2.5.0",
-    "sass": "^1.89.2",
+    "sass": "^1.101.0",
     "tslib": "^2.8.1",
-    "type-fest": "^5.0.1",
-    "typescript": "^5.8.3",
+    "type-fest": "^5.7.0",
+    "typescript": "^6.0.3",
     "webpack": "^5.99.6",
-    "webpack-cli": "^6.0.1"
+    "webpack-cli": "^7.1.0"
   }
 }