asciify-engine 1.1.0 → 1.3.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"
-  updated: "2026-09-08"
+  tested-engine: "1.3.0"
+  updated: "2026-09-09"
 ---
 
 # 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.3.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@latest
 ```
 
-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
 
@@ -27,7 +27,7 @@ Version 1.1.0 exports `asciify-engine`, `asciify-engine/core` for media without
 npx skills add ayangabryl/asciify-engine --skill asciify-engine
 ```
 
-This uses the Vercel Skills CLI to install the repository skill and its linked resources. Updating the npm dependency alone does not update an already installed skill. Use `npx skills update asciify-engine` to refresh it.
+This uses the Vercel Skills CLI to install the repository skill and its linked resources. The npm dependency and an installed agent skill update separately. When asked to update Asciify or when an integration needs newer options, follow [references/upgrading.md](references/upgrading.md): check npm's current `latest`, update with the project's package manager, then refresh only this skill in its installed scope. Do not treat this document's tested version as permanently latest, or upgrade unrelated skills/dependencies.
 
 ## Choose the integration
 
@@ -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,9 @@ 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.
+
+
+## Unreleased hero finish
+
+Version 1.3.0 adds text-shaped charcoal cutouts (`textMask`), peripheral scanline/fringe control (`edgeEffect`), fixed accent ink, Prism edge softness (`edgeSoftness`), and fixed-grid fluid Trail. These additions ship in **npm 1.3.0**. Upgrade older applications before using them. See the [complete API, layering example, lifecycle, and fallback limits](references/hero-finish.md).

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

