asciify-engine 1.0.97 → 1.0.99

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "asciify-engine",
-  "version": "1.0.97",
+  "version": "1.0.99",
   "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.97`  
+**Current version:** `1.0.99`  
 **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.97
+npm install asciify-engine@1.0.99
 ```
 
 ## Mental Model
@@ -72,8 +72,48 @@ options: {
 }
 ```
 
+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.
 
+Use top-level `asciifyVideo` layout options when the destination needs full-bleed framing. These affect the visible canvas only, not the sampled media:
+
+```ts
+await asciifyVideo('/hero.mp4', canvas, {
+  fitTo: hero,
+  objectFit: 'cover',
+  objectPosition: 'center 62%',
+  scale: 1.06,
+  width: '100%',
+  height: '100%',
+  options: {
+    sourceCrop: { top: 0.08, bottom: 0.14 },
+  },
+});
+```
+
+Mental split:
+
+- `sourceCrop` chooses the source window before ASCII conversion.
+- `objectFit`, `objectPosition`, `scale`, `width`, and `height` place the rendered canvas in the page.
+- Use `objectFit: 'cover'` for full-width/full-bleed heroes.
+- Use `objectFit: 'contain'` for previews where the whole source should remain visible.
+- Use `scale` for gentle overfill instead of CSS width hacks like `110vw`.
+
 ## Visual Target
 
 Good ASCII media should feel intentional, not like a broken video filter.
@@ -123,6 +163,10 @@ Recommended starting point:
 ```ts
 {
   fitTo: hero,
+  objectFit: 'cover',
+  objectPosition: 'center bottom',
+  width: '100%',
+  height: '100%',
   fontSize: 5,
   fps: 60,
   maxRenderDimension: 1280,
@@ -228,8 +272,9 @@ await asciifyVideo(video, canvas, {
 
 - `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