asciify-engine 1.0.96 → 1.0.98

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "asciify-engine",
-  "version": "1.0.96",
+  "version": "1.0.98",
   "description": "Framework-agnostic ASCII art engine. Convert images, videos, and GIFs into ASCII art rendered on canvas.",
   "type": "module",
   "main": "./dist/index.cjs",

package/skills/asciify-engine/SKILL.md

@@ -8,7 +8,7 @@ description: Convert images, videos, GIFs, webcam streams, text, and animated ba
 Use this skill for the `asciify-engine` npm package.
 
 **Package:** `asciify-engine`  
-**Current version:** `1.0.96`  
+**Current version:** `1.0.98`  
 **Playground:** https://asciify.org  
 **GitHub:** https://github.com/ayangabryl/asciify-engine
 
@@ -36,7 +36,7 @@ npm install asciify-engine
 For existing apps, install the latest tested version:
 
 ```bash
-npm install asciify-engine@1.0.96
+npm install asciify-engine@1.0.98
 ```
 
 ## Mental Model
@@ -64,15 +64,31 @@ Use legacy object frames only when you need per-cell mutation, dots mode, heavy
 - `gifToAsciiFrames()`
 - `renderFrameToCanvas()`
 
-Use `options.sourceCrop` when the source media has empty edges or needs tighter framing without changing the destination canvas size. Percent values are normalized `0–1` by default. Passing only `height` or only `width` preserves source proportions and centers the crop:
+Use `options.sourceCrop` when the source media has empty edges or needs tighter framing without changing the destination canvas size. Percent values are normalized `0–1` by default. Prefer CSS-like insets for readable framing; the engine preserves source proportions by default and auto-crops the opposite axis:
 
 ```ts
 options: {
-  sourceCrop: { height: 0.7 },
+  sourceCrop: { top: 0.08, bottom: 0.22 },
 }
 ```
 
-Set `x`, `y`, `width`, and `height` together only when manual framing is needed. `sourceCrop` is opt-in; when omitted, the engine samples the full source exactly as older versions did.
+Crop from the sides the same way:
+
+```ts
+options: {
+  sourceCrop: { left: 0.1, right: 0.1 },
+}
+```
+
+Use any side together:
+
+```ts
+options: {
+  sourceCrop: { top: 0.08, right: 0.12, bottom: 0.22, left: 0.12 },
+}
+```
+
+For centered crops, `sourceCrop: { height: 0.7 }` keeps 70% of the source and crops equally from top/bottom plus left/right as needed. Set `preserveAspect: false` only when an exact source window is more important than avoiding stretch. `sourceCrop` is opt-in; when omitted, the engine samples the full source exactly as older versions did.
 
 ## Visual Target
 
@@ -221,15 +237,16 @@ await asciifyVideo(video, canvas, {
   fitTo: hero,
   options: {
     chromaKey: true,
-    sourceCrop: { height: 0.7 },
+    sourceCrop: { top: 0.08, bottom: 0.22 },
   },
 });
 ```
 
 - `sourceCrop` happens before ASCII sampling, so the subject is reframed without changing the canvas box.
 - Default unit is `'percent'`; use values from `0` to `1`.
+- Use `top`, `right`, `bottom`, and `left` for CSS-like side crops.
 - Use `{ unit: 'pixel', x, y, width, height }` for exact media-pixel crops.
-- Keep the crop aspect ratio close to the output aspect ratio when you want zero perceived stretching.
+- Keep `preserveAspect` enabled unless you intentionally want an exact source window that can stretch.
 - For hero videos, crop the source first, then use small layout overlap only if the next section needs to tuck closer.
 
 ### Scroll-Scrub Performance Model