@@ -0,0 +1,123 @@
+# Text cutouts, peripheral texture, and physical Trail
+
+**Availability: asciify-engine 1.3.0+.** These additions ship in the optional `/hover` entry. Upgrade projects still using 1.2.0 before using these options. Existing media and hover APIs remain supported.
+
+## Intended result
+
+Keep the headline as accessible HTML. Gray ASCII crosses over it, but the character ink turns charcoal only inside the chosen text shapes. Transparent gaps reveal the yellow headline. A stationary peripheral finish adds small directional fringes and scanline breaks, while the middle remains clear. Trail has local momentum: strokes transport image detail through a fixed character grid, open dense areas, fill sparse ones, then return to the source.
+
+This is a rendering treatment, not a background-color key. It does not change the media's colors or remove regions by color. It does not infer which yellow elements are text: explicitly pass the intended heading elements.
+
+## Integration
+
+Use a host fitted to the source canvas. Keep headline, artwork, and controls in the layer order described in [layered-hero.md](layered-hero.md). For the exact glyph path, pass the current object frame and matching character settings:
+
+```js
+import { DEFAULT_OPTIONS, imageToAsciiFrame, renderFrameToCanvas } from 'asciify-engine/core';
+import { mountHover } from 'asciify-engine/hover';
+
+const options = {
+  ...DEFAULT_OPTIONS,
+  charset: ' .:-=+*#%@',
+  fontSize: 8, charAspect: 0.58,
+  colorMode: 'accent', accentColor: '#888888',
+  normalize: false, hoverStrength: 0, animationStyle: 'none',
+};
+let frame;
+function draw(media) {
+  frame = imageToAsciiFrame(media, options, width, height).frame;
+  renderFrameToCanvas(canvas.getContext('2d'), frame, options, width, height, 0, null);
+}
+draw(image); // Use your loaded image; width/height are the canvas's CSS size.
+const surface = mountHover(host, canvas, {
+  getFrame: () => frame,
+  effect: 'trail', strength: 0.55, radius: 0.45,
+  fontSize: options.fontSize, charAspect: options.charAspect,
+  charset: options.charset,
+  colorMode: 'accent', accentColor: '#888888',
+  textMask: host.querySelector('h1'),
+  filter: 'prism', edgeEffect: 0.95, edgeSoftness: 0.35,
+});
+surface.canvas.style.zIndex = '1';
+surface.canvas.setAttribute('aria-hidden', 'true');
+// After drawing a different still: draw(nextImage); surface.invalidate();
+// On cleanup: surface.destroy();
+```
+
+For live video, coordinate the source loop with `animated: true, fps: 30` (or the source frame rate) and update `frame` when decoding produces a new image. Keep pointer updates independent of the source frame rate. `paused` controls the surface; also pause the video element and its drawing loop.
+
+## Controls
+
+| Option | Default | Behavior |
+| --- | --- | --- |
+| `edgeSafe` | `false` | Opt in to fixed outer Trail rows and softened border displacement. Does not change Prism softness. |
+| `radius` | `0.45` for Trail; `0.2` otherwise | Hover size from `0.1` to `1`. |
+| `textMask` | unset | One HTML element or an array of elements. Darkens ASCII only over their text. `update({ textMask: undefined })` removes it. |
+| `filter` | `prism` (inactive) | `clean`, `signal`, `prism`, or `etch`. Select a treatment independently of the hover effect. |
+| `edgeEffect` | `0` without `filter`; `1` when a filter is selected | Intensity from 0 to 1 on the GPU ASCII glyph path with `getFrame`. `clean` always disables the finish. |
+| `edgeSoftness` | `0` | Prism-only blur/fade at the perimeter, from 0 to 1. The center stays crisp. Ignored by Clean, Signal and Etch. |
+| `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. |
+
+`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.
+
+## Layering, layout, and limitations
+
+- Use normal horizontal HTML headings/labels. The mask is a rasterized helper; the original HTML stays searchable, selectable, and accessible.
+- Plain untransformed Latin text is the supported baseline. Rotated/transformed text, vertical writing, ligatures and complex-script shaping require a dedicated mask implementation. Do not silently promise exact glyph alignment for those cases.
+- Fonts, text changes, and observed resizes invalidate the mask. After an external layout change that moves the heading without resizing it, call `surface.invalidate()`.
+- Keep controls above the artwork at z-index 2 or 3. Do not include buttons in `textMask`. Avoid a positioned/filtered ancestor that traps the headline and CTA in one stacking context.
+- The mask automatically keeps the direct glyph surface transparent between characters. Do not add a solid background to the overlay canvas.
+- The peripheral finish is a GPU enhancement for the glyph path. Canvas fallback keeps text cutouts and fixed-grid source flow; it does not reproduce the full optical finish. Fine dither retains a coverage-based wake.
+
+## Performance and motion
+
+The text mask rebuilds on changes, not on every video frame. It uses a bounded canvas and one cached GPU texture. Peripheral samples stay inside the current glyph tile. Trail uses a fixed-size field and transports cached source metadata through it. The GPU interpolates four small metadata samples before choosing one glyph, replacing the previous four-glyph overlap pass. Glyph positions stay fixed; source sampling is bounded to 2.6% per axis. With `edgeSafe: true`, it eases to zero across the outer rows. There are no DOM particles or growing particle lists.
+
+Reduced motion and paused state stop continuous interaction. The edge finish is stationary, with no random time-based flicker. Validate performance on the target device, viewport, source and maximum intended hover strength. A 30 fps video cannot contain 60 distinct source frames; independently updating hover is what keeps input responsive between decoded frames.
+
+
+### Fluid character Trail (1.3.0+)
+
+Pointer speed controls the impulse width and force. Visible density follows the moving velocity field, with a small deposited-density contribution; it is not simply a painted path. Fast sweeps open a wider clearing that rolls and dissipates after release, while slow sweeps stay restrained. Damping uses elapsed time and the solver advances on every display frame (with bounded substeps for long gaps), including 120 Hz. Each animation frame consumes up to six timestamped pointer samples so fast direction changes retain their path. This does not guarantee a particular FPS on every device. Reversal redirects the flow while older momentum continues. A stationary pointer adds no new force. The grid stays aligned: source detail moves through the cells and their selected glyphs change with the flow. A continuous tonal fold opens dense regions and gives sparse regions more marks. A small, stable per-cell variation breaks the tail into individual marks without random flicker or fading the whole stroke. It does not fade all characters into a translucent brush or add white ink.
+
+Use `effect: 'trail', strength: 0.55, radius: 0.45`. No new option is required. The existing character ramp supplies the available glyphs; order custom character sets from sparse to dense when a tonal ramp is desired. Accent ink stays fixed; full-color input transports its existing colors. Transparent source regions remain transparent. A formerly empty cell may gain a glyph as density changes.
+
+The GPU and Canvas paths share source transport and density mapping. Bilinear interpolation happens in cached metadata before glyph selection, so there is one glyph per destination cell. Outer rows are pinned and the result returns exactly to the resting source after the field settles. Source media conversion and font-atlas generation remain outside pointer-only redraws.
+
+### Character finishes (1.3.0+)
+
+- **Signal:** displaced scanline fragments toward the perimeter; monochrome ink and a sharp center.
+- **Prism:** a soft red/cyan fringe around peripheral characters. The hero defaults to Prism at 95% with 35% edge softness. This deliberately introduces small color separations, even with gray base ink.
+- **Etch:** fine diagonal linework cut into the ink. No color fringe.
+- **Clean:** disables the optical treatment completely.
+
+Use `surface.update({ filter: 'prism', edgeEffect: 0.95, edgeSoftness: 0.35 })`. `edgeSoftness: 0` keeps the sharper fringe; increasing it blends a short blur and gentle fade into the outer characters. It reuses the five Prism samples, and all lookups stay within the glyph tile's three-pixel padding. Modes are stationary: they do not add random flashing or whole-canvas blur. Clean/Etch use one atlas lookup; Signal uses at most two; Prism uses at most five, in the existing draw pass. The center remains unchanged. Canvas fallback, dots, emoji, and non-glyph paths do not reproduce these optical finishes; use Clean there.
+
+The website exposes these in Hero → Customize → Finish and Playground → Effects → Character finish. Hero finish changes reuse converted media. Preview metadata is mapped to the surface API, not a new core conversion filter. PNG snapshots capture the visible finish; text/SVG exports remain character data and do not reproduce the GPU treatment. These features ship in npm 1.3.0.
+
+### Frame pacing and mobile
+
+The playground's old 60 Hz hover gate has been removed. Hover redraws follow requestAnimationFrame; decoded video frames retain their own source cadence. Auto performance estimates the display cadence and normalizes its capacity score, so rendering at 60 on a 120 Hz screen no longer counts as full capacity. Under pressure it trades preview detail for responsiveness. The hero retains its bounded glyph count, 1.5× maximum backing ratio, four-million-pixel cap, cached frame textures, and one in-flight media conversion.
+
+Do not promise a 120 FPS minimum on every mobile device or arbitrary character count. A 60 Hz display cannot display 120 distinct refreshes; browser scheduling, device power/thermal state, GPU cost and decoding also constrain delivery. Validate high-refresh hardware separately from emulated mobile layout. Reduced motion and offscreen/hidden suspension remain in effect. Reference: https://developer.mozilla.org/en-US/docs/Web/API/Window/requestAnimationFrame
+
+### Hero character catalog
+
+Hero → Customize → Character set exposes every preset from the published engine `CHARSETS` catalog, plus the Asciify brand set. Selecting a set clears a custom-letter override; Apply letters modifies only the selected set, and Reset set restores it. Selection works while paused or with reduced motion. The hero remains gray, including emoji silhouettes; these are character ramps, not the playground’s Halftone/Dither rendering modes. Prism at 95% with 35% edge softness is the default hero finish: red/cyan separation with short soft shoulders at the perimeter, a clear center, and no blur on HTML text or controls. The same Prism shader is used by the playground and optional engine hover surface.
+
+The default Trail radius is now `0.45` in the hero, playground preset and optional engine mount. This widens the nominal fluid impulse by about 51% versus `0.2`, while preserving the same strength, bounded flow field. Pass `radius: 0.2` explicitly for the previous narrower reach. Other hover presets keep their existing sizes.
+
+### Motion verification
+
+Test slow sweeps, rapid reversal, stationary recovery and pointer exit. Confirm that destination cells remain aligned, source colors remain intact and the final image equals the resting frame. Profile with recording disabled: 60 FPS is a measured target, not a guarantee for every device or source size. Pause and reduced motion stop continuous interaction.
+
+
+### Hover reach and optional edge protection (1.3.0+)
+
+`mountHover(host, canvas, { effect: 'trail', radius: 0.45, edgeSafe: false })` lets the interaction reach the borders. `edgeSafe` defaults to **false**. Set it to `true` to preserve Trail's outer glyph rows and attenuate Water, Silk and Vortex displacement near the boundary. Source coordinates remain clamped with either setting; this option does not control Prism edge softness or change the fixed Trail glyph grid. Contour and Dissolve already keep glyph positions fixed.
+
+`radius` is normalized from `0.1` (focused) to `1` (expansive). The hero starts at `0.45`; adjust **Customize → Hover → Hover size**. Edge protection is in the same tab. Characters and optical finishes have separate tabs, with state preserved between them. Reset restores size 45% and protection off. Preview hover demonstrates the current effect; it is disabled when motion is paused, reduced, or Off. In the playground these settings are under **Effects → Cursor response → Fine-tune cursor response**. The exported snippet includes the chosen `edgeSafe` value and the minimum package version.
+
+Update a mounted engine instance with `hover.update({ radius: 0.7, edgeSafe: true })`. No media re-conversion is required. A larger radius still uses the same bounded simulation grid, although target-device profiling remains necessary.

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.
 
