lascii 1.0.0

package/CHANGELOG.md

@@ -0,0 +1,21 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [1.0.0] - 2026-05-27
+
+### Added
+
+- Initial public release of `lascii`.
+- `LasciiTextEffect` — scramble/reveal text with optional phrase looping (`|:|` separator).
+- `LasciiImageEffect` — ASCII canvas animation with staggered cell reveal and image fade-in.
+- DOM adapter with `data-lascii-text` and `data-lascii-image` attributes.
+- Auto-initialization on `DOMContentLoaded` when importing `lascii` or `lascii/dom`.
+- Subpath exports: `lascii/dom`, `lascii/core/text`, `lascii/core/image`.
+- TypeScript declaration files for all public entry points.
+- Documentation: README, API reference, contributing and security policies.
+
+[1.0.0]: https://github.com/whosramoss/lascii/releases/tag/v1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 lascii
+
+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,90 @@
+<h1>
+  <p align="center">
+    <img src="https://lascii.whosramoss.com/icons/android-chrome-512x512.png" alt="logo" width="128">
+    <br>LASCII
+  </p>
+</h1>
+
+<p align="center">
+ Lightweight ASCII animation effects for the web. Transform images and text into living character art.
+  <br /> <br />
+  <a href="#how-to-install">Install</a>
+  ·
+  <a href="#usage">Usage</a>
+  ·
+  <a href="#effects">Effects</a>
+</p>
+
+<p align="center">
+  <a href="https://lascii.whosramoss.com">Live demo</a>
+</p>
+
+## How to install
+
+```bash
+npm install lascii
+```
+
+## Usage
+
+Add `data-lascii-text` or `data-lascii-image` attributes to your elements and import the module:
+
+```html
+<script type="module">
+  import "lascii";
+</script>
+
+<p data-lascii-text>Hello World</p>
+<p data-lascii-text>First|:|Second|:|Third</p>
+
+<div style="position: relative; aspect-ratio: 4/5; overflow: hidden;">
+  <img data-lascii-image src="photo.jpg" alt="photo" />
+</div>
+```
+
+The effect auto-initializes on DOM ready. No configuration needed.
+
+## Effects
+
+### Text effect
+
+| Feature       | How                                                  |
+| ------------- | ---------------------------------------------------- |
+| Single reveal | `<p data-lascii-text>Hello</p>`                      |
+| Loop phrases  | Separate with `\|:\|` — `First\|:\|Second\|:\|Third` |
+
+### Image effect
+
+Wrap an `<img>` with `data-lascii-image` inside a positioned container with `overflow: hidden`. The effect samples the image, renders an ASCII canvas animation, then fades to the original.
+
+### Configuration
+
+By default, `import "lascii"` runs `init()` on DOM ready and uses built-in defaults. To customize behavior, import the effect classes, pass an options object to the constructor (merged over `DEFAULTS`), and wire elements yourself.
+
+See the **[API reference](./docs/API.md)** for all options, exports, and TypeScript types.
+
+### Manual setup
+
+```js
+import LasciiTextEffect from "lascii/core/text";
+import LasciiImageEffect from "lascii/core/image";
+
+document.querySelectorAll("[data-lascii-image]").forEach((img, index) => {
+  new LasciiImageEffect(img, index, { SCRAMBLE_COUNT: 20 });
+});
+
+new LasciiTextEffect(document.querySelector(".headline"), {
+  phraseDelay: 1200,
+  revealOrigin: LasciiTextEffect.RevealOrigin.MIDDLE,
+});
+```
+
+For auto-init without importing the main entry (side effects), use subpath imports from `lascii/core/*` and call `LasciiTextEffect.init()` / `LasciiImageEffect.init()` — details in [API](./docs/API.md).
+
+## TypeScript
+
+Declaration files ship with the package. No separate `@types` package required.
+
+```ts
+import { LasciiTextEffect, LasciiImageEffect } from "lascii";
+```

package/docs/API.md

