textmode.js 0.6.0-beta.3 → 0.6.0-beta.4

package/README.md

@@ -58,25 +58,6 @@ To get started with `textmode.js`, you'll need:
 
 ### Importing `textmode.js`
 
-`textmode.js` is available in multiple bundle variants to suit different project needs:
-
-| Bundle type | File size | Font included? | Best for |
-|-------------|-----------|---------------|----------|
-| **Standard UMD** (`textmode.umd.js`) | ~87kB | ✅ [UrsaFont](https://ursafrank.itch.io/ursafont) embedded | Quick setup, prototyping |
-| **Standard ESM** (`textmode.esm.js`) | ~111kB | ✅ [UrsaFont](https://ursafrank.itch.io/ursafont) embedded | Quick setup, prototyping |
-| **Minified UMD** (`textmode.umd.min.js`) | ~79kB | ❌ Requires external font | Custom fonts |
-| **Minified ESM** (`textmode.esm.min.js`) | ~103kB | ❌ Requires external font | Custom fonts |
-
-**Choose standard bundles for:**
-- Quick setup with no additional configuration
-- Production applications that use the embedded font
-
-**Choose minified bundles for:**
-- Production applications that don't use the embedded font
-
-> [!NOTE]
-> Apart from the font inclusion, both bundle types are functionally identical and equally minified.
-
 #### UMD
 
 To use `textmode.js` in a UMD environment, download the latest `umd` build from the [**GitHub releases page**](https://github.com/humanbydefinition/textmode.js/releases/) or import it directly from a CDN like [**jsDelivr**](https://www.jsdelivr.com/package/npm/textmode.js). The library is distributed as a single JavaScript file, which you can include in your project by adding the following script tag to your HTML file:
@@ -186,6 +167,65 @@ t.windowResized(() => {
 });
 ```
 
+## Conversion strategies & add-ons
+
+`textmode.js` now exposes a pluggable conversion pipeline so you can swap out how images, videos, and other sources translate into ASCII cells. The core bundle ships with the classic brightness-based converter, and you can register additional strategies at runtime—either from your own code or from official/community add-ons.
+
+```ts
+import {
+    registerConversionStrategy,
+    Shader,
+    type TextmodeConversionStrategy,
+} from 'textmode.js';
+
+import fragmentSource from './my-custom-image-to-mrt.frag';
+import vertexSource from './my-shared-instanced.vert';
+
+const customStrategy: TextmodeConversionStrategy = {
+    id: 'posterize',
+    createShader({ gl }) {
+        return new Shader(gl, vertexSource, fragmentSource);
+    },
+    createUniforms({ source }) {
+        return {
+            ...source.createBaseConversionUniforms(),
+            u_levels: 6,
+        };
+    },
+};
+
+registerConversionStrategy(customStrategy);
+
+// Later in your sketch
+image.conversionMode('posterize');
+```
+
+### Accurate conversion add-on
+
+The heavy multi-sample “accurate” converter now lives in a standalone add-on so you only pay for it when you need it:
+
+```bash
+npm install textmode.accurate.js
+```
+
+```ts
+import { textmode } from 'textmode.js';
+import { createAccurateConversionPlugin } from 'textmode.accurate.js';
+
+const t = textmode.create({
+    width: 1024,
+    height: 576,
+    plugins: [createAccurateConversionPlugin()],
+});
+
+t.setup(async () => {
+    const img = await t.loadImage('https://example.com/image.jpg');
+    img.conversionMode('accurate', { sampleRate: 12 });
+});
+```
+
+If you call `conversionMode('accurate')` without the add-on installed, `textmode.js` will throw a clear runtime error explaining how to enable it.
+
 ## Next steps
 
 Now that you have `textmode.js` set up, you can start creating your textmode art projects! Going forward, here are some resources to help you get the most out of the library: