asciify-engine 4.0.0 → 4.2.0

package/dist/types-BeXEm4UY.d.ts

@@ -0,0 +1,323 @@
+type ColorMode = 'grayscale' | 'fullcolor' | 'matrix' | 'accent';
+type RenderMode = 'ascii' | 'dots';
+type AnimationStyle = 'none' | 'caustics' | 'current' | 'reform';
+/** Core media draws ASCII/dots; use StudioStyle for the 15 render styles. */
+type ArtStyle = 'classic';
+type HoverEffect = 'spotlight' | 'magnify' | 'repel' | 'glow' | 'colorShift' | 'attract' | 'shatter' | 'trail' | 'glitchText';
+type HoverShape = 'circle' | 'box';
+type HoverPreset = 'none' | 'subtle' | 'flashlight' | 'magnifier' | 'forceField' | 'neon' | 'fire' | 'ice' | 'gravity' | 'shatter' | 'ghost' | 'glitchReveal';
+type SourceCropUnit = 'percent' | 'pixel';
+type SourceCropAnchor = 'center' | 'top' | 'bottom' | 'left' | 'right' | 'top-left' | 'top-right' | 'bottom-left' | 'bottom-right';
+interface SourceCrop {
+    /** Legacy crop origin on the source media. Percent values use 0–1. Default: centered when cropped */
+    x?: number;
+    /** Legacy crop origin on the source media. Percent values use 0–1. Default: centered when cropped */
+    y?: number;
+    /** Legacy crop width on the source media. Percent values use 0–1. Default: mirrors `height` to preserve proportions */
+    width?: number;
+    /** Legacy crop height on the source media. Percent values use 0–1. Default: mirrors `width` to preserve proportions */
+    height?: number;
+    /** CSS-like crop inset from the top edge. Percent values use 0–1. */
+    top?: number;
+    /** CSS-like crop inset from the right edge. Percent values use 0–1. */
+    right?: number;
+    /** CSS-like crop inset from the bottom edge. Percent values use 0–1. */
+    bottom?: number;
+    /** CSS-like crop inset from the left edge. Percent values use 0–1. */
+    left?: number;
+    /**
+     * Keep the source aspect ratio when deriving a crop from a single `width` or
+     * `height`. CSS-like side insets (`top`, `right`, `bottom`, `left`) already
+     * define an exact source view box, and `asciifyVideo` sizes from that crop
+     * aspect so the output does not stretch. Default: `true`.
+     */
+    preserveAspect?: boolean;
+    /** Bias auto-centered crops toward an edge or corner. Default: `'center'` */
+    anchor?: SourceCropAnchor;
+    /** Interpret values as normalized percentages or source pixels. Default: `'percent'` */
+    unit?: SourceCropUnit;
+}
+/**
+ * Named colour palette presets — pass as `colorMode` for themed rendering.
+ * Applied as a post-process colour remap over the standard grayscale output.
+ */
+type PaletteTheme = 'dracula' | 'monokai' | 'nord' | 'catppuccin' | 'solarized' | 'gruvbox';
+declare const PALETTE_THEMES: Record<PaletteTheme, {
+    name: string;
+    accent: string;
+    bg: string;
+    fg: string;
+}>;
+type SourceType = 'image' | 'video' | 'gif' | null;
+interface AsciiOptions {
+    /** Character cell width in pixels. Smaller = more detail, more cells. Default: `7` */
+    fontSize: number;
+    /** Extra horizontal spacing between characters (pixels). Default: `1` */
+    charSpacing: number;
+    /**
+     * Brightness adjustment applied before luminance mapping.
+     * Range −1 (black) → 0 (unchanged) → 1 (white). Default: `0`
+     */
+    brightness: number;
+    /**
+     * Contrast boost applied before luminance mapping.
+     * `0` = unchanged, positive values increase contrast, negative decrease it.
+     * Default: `0`
+     */
+    contrast: number;
+    /**
+     * Character density ramp — ordered from lightest to darkest.
+     * Use `CHARACTER_SETS.standard.chars` for a curated ramp or supply your own string.
+     * Default: `' .:-=+*#%@'`
+     */
+    charset: string;
+    /**
+     * Colour output mode.
+     * - `'grayscale'` — white-on-black monochrome
+     * - `'fullcolor'` — samples pixel colours from the source
+     * - `'matrix'` — green phosphor terminal look
+     * - `'accent'` — single accent colour with intensity-driven brightness
+     * Default: `'grayscale'`
+     */
+    colorMode: ColorMode;
+    /**
+     * The accent colour used when `colorMode` is `'accent'` or `'matrix'`.
+     * Any CSS colour string. Default: `'#d4ff00'`
+     */
+    /**
+     * Hex color string used when `colorMode` is `'accent'`.
+     * Set to `'auto'` to let the engine pick contrasting ink automatically:
+     * dark ink (`#0d0d0d`) in light mode, light ink (`#faf9f7`) in dark mode.
+     */
+    accentColor: string;
+    /**
+     * Invert luminance mapping (light pixels → dense chars). Default: `false`
+     *
+     * Set to `'auto'` to let the engine detect the OS color scheme:
+     * - Light mode → inverts (bright pixel = dark char = visible on white background)
+     * - Dark mode  → normal  (bright pixel = bright char = visible on dark background)
+     */
+    invert: boolean | 'auto';
+    /**
+     * Render mode.
+     * - `'ascii'` — characters drawn as text
+     * - `'dots'` — each cell rendered as a filled circle (particle look)
+     * Default: `'ascii'`
+     */
+    renderMode: RenderMode;
+    /**
+     * Per-character animation driven over time.
+     * Applies wave, glitch, rain-drop, spiral, and other effects to the rendered text.
+     * Default: `'none'`
+     */
+    animationStyle: AnimationStyle;
+    /** Speed multiplier for `animationStyle` effects. Default: `1` */
+    animationSpeed: number;
+    /**
+     * Size of each dot relative to the cell when `renderMode === 'dots'`.
+     * `1` fills the whole cell, `0.5` draws half-size circles. Default: `0.8`
+     */
+    dotSizeRatio: number;
+    /**
+     * Ordered Bayer (4×4) dither strength applied to the luminance map.
+     * `0` = no dithering, `1` = full dithering. Default: `0`
+     */
+    ditherStrength: number;
+    /**
+     * Assumed aspect ratio (width ÷ height) of a single output character.
+     * Controls how many rows vs columns are generated — must match your rendering
+     * environment to preserve the source image's proportions.
+     * - `0.55` — browser monospace at `line-height: 1.09` (default)
+     * - `0.52` — browser monospace at `line-height: 1.15`
+     * - `0.5`  — most terminal emulators
+     * Default: `0.55`
+     */
+    charAspect: number;
+    /**
+     * Auto-stretch the luminance range before charset mapping.
+     * When `true`, the darkest pixel in the frame maps to the first charset character
+     * and the brightest to the last, maximising perceived detail and contrast.
+     * Particularly useful for images with low inherent contrast or muted tones.
+     * Default: `false`
+     */
+    normalize: boolean;
+    /**
+     * Overall intensity of the hover / cursor interaction effect.
+     * `0` disables the effect. Default: `0`
+     */
+    hoverStrength: number;
+    /**
+     * Radius of the hover interaction zone as a fraction of the canvas size.
+     * `0.1` = 10% of canvas width. Default: `0.2`
+     */
+    hoverRadius: number;
+    /**
+     * Which cursor interaction style to apply when `hoverStrength > 0`.
+     * See `HoverPreset` or `HOVER_PRESETS` for ready-made configurations.
+     * Default: `'spotlight'`
+     */
+    hoverEffect: HoverEffect;
+    /**
+     * Tint colour used by hover effects such as spotlight, glow, and colorShift.
+     * Any CSS colour string. Default: `'#ffffff'`
+     */
+    hoverColor: string;
+    /**
+     * Shape of the hover interaction zone.
+     * - `'circle'` — radial falloff (default)
+     * - `'box'` — rectangular zone, text fills a block around the cursor
+     * Default: `'circle'`
+     */
+    hoverShape: HoverShape;
+    /**
+     * Text string revealed by the `'glitchText'` hover effect.
+     * Characters around the cursor scramble and resolve into this text.
+     * Supports `\n` for multi-line reveals.
+     *
+     * Pass an **array** of strings to cycle through different words based on
+     * the cursor's grid region — the engine picks one via a spatial hash so
+     * each area of the canvas shows a different word.
+     *
+     * Default: `'ASCIIFY'`
+     *
+     * @example
+     * // Single word:
+     * options: { hoverEffect: 'glitchText', hoverText: 'HELLO' }
+     *
+     * // Word pool — different text at different cursor positions:
+     * options: { hoverEffect: 'glitchText', hoverText: ['DEPLOY', 'SCALE', 'SHIP', 'BUILD'] }
+     */
+    hoverText: string | string[];
+    /**
+     * Core renderer discriminator. No legacy preset lookup is performed.
+     * Core rendering uses `classic`; select the current render styles through `/studio`.
+     */
+    artStyle: ArtStyle;
+    /** Explicit fine-dither treatment for the optional hover compositor. */
+    fineDither?: boolean;
+    /**
+     * Custom repeating text used when `artStyle` is `'letters'` or when you set
+     * a custom charset. Leave empty to use the selected `charset`. Default: `''`
+     */
+    customText: string;
+    /**
+     * Chroma-key colour to remove from the source (green screen / blue screen).
+     * Pixels whose RGB distance from this colour is within `chromaKeyTolerance`
+     * are keyed out: their character becomes a space and alpha is set to 0,
+     * letting the canvas background show through.
+     *
+     * - `true` — **smart green screen**: heuristic detection (`g > r*1.4 && g > b*1.4`)
+     *   catches every shade of green screen (lime, broadcast, chroma green) with no
+     *   config. Works on virtually all studio/streaming footage.
+     * - `'blue-screen'` — **smart blue screen**: same heuristic for blue.
+     * - `{ r, g, b }` or CSS colour string — custom key colour + `chromaKeyTolerance`
+     * - `null` / `false` — disabled (default)
+     *
+     * @example
+     * // Standard green screen — zero config:
+     * options: { chromaKey: true }
+     *
+     * // Blue screen — zero config:
+     * options: { chromaKey: 'blue-screen' }
+     *
+     * // Custom CSS colour:
+     * options: { chromaKey: '#00b140', chromaKeyTolerance: 70 }
+     */
+    chromaKey: {
+        r: number;
+        g: number;
+        b: number;
+    } | string | boolean | null;
+    /**
+     * Euclidean RGB tolerance radius for chroma-key detection.
+     * `0` = exact match only, `441` ≈ key out everything.
+     * Higher values remove more pixels. Default: `60`
+     */
+    chromaKeyTolerance: number;
+    /**
+     * Extra normalized padding kept around the detected chroma-key foreground when
+     * `asciifyVideo` auto-trims keyed video content inside `sourceCrop`.
+     * `0` hugs the visible foreground. `0.01` keeps 1% safety padding.
+     * Default: `0.002`
+     */
+    chromaKeyTrimPadding: number;
+    /**
+     * Minimum source-pixel luminance for chroma-key foreground auto-trim.
+     * Raise this when faint edge noise is counted as content and prevents a
+     * keyed subject from filling a preserved-ratio layout. Range `0–255`.
+     * Default: `0`
+     */
+    chromaKeyTrimLuminanceThreshold: number;
+    /**
+     * How keyed video foreground trimming is applied when `chromaKey` and
+     * `sourceCrop` are enabled.
+     *
+     * - `'range'` samples the video/scroll range once and keeps a stable union
+     *   crop. Best default for consistent framing.
+     * - `'frame'` remeasures each rendered frame and expands the crop to the
+     *   render aspect. Best for scroll-scrubbed hero footage where foreground
+     *   position changes and pure contain leaves empty edges.
+     * - `'off'` disables automatic keyed foreground trimming.
+     *
+     * Default: `'range'`
+     */
+    chromaKeyTrimMode: 'range' | 'frame' | 'off';
+    /**
+     * Optional source crop applied before ASCII sampling.
+     *
+     * Use this when the media has empty edges or a subject that should be framed
+     * tighter without changing the destination canvas size.
+     *
+     * @example
+     * // Remove 15% from the top and 15% from the bottom, preserving proportions:
+     * options: { sourceCrop: { top: 0.15, bottom: 0.15 } }
+     *
+     * @example
+     * // Keep 70% of the source, preserve proportions, and center it:
+     * options: { sourceCrop: { height: 0.7 } }
+     *
+     * @example
+     * // Use an exact source window when manual framing should override proportions:
+     * options: { sourceCrop: { x: 0.05, y: 0.08, width: 0.9, height: 0.9, preserveAspect: false } }
+     */
+    sourceCrop?: SourceCrop | null;
+    /**
+     * Array of charset strings to cycle through over time.
+     * The engine picks `charsetFrames[Math.floor(time * charsetFps) % length]` on each
+     * render tick, re-mapping characters from stored cell luminance.
+     * Pairs beautifully with `animationStyle` and `asciiBackground`.
+     *
+     * Supply your own array of character ramps:
+     * @example
+     * options: { charsetFrames: [CHARACTER_SETS.standard.chars, CHARACTER_SETS.blocks.chars] }
+     */
+    charsetFrames?: string[];
+    /** Cycle rate for `charsetFrames` in frames-per-second. Default: `2` */
+    charsetFps?: number;
+}
+interface AsciiCell {
+    char: string;
+    r: number;
+    g: number;
+    b: number;
+    a: number;
+    /** Stored dithered luminance (0–255). Present when the frame was generated by the engine. Used for dynamic charset re-selection at render time via `charsetFrames`. */
+    lum?: number;
+}
+type AsciiFrame = AsciiCell[][];
+interface AsciiResult {
+    frames: AsciiFrame[];
+    cols: number;
+    rows: number;
+    fps: number;
+}
+declare const DEFAULT_OPTIONS: AsciiOptions;
+/**
+ * Hover presets — one-click configurations for the hover system.
+ */
+declare const HOVER_PRESETS: Record<HoverPreset, {
+    label: string;
+    options: Partial<AsciiOptions>;
+}>;
+
+export { type AsciiFrame as A, type ColorMode as C, DEFAULT_OPTIONS as D, type HoverEffect as H, PALETTE_THEMES as P, type RenderMode as R, type SourceType as S, type AsciiOptions as a, type ArtStyle as b, type AnimationStyle as c, type AsciiCell as d, type AsciiResult as e, HOVER_PRESETS as f, type HoverPreset as g, type HoverShape as h, type PaletteTheme as i };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "asciify-engine",
-  "version": "4.0.0",
+  "version": "4.2.0",
   "description": "Framework-agnostic ASCII art engine. Convert images, videos, and GIFs into ASCII art rendered on canvas.",
   "type": "module",
   "main": "./dist/index.cjs",

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.0.0"
-  updated: "2026-09-09"
+  tested-engine: "4.2.0"
+  updated: "2026-10-07"
 ---
 
 # Asciify Engine
 
