asciify-engine 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 ayangabryl
+
+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,204 @@
+# asciify-engine
+
+Framework-agnostic ASCII art engine. Convert images, videos, and GIFs into ASCII art rendered on HTML canvas.
+
+## Features
+
+- **Image → ASCII** — single-frame conversion
+- **Video → ASCII** — extract frames from `<video>` elements
+- **GIF → ASCII** — parse and convert animated GIFs
+- **Canvas rendering** — render ASCII frames to any `<canvas>`
+- **6 art styles** — Classic, Particles, Letters, Box Drawing, Dense Art, Terminal
+- **Color modes** — Grayscale, Full Color, Matrix, Accent
+- **Hover effects** — Spotlight, Magnify, Repel, Glow, Color Shift
+- **Embed code generation** — self-contained HTML output
+- **Zero framework dependencies** — works with React, Angular, Vue, Svelte, vanilla JS
+
+## Install
+
+```bash
+npm install asciify-engine
+```
+
+## Quick Start
+
+### Vanilla JS
+
+```html
+<canvas id="ascii" width="800" height="600"></canvas>
+<script type="module">
+  import {
+    imageToAsciiFrame,
+    renderFrameToCanvas,
+    DEFAULT_OPTIONS,
+    ART_STYLE_PRESETS,
+  } from 'asciify-engine';
+
+  const img = new Image();
+  img.crossOrigin = 'anonymous';
+  img.src = 'https://picsum.photos/600/400';
+  img.onload = () => {
+    const canvas = document.getElementById('ascii');
+    const options = { ...DEFAULT_OPTIONS, ...ART_STYLE_PRESETS.classic, fontSize: 10 };
+    const cols = Math.floor(canvas.width / options.fontSize);
+    const rows = Math.floor(canvas.height / (options.fontSize * 1.8));
+    const frame = imageToAsciiFrame(img, options, cols, rows);
+    renderFrameToCanvas(canvas.getContext('2d'), frame, options, canvas.width, canvas.height);
+  };
+</script>
+```
+
+### React
+
+```tsx
+import { useEffect, useRef } from 'react';
+import {
+  imageToAsciiFrame,
+  renderFrameToCanvas,
+  DEFAULT_OPTIONS,
+  ART_STYLE_PRESETS,
+  type ArtStyle,
+} from 'asciify-engine';
+
+export function AsciiImage({ src, style = 'classic' }: { src: string; style?: ArtStyle }) {
+  const ref = useRef<HTMLCanvasElement>(null);
+
+  useEffect(() => {
+    const img = new Image();
+    img.crossOrigin = 'anonymous';
+    img.src = src;
+    img.onload = () => {
+      const canvas = ref.current!;
+      const opts = { ...DEFAULT_OPTIONS, ...ART_STYLE_PRESETS[style], fontSize: 10 };
+      const cols = Math.floor(canvas.width / opts.fontSize);
+      const rows = Math.floor(canvas.height / (opts.fontSize * 1.8));
+      const frame = imageToAsciiFrame(img, opts, cols, rows);
+      renderFrameToCanvas(canvas.getContext('2d')!, frame, opts, canvas.width, canvas.height);
+    };
+  }, [src, style]);
+
+  return <canvas ref={ref} width={800} height={600} />;
+}
+```
+
+### Angular
+
+```typescript
+import { Component, ElementRef, Input, ViewChild, AfterViewInit } from '@angular/core';
+import {
+  imageToAsciiFrame,
+  renderFrameToCanvas,
+  DEFAULT_OPTIONS,
+  ART_STYLE_PRESETS,
+} from 'asciify-engine';
+
+@Component({
+  selector: 'app-ascii',
+  template: `<canvas #canvas [width]="800" [height]="600"></canvas>`,
+})
+export class AsciiComponent implements AfterViewInit {
+  @ViewChild('canvas') canvasRef!: ElementRef<HTMLCanvasElement>;
+  @Input() src!: string;
+  @Input() artStyle = 'classic';
+
+  ngAfterViewInit() {
+    const img = new Image();
+    img.crossOrigin = 'anonymous';
+    img.src = this.src;
+    img.onload = () => {
+      const canvas = this.canvasRef.nativeElement;
+      const opts = { ...DEFAULT_OPTIONS, ...ART_STYLE_PRESETS[this.artStyle], fontSize: 10 };
+      const cols = Math.floor(canvas.width / opts.fontSize);
+      const rows = Math.floor(canvas.height / (opts.fontSize * 1.8));
+      const frame = imageToAsciiFrame(img, opts, cols, rows);
+      renderFrameToCanvas(canvas.getContext('2d')!, frame, opts, canvas.width, canvas.height);
+    };
+  }
+}
+```
+
+### GIF Animation
+
+```ts
+import { gifToAsciiFrames, renderFrameToCanvas, DEFAULT_OPTIONS } from 'asciify-engine';
+
+const response = await fetch('https://media.giphy.com/media/ENagATV1Gr9eg/giphy.gif');
+const buffer = await response.arrayBuffer();
+
+const canvas = document.getElementById('ascii') as HTMLCanvasElement;
+const ctx = canvas.getContext('2d')!;
+const options = { ...DEFAULT_OPTIONS, fontSize: 8 };
+const cols = Math.floor(canvas.width / options.fontSize);
+const rows = Math.floor(canvas.height / (options.fontSize * 1.8));
+
+const { frames, fps } = await gifToAsciiFrames(buffer, options, cols, rows);
+
+let i = 0;
+setInterval(() => {
+  renderFrameToCanvas(ctx, frames[i], options, canvas.width, canvas.height);
+  i = (i + 1) % frames.length;
+}, 1000 / fps);
+```
+
+### Video
+
+```ts
+import { videoToAsciiFrames, renderFrameToCanvas, DEFAULT_OPTIONS } from 'asciify-engine';
+
+const video = document.createElement('video');
+video.crossOrigin = 'anonymous';
+video.src = '/my-video.mp4';
+await new Promise((r) => (video.onloadeddata = r));
+
+const options = { ...DEFAULT_OPTIONS, fontSize: 8 };
+const cols = 120;
+const rows = 50;
+const { frames, fps } = await videoToAsciiFrames(video, options, cols, rows, 10, 6);
+
+let i = 0;
+setInterval(() => {
+  const ctx = document.getElementById('ascii').getContext('2d');
+  renderFrameToCanvas(ctx, frames[i], options, 800, 600);
+  i = (i + 1) % frames.length;
+}, 1000 / fps);
+```
+
+## API
+
+### Functions
+
+| Function | Description |
+|---|---|
+| `imageToAsciiFrame(img, options, cols, rows)` | Convert an image element to a single ASCII frame |
+| `renderFrameToCanvas(ctx, frame, options, width, height)` | Render an ASCII frame onto a canvas context |
+| `gifToAsciiFrames(buffer, options, cols, rows, onProgress?)` | Convert a GIF `ArrayBuffer` to animated frames |
+| `videoToAsciiFrames(video, options, cols, rows, fps, maxDuration, onProgress?)` | Convert a `<video>` to animated frames |
+| `generateEmbedCode(frame, options)` | Generate self-contained HTML embed string |
+| `generateAnimatedEmbedCode(frames, options, fps)` | Generate animated HTML embed string |
+
+### Art Styles
+
+| Style | Charset | Color Mode |
+|---|---|---|
+| `classic` | ` .:-=+*#%@` | Grayscale |
+| `particles` | Dots mode | Full Color |
+| `letters` | A-Z a-z | Full Color |
+| `claudeCode` | Box drawing `╔╗╚╝║═...` | Accent |
+| `art` | Dense 70-char set | Full Color |
+| `terminal` | ` .:-=+*#%@` | Matrix green |
+
+### Options
+
+See `AsciiOptions` type for full configuration. Key options:
+
+- `fontSize` — character size in pixels (default: 10)
+- `colorMode` — `'grayscale' | 'fullcolor' | 'matrix' | 'accent'`
+- `renderMode` — `'ascii' | 'dots'`
+- `charset` — character ramp string
+- `brightness` / `contrast` — image adjustments
+- `invert` — invert luminance mapping
+- `hoverEffect` / `hoverStrength` / `hoverRadius` — interactive hover
+
+## License
+
+MIT