@@ -43,3 +43,8 @@ Do not paint a solid rectangle behind the ASCII glyphs. A black stage/canvas at
 This example shows portable layering and lifecycle with the published package. It does not claim the exact GPU performance or custom interactions of the Asciify production hero. Match the website's enhanced hover behavior only by intentionally adding the [optional studio module](studio-effects.md). That module adds a canvas and must occupy the same artwork layer, not cover the controls.
 
 For additional custom text in the artwork, change `options.charset` while retaining its tonal symbols. Keep the headline itself in HTML so it remains readable, searchable, selectable, and accessible.
+
+
+## Unreleased hero finish
+
+Version 1.3.0 adds text-shaped charcoal cutouts (`textMask`), peripheral scanline/fringe control (`edgeEffect`), fixed accent ink, Prism edge softness (`edgeSoftness`), and fixed-grid fluid Trail. These additions ship in **npm 1.3.0**. Upgrade older applications before using them. See the [complete API, layering example, lifecycle, and fallback limits](hero-finish.md).

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,23 @@ 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.
+
+
+## Unreleased hero finish
+
+Version 1.3.0 adds text-shaped charcoal cutouts (`textMask`), peripheral scanline/fringe control (`edgeEffect`), fixed accent ink, Prism edge softness (`edgeSoftness`), and fixed-grid fluid Trail. These additions ship in **npm 1.3.0**. Upgrade older applications before using them. See the [complete API, layering example, lifecycle, and fallback limits](hero-finish.md).

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

