docs: explain loading and reading images functions for browser

EscapedGibbon · web-flow · commit 636de85223b5 · 2025-12-09T17:26:29.000+01:00
diff --git a/blog/releases/1.0.md b/blog/releases/1.0.md
@@ -31,7 +31,11 @@ Developers can now catch bugs at compile time rather than discovering them in pr
 
 #### Loading and saving images
 
-`load()` and `save()` have been replaced with dedicated functions `read()` and `write()`.
+`load()` and `save()` have been restructured and replaced with different functions.
+
+#### Node.js only
+
+`read()` and `write()` are for reading and writing images on the file system with Node.js.
 
 ```ts
 //Before
@@ -55,7 +59,33 @@ const img = readSync('cat.jpg');
 writeSync('newCat.jpg', img);
 ```
 
-Those changes separate I/O operations from image manipulation for a clearer API design.
+#### Node.js and browser
+
+You can read an image via URL, by using `fetchURL`. This function works both for Node.js and browser.
+
+```ts
+import { fetchURL } from 'image-js';
+let image = await fetchURL('https://example.com/image.jpg');
+image = image.grey();
+```
+
+#### Browser only
+
+If you have an HTML element that you want to read an image from, use `readImg`.
+
+```ts
+const htmlImage = document.querySelector('img');
+const img = readImg(htmlImage);
+```
+
+For writing an image in the browser to canvas, `writeCanvas` is available.
+
+```ts
+const canvas = document.getElementById('myCanvas');
+writeCanvas(img, canvas);
+```
+
+These changes separate I/O operations from image manipulation for a clearer API design.
 
 #### Creating images
 
@@ -254,6 +284,8 @@ Several methods have been renamed for consistency:
 
 `img.getMedian()` ➡️ `img.median()`
 
+`getBase64()` ➡️ `encodeDataURL()`
+
 ### Compatibility requirements
 
 - Node.js: 18+ (previously 14+)
diff --git a/docs/getting-started.mdx b/docs/getting-started.mdx
@@ -96,6 +96,45 @@ let image = await fetchURL('https://example.com/image.jpg');
 image = image.grey();
 ```
 
+You can also read and write an image from and to HTML image source. Here is a simple example:
+
+```html
+<html>
+  <head> </head>
+  <body>
+    <img src="https://example.com/image.jpg" />
+    <canvas id="myCanvas"></canvas>
+    <script type="module">
+      import {
+        readImg,
+        writeCanvas,
+      } from 'https://cdn.jsdelivr.net/npm/image-js@latest/+esm';
+
+      async function run() {
+        const htmlImg = document.querySelector('img');
+        // Wait for image to load
+        const { promise, resolve } = Promise.withResolvers();
+
+        if (htmlImg.complete) {
+          resolve();
+        } else {
+          htmlImg.onload = resolve;
+        }
+
+        await promise;
+
+        let img = await readImg(htmlImg);
+        img = img.grey();
+        const canvas = document.getElementById('myCanvas');
+        writeCanvas(img, canvas);
+      }
+
+      await run();
+    </script>
+  </body>
+</html>
+```
+
 :::info
 To see more methods, visit the ["Features"](./features/features.mdx) category.
 :::