@@ -0,0 +1,250 @@
+# API Reference
+
+## Package entry points
+
+| Import | Description |
+| ------ | ----------- |
+| `lascii` | Main entry. Auto-initializes on `DOMContentLoaded` via `autoInitDom()`. |
+| `lascii/dom` | Same exports as main, but scoped to the DOM adapter (also auto-inits on import). |
+| `lascii/core/text` | `LasciiTextEffect` only (no auto-init). |
+| `lascii/core/image` | `LasciiImageEffect` only (no auto-init). |
+
+Use `lascii/core/*` when you want full control and no side effects on import.
+
+---
+
+## `lascii` exports
+
+```ts
+import lascii, {
+  LasciiTextEffect,
+  LasciiImageEffect,
+  init,
+  autoInitDom,
+} from "lascii";
+```
+
+| Export | Type | Description |
+| ------ | ---- | ----------- |
+| `LasciiTextEffect` | `class` | Scramble/reveal text animation. |
+| `LasciiImageEffect` | `class` | ASCII canvas reveal for images. |
+| `init` | `function` | Scans the DOM and starts effects (`initDom`). |
+| `autoInitDom` | `function` | Registers `init` on `DOMContentLoaded`, or runs immediately if the document is ready. |
+| `default` | `object` | `{ LasciiTextEffect, LasciiImageEffect, init, autoInitDom }`. |
+
+### `init()` / `autoInitDom()`
+
+`init()` (alias of `initDom`) runs:
+
+- `LasciiImageEffect.init("[data-lascii-image]")`
+- `LasciiTextEffect.init("[data-lascii-text]")`
+
+`autoInitDom()` calls `init()` when the document is ready.
+
+To avoid auto-init on import, use subpath imports:
+
+```js
+import { LasciiTextEffect } from "lascii/core/text";
+import { LasciiImageEffect } from "lascii/core/image";
+```
+
+---
+
+## Data attributes
+
+| Attribute | Element | Behavior |
+| --------- | ------- | -------- |
+| `data-lascii-text` | Any text container | Reads `textContent`, runs text scramble effect. |
+| `data-lascii-image` | `<img>` | Samples image, ASCII animation, then fades to original. |
+
+### Text: phrase separator
+
+Multiple phrases in one element are separated by `|:|` (configurable via `separator`):
+
+```html
+<p data-lascii-text>First|:|Second|:|Third</p>
+```
+
+When the separator is present, phrases loop with `phraseDelay` between transitions.
+
+### Image: layout requirements
+
+Place the image inside a **positioned** wrapper with **overflow hidden** and a defined aspect ratio (e.g. `aspect-ratio: 4/5`):
+
+```html
+<div style="position: relative; aspect-ratio: 4/5; overflow: hidden;">
+  <img data-lascii-image src="photo.jpg" alt="photo" />
+</div>
+```
+
+Cross-origin images need CORS headers on the image server (`crossOrigin = "anonymous"` is set internally).
+
+---
+
+## `LasciiTextEffect`
+
+```js
+import { LasciiTextEffect } from "lascii";
+// or
+import LasciiTextEffect from "lascii/core/text";
+```
+
+### Constructor
+
+```js
+new LasciiTextEffect(element, options?)
+```
+
+- **element** — DOM node whose `textContent` is the source string.
+- **options** — Partial override of `LasciiTextEffect.DEFAULTS`.
+
+On construction, the element’s text is cleared and the animation starts.
+
+### Static members
+
+#### `LasciiTextEffect.RevealOrigin`
+
+| Key | Value | Effect |
+| --- | ----- | ------ |
+| `START` | `"start"` | Reveal progresses from the start of the string. |
+| `MIDDLE` | `"middle"` | Reveal radiates from the center outward. |
+
+#### `LasciiTextEffect.DEFAULTS`
+
+| Option | Type | Default | Description |
+| ------ | ---- | ------- | ----------- |
+| `introChars` | `string` | `"█▓▒░x92"` | Character sequence shown at the start of each cell’s scramble. |
+| `introPhaseFrames` | `number` | `10` | Frames to step through `introChars` before random chars. |
+| `chars` | `string` | `"!<>-_\\/[]{}—=+*^?#________"` | Pool of random scramble characters. |
+| `frameStartMax` | `number` | `40` | Max frames before a character begins scrambling (spread along string). |
+| `frameEndMax` | `number` | `40` | Random extra scramble length cap per character. |
+| `randomCharChance` | `number` | `0.28` | Probability of picking a new random char each frame. |
+| `phraseDelay` | `number` | `800` | Ms between phrases when looping (`|:|`). |
+| `separator` | `string` | `"\|:|"` | Delimiter between phrases in `textContent`. |
+| `revealOrigin` | `string` | `"start"` | `"start"` or `"middle"` (`RevealOrigin`). |
+
+Scramble characters are rendered in `<span class="dud">` — style `.dud` in your CSS if needed.
+
+### Instance methods
+
+| Method | Returns | Description |
+| ------ | ------- | ----------- |
+| `setText(newText)` | `Promise<void>` | Animates from current text to `newText`. Resolves when complete (3s safety timeout). |
+
+### Static methods
+
+```js
+LasciiTextEffect.init(selector = "[data-lascii-text]")
+```
+
+Creates one `LasciiTextEffect` per matching element.
+
+### Example
+
+```js
+const effect = new LasciiTextEffect(document.querySelector(".headline"), {
+  phraseDelay: 1200,
+  revealOrigin: LasciiTextEffect.RevealOrigin.MIDDLE,
+});
+
+await effect.setText("Updated copy");
+```
+
+---
+
+## `LasciiImageEffect`
+
+```js
+import { LasciiImageEffect } from "lascii";
+// or
+import LasciiImageEffect from "lascii/core/image";
+```
+
+### Constructor
+
+```js
+new LasciiImageEffect(img, index = 0, options?)
+```
+
+- **img** — `<img>` element. Opacity is set to `0` until reveal; a canvas is appended to the parent.
+- **index** — Stagger index: delay = `index * IMAGE_STAGGER_MS`.
+- **options** — Partial override of `LasciiImageEffect.DEFAULTS`.
+
+### `LasciiImageEffect.DEFAULTS`
+
+| Option | Type | Default | Description |
+| ------ | ---- | ------- | ----------- |
+| `ASCII_CHARS` | `string` | `" . . . . . . :::=+xX#0369"` | Light-to-dark character ramp for luminance mapping. |
+| `FONT_SIZE` | `number` | `40` | Monospace font size used for measurement and drawing. |
+| `ASPECT_WIDTH` | `number` | `4` | Target crop aspect (width). |
+| `ASPECT_HEIGHT` | `number` | `5` | Target crop aspect (height). |
+| `ASCII_COLUMNS` | `number` | `25` | Minimum column count (may increase with container width). |
+| `MAX_ASCII_COLUMNS` | `number` | `96` | Upper cap when scaling to container width. |
+| `TARGET_CELL_CSS_PX` | `number` | `9` | Target cell size in CSS pixels for column scaling. |
+| `IMAGE_STAGGER_MS` | `number` | `100` | Delay multiplier per image `index`. |
+| `CELL_APPEAR_MS` | `number` | `0.5` | Delay between starting each cell animation. |
+| `SCRAMBLE_COUNT` | `number` | `10` | Scramble frames for “dense” (dark) cells. |
+| `SCRAMBLE_SPEED_MS` | `number` | `50` | Interval between scramble frame updates. |
+| `REVEAL_DELAY_MS` | `number` | `0` | Delay before fading canvas out and showing the image. |
+| `BACKGROUND_COLOR` | `string` | `"transparent"` | Canvas cell background. |
+| `TEXT_COLOR` | `string` | `"#c8c8c8"` | ASCII character color. |
+
+Column count is recalculated from the image’s displayed width:  
+`cols = clamp(ASCII_COLUMNS, round(width / TARGET_CELL_CSS_PX), MAX_ASCII_COLUMNS)`.
+
+### Static methods
+
+```js
+LasciiImageEffect.init(selector = "[data-lascii-image]")
+```
+
+Creates one `LasciiImageEffect` per matching image, with `index` from `forEach` order.
+
+### Example
+
+```js
+document.querySelectorAll("[data-lascii-image]").forEach((img, index) => {
+  new LasciiImageEffect(img, index, {
+    SCRAMBLE_COUNT: 20,
+    TEXT_COLOR: "#ffffff",
+  });
+});
+```
+
+---
+
+## Import patterns
+
+### Declarative (auto-init)
+
+```html
+<script type="module">
+  import "lascii";
+</script>
+```
+
+### Manual init (no constructor side effects until you call `init`)
+
+```js
+import { LasciiImageEffect, LasciiTextEffect, init } from "lascii";
+
+// If you imported from "lascii", autoInitDom may already have run.
+// Prefer core/* subpaths to avoid double init:
+
+import LasciiTextEffect from "lascii/core/text";
+import LasciiImageEffect from "lascii/core/image";
+import { initDom } from "lascii/dom"; // note: lascii/dom still auto-inits on import
+
+initDom();
+```
+
+To import DOM helpers without auto-init, import from `initDom` via a future dedicated export or duplicate `initDom` in your bundle by importing only from `lascii/core/*` and calling `.init()` yourself.
+
+### Tree-shaking / side effects
+
+`package.json` marks these as side-effectful:
+
+- `./src/index.js`
+- `./src/adapters/dom/index.js`
+
+Bundlers will not drop them if imported. Use `lascii/core/text` and `lascii/core/image` for side-effect-free imports.

