tiny-essentials 1.29.1 → 1.29.2

package/docs/v1/Exports.md

@@ -21,6 +21,8 @@ These are pre-built stylesheets that can be directly imported:
 import "tiny-essentials/css/TinyNotify.min.css";
 ```
 
+> 💡 The whole `css/` folder is exposed through the `./css/*.css` wildcard, so any new stylesheet shipped in `dist/v1/css` is importable without a `package.json` change.
+
 ---
 
 ## 🏠 Root Entrypoints
@@ -62,6 +64,7 @@ Direct access to smaller utilities:
 * `basics/promiseUtils`
 * `basics/browserDetector`
 * `basics/jsonFilter`
+* `basics/media/youtube`
 
 Direct access to file utilities:
 
@@ -228,6 +231,22 @@ Each library can be imported separately:
   * `libs/media/TinyMediaPlayer/docs/SoundCloudWidget`
   * `libs/media/TinyRadioFm`
 
+* **Media Loaders 🎞️**
+
+  * `libs/html/loader/TinyMediaLoader`
+  * `libs/html/loader/formats/TinyImageLoader`
+  * `libs/html/loader/formats/TinyFetchLoader`
+  * `libs/html/loader/utils/TinyMediaCache`
+  * `libs/html/loader/utils/TinyMediaProgress`
+  * `libs/html/loader/utils/TinyMediaMirror`
+  * `libs/html/loader/utils/TinyBufferReader`
+  * `libs/html/loader/utils/TinyIsoBox`
+  * `libs/html/loader/probe/TinyImageProbe`
+  * `libs/html/loader/beta/formats/TinyContentLoader` (BETA)
+  * `libs/html/loader/beta/formats/TinyAudioLoader` (BETA)
+  * `libs/html/loader/beta/formats/TinyVideoLoader` (BETA)
+  * `libs/html/loader/beta/probe/TinyMediaProbe` (BETA)
+
 * **HTML Helpers 🧩**
 
   * `libs/html/TinyHtml`
@@ -310,8 +329,20 @@ Each library can be imported separately:
 ### Bootstrap 5.3 🅱️
 
 * `webTemplates/bootstrap/5.3/html/BootstrapDialogs`
-* `webTemplates/bootstrap/5.3/scss/input/Placeholder-Colors-Fix.scss`
-* `webTemplates/bootstrap/5.3/scss/spacing/Spacing-Plus.scss`
+* `webTemplates/bootstrap/5.3/scss/*` (wildcard)
+
+> 💡 The whole `scss/` folder is exposed through the `./webTemplates/bootstrap/5.3/scss/*` wildcard, so every partial is importable without a `package.json` change.
+
+**Theme (DeepStrap)**
+
+* `webTemplates/bootstrap/5.3/scss/themes/deepstrap/theme`
+* `webTemplates/bootstrap/5.3/scss/background/background-grid`
+* `webTemplates/bootstrap/5.3/scss/components/buttons/buttons-ghost`
+* `webTemplates/bootstrap/5.3/scss/components/buttons/buttons-contrast`
+* `webTemplates/bootstrap/5.3/scss/components/icon/cube-icon`
+* `webTemplates/bootstrap/5.3/scss/components/icon/sphere-pulse`
+* `webTemplates/bootstrap/5.3/scss/input/placeholder-colors-fix`
+* `webTemplates/bootstrap/5.3/scss/spacing/spacing-plus`
 
 ### Vite 7.3 ⚡
 

package/docs/v1/README.md

@@ -22,6 +22,7 @@ Here, you can navigate through different sections of the project. Below are the
 - 📺 **[FullScreen](./basics/fullScreen.md)** — A complete fullscreen API manager with detection, event handling, and cross-browser compatibility.
 - 🧱 **[Collision](./basics/collision.md)** — Full-featured rectangle collision detection system with directional analysis, depth calculation, and center offset metrics.
 - 🎵 **[MediaContent](./basics/mediaContent.md)** — A comprehensive media processing module for downloading audio, extracting rich ID3 metadata, and managing image blobs for album art.
+- 🎬 **[YouTube](./basics/youtube.md)** — Extract video ids from any YouTube URL, build thumbnail URLs for every quality, and fetch/validate the official oEmbed metadata.
 - 📦 **[BrowserDetector](./basics/browserDetector.md)** — A multi-layered JavaScript utility for identifying the user's web browser and rendering engine.
 - 🔐 **[Crypto](./basics/crypto.md)** — A lightweight utility for generating cryptographic hashes (e.g., SHA-256) using the Web Crypto API.
 - 🔁 **[PromiseUtils](./basics/promiseUtils.md)** — Promise helpers such as `waitForTrue` and `createSingletonTask` for polling and single-flight async tasks.
@@ -119,6 +120,13 @@ Here, you can navigate through different sections of the project. Below are the
 - 📻 **[TinyRadioFm](./libs/media/TinyRadioFm.md)** — 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.
 - ⏯️ **[TinyMediaPlayer](./libs/media/TinyMediaPlayer.md)** — A universal media player architecture utilizing an adapter pattern to orchestrate multiple platform APIs, featuring robust playlist management, playback controls, and weighted random selection.
 
+#### 2.9.1. **`libs/html/loader`**
+
+- 📦 **[TinyMediaLoader](./libs/html/loader/TinyMediaLoader.md)** — The abstract base class behind every media loader, with a full state machine, streaming progress, shared cache, download mirroring and a typed event surface.
+- 🖼️ **[TinyImageLoader](./libs/html/loader/TinyImageLoader.md)** — Image loader with intrinsic size helpers, streaming and a complete animation engine for `GIF`, `APNG`, `WebP` and `AVIF`.
+- 📥 **[TinyFetchLoader](./libs/html/loader/TinyFetchLoader.md)** — Generic file loader that reuses the media pipeline to download `blob`, `arraybuffer`, `text` or `json` payloads.
+- 🗄️ **[TinyMediaCache](./libs/html/loader/TinyMediaCache.md)** — Shared, reference-counted blob cache with TTL, byte budgets and parent/child links.
+
 ### 2.10. **`libs/tools`**
 
 - 🛠️ **[TinyDebugger](./libs/tools/TinyDebugger.md)** — A lightweight, event-driven debugging utility designed to wrap standard `console` methods. It provides enhanced features such as custom prefixes, color support, and the ability to emit events whenever a log occurs, making it perfect for complex applications where you might want to redirect logs to an external service or a UI component.
@@ -208,6 +216,7 @@ Here, you can navigate through different sections of the project. Below are the
 #### 4.1. **`webTemplates/bootstrap/`**
 
 - 🖼️ **[BootstrapDialogs](./webTemplates/bootstrap/5.3/html/BootstrapDialogs.md)** — An asynchronous JavaScript utility designed to replace native browser dialogs with customizable Bootstrap 5 Modals.
+- 🎨 **[DeepStrap](./webTemplates/bootstrap/5.3/DeepStrap.md)** — A token-driven Bootstrap 5.3 theme with light/dark palettes, CSS custom properties and optional plugins (ghost buttons, contrast buttons, cube icon, sphere pulse and background grid).
 
 #### 4.2. **`webTemplates/vite/`**
 

package/docs/v1/basics/youtube.md

@@ -0,0 +1,204 @@
+# 🎬 YouTube Utils Documentation
+
+A tiny, dependency-free toolkit for everything you need to do with a YouTube link: **extract the video id**, **build thumbnail URLs** and **fetch the official oEmbed metadata** — with strict validation at every step. 🚀
+
+```javascript
+import {
+  extractYouTubeVideoId,
+  getYouTubeThumbnailUrl,
+  fetchYouTubeOEmbed,
+  assertYouTubeOEmbedResponse,
+} from 'tiny-essentials/basics/media/youtube';
+```
+
+---
+
+## 📋 Table of Contents
+
+1. [Data Types](#-data-types)
+2. [extractYouTubeVideoId](#-extractyoutubevideoid)
+3. [getYouTubeThumbnailUrl](#-getyoutubethumbnailurl)
+4. [fetchYouTubeOEmbed](#-fetchyoutuboeembed)
+5. [assertYouTubeOEmbedResponse](#-assertyoutuboeembedresponse)
+6. [Error Reference](#-error-reference)
+
+---
+
+## 📋 Data Types
+
+### `YouTubeThumbnailQuality`
+
+```typescript
+type YouTubeThumbnailQuality =
+  | 'default' // 120x90
+  | 'mqdefault' // 320x180
+  | 'hqdefault' // 480x360 (default)
+  | 'sddefault' // 640x480
+  | 'maxresdefault'; // 1280x720
+```
+
+### `YouTubeOEmbedResponse`
+
+The validated payload returned by [`fetchYouTubeOEmbed`](#-fetchyoutuboeembed).
+
+| Property           | Type      | Description                             |
+| :----------------- | :-------- | :-------------------------------------- |
+| `title`            | `string`  | Video title.                            |
+| `author_name`      | `string`  | Channel display name.                   |
+| `author_url`       | `string`  | Channel URL.                            |
+| `type`             | `'video'` | Resource type returned by the provider. |
+| `version`          | `string`  | oEmbed version.                         |
+| `provider_name`    | `string`  | Always `"YouTube"`.                     |
+| `provider_url`     | `string`  | Provider root URL.                      |
+| `html`             | `string`  | Ready to use iframe markup.             |
+| `width`            | `number`  | Suggested iframe width in pixels.       |
+| `height`           | `number`  | Suggested iframe height in pixels.      |
+| `thumbnail_url`    | `string`  | Thumbnail URL provided by the provider. |
+| `thumbnail_width`  | `number`  | Thumbnail width in pixels.              |
+| `thumbnail_height` | `number`  | Thumbnail height in pixels.             |
+
+---
+
+## 🆔 `extractYouTubeVideoId`
+
+Extracts the canonical 11 character video id from a raw id or a full YouTube URL.
+
+```javascript
+import { extractYouTubeVideoId } from 'tiny-essentials/basics/media/youtube';
+
+extractYouTubeVideoId('dQw4w9WgXcQ');
+// → 'dQw4w9WgXcQ'
+
+extractYouTubeVideoId('https://www.youtube.com/watch?v=dQw4w9WgXcQ&list=PL123');
+// → 'dQw4w9WgXcQ'
+
+extractYouTubeVideoId('https://youtu.be/dQw4w9WgXcQ?t=42');
+// → 'dQw4w9WgXcQ'
+```
+
+### Supported inputs
+
+| Input      | Example                                       |
+| :--------- | :-------------------------------------------- |
+| Raw id     | `dQw4w9WgXcQ`                                 |
+| `watch`    | `https://www.youtube.com/watch?v=dQw4w9WgXcQ` |
+| Short link | `https://youtu.be/dQw4w9WgXcQ`                |
+| `embed`    | `https://www.youtube.com/embed/dQw4w9WgXcQ`   |
+| `shorts`   | `https://www.youtube.com/shorts/dQw4w9WgXcQ`  |
+| `live`     | `https://www.youtube.com/live/dQw4w9WgXcQ`    |
+| `v`        | `https://www.youtube.com/v/dQw4w9WgXcQ`       |
+
+**Allowed hosts:** `youtube.com`, `m.youtube.com`, `music.youtube.com`, `youtube-nocookie.com` and `youtu.be` (the `www.` prefix is optional). Only `http:` and `https:` are accepted.
+
+**Throws:**
+
+- `TypeError` — when the input is not a string.
+- `RangeError` — when the input is empty, the protocol is unsupported or the host is not a YouTube host.
+- `SyntaxError` — when the input is not a video id, is not a valid URL, or does not contain a video id.
+
+---
+
+## 🖼️ `getYouTubeThumbnailUrl`
+
+Builds the thumbnail URL of a video **without any network request**.
+
+```javascript
+import { getYouTubeThumbnailUrl } from 'tiny-essentials/basics/media/youtube';
+
+getYouTubeThumbnailUrl('dQw4w9WgXcQ');
+// → 'https://i.ytimg.com/vi/dQw4w9WgXcQ/hqdefault.jpg'
+
+getYouTubeThumbnailUrl('https://youtu.be/dQw4w9WgXcQ', 'maxresdefault');
+// → 'https://i.ytimg.com/vi/dQw4w9WgXcQ/maxresdefault.jpg'
+```
+
+| Parameter      | Type                      | Default       | Description                                                                       |
+| :------------- | :------------------------ | :------------ | :-------------------------------------------------------------------------------- |
+| `videoIdOrUrl` | `string`                  | —             | Raw id or any URL accepted by [`extractYouTubeVideoId`](#-extractyoutubevideoid). |
+| `quality`      | `YouTubeThumbnailQuality` | `'hqdefault'` | Thumbnail resolution.                                                             |
+
+**Returns:** `string` — the thumbnail URL.
+
+**Throws:** `TypeError` when `quality` is not a string, `RangeError` when it is not a supported quality, plus anything thrown by `extractYouTubeVideoId`.
+
+---
+
+## 📡 `fetchYouTubeOEmbed`
+
+Fetches the [official oEmbed](https://oembed.com/) metadata of a video and returns a fully validated [`YouTubeOEmbedResponse`](#-data-types).
+
+```javascript
+import { fetchYouTubeOEmbed } from 'tiny-essentials/basics/media/youtube';
+
+const video = await fetchYouTubeOEmbed('https://youtu.be/dQw4w9WgXcQ');
+
+console.log(video.title); // 'Never Gonna Give You Up'
+console.log(video.author_name); // 'Rick Astley'
+```
+
+### Options
+
+| Option      | Type           | Default            | Description                                         |
+| :---------- | :------------- | :----------------- | :-------------------------------------------------- |
+| `signal`    | `AbortSignal`  | `undefined`        | Forwarded to `fetch` so the request can be aborted. |
+| `fetchImpl` | `typeof fetch` | `globalThis.fetch` | Injectable fetch implementation (handy for tests).  |
+
+```javascript
+const controller = new AbortController();
+
+const video = await fetchYouTubeOEmbed('dQw4w9WgXcQ', {
+  signal: controller.signal,
+  fetchImpl: myFetch,
+});
+```
+
+**Returns:** `Promise<YouTubeOEmbedResponse>`
+
+**Throws:**
+
+- `TypeError` — invalid `options`, `options.signal` or `options.fetchImpl`, or a response that is not a `Response`.
+- `Error` — the request failed or returned a non 2xx status.
+- `RangeError` — the payload contains an out of range numeric value.
+
+---
+
+## ✅ `assertYouTubeOEmbedResponse`
+
+Deeply validates an oEmbed payload and returns a **brand new** object containing only the known properties.
+
+```javascript
+import { assertYouTubeOEmbedResponse } from 'tiny-essentials/basics/media/youtube';
+
+const payload = await fetch('/oembed.json').then((res) => res.json());
+const video = assertYouTubeOEmbedResponse(payload);
+
+console.log(video.title);
+```
+
+| Parameter | Type      | Default                         | Description                              |
+| :-------- | :-------- | :------------------------------ | :--------------------------------------- |
+| `payload` | `unknown` | —                               | Raw value returned by `response.json()`. |
+| `context` | `string`  | `'assertYouTubeOEmbedResponse'` | Caller name used in the error messages.  |
+
+**Throws:**
+
+- `TypeError` — the payload (or one of its properties) has the wrong type.
+- `RangeError` — a numeric property is not a positive integer, or `type` is not `'video'`.
+
+---
+
+## ❌ Error Reference
+
+| Error         | When                                                                                                                               |
+| :------------ | :--------------------------------------------------------------------------------------------------------------------------------- |
+| `TypeError`   | A value has the wrong type (non-string id, non-function `fetchImpl`, non-`AbortSignal` signal, non-object payload…).               |
+| `RangeError`  | A value is syntactically valid but out of range (empty string, unsupported host/protocol, unknown quality, non-positive integer…). |
+| `SyntaxError` | The input is neither a video id nor a URL containing one.                                                                          |
+| `Error`       | The HTTP request failed or returned a non 2xx status.                                                                              |
+
+---
+
+## 🧪 Testing
+
+- **Browser playground:** `test/html/basics/youtube` (run `npm run test:mjs:web` and open `/basics/youtube/`).
+- **Node.js suite:** `npm run test:mjs:youtube`.

package/docs/v1/libs/html/loader/TinyFetchLoader.md

@@ -0,0 +1,114 @@
+# 📥 TinyFetchLoader
+
+`TinyFetchLoader` is a generic file loader built on top of [`TinyMediaLoader`](./TinyMediaLoader.md). It does not create a DOM element — it downloads any resource and exposes the payload as a `Blob`, `ArrayBuffer`, `string` or parsed `JSON`.
+
+Because it reuses the whole media pipeline, it inherits progress tracking, caching, mirroring, timeouts and the typed event surface.
+
+---
+
+## ✨ Highlights
+
+* **Any payload type** — `blob`, `arraybuffer`, `text` or `json`.
+* **`fetch` compatible** — `exportFetch()` returns a drop-in replacement for `globalThis.fetch`.
+* **Cloneable** — `clone(overrides)` creates an independent loader that reuses the shared cache.
+* **No DOM required** — works in workers and in Node.js (with a `fetch` implementation).
+
+---
+
+## 🚀 Quick start
+
+```js
+import TinyFetchLoader from 'tiny-essentials/libs/html/loader/formats/TinyFetchLoader';
+
+const loader = new TinyFetchLoader({
+  src: 'https://api.example.com/data.json',
+  responseType: 'json',
+  init: { headers: { Accept: 'application/json' } },
+  timeout: 15_000,
+});
+
+loader.on('progress', (p) => console.log(`${p.percent.toFixed(0)}%`));
+
+await loader.load();
+console.log(loader.data);
+```
+
+---
+
+## ⚙️ Options
+
+Inherits every [`TinyMediaLoader`](./TinyMediaLoader.md) option, plus:
+
+| Option | Type | Default | Description |
+| :--- | :--- | :--- | :--- |
+| `src` | `string` | `''` | The file URL. |
+| `init` | `RequestInit` | `{}` | Options forwarded to `fetch` (method, headers, body, credentials, mode, cache, redirect, referrer, referrerPolicy, integrity, keepalive). |
+| `fetch` | `typeof fetch` | `globalThis.fetch` | A custom fetch implementation. |
+| `responseType` | `'blob' \| 'arraybuffer' \| 'text' \| 'json'` | `'blob'` | How the payload is parsed. |
+| `body` | `BodyInit \| undefined` | `undefined` | The request body forwarded to the transport. Ignored by `GET`/`HEAD`; `init.body` wins when both are set. |
+
+> **Note:** `body` is inherited from [`TinyMediaLoader`](./TinyMediaLoader.md#-request-body) and is only sent when the request method is not `GET`/`HEAD`.
+
+---
+
+## 🧩 Properties
+
+| Getter | Type | Description |
+| :--- | :--- | :--- |
+| `blob` | `Blob \| null` | The raw payload, or `null` before the load finishes. |
+| `data` | `Blob \| ArrayBuffer \| string \| unknown \| null` | The parsed payload. |
+| `responseType` | `string` | The requested response type. |
+| `init` | `RequestInit` | A defensive copy of the fetch options. |
+
+---
+
+## 🛠️ Methods
+
+### `clone(overrides = {})`
+
+Creates a new, fully independent loader. The shared `cache` and the custom `fetch` implementation are reused by reference, which makes cloning cheap.
+
+```js
+const json = loader.clone({ responseType: 'json' });
+const text = loader.clone({ responseType: 'text' });
+```
+
+### `exportFetch()`
+
+Returns a function with the same signature as `fetch` that is backed by this loader.
+
+```js
+const tinyFetch = loader.exportFetch();
+const response = await tinyFetch('https://api.example.com/ping');
+```
+
+---
+
+## 📦 Response types
+
+| `responseType` | `loader.data` |
+| :--- | :--- |
+| `'blob'` *(default)* | `Blob` |
+| `'arraybuffer'` | `ArrayBuffer` |
+| `'text'` | `string` |
+| `'json'` | `unknown` |
+
+---
+
+## 🧪 Example: downloading a JSON file with progress
+
+```js
+import TinyFetchLoader from 'tiny-essentials/libs/html/loader/formats/TinyFetchLoader';
+
+const loader = new TinyFetchLoader({
+  src: './data/large-dataset.json',
+  responseType: 'json',
+});
+
+loader.on('progress', ({ percent, rate, eta }) => {
+  console.log(`${percent.toFixed(1)}% — ${(rate / 1024).toFixed(0)} KB/s — ETA ${(eta / 1000).toFixed(1)}s`);
+});
+
+await loader.load();
+console.log(loader.data);
+```

package/docs/v1/libs/html/loader/TinyImageLoader.md

@@ -0,0 +1,141 @@
+# 🖼️ TinyImageLoader
+
+`TinyImageLoader` is the image implementation of [`TinyMediaLoader`](./TinyMediaLoader.md). On top of the shared lifecycle it adds intrinsic size helpers, streaming, and a complete animation engine capable of decoding and replaying `GIF`, `APNG`, `WebP` and `AVIF` frames by hand.
+
+---
+
+## ✨ Highlights
+
+* **Everything from `TinyMediaLoader`** — cache, progress, mirror, timeout, events.
+* **Intrinsic metrics** — `naturalWidth`, `naturalHeight` and `aspectRatio` without touching the DOM.
+* **Four animation modes** — from fully native to a manual frame clock.
+* **Frame extraction** — every frame becomes an independent blob stored in a dedicated `TinyMediaCache`.
+* **Playback API** — `play`, `pause`, `freeze`, `unfreeze` and `playbackRate`.
+
+---
+
+## 🚀 Quick start
+
+```js
+import TinyImageLoader from 'tiny-essentials/libs/html/loader/formats/TinyImageLoader';
+
+const loader = new TinyImageLoader({
+  src: './assets/nyan-cat.gif',
+  animationControl: 'native',
+  decoding: 'async',
+  crossOrigin: 'anonymous',
+});
+
+loader.on('loaded', () => {
+  console.log(loader.naturalWidth, loader.naturalHeight, loader.aspectRatio);
+  loader.mount(document.querySelector('#stage'));
+  loader.play();
+});
+
+await loader.load();
+```
+
+---
+
+## ⚙️ Options
+
+Inherits every [`TinyMediaLoader`](./TinyMediaLoader.md) option, plus:
+
+| Option | Type | Default | Description |
+| :--- | :--- | :--- | :--- |
+| `crossOrigin` | `'anonymous' \| 'use-credentials' \| null` | `null` | The `crossorigin` attribute applied to the image. |
+| `decoding` | `'sync' \| 'async' \| 'auto'` | `'async'` | The `decoding` hint passed to the browser. |
+| `stream` | `boolean` | `false` | Downloads the image through `fetch` to expose byte level progress. |
+| `animationControl` | `'none' \| 'native' \| 'script-only' \| 'controlled'` | `'none'` | How animated images are handled. |
+
+### Animation modes
+
+| Mode | Description |
+| :--- | :--- |
+| `none` | The browser renders the image as-is. No frame extraction. |
+| `native` | Frames are extracted, but the browser still plays the animation. `freeze()` falls back to the first frame. |
+| `script-only` | Frames are extracted and available, but the loader never touches playback. |
+| `controlled` | The loader owns a frame clock. Use `play`, `pause`, `freeze`, `unfreeze` and `playbackRate`. **Stable on `WebP`, 95% on `PNG` (APNG), unstable on other formats — see the compatibility status below.** |
+
+### ⚠️ Compatibility status (`controlled` mode)
+
+Frame extraction and the manual frame clock are **not equally stable across every container**. Check the table below before relying on `controlled` in production:
+
+| Format | Status | Notes |
+| :--- | :--- | :--- |
+| `WebP` | ✅ Stable | Fully working. This is the recommended format. |
+| `PNG` (APNG) | 🟡 95% | Works in almost every case. Rare edge cases may show a wrong frame delay or drop a frame. |
+| `GIF` / `AVIF` | ⚠️ Unstable | Frame extraction may fail, desynchronize or return incomplete data depending on the encoder. |
+
+**Recommendation:** if you need `controlled` mode, convert the asset to `WebP` first. If you cannot convert it, use `animationControl: 'native'` instead — it is 100% tested and stable on every animated format listed above.
+
+---
+
+## 🧩 Properties
+
+| Getter | Type | Description |
+| :--- | :--- | :--- |
+| `image` | `HTMLImageElement \| null` | The managed `<img>` element. |
+| `stream` | `boolean` | Whether the image is downloaded through `fetch`. |
+| `naturalWidth` | `number` | The intrinsic width in pixels. |
+| `naturalHeight` | `number` | The intrinsic height in pixels. |
+| `aspectRatio` | `number` | `naturalWidth / naturalHeight`, or `0` when unknown. |
+| `playbackRate` | `number` | Playback speed modifier (controlled mode). |
+| `animationScript` | `AnimationScriptStep[]` | A deep copy of the per-frame delays. |
+
+---
+
+## 🛠️ Methods
+
+### `freeze(frameIndex = null)`
+
+Freezes the animation.
+
+* In `native` mode the first frame is displayed.
+* In `controlled` mode the clock stops at `frameIndex` (or at the current frame when omitted).
+
+```js
+loader.freeze(0); // back to the first frame
+```
+
+### `unfreeze()`
+
+Resumes the animation from the frozen state.
+
+### `play()`
+
+Starts (or resumes) the frame clock. Only available in `controlled` mode.
+
+### `pause()`
+
+Stops the frame clock without changing the current frame. Only available in `controlled` mode.
+
+### `playbackRate` (setter)
+
+Changes the playback speed. Values are clamped to a minimum of `0.1`.
+
+```js
+loader.playbackRate = 0.5; // half speed
+```
+
+### `animationScript` (setter)
+
+Replaces the per-frame delays. Only available in `controlled` mode.
+
+```js
+loader.animationScript = loader.animationScript.map(() => ({ delay: 50 }));
+```
+
+---
+
+## 📡 Events
+
+Every event from [`TinyMediaLoader`](./TinyMediaLoader.md#-events) is available. The `metadata` event is emitted with `type: 'PROBE_ANIMATION'` once the animation data has been resolved.
+
+```js
+loader.on('metadata', (metadata, type) => {
+  if (type === 'PROBE_ANIMATION') {
+    console.log(metadata.animation); // { frames, loopCount, duration }
+  }
+});
+```