asciify-engine 4.3.0 → 4.4.0

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

@@ -33,18 +33,23 @@ The positioned host must fit the displayed source canvas. The surface appends a
 | Module `effect` | Behavior |
 | --- | --- |
 | `trail` | Density wake with a fading tail; glyph grid remains fixed. |
-| `water` | Local refraction with aligned outer boundaries. |
+| `water` | Local refraction; opt into protected boundaries with `edgeSafe: true`. |
 | `contour` | Expanding ring echoes along the pointer path. |
 | `dissolve` | Fading/reforming density trace with a lingering tail. |
 | `silk` | Directional folds following the stroke. |
 | `vortex` | Local rotational wake. |
+| `magnetic` | Attracts the field toward a stroke, then relaxes. |
+| `scatter` | Spatially varied radial scatter with a decaying wake. |
+| `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. |
 | `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.
 
 ## Still-image motion and dither
 
-The module's `motion` IDs are `none`, `caustics` (traveling light on a fixed grid), `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.
+The module's `motion` IDs are `none`, `caustics` (traveling light on a fixed grid), `current` (Slow Current), `reform` (Reveal & Reform), `sheen` (diagonal light sweep), `tidal` (Tidal Rings), and `grain` (Living Grain). 4.4 adds `parallax` (shallow drift), `weave` (interlaced flow), `print` (staggered row registration), and `trace` (light that follows source-image tonal contours). Sheen, Living Grain and Contour Light keep the grid anchored. Contour Light uses source luminance; pass `getFrame` for exact source tones when layering a surface over an existing canvas. 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 core renderer’s built-in dither behavior. Check a still and a moving scene for flicker before choosing the default.
 
@@ -60,3 +65,13 @@ When using the low-level object-frame API, pass `getFrame: () => currentFrame` t
 ## 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).
+
+## Catalogs and useful combinations (4.4)
+
+Build controls from `STUDIO_HOVERS` and `STUDIO_MOTIONS`, exported by `/studio` and `/hover`. Each entry includes `value`, `label`, `group`, and `description`. Use the `value` as the API ID; “Emboss” is `etch` and “Contour Light” is `trace`. Do not maintain a second hard-coded menu or use the legacy core hover IDs for these interactions.
+
+For a fixed grid, try Contour Light with Emboss. For continuous spatial movement, try Parallax with Elastic. For a fabric-like treatment, try Woven Flow with Rake. These are combinations of two independent settings, not additional art styles. Keep strength restrained until you have checked the source at actual display size.
+
+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.

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

@@ -45,7 +45,7 @@ Start with `normalizeStudioSettings({ ... })`, `DEFAULT_STUDIO_SETTINGS`, or `st
 - `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.
+- `hover`: Trail, Water, Contour, Dissolve, Silk, Vortex, Magnetic Pull, Scatter, 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.
 
@@ -109,7 +109,7 @@ Other renderer styles define their own marks, so character controls only apply t
 
 Use `studioGrid(width, height, settings, maxCells, pixelRatio)` to inspect `minimum`, `cell`, `columns`, `rows`, and `limited` at the actual preview resolution. ASCII/tile renderers use `cellSize`; Dither uses `dither.scale`. Respect the returned minimum in a size picker instead of offering a range that the performance budget silently clamps. Use the same budget and reference width for export to retain density.
 
-For PNG/JPEG, pass `time: player.time` to `exportStudio` to save the selected frame. Default time is zero; animation exports start at zero. Snapshot the time/settings/preview size before asynchronous loading. The editor's Export tab separates Image and Animation, shows validated pixel sizes and keeps website code in an expandable section.
+For PNG/JPEG, pass `time: player.time` and `motionTime: player.motionTime` to `exportStudio` to save the selected frame. Default time is zero; animation exports start at zero. Snapshot the time/settings/preview size before asynchronous loading. The editor's Export tab separates Image and Animation, shows validated pixel sizes and keeps website code in an expandable section.
 
 ## Still-image motion (3.0)
 