@@ -0,0 +1,27 @@
+# Update Asciify and its agent skill
+
+Use this when a user asks for the latest package or skill, or a requested feature needs a newer release. Updating npm does not refresh a Vercel Skills CLI installation, and updating a skill does not change the application's runtime dependency.
+
+## Package
+
+1. In the target application, inspect its manifest and lockfile; use that project's existing package manager. Read the installed version (`npm ls asciify-engine --depth=0`, or its package-manager equivalent) and check the registry (`npm view asciify-engine@latest version`). The skill's `tested-engine` is a compatibility checkpoint, not a live registry alias.
+2. When the task authorizes an upgrade, use `npm install asciify-engine@latest`, `pnpm add asciify-engine@latest`, `yarn add asciify-engine@latest`, or `bun add asciify-engine@latest` as appropriate. Preserve the project's exact-version policy and update the matching lockfile. Do not use `npm update` as a substitute when an existing range excludes latest. Never use a sibling `file:` dependency in a consumer release.
+3. Verify the resolved version and installed `asciify-engine/hover` types. Run the application's relevant build/tests and exercise its ASCII media, hover, cleanup and reduced-motion path. Check release notes before crossing a major version; resolve affected integration code rather than claiming the upgrade is automatically compatible.
+
+Version 1.3.0 adds velocity-driven Trail, character finishes (`filter`, `edgeEffect`, `edgeSoftness`), text cutouts (`textMask`) and optional boundary protection (`edgeSafe`, default false). Use `radius` from 0.1 to 1 for hover size. Existing core media APIs remain supported. Read [hero-finish.md](hero-finish.md) for complete examples and limits.
+
+## Installed agent skill
+
+Inspect `npx skills list --json` for project installs or `npx skills list -g --json` for global installs. Refresh this skill in the same scope:
+
+```sh
+# Existing project installation
+npx skills update asciify-engine --project --yes
+
+# Existing global installation
+npx skills update asciify-engine --global --yes
+```
+
+Use the scoped command matching the existing installation. Do not run an unqualified bulk update of every installed skill. If this skill is absent, install it with `npx skills add ayangabryl/asciify-engine --skill asciify-engine` and the appropriate scope/agent flags. Preserve agent selection; do not add `--all` unless requested. Inspect `npx skills --help` if CLI flags differ in the installed version. A manually copied skill can be refreshed from the same repository or the matching npm tarball's `skills/asciify-engine` directory; preserve unrelated files.
+
+After updating, read the installed SKILL.md and its linked references, confirm its source/version and resource links, and report both the resolved npm version and whether the installed skill was refreshed. If an offline/registry/authentication error prevents either step, report the actual partial result; do not silently fall back to an unverified version. These consumer upgrade instructions do not authorize publishing npm packages or deploying a site.