asciify-engine 4.6.0 → 4.8.0

package/dist/studio.d.cts

@@ -1,5 +1,5 @@
-import { S as StudioSettings, a as StudioInput } from './model-BR3qK_NW.cjs';
-export { B as BLEND_MODES, C as CHARACTER_SETS, D as DEFAULT_STUDIO_SETTINGS, b as DITHER_ALGORITHMS, c as DitherAlgorithm, d as STUDIO_CHARACTER_SETS, e as STUDIO_CURVE_CHANNELS, f as STUDIO_PALETTES, g as STUDIO_STYLES, h as StudioCurveChannel, i as StudioCurvePoint, j as StudioCurves, k as StudioLight, l as StudioMask, m as StudioStyle, n as createStudioCurveLookup, o as normalizeStudioCurve, p as normalizeStudioCurves, q as normalizeStudioSettings, r as parseStudioSettings, s as serializeStudioSettings, t as studioCrop, u as studioDimensions, v as studioGrid, w as updateStudioSettings } from './model-BR3qK_NW.cjs';
+import { S as StudioSettings, a as StudioInput, B as BLEND_MODES } from './model-fP9NdG-w.cjs';
+export { C as CHARACTER_SETS, D as DEFAULT_STUDIO_SETTINGS, b as DITHER_ALGORITHMS, c as DitherAlgorithm, M as MAX_STUDIO_WARPS, d as STUDIO_CHARACTER_SETS, e as STUDIO_CURVE_CHANNELS, f as STUDIO_PALETTES, g as STUDIO_STYLES, h as STUDIO_WARPS, i as StudioCurveChannel, j as StudioCurvePoint, k as StudioCurves, l as StudioLight, m as StudioMask, n as StudioStyle, o as StudioWarp, p as StudioWarpEdge, q as StudioWarpType, r as createStudioCurveLookup, s as normalizeStudioCurve, t as normalizeStudioCurves, u as normalizeStudioSettings, v as normalizeStudioWarps, w as parseStudioSettings, x as serializeStudioSettings, y as studioCrop, z as studioDimensions, A as studioGrid, E as updateStudioSettings } from './model-fP9NdG-w.cjs';
 import * as figlet_fonts_Wavy from 'figlet/fonts/Wavy';
 import * as figlet_fonts_Univers from 'figlet/fonts/Univers';
 import * as figlet_fonts_3_D from 'figlet/fonts/3-D';