-Use the published `asciify-engine` npm package for browser canvas rendering. Tested against **4.0.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.2.0**. Check the application's installed version and its public types before using newer options; a local checkout can contain unpublished changes.
 
 - Agent entry: https://asciify.org/skill (redirects to this Markdown document).
 - Playground: https://asciify.org/editor
@@ -83,7 +83,7 @@ const letters = [...new Set('ASCIIFY'.toUpperCase().replace(/[^A-Z]/g, ''))].joi
 const charset = ` .:-=+${letters}#%@`;
 ```
 
-Preview it: letter glyph densities differ, so arbitrary words are not automatically an evenly ordered ramp. Keep the leading space and the light/dense symbols. Use `CHARSETS.standard`, `dense`, `blocks`, or `braille` when they better suit the subject.
+Preview it: letter glyph densities differ, so arbitrary words are not automatically an evenly ordered ramp. Keep the leading space and the light/dense symbols. Use the curated `CHARACTER_SETS.standard.chars`, `detailed.chars`, `blocks.chars`, or `braille.chars` from `/core` when appropriate.
 
 ## Engine effects versus studio effects
 
@@ -136,6 +136,11 @@ Version 1.3.0 adds text-shaped charcoal cutouts (`textMask`), peripheral scanlin
 
 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.
 
-## Standard catalogs in 2.0
+## Current catalogs (4.2)
 
-`CHARSETS` and `ART_STYLE_PRESETS` no longer include `emoji`, `musical` or `starfield`. Do not recommend or generate those names. For character selection in a Studio integration, use `STUDIO_CHARACTER_SETS` from `asciify-engine/studio` and assign an entry's `chars` to `settings.charset`. These ramps apply to the `ascii` style; other styles define their own marks. Custom Unicode strings remain supported. Read the upgrade reference when migrating 1.x preset names. The site now opens its primary workspace at `/editor`; `/editor/classic` preserves earlier workflows. Keep the engine imports modular: new editor defaults do not require importing Studio into an existing hero.
+Legacy `CHARSETS`, `ART_STYLE_PRESETS`, `CHARSET_SEQUENCES`, `LIVING_STYLE_PRESETS` and their key types are removed. Do not import them or generate old names such as Katakana, Binary, Waves or Smoke. Use the 18 `STUDIO_STYLES` for render-style selectors and `/studio` rendering. For ASCII-only character ramps use `CHARACTER_SETS` from `/core` or `STUDIO_CHARACTER_SETS` from `/studio`; custom Unicode and user-provided frame arrays remain supported. Core `artStyle` only accepts `classic`; use explicit options instead of preset shortcuts. Despite the requested 4.1.0 version number, migrating these removed APIs is a breaking change.
+
+
+## Fine dither and creative controls (4.2)
+
+Studio adds `hex`, `led`, and `cmyk` render styles, directional/radial dither patterns, additional palettes, luminance mapping, RGB split, sharpening, and adjustable still-image motion strength. Read [studio-workspace.md](references/studio-workspace.md#fine-detail-and-controls-42) for exact options, density budgets and preview/export consistency. These are local Canvas/WebGL effects, not AI generation or a claim of parity with every competing catalog.

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

@@ -105,7 +105,7 @@ Do not promise a 120 FPS minimum on every mobile device or arbitrary character c
 
 ### 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; 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.
+Hero → Customize → Characters uses the same 15 render-style tiles as the editor, with six primary styles and nine under More render styles. Custom letters are available under ASCII. Alternate styles use the published Studio renderer and share the hero's video; they are not aliases for old alphabets. Default ASCII retains its GPU hover and Prism finish. Selecting styles works while paused or with reduced motion.
 
 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.
 

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

@@ -125,3 +125,35 @@ Studio defaults to a 6-unit cell size. Separate the sampling grid from canvas ba
 Start with `cellSize: 6`; the editor remembers each style's size. A Retina preview uses `resize(width, height, pixelRatio)` on a `mountStudioMedia` handle to keep logical cells independent of physical raster resolution. Its `setBudget(maxCells)` changes the upper sampling budget; automatic adaptation may reduce it when frames are slow. At a 960×540 logical canvas, 32,768 cells permit Lego size 4, and 65,536 permit dither scale 3. Keep ASCII at a measured budget such as 12,000 cells. Smaller requested cells cannot bypass the active budget; show `studioGrid`'s actual minimum in controls. Fine grids cost more, so profile hover and motion on target devices. Studio caches Lego stud artwork.
 
 For menus shared with a media hero, import the eight `CHARACTER_SETS` from `asciify-engine/core`; `STUDIO_CHARACTER_SETS` is the identical catalog through `/studio`. A hero need not load the Studio runtime.
+
+
+## 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.
+- 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.
+- Mounts expose `setAdaptive(boolean)` and `setBudget(cells)`. The budget cannot exceed the mount's original `maxCells`. Adaptive mode can reduce the grid during animation/hover; disable it deliberately when exact density is more important. Static dither is cached until its source/settings/grid change.
+- 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.
+
+```ts
+const studio = await mountStudio(canvas, file, {
+  width: 960, height: 540, maxDimension: 960,
+  maxCells: 1048576, adaptive: false,
+  settings: {
+    style: 'dither',
+    dither: { scale: 1, algorithm: 'bayer8', palette: 'gray4',
+      colorSpace: 'luminance', motion: 'drift', direction: 90, speed: .5 },
+    motion: { type: 'current', speed: .4, amount: .35 },
+    effects: { sharpen: .15 },
+  },
+});
+// Return to an interactive budget without remounting:
+studio.setAdaptive(true);
+studio.setBudget(65536);
+```
+
+When exporting, pass the same `maxCells` and logical `referenceWidth` as the preview to retain cell density. Increasing output resolution alone should not invent a different composition. Older projects normalize new fields to neutral defaults.

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

@@ -30,7 +30,7 @@ After updating, read the installed SKILL.md and its linked references, confirm i
 
 ## 2.0 catalog migration
 
-2.0.0 removes the `emoji`, `musical`, and `starfield` keys from `CHARSETS`, `ArtStyle`, and `ART_STYLE_PRESETS`. Before upgrading, search application settings and saved presets for those names. Use `classic` plus a custom `charset` to retain an application-owned alphabet, or use `circles`, `braille`, or `geometric` for structural alternatives. The existing cosmic sequence now uses sparse marks/circles/shadows, and angular uses geometry/shards/blocks. Other core options and renderers retain their behavior. Do not pass retired keys or tell users that custom Unicode has been removed.
+2.0.0 removes the `emoji`, `musical`, and `starfield` keys from `CHARSETS`, `ArtStyle`, and `ART_STYLE_PRESETS`. Before upgrading, search application settings and saved presets for those names. For current releases, use a custom `charset` or a current StudioStyle. The existing cosmic sequence now uses sparse marks/circles/shadows, and angular uses geometry/shards/blocks. Other core options and renderers retain their behavior. Do not pass retired keys or tell users that custom Unicode has been removed.
 
 The curated `STUDIO_CHARACTER_SETS` export is available from `/studio` in 2.0.0. Its values contain `label` and `chars`; assign `chars` to Studio settings only for `style: 'ascii'`. The primary editor at `/editor` uses Studio; earlier webcam and classic-editor workflows remain at `/editor/classic`.
 
@@ -48,4 +48,9 @@ Use one motion owner: `animationStyle` for core, `motion` for `/hover`, or `moti
 
 Remove imports from `asciify-engine/backgrounds` and generator imports from the root package. Download the chosen `.js` template from https://asciify.org/backgrounds and change the import to `./wave.js` (or your selected file). The template exports `asciiBackground`; keep calling `destroy()` on unmount. It handles resizing, hidden/offscreen suspension, reduced motion, and cleanup. A selected template contains only that generator; backgrounds.js is the optional full collection. Application-owned source templates are separate from npm updates. Existing installations can stay on 3.x while migrating. Text and media rendering remain supported, including text backgrounds.
 
