ascii-shape-renderer 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Will Laws
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,113 @@
+# ASCII Shape Renderer
+
+> ## 📖 This library implements the techniques from [Alex Harri's brilliant blog post](https://alexharri.com/blog/ascii-rendering)
+> 
+> **"ASCII characters are not pixels"** — If you want to understand *why* this works, read his post. It's excellent and covers everything in depth with interactive demos.
+
+![ASCII Renderer Demo](preview.gif)
+
+**[Live Demo](https://jeeshofone.github.io/ascii-shape-renderer/demo.html)** | **[Video Demo](https://jeeshofone.github.io/ascii-shape-renderer/video-demo.html)** | **[All Examples](https://jeeshofone.github.io/ascii-shape-renderer/example.html)**
+
+## How It Works
+
+From [Alex Harri's post](https://alexharri.com/blog/ascii-rendering):
+
+> "Most ASCII renderers map each pixel's brightness to a character... but this ignores the *shape* of each character."
+
+Instead, this library:
+
+1. **Captures character shapes** using 6 sampling circles in a staggered grid
+2. **Matches shapes** via k-d tree lookup in 6D space
+3. **Enhances contrast** to sharpen edges and prevent "staircasing"
+
+The result: characters follow contours instead of creating blocky pixels.
+
+## Features
+
+- Sharp edges via shape matching (not brightness mapping)
+- Color modes: none, foreground, background, or both
+- Video & webcam support with Web Workers
+- Single script tag — no build step required
+
+## Quick Start
+
+### Browser
+
+```html
+<script src="https://unpkg.com/ascii-shape-renderer"></script>
+<pre id="output"></pre>
+<script>
+  AsciiRenderer.image('photo.jpg', '#output', { colorMode: 'fg' });
+</script>
+```
+
+### Video
+
+```html
+<script>
+  AsciiRenderer.video('video.mp4', '#output', { colorMode: 'both' });
+</script>
+```
+
+### Webcam
+
+```html
+<script>
+  AsciiRenderer.webcam('#output', { colorMode: 'fg' });
+</script>
+```
+
+### npm
+
+```bash
+npm install ascii-shape-renderer
+```
+
+```typescript
+import { AsciiRenderer } from 'ascii-shape-renderer';
+
+const renderer = new AsciiRenderer({ colorMode: 'fg' });
+const ascii = renderer.render(imageData);
+```
+
+### Node.js
+
+Works in Node.js with the `canvas` package:
+
+```bash
+npm install ascii-shape-renderer canvas
+```
+
+```javascript
+const { createCanvas, loadImage } = require('canvas');
+const { AsciiRenderer } = require('ascii-shape-renderer');
+
+const renderer = new AsciiRenderer({ colorMode: 'fg' });
+
+const img = await loadImage('photo.jpg');
+const canvas = createCanvas(img.width, img.height);
+const ctx = canvas.getContext('2d');
+ctx.drawImage(img, 0, 0);
+
+const ascii = renderer.render(ctx.getImageData(0, 0, img.width, img.height));
+console.log(ascii);
+```
+
+## Options
+
+| Option | Default | Description |
+|--------|---------|-------------|
+| `colorMode` | `'none'` | `'none'`, `'fg'`, `'bg'`, or `'both'` |
+| `globalContrastExponent` | `2` | Sharpens all boundaries |
+| `directionalContrastExponent` | `3` | Prevents staircasing at edges |
+| `cellWidth` / `cellHeight` | `10` / `16` | Cell size in source pixels |
+
+## Credits
+
+This is an implementation of [Alex Harri's ASCII rendering technique](https://alexharri.com/blog/ascii-rendering). All the clever ideas — shape vectors, contrast enhancement, k-d tree lookups — come from his post.
+
+Sample video: [Big Buck Bunny](https://peach.blender.org/) © Blender Foundation | [CC BY 3.0](https://creativecommons.org/licenses/by/3.0/)
+
+## License
+
+MIT

package/dist/ascii-renderer.esm.js

@@ -0,0 +1,447 @@
+// src/browser.ts
+var BASE_CW = 8;
+var BASE_CH = 14;
+var CIRCLE_R = 0.18;
+var CHARS = " !\"#$%&'()*+,-./0123456789:;<=>?@ABCDEFGHIJKLMNOPQRSTUVWXYZ[\\]^_`abcdefghijklmnopqrstuvwxyz{|}~";
+var INT_POS = [{ x: 0.25, y: 0.2 }, { x: 0.75, y: 0.13 }, { x: 0.25, y: 0.5 }, { x: 0.75, y: 0.5 }, { x: 0.25, y: 0.8 }, { x: 0.75, y: 0.87 }];
+var EXT_POS = [{ x: 0.25, y: -0.15 }, { x: 0.75, y: -0.15 }, { x: -0.15, y: 0.2 }, { x: 1.15, y: 0.13 }, { x: -0.15, y: 0.5 }, { x: 1.15, y: 0.5 }, { x: -0.15, y: 0.8 }, { x: 1.15, y: 0.87 }, { x: 0.25, y: 1.15 }, { x: 0.75, y: 1.15 }];
+var AFFECT = [[0, 1, 2, 4], [0, 1, 3, 5], [2, 4, 6], [3, 5, 7], [4, 6, 8, 9], [5, 7, 8, 9]];
+var shapeVecs = [];
+var kdTree = null;
+var initialized = false;
+var workerPool = [];
+var workerIndex = 0;
+var pendingCallbacks = /* @__PURE__ */ new Map();
+var messageId = 0;
+function getWorker() {
+  if (typeof Worker === "undefined") return null;
+  if (workerPool.length === 0) {
+    const workerCode = `${WORKER_CODE}`;
+    try {
+      const blob = new Blob([workerCode], { type: "application/javascript" });
+      const url = URL.createObjectURL(blob);
+      const numWorkers = Math.min(navigator.hardwareConcurrency || 4, 4);
+      for (let i = 0; i < numWorkers; i++) {
+        const w = new Worker(url);
+        w.onmessage = (e) => {
+          const cb = pendingCallbacks.get(e.data.id);
+          if (cb) {
+            pendingCallbacks.delete(e.data.id);
+            cb(e.data);
+          }
+        };
+        workerPool.push(w);
+      }
+      console.log(`[AsciiRenderer] Using ${numWorkers} Web Workers for rendering`);
+    } catch (e) {
+      console.log("[AsciiRenderer] Web Workers unavailable, using main thread");
+      return null;
+    }
+  }
+  const worker = workerPool[workerIndex];
+  workerIndex = (workerIndex + 1) % workerPool.length;
+  return worker;
+}
+function renderInWorker(data, width, height, options) {
+  return new Promise((resolve) => {
+    const worker = getWorker();
+    if (!worker) {
+      init();
+      resolve(renderFrame({ data, width, height }, options));
+      return;
+    }
+    const id = messageId++;
+    pendingCallbacks.set(id, resolve);
+    worker.postMessage({ type: "render", id, data, width, height, options }, [data.buffer]);
+  });
+}
+var WORKER_CODE = `
+const BASE_CW=8,BASE_CH=14,CIRCLE_R=.18,CHARS=' !"#$%&\\'()*+,-./0123456789:;<=>?@ABCDEFGHIJKLMNOPQRSTUVWXYZ[\\\\]^\`_abcdefghijklmnopqrstuvwxyz{|}~',INT_POS=[{x:.25,y:.2},{x:.75,y:.13},{x:.25,y:.5},{x:.75,y:.5},{x:.25,y:.8},{x:.75,y:.87}],EXT_POS=[{x:.25,y:-.15},{x:.75,y:-.15},{x:-.15,y:.2},{x:1.15,y:.13},{x:-.15,y:.5},{x:1.15,y:.5},{x:-.15,y:.8},{x:1.15,y:.87},{x:.25,y:1.15},{x:.75,y:1.15}],AFFECT=[[0,1,2,4],[0,1,3,5],[2,4,6],[3,5,7],[4,6,8,9],[5,7,8,9]];let shapeVecs=[],kdTree=null;const cache=new Map;function init(){if(kdTree)return;const c=new OffscreenCanvas(BASE_CW,BASE_CH),ctx=c.getContext("2d",{willReadFrequently:true});for(const ch of CHARS){ctx.fillStyle="#000",ctx.fillRect(0,0,BASE_CW,BASE_CH),ctx.fillStyle="#fff",ctx.font=BASE_CH+"px monospace",ctx.textBaseline="top",ctx.textAlign="center",ctx.fillText(ch,BASE_CW/2,0);const d=ctx.getImageData(0,0,BASE_CW,BASE_CH),v=INT_POS.map(p=>sampleC(d,p.x*BASE_CW,p.y*BASE_CH,CIRCLE_R*BASE_CH));shapeVecs.push({ch,v})}const max=[0,0,0,0,0,0];shapeVecs.forEach(({v})=>v.forEach((x,i)=>max[i]=Math.max(max[i],x))),shapeVecs=shapeVecs.map(({ch,v})=>({ch,v:v.map((x,i)=>max[i]?x/max[i]:0)})),kdTree=buildKd(shapeVecs)}function sampleC(d,cx,cy,r){let t=0,c=0;for(let dy=-r;dy<=r;dy++)for(let dx=-r;dx<=r;dx++)dx*dx+dy*dy<=r*r&&(x=~~(cx+dx),y=~~(cy+dy),x>=0&&x<d.width&&y>=0&&y<d.height&&(t+=d.data[(y*d.width+x)*4]/255,c++));return c?t/c:0}function buildKd(items,depth=0){if(!items.length)return null;const a=depth%6;items.sort((x,y)=>x.v[a]-y.v[a]);const m=items.length>>1;return{item:items[m],left:buildKd(items.slice(0,m),depth+1),right:buildKd(items.slice(m+1),depth+1),axis:a}}function findNear(n,t,best={dist:1/0,ch:" "}){if(!n)return best;const d=n.item.v.reduce((s,x,i)=>s+(x-t[i])**2,0);d<best.dist&&(best={dist:d,ch:n.item.ch});const diff=t[n.axis]-n.item.v[n.axis];return best=findNear(diff<0?n.left:n.right,t,best),diff*diff<best.dist&&(best=findNear(diff<0?n.right:n.left,t,best)),best}function contrast(int,ext,gE,dE){let v=int.map((val,i)=>{if(dE<=1)return val;let m=val;for(const e of AFFECT[i])m=Math.max(m,ext[e]);return m?Math.pow(val/m,dE)*m:val});if(gE>1){const m=Math.max(...v);m&&(v=v.map(x=>Math.pow(x/m,gE)*m))}return v}function sampleImg(data,w,h,cx,cy,r){let t=0,c=0;for(let dy=-r;dy<=r;dy+=2)for(let dx=-r;dx<=r;dx+=2)dx*dx+dy*dy<=r*r&&(x=~~(cx+dx),y=~~(cy+dy),x>=0&&x<w&&y>=0&&y<h&&(i=(y*w+x)*4,t+=.2126*data[i]/255+.7152*data[i+1]/255+.0722*data[i+2]/255,c++));return c?t/c:0}function sampleClr(data,w,h,cx,cy,cw,ch){let r=0,g=0,b=0,c=0;for(let dy=ch*.25;dy<ch*.75;dy+=2)for(let dx=cw*.25;dx<cw*.75;dx+=2){const x=~~(cx+dx),y=~~(cy+dy);x>=0&&x<w&&y>=0&&y<h&&(i=(y*w+x)*4,r+=data[i],g+=data[i+1],b+=data[i+2],c++)}return c?"#"+[r,g,b].map(v=>(~~(v/c)).toString(16).padStart(2,"0")).join(""):"#000"}function darken(h,a){return"#"+[1,3,5].map(i=>(~~(parseInt(h.slice(i,i+2),16)*(1-a))).toString(16).padStart(2,"0")).join("")}function renderFrame(data,w,h,opts){const gE=opts.globalContrast??2,dE=opts.directionalContrast??3,colorMode=opts.colorMode??"none",cols=Math.round(w/BASE_CW),rows=Math.round(h/BASE_CH),cW=w/cols,cH=h/rows,r=CIRCLE_R*cH;cache.clear();let html="";for(let row=0;row<rows;row++){for(let col=0;col<cols;col++){const cx=col*cW,cy=row*cH,int=INT_POS.map(p=>sampleImg(data,w,h,cx+p.x*cW,cy+p.y*cH,r)),ext=EXT_POS.map(p=>sampleImg(data,w,h,cx+p.x*cW,cy+p.y*cH,r)),enh=contrast(int,ext,gE,dE),key=enh.map(v=>~~(31*v)).join(",");cache.has(key)||cache.set(key,findNear(kdTree,enh).ch);let ch=cache.get(key);"<"===ch?ch="&lt;":">"===ch?ch="&gt;":"&"===ch&&(ch="&amp;"),"none"===colorMode?html+=ch:(clr=sampleClr(data,w,h,cx,cy,cW,cH),st=[],"fg"!==colorMode&&"both"!==colorMode||st.push("color:"+clr),"bg"!==colorMode&&"both"!==colorMode||st.push("background:"+darken(clr,.5)),html+='<span style="'+st.join(";")+'">'+ch+"</span>")}html+="\\n"}return{html,cols,rows}}self.onmessage=e=>{if("render"===e.data.type){init();const{id,data,width,height,options}=e.data,result=renderFrame(data,width,height,options);self.postMessage({id,...result})}};
+`;
+function init() {
+  if (initialized) return;
+  const c = document.createElement("canvas");
+  c.width = BASE_CW;
+  c.height = BASE_CH;
+  const ctx = c.getContext("2d", { willReadFrequently: true });
+  for (const ch of CHARS) {
+    ctx.fillStyle = "#000";
+    ctx.fillRect(0, 0, BASE_CW, BASE_CH);
+    ctx.fillStyle = "#fff";
+    ctx.font = `${BASE_CH}px monospace`;
+    ctx.textBaseline = "top";
+    ctx.textAlign = "center";
+    ctx.fillText(ch, BASE_CW / 2, 0);
+    const d = ctx.getImageData(0, 0, BASE_CW, BASE_CH);
+    const v = INT_POS.map((p) => sampleCircle(d, p.x * BASE_CW, p.y * BASE_CH, CIRCLE_R * BASE_CH));
+    shapeVecs.push({ ch, v });
+  }
+  const max = [0, 0, 0, 0, 0, 0];
+  shapeVecs.forEach(({ v }) => v.forEach((x, i) => max[i] = Math.max(max[i], x)));
+  shapeVecs = shapeVecs.map(({ ch, v }) => ({ ch, v: v.map((x, i) => max[i] ? x / max[i] : 0) }));
+  kdTree = buildKd(shapeVecs);
+  initialized = true;
+}
+function sampleCircle(d, cx, cy, r) {
+  let t = 0, c = 0;
+  for (let dy = -r; dy <= r; dy++) for (let dx = -r; dx <= r; dx++)
+    if (dx * dx + dy * dy <= r * r) {
+      const x = ~~(cx + dx), y = ~~(cy + dy);
+      if (x >= 0 && x < d.width && y >= 0 && y < d.height) {
+        t += d.data[(y * d.width + x) * 4] / 255;
+        c++;
+      }
+    }
+  return c ? t / c : 0;
+}
+function buildKd(items, depth = 0) {
+  if (!items.length) return null;
+  const a = depth % 6;
+  items.sort((x, y) => x.v[a] - y.v[a]);
+  const m = items.length >> 1;
+  return { item: items[m], left: buildKd(items.slice(0, m), depth + 1), right: buildKd(items.slice(m + 1), depth + 1), axis: a };
+}
+function findNear(n, t, best = { dist: Infinity, ch: " " }) {
+  if (!n) return best;
+  const d = n.item.v.reduce((s, x, i) => s + (x - t[i]) ** 2, 0);
+  if (d < best.dist) best = { dist: d, ch: n.item.ch };
+  const diff = t[n.axis] - n.item.v[n.axis];
+  best = findNear(diff < 0 ? n.left : n.right, t, best);
+  if (diff * diff < best.dist) best = findNear(diff < 0 ? n.right : n.left, t, best);
+  return best;
+}
+function contrast(int, ext, gE, dE) {
+  let v = int.map((val, i) => {
+    if (dE <= 1) return val;
+    let m = val;
+    for (const e of AFFECT[i]) m = Math.max(m, ext[e]);
+    return m ? Math.pow(val / m, dE) * m : val;
+  });
+  if (gE > 1) {
+    const m = Math.max(...v);
+    if (m) v = v.map((x) => Math.pow(x / m, gE) * m);
+  }
+  return v;
+}
+function sampleImg(d, cx, cy, r) {
+  let t = 0, c = 0;
+  for (let dy = -r; dy <= r; dy += 2) for (let dx = -r; dx <= r; dx += 2)
+    if (dx * dx + dy * dy <= r * r) {
+      const x = ~~(cx + dx), y = ~~(cy + dy);
+      if (x >= 0 && x < d.width && y >= 0 && y < d.height) {
+        const i = (y * d.width + x) * 4;
+        t += 0.2126 * d.data[i] / 255 + 0.7152 * d.data[i + 1] / 255 + 0.0722 * d.data[i + 2] / 255;
+        c++;
+      }
+    }
+  return c ? t / c : 0;
+}
+function sampleClr(d, cx, cy, cw, ch) {
+  let r = 0, g = 0, b = 0, c = 0;
+  for (let dy = ch * 0.25; dy < ch * 0.75; dy += 2) for (let dx = cw * 0.25; dx < cw * 0.75; dx += 2) {
+    const x = ~~(cx + dx), y = ~~(cy + dy);
+    if (x >= 0 && x < d.width && y >= 0 && y < d.height) {
+      const i = (y * d.width + x) * 4;
+      r += d.data[i];
+      g += d.data[i + 1];
+      b += d.data[i + 2];
+      c++;
+    }
+  }
+  return c ? "#" + [r, g, b].map((v) => (~~(v / c)).toString(16).padStart(2, "0")).join("") : "#000";
+}
+function darken(h, a) {
+  return "#" + [1, 3, 5].map((i) => (~~(parseInt(h.slice(i, i + 2), 16) * (1 - a))).toString(16).padStart(2, "0")).join("");
+}
+var cache = /* @__PURE__ */ new Map();
+function renderFrame(imgData, opts) {
+  const gE = opts.globalContrast ?? 2;
+  const dE = opts.directionalContrast ?? 3;
+  const colorMode = opts.colorMode ?? "none";
+  const cols = Math.round(imgData.width / BASE_CW);
+  const rows = Math.round(imgData.height / BASE_CH);
+  const cW = imgData.width / cols, cH = imgData.height / rows;
+  const r = CIRCLE_R * cH;
+  cache.clear();
+  let html = "";
+  for (let row = 0; row < rows; row++) {
+    for (let col = 0; col < cols; col++) {
+      const cx = col * cW, cy = row * cH;
+      const int = INT_POS.map((p) => sampleImg(imgData, cx + p.x * cW, cy + p.y * cH, r));
+      const ext = EXT_POS.map((p) => sampleImg(imgData, cx + p.x * cW, cy + p.y * cH, r));
+      const enh = contrast(int, ext, gE, dE);
+      const key = enh.map((v) => ~~(v * 31)).join(",");
+      if (!cache.has(key)) cache.set(key, findNear(kdTree, enh).ch);
+      let ch = cache.get(key);
+      if (ch === "<") ch = "&lt;";
+      else if (ch === ">") ch = "&gt;";
+      else if (ch === "&") ch = "&amp;";
+      if (colorMode === "none") {
+        html += ch;
+      } else {
+        const clr = sampleClr(imgData, cx, cy, cW, cH);
+        const st = [];
+        if (colorMode === "fg" || colorMode === "both") st.push(`color:${clr}`);
+        if (colorMode === "bg" || colorMode === "both") st.push(`background:${darken(clr, 0.5)}`);
+        html += `<span style="${st.join(";")}">${ch}</span>`;
+      }
+    }
+    html += "\n";
+  }
+  return html;
+}
+function getEl(el) {
+  return typeof el === "string" ? document.querySelector(el) : el;
+}
+function createOutput(container, colorMode) {
+  const pre = document.createElement("pre");
+  pre.style.cssText = "margin:0;line-height:1;font-family:monospace;white-space:pre;";
+  if (colorMode === "none") pre.style.color = "#0f0";
+  pre.style.background = "#000";
+  container.innerHTML = "";
+  container.appendChild(pre);
+  return pre;
+}
+function image(source, container, options = {}) {
+  init();
+  const containerEl = getEl(container);
+  const output = createOutput(containerEl, options.colorMode ?? "none");
+  const canvas = document.createElement("canvas");
+  const ctx = canvas.getContext("2d", { willReadFrequently: true });
+  let img;
+  let currentOpts = { ...options };
+  function render() {
+    const maxW = currentOpts.maxWidth ?? 800;
+    const scale = Math.min(1, maxW / img.width);
+    canvas.width = ~~(img.width * scale);
+    canvas.height = ~~(img.height * scale);
+    ctx.drawImage(img, 0, 0, canvas.width, canvas.height);
+    const imgData = ctx.getImageData(0, 0, canvas.width, canvas.height);
+    const html = renderFrame(imgData, currentOpts);
+    const cols = Math.round(canvas.width / BASE_CW);
+    const containerWidth = containerEl.clientWidth - 16;
+    const fontSize = containerWidth / (cols * 0.6);
+    output.style.fontSize = fontSize + "px";
+    output.innerHTML = html;
+    if (currentOpts.colorMode === "none") output.style.color = "#0f0";
+    else output.style.color = "";
+  }
+  function load(src) {
+    if (typeof src === "string") {
+      img = new Image();
+      img.crossOrigin = "anonymous";
+      img.onload = render;
+      img.src = src;
+    } else {
+      img = src;
+      render();
+    }
+  }
+  load(source);
+  return {
+    update(opts) {
+      if (opts) currentOpts = { ...currentOpts, ...opts };
+      if (img) render();
+    },
+    destroy() {
+      containerEl.innerHTML = "";
+    }
+  };
+}
+function video(source, container, options = {}) {
+  init();
+  const containerEl = getEl(container);
+  const output = createOutput(containerEl, options.colorMode ?? "none");
+  const canvas = document.createElement("canvas");
+  const ctx = canvas.getContext("2d", { willReadFrequently: true });
+  const vid = document.createElement("video");
+  vid.playsInline = true;
+  vid.muted = true;
+  vid.loop = true;
+  let currentOpts = { ...options };
+  let playing = false;
+  let animId = null;
+  let lastRender = 0;
+  const minFrameTime = 1e3 / (options.fps ?? 30);
+  let canvasReady = false;
+  function setupCanvas() {
+    if (canvasReady || !vid.videoWidth) return;
+    const maxW = currentOpts.maxWidth ?? 640;
+    const scale = Math.min(1, maxW / vid.videoWidth);
+    canvas.width = ~~(vid.videoWidth * scale);
+    canvas.height = ~~(vid.videoHeight * scale);
+    canvasReady = true;
+  }
+  let rendering = false;
+  let cachedFontSize = 0;
+  async function render() {
+    if (!vid.videoWidth || rendering) return;
+    setupCanvas();
+    rendering = true;
+    ctx.drawImage(vid, 0, 0, canvas.width, canvas.height);
+    const imgData = ctx.getImageData(0, 0, canvas.width, canvas.height);
+    const result = await renderInWorker(
+      new Uint8ClampedArray(imgData.data),
+      canvas.width,
+      canvas.height,
+      currentOpts
+    );
+    if (!cachedFontSize) {
+      const containerWidth = containerEl.clientWidth - 16;
+      cachedFontSize = containerWidth / (result.cols * 0.6);
+      output.style.fontSize = cachedFontSize + "px";
+    }
+    output.innerHTML = result.html;
+    if (currentOpts.colorMode === "none") output.style.color = "#0f0";
+    else output.style.color = "";
+    rendering = false;
+  }
+  function loop() {
+    if (!playing) return;
+    const now = performance.now();
+    if (now - lastRender >= minFrameTime) {
+      lastRender = now;
+      render();
+    }
+    animId = requestAnimationFrame(loop);
+  }
+  if (source instanceof File) {
+    vid.src = URL.createObjectURL(source);
+  } else if (typeof source === "string") {
+    vid.src = source;
+  } else {
+    vid.src = source.src;
+  }
+  vid.onloadedmetadata = () => {
+    render();
+    if (options.autoplay) {
+      playing = true;
+      vid.play();
+      loop();
+    }
+  };
+  return {
+    play() {
+      if (playing || !vid.readyState) return;
+      playing = true;
+      vid.play();
+      loop();
+    },
+    pause() {
+      playing = false;
+      vid.pause();
+      if (animId) cancelAnimationFrame(animId);
+    },
+    seek(time) {
+      vid.currentTime = time;
+      if (!playing) render();
+    },
+    update(opts) {
+      if (opts) currentOpts = { ...currentOpts, ...opts };
+      if (!playing) render();
+    },
+    destroy() {
+      playing = false;
+      if (animId) cancelAnimationFrame(animId);
+      if (vid.src.startsWith("blob:")) URL.revokeObjectURL(vid.src);
+      containerEl.innerHTML = "";
+    },
+    get isPlaying() {
+      return playing;
+    },
+    get currentTime() {
+      return vid.currentTime;
+    },
+    get duration() {
+      return vid.duration;
+    }
+  };
+}
+var browser_default = { image, video, webcam };
+function webcam(container, options = {}) {
+  init();
+  const containerEl = getEl(container);
+  const output = createOutput(containerEl, options.colorMode ?? "none");
+  const canvas = document.createElement("canvas");
+  const ctx = canvas.getContext("2d", { willReadFrequently: true });
+  let currentOpts = { ...options };
+  let animId = null;
+  let stream = null;
+  let lastRender = 0;
+  const minFrameTime = 1e3 / (options.fps ?? 30);
+  const vid = document.createElement("video");
+  vid.playsInline = true;
+  vid.muted = true;
+  let canvasReady = false;
+  function setupCanvas() {
+    if (canvasReady || !vid.videoWidth) return;
+    const maxW = currentOpts.maxWidth ?? 640;
+    const scale = Math.min(1, maxW / vid.videoWidth);
+    canvas.width = ~~(vid.videoWidth * scale);
+    canvas.height = ~~(vid.videoHeight * scale);
+    canvasReady = true;
+  }
+  let rendering = false;
+  let cachedFontSize = 0;
+  async function render() {
+    if (!vid.videoWidth || rendering) return;
+    setupCanvas();
+    rendering = true;
+    ctx.drawImage(vid, 0, 0, canvas.width, canvas.height);
+    const imgData = ctx.getImageData(0, 0, canvas.width, canvas.height);
+    const result = await renderInWorker(
+      new Uint8ClampedArray(imgData.data),
+      canvas.width,
+      canvas.height,
+      currentOpts
+    );
+    if (!cachedFontSize) {
+      const containerWidth = containerEl.clientWidth - 16;
+      cachedFontSize = containerWidth / (result.cols * 0.6);
+      output.style.fontSize = cachedFontSize + "px";
+    }
+    output.innerHTML = result.html;
+    if (currentOpts.colorMode === "none") output.style.color = "#0f0";
+    else output.style.color = "";
+    rendering = false;
+  }
+  function loop() {
+    const now = performance.now();
+    if (now - lastRender >= minFrameTime) {
+      lastRender = now;
+      render();
+    }
+    animId = requestAnimationFrame(loop);
+  }
+  const videoConstraints = {
+    video: {
+      width: { ideal: 1280 },
+      height: { ideal: 720 }
+    }
+  };
+  return navigator.mediaDevices.getUserMedia(videoConstraints).then((s) => {
+    stream = s;
+    vid.srcObject = stream;
+    vid.play();
+    vid.onplaying = () => {
+      setupCanvas();
+      loop();
+    };
+    return {
+      stop() {
+        if (animId) cancelAnimationFrame(animId);
+        stream?.getTracks().forEach((t) => t.stop());
+        containerEl.innerHTML = "";
+      },
+      update(opts) {
+        if (opts) currentOpts = { ...currentOpts, ...opts };
+      }
+    };
+  });
+}
+export {
+  browser_default as default,
+  image,
+  video,
+  webcam
+};

package/dist/ascii-renderer.min.js

@@ -0,0 +1,4 @@
+"use strict";var AsciiRenderer=(()=>{var W=Object.defineProperty;var N=Object.getOwnPropertyDescriptor;var q=Object.getOwnPropertyNames;var D=Object.prototype.hasOwnProperty;var z=(e,i)=>{for(var r in i)W(e,r,{get:i[r],enumerable:!0})},$=(e,i,r,a)=>{if(i&&typeof i=="object"||typeof i=="function")for(let n of q(i))!D.call(e,n)&&n!==r&&W(e,n,{get:()=>i[n],enumerable:!(a=N(i,n))||a.enumerable});return e};var K=e=>$(W({},"__esModule",{value:!0}),e);var ie={};z(ie,{default:()=>oe,image:()=>P,video:()=>j,webcam:()=>U});var X=" !\"#$%&'()*+,-./0123456789:;<=>?@ABCDEFGHIJKLMNOPQRSTUVWXYZ[\\]^_`abcdefghijklmnopqrstuvwxyz{|}~",L=[{x:.25,y:.2},{x:.75,y:.13},{x:.25,y:.5},{x:.75,y:.5},{x:.25,y:.8},{x:.75,y:.87}],G=[{x:.25,y:-.15},{x:.75,y:-.15},{x:-.15,y:.2},{x:1.15,y:.13},{x:-.15,y:.5},{x:1.15,y:.5},{x:-.15,y:.8},{x:1.15,y:.87},{x:.25,y:1.15},{x:.75,y:1.15}],J=[[0,1,2,4],[0,1,3,5],[2,4,6],[3,5,7],[4,6,8,9],[5,7,8,9]],C=[],O=null,k=!1,v=[],A=0,H=new Map,Q=0;function Y(){if(typeof Worker>"u")return null;if(v.length===0){let i=`${Z}`;try{let r=new Blob([i],{type:"application/javascript"}),a=URL.createObjectURL(r),n=Math.min(navigator.hardwareConcurrency||4,4);for(let o=0;o<n;o++){let c=new Worker(a);c.onmessage=t=>{let s=H.get(t.data.id);s&&(H.delete(t.data.id),s(t.data))},v.push(c)}console.log(`[AsciiRenderer] Using ${n} Web Workers for rendering`)}catch{return console.log("[AsciiRenderer] Web Workers unavailable, using main thread"),null}}let e=v[A];return A=(A+1)%v.length,e}function F(e,i,r,a){return new Promise(n=>{let o=Y();if(!o){S(),n(V({data:e,width:i,height:r},a));return}let c=Q++;H.set(c,n),o.postMessage({type:"render",id:c,data:e,width:i,height:r,options:a},[e.buffer])})}var Z=`
+const BASE_CW=8,BASE_CH=14,CIRCLE_R=.18,CHARS=' !"#$%&\\'()*+,-./0123456789:;<=>?@ABCDEFGHIJKLMNOPQRSTUVWXYZ[\\\\]^\`_abcdefghijklmnopqrstuvwxyz{|}~',INT_POS=[{x:.25,y:.2},{x:.75,y:.13},{x:.25,y:.5},{x:.75,y:.5},{x:.25,y:.8},{x:.75,y:.87}],EXT_POS=[{x:.25,y:-.15},{x:.75,y:-.15},{x:-.15,y:.2},{x:1.15,y:.13},{x:-.15,y:.5},{x:1.15,y:.5},{x:-.15,y:.8},{x:1.15,y:.87},{x:.25,y:1.15},{x:.75,y:1.15}],AFFECT=[[0,1,2,4],[0,1,3,5],[2,4,6],[3,5,7],[4,6,8,9],[5,7,8,9]];let shapeVecs=[],kdTree=null;const cache=new Map;function init(){if(kdTree)return;const c=new OffscreenCanvas(BASE_CW,BASE_CH),ctx=c.getContext("2d",{willReadFrequently:true});for(const ch of CHARS){ctx.fillStyle="#000",ctx.fillRect(0,0,BASE_CW,BASE_CH),ctx.fillStyle="#fff",ctx.font=BASE_CH+"px monospace",ctx.textBaseline="top",ctx.textAlign="center",ctx.fillText(ch,BASE_CW/2,0);const d=ctx.getImageData(0,0,BASE_CW,BASE_CH),v=INT_POS.map(p=>sampleC(d,p.x*BASE_CW,p.y*BASE_CH,CIRCLE_R*BASE_CH));shapeVecs.push({ch,v})}const max=[0,0,0,0,0,0];shapeVecs.forEach(({v})=>v.forEach((x,i)=>max[i]=Math.max(max[i],x))),shapeVecs=shapeVecs.map(({ch,v})=>({ch,v:v.map((x,i)=>max[i]?x/max[i]:0)})),kdTree=buildKd(shapeVecs)}function sampleC(d,cx,cy,r){let t=0,c=0;for(let dy=-r;dy<=r;dy++)for(let dx=-r;dx<=r;dx++)dx*dx+dy*dy<=r*r&&(x=~~(cx+dx),y=~~(cy+dy),x>=0&&x<d.width&&y>=0&&y<d.height&&(t+=d.data[(y*d.width+x)*4]/255,c++));return c?t/c:0}function buildKd(items,depth=0){if(!items.length)return null;const a=depth%6;items.sort((x,y)=>x.v[a]-y.v[a]);const m=items.length>>1;return{item:items[m],left:buildKd(items.slice(0,m),depth+1),right:buildKd(items.slice(m+1),depth+1),axis:a}}function findNear(n,t,best={dist:1/0,ch:" "}){if(!n)return best;const d=n.item.v.reduce((s,x,i)=>s+(x-t[i])**2,0);d<best.dist&&(best={dist:d,ch:n.item.ch});const diff=t[n.axis]-n.item.v[n.axis];return best=findNear(diff<0?n.left:n.right,t,best),diff*diff<best.dist&&(best=findNear(diff<0?n.right:n.left,t,best)),best}function contrast(int,ext,gE,dE){let v=int.map((val,i)=>{if(dE<=1)return val;let m=val;for(const e of AFFECT[i])m=Math.max(m,ext[e]);return m?Math.pow(val/m,dE)*m:val});if(gE>1){const m=Math.max(...v);m&&(v=v.map(x=>Math.pow(x/m,gE)*m))}return v}function sampleImg(data,w,h,cx,cy,r){let t=0,c=0;for(let dy=-r;dy<=r;dy+=2)for(let dx=-r;dx<=r;dx+=2)dx*dx+dy*dy<=r*r&&(x=~~(cx+dx),y=~~(cy+dy),x>=0&&x<w&&y>=0&&y<h&&(i=(y*w+x)*4,t+=.2126*data[i]/255+.7152*data[i+1]/255+.0722*data[i+2]/255,c++));return c?t/c:0}function sampleClr(data,w,h,cx,cy,cw,ch){let r=0,g=0,b=0,c=0;for(let dy=ch*.25;dy<ch*.75;dy+=2)for(let dx=cw*.25;dx<cw*.75;dx+=2){const x=~~(cx+dx),y=~~(cy+dy);x>=0&&x<w&&y>=0&&y<h&&(i=(y*w+x)*4,r+=data[i],g+=data[i+1],b+=data[i+2],c++)}return c?"#"+[r,g,b].map(v=>(~~(v/c)).toString(16).padStart(2,"0")).join(""):"#000"}function darken(h,a){return"#"+[1,3,5].map(i=>(~~(parseInt(h.slice(i,i+2),16)*(1-a))).toString(16).padStart(2,"0")).join("")}function renderFrame(data,w,h,opts){const gE=opts.globalContrast??2,dE=opts.directionalContrast??3,colorMode=opts.colorMode??"none",cols=Math.round(w/BASE_CW),rows=Math.round(h/BASE_CH),cW=w/cols,cH=h/rows,r=CIRCLE_R*cH;cache.clear();let html="";for(let row=0;row<rows;row++){for(let col=0;col<cols;col++){const cx=col*cW,cy=row*cH,int=INT_POS.map(p=>sampleImg(data,w,h,cx+p.x*cW,cy+p.y*cH,r)),ext=EXT_POS.map(p=>sampleImg(data,w,h,cx+p.x*cW,cy+p.y*cH,r)),enh=contrast(int,ext,gE,dE),key=enh.map(v=>~~(31*v)).join(",");cache.has(key)||cache.set(key,findNear(kdTree,enh).ch);let ch=cache.get(key);"<"===ch?ch="&lt;":">"===ch?ch="&gt;":"&"===ch&&(ch="&amp;"),"none"===colorMode?html+=ch:(clr=sampleClr(data,w,h,cx,cy,cW,cH),st=[],"fg"!==colorMode&&"both"!==colorMode||st.push("color:"+clr),"bg"!==colorMode&&"both"!==colorMode||st.push("background:"+darken(clr,.5)),html+='<span style="'+st.join(";")+'">'+ch+"</span>")}html+="\\n"}return{html,cols,rows}}self.onmessage=e=>{if("render"===e.data.type){init();const{id,data,width,height,options}=e.data,result=renderFrame(data,width,height,options);self.postMessage({id,...result})}};
+`;function S(){if(k)return;let e=document.createElement("canvas");e.width=8,e.height=14;let i=e.getContext("2d",{willReadFrequently:!0});for(let a of X){i.fillStyle="#000",i.fillRect(0,0,8,14),i.fillStyle="#fff",i.font="14px monospace",i.textBaseline="top",i.textAlign="center",i.fillText(a,8/2,0);let n=i.getImageData(0,0,8,14),o=L.map(c=>ee(n,c.x*8,c.y*14,.18*14));C.push({ch:a,v:o})}let r=[0,0,0,0,0,0];C.forEach(({v:a})=>a.forEach((n,o)=>r[o]=Math.max(r[o],n))),C=C.map(({ch:a,v:n})=>({ch:a,v:n.map((o,c)=>r[c]?o/r[c]:0)})),O=T(C),k=!0}function ee(e,i,r,a){let n=0,o=0;for(let c=-a;c<=a;c++)for(let t=-a;t<=a;t++)if(t*t+c*c<=a*a){let s=~~(i+t),l=~~(r+c);s>=0&&s<e.width&&l>=0&&l<e.height&&(n+=e.data[(l*e.width+s)*4]/255,o++)}return o?n/o:0}function T(e,i=0){if(!e.length)return null;let r=i%6;e.sort((n,o)=>n.v[r]-o.v[r]);let a=e.length>>1;return{item:e[a],left:T(e.slice(0,a),i+1),right:T(e.slice(a+1),i+1),axis:r}}function _(e,i,r={dist:1/0,ch:" "}){if(!e)return r;let a=e.item.v.reduce((o,c,t)=>o+(c-i[t])**2,0);a<r.dist&&(r={dist:a,ch:e.item.ch});let n=i[e.axis]-e.item.v[e.axis];return r=_(n<0?e.left:e.right,i,r),n*n<r.dist&&(r=_(n<0?e.right:e.left,i,r)),r}function te(e,i,r,a){let n=e.map((o,c)=>{if(a<=1)return o;let t=o;for(let s of J[c])t=Math.max(t,i[s]);return t?Math.pow(o/t,a)*t:o});if(r>1){let o=Math.max(...n);o&&(n=n.map(c=>Math.pow(c/o,r)*o))}return n}function B(e,i,r,a){let n=0,o=0;for(let c=-a;c<=a;c+=2)for(let t=-a;t<=a;t+=2)if(t*t+c*c<=a*a){let s=~~(i+t),l=~~(r+c);if(s>=0&&s<e.width&&l>=0&&l<e.height){let h=(l*e.width+s)*4;n+=.2126*e.data[h]/255+.7152*e.data[h+1]/255+.0722*e.data[h+2]/255,o++}}return o?n/o:0}function ne(e,i,r,a,n){let o=0,c=0,t=0,s=0;for(let l=n*.25;l<n*.75;l+=2)for(let h=a*.25;h<a*.75;h+=2){let d=~~(i+h),f=~~(r+l);if(d>=0&&d<e.width&&f>=0&&f<e.height){let y=(f*e.width+d)*4;o+=e.data[y],c+=e.data[y+1],t+=e.data[y+2],s++}}return s?"#"+[o,c,t].map(l=>(~~(l/s)).toString(16).padStart(2,"0")).join(""):"#000"}function re(e,i){return"#"+[1,3,5].map(r=>(~~(parseInt(e.slice(r,r+2),16)*(1-i))).toString(16).padStart(2,"0")).join("")}var M=new Map;function V(e,i){let r=i.globalContrast??2,a=i.directionalContrast??3,n=i.colorMode??"none",o=Math.round(e.width/8),c=Math.round(e.height/14),t=e.width/o,s=e.height/c,l=.18*s;M.clear();let h="";for(let d=0;d<c;d++){for(let f=0;f<o;f++){let y=f*t,p=d*s,g=L.map(u=>B(e,y+u.x*t,p+u.y*s,l)),E=G.map(u=>B(e,y+u.x*t,p+u.y*s,l)),x=te(g,E,r,a),w=x.map(u=>~~(u*31)).join(",");M.has(w)||M.set(w,_(O,x).ch);let m=M.get(w);if(m==="<"?m="&lt;":m===">"?m="&gt;":m==="&"&&(m="&amp;"),n==="none")h+=m;else{let u=ne(e,y,p,t,s),b=[];(n==="fg"||n==="both")&&b.push(`color:${u}`),(n==="bg"||n==="both")&&b.push(`background:${re(u,.5)}`),h+=`<span style="${b.join(";")}">${m}</span>`}}h+=`
+`}return h}function R(e){return typeof e=="string"?document.querySelector(e):e}function I(e,i){let r=document.createElement("pre");return r.style.cssText="margin:0;line-height:1;font-family:monospace;white-space:pre;",i==="none"&&(r.style.color="#0f0"),r.style.background="#000",e.innerHTML="",e.appendChild(r),r}function P(e,i,r={}){S();let a=R(i),n=I(a,r.colorMode??"none"),o=document.createElement("canvas"),c=o.getContext("2d",{willReadFrequently:!0}),t,s={...r};function l(){let d=s.maxWidth??800,f=Math.min(1,d/t.width);o.width=~~(t.width*f),o.height=~~(t.height*f),c.drawImage(t,0,0,o.width,o.height);let y=c.getImageData(0,0,o.width,o.height),p=V(y,s),g=Math.round(o.width/8),x=(a.clientWidth-16)/(g*.6);n.style.fontSize=x+"px",n.innerHTML=p,s.colorMode==="none"?n.style.color="#0f0":n.style.color=""}function h(d){typeof d=="string"?(t=new Image,t.crossOrigin="anonymous",t.onload=l,t.src=d):(t=d,l())}return h(e),{update(d){d&&(s={...s,...d}),t&&l()},destroy(){a.innerHTML=""}}}function j(e,i,r={}){S();let a=R(i),n=I(a,r.colorMode??"none"),o=document.createElement("canvas"),c=o.getContext("2d",{willReadFrequently:!0}),t=document.createElement("video");t.playsInline=!0,t.muted=!0,t.loop=!0;let s={...r},l=!1,h=null,d=0,f=1e3/(r.fps??30),y=!1;function p(){if(y||!t.videoWidth)return;let m=s.maxWidth??640,u=Math.min(1,m/t.videoWidth);o.width=~~(t.videoWidth*u),o.height=~~(t.videoHeight*u),y=!0}let g=!1,E=0;async function x(){if(!t.videoWidth||g)return;p(),g=!0,c.drawImage(t,0,0,o.width,o.height);let m=c.getImageData(0,0,o.width,o.height),u=await F(new Uint8ClampedArray(m.data),o.width,o.height,s);E||(E=(a.clientWidth-16)/(u.cols*.6),n.style.fontSize=E+"px"),n.innerHTML=u.html,s.colorMode==="none"?n.style.color="#0f0":n.style.color="",g=!1}function w(){if(!l)return;let m=performance.now();m-d>=f&&(d=m,x()),h=requestAnimationFrame(w)}return e instanceof File?t.src=URL.createObjectURL(e):typeof e=="string"?t.src=e:t.src=e.src,t.onloadedmetadata=()=>{x(),r.autoplay&&(l=!0,t.play(),w())},{play(){l||!t.readyState||(l=!0,t.play(),w())},pause(){l=!1,t.pause(),h&&cancelAnimationFrame(h)},seek(m){t.currentTime=m,l||x()},update(m){m&&(s={...s,...m}),l||x()},destroy(){l=!1,h&&cancelAnimationFrame(h),t.src.startsWith("blob:")&&URL.revokeObjectURL(t.src),a.innerHTML=""},get isPlaying(){return l},get currentTime(){return t.currentTime},get duration(){return t.duration}}}var oe={image:P,video:j,webcam:U};function U(e,i={}){S();let r=R(e),a=I(r,i.colorMode??"none"),n=document.createElement("canvas"),o=n.getContext("2d",{willReadFrequently:!0}),c={...i},t=null,s=null,l=0,h=1e3/(i.fps??30),d=document.createElement("video");d.playsInline=!0,d.muted=!0;let f=!1;function y(){if(f||!d.videoWidth)return;let m=c.maxWidth??640,u=Math.min(1,m/d.videoWidth);n.width=~~(d.videoWidth*u),n.height=~~(d.videoHeight*u),f=!0}let p=!1,g=0;async function E(){if(!d.videoWidth||p)return;y(),p=!0,o.drawImage(d,0,0,n.width,n.height);let m=o.getImageData(0,0,n.width,n.height),u=await F(new Uint8ClampedArray(m.data),n.width,n.height,c);g||(g=(r.clientWidth-16)/(u.cols*.6),a.style.fontSize=g+"px"),a.innerHTML=u.html,c.colorMode==="none"?a.style.color="#0f0":a.style.color="",p=!1}function x(){let m=performance.now();m-l>=h&&(l=m,E()),t=requestAnimationFrame(x)}let w={video:{width:{ideal:1280},height:{ideal:720}}};return navigator.mediaDevices.getUserMedia(w).then(m=>(s=m,d.srcObject=s,d.play(),d.onplaying=()=>{y(),x()},{stop(){t&&cancelAnimationFrame(t),s?.getTracks().forEach(u=>u.stop()),r.innerHTML=""},update(u){u&&(c={...c,...u})}}))}return K(ie);})();

package/dist/browser.d.ts

@@ -0,0 +1,48 @@
+/**
+ * ASCII Shape Renderer - Browser Bundle
+ * Simple drop-in library for rendering images/video as ASCII art
+ */
+export interface RenderOptions {
+    globalContrast?: number;
+    directionalContrast?: number;
+    colorMode?: 'none' | 'fg' | 'bg' | 'both';
+    maxWidth?: number;
+    characters?: string;
+}
+export interface VideoOptions extends RenderOptions {
+    fps?: number;
+    autoplay?: boolean;
+}
+/**
+ * Render an image as ASCII art
+ */
+export declare function image(source: string | HTMLImageElement | HTMLCanvasElement, container: string | HTMLElement, options?: RenderOptions): {
+    update: (opts?: RenderOptions) => void;
+    destroy: () => void;
+};
+/**
+ * Render a video as ASCII art
+ */
+export declare function video(source: string | HTMLVideoElement | File, container: string | HTMLElement, options?: VideoOptions): {
+    play: () => void;
+    pause: () => void;
+    seek: (time: number) => void;
+    update: (opts?: VideoOptions) => void;
+    destroy: () => void;
+    readonly isPlaying: boolean;
+    readonly currentTime: number;
+    readonly duration: number;
+};
+declare const _default: {
+    image: typeof image;
+    video: typeof video;
+    webcam: typeof webcam;
+};
+export default _default;
+/**
+ * Render webcam as ASCII art
+ */
+export declare function webcam(container: string | HTMLElement, options?: VideoOptions): Promise<{
+    stop: () => void;
+    update: (opts?: VideoOptions) => void;
+}>;