@@ -129,7 +129,7 @@ For menus shared with a media hero, import the eight `CHARACTER_SETS` from `asci
 
 ## Fine detail and controls (4.2)
 
-- The style catalog adds `hex` (hexagonal tiles), `led` (circular emitters), and `cmyk` (offset cyan/magenta/yellow/black ink dots on white paper). CMYK uses source channel coverage. These remain in the optional `/studio` entry; `/core` does not import them.
+- The style catalog adds `hex` (hexagonal tiles), `led` (circular emitters), and `cmyk` (offset cyan/magenta/yellow/black ink dots on white paper). CMYK derives channel coverage from the selected color mode and tonal hover/motion. These remain in the optional `/studio` entry; `/core` does not import them.
 - Tile styles accept `cellSize: 1`; glyph styles retain a minimum of 3. Dither uses `dither.scale` from 1 to 12, independent of `cellSize`. Values are logical pixels in the reference frame, not device pixels.
 - `studioGrid(width, height, settings, maxCells, pixelRatio)` reports the actual grid, `minimum`, and `limited`. Explain a limit in the UI rather than presenting a requested 1px value as an actual 1px grid.
 - `maxCells` can be explicitly raised to 1,048,576. Defaults remain bounded. For a 960 × 540 reference, `maxCells: 1048576` allows one-pixel dithering. This is a detail option, not a promise of real-time performance at that density. Larger reference frames can still be limited.
@@ -137,7 +137,7 @@ For menus shared with a media hero, import the eight `CHARACTER_SETS` from `asci
 - New dither algorithms: `vertical-lines`, `diagonal-lines`, `radial`. `lines` remains horizontal; `noise` remains deterministic white noise, not blue noise. New palettes: `gray4`, `gray8`, `rgb8`, `cyberpunk`, `pastel`.
 - `dither.colorSpace` is `rgb` (nearest palette color) or `luminance` (nearest perceived brightness); default `rgb`. `dither.direction` is degrees from −180 to 180, with 0 toward positive X and 90 toward positive Y. It controls drift, with `motion: 'drift'` and `speed: 0.1–3`. Radial drift travels through concentric thresholds, so direction does not apply. Diffusion has no ordered matrix to translate; choose an ordered algorithm for drift.
 - `effects.rgbSplit` and `effects.sharpen` are 0–1, default 0. RGB split is uniform channel separation; `prism` remains peripheral separation. Both need WebGL finishing. Do not silently claim unsupported effects were rendered.
