asciify-engine 4.8.0 → 4.9.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: "4.8.0"
+  tested-engine: "4.9.0"
   updated: "2026-10-07"
 ---
 
 # Asciify Engine
 
-Use the published `asciify-engine` npm package for browser canvas rendering. Tested against **4.8.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.9.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
@@ -143,7 +143,7 @@ For optional wallpaper/backdrops, alternate renderers, palettes, masks, saved lo
 
 For multiple media/text layers in one live component, use 4.8+ `mountStudioProject` and read [layered-projects.md](references/layered-projects.md). It shares one playback loop and rendering budgets across up to eight independently styled layers. Persist source keys separately from media, and use `exportStudioProject` for independent exports. Do not create one mounted Studio instance per layer or rasterize accessible interface text.
 
-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.
+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 24 `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)
@@ -155,3 +155,5 @@ From 4.5, `dither.algorithm: 'blue-noise'` uses a precomputed dispersed threshol
 From 4.6, Studio adds `color.curves` (RGB, red, green, blue) and optional edge-preserving `color.denoise`. `player.settings` returns a detached snapshot for saving or exporting after updates. Read [channel curves and source noise](references/studio-workspace.md#channel-curves-and-source-noise-46) for point limits, update semantics and the processing budget. Do not turn noise reduction on by default or apply it again to the already-rendered characters.
 
 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.

package/skills/asciify-engine/references/print-styles.md

@@ -0,0 +1,63 @@
+# Print and illustration (4.9)
+
+Six local Canvas renderers live in the optional `asciify-engine/studio` entry. They do not change the default ASCII style or add a server/provider. They share source grading, curves, warps, masks, hover, still-image motion, finishing, saved settings, single-image export and layered projects.
+
+| Style ID | Mechanism | Useful controls |
+| --- | --- | --- |
+| `stipple` | Four spatially jittered dots per sample; tone changes their area | Coverage, weight, texture, seed |
+| `engraving` | Parallel world-anchored cuts with tone-dependent width | Coverage, weight, angle, texture |
+| `crosshatch` | Up to three crossing screens appear across the tonal range | Coverage, weight, angle, texture |
+| `woodblock` | Five tone steps in broad carved bands with correlated irregular edges | Coverage, weight, angle, texture |
+| `risograph` | Two overlapping ink-dot screens; source warmth separates coverage in source-color mode | Second ink, registration offset/direction, texture |
+| `pointillism` | Four small elliptical pigment strokes per sample | Source color, weight, texture, seed |
+
+`STUDIO_PRINT_STYLES` supplies `value`, `label`, and `description` for selectors. `isStudioPrintStyle(style)` identifies this family. The full `STUDIO_STYLES` catalog has 24 styles. Existing `riso` and `print` look IDs remain dither presets; choose `style: 'risograph'` to use the new two-screen renderer. These are print-inspired raster treatments, not physical ink simulation, CMYK separations or vector paths.
+
+## Live still image
+
+```ts
+import { mountStudio } from 'asciify-engine/studio';
+
+const player = await mountStudio(canvas, '/your-image.jpg', {
+  settings: {
+    style: 'engraving', cellSize: 7, colorMode: 'accent', ink: '#becbbe',
+    print: { angle: -35, weight: 1.1, roughness: .3 },
+    backdrop: { color: '#101810' },
+    motion: { type: 'sheen', speed: .5, amount: .4 },
+    hover: { effect: 'water', radius: .4, strength: .5 },
+  },
+  maxDimension: 960, maxCells: 12000,
+  onError: console.error,
+});
+player.update({ print: { angle: 20 } }); // retains the other print settings
+const settings = player.settings;       // detached snapshot for saving/export
+// On unmount:
+player.destroy();
+```
+
+For dark ink on paper, use `print.invert: true`, a dark `ink`, and a light `backdrop.color`. Inversion chooses which source tones receive ink; it does not change the ink or backdrop automatically. Dissolve reduces ink in either polarity. Trail still inverts the local tonal response. The motion engine retains its own `12 / speed` cycle; the print texture has no independent time source.
+
+## Exact settings
+
+`print` is an optional nested group in `StudioInput` and saved version-1 `StudioSettings`. Old files receive compatible defaults. Partial updates merge this group. `normalizeStudioPrint`, `DEFAULT_STUDIO_PRINT`, and `StudioPrintSettings` are exported from `/studio`.
+
+| Field | Range / default | Meaning |
+| --- | --- | --- |
+| `density` | 0–2 / 1 | Tonal coverage; zero draws no print marks |
+| `weight` | .25–2 / 1 | Dot/stroke size; size is bounded within the screen |
+| `angle` | −180–180° / −35 | Line angle for engraving/crosshatch/woodblock; registration direction for risograph |
+| `roughness` | 0–1 / .35 | Spatial texture variation; not random animation |
+| `invert` | boolean / false | False draws highlights; true draws shadows |
+| `secondaryInk` | six-digit hex / `#ec6752` | Second risograph ink only |
+| `registration` | 0–1 / .2 | Risograph offset, up to .38 of one cell |
+| `seed` | integer 0–65535 / 7 | Repeatable spatial texture |
+
+All print styles use square sampling cells. `cellSize` accepts 1–60 in the reference frame; `studioGrid` still reports any effective budget limit. It is independent of `dither.scale`. Source color and gray modes remain available. Only Pointillism's source-color mode separates pigment hues; accent mode retains the chosen ink. Risograph mixes its two screens on transparent artwork with multiply, then composes that artwork over the chosen backdrop.
+
+## Work and quality limits
+
+Compiled screen directions and texture buffers are reused. No per-cell canvas, save/rotate/clip, or new simulation loop is created. A stable still caches the complete composition. Spatial texture uses a deterministic seed and bounded lookup; source tone changes can still change coverage. Woodblock intentionally has stepped tones. Do not label it smooth continuous shading.
+
+Dense live print rendering costs more than the sample count alone: Pointillism draws four strokes per cell, Crosshatch up to three screens, and Woodblock emits carved polygons. Start with 12,000 cells, retain adaptive quality for motion, and measure the real device. High-resolution still exports can use a larger explicit budget. Keep the same reference pixel ratio/grid for preview and export.
+
+The regression suite checks geometry, normalization, scaling, deterministic texture, composition caching and every hover/motion path. CPU geometry timings exclude actual Canvas drawing, decoding, GPU work and browser frame pacing. Visual output, browser export and mobile frame-rate acceptance are still unverified; do not claim competitor parity or guaranteed FPS from these tests.

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

