asciify-engine 4.6.0 → 4.8.0

package/README.md

@@ -580,3 +580,34 @@ const settings = player.settings; // detached snapshot for save/export
 ```
 
 See [settings, normalization, processing order and performance guidance](skills/asciify-engine/references/studio-workspace.md#channel-curves-and-source-noise-46). Curves are local source controls, not another art-style alias or AI restoration.
+
+### Ordered source shaping (4.7)
+
+Combine up to eight source transformations before ASCII, dither or any Studio style: Twirl, Pinch, Spherize, Ripple, Zigzag, Shear, Smudge, Polar and Fragment. Edit strength, position and radius, plus direction/frequency where applicable. Reorder or disable stages without losing their settings; choose extended or transparent edges. Generate controls from `STUDIO_WARPS` and `MAX_STUDIO_WARPS`.
+
+```ts
+player.update({
+  warps: [{type:'sphere',amount:.3,radius:.7}, {type:'shear',amount:.15,angle:25}],
+  warpEdge:'clamp',
+  motion:{type:'parallax',amount:.5},
+});
+```
+
+The stack is static shaping; motion and pointer hover remain independent. Coordinate maps are cached across video frames, and stills reuse shaped pixels during interaction. Empty stacks are free of additional pixel work. Defaults and root/core/hover behavior remain unchanged. Dither motion also gains alpha-correct interpolation at transparent edges. See [parameters, order, persistence/export and measured CPU tradeoffs](skills/asciify-engine/references/source-shaping.md).
+
+### Layered projects (4.8)
+
+Compose up to eight image, video, GIF or text layers with independent styles, motion, hover, placement, opacity and blend modes. `mountStudioProject` owns one playback loop and a shared cell/raster budget; hidden and unchanged layers skip work. Root/core/hover entry points remain unchanged.
+
+```ts
+import { mountStudioProject } from 'asciify-engine/studio';
+const player = await mountStudioProject(canvas, { layers: [
+  { id: 'photo', source: 'image', settings: { motion: { type: 'parallax' } } },
+  { id: 'title', source: 'text', placement: { width: .8, height: .25 },
+    settings: { ink: '#b3ed82', hover: { effect: 'elastic' } } },
+] }, { image: '/your-photo.webp', text: { text: 'HELLO', font: 'Small' } });
+player.updateLayer('photo', { settings: { hover: { effect: 'water' } } });
+// player.destroy() on unmount
+```
+
+`exportStudioProject` owns independent export media, so it does not disturb the live preview. Save layouts with `serializeStudioProject`, retain/rebind source assets separately, and restore with `parseStudioProject`. See the [layered-project guide](skills/asciify-engine/references/layered-projects.md) and [typed live/export example](examples/layered-composition.ts) for geometry, picking, ownership, cancellation and performance limits. This is an optional local composition API, not a claim of complete competitor-style or FPS parity.

package/dist/core.d.cts

@@ -1,6 +1,6 @@
 import { a as AsciiOptions, A as AsciiFrame, b as ArtStyle, H as HoverEffect } from './types-D38BMBRB.cjs';
 export { c as AnimationStyle, d as AsciiCell, e as AsciiResult, C as ColorMode, D as DEFAULT_OPTIONS, f as HOVER_PRESETS, g as HoverPreset, h as HoverShape, P as PALETTE_THEMES, i as PaletteTheme, R as RenderMode, S as SourceType } from './types-D38BMBRB.cjs';
-export { C as CHARACTER_SETS, g as STUDIO_STYLES, m as StudioStyle } from './model-BR3qK_NW.cjs';
+export { C as CHARACTER_SETS, g as STUDIO_STYLES, n as StudioStyle } from './model-fP9NdG-w.cjs';
 import './hover-catalog-BeIkNwhH.cjs';
 
 /**

package/dist/core.d.ts

@@ -1,6 +1,6 @@
 import { a as AsciiOptions, A as AsciiFrame, b as ArtStyle, H as HoverEffect } from './types-C05AfrjT.js';
 export { c as AnimationStyle, d as AsciiCell, e as AsciiResult, C as ColorMode, D as DEFAULT_OPTIONS, f as HOVER_PRESETS, g as HoverPreset, h as HoverShape, P as PALETTE_THEMES, i as PaletteTheme, R as RenderMode, S as SourceType } from './types-C05AfrjT.js';
-export { C as CHARACTER_SETS, g as STUDIO_STYLES, m as StudioStyle } from './model-Tyu-NpVf.js';
+export { C as CHARACTER_SETS, g as STUDIO_STYLES, n as StudioStyle } from './model-CMKdRB30.js';
 import './hover-catalog-BeIkNwhH.js';
 
 /**

package/dist/index.d.cts

@@ -1,4 +1,4 @@
 export { c as AnimationStyle, b as ArtStyle, d as AsciiCell, A as AsciiFrame, a as AsciiOptions, e as AsciiResult, C as ColorMode, D as DEFAULT_OPTIONS, f as HOVER_PRESETS, H as HoverEffect, g as HoverPreset, h as HoverShape, P as PALETTE_THEMES, i as PaletteTheme, R as RenderMode, S as SourceType } from './types-D38BMBRB.cjs';
 export { AsciiTextFrame, AsciifyLiveVideoOptions, AsciifySimpleOptions, AsciifyVideoOptions, BigTextOptions, CanvasBleed, CanvasObjectFit, CanvasRenderSizeInput, SnapshotOptions, TextBackgroundOptions, VideoScrollScrubOptions, WebcamOptions, asciiText, asciiTextAnsi, asciify, asciifyGif, asciifyLiveVideo, asciifyText, asciifyVideo, asciifyWebcam, buildTextFrame, captureSnapshot, clearAsciifyCaches, computeCanvasRenderSize, createVideoScrollScrub, gifToAsciiFrames, gifToAsciiTextFrames, imageToAsciiFrame, imageToAsciiTextFrame, renderFrameToCanvas, renderTextBackground, renderTextFrameToCanvas, renderTextToCanvas, snapshotAndDownload, videoToAsciiFrames, videoToAsciiTextFrames } from './core.cjs';
-export { C as CHARACTER_SETS, g as STUDIO_STYLES, m as StudioStyle } from './model-BR3qK_NW.cjs';
+export { C as CHARACTER_SETS, g as STUDIO_STYLES, n as StudioStyle } from './model-fP9NdG-w.cjs';
 import './hover-catalog-BeIkNwhH.cjs';

package/dist/index.d.ts

@@ -1,4 +1,4 @@
 export { c as AnimationStyle, b as ArtStyle, d as AsciiCell, A as AsciiFrame, a as AsciiOptions, e as AsciiResult, C as ColorMode, D as DEFAULT_OPTIONS, f as HOVER_PRESETS, H as HoverEffect, g as HoverPreset, h as HoverShape, P as PALETTE_THEMES, i as PaletteTheme, R as RenderMode, S as SourceType } from './types-C05AfrjT.js';
 export { AsciiTextFrame, AsciifyLiveVideoOptions, AsciifySimpleOptions, AsciifyVideoOptions, BigTextOptions, CanvasBleed, CanvasObjectFit, CanvasRenderSizeInput, SnapshotOptions, TextBackgroundOptions, VideoScrollScrubOptions, WebcamOptions, asciiText, asciiTextAnsi, asciify, asciifyGif, asciifyLiveVideo, asciifyText, asciifyVideo, asciifyWebcam, buildTextFrame, captureSnapshot, clearAsciifyCaches, computeCanvasRenderSize, createVideoScrollScrub, gifToAsciiFrames, gifToAsciiTextFrames, imageToAsciiFrame, imageToAsciiTextFrame, renderFrameToCanvas, renderTextBackground, renderTextFrameToCanvas, renderTextToCanvas, snapshotAndDownload, videoToAsciiFrames, videoToAsciiTextFrames } from './core.js';
-export { C as CHARACTER_SETS, g as STUDIO_STYLES, m as StudioStyle } from './model-Tyu-NpVf.js';
+export { C as CHARACTER_SETS, g as STUDIO_STYLES, n as StudioStyle } from './model-CMKdRB30.js';
 import './hover-catalog-BeIkNwhH.js';

package/dist/{model-Tyu-NpVf.d.ts → model-CMKdRB30.d.ts}

@@ -84,6 +84,79 @@ declare function normalizeStudioCurves(input: unknown): StudioCurves;
  */
 declare function createStudioCurveLookup(input: unknown): Uint8Array;
 
+/** Source transformations, applied in list order before style conversion. */
+declare const STUDIO_WARPS: readonly [{
+    readonly value: "twirl";
+    readonly label: "Twirl";
+    readonly description: "Rotate the center into a smooth spiral; the outer boundary stays fixed.";
+    readonly direction: false;
+    readonly frequency: false;
+}, {
+    readonly value: "pinch";
+    readonly label: "Pinch";
+    readonly description: "Contract the center, or expand it with negative strength.";
+    readonly direction: false;
+    readonly frequency: false;
+}, {
+    readonly value: "sphere";
+    readonly label: "Spherize";
+    readonly description: "Magnify a rounded lens through the source; negative strength recedes.";
+    readonly direction: false;
+    readonly frequency: false;
+}, {
+    readonly value: "ripple";
+    readonly label: "Ripple";
+    readonly description: "Bend the image through concentric, soft-edged waves.";
+    readonly direction: false;
+    readonly frequency: true;
+}, {
+    readonly value: "zigzag";
+    readonly label: "Zigzag";
+    readonly description: "Alternate the twist in sharp, concentric bands.";
+    readonly direction: false;
+    readonly frequency: true;
+}, {
+    readonly value: "shear";
+    readonly label: "Shear";
+    readonly description: "Slant a region along an adjustable direction.";
+    readonly direction: true;
+    readonly frequency: false;
+}, {
+    readonly value: "smudge";
+    readonly label: "Smudge";
+    readonly description: "Draw a soft region of the source along one direction.";
+    readonly direction: true;
+    readonly frequency: false;
+}, {
+    readonly value: "polar";
+    readonly label: "Polar";
+    readonly description: "Unwrap a region into polar coordinates; negative strength wraps it.";
+    readonly direction: true;
+    readonly frequency: false;
+}, {
+    readonly value: "fragment";
+    readonly label: "Fragment";
+    readonly description: "Offset small source tiles into a stable fractured texture.";
+    readonly direction: true;
+    readonly frequency: true;
+}];
+type StudioWarpType = typeof STUDIO_WARPS[number]['value'];
+interface StudioWarp {
+    type: StudioWarpType;
+    enabled?: boolean;
+    amount?: number;
+    x?: number;
+    y?: number;
+    /** Radius as a fraction of the canvas's shorter side. */
+    radius?: number;
+    angle?: number;
+    frequency?: number;
+}
+type StudioWarpEdge = 'clamp' | 'transparent';
+declare const MAX_STUDIO_WARPS = 8;
+/** Unknown types are omitted, never silently converted into a different warp. */
+declare function normalizeStudioWarps(input: unknown): Required<StudioWarp>[];
+
 /** Serializable, media-independent editing state. No DOM work at import time. */
 declare const STUDIO_STYLES: readonly ["ascii", "blocks", "braille", "dots", "lines", "cross", "diagonal", "diamond", "mixed", "pixel", "mosaic", "lego", "voxel", "disco", "dither", "hex", "led", "cmyk"];
 type StudioStyle = (typeof STUDIO_STYLES)[number];
@@ -121,6 +194,8 @@ interface StudioSettings {
         zoom: number;
         rotation: number;
     };
+    warps?: StudioWarp[];
+    warpEdge?: StudioWarpEdge;
     backdrop: {
         mode: "solid" | "transparent" | "source" | "blurred" | "gradient";
         color: string;
@@ -225,4 +300,4 @@ declare function studioGrid(width: number, height: number, settings: Pick<Studio
     limited: boolean;
 };
 
-export { BLEND_MODES as B, CHARACTER_SETS as C, DEFAULT_STUDIO_SETTINGS as D, type StudioSettings as S, type StudioInput as a, DITHER_ALGORITHMS as b, type DitherAlgorithm as c, STUDIO_CHARACTER_SETS as d, STUDIO_CURVE_CHANNELS as e, STUDIO_PALETTES as f, STUDIO_STYLES as g, type StudioCurveChannel as h, type StudioCurvePoint as i, type StudioCurves as j, type StudioLight as k, type StudioMask as l, type StudioStyle as m, createStudioCurveLookup as n, normalizeStudioCurve as o, normalizeStudioCurves as p, normalizeStudioSettings as q, parseStudioSettings as r, serializeStudioSettings as s, studioCrop as t, studioDimensions as u, studioGrid as v, updateStudioSettings as w };
+export { studioGrid as A, BLEND_MODES as B, CHARACTER_SETS as C, DEFAULT_STUDIO_SETTINGS as D, updateStudioSettings as E, MAX_STUDIO_WARPS as M, type StudioSettings as S, type StudioInput as a, DITHER_ALGORITHMS as b, type DitherAlgorithm as c, STUDIO_CHARACTER_SETS as d, STUDIO_CURVE_CHANNELS as e, STUDIO_PALETTES as f, STUDIO_STYLES as g, STUDIO_WARPS as h, type StudioCurveChannel as i, type StudioCurvePoint as j, type StudioCurves as k, type StudioLight as l, type StudioMask as m, type StudioStyle as n, type StudioWarp as o, type StudioWarpEdge as p, type StudioWarpType as q, createStudioCurveLookup as r, normalizeStudioCurve as s, normalizeStudioCurves as t, normalizeStudioSettings as u, normalizeStudioWarps as v, parseStudioSettings as w, serializeStudioSettings as x, studioCrop as y, studioDimensions as z };

package/dist/{model-BR3qK_NW.d.cts → model-fP9NdG-w.d.cts}

@@ -84,6 +84,79 @@ declare function normalizeStudioCurves(input: unknown): StudioCurves;
  */
 declare function createStudioCurveLookup(input: unknown): Uint8Array;
 
+/** Source transformations, applied in list order before style conversion. */
+declare const STUDIO_WARPS: readonly [{
+    readonly value: "twirl";
+    readonly label: "Twirl";
+    readonly description: "Rotate the center into a smooth spiral; the outer boundary stays fixed.";
+    readonly direction: false;
+    readonly frequency: false;
+}, {
+    readonly value: "pinch";
+    readonly label: "Pinch";
+    readonly description: "Contract the center, or expand it with negative strength.";
+    readonly direction: false;
+    readonly frequency: false;
+}, {
+    readonly value: "sphere";
+    readonly label: "Spherize";
+    readonly description: "Magnify a rounded lens through the source; negative strength recedes.";
+    readonly direction: false;
+    readonly frequency: false;
+}, {
+    readonly value: "ripple";
+    readonly label: "Ripple";
+    readonly description: "Bend the image through concentric, soft-edged waves.";
+    readonly direction: false;
+    readonly frequency: true;
+}, {
+    readonly value: "zigzag";
+    readonly label: "Zigzag";
+    readonly description: "Alternate the twist in sharp, concentric bands.";
+    readonly direction: false;
+    readonly frequency: true;
+}, {
+    readonly value: "shear";
+    readonly label: "Shear";
+    readonly description: "Slant a region along an adjustable direction.";
+    readonly direction: true;
+    readonly frequency: false;
+}, {
+    readonly value: "smudge";
+    readonly label: "Smudge";
+    readonly description: "Draw a soft region of the source along one direction.";
+    readonly direction: true;
+    readonly frequency: false;
+}, {
+    readonly value: "polar";
+    readonly label: "Polar";
+    readonly description: "Unwrap a region into polar coordinates; negative strength wraps it.";
+    readonly direction: true;
+    readonly frequency: false;
+}, {
+    readonly value: "fragment";
+    readonly label: "Fragment";
+    readonly description: "Offset small source tiles into a stable fractured texture.";
+    readonly direction: true;
+    readonly frequency: true;
+}];
+type StudioWarpType = typeof STUDIO_WARPS[number]['value'];
+interface StudioWarp {
+    type: StudioWarpType;
+    enabled?: boolean;
+    amount?: number;
+    x?: number;
+    y?: number;
+    /** Radius as a fraction of the canvas's shorter side. */
+    radius?: number;
+    angle?: number;
+    frequency?: number;
+}
+type StudioWarpEdge = 'clamp' | 'transparent';
+declare const MAX_STUDIO_WARPS = 8;
+/** Unknown types are omitted, never silently converted into a different warp. */
+declare function normalizeStudioWarps(input: unknown): Required<StudioWarp>[];
+
 /** Serializable, media-independent editing state. No DOM work at import time. */
 declare const STUDIO_STYLES: readonly ["ascii", "blocks", "braille", "dots", "lines", "cross", "diagonal", "diamond", "mixed", "pixel", "mosaic", "lego", "voxel", "disco", "dither", "hex", "led", "cmyk"];
 type StudioStyle = (typeof STUDIO_STYLES)[number];
@@ -121,6 +194,8 @@ interface StudioSettings {
         zoom: number;
         rotation: number;
     };
+    warps?: StudioWarp[];
+    warpEdge?: StudioWarpEdge;
     backdrop: {
         mode: "solid" | "transparent" | "source" | "blurred" | "gradient";
         color: string;
@@ -225,4 +300,4 @@ declare function studioGrid(width: number, height: number, settings: Pick<Studio
     limited: boolean;
 };
 
-export { BLEND_MODES as B, CHARACTER_SETS as C, DEFAULT_STUDIO_SETTINGS as D, type StudioSettings as S, type StudioInput as a, DITHER_ALGORITHMS as b, type DitherAlgorithm as c, STUDIO_CHARACTER_SETS as d, STUDIO_CURVE_CHANNELS as e, STUDIO_PALETTES as f, STUDIO_STYLES as g, type StudioCurveChannel as h, type StudioCurvePoint as i, type StudioCurves as j, type StudioLight as k, type StudioMask as l, type StudioStyle as m, createStudioCurveLookup as n, normalizeStudioCurve as o, normalizeStudioCurves as p, normalizeStudioSettings as q, parseStudioSettings as r, serializeStudioSettings as s, studioCrop as t, studioDimensions as u, studioGrid as v, updateStudioSettings as w };
+export { studioGrid as A, BLEND_MODES as B, CHARACTER_SETS as C, DEFAULT_STUDIO_SETTINGS as D, updateStudioSettings as E, MAX_STUDIO_WARPS as M, type StudioSettings as S, type StudioInput as a, DITHER_ALGORITHMS as b, type DitherAlgorithm as c, STUDIO_CHARACTER_SETS as d, STUDIO_CURVE_CHANNELS as e, STUDIO_PALETTES as f, STUDIO_STYLES as g, STUDIO_WARPS as h, type StudioCurveChannel as i, type StudioCurvePoint as j, type StudioCurves as k, type StudioLight as l, type StudioMask as m, type StudioStyle as n, type StudioWarp as o, type StudioWarpEdge as p, type StudioWarpType as q, createStudioCurveLookup as r, normalizeStudioCurve as s, normalizeStudioCurves as t, normalizeStudioSettings as u, normalizeStudioWarps as v, parseStudioSettings as w, serializeStudioSettings as x, studioCrop as y, studioDimensions as z };