-Use `CHARACTER_SETS` from root or `/core` for the same eight choices as the editor's `STUDIO_CHARACTER_SETS`. This data-only import does not load Studio. Keep custom characters available separately; do not populate standard UI choices from the larger legacy `CHARSETS` object.
+Use `CHARACTER_SETS` from root or `/core` for the same eight choices as the editor's `STUDIO_CHARACTER_SETS`. This data-only import does not load Studio. Keep custom characters available separately; do not import the removed `CHARSETS` object.
+
+
+## 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.

package/dist/characters-BNTu2oEF.d.cts

@@ -1,71 +0,0 @@
-/** Curated ASCII ramps. Use custom text to supply a different alphabet. */
-declare const CHARACTER_SETS: {
-    readonly standard: {
-        readonly label: "Classic ASCII";
-        readonly chars: " .:-=+*#%@";
-    };
-    readonly asciify: {
-        readonly label: "Asciify";
-        readonly chars: " .:-=+ASCIIFY#@";
-    };
-    readonly minimal: {
-        readonly label: "Minimal";
-        readonly chars: " .:+";
-    };
-    readonly detailed: {
-        readonly label: "Detailed";
-        readonly chars: " .,:;i1tfLCG08@";
-    };
-    readonly letters: {
-        readonly label: "Letters";
-        readonly chars: " .ilLCFTYASMW";
-    };
-    readonly technical: {
-        readonly label: "Technical";
-        readonly chars: " .:;>_/[{}]=+*#@$";
-    };
-    readonly blocks: {
-        readonly label: "Tonal blocks";
-        readonly chars: " ░▒▓█";
-    };
-    readonly braille: {
-        readonly label: "Braille";
-        readonly chars: " ⠁⠃⠇⡇⣇⣧⣷⣿";
-    };
-};
-declare const STUDIO_CHARACTER_SETS: {
-    readonly standard: {
-        readonly label: "Classic ASCII";
-        readonly chars: " .:-=+*#%@";
-    };
-    readonly asciify: {
-        readonly label: "Asciify";
-        readonly chars: " .:-=+ASCIIFY#@";
-    };
-    readonly minimal: {
-        readonly label: "Minimal";
-        readonly chars: " .:+";
-    };
-    readonly detailed: {
-        readonly label: "Detailed";
-        readonly chars: " .,:;i1tfLCG08@";
-    };
-    readonly letters: {
-        readonly label: "Letters";
-        readonly chars: " .ilLCFTYASMW";
-    };
-    readonly technical: {
-        readonly label: "Technical";
-        readonly chars: " .:;>_/[{}]=+*#@$";
-    };
-    readonly blocks: {
-        readonly label: "Tonal blocks";
-        readonly chars: " ░▒▓█";
-    };
-    readonly braille: {
-        readonly label: "Braille";
-        readonly chars: " ⠁⠃⠇⡇⣇⣧⣷⣿";
-    };
-};
-
-export { CHARACTER_SETS as C, STUDIO_CHARACTER_SETS as S };

