asciify-engine 1.1.0 → 1.2.0

package/skills/asciify-engine/SKILL.md

@@ -2,13 +2,13 @@
 name: asciify-engine
 description: Build and tune browser ASCII images, video, GIFs, text, and interactive heroes with asciify-engine. Use for media conversion, character and color choices, hover integration, layered HTML typography, scroll-synced video, and rendering performance in apps using this package.
 metadata:
-  tested-engine: "1.1.0"
+  tested-engine: "1.2.0"
   updated: "2026-09-08"
 ---
 
 # Asciify Engine
 
-Use the published `asciify-engine` npm package for browser canvas rendering. Tested against **1.1.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 for browser canvas rendering. Tested against **1.2.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).
 - Playground: https://asciify.org/editor
@@ -16,10 +16,10 @@ Use the published `asciify-engine` npm package for browser canvas rendering. Tes
 - Repository: https://github.com/ayangabryl/asciify-engine
 
 ```sh
-npm install asciify-engine@1.1.0
+npm install asciify-engine@1.2.0
 ```
 
-Version 1.1.0 exports `asciify-engine`, `asciify-engine/core` for media without procedural generators, and `asciify-engine/backgrounds` for optional backgrounds. Root imports remain supported. GIF decoding loads `gifuct-js` when a GIF API is called. Site-internal studio modules are separate.
+Version 1.2.0 exports `asciify-engine`, `asciify-engine/core` for media without procedural generators, and `asciify-engine/backgrounds` for optional backgrounds. Root imports remain supported. GIF decoding loads `gifuct-js` when a GIF API is called. Enhanced website hovers, living-image motion and fine dither are available from the optional `asciify-engine/hover` entry; root and `/core` do not load it.
 
 ## Install the agent skill
 
@@ -87,11 +87,11 @@ Preview it: letter glyph densities differ, so arbitrary words are not automatica
 
 ## Engine effects versus studio effects
 
-The public npm `HoverEffect` IDs in 1.1.0 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 public npm `HoverEffect` IDs in 1.2.0 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, and Off** through an optional studio surface module. Its Living Print, Slow Current, Reveal & Reform, and fine-dither treatments are also site features; do not invent npm options from their display names.
+The website offers **Trail, Water, Contour, Dissolve, Silk, Vortex, and Off** through an optional studio surface module. Its Living Print, Slow Current, Reveal & Reform, 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). The module is downloadable application code. 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.
+To reproduce those interactions, read [references/studio-effects.md](references/studio-effects.md). Import `mountHover` from `asciify-engine/hover` (1.2.0+); 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.
 
 For built-in hover alone, use a supported `options.hoverEffect` and a restrained nonzero `hoverStrength`; validate its behavior instead of promising that it matches the website.
 
@@ -112,7 +112,7 @@ Choose the more conventional arrangement—artwork behind all text—when it imp
 ## Performance and lifecycle
 
 - Reduce processing dimensions and cell count before dropping source playback FPS. Do not default to 60 fps on a 24 fps video.
-- Start video at 24–30 fps with a 720–960px processing cap. More processing pixels do not create detail absent from the source. Version 1.1.0 includes the renderer fixes previously applied by the website; it does not include the optional studio surface module.
+- Start video at 24–30 fps with a 720–960px processing cap. More processing pixels do not create detail absent from the source. Version 1.2.0 includes the renderer fixes previously applied by the website; the enhanced surface module is included through the optional `/hover` import.
 - Keep stable canvas dimensions; resize on layout changes, not on every animation frame.
 - Avoid remounting the renderer on pointer movement or each React render.
 - Pause media offscreen and when the document is hidden. Reduced-motion users should get a still; do not merely hide a playing video with CSS.
@@ -125,4 +125,4 @@ Choose the more conventional arrangement—artwork behind all text—when it imp
 
 Check the actual implementation: readable subject and text, no stretching or unintended empty margins, working pointer and keyboard controls, mobile crop, reduced motion, autoplay failure, and cleanup after navigation. Observe several seconds of motion and an entire loop boundary. State the measured device/settings if reporting FPS; screenshots and recordings alone do not establish performance.
 
-Do not import nonexistent helpers such as `createRecorder` or `recordAndDownload` from 1.1.0. For recording, use a browser `MediaRecorder` with a supported `canvas.captureStream()` format and clean up its tracks; for snapshots, inspect the published `captureSnapshot` / `snapshotAndDownload` types.
+Do not import nonexistent helpers such as `createRecorder` or `recordAndDownload` from 1.2.0. For recording, use a browser `MediaRecorder` with a supported `canvas.captureStream()` format and clean up its tracks; for snapshots, inspect the published `captureSnapshot` / `snapshotAndDownload` types.

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

@@ -1,6 +1,6 @@
 # Layer HTML text through ASCII artwork
 
-Use the companion [HTML](../examples/layered-hero.html), [CSS](../examples/layered-hero.css), and [JavaScript](../examples/layered-hero.js) in a browser app with `asciify-engine@1.1.0` installed. Rename the HTML to `index.html` in a Vite project, and provide `/hero.mp4` plus `/hero-poster.jpg` or change its data attributes. The example starts with `data-render-limit="720"`; set this no larger than the source video's longer dimension. No Asciify site footage or fonts are included.
+Use the companion [HTML](../examples/layered-hero.html), [CSS](../examples/layered-hero.css), and [JavaScript](../examples/layered-hero.js) in a browser app with `asciify-engine@1.2.0` installed. Rename the HTML to `index.html` in a Vite project, and provide `/hero.mp4` plus `/hero-poster.jpg` or change its data attributes. The example starts with `data-render-limit="720"`; set this no larger than the source video's longer dimension. No Asciify site footage or fonts are included.
 
 The script renders a poster before requesting video, respects initial reduced motion, pauses offscreen/hidden video, provides a keyboard-operable Play/Pause button, and returns cleanup synchronously while guarding asynchronous setup. Call it on mount and call its returned function on unmount. It uses the public package without the site's patched renderer or private hero sampler.
 