@@ -94,7 +94,7 @@ interface StudioExportOptions {
 interface StudioExportSource {
     frame(time: number, signal?: AbortSignal): StudioSource | Promise<StudioSource>;
 }
-/** A separate renderer preserves preview state. The source callback must also be independent for video exports. */
+/** A separate renderer preserves preview state. Video sources must also be independent. */
 declare function exportStudio(source: StudioExportSource, settings: StudioSettings, options: StudioExportOptions): Promise<Blob>;
 
 interface MountStudioOptions {
@@ -184,9 +184,172 @@ declare const loaders: {
     Wavy: () => Promise<typeof figlet_fonts_Wavy>;
 };
 declare const STUDIO_TEXT_FONTS: (keyof typeof loaders)[];
-declare function createStudioText(text: string, font?: keyof typeof loaders, ink?: string): Promise<{
+declare function createStudioText(text: string, font?: keyof typeof loaders, ink?: string, background?: string | null): Promise<{
     canvas: HTMLCanvasElement;
     ascii: string;
 }>;
 
-export { type MountStudioOptions, STUDIO_LOOKS, STUDIO_TEXT_FONTS, type StudioExportFormat, type StudioExportOptions, type StudioExportSource, StudioInput, type StudioMedia, StudioSettings, type StudioSource, createStudioRenderer, createStudioText, exportStudio, loadStudioMedia, mountStudio, mountStudioMedia, restyleStudio, studioLook, studioSourceSize };
+declare const MAX_STUDIO_LAYERS = 8;
+interface StudioLayerPlacement {
+    /** Normalized center and size in the project canvas. */
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+    rotation: number;
+    flipX: boolean;
+    flipY: boolean;
+}
+interface StudioProjectLayer {
+    id: string;
+    name: string;
+    source: string;
+    visible: boolean;
+    opacity: number;
+    blend: typeof BLEND_MODES[number];
+    placement: StudioLayerPlacement;
+    settings: StudioSettings;
+}
+interface StudioProject {
+    kind: 'asciify-project';
+    version: 1;
+    width: number;
+    height: number;
+    background: string | null;
+    pointerMode: 'top' | 'all';
+    layers: StudioProjectLayer[];
+}
+type StudioLayerInput = Pick<StudioProjectLayer, 'id' | 'source'> & Partial<Omit<StudioProjectLayer, 'id' | 'source' | 'placement' | 'settings'>> & {
+    placement?: Partial<StudioLayerPlacement>;
+    settings?: StudioInput;
+};
+type StudioLayerPatch = Partial<Omit<StudioLayerInput, 'id'>>;
+type StudioProjectInput = Partial<Omit<StudioProject, 'layers'>> & {
+    layers?: StudioLayerInput[];
+};
+/** A project contains asset keys, never source files, URLs or executable code. */
+declare function normalizeStudioProject(input?: unknown): StudioProject;
+declare function updateStudioProjectLayer(project: StudioProject, id: string, patch: StudioLayerPatch): StudioProject;
+declare const serializeStudioProject: (project: StudioProject) => string;
+declare function parseStudioProject(json: string): StudioProject;
+/** No pixel readback: pointer picking uses transformed rectangular layer bounds. */
+declare function studioLayerPoint(layer: StudioProjectLayer, x: number, y: number, width: number, height: number): [number, number];
+declare function visibleStudioLayers(project: StudioProject): StudioProjectLayer[];
+/** A shared budget prevents each extra layer from multiplying the work ceiling. */
+declare function studioProjectBudget(project: StudioProject, maxCells?: number, maxRasterPixels?: number, width?: number, height?: number): {
+    id: string;
+    maxCells: number;
+    width: number;
+    height: number;
+}[];
+
+interface StudioProjectLimits {
+    maxDimension?: number;
+    maxCells?: number;
+    maxRasterPixels?: number;
+    pixelRatio?: number;
+}
+type StudioProjectFrames = ReadonlyMap<string, StudioSource>;
+/** Reusable composition renderer. No RAF, event listeners, loading or media ownership. */
+declare function createStudioProjectRenderer(canvas: HTMLCanvasElement, input?: unknown, limits?: StudioProjectLimits): {
+    canvas: HTMLCanvasElement;
+    render(frames: StudioProjectFrames, time?: number, width?: number, height?: number, motionTimes?: Readonly<Record<string, number>>): boolean;
+    configure(next: unknown): void;
+    pointer(x: number, y: number, time: number): void;
+    leave(): void;
+    invalidate(source?: string): void;
+    setBudget(value: number): void;
+    setPixelRatio(value: number): void;
+    readonly maxCells: number;
+    readonly pixelRatio: number;
+    readonly quality: {
+        id: string;
+        maxCells: number;
+        width: number;
+        height: number;
+    }[];
+    readonly active: boolean;
+    destroy(): void;
+};
+
+interface StudioProjectTextSource {
+    text: string;
+    font?: Parameters<typeof createStudioText>[1];
+    ink?: string;
+}
+type StudioProjectSource = File | string | StudioProjectTextSource;
+type StudioProjectSources = Readonly<Record<string, StudioProjectSource>>;
+type StudioProjectMedia = ReadonlyMap<string, StudioMedia>;
+
+interface MountStudioProjectOptions extends StudioProjectLimits {
+    fps?: number;
+    adaptive?: boolean;
+    signal?: AbortSignal;
+    onFrame?: (time: number, costMs: number) => void;
+    onError?: (error: Error) => void;
+    onQualityChange?: (maxCells: number) => void;
+}
+declare function mountStudioProject(canvas: HTMLCanvasElement, input: StudioProjectInput, sources: StudioProjectSources, options?: MountStudioProjectOptions): Promise<{
+    canvas: HTMLCanvasElement;
+    readonly project: StudioProject;
+    readonly time: number;
+    readonly motionTimes: {
+        [x: string]: number;
+    };
+    readonly paused: boolean;
+    readonly maxCells: number;
+    readonly pixelRatio: number;
+    readonly quality: {
+        id: string;
+        maxCells: number;
+        width: number;
+        height: number;
+    }[];
+    update: (next: StudioProjectInput) => void;
+    updateLayer: (id: string, patch: StudioLayerPatch) => void;
+    resize(w: number, h: number, pixelRatio?: number): void;
+    pause(value?: boolean): void;
+    seek(seconds: number): Promise<void>;
+    redraw(): void;
+    setBudget(value: number): void;
+    setAdaptive(value: boolean): void;
+    destroy: () => void;
+}>;
+/** Takes ownership of the supplied media. One shared RAF drives all layers. */
+declare function mountStudioProjectMedia(canvas: HTMLCanvasElement, input: StudioProjectInput, media: StudioProjectMedia, options?: MountStudioProjectOptions): {
+    canvas: HTMLCanvasElement;
+    readonly project: StudioProject;
+    readonly time: number;
+    readonly motionTimes: {
+        [x: string]: number;
+    };
+    readonly paused: boolean;
+    readonly maxCells: number;
+    readonly pixelRatio: number;
+    readonly quality: {
+        id: string;
+        maxCells: number;
+        width: number;
+        height: number;
+    }[];
+    update: (next: StudioProjectInput) => void;
+    updateLayer: (id: string, patch: StudioLayerPatch) => void;
+    resize(w: number, h: number, pixelRatio?: number): void;
+    pause(value?: boolean): void;
+    seek(seconds: number): Promise<void>;
+    redraw(): void;
+    setBudget(value: number): void;
+    setAdaptive(value: boolean): void;
+    destroy: () => void;
+};
+
+interface StudioProjectExportOptions extends Omit<StudioExportOptions, 'motionTime'> {
+    /** Phase snapshot from a mounted project, for a still after speed edits. */
+    motionTimes?: Readonly<Record<string, number>>;
+    /** Combined child-raster budget, distinct from the shared character budget. */
+    maxRasterPixels?: number;
+}
+/** Loads independent assets and never seeks, pauses or destroys a live preview. */
+declare function exportStudioProject(input: StudioProjectInput, sources: StudioProjectSources, options: StudioProjectExportOptions): Promise<Blob>;
+
+export { BLEND_MODES, MAX_STUDIO_LAYERS, type MountStudioOptions, type MountStudioProjectOptions, STUDIO_LOOKS, STUDIO_TEXT_FONTS, type StudioExportFormat, type StudioExportOptions, type StudioExportSource, StudioInput, type StudioLayerInput, type StudioLayerPatch, type StudioLayerPlacement, type StudioMedia, type StudioProject, type StudioProjectExportOptions, type StudioProjectFrames, type StudioProjectInput, type StudioProjectLayer, type StudioProjectLimits, type StudioProjectMedia, type StudioProjectSource, type StudioProjectSources, type StudioProjectTextSource, StudioSettings, type StudioSource, createStudioProjectRenderer, createStudioRenderer, createStudioText, exportStudio, exportStudioProject, loadStudioMedia, mountStudio, mountStudioMedia, mountStudioProject, mountStudioProjectMedia, normalizeStudioProject, parseStudioProject, restyleStudio, serializeStudioProject, studioLayerPoint, studioLook, studioProjectBudget, studioSourceSize, updateStudioProjectLayer, visibleStudioLayers };

package/dist/studio.d.ts

@@ -1,5 +1,5 @@
-import { S as StudioSettings, a as StudioInput } from './model-Tyu-NpVf.js';
-export { B as BLEND_MODES, C as CHARACTER_SETS, D as DEFAULT_STUDIO_SETTINGS, b as DITHER_ALGORITHMS, c as DitherAlgorithm, d as STUDIO_CHARACTER_SETS, e as STUDIO_CURVE_CHANNELS, f as STUDIO_PALETTES, g as STUDIO_STYLES, h as StudioCurveChannel, i as StudioCurvePoint, j as StudioCurves, k as StudioLight, l as StudioMask, m as StudioStyle, n as createStudioCurveLookup, o as normalizeStudioCurve, p as normalizeStudioCurves, q as normalizeStudioSettings, r as parseStudioSettings, s as serializeStudioSettings, t as studioCrop, u as studioDimensions, v as studioGrid, w as updateStudioSettings } from './model-Tyu-NpVf.js';
+import { S as StudioSettings, a as StudioInput, B as BLEND_MODES } from './model-CMKdRB30.js';
+export { C as CHARACTER_SETS, D as DEFAULT_STUDIO_SETTINGS, b as DITHER_ALGORITHMS, c as DitherAlgorithm, M as MAX_STUDIO_WARPS, d as STUDIO_CHARACTER_SETS, e as STUDIO_CURVE_CHANNELS, f as STUDIO_PALETTES, g as STUDIO_STYLES, h as STUDIO_WARPS, i as StudioCurveChannel, j as StudioCurvePoint, k as StudioCurves, l as StudioLight, m as StudioMask, n as StudioStyle, o as StudioWarp, p as StudioWarpEdge, q as StudioWarpType, r as createStudioCurveLookup, s as normalizeStudioCurve, t as normalizeStudioCurves, u as normalizeStudioSettings, v as normalizeStudioWarps, w as parseStudioSettings, x as serializeStudioSettings, y as studioCrop, z as studioDimensions, A as studioGrid, E as updateStudioSettings } from './model-CMKdRB30.js';
 import * as figlet_fonts_Wavy from 'figlet/fonts/Wavy';
 import * as figlet_fonts_Univers from 'figlet/fonts/Univers';
 import * as figlet_fonts_3_D from 'figlet/fonts/3-D';
@@ -94,7 +94,7 @@ interface StudioExportOptions {
 interface StudioExportSource {
     frame(time: number, signal?: AbortSignal): StudioSource | Promise<StudioSource>;
 }
-/** A separate renderer preserves preview state. The source callback must also be independent for video exports. */
+/** A separate renderer preserves preview state. Video sources must also be independent. */
 declare function exportStudio(source: StudioExportSource, settings: StudioSettings, options: StudioExportOptions): Promise<Blob>;
 
 interface MountStudioOptions {
@@ -184,9 +184,172 @@ declare const loaders: {
     Wavy: () => Promise<typeof figlet_fonts_Wavy>;
 };
 declare const STUDIO_TEXT_FONTS: (keyof typeof loaders)[];
-declare function createStudioText(text: string, font?: keyof typeof loaders, ink?: string): Promise<{
+declare function createStudioText(text: string, font?: keyof typeof loaders, ink?: string, background?: string | null): Promise<{
     canvas: HTMLCanvasElement;
     ascii: string;
 }>;
 
-export { type MountStudioOptions, STUDIO_LOOKS, STUDIO_TEXT_FONTS, type StudioExportFormat, type StudioExportOptions, type StudioExportSource, StudioInput, type StudioMedia, StudioSettings, type StudioSource, createStudioRenderer, createStudioText, exportStudio, loadStudioMedia, mountStudio, mountStudioMedia, restyleStudio, studioLook, studioSourceSize };
+declare const MAX_STUDIO_LAYERS = 8;
+interface StudioLayerPlacement {
+    /** Normalized center and size in the project canvas. */
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+    rotation: number;
+    flipX: boolean;
+    flipY: boolean;
+}
+interface StudioProjectLayer {
+    id: string;
+    name: string;
+    source: string;
+    visible: boolean;
+    opacity: number;
+    blend: typeof BLEND_MODES[number];
+    placement: StudioLayerPlacement;
+    settings: StudioSettings;
+}
+interface StudioProject {
+    kind: 'asciify-project';
+    version: 1;
+    width: number;
+    height: number;
+    background: string | null;
+    pointerMode: 'top' | 'all';
+    layers: StudioProjectLayer[];
+}
+type StudioLayerInput = Pick<StudioProjectLayer, 'id' | 'source'> & Partial<Omit<StudioProjectLayer, 'id' | 'source' | 'placement' | 'settings'>> & {
+    placement?: Partial<StudioLayerPlacement>;
+    settings?: StudioInput;
+};
+type StudioLayerPatch = Partial<Omit<StudioLayerInput, 'id'>>;
+type StudioProjectInput = Partial<Omit<StudioProject, 'layers'>> & {
+    layers?: StudioLayerInput[];
+};
+/** A project contains asset keys, never source files, URLs or executable code. */
+declare function normalizeStudioProject(input?: unknown): StudioProject;
+declare function updateStudioProjectLayer(project: StudioProject, id: string, patch: StudioLayerPatch): StudioProject;
+declare const serializeStudioProject: (project: StudioProject) => string;
+declare function parseStudioProject(json: string): StudioProject;
+/** No pixel readback: pointer picking uses transformed rectangular layer bounds. */
+declare function studioLayerPoint(layer: StudioProjectLayer, x: number, y: number, width: number, height: number): [number, number];
+declare function visibleStudioLayers(project: StudioProject): StudioProjectLayer[];
+/** A shared budget prevents each extra layer from multiplying the work ceiling. */
+declare function studioProjectBudget(project: StudioProject, maxCells?: number, maxRasterPixels?: number, width?: number, height?: number): {
+    id: string;
+    maxCells: number;
+    width: number;
+    height: number;
+}[];
+
+interface StudioProjectLimits {
+    maxDimension?: number;
+    maxCells?: number;
+    maxRasterPixels?: number;
+    pixelRatio?: number;
+}
+type StudioProjectFrames = ReadonlyMap<string, StudioSource>;
+/** Reusable composition renderer. No RAF, event listeners, loading or media ownership. */
+declare function createStudioProjectRenderer(canvas: HTMLCanvasElement, input?: unknown, limits?: StudioProjectLimits): {
+    canvas: HTMLCanvasElement;
+    render(frames: StudioProjectFrames, time?: number, width?: number, height?: number, motionTimes?: Readonly<Record<string, number>>): boolean;
+    configure(next: unknown): void;
+    pointer(x: number, y: number, time: number): void;
+    leave(): void;
+    invalidate(source?: string): void;
+    setBudget(value: number): void;
+    setPixelRatio(value: number): void;
+    readonly maxCells: number;
+    readonly pixelRatio: number;
+    readonly quality: {
+        id: string;
+        maxCells: number;
+        width: number;
+        height: number;
+    }[];
+    readonly active: boolean;
+    destroy(): void;
+};
+
+interface StudioProjectTextSource {
+    text: string;
+    font?: Parameters<typeof createStudioText>[1];
+    ink?: string;
+}
+type StudioProjectSource = File | string | StudioProjectTextSource;
+type StudioProjectSources = Readonly<Record<string, StudioProjectSource>>;
+type StudioProjectMedia = ReadonlyMap<string, StudioMedia>;
+
+interface MountStudioProjectOptions extends StudioProjectLimits {
+    fps?: number;
+    adaptive?: boolean;
+    signal?: AbortSignal;
+    onFrame?: (time: number, costMs: number) => void;
+    onError?: (error: Error) => void;
+    onQualityChange?: (maxCells: number) => void;
+}
+declare function mountStudioProject(canvas: HTMLCanvasElement, input: StudioProjectInput, sources: StudioProjectSources, options?: MountStudioProjectOptions): Promise<{
+    canvas: HTMLCanvasElement;
+    readonly project: StudioProject;
+    readonly time: number;
+    readonly motionTimes: {
+        [x: string]: number;
+    };
+    readonly paused: boolean;
+    readonly maxCells: number;
+    readonly pixelRatio: number;
+    readonly quality: {
+        id: string;
+        maxCells: number;
+        width: number;
+        height: number;
+    }[];
+    update: (next: StudioProjectInput) => void;
+    updateLayer: (id: string, patch: StudioLayerPatch) => void;
+    resize(w: number, h: number, pixelRatio?: number): void;
+    pause(value?: boolean): void;
+    seek(seconds: number): Promise<void>;
+    redraw(): void;
+    setBudget(value: number): void;
+    setAdaptive(value: boolean): void;
+    destroy: () => void;
+}>;
+/** Takes ownership of the supplied media. One shared RAF drives all layers. */
+declare function mountStudioProjectMedia(canvas: HTMLCanvasElement, input: StudioProjectInput, media: StudioProjectMedia, options?: MountStudioProjectOptions): {
+    canvas: HTMLCanvasElement;
+    readonly project: StudioProject;
+    readonly time: number;
+    readonly motionTimes: {
+        [x: string]: number;
+    };
+    readonly paused: boolean;
+    readonly maxCells: number;
+    readonly pixelRatio: number;
+    readonly quality: {
+        id: string;
+        maxCells: number;
+        width: number;
+        height: number;
+    }[];
+    update: (next: StudioProjectInput) => void;
+    updateLayer: (id: string, patch: StudioLayerPatch) => void;
+    resize(w: number, h: number, pixelRatio?: number): void;
+    pause(value?: boolean): void;
+    seek(seconds: number): Promise<void>;
+    redraw(): void;
+    setBudget(value: number): void;
+    setAdaptive(value: boolean): void;
+    destroy: () => void;
+};
+
+interface StudioProjectExportOptions extends Omit<StudioExportOptions, 'motionTime'> {
+    /** Phase snapshot from a mounted project, for a still after speed edits. */
+    motionTimes?: Readonly<Record<string, number>>;
+    /** Combined child-raster budget, distinct from the shared character budget. */
+    maxRasterPixels?: number;
+}
+/** Loads independent assets and never seeks, pauses or destroys a live preview. */
+declare function exportStudioProject(input: StudioProjectInput, sources: StudioProjectSources, options: StudioProjectExportOptions): Promise<Blob>;
+
+export { BLEND_MODES, MAX_STUDIO_LAYERS, type MountStudioOptions, type MountStudioProjectOptions, STUDIO_LOOKS, STUDIO_TEXT_FONTS, type StudioExportFormat, type StudioExportOptions, type StudioExportSource, StudioInput, type StudioLayerInput, type StudioLayerPatch, type StudioLayerPlacement, type StudioMedia, type StudioProject, type StudioProjectExportOptions, type StudioProjectFrames, type StudioProjectInput, type StudioProjectLayer, type StudioProjectLimits, type StudioProjectMedia, type StudioProjectSource, type StudioProjectSources, type StudioProjectTextSource, StudioSettings, type StudioSource, createStudioProjectRenderer, createStudioRenderer, createStudioText, exportStudio, exportStudioProject, loadStudioMedia, mountStudio, mountStudioMedia, mountStudioProject, mountStudioProjectMedia, normalizeStudioProject, parseStudioProject, restyleStudio, serializeStudioProject, studioLayerPoint, studioLook, studioProjectBudget, studioSourceSize, updateStudioProjectLayer, visibleStudioLayers };