asciify-engine 1.2.0 → 1.4.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.2.0"
-  updated: "2026-09-08"
+  tested-engine: "1.4.0"
+  updated: "2026-09-09"
 ---
 
 # Asciify Engine
 
-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.
+Use the published `asciify-engine` npm package for browser canvas rendering. Tested against **1.4.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,7 +16,7 @@ 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.2.0
+npm install asciify-engine@latest
 ```
 
 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.
@@ -27,7 +27,7 @@ Version 1.2.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
 
@@ -125,4 +125,13 @@ 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.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.
+Do not import nonexistent helpers such as `createRecorder` or `recordAndDownload` from 1.2.0. For deterministic composition export in 1.4.0+, use `/studio` as described below. For recording an existing interactive canvas, use a browser `MediaRecorder` with a supported `canvas.captureStream()` format and clean up its tracks; for snapshots, inspect the published `captureSnapshot` / `snapshotAndDownload` types.
+
+
+## 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).
+
+## Studio composition and export
+
+For optional wallpaper/backdrops, alternate renderers, palettes, masks, saved looks, text fonts, or deterministic MP4/GIF export, read [references/studio-workspace.md](references/studio-workspace.md). The new `/studio` API is separate from `/hover` and `AsciiOptions`; do not replace an existing hero pipeline just to add a backdrop. Use version 1.4.0 or newer for these APIs after verifying the installed package.

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

@@ -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/studio-effects.md

@@ -55,3 +55,8 @@ The module observes reduced motion and visibility. Coordinate explicit pause wit
 `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/studio-workspace.md