package/skills/asciify-engine/references/media-api.md

@@ -1,4 +1,4 @@
-# Media API notes — published 1.1.0
+# Media API notes — published 1.2.0
 
 Use installed package types as the authority for exact signatures. Import from `asciify-engine`.
 

package/skills/asciify-engine/references/studio-effects.md

@@ -1,14 +1,14 @@
 # Optional studio surface effects
 
-Use this only when the requested behavior should match the Asciify website's enhanced interactions or living-image treatments. It is application code, separate from the npm engine. It is not required for ordinary ASCII conversion.
+Use this only when the requested behavior should match the Asciify website's enhanced interactions or living-image treatments. It ships with `asciify-engine@1.2.0` and later as an optional entry point. Root and `/core` imports do not load its code.
 
-Download https://asciify.org/background-sources/studio-hover.js into the consuming app (for example, `src/vendor/studio-hover.js`). Keep a reviewed local copy with the project rather than relying on an unversioned runtime import. Source files are available alongside it at https://asciify.org/background-sources/studio-hover.ts.
+Install `npm install asciify-engine`, then import from `asciify-engine/hover`. No extra package or file download is required. For a project without a bundler, the standalone ES module remains available at https://asciify.org/background-sources/studio-hover.js; save it locally and import `mountHover` from that file. Prefer npm for versioned updates and TypeScript types.
 
 After the engine has rendered the source canvas:
 
 ```js
-import { mountStudioHover } from './vendor/studio-hover.js';
-const surface = mountStudioHover(host, canvas, {
+import { mountHover } from 'asciify-engine/hover';
+const surface = mountHover(host, canvas, {
   effect: 'trail',
   strength: 0.55,
   radius: 0.2,
@@ -24,7 +24,7 @@ const surface = mountStudioHover(host, canvas, {
 // On unmount: surface.destroy(); then stop the engine renderer.
 ```
 
-Keep engine `options.hoverStrength: 0` and `animationStyle: 'none'`. Pass the same charset, font size, aspect, dots mode, and custom text used to draw the backing canvas. `animated: true` refreshes the rendered source; it does not play the video itself.
+Keep engine `options.hoverStrength: 0` and `animationStyle: 'none'`. Pass the same charset, font size, aspect, charSpacing, dots mode, and custom text used to draw the backing canvas. `animated: true` refreshes the rendered source; it does not play the video itself.
 
 The positioned host must fit the displayed source canvas. The surface appends a visible overlay canvas and keeps the source for sampling. If using the layered hero, assign the overlay the same artwork stacking level as the source. Do not put the description or links inside a lower stacking context. When a `cover` canvas extends beyond its host, crop it with `overflow: hidden` and check pointer alignment at both edges.
 
@@ -40,12 +40,18 @@ The positioned host must fit the displayed source canvas. The surface appends a
 | `vortex` | Local rotational wake. |
 | `none` | No hover effect. |
 
-These are module IDs, not npm `HoverEffect` values. For example, passing `hoverEffect: 'water'` to the published engine is invalid.
+These are `/hover` module `effect` IDs, not the root engine’s legacy `HoverEffect` values. For example, passing `hoverEffect: 'water'` to the published engine is invalid.
 
 ## Still-image motion and dither
 
 The module's `motion` IDs are `none`, `print` (Living Print), `current` (Slow Current), and `reform` (Reveal & Reform). Keep source-video motion alone unless the user intentionally wants another animation layered onto it. For a still, select one motion and a restrained `motionSpeed`, rather than stacking effects.
 
-For the website's fine-dither treatment, use the module's `fineDither: true` and `ditherStrength` after matching the backing canvas's character settings. This is separate from the published engine's built-in dither behavior. Check a still and a moving scene for flicker before choosing the default.
+For the website's fine-dither treatment, use the module's `fineDither: true` and `ditherStrength` after matching the backing canvas's character settings. This is separate from the core renderer’s built-in dither behavior. Check a still and a moving scene for flicker before choosing the default.
 
 The module observes reduced motion and visibility. Coordinate explicit pause with the underlying media; destroy both on unmount. Verify performance on the actual target device, especially with full-screen dense color video.
+
+## Updates and cleanup
+
+`surface.update({ effect: 'water' })` replaces the effect and clears the previous wake. `surface.invalidate()` uploads a newly drawn still. `surface.canvas` is the visible overlay, useful for layering or snapshots; the supplied canvas remains the source. `surface.destroy()` removes the overlay, listeners and observers and restores the source visibility. Stop the source renderer separately. Reduced motion disables hover and ambient motion; offscreen and hidden surfaces stop scheduling frames. Canvas 2D fallback preserves artwork when WebGL is unavailable, with simpler spatial refraction.
+
+When using the low-level object-frame API, pass `getFrame: () => currentFrame` to preserve exact glyph identities and colors. With canvas-only integrations the module estimates density from sampled ink coverage.