package/package.json

@@ -0,0 +1,57 @@
+{
+  "name": "lascii",
+  "version": "1.0.0",
+  "description": "Lightweight ASCII animation effects for the web",
+  "type": "module",
+  "main": "./src/index.js",
+  "types": "./src/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./src/index.d.ts",
+      "import": "./src/index.js",
+      "default": "./src/index.js"
+    },
+    "./dom": {
+      "types": "./src/adapters/dom/index.d.ts",
+      "import": "./src/adapters/dom/index.js",
+      "default": "./src/adapters/dom/index.js"
+    },
+    "./core/text": {
+      "types": "./src/core/effects/LasciiTextEffect.d.ts",
+      "import": "./src/core/effects/LasciiTextEffect.js",
+      "default": "./src/core/effects/LasciiTextEffect.js"
+    },
+    "./core/image": {
+      "types": "./src/core/effects/LasciiImageEffect.d.ts",
+      "import": "./src/core/effects/LasciiImageEffect.js",
+      "default": "./src/core/effects/LasciiImageEffect.js"
+    }
+  },
+  "sideEffects": [
+    "./src/index.js",
+    "./src/adapters/dom/index.js"
+  ],
+  "files": [
+    "src",
+    "docs",
+    "CHANGELOG.md"
+  ],
+  "keywords": [
+    "ascii",
+    "animation",
+    "effect",
+    "dom",
+    "canvas",
+    "text-effect"
+  ],
+  "license": "MIT",
+  "author": "Gabriel Ramos (https://github.com/whosramoss)",
+  "homepage": "https://lascii.whosramoss.com",
+  "bugs": {
+    "url": "https://github.com/whosramoss/lascii/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/whosramoss/lascii.git"
+  }
+}

