tiny-essentials 1.29.0 → 1.29.2

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

@@ -0,0 +1,166 @@
+# 🗄️ TinyMediaCache
+
+`TinyMediaCache` is the shared memory cache used by every media loader. It stores blobs and their object URLs, reference-counts the consumers and releases the underlying `Blob` only when the last cache that knows about it is gone.
+
+---
+
+## ✨ Highlights
+
+* **Shared registry** — the same URL is downloaded once, no matter how many loaders ask for it.
+* **Reference counting** — an object URL is only revoked when the last consumer releases it.
+* **Three cleanup strategies** — `auto`, `manual` and `ttl`.
+* **Budgets** — limit the cache by number of entries (`maxItems`) and by total size (`maxBytes`).
+* **Parent/child links** — derived entries (e.g. animation frames) can be attached to the entry that owns them.
+* **Statistics** — hits, misses, evictions, bytes and links.
+
+---
+
+## 🚀 Quick start
+
+```js
+import TinyMediaCache from 'tiny-essentials/libs/html/loader/utils/TinyMediaCache';
+
+const cache = new TinyMediaCache({
+  maxItems: 100,
+  maxBytes: 128 * 1024 * 1024,
+  ttl: 5 * 60 * 1000,
+  strategy: TinyMediaCache.Strategy.TTL,
+});
+```
+
+---
+
+## ⚙️ Options
+
+| Option | Type | Default | Description |
+| :--- | :--- | :--- | :--- |
+| `maxItems` | `number` | `Infinity` | Maximum number of entries. |
+| `maxBytes` | `number` | `Infinity` | Maximum cache size in bytes. |
+| `ttl` | `number` | `0` | Entry lifetime in milliseconds (`0` = never expires). |
+| `strategy` | `'auto' \| 'manual' \| 'ttl'` | `'manual'` | Cleanup strategy applied when an entry reaches zero references. |
+| `ignoreSearch` | `boolean` | `false` | Ignores the query string when building keys. |
+| `sweepInterval` | `number` | `0` | Interval in milliseconds for active TTL sweeping (`0` = disabled). |
+
+---
+
+## 🧩 Properties
+
+| Getter | Type | Description |
+| :--- | :--- | :--- |
+| `size` | `number` | Number of entries in this cache. |
+| `bytes` | `number` | Total size in bytes held by this cache. |
+| `links` | `number` | Number of entries that own at least one child. |
+| `maxItems` | `number` | The configured item budget. |
+| `maxBytes` | `number` | The configured byte budget. |
+| `strategy` | `string` | The active cleanup strategy. |
+| `evictions` | `number` | Number of evicted entries. |
+| `destroyed` | `boolean` | `true` after `destroy()` ran. |
+| `stats` | `MediaCacheStats` | A snapshot of every counter. |
+
+---
+
+## 🛠️ Methods
+
+### `set(url, blob, pinned?, metadata?, parent?)`
+
+Stores a blob and returns the created entry.
+
+```js
+cache.set('https://cdn/a.png', blob, true, { width: 100 }, null);
+```
+
+* **Throws:** `TypeError` when `blob` is not a `Blob`, when `pinned` is not a boolean, when `metadata` is not a plain object, or when `parent` is neither a string nor `null`.
+
+### `get(url)` / `has(url)`
+
+Reads an entry without changing its reference count.
+
+### `peek(url)`
+
+Reads an entry without changing its reference count **and** without touching the `hits`/`misses` counters. Expired entries are reported as missing but are not removed, so a read-only probe never mutates the cache.
+
+```js
+const entry = cache.peek('https://cdn/a.png');
+if (entry) console.log(entry.size, entry.type);
+```
+
+* **Returns:** `MediaCacheEntry | null` — the live entry, or `null` when absent or expired.
+* **Throws:** `TypeError` when `url` is not a string; `Error` when the cache was destroyed.
+
+> Use `peek()` to decide *whether* to load a resource. Never use it as a replacement for `get()`/`acquire()`, which are the methods that keep the reference count correct.
+
+### `acquire(url)` / `release(url)`
+
+Increments / decrements the reference count. When the count reaches zero the configured strategy is applied.
+
+### `delete(url)`
+
+Removes an entry. When the removed entry was the last child of a parent, the parent is removed as well.
+
+### `children(url)`
+
+Returns the normalized keys of the entries owned by `url`.
+
+```js
+cache.set(frameUrl, frameBlob, false, {}, 'https://cdn/anim.gif');
+console.log(cache.children('https://cdn/anim.gif')); // [frameUrl]
+```
+
+### `entries()`
+
+Returns a defensive copy of every entry, including a shallow copy of each `metadata` object.
+
+### `pin(url, value?)`
+
+Protects (or unprotects) an entry from eviction.
+
+### `prune()` / `clear()` / `destroy()`
+
+Removes expired entries, empties the cache, or tears the instance down and releases the shared registry.
+
+---
+
+## 🧠 Strategies
+
+| Strategy | Behavior |
+| :--- | :--- |
+| `auto` | The entry is deleted as soon as its reference count reaches zero. |
+| `manual` | The entry stays until `delete`, `clear` or eviction. |
+| `ttl` | The entry expires after `ttl` milliseconds. |
+
+---
+
+## 📊 Statistics
+
+```js
+const { size, bytes, hits, misses, evictions, links, instances, blobs } = cache.stats;
+```
+
+| Field | Description |
+| :--- | :--- |
+| `size` | Entries in this cache. |
+| `bytes` | Total size in bytes held by this cache. |
+| `refs` | Total number of active references. |
+| `hits` / `misses` | Lookup counters. |
+| `evictions` | Entries evicted by the limits. |
+| `links` | Entries that own at least one child. |
+| `instances` | Live cache instances. |
+| `blobs` | Blobs in the shared registry. |
+
+---
+
+## 🔗 Parent / child links
+
+Derived blobs (animation frames, thumbnails, transcoded variants) can be attached to the entry that produced them:
+
+```js
+cache.set(originalUrl, originalBlob);
+
+frames.forEach((frame, index) => {
+  cache.set(`${originalUrl}#frame-${index}`, frame, false, { index }, originalUrl);
+});
+
+console.log(cache.links); // 1
+console.log(cache.children(originalUrl).length); // frames.length
+```
+Deleting the last child also deletes the parent, which keeps the cache consistent without any manual bookkeeping.

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

@@ -0,0 +1,300 @@
+# 📦 TinyMediaLoader
+
+`TinyMediaLoader` is the abstract base class that powers every media loader in the library. It owns the whole lifecycle of a media element — download, cache, progress, state machine and cleanup — while subclasses only describe **how** a specific kind of media is created and decoded.
+
+> **Note:** this class cannot be instantiated directly. Use [`TinyImageLoader`](./TinyImageLoader.md), [`TinyFetchLoader`](./TinyFetchLoader.md) or extend it with your own `_createElement` / `_startLoad` implementation.
+
+---
+
+## ✨ Highlights
+
+* **Full state machine** — `idle` → `loading` → `loaded` / `error` → `destroyed`.
+* **Streaming with progress** — every chunk is measured, so you get speed, ETA and byte counts for free.
+* **Shared cache** — plug a [`TinyMediaCache`](./TinyMediaCache.md) and the same URL is never downloaded twice.
+* **Mirror registry** — concurrent loads of the same URL share a single network request.
+* **Progressive rendering** — the element is updated while the bytes are still arriving.
+* **Optional `HEAD` pre-flight** — read the response headers before downloading the body.
+* **Typed events** — the entire event surface is described by `MediaLoaderEvents`.
+
+---
+
+## 🚀 Quick start
+
+```js
+import TinyImageLoader from 'tiny-essentials/libs/html/loader/formats/TinyImageLoader';
+import TinyMediaCache from 'tiny-essentials/libs/html/loader/utils/TinyMediaCache';
+
+const cache = new TinyMediaCache({ maxItems: 50, maxBytes: 64 * 1024 * 1024 });
+
+const loader = new TinyImageLoader({
+  src: 'https://picsum.photos/1200/800',
+  cache,
+  timeout: 30_000,
+});
+
+loader.on('progress', (p) => console.log(`${p.percent.toFixed(1)}%`));
+loader.on('error', (error) => console.error(error));
+
+await loader.load();
+loader.mount(document.body);
+```
+
+---
+
+## ⚙️ Options
+
+Every option is optional.
+
+| Option | Type | Default | Description |
+| :--- | :--- | :--- | :--- |
+| `src` | `string` | `''` | The media source URL. |
+| `timeout` | `number` | `Infinity` | Maximum time in milliseconds before the load is aborted. |
+| `element` | `HTMLElement \| null` | `null` | An existing DOM element to adopt instead of creating a new one. |
+| `autoReload` | `boolean` | `false` | Reloads automatically when the `src` attribute changes externally. |
+| `originalSrc` | `boolean` | `false` | Mirrors the original URL into the `original-src` attribute. |
+| `earlyDecode` | `boolean` | `true` | Decodes dimensions from the response headers using WebCodecs. |
+| `progressive` | `boolean` | `true` | Renders the media while it is still downloading. |
+| `useHeadRequest` | `boolean` | `false` | Performs a `HEAD` request to read the headers before downloading. |
+| `mirror` | `boolean` | `true` | Shares a single download between loaders that request the same URL. |
+| `cache` | `TinyMediaCache \| null` | `null` | A shared memory cache. |
+| `body` | `BodyInit \| undefined` | `undefined` | The request body forwarded to the transport. Ignored by `GET`/`HEAD`, which the Fetch spec forbids from carrying a body. |
+
+> **Note:** `body` is only sent when the request is not a `GET`/`HEAD` (for example when a subclass sets `_requestInit.method` to `'POST'`). When `_requestInit.body` is already set, it takes precedence over the `body` option.
+
+---
+
+## 🧩 Properties
+
+### State
+
+| Getter | Type | Description |
+| :--- | :--- | :--- |
+| `state` | `string` | The current state machine value. |
+| `isLoading` | `boolean` | `true` while a load is in flight. |
+| `isLoaded` | `boolean` | `true` after a successful load. |
+| `hasError` | `boolean` | `true` when the last load failed. |
+| `aborted` | `boolean` | `true` when the last load was aborted. |
+
+### Source & element
+
+| Getter | Type | Description |
+| :--- | :--- | :--- |
+| `src` | `string` | The current source URL (settable). |
+| `internalSrc` | `string` | The URL currently assigned to the element (may be an object URL). |
+| `objectUrl` | `string \| null` | The object URL created for a streamed blob. |
+| `element` | `HTMLElement \| null` | The managed DOM element. |
+
+### Network
+
+| Getter | Type | Description |
+| :--- | :--- | :--- |
+| `response` | `Response \| null` | The `GET` response, when one was received. |
+| `headResponse` | `Response \| null` | The `HEAD` response, when `useHeadRequest` is enabled. |
+| `useHeadRequest` | `boolean` | Whether the `HEAD` pre-flight is enabled. |
+| `progressive` | `boolean` | Whether progressive rendering is enabled. |
+| `mirror` | `boolean` | Whether download mirroring is enabled. |
+| `mirrored` | `boolean` | `true` when the payload was shared by another loader. |
+| `signal` | `AbortSignal` | The signal of the current request. |
+| `body` | `BodyInit \| undefined` | The request body forwarded to the transport (settable). |
+| `pending` | `boolean` | `true` while another loader is downloading the same source (mirror registry). |
+| `cached` | `boolean` | `true` when the current source is already available in the shared cache. |
+
+### Metrics
+
+| Getter | Type | Description |
+| :--- | :--- | :--- |
+| `progress` | `MediaProgressSnapshot \| null` | The latest progress snapshot. |
+| `metadata` | `MediaMetadata` | The metadata of the last successful load. |
+| `resourceSize` | `number` | The resource size in bytes. |
+| `startTime` | `number` | Timestamp of when the load started. |
+| `endTime` | `number` | Timestamp of when the load finished. |
+| `cacheHint` | `boolean` | Whether the resource is expected to come from the cache. |
+| `cacheAcquired` | `boolean` | Whether the cache entry is currently acquired. |
+
+---
+
+## 🛠️ Methods
+
+### `load()`
+
+Starts the download and resolves with the final `MediaMetadata`.
+
+```js
+const metadata = await loader.load();
+console.log(metadata.width, metadata.height, metadata.size);
+```
+
+* **Throws:** `Error` when the loader was destroyed, is already loading, or has no source.
+
+### `reload()`
+
+Resets the state machine and loads the current source again.
+
+### `abort()`
+
+Cancels the in-flight load.
+
+* **Returns:** `boolean` — `true` when a load was cancelled.
+
+### `mount(container)`
+
+Appends the managed element to `container`.
+
+```js
+loader.mount(document.querySelector('#stage'));
+```
+
+### `destroy()`
+
+Aborts the request, releases the cache entry, detaches every listener and revokes the object URLs. The instance cannot be reused afterwards.
+
+### `isCached(src = this.src)`
+
+Checks whether a URL already has a live payload in the shared cache, without acquiring a reference and without touching the network. The lookup is strictly read-only: it never increments `hits`/`misses`, never revives an expired entry and never creates an object URL.
+
+```js
+if (loader.isCached('https://cdn/a.png')) {
+  console.log('no network request needed');
+}
+```
+
+* **Returns:** `boolean` — `true` when the cache holds a live entry.
+* **Throws:** `TypeError` when `src` is not a string; `Error` when the cache was destroyed.
+
+### `peekCache(src = this.src)`
+
+Reads the cache entry of a URL without acquiring a reference, so it can be inspected (size, type, metadata) before deciding to load it.
+
+```js
+const entry = loader.peekCache('https://cdn/a.png');
+if (entry) console.log(entry.size, entry.type, entry.metadata);
+```
+
+* **Returns:** `MediaCacheEntry | null` — the cached entry, or `null`.
+* **Throws:** `TypeError` when `src` is not a string; `Error` when the cache was destroyed.
+
+---
+
+## 📡 Events
+
+| Event | Payload | Description |
+| :--- | :--- | :--- |
+| `loadstart` | `{ src }` | A load just started. |
+| `progress` | `MediaProgressSnapshot` | Download progress. |
+| `chunk` | `{ chunk, loaded, total }` | A binary chunk was received. |
+| `metadata` | `(metadata, type)` | Partial or full metadata was resolved. |
+| `response` | `Response` | The `GET` response was received. |
+| `headResponse` | `Response` | The `HEAD` response was received. |
+| `cachemiss` | `MediaCacheEntry` | The resource was not in the cache. |
+| `cachehit` | `MediaCacheEntry` | The resource was served from the cache. |
+| `mirror` | `MediaMirrorPayload` | The download is being shared with another loader. |
+| `statechange` | `{ state, previous, src }` | The state machine transitioned. |
+| `srcchange` | `{ src, previousSrc }` | The source URL changed. |
+| `srctransition` | `{ src, internalSrc }` | The element swapped between a network and an object URL. |
+| `timeout` | `{ src, timeout }` | The configured timeout was reached. |
+| `abort` | `{ src }` | The load was aborted. |
+| `loaded` | `MediaMetadata` | The media was fully loaded. |
+| `loadend` | `{ src, state }` | The load finished, successfully or not. |
+| `error` | `Error` | An unrecoverable error occurred. |
+| `destroy` | — | The loader was destroyed. |
+
+---
+
+## 🧬 Metadata
+
+```ts
+type MediaMetadata = {
+  src: string;
+  type: string;
+  width: number;
+  height: number;
+  duration: number;
+  size: number;
+  fromCache: boolean;
+  loadTime: number;
+  timestamp: number;
+  animation: AnimationProbeData | null;
+  httpHeaders?: Record<string, string>;
+};
+```
+
+---
+
+## 📤 Request body
+
+The `body` option forwards a payload to the transport, which is required by endpoints that only accept `POST`, `PUT` or `PATCH` requests. It is ignored by `GET` and `HEAD`, because the Fetch specification forbids those methods from carrying a body.
+
+```js
+const loader = new TinyFetchLoader({
+  src: 'https://api.example.com/render',
+  init: { method: 'POST', headers: { 'Content-Type': 'application/json' } },
+  body: JSON.stringify({ width: 800, height: 450 }),
+  responseType: 'blob',
+});
+
+await loader.load();
+```
+
+* When `init.body` is already set, it takes precedence over the `body` option.
+* The value is exposed through the `body` getter/setter, so it can be replaced between loads:
+
+```js
+loader.body = JSON.stringify({ width: 1920, height: 1080 });
+await loader.reload();
+```
+
+---
+
+## 🪞 Mirror registry
+
+When two loaders request the same URL at the same time, only one connection is opened. The second loader attaches to the running download, replays the events emitted so far and receives the very same `Blob` instance.
+
+```js
+const a = new TinyImageLoader({ src, mirror: true });
+const b = new TinyImageLoader({ src, mirror: true });
+
+b.on('mirror', (info) => console.log(`sharing with ${info.mirrors} loader(s)`));
+
+await Promise.all([a.load(), b.load()]);
+console.log(b.mirrored); // true
+```
+
+Set `mirror: false` to always open a dedicated request.
+
+---
+
+## 🧩 Extending
+
+Subclasses must implement the protected hooks below.
+
+| Hook | Description |
+| :--- | :--- |
+| `static get tagName` | The uppercase tag name of the managed element. |
+| `_createElement()` | Creates the DOM element. |
+| `_startLoad()` | Performs the download and resolves when the media is ready. |
+| `_getMetadataDetails()` | Returns the media specific metadata fields. |
+| `_abort()` | Cancels the underlying operation. |
+| `_cleanup()` | Releases the subclass resources. |
+
+```js
+import TinyMediaLoader from 'tiny-essentials/libs/html/loader/TinyMediaLoader';
+
+class TinyJsonLoader extends TinyMediaLoader {
+  static get tagName() {
+    return 'DIV';
+  }
+
+  async _startLoad() {
+    const blob = await this._downloadStream(this.src);
+    this.data = JSON.parse(await blob.text());
+  }
+
+  _getMetadataDetails() {
+    return { type: 'application/json', width: 0, height: 0, duration: 0, size: 0 };
+  }
+
+  _createElement() {
+    return document.createElement('div');
+  }
+}
+```

package/docs/v1/libs/tools/TinyPkgExportValidator.md

@@ -228,6 +228,9 @@ To ensure a valid custom message object, you must provide all the following keys
 | `itemValid` | Message for a successful check. |
 | `itemInvalid` | Message for a failed check. |
 | `itemMissing` | Message showing the missing path. |
+| `itemSkipped` | Message for a `null` target (excluded subpath). |
+| `itemPattern` | Message for a successful wildcard match. |
+| `itemInvalidTarget` | Message for an invalid target, with the reason code. |
 | `successHeader` | Final message on total success. |
 | `failureHeader` | Final message on failure. |
 | `errorLoad` | Error if `package.json` isn't loaded. |
@@ -271,8 +274,60 @@ FAILURE: 1 export(s) are missing or invalid.
 ## ⚠️ Error Handling
 
 The validator provides specific feedback for common issues:
+
 1. **`errorLoad`**: Attempted to validate before calling `.start()`.
 2. **`noExports`**: The `package.json` exists, but the `"exports"` field is missing.
 3. **`errorNotFound`**: The file at `packageJsonPath` does not exist.
 4. **`errorParse`**: The `package.json` file contains syntax errors.
 5. **`errorUnexpected`**: Any other error (e.g., permission issues).
+
+---
+
+## 🧭 Node.js `exports` rules
+
+Starting with version 1.29.2 the validator follows the [official Node.js documentation](https://nodejs.org/api/packages.html#package-entry-points) for the `exports` field.
+
+### Wildcard targets
+
+A target that contains `*` is expanded against the file system. The validation succeeds when at least one file matches the pattern:
+
+```json
+{
+  "exports": {
+    "./css/*.css": "./dist/v1/css/*.css"
+  }
+}
+```
+
+### `null` targets
+
+A `null` target excludes a subpath from a broader pattern. It is reported as `itemSkipped` and never fails the validation:
+
+```json
+{
+  "exports": {
+    "./internal/*": null
+  }
+}
+```
+
+### Fallback arrays
+
+An array is treated as an ordered list of fallbacks. Every entry is validated, and an empty array is reported as `EMPTY_ARRAY`.
+
+### Rejected targets
+
+| Reason | Description |
+| :--- | :--- |
+| `EMPTY_TARGET` | The target is an empty string. |
+| `INVALID_SEGMENT` | The target contains `\`, `.` or `..` segments. |
+| `INVALID_CHARACTER` | The target contains `?` or `#`. |
+| `URL_SCHEME_NOT_ALLOWED` | The target looks like a URL (`node:fs`, `https://…`). |
+| `TARGET_NOT_RELATIVE` | The target does not start with `./`. |
+| `INVALID_PATTERN` | The target contains `**`. |
+| `PATTERN_NO_MATCH` | The wildcard pattern matched no file. |
+| `DIRECTORY_NOT_FOUND` | The directory that holds the pattern does not exist. |
+| `NESTED_SUBPATH_KEY` | A subpath key was declared inside another subpath. |
+| `INVALID_SUBPATH_KEY` | A key starts with `.` but is not `.` or `./…`. |
+| `INVALID_CONDITION` | A condition key contains `,`, `/` or `\`. |
+| `EMPTY_KEY` | A key is an empty string. |

package/docs/v1/webTemplates/ag-psd/31.0/ProcessSolidFilters.md

@@ -2,10 +2,6 @@
 
 > Extract solid colors from PSD layers, generate separated images per filter, and get pixel statistics — in **Node.js** and the **Browser**, with the exact same API.
 
-[![Node.js](https://img.shields.io/badge/Node.js-%E2%89%A518-339933?logo=node.js&logoColor=white)](#-nodejs-usage)
-[![Browser](https://img.shields.io/badge/Browser-ESM-4285F4?logo=googlechrome&logoColor=white)](#-browser-usage)
-[![ag-psd](https://img.shields.io/badge/built%20on-ag--psd-8A2BE2)](#-how-it-works)
-
 ---
 
 ## 📖 Table of Contents