@@ -25,7 +25,7 @@ await studio.seek(1.5);
 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.
+Keep complete settings in application state. Apply edits with `updateStudioSettings(settings, patch)` and pass that state to `studio.update`; from 4.6 the mounted instance also exposes a detached `settings` snapshot. Serialize that snapshot or 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.
 
@@ -190,7 +190,7 @@ Example: `player.update({ motion: { type: 'trace', speed: 1, amount: .7 }, hover
 
 Use `color.gamma` to lift midtones (above 1) or deepen them (below 1), from 0.25 to 4. `color.shadows` and `color.highlights` range from −1 to 1; positive lifts that region, negative darkens it. They form a monotone curve with fixed black, middle and white anchors. This is a bounded tonal curve, not a freely editable per-channel curve graph. It cannot recover clipped source detail.
 
-`color.blackPoint` (0–0.99, default 0) and `color.whitePoint` (default 1) map the input range before gamma. White is normalized to at least 1/255 above black. These controls apply equally to all 18 renderers before dither/character conversion, preserve source alpha, and round-trip in settings. Neutral settings skip the transform. The 256-entry lookup is rebuilt on configuration changes and reused for source frames. Reset with `{ blackPoint: 0, whitePoint: 1, gamma: 1, shadows: 0, highlights: 0 }`.
+`color.blackPoint` (0–0.99, default 0) and `color.whitePoint` (default 1) map the input range before gamma. White is normalized to at least 1/255 above black. These controls apply equally to all Studio renderers before dither/character conversion, preserve source alpha, and round-trip in settings. Neutral settings skip the transform. The 256-entry lookup is rebuilt on configuration changes and reused for source frames. Reset with `{ blackPoint: 0, whitePoint: 1, gamma: 1, shadows: 0, highlights: 0 }`.
 
 `blue-noise` uses a deterministic 64×64 toroidal rank tile generated offline with void-and-cluster relaxation. It suppresses low-frequency clumping; it is not white noise with a different label. A palette-pair projection controls coverage, preserving flat grayscale means for a black/white palette at full strength. Arbitrary color palettes still approximate the source. The original palette uses web-safe channel quantization. The rank tile is 8 KiB in memory, loads only with `/studio`, and has no network request or runtime generator.
 
@@ -243,3 +243,7 @@ const saved = serializeStudioSettings(player.settings);
 ## Ordered source shaping (4.7)
 
 `warps` stores up to eight optional transforms applied in array order before all styles. `warpEdge` selects extended or transparent edges. Read [source shaping](source-shaping.md) for the nine mechanisms, controls, normalization, editor construction and dense-video cost. This is separate from art-style selection, pointer response and autonomous motion. The default stack is empty.
+
+## 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.

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

@@ -77,3 +77,7 @@ Adds optional Studio `warps` and `warpEdge` with an empty default stack. Nine tr
 ### 4.8 layered projects
 
 Adds `mountStudioProject`, `mountStudioProjectMedia`, `createStudioProjectRenderer`, `exportStudioProject` and the typed project model in optional `/studio`. Up to eight independently styled media/text layers share a playback loop and cell/raster budgets. Existing single-source APIs/defaults remain. Layered project JSON uses a distinct `kind` and source keys; it is not interchangeable with single-source settings JSON and does not contain media. See [layered-projects.md](layered-projects.md) for ownership, pointer routing, export consistency and migration choices. Refresh this skill separately from npm; do not migrate simple heroes unnecessarily.
+
+## 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.