package/src/adapters/dom/index.d.ts

@@ -0,0 +1,14 @@
+import LasciiImageEffect from "../../core/effects/LasciiImageEffect.js";
+import LasciiTextEffect from "../../core/effects/LasciiTextEffect.js";
+import { autoInitDom, initDom } from "./initDom.js";
+
+export { LasciiImageEffect, LasciiTextEffect, initDom, autoInitDom };
+
+declare const lasciiDom: {
+  LasciiImageEffect: typeof LasciiImageEffect;
+  LasciiTextEffect: typeof LasciiTextEffect;
+  initDom: typeof initDom;
+  autoInitDom: typeof autoInitDom;
+};
+
+export default lasciiDom;

package/src/adapters/dom/index.js

@@ -0,0 +1,8 @@
+import LasciiImageEffect from "../../core/effects/LasciiImageEffect.js";
+import LasciiTextEffect from "../../core/effects/LasciiTextEffect.js";
+import { autoInitDom, initDom } from "./initDom.js";
+
+autoInitDom();
+
+export { LasciiImageEffect, LasciiTextEffect, initDom, autoInitDom };
+export default { LasciiImageEffect, LasciiTextEffect, initDom, autoInitDom };

package/src/adapters/dom/initDom.d.ts

@@ -0,0 +1,2 @@
+export function initDom(): void;
+export function autoInitDom(): void;

package/src/adapters/dom/initDom.js

@@ -0,0 +1,16 @@
+import LasciiImageEffect from "../../core/effects/LasciiImageEffect.js";
+import LasciiTextEffect from "../../core/effects/LasciiTextEffect.js";
+
+export function initDom() {
+  LasciiImageEffect.init("[data-lascii-image]");
+  LasciiTextEffect.init("[data-lascii-text]");
+}
+
+export function autoInitDom() {
+  if (document.readyState === "loading") {
+    document.addEventListener("DOMContentLoaded", initDom);
+    return;
+  }
+
+  initDom();
+}

package/src/core/effects/LasciiImageEffect.d.ts

@@ -0,0 +1,38 @@
+export interface LasciiImageEffectOptions {
+  ASCII_CHARS?: string;
+  FONT_SIZE?: number;
+  ASPECT_WIDTH?: number;
+  ASPECT_HEIGHT?: number;
+  ASCII_COLUMNS?: number;
+  MAX_ASCII_COLUMNS?: number;
+  TARGET_CELL_CSS_PX?: number;
+  IMAGE_STAGGER_MS?: number;
+  CELL_APPEAR_MS?: number;
+  SCRAMBLE_COUNT?: number;
+  SCRAMBLE_SPEED_MS?: number;
+  REVEAL_DELAY_MS?: number;
+  BACKGROUND_COLOR?: string;
+  TEXT_COLOR?: string;
+}
+
+export interface LasciiImageEffectDefaults
+  extends Required<LasciiImageEffectOptions> {}
+
+declare class LasciiImageEffect {
+  static readonly DEFAULTS: LasciiImageEffectDefaults;
+
+  readonly img: HTMLImageElement;
+  readonly index: number;
+  readonly config: LasciiImageEffectDefaults;
+
+  constructor(
+    img: HTMLImageElement,
+    index?: number,
+    options?: LasciiImageEffectOptions,
+  );
+
+  static init(selector?: string): void;
+}
+
+export default LasciiImageEffect;
+export { LasciiImageEffect };

package/src/core/effects/LasciiImageEffect.js