@@ -0,0 +1,92 @@
+# Optional Studio composition API
+
+Use `asciify-engine/studio` (introduced in 1.4.0) when the task needs saved looks, alternate render styles, crop/masks, backdrops, or deterministic video export. Keep `/core` and `/hover` for existing ASCII integrations and layered interactive heroes; those defaults and entry points are unchanged. Studio settings are a separate schema, not `AsciiOptions`.
+
+## Mount, update, destroy
+
+```ts
+import { mountStudio, studioLook } from 'asciify-engine/studio';
+
+const abort = new AbortController();
+const studio = await mountStudio(canvas, '/media/your-video.mp4', {
+  settings: studioLook('wallpaper'),
+  maxDimension: 960,
+  maxCells: 12000,
+  signal: abort.signal,
+  onError: error => console.error(error),
+});
+
+// Updates merge nested option groups. Arrays replace their previous contents.
+studio.update({ backdrop: { mode: 'blurred', opacity: 0.45 } });
+studio.update({ hover: { effect: 'water', radius: 0.35 } });
+studio.pause(true);
+await studio.seek(1.5);
+// Cleanup when the view unmounts:
+studio.destroy();
+```
+
+Keep complete settings in application state. Apply edits with `updateStudioSettings(settings, patch)` and pass that state to `studio.update`; the mounted instance does not expose a settings getter. Serialize your application state when saving a look.
+
+In React, create the AbortController inside the effect. On cleanup, abort and destroy the returned instance; if setup resolves after disposal, immediately destroy that instance. Do not remount for slider changes: call `update`. The mount owns its loaded media. `mountStudioMedia` takes ownership of an already loaded `StudioMedia`. Use an independent media instance for export.
+
+Sources are local `File` objects or permitted image/video/GIF URLs. Remote servers must permit canvas CORS access. No media is uploaded by this API. A YouTube page or iframe is not a pixel source. HEIC browser decoding is not universal; convert it to PNG/JPG before this optional API.
+
+## Settings and looks
+
+Start with `normalizeStudioSettings({ ... })`, `DEFAULT_STUDIO_SETTINGS`, or `studioLook(id)`. Enumerate `STUDIO_STYLES`, `DITHER_ALGORITHMS`, `STUDIO_PALETTES`, `STUDIO_LOOKS`, and `STUDIO_TEXT_FONTS` rather than guessing IDs. Partial mounts and `update` accept `StudioInput`; complete state is `StudioSettings`.
+
+- `style`: ASCII and character shapes, dots, pixel, mosaic, LEGO-like studded cells (`lego`), isometric tiles (`voxel`), faceted tiles (`disco`), or `dither`. These are canvas treatments, not editable 3D scenes.
+- `charset`, `cellSize`, `colorMode` (`accent`, `source`, `gray`), `ink`: rendering choices. Character density is bounded by the working-size and cell budgets.
+- `aspectRatio`: `original`, `16:9`, `9:16`, `1:1`, `4:3`, `3:4`, `21:9`. `studioDimensions` resolves dimensions from the source and rotation.
+- `crop`: normalized `x`/`y` anchor, `zoom` 1–5, rotation in 90-degree steps. Cover framing fills the output.
+- `backdrop`: `solid`, `transparent`, `source`, `blurred`, or `gradient`; `color`, `color2`, `opacity`, `blur`. A wallpaper look is an opt-in composition, not an operating-system wallpaper installer.
+- `color`: brightness, contrast, saturation, grayscale, tint amount/color and blend mode. Tint and lights retain the artwork alpha rather than filling empty glyph cells.
+- `dither`: algorithm, palette/custom colors, amount, scale, threshold, pattern motion (`none`, `drift`, `shimmer`) and speed. Diffusion and ordered patterns differ; animated thresholds can shimmer intentionally.
+- `mask`: enable/invert and a list of rectangle, ellipse, or brush shapes. Coordinates are normalized to the output canvas. Masks are bounded to 64 shapes and 2,048 total brush points. Masking affects the artwork; the backdrop remains visible.
+- `lights`: at most four colored radial lights with normalized position, radius, and intensity. This is 2D illumination, not physically based material lighting.
+- `effects`: independent character bloom and whole-composition bloom, prism, grain, dust, scanlines, CRT, vignette, glitch, pixelation, halftone, and Gaussian/directional/radial/progressive blur. Optical effects use an optional WebGL pass. Check `capabilities.gpuFinish` after an effect renders; unavailable GPU effects must not be described as applied.
+- `hover`: Trail, Water, Contour, Dissolve, Silk, Vortex, or none; strength, normalized radius, optional `edgeSafe`. Hover is live interaction; it is not recorded into offline exports.
+
+`serializeStudioSettings` and `parseStudioSettings` round-trip validated, versioned state. Media URLs/files are excluded. Unknown fields are discarded, values are bounded, future schema versions and oversized imports are rejected. Share source files separately. `restyleStudio` chooses another curated look while preserving crop, ratio, and mask.
+
+## Export the same composition
+
+Exports render explicit frames with encoder backpressure, using a separate renderer. This avoids dropped frames from screen recording and leaves the live preview alone.
+
+```ts
+import { loadStudioMedia, exportStudio } from 'asciify-engine/studio';
+
+const cancellation = new AbortController();
+const media = await loadStudioMedia(file, cancellation.signal);
+try {
+  const blob = await exportStudio({
+    frame: async (time, signal) => {
+      await media.seek(time, signal);
+      return media.frame(time);
+    },
+  }, settings, {
+    format: 'mp4', width: 1280, height: 720,
+    referenceWidth: 640, // width of the preview: keeps the same cell density at 2×
+    duration: 8, fps: 24,
+    signal: cancellation.signal,
+    onProgress: progress => console.log(progress),
+  });
+  // Download or otherwise use this Blob in your application.
+} finally {
+  media.destroy();
+}
+```
+
+Formats: PNG, JPG (`jpeg`), GIF, MP4/H.264, WebM/VP9. MP4/WebM require a compatible WebCodecs encoder; errors describe unavailable encoding instead of silently changing formats. Choose even dimensions for MP4. Videos are silent. Pointer trails belong in the live integration; offline frames contain the source and chosen motion/effects. PNG retains alpha; opaque formats flatten it. GIF timing uses hundredths of a second, distributing rounding across frames.
+
+Bounds: 4096 pixels per side and 16 megapixels for stills; video at most 3840×2160 pixels in total, 60 seconds, 60 fps; GIF at most 1280×720 pixels and 600 frames at up to 30 fps. Large exports take time and memory. Use MP4 for longer animation. Cancel with AbortController. `referenceWidth` preserves preview character density when increasing export dimensions; `maxCells` controls the render budget separately.
+
+## Text
+
+`createStudioText(text, font)` lazily loads the selected FIGlet font and returns `{ canvas, ascii }`. Copy `ascii` for plain text or use `canvas` as a source for visual treatments and animation. These are FIGlet letterforms, not a replacement for readable HTML headings or a promise that every imported browser font is supported. Font data and encoding libraries load only when used; they are outside `/core` and `/hover`.
+
+## Performance and lower-level rendering
+
+`createStudioRenderer(canvas, settings, limits)` exposes `render(source, time, width, height)`, `configure`, `pointer`, `leave`, `invalidate`, and `destroy` for applications owning their own loop. Call `invalidate` when a canvas source changes in place; source identity alone does not indicate new pixels. Use an increasing time in seconds; pointer timestamps are milliseconds.
+
+`mountStudio` pauses when hidden/offscreen and respects reduced motion. Still scenes sleep when their interaction settles. Video sampling caches decoded frames independently of display-rate pointer animation. Adaptive preview reduces its cell budget when sustained render cost is high; disable with `adaptive: false` for fixed measurement. It does not change saved settings or the standard ASCII editor. Exports use their own explicit budget. Measure sustained behavior on real target devices; no renderer can guarantee 60 fps on every device with arbitrary effects and density.

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

@@ -0,0 +1,29 @@
+# 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.
+
+Version 1.4.0 adds the optional `/studio` composition and export API. Its settings are separate from `AsciiOptions`; existing `/core` and `/hover` integrations keep their behavior. Read [studio-workspace.md](studio-workspace.md) only when adding these tools.
+
+## 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.