asciify-engine 4.19.0 → 4.21.0

package/dist/{types-CM4452nD.d.ts → types-Bmu4dXdQ.d.ts}

@@ -1,4 +1,4 @@
-import { A as AmbientMotion } from './hover-catalog-D85jh6dR.js';
+import { A as AmbientMotion } from './hover-guide-DKRQPtDO.js';
 
 type ColorMode = 'grayscale' | 'fullcolor' | 'matrix' | 'accent';
 type RenderMode = 'ascii' | 'dots';

package/dist/{types-FkqhgDYx.d.cts → types-Cn3wY-ST.d.cts}

@@ -1,4 +1,4 @@
-import { A as AmbientMotion } from './hover-catalog-D85jh6dR.cjs';
+import { A as AmbientMotion } from './hover-guide-DKRQPtDO.cjs';
 
 type ColorMode = 'grayscale' | 'fullcolor' | 'matrix' | 'accent';
 type RenderMode = 'ascii' | 'dots';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "asciify-engine",
-  "version": "4.19.0",
+  "version": "4.21.0",
   "description": "Framework-agnostic ASCII art engine. Convert images, videos, and GIFs into ASCII art rendered on canvas, or run full-bleed GPU character fields with a fluid cursor wake.",
   "type": "module",
   "main": "./dist/index.cjs",

package/skills/asciify-engine/SKILL.md

@@ -2,13 +2,13 @@
 name: asciify-engine
 description: Apply Asciify the way asciify.org does - ASCII components and backgrounds that belong in a real interface, inked from the theme, clear around text, inside the page's radii and motion. Use for UI components in characters (loading, status, toasts, tabs, AI states, charts, transitions, pages), animated ASCII backgrounds, and also photo, video and GIF conversion, GPU character fields, artwork looks for wallpapers, posters and prints, art styles and export, hover and motion, layered typography and rendering performance.
 metadata:
-  tested-engine: "4.19.0"
+  tested-engine: "4.21.0"
   updated: "2026-10-17"
 ---
 
 # Asciify Engine
 
-Use the published `asciify-engine` npm package. Tested against **4.19.0**. Check the application's installed version and its public types before using newer options; a local checkout can contain unpublished changes.
+Use the published `asciify-engine` npm package. Tested against **4.21.0**. Check the application's installed version and its public types before using newer options; a local checkout can contain unpublished changes.
 
 - Agent entry: https://asciify.org/skill (redirects to this Markdown document).
 - Components: https://asciify.org/components · Looks: https://asciify.org/looks · Backgrounds: https://asciify.org/backgrounds