@@ -0,0 +1,283 @@
+class LasciiImageEffect {
+  static DEFAULTS = {
+    ASCII_CHARS: " . . . . . . :::=+xX#0369",
+    FONT_SIZE: 40,
+    ASPECT_WIDTH: 4,
+    ASPECT_HEIGHT: 5,
+    ASCII_COLUMNS: 25,
+    MAX_ASCII_COLUMNS: 96,
+    TARGET_CELL_CSS_PX: 9,
+    IMAGE_STAGGER_MS: 100,
+    CELL_APPEAR_MS: 0.5,
+    SCRAMBLE_COUNT: 10,
+    SCRAMBLE_SPEED_MS: 50,
+    REVEAL_DELAY_MS: 0,
+    BACKGROUND_COLOR: "transparent",
+    TEXT_COLOR: "#c8c8c8",
+  };
+
+  constructor(img, index = 0, options = {}) {
+    this.img = img;
+    this.img.style.opacity = "0";
+    this.index = index;
+    this.config = { ...LasciiImageEffect.DEFAULTS, ...options };
+    this._minAsciiColumns = this.config.ASCII_COLUMNS;
+    this.canvas = document.createElement("canvas");
+    this.ctx = this.canvas.getContext("2d");
+    this.staggerDelay = this.index * this.config.IMAGE_STAGGER_MS;
+    this.load();
+  }
+
+  applyDisplayScaledColumns() {
+    const rect = this.img.getBoundingClientRect();
+    const width = rect.width;
+    if (width < 8) return;
+    const target = this.config.TARGET_CELL_CSS_PX;
+    const maxCols = this.config.MAX_ASCII_COLUMNS;
+    const cols = Math.min(
+      maxCols,
+      Math.max(this._minAsciiColumns, Math.round(width / target)),
+    );
+    this.config.ASCII_COLUMNS = cols;
+  }
+
+  measureCharacters() {
+    const measureCtx = document.createElement("canvas").getContext("2d");
+    measureCtx.font = `${this.config.FONT_SIZE}px monospace`;
+    this.charWidth = Math.ceil(measureCtx.measureText("M").width);
+    this.charHeight = this.config.FONT_SIZE;
+    this.ASCII_ROWS = Math.round(
+      this.config.ASCII_COLUMNS *
+        (this.config.ASPECT_HEIGHT / this.config.ASPECT_WIDTH) *
+        (this.charWidth / this.charHeight),
+    );
+    this.denseCharIndex = this.config.ASCII_CHARS.lastIndexOf(".");
+    this.denseChars = this.config.ASCII_CHARS.slice(
+      this.denseCharIndex + 1,
+    ).split("");
+  }
+
+  prepareCanvas() {
+    this.canvas.width = this.config.ASCII_COLUMNS * this.charWidth;
+    this.canvas.height = this.ASCII_ROWS * this.charHeight;
+    this.ctx.font = `${this.charHeight}px monospace`;
+    this.ctx.textBaseline = "top";
+  }
+
+  attachCanvas() {
+    const wrapper = this.img.parentElement;
+    if (wrapper) {
+      this.img.style.opacity = "0";
+      this.canvas.style.position = "absolute";
+      this.canvas.style.top = "0";
+      this.canvas.style.left = "0";
+      this.canvas.style.width = "100%";
+      this.canvas.style.height = "100%";
+      this.canvas.style.objectFit = "cover";
+      const computedPosition = getComputedStyle(wrapper).position;
+      if (computedPosition === "static") {
+        wrapper.style.position = "relative";
+      }
+      if (!this.canvas.isConnected) {
+        wrapper.appendChild(this.canvas);
+      }
+    }
+  }
+
+  load() {
+    this.samplingImg = new Image();
+    this.samplingImg.crossOrigin = "anonymous";
+    this.samplingImg.onload = () => {
+      const kickoff = () => {
+        try {
+          this.applyDisplayScaledColumns();
+          this.measureCharacters();
+          this.prepareCanvas();
+          this.attachCanvas();
+          this.start();
+        } catch (error) {
+          this.img.style.opacity = "1";
+          this.canvas.remove();
+        }
+      };
+      requestAnimationFrame(() => {
+        requestAnimationFrame(kickoff);
+      });
+    };
+    this.samplingImg.onerror = () => {
+      this.img.style.opacity = "1";
+      this.canvas.remove();
+    };
+    this.samplingImg.src = this.img.src;
+  }
+
+  start() {
+    const { asciiGrid, brightnessGrid } = this.imageToAsciiGrid();
+    this.animateCells(asciiGrid, brightnessGrid);
+  }
+
+  imageToAsciiGrid() {
+    const img = this.samplingImg;
+    const imageAspect = img.naturalWidth / img.naturalHeight;
+    const itemAspect = this.config.ASPECT_WIDTH / this.config.ASPECT_HEIGHT;
+    let cropX = 0;
+    let cropY = 0;
+    let cropW = img.naturalWidth;
+    let cropH = img.naturalHeight;
+
+    if (imageAspect > itemAspect) {
+      cropW = img.naturalHeight * itemAspect;
+      cropX = (img.naturalWidth - cropW) / 2;
+    } else {
+      cropH = img.naturalWidth / itemAspect;
+      cropY = (img.naturalHeight - cropH) / 2;
+    }
+
+    const samplingCanvas = document.createElement("canvas");
+    const samplingCtx = samplingCanvas.getContext("2d");
+    samplingCanvas.width = this.config.ASCII_COLUMNS;
+    samplingCanvas.height = this.ASCII_ROWS;
+    samplingCtx.drawImage(
+      img,
+      cropX,
+      cropY,
+      cropW,
+      cropH,
+      0,
+      0,
+      this.config.ASCII_COLUMNS,
+      this.ASCII_ROWS,
+    );
+
+    const { data } = samplingCtx.getImageData(
+      0,
+      0,
+      this.config.ASCII_COLUMNS,
+      this.ASCII_ROWS,
+    );
+    const asciiGrid = [];
+    const brightnessGrid = [];
+
+    for (let row = 0; row < this.ASCII_ROWS; row++) {
+      const asciiRow = [];
+      const brightnessRow = [];
+      for (let col = 0; col < this.config.ASCII_COLUMNS; col++) {
+        const pixelIndex = (row * this.config.ASCII_COLUMNS + col) * 4;
+        const brightness =
+          (data[pixelIndex] * 0.299 +
+            data[pixelIndex + 1] * 0.587 +
+            data[pixelIndex + 2] * 0.114) /
+          255;
+        const charIndex = Math.min(
+          this.config.ASCII_CHARS.length - 1,
+          Math.floor((1 - brightness) * this.config.ASCII_CHARS.length),
+        );
+        asciiRow.push(this.config.ASCII_CHARS[charIndex]);
+        brightnessRow.push(charIndex);
+      }
+      asciiGrid.push(asciiRow);
+      brightnessGrid.push(brightnessRow);
+    }
+
+    return { asciiGrid, brightnessGrid };
+  }
+
+  animateCells(asciiGrid, brightnessGrid) {
+    const totalCells = this.config.ASCII_COLUMNS * this.ASCII_ROWS;
+    const scrambleState = new Array(totalCells).fill(null);
+    let settledCount = 0;
+
+    const cellOrder = this.shuffleArray(
+      Array.from({ length: totalCells }, (_, i) => i),
+    );
+
+    cellOrder.forEach((cellIndex, i) => {
+      setTimeout(
+        () => {
+          const row = Math.floor(cellIndex / this.config.ASCII_COLUMNS);
+          const col = cellIndex % this.config.ASCII_COLUMNS;
+          const isDark = brightnessGrid[row][col] > this.denseCharIndex;
+
+          if (!isDark) {
+            this.drawCharacter(col, row, asciiGrid[row][col]);
+            scrambleState[cellIndex] = 0;
+            settledCount++;
+            if (settledCount === totalCells) this.revealImage();
+          } else {
+            scrambleState[cellIndex] = this.config.SCRAMBLE_COUNT;
+          }
+        },
+        this.staggerDelay + i * this.config.CELL_APPEAR_MS,
+      );
+    });
+
+    const scrambleTicker = setInterval(() => {
+      let stillScrambling = false;
+      for (let cellIndex = 0; cellIndex < totalCells; cellIndex++) {
+        const remaining = scrambleState[cellIndex];
+        if (remaining === null || remaining <= 0) continue;
+        stillScrambling = true;
+        const row = Math.floor(cellIndex / this.config.ASCII_COLUMNS);
+        const col = cellIndex % this.config.ASCII_COLUMNS;
+
+        if (remaining === 1) {
+          this.drawCharacter(col, row, asciiGrid[row][col]);
+          scrambleState[cellIndex] = 0;
+          settledCount++;
+          if (settledCount === totalCells) this.revealImage();
+        } else {
+          this.drawCharacter(col, row, this.randomDenseCharacter());
+          scrambleState[cellIndex] = remaining - 1;
+        }
+      }
+      if (!stillScrambling && settledCount === totalCells) {
+        clearInterval(scrambleTicker);
+      }
+    }, this.config.SCRAMBLE_SPEED_MS);
+  }
+
+  drawCharacter(col, row, char) {
+    this.ctx.fillStyle = this.config.BACKGROUND_COLOR;
+    this.ctx.fillRect(
+      col * this.charWidth,
+      row * this.charHeight,
+      this.charWidth,
+      this.charHeight,
+    );
+    this.ctx.fillStyle = this.config.TEXT_COLOR;
+    this.ctx.fillText(char, col * this.charWidth, row * this.charHeight);
+  }
+
+  randomDenseCharacter() {
+    return this.denseChars[Math.floor(Math.random() * this.denseChars.length)];
+  }
+
+  revealImage() {
+    setTimeout(() => {
+      this.canvas.style.transition = "opacity 0.5s ease";
+      this.canvas.style.opacity = "0";
+      this.img.style.transition = "opacity 0.5s ease";
+      this.img.style.opacity = "1";
+      setTimeout(() => {
+        this.canvas.remove();
+      }, 500);
+    }, this.config.REVEAL_DELAY_MS);
+  }
+
+  shuffleArray(array) {
+    for (let i = array.length - 1; i > 0; i--) {
+      const j = Math.floor(Math.random() * (i + 1));
+      [array[i], array[j]] = [array[j], array[i]];
+    }
+    return array;
+  }
+
+  static init(selector = "[data-lascii-image]") {
+    const images = document.querySelectorAll(selector);
+    images.forEach((img, index) => {
+      new LasciiImageEffect(img, index);
+    });
+  }
+}
+
+export default LasciiImageEffect;