package/dist/characters-BNTu2oEF.d.ts

@@ -1,71 +0,0 @@
-/** Curated ASCII ramps. Use custom text to supply a different alphabet. */
-declare const CHARACTER_SETS: {
-    readonly standard: {
-        readonly label: "Classic ASCII";
-        readonly chars: " .:-=+*#%@";
-    };
-    readonly asciify: {
-        readonly label: "Asciify";
-        readonly chars: " .:-=+ASCIIFY#@";
-    };
-    readonly minimal: {
-        readonly label: "Minimal";
-        readonly chars: " .:+";
-    };
-    readonly detailed: {
-        readonly label: "Detailed";
-        readonly chars: " .,:;i1tfLCG08@";
-    };
-    readonly letters: {
-        readonly label: "Letters";
-        readonly chars: " .ilLCFTYASMW";
-    };
-    readonly technical: {
-        readonly label: "Technical";
-        readonly chars: " .:;>_/[{}]=+*#@$";
-    };
-    readonly blocks: {
-        readonly label: "Tonal blocks";
-        readonly chars: " ░▒▓█";
-    };
-    readonly braille: {
-        readonly label: "Braille";
-        readonly chars: " ⠁⠃⠇⡇⣇⣧⣷⣿";
-    };
-};
-declare const STUDIO_CHARACTER_SETS: {
-    readonly standard: {
-        readonly label: "Classic ASCII";
-        readonly chars: " .:-=+*#%@";
-    };
-    readonly asciify: {
-        readonly label: "Asciify";
-        readonly chars: " .:-=+ASCIIFY#@";
-    };
-    readonly minimal: {
-        readonly label: "Minimal";
-        readonly chars: " .:+";
-    };
-    readonly detailed: {
-        readonly label: "Detailed";
-        readonly chars: " .,:;i1tfLCG08@";
-    };
-    readonly letters: {
-        readonly label: "Letters";
-        readonly chars: " .ilLCFTYASMW";
-    };
-    readonly technical: {
-        readonly label: "Technical";
-        readonly chars: " .:;>_/[{}]=+*#@$";
-    };
-    readonly blocks: {
-        readonly label: "Tonal blocks";
-        readonly chars: " ░▒▓█";
-    };
-    readonly braille: {
-        readonly label: "Braille";
-        readonly chars: " ⠁⠃⠇⡇⣇⣧⣷⣿";
-    };
-};
-
-export { CHARACTER_SETS as C, STUDIO_CHARACTER_SETS as S };