@@ -36,7 +36,7 @@ Most requests are a feeling ("make the loading state feel alive", "a calm backgr
 | The user wants | Use |
 | --- | --- |
 | A UI component in characters: button loading, status, toasts, tabs, pills, odometer, chart, AI thinking and streaming, transitions, sign-in, pricing, 404 | `asciify-engine/kit` ([applying-asciify.md](references/applying-asciify.md), [components.md](references/components.md), [kit.md](references/kit.md)) |
-| A background behind a hero, pricing, docs or a section, light or dark | Kit `fieldBackground(el, { preset: 'hero', clear })` (asciify.org's hero) or `background(el, { preset, clear })` with one of the 13 curated presets below |
+| A background behind a hero, pricing, docs or a section, light or dark | Kit `fieldBackground(el, { preset: 'hero', clear })` (asciify.org's hero) or `background(el, { preset, clear })` with one of the 12 curated presets below |
 | Their word or brand in characters | Kit `wordmark`, or `background()` with `wordField` |
 | Their video in characters on the page | Kit `asciiVideo` |
 | Their photo, video or GIF converted, optionally answering the cursor | Advanced: `asciify` / `asciifyVideo` / `asciifyGif`, plus `mountHover` from `/hover` |
@@ -57,7 +57,7 @@ const b = beam(card, { palette: 'mono', mode: 'pulse' });
 // On unmount: b.destroy();
 ```
 
-`background()`, its presets, `lazy`, `poster`, `setFieldBudget` and `setGlobalLook` are new in 4.14.0; `halo`, `ripple`, `mesh`, `interference`, `constellation`, `cascade`, the GPU `caustics`, `contour` and `aurora`, and the `mark` option are new in 4.19.0. Check that the installed `asciify-engine/kit` exports them; if not, upgrade ([upgrading.md](references/upgrading.md)).
+`background()`, its presets, `lazy`, `poster`, `setFieldBudget` and `setGlobalLook` are new in 4.14.0; `halo`, `ripple`, `mesh`, `interference`, `constellation`, `cascade`, the GPU `caustics` and `contour`, and the `mark` option are new in 4.19.0. Check that the installed `asciify-engine/kit` exports them; if not, upgrade ([upgrading.md](references/upgrading.md)).
 
 ## Backgrounds
 
@@ -68,9 +68,9 @@ import { background, swell } from 'asciify-engine/kit';
 const bg = background(pricing, { preset: swell, clear: pricingCopy });
 ```
 
-The 13 curated presets, as export → `id` (name), all on the GPU glyph field (WebGL2, sharing the context budget): `swell` (Swell, dots or characters), `drift` (Drift), `halo` (Halo), `caustics` (Caustics), `contour` (Contour), `aurora` (Aurora), `ripple` (Ripple), `mesh` (Mesh), `interference` (Interference), `constellation` (Constellation), `cascade` (Cascade), `wordField` → `field` (Field), `fluid` (Fluid).
+The 12 curated presets, as export → `id` (name), all on the GPU glyph field (WebGL2, sharing the context budget): `swell` (Swell, dots or characters), `drift` (Drift), `halo` (Halo), `caustics` (Caustics), `contour` (Contour), `ripple` (Ripple), `mesh` (Mesh), `interference` (Interference), `constellation` (Constellation), `cascade` (Cascade), `wordField` → `field` (Field), `fluid` (Fluid).
 
-The retired presets (`halftone`, `dna`, `circuit`, `fire`, `grid`, `morph`, `noise`, `pulse`, `rain`, `silk`, `stars`, `terrain`, `veil`, `voidWell`, `wave`, `weave`, `dune`, `etch`, `facet`, `moire`) are still exported and marked `@deprecated` so old code runs; do not reach for them in new work. [kit.md](references/kit.md#backgrounds) maps each to its replacement. `fieldBackground` is separate: its `hero`, `brand` and `notFound` presets are the asciify.org hero ground, the same ground in the brand colour, and the 404.
+The retired presets (`aurora`, `halftone`, `dna`, `circuit`, `fire`, `grid`, `morph`, `noise`, `pulse`, `rain`, `silk`, `stars`, `terrain`, `veil`, `voidWell`, `wave`, `weave`, `dune`, `etch`, `facet`, `moire`) are still exported and marked `@deprecated` so old code runs; do not reach for them in new work. [kit.md](references/kit.md#backgrounds) maps each to its replacement. `fieldBackground` is separate: its `hero`, `brand` and `notFound` presets are the asciify.org hero ground, the same ground in the brand colour, and the 404.
 
 Templates already downloaded from asciify.org/backgrounds (`asciiBackground` from a local `./wave.js`) keep working in apps that ship them, but the site no longer offers them; move those apps to `background()` with the closest preset (kit.md maps each).
 
@@ -153,7 +153,7 @@ Preview it: letter glyph densities differ, so arbitrary words are not automatica
 
 The core `HoverEffect` IDs are `spotlight`, `magnify`, `repel`, `glow`, `colorShift`, `attract`, `shatter`, `trail`, and `glitchText`. Those remain valid APIs, but they are **not identical to the current website's enhanced interactions**.
 
-The website offers **Trail, Water, Contour, Dissolve, Silk, Vortex, Magnetic Pull, Scatter, Emboss, Elastic, Rake, Lens wake, Smudge, Ripple rings, and Off** through an optional studio surface module. Its fourteen still-image motions—Caustics, Slow Current, Reveal & Reform, Sheen, Tidal Rings, Living Grain, Parallax, Woven Flow, Print Shift, Contour Light, Relight, Shimmer, Breeze, Unfold—and fine-dither treatments ship in the same `asciify-engine/hover` module. Use its typed options rather than converting display names into engine `hoverEffect` or `animationStyle` values.
+The website offers **Trail, Dissolve, Contour, Emboss, Ripple rings, Ink bleed, Water, Silk, Vortex, Magnetic Pull, Scatter, Elastic, Lens wake, Smudge, Loupe, Reveal, Repel, Tilt, Heat haze, and Off** through an optional studio surface module, each with `scope: 'all' | 'subject' | 'outside'` to keep it on a cut-out subject or around it (`rake` is retired and plays Silk). Its fourteen still-image motions—Caustics, Slow Current, Reveal & Reform, Sheen, Tidal Rings, Living Grain, Parallax, Woven Flow, Print Shift, Contour Light, Relight, Shimmer, Breeze, Unfold—and fine-dither treatments ship in the same `asciify-engine/hover` module. Use its typed options rather than converting display names into engine `hoverEffect` or `animationStyle` values.
 
 To reproduce those interactions, read [references/studio-effects.md](references/studio-effects.md). Import `mountHover` from `asciify-engine/hover`; no separate download is needed. Keep engine `hoverStrength: 0` and `animationStyle: 'none'` when using it, to avoid applying two effects. Trail is the site's default. Prefer a stationary-grid effect such as Trail or Dissolve when the user wants a wake without spatial displacement.
 

package/skills/asciify-engine/references/applying-asciify.md

@@ -187,7 +187,7 @@ publishButton.addEventListener('click', async () => {
 
 ## 9. Backgrounds
 
-`background(element, { preset })` draws any of the 13 curated presets from asciify.org/backgrounds under the element's content. Choose by surface:
+`background(element, { preset })` draws any of the 12 curated presets from asciify.org/backgrounds under the element's content. Choose by surface:
 
 | Surface | Presets | Notes |
 | --- | --- | --- |
@@ -195,7 +195,7 @@ publishButton.addEventListener('click', async () => {
 | A brand or name moment | `wordField` (id `field`), `fieldBackground` `brand` | Your word in the field; keep copy off its centre. |
 | Art-first hero with little copy | `fluid`, `mesh` | `fluid` is the original Asciify hero, 7px cells at 0.7 opacity; `mesh` is a soft gradient in characters. Not behind reading text. |
 | Quiet texture: section bands, footers, empty states, side panels | `caustics`, `contour`, `interference`, `constellation` | Fine lines, slow. Safe behind text with `clear`. |
-| An ambient or interactive moment | `aurora`, `ripple`, `cascade` | `aurora` sits above the copy; `ripple` drops rings where the pointer moves; `cascade` falls in three depths. Keep them away from forms and body copy. |
+| An ambient or interactive moment | `ripple`, `cascade` | `ripple` drops rings where the pointer moves; `cascade` falls in three depths. Keep them away from forms and body copy. |
 
 Keep them calm:
 

package/skills/asciify-engine/references/components.md

@@ -487,11 +487,11 @@ Prompt:
 ```ts
 import { background, swell } from 'asciify-engine/kit';
 
-// One of 13 presets. Import only the one you use; bg.setPreset(other) cross-fades to another.
+// One of 12 presets. Import only the one you use; bg.setPreset(other) cross-fades to another.
 const bg = background(heroSection, { preset: swell, clear: heroText });
 ```
 
-Any preset from [the kit reference](kit.md#backgrounds) fits the same call: `swell`, `drift`, `halo`, `caustics`, `contour`, `aurora`, `ripple`, `mesh`, `interference`, `constellation`, `cascade`, `wordField` and `fluid`, all on the GPU glyph field. `cursor: false` turns the pointer response off; `swell` takes `mark: 'glyph'` or a `charset` for characters instead of dots. For asciify.org's own hero ground, with the frosted veil and `pulse()`, use `fieldBackground(heroSection, { preset: 'hero', clear: heroText })`.
+Any preset from [the kit reference](kit.md#backgrounds) fits the same call: `swell`, `drift`, `halo`, `caustics`, `contour`, `ripple`, `mesh`, `interference`, `constellation`, `cascade`, `wordField` and `fluid`, all on the GPU glyph field. `cursor: false` turns the pointer response off; `swell` takes `mark: 'glyph'` or a `charset` for characters instead of dots. For asciify.org's own hero ground, with the frosted veil and `pulse()`, use `fieldBackground(heroSection, { preset: 'hero', clear: heroText })`.
 
 ## Advanced: raw field
 

package/skills/asciify-engine/references/design-matching.md

@@ -42,7 +42,7 @@ For an interface component or a background, use `asciify-engine/kit` and follow
 | A calm background for a product page, docs, pricing or SaaS hero, in light or dark | Kit `background(el, { preset: swell, clear })` or `fieldBackground(el, { preset: 'hero', clear })` | Graphite ink, clear zone plus veil. See [applying-asciify.md](applying-asciify.md#9-backgrounds). Raw `mountGlyphField` with `mark: 'dot'` only for a look the kit lacks ([glyph-field.md](glyph-field.md#halftone-for-interfaces-412)). |
 | Art styles (halftone, dither, braille, print, mosaic, LED…), saved looks, backdrops, masks, effects, PNG/MP4/GIF export | `mountStudio` from `/studio` | Studio owns motion, hover and finish. Start from `studioLook(id)` when one of the 12 looks matches the mood. |
 | Several media and text layers in one artwork | `mountStudioProject` from `/studio` | One loop and budget for up to eight layers. See [layered-projects.md](layered-projects.md). |
-| An ambient animated background with no media (rain, stars, waves, aurora…) | Kit `background(el, { preset })` with one of the 26 presets | Import presets by name from `asciify-engine/kit`. See [applying-asciify.md](applying-asciify.md#9-backgrounds) for which suits which surface. |
+| An ambient animated background with no media (rain, stars, waves, aurora…) | Kit `background(el, { preset })` with one of the 12 curated presets | Import presets by name from `asciify-engine/kit`. See [applying-asciify.md](applying-asciify.md#9-backgrounds) for which suits which surface. |
 | A text banner or lettering | `asciifyText` / `renderTextToCanvas` | Plain text output works anywhere; canvas for color. |
 | Headline text visible through the art | Layered HTML, see [layered-hero.md](layered-hero.md) | Real text stays in the DOM. |
 
@@ -66,6 +66,7 @@ Hover choice by intent:
 - **Pure characters, the classic Asciify feel:** Trail. In the wake the characters fold their tone, sparse marks fill in and dense marks open up, then they settle; nothing bends. On `/field` use `hover: 'trail'` with `backdrop: 0` (GPU, 120 fps class); in `/studio` or `/hover` use `hover: { effect: 'trail' }` with a solid backdrop in the page color and `effects.characterBloom: 0`. Both run the same ink field with the same `strength` and `radius`, so the canvas renderer is a faithful fallback.
 - **Subtle but premium, no watery distortion:** field `hover: 'lantern'`. A soft light glides after the pointer and lifts the characters it passes, with a short fading tail. Good near text, on product imagery and on calm brands.
 - **Canvas pipelines (`/hover`, `/studio`):** Trail or Dissolve keep the image still; Water and Ripple are liquid; Magnetic and Scatter are playful; Lens magnifies detail.
+- **Premium, cursor-attached (`/hover`, `/studio`):** Loupe for products and detail, Reveal to show the photograph through the characters, Tilt for covers and posters, Repel for stickers and tiles, Heat haze for neon and dusk, Ink bleed for print and ink looks. For a cut-out or a subject on a plain ground add `scope: 'subject'` (or `'outside'` for an aura around it).
 - **Off:** when the art sits behind body text, in dense UIs, or when the user asks for none.
 
 ## Living or still

package/skills/asciify-engine/references/glyph-field.md

@@ -55,7 +55,7 @@ Size the canvas with CSS (for example `position:absolute; inset:0; width:100%; h
 | `fit`, `focus` | `'cover'`, centre | `focus` moves the cover crop (0–1 on each axis). |
 | `vignette` | `0` | Darkens toward the corners. |
 | `drift`, `speed` | `0`, `1` | Slow ambient sampling drift keeps a still image alive; `speed` scales drift and generated scenes. |
-| `hover` | `'fluid'` | `'fluid'`: an ink-in-water wake that bends the image and swirls the characters. `'lantern'`: a soft light that follows the pointer and lifts characters with no distortion. `'trail'`: the Asciify Trail, the same ink field as the studio's Trail hover: in the wake, sparse characters fill in and dense ones open up, then settle, with no distortion. `'none'`: still under the pointer. `FIELD_HOVERS` lists them with labels. |
+| `hover` | `'fluid'` | `'fluid'`: an ink-in-water wake that bends the image and swirls the characters. `'lantern'`: a soft light that follows the pointer and lifts characters with no distortion. `'trail'`: the Asciify Trail, the same ink field as the studio's Trail hover: in the wake, sparse characters fill in and dense ones open up, then settle, with no distortion. `'loupe'`: a glass loupe glides after the pointer and magnifies the characters it covers through a soft rim. `'reveal'`: under a soft spotlight the characters take the source's own colours (best over a photo in one ink). Loupe and Reveal use the `lantern` radius, strength and follow. `'none'`: still under the pointer. `FIELD_HOVERS` lists them with labels. The field has no `scope`; for a cut-out subject use `/studio` or `/hover`. |
 | `trail` | `{ strength: 0.55, radius: 0.45 }` | Same meaning and defaults as the studio's Trail hover, so a look moves between renderers unchanged. |
 | `lantern` | soft | `radius` (fraction of height), `strength`, `trail` (seconds its tail takes to fade), `follow` (how tightly the light catches the pointer). |
 | `fluid` | on | Settings for the fluid hover; `false` turns it off. `radius` (fraction of height), `force`, `dissipation` (per second; higher settles sooner), `curl` (vorticity: how strongly the wake curls into eddies, 0 is a straight smear), `refraction` (how far the flow bends sampling), `glow` (how strongly the flow lights characters), `resolution` (simulation grid, longest side). |

package/skills/asciify-engine/references/hero-finish.md

@@ -59,6 +59,9 @@ For live video, coordinate the source loop with `animated: true, fps: 30` (or th
 | `colorMode` | `fullcolor` | Match source frame rendering: `fullcolor`, `grayscale`, `accent`, or `matrix`. |
 | `accentColor` | `#888888` | Six-digit hex ink color for `colorMode: 'accent'`. |
 | `effect` | `trail` | Trail transports cached source detail and remaps character density on a fixed grid. Other hover modes retain their own behavior. |
+| `scope` | `all` | `subject` keeps the hover on the subject, `outside` on the ground around it; read from the canvas's transparency or a plain ground. See studio-effects.md. |
+| `decay` | `0.5` | How long the effect lingers after the pointer moves on or leaves, 0–1. |
+| `touch` | `true` | Follow touch drags; scrolling still wins a vertical swipe. |
 
 `createTextMask(host, elements, onChange)` is also exported for custom integrations. Its `read()` returns a cached `{ canvas, revision }`; `invalidate()` refreshes it and `destroy()` releases observers. This helper does not itself draw ASCII.
 

package/skills/asciify-engine/references/kit.md

@@ -502,10 +502,9 @@ Options: `preset` (required), `palette` (one ink or `{ light, dark }`, winning o
 | --- | --- | --- |
 | `swell` | A fine grid swelling in slow rolling waves, quiet in the middle; dots by default, or characters | 10, 1, lantern |
 | `drift` | Characters drifting slowly in broad soft lobes, clear round your content | 11, 1, trail |
-| `halo` | A corona breathing slowly round the middle, its rays turning; the centre stays empty for a headline | 11, 1, lantern |
-| `caustics` | Light focused by moving water: fine bright lines that fold, part and meet | 11, 1, lantern |
+| `halo` | A corona breathing slowly round the middle, shaped to the stage (wide on desktop, tall on a phone); the centre stays empty for a headline | 11, 1, lantern |
+| `caustics` | Light through moving water: soft filaments that interlace and lift a little where they cross | 11, 1, lantern |
 | `contour` | Survey lines over a slowly shifting terrain, one character wide, every fifth an index line | 11, 1, lantern |
-| `aurora` | Curtains of light folding across the top, sharp along their hems | 11, 1, lantern |
 | `ripple` | Still water: drops ring outward here and there; the pointer drops its own (`field.pulse`) | 11, 1, drops |
 | `mesh` | Four soft lights on slow paths, a gradient mesh across the whole ramp | 11, 1, trail |
 | `interference` | Two ring grids from orbiting centres; moiré bands open and close where they cross | 11, 1, lantern |
@@ -514,6 +513,6 @@ Options: `preset` (required), `palette` (one ink or `{ light, dark }`, winning o
 | `wordField` | Your word (`text`) as a flowing field of letters | 13, 1, trail |
 | `fluid` | The original Asciify hero: flowing folds with a wake behind the cursor | 7, 1, wake |
 
-Retired presets are still exported, marked `@deprecated`, so code that imports them keeps running unchanged; they are no longer shown on the site or in these docs. Move to the closest current one: `halftone` → `drift` with `mark: 'dot'` (`cellSize: 14`), `dna` and `voidWell` → `halo`, `circuit` and `stars` → `constellation`, `fire`, `silk` and `veil` → `aurora`, `grid`, `weave` and `moire` → `interference`, `morph` and `noise` → `mesh`, `pulse` → `ripple`, `rain` → `cascade`, `terrain`, `dune` and `etch` → `contour`, `facet` → `caustics`, `wave` → `swell`. The retired canvas presets draw on a 2D canvas and also take `accent` and `dither`.
+Retired presets are still exported, marked `@deprecated`, so code that imports them keeps running unchanged; they are no longer shown on the site or in these docs. Move to the closest current one: `halftone` → `drift` with `mark: 'dot'` (`cellSize: 14`), `dna` and `voidWell` → `halo`, `circuit` and `stars` → `constellation`, `aurora`, `fire`, `silk` and `veil` → `mesh`, `grid`, `weave` and `moire` → `interference`, `morph` and `noise` → `mesh`, `pulse` → `ripple`, `rain` → `cascade`, `terrain`, `dune` and `etch` → `contour`, `facet` → `caustics`, `wave` → `swell`. The retired canvas presets draw on a 2D canvas and also take `accent` and `dither`.
 
 Your own preset is an object with `id`, `name`, `description`, `cellSize`, `speed`, `cursor` and `mount(context)`; `mountCanvas(context, draw)` runs a 2D template with the same clock and pointer as the built-ins.