package/src/core/effects/LasciiTextEffect.d.ts

@@ -0,0 +1,36 @@
+export type RevealOriginValue = "start" | "middle";
+
+export interface LasciiTextEffectOptions {
+  introChars?: string;
+  introPhaseFrames?: number;
+  chars?: string;
+  frameStartMax?: number;
+  frameEndMax?: number;
+  randomCharChance?: number;
+  phraseDelay?: number;
+  separator?: string;
+  revealOrigin?: RevealOriginValue;
+}
+
+export interface LasciiTextEffectDefaults extends Required<LasciiTextEffectOptions> {}
+
+declare class LasciiTextEffect {
+  static readonly RevealOrigin: Readonly<{
+    readonly START: "start";
+    readonly MIDDLE: "middle";
+  }>;
+
+  static readonly DEFAULTS: LasciiTextEffectDefaults;
+
+  readonly el: HTMLElement;
+  readonly config: LasciiTextEffectDefaults;
+
+  constructor(element: HTMLElement, options?: LasciiTextEffectOptions);
+
+  setText(newText: string): Promise<void>;
+
+  static init(selector?: string): void;
+}
+
+export default LasciiTextEffect;
+export { LasciiTextEffect };

package/src/core/effects/LasciiTextEffect.js

@@ -0,0 +1,185 @@
+class LasciiTextEffect {
+  static RevealOrigin = Object.freeze({
+    START: "start",
+    MIDDLE: "middle",
+  });
+
+  static DEFAULTS = {
+    introChars: "█▓▒░x92",
+    introPhaseFrames: 10,
+    chars: "!<>-_\\/[]{}—=+*^?#________",
+    frameStartMax: 40,
+    frameEndMax: 40,
+    randomCharChance: 0.28,
+    phraseDelay: 800,
+    separator: "|:|",
+    revealOrigin: LasciiTextEffect.RevealOrigin.START,
+  };
+
+  constructor(element, options = {}) {
+    this.el = element;
+    this.config = { ...LasciiTextEffect.DEFAULTS, ...options };
+    this.queue = [];
+    this.frame = 0;
+    this.frameRequest = null;
+    this.resolve = null;
+    this.safetyTimeout = null;
+    this.rawText = this.el.textContent.trim();
+    this.phrases = this.extractPhrases();
+    this.shouldLoop = this.rawText.includes(this.config.separator);
+    this.counter = 0;
+    this.clearInitialText();
+    this.start();
+  }
+
+  extractPhrases() {
+    return this.rawText
+      .split(this.config.separator)
+      .map((text) => text.trim())
+      .filter(Boolean);
+  }
+
+  clearInitialText() {
+    this.el.textContent = "";
+  }
+
+  start() {
+    if (!this.phrases.length) return;
+    if (this.shouldLoop) {
+      this.displayNextPhrase();
+    } else {
+      this.setText(this.phrases[0]);
+    }
+  }
+
+  displayNextPhrase() {
+    const currentPhrase = this.phrases[this.counter];
+    this.setText(currentPhrase).then(() => {
+      setTimeout(() => {
+        this.updateCounter();
+        this.displayNextPhrase();
+      }, this.config.phraseDelay);
+    });
+  }
+
+  updateCounter() {
+    this.counter = (this.counter + 1) % this.phrases.length;
+  }
+
+  setText(newText) {
+    const oldText = this.el.innerText;
+    const length = Math.max(oldText.length, newText.length);
+    const promise = new Promise((resolve) => {
+      this.resolve = resolve;
+    });
+    this.queue = this.buildQueue(oldText, newText, length);
+    this.resetAnimation();
+
+    this.safetyTimeout = setTimeout(() => {
+      if (this.frameRequest) {
+        cancelAnimationFrame(this.frameRequest);
+        this.frameRequest = null;
+        this.el.textContent = newText;
+        this.resolve?.();
+      }
+    }, 3000);
+
+    return promise;
+  }
+
+  buildQueue(oldText, newText, length) {
+    const queue = [];
+    const origin =
+      this.config.revealOrigin ?? LasciiTextEffect.RevealOrigin.START;
+    const cap = this.config.frameStartMax;
+    const scrambleLen = Math.max(
+      1,
+      Math.floor(Math.random() * this.config.frameEndMax),
+    );
+
+    for (let i = 0; i < length; i++) {
+      const from = oldText[i] || "";
+      const to = newText[i] || "";
+      let start = 0;
+
+      if (origin === LasciiTextEffect.RevealOrigin.MIDDLE) {
+        const mid = (length - 1) / 2;
+        const dist = Math.abs(i - mid);
+        const maxDist = Math.max(mid, length - 1 - mid) || 1;
+        start = Math.floor((dist / maxDist) * cap);
+      } else if (length > 1) {
+        start = Math.floor((i / (length - 1)) * cap);
+      }
+
+      const end = start + scrambleLen;
+      queue.push({ from, to, start, end, char: "" });
+    }
+    return queue;
+  }
+
+  resetAnimation() {
+    cancelAnimationFrame(this.frameRequest);
+    this.frame = 0;
+    this.update();
+  }
+
+  update = () => {
+    let output = "";
+    let complete = 0;
+    for (let i = 0; i < this.queue.length; i++) {
+      const item = this.queue[i];
+      const { from, to, start, end } = item;
+      let char = item.char;
+      if (this.frame >= end) {
+        complete++;
+        output += to;
+      } else if (this.frame >= start) {
+        const local = this.frame - start;
+        const intro = this.config.introChars ?? "";
+        const introPhase = this.config.introPhaseFrames ?? 10;
+        if (intro.length && local < introPhase) {
+          const last = intro.length - 1;
+          const idx =
+            last <= 0
+              ? 0
+              : Math.min(
+                  last,
+                  Math.floor((local / Math.max(introPhase - 1, 1)) * last),
+                );
+          char = intro[idx];
+          this.queue[i].char = char;
+        } else if (!char || Math.random() < this.config.randomCharChance) {
+          char = this.randomChar();
+          this.queue[i].char = char;
+        }
+        output += `<span class="dud">${char}</span>`;
+      } else {
+        output += from;
+      }
+    }
+    this.el.innerHTML = output;
+    if (complete === this.queue.length) {
+      this.el.textContent = this.queue.map((item) => item.to).join("");
+      clearTimeout(this.safetyTimeout);
+      this.resolve?.();
+    } else {
+      this.frameRequest = requestAnimationFrame(this.update);
+      this.frame++;
+    }
+  };
+
+  randomChar() {
+    return this.config.chars[
+      Math.floor(Math.random() * this.config.chars.length)
+    ];
+  }
+
+  static init(selector = "[data-lascii-text]") {
+    const elements = document.querySelectorAll(selector);
+    elements.forEach((element) => {
+      new LasciiTextEffect(element);
+    });
+  }
+}
+
+export default LasciiTextEffect;

package/src/index.d.ts

@@ -0,0 +1,15 @@
+import LasciiImageEffect from "./core/effects/LasciiImageEffect.js";
+import LasciiTextEffect from "./core/effects/LasciiTextEffect.js";
+import { autoInitDom, initDom } from "./adapters/dom/initDom.js";
+
+export { LasciiImageEffect, LasciiTextEffect };
+export { initDom as init, autoInitDom };
+
+declare const lascii: {
+  LasciiImageEffect: typeof LasciiImageEffect;
+  LasciiTextEffect: typeof LasciiTextEffect;
+  init: typeof initDom;
+  autoInitDom: typeof autoInitDom;
+};
+
+export default lascii;

package/src/index.js

@@ -0,0 +1,13 @@
+import LasciiImageEffect from "./core/effects/LasciiImageEffect.js";
+import LasciiTextEffect from "./core/effects/LasciiTextEffect.js";
+import { autoInitDom, initDom } from "./adapters/dom/initDom.js";
+
+autoInitDom();
+
+export { LasciiImageEffect, LasciiTextEffect, initDom as init, autoInitDom };
+export default {
+  LasciiImageEffect,
+  LasciiTextEffect,
+  init: initDom,
+  autoInitDom,
+};