-- `motion.amount` is 0–2, default 1. It changes displacement/light/dissolve strength without changing phase or speed. Zero retains the stationary image. Caustics, Slow Current, and Reveal & Reform remain the supported motion types.
+- `motion.amount` is 0–2, default 1. It changes displacement/light/dissolve strength without changing phase or speed. Zero retains the stationary image. Enumerate `STUDIO_MOTIONS` for all supported motion types, including the 4.3 additions below.
 
 ```ts
 const studio = await mountStudio(canvas, file, {
@@ -175,3 +175,13 @@ Base cycles last 12 seconds; speed scales duration. Studio amount scales strengt
 Keep automatic motion off for source video unless requested. Respect reduced motion.
 These are local effects, not AI-generated frames. Frame rate depends on device,
 resolution and other effects; no universal FPS guarantee.
+
+## Performance fixes (4.3.1)
+
+Stationary artwork, masks, lights, backdrops and character bloom are cached while finishing grain/dust/glitch continue. Source/settings/layout edits invalidate the composition; pointer motion redraws until the field settles and restores a clean final frame. Unused dither motion on other styles and zero-strength ambient motion no longer keep a still preview awake. Ordered Bayer threshold tables avoid per-pixel recurrence without changing quantized output. CMYK now honors tonal hover/motion and gray/accent color modes. Still exports accept `motionTime` from the mounted preview to preserve the selected phase after speed edits; animation exports still start at zero.
+
+## 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.
+
+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.

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

@@ -54,3 +54,11 @@ Use `CHARACTER_SETS` from root or `/core` for the same eight choices as the edit
 ## 4.1.0 — remove legacy catalogs
 
 This requested minor version contains breaking API removals: `CHARSETS`, `ART_STYLE_PRESETS`, `CHARSET_SEQUENCES`, `LIVING_STYLE_PRESETS`, `CharsetKey`, `CharsetSequenceKey`, and `LivingStylePresetKey`. Search source, saved settings, generated snippets, and documentation before upgrading. Use `/studio`'s 15 `STUDIO_STYLES` for render styles; use `/core`'s curated `CHARACTER_SETS` for ASCII alphabets. Replace old shorthand `artStyle` names with actual Studio rendering or explicit core charset/renderMode/colorMode options. Core only accepts `artStyle: 'classic'`. Custom `charset` and `charsetFrames` remain supported. Fine-dither hover integration uses explicit `fineDither: true`, not the removed terminal preset.
+
+## 4.3 and 4.3.1
+
+4.3 adds Magnetic Pull and Scatter hover (`magnetic`, `scatter`) and Sheen, Tidal Rings and Living Grain motion (`sheen`, `tidal`, `grain`). Old defaults remain. 4.3.1 fixes CMYK tonal interactions and idle-frame work, caches stationary compositions, and accelerates ordered dithering without changing its output. Read [project-integration.md](project-integration.md) for one-owner live integration and independent PNG/video export.
+
+## 4.4
+
+Adds Emboss, Elastic and Rake hover; Parallax, Woven Flow, Print Shift and Contour Light motion. Existing IDs, defaults, saved projects and v1 settings remain valid. `STUDIO_HOVERS` and `STUDIO_MOTIONS` are now shared public catalogs in `/studio` and `/hover`; generate selection controls from them. The four new ambient IDs are also accepted by core `animationStyle`. Keep only one owner for motion.

package/dist/ambient-motion-C2qG4xUI.d.cts

@@ -1,39 +0,0 @@
-type AmbientMotion = 'none' | 'caustics' | 'current' | 'reform' | 'sheen' | 'tidal' | 'grain';
-declare const MOTION_STYLES: readonly [{
-    readonly value: "none";
-    readonly mode: "none";
-    readonly label: "Off";
-    readonly description: "Keep the image still. Hover stays available.";
-}, {
-    readonly value: "caustics";
-    readonly mode: "caustics";
-    readonly label: "Caustics";
-    readonly description: "Soft ribbons of light travel across a stationary character grid.";
-}, {
-    readonly value: "current";
-    readonly mode: "current";
-    readonly label: "Slow Current";
-    readonly description: "A gentle flow through the image, with steady edges.";
-}, {
-    readonly value: "reform";
-    readonly mode: "reform";
-    readonly label: "Reveal & Reform";
-    readonly description: "Disperse, gather, then hold the complete image.";
-}, {
-    readonly value: "sheen";
-    readonly mode: "sheen";
-    readonly label: "Sheen";
-    readonly description: "A broad diagonal light sweep; characters stay anchored.";
-}, {
-    readonly value: "tidal";
-    readonly mode: "tidal";
-    readonly label: "Tidal Rings";
-    readonly description: "Concentric currents travel outward, with protected edges.";
-}, {
-    readonly value: "grain";
-    readonly mode: "grain";
-    readonly label: "Living Grain";
-    readonly description: "Slow, individually phased tonal changes on a stationary grid.";
-}];
-
-export { type AmbientMotion as A, MOTION_STYLES as M };

package/dist/ambient-motion-C2qG4xUI.d.ts

@@ -1,39 +0,0 @@
-type AmbientMotion = 'none' | 'caustics' | 'current' | 'reform' | 'sheen' | 'tidal' | 'grain';
-declare const MOTION_STYLES: readonly [{
-    readonly value: "none";
-    readonly mode: "none";
-    readonly label: "Off";
-    readonly description: "Keep the image still. Hover stays available.";
-}, {
-    readonly value: "caustics";
-    readonly mode: "caustics";
-    readonly label: "Caustics";
-    readonly description: "Soft ribbons of light travel across a stationary character grid.";
-}, {
-    readonly value: "current";
-    readonly mode: "current";
-    readonly label: "Slow Current";
-    readonly description: "A gentle flow through the image, with steady edges.";
-}, {
-    readonly value: "reform";
-    readonly mode: "reform";
-    readonly label: "Reveal & Reform";
-    readonly description: "Disperse, gather, then hold the complete image.";
-}, {
-    readonly value: "sheen";
-    readonly mode: "sheen";
-    readonly label: "Sheen";
-    readonly description: "A broad diagonal light sweep; characters stay anchored.";
-}, {
-    readonly value: "tidal";
-    readonly mode: "tidal";
-    readonly label: "Tidal Rings";
-    readonly description: "Concentric currents travel outward, with protected edges.";
-}, {
-    readonly value: "grain";
-    readonly mode: "grain";
-    readonly label: "Living Grain";
-    readonly description: "Slow, individually phased tonal changes on a stationary grid.";
-}];
-
-export { type AmbientMotion as A, MOTION_STYLES as M };