asciify-engine 4.9.0 → 4.10.0

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

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

package/examples/living-image.ts

@@ -0,0 +1,15 @@
+import { STUDIO_ANIMATION_PRESETS } from 'asciify-engine/studio';
+import { createComposition } from './studio-composition.js';
+
+/** A live still-image composition, with settings persistence and independent export. */
+export async function createLivingImage(canvas: HTMLCanvasElement, source: File | string, signal?: AbortSignal) {
+  const composition=await createComposition(canvas,source,signal);
+  function applyAnimation(id: string) {
+    const preset=STUDIO_ANIMATION_PRESETS.find(item=>item.id===id);
+    if(!preset)throw new Error(`Unknown animation preset: ${id}`);
+    // Partial group updates preserve edgeSafe, the art style, source and finish.
+    composition.update({motion:preset.motion,hover:preset.hover});
+  }
+  applyAnimation('quiet-light');
+  return {...composition,applyAnimation};
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "asciify-engine",
-  "version": "4.9.0",
+  "version": "4.10.0",
   "description": "Framework-agnostic ASCII art engine. Convert images, videos, and GIFs into ASCII art rendered on canvas.",
   "type": "module",
   "main": "./dist/index.cjs",
@@ -59,7 +59,8 @@
     "examples/layered-composition.ts",
     "examples/print-composition.ts",
     "THIRD_PARTY.md",
-    "licenses"
+    "licenses",
+    "examples/living-image.ts"
   ],
   "scripts": {
     "build": "tsup",

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: "4.9.0"
+  tested-engine: "4.10.0"
   updated: "2026-10-07"
 ---
 
 # Asciify Engine
 
-Use the published `asciify-engine` npm package for browser canvas rendering. Tested against **4.9.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 **4.10.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
@@ -92,7 +92,7 @@ Preview it: letter glyph densities differ, so arbitrary words are not automatica
 
 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, Magnetic Pull, Scatter, Emboss, Elastic, Rake, and Off** through an optional studio surface module. Its ten still-image motions—Caustics, Slow Current, Reveal & Reform, Sheen, Tidal Rings, Living Grain, Parallax, Woven Flow, Print Shift, Contour Light—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, 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.
 
 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.
 
@@ -157,3 +157,7 @@ From 4.6, Studio adds `color.curves` (RGB, red, green, blue) and optional edge-p
 From 4.7, Studio supports up to eight ordered source warps: Twirl, Pinch, Spherize, Ripple, Zigzag, Shear, Smudge, Polar and Fragment. Build controls from `STUDIO_WARPS`, retain array order, and read [source shaping](references/source-shaping.md) for bounds, alpha/edge policy and cached-map performance. These shape the source; use `motion.type` to bring a still image to life and `hover.effect` for pointer interaction. Keep them independent, with an empty warp stack by default.
 
 From 4.9, optional Studio adds Stipple, Engraving, Crosshatch, Woodblock, Risograph and Pointillism with a shared `print` settings group. Read [print and illustration](references/print-styles.md) for exact controls, light-ink versus dark-ink polarity, still-motion integration and dense-render limits. These are genuine additional render paths; do not substitute dither presets for their IDs.
+
+## Lively images and interaction starting points (4.10)
+
+`STUDIO_ANIMATION_PRESETS` provides six editable motion/hover pairings through `/studio` and `/hover`. Apply `motion` and `hover` to an existing Studio player to keep the source and art style; do not treat the pairings as additional art styles. Read [studio-effects.md](references/studio-effects.md#lively-images-410) for exact new IDs, loop limits and the live component example.

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

@@ -43,6 +43,9 @@ The positioned host must fit the displayed source canvas. The surface appends a
 | `etch` | Signed light-and-shadow impression; the glyph grid stays fixed. |
 | `elastic` | Directional momentum, damped recoil and a return to rest. |
 | `rake` | Alternating strips shear with the pointer, then align again. |
+| `lens` | Smooth local magnification, relaxing when the pointer stops. |
+| `smudge` | Directional source drag with a non-oscillating release. |
+| `ripple` | Expanding signed tonal wave packets; speed-sensitive and fixed-grid. |
 | `none` | No hover effect. |
 
 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.
@@ -75,3 +78,29 @@ For a fixed grid, try Contour Light with Emboss. For continuous spatial movement
 All ambient modes repeat after `12 / speed` seconds. Looping the motion does not guarantee that a source video, film grain, dust, glitch or animated dither has the same boundary. Exported PNG/JPEG captures one frame; MP4/WebM/GIF carries autonomous motion, not live pointer movement. For complete composition export, use `/studio` rather than capturing the hover overlay.
 
 The pointer simulations have bounded storage. Elastic allocates its two velocity buffers only when first selected; idle effects stop. This is not a device-independent FPS promise. Test dense grids, fast reversal and the actual finish stack on the target device.
+
+## Lively images (4.10)
+
+The catalogs contain fourteen active hover effects and fourteen active ambient motions, plus Off for each. New motion IDs are `relight`, `shimmer`, `breeze`, and `unfold`. Relight models midtones with a rotating light field; Shimmer slowly animates source highlights. Both keep geometry stationary. Breeze bends the image with a traveling sway. Unfold closes and opens staggered panels, then holds the complete image. All use deterministic 12-second base cycles; `motion.speed` changes cycle duration, `motion.amount` changes strength. These are local image treatments, not AI-generated scene or subject motion.
+
+`STUDIO_ANIMATION_PRESETS` is exported by `/studio` and `/hover`. Its six entries have `id`, `label`, `description`, `motion: {type,speed,amount}`, and `hover: {effect,radius,strength}`. These are editable combinations, not additional renderer styles. Do not overwrite the rest of a user's settings to apply one:
+
+```ts
+import { mountStudio, STUDIO_ANIMATION_PRESETS } from 'asciify-engine/studio';
+const preset = STUDIO_ANIMATION_PRESETS.find(item => item.id === 'quiet-light')!;
+const player = await mountStudio(canvas, '/photo.webp', {
+  settings: { style: 'ascii', cellSize: 6, motion: preset.motion, hover: preset.hover },
+  maxDimension: 960,
+});
+player.update({ motion: { amount: .6 }, hover: { radius: .55 } });
+// Stop on unmount. Do not mount a second /hover instance on this canvas.
+player.destroy();
+```
+
+For a complete integration with independent PNG/MP4 export, copy the repository's `examples/living-image.ts` and `examples/studio-composition.ts`. Keep their relative import together; these helpers are example application code, not npm exports. Saved Studio state stores the resolved settings, so later catalog edits do not change a saved look.
+
+For `/hover`, the same catalog needs an explicit shape conversion: `surface.update({ motion: preset.motion.type, motionSpeed: preset.motion.speed, effect: preset.hover.effect, radius: preset.hover.radius, strength: preset.hover.strength })`. `/hover` has no `motion.amount` option; use Studio for independently adjustable motion strength. Do not spread the nested Studio groups directly into surface options.
+
+Ripple rings uses at most eight wave packets and a fixed-resolution field. It does not allocate particles per character. Lens and Smudge reuse the existing field; their release integrates elapsed time, not a fixed frame count. Zero strength suppresses hover input; completed wakes sleep. These bounds and tests are not a guaranteed frame rate on every device.
+
+To export a loop of a photo, use duration `12 / speed`. Restrict the speed/duration to your encoder's limits and use a frame count that fits whole cycles. Film grain, dust, glitch, pattern animation and input videos may not loop at that boundary. Pointer paths are not included in offline export. Respect reduced motion and provide pause; do not advertise artificial depth as true scene reconstruction.

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

@@ -182,7 +182,7 @@ Stationary artwork, masks, lights, backdrops and character bloom are cached whil
 
 ## Expanded motion library (4.4)
 
-Use `STUDIO_HOVERS` and `STUDIO_MOTIONS` to show all eleven hovers and ten still-image motions, plus Off, grouped by behavior. New hover IDs are `etch`, `elastic`, `rake`; new motion IDs are `parallax`, `weave`, `print`, `trace`. `hover.radius` and `hover.strength` are independent of `motion.speed` and `motion.amount`. All remain serialized in look links and saved projects. A static photo needs no video input or AI service to animate.
+Use `STUDIO_HOVERS` and `STUDIO_MOTIONS` to show all available hovers and still-image motions, plus Off, grouped by behavior. New hover IDs are `etch`, `elastic`, `rake`; new motion IDs are `parallax`, `weave`, `print`, `trace`. `hover.radius` and `hover.strength` are independent of `motion.speed` and `motion.amount`. All remain serialized in look links and saved projects. A static photo needs no video input or AI service to animate.
 
 Example: `player.update({ motion: { type: 'trace', speed: 1, amount: .7 }, hover: { effect: 'etch', radius: .45, strength: .65 } })`. Tone and character choices remain yours. See [effect behaviors and combinations](studio-effects.md#catalogs-and-useful-combinations-44). Do not run several looping thumbnail canvases just to display this catalog; apply the selected treatment to one shared preview.
 
@@ -247,3 +247,7 @@ const saved = serializeStudioSettings(player.settings);
 ## Print and illustration (4.9)
 
 The catalog adds six print treatments with fine square cells and an optional `print` settings group. See [print-styles.md](print-styles.md) for the mechanisms, controls, polarity, bounded rendering and living-image example. They use the same Studio pipeline, saved settings and exports.
+
+## Animation starting points (4.10)
+
+Fourteen hover responses and fourteen local still-image motions are available through the public catalogs. The editor's Effects panel and layered editor's Motion panel share all choices, independent size/strength/speed controls and six editable starting combinations from `STUDIO_ANIMATION_PRESETS`. See [lively images](studio-effects.md#lively-images-410). Existing defaults stay unchanged; animate a photograph deliberately rather than enabling motion for every upload.

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

@@ -81,3 +81,7 @@ Adds `mountStudioProject`, `mountStudioProjectMedia`, `createStudioProjectRender
 ## 4.9 print rendering
 
 Six additional `STUDIO_STYLES` use optional `print` settings. Existing v1 settings remain valid and ASCII defaults stay unchanged. The print group merges on partial updates. Import the shared catalog and read [print-styles.md](print-styles.md); offer print-specific controls only for those styles. Existing `print` and `riso` look IDs retain their dither behavior. Refresh the npm dependency and installed skill separately.
+
+## 4.10 interaction expansion
+
+Adds `lens`, `smudge`, `ripple` hover and `relight`, `shimmer`, `breeze`, `unfold` ambient motion. No IDs are removed and existing defaults remain. `STUDIO_ANIMATION_PRESETS` is exported by Studio and hover; its nested settings are shaped for `player.update`. Core accepts the new ambient IDs through `animationStyle`, with its existing simpler opacity treatment. Do not pass the new surface hover IDs to core `hoverEffect`. Update the npm dependency and refresh the agent skill separately; older packages do not implement these IDs.