@pixerate/editor 0.123.0 → 0.124.0

package/dist/gradient-KDfCvhuj.d.cts

@@ -0,0 +1,66 @@
+/**
+ * Canvas gradient models, parsing, presets, and SVG defs generation.
+ * Supports linear and radial gradients for shape fills, strokes, and freehand drawing.
+ */
+interface GradientStop {
+    offset: number;
+    color: string;
+    opacity?: number;
+}
+interface CanvasLinearGradient {
+    type: 'linear';
+    angle?: number;
+    stops: GradientStop[];
+}
+interface CanvasRadialGradient {
+    type: 'radial';
+    cx?: number;
+    cy?: number;
+    r?: number;
+    stops: GradientStop[];
+}
+type CanvasGradientDef = CanvasLinearGradient | CanvasRadialGradient;
+interface SvgGradientStop {
+    offset: string;
+    stopColor: string;
+    stopOpacity?: number;
+}
+interface SvgGradientDef {
+    id: string;
+    type: 'linear' | 'radial';
+    attrs: Record<string, string | number>;
+    stops: SvgGradientStop[];
+}
+declare const PIXERATE_BRAND_GRADIENT: CanvasLinearGradient;
+declare const CANVAS_GRADIENT_PRESETS: Record<string, CanvasLinearGradient>;
+/** Whether an arbitrary value matches a CanvasGradientDef object. */
+declare function isCanvasGradient(value: unknown): value is CanvasGradientDef;
+/**
+ * Parses CSS linear-gradient or radial-gradient strings into CanvasGradientDef.
+ * Supports forms like:
+ * - linear-gradient(90deg, #ff0000 0%, #0000ff 100%)
+ * - linear-gradient(to right, red, blue)
+ * - radial-gradient(circle, red 0%, blue 100%)
+ */
+declare function parseCssGradient(css: string): CanvasGradientDef | null;
+/**
+ * Resolves a paint value (which could be a CSS color, preset name, CSS gradient string, or CanvasGradientDef)
+ * into either a CanvasGradientDef (if gradient) or null (if solid color or invalid).
+ */
+declare function resolveCanvasGradient(value: unknown): CanvasGradientDef | null;
+/**
+ * Converts degrees clockwise (CSS angle: 0 = top, 90 = right, 180 = bottom, 270 = left)
+ * to SVG linearGradient vector coordinates (x1, y1, x2, y2) normalized [0, 1].
+ */
+declare function angleToSvgLinearCoords(angleDeg?: number): {
+    x1: number;
+    y1: number;
+    x2: number;
+    y2: number;
+};
+/**
+ * Converts a CanvasGradientDef to an SvgGradientDef descriptor ready for rendering `<linearGradient>` / `<radialGradient>`.
+ */
+declare function gradientToSvgDef(gradient: CanvasGradientDef, id: string): SvgGradientDef;
+
+export { type CanvasGradientDef as C, type GradientStop as G, PIXERATE_BRAND_GRADIENT as P, type SvgGradientDef as S, CANVAS_GRADIENT_PRESETS as a, type CanvasLinearGradient as b, type CanvasRadialGradient as c, type SvgGradientStop as d, angleToSvgLinearCoords as e, gradientToSvgDef as g, isCanvasGradient as i, parseCssGradient as p, resolveCanvasGradient as r };

package/dist/gradient-KDfCvhuj.d.ts

@@ -0,0 +1,66 @@
+/**
+ * Canvas gradient models, parsing, presets, and SVG defs generation.
+ * Supports linear and radial gradients for shape fills, strokes, and freehand drawing.
+ */
+interface GradientStop {
+    offset: number;
+    color: string;
+    opacity?: number;
+}
+interface CanvasLinearGradient {
+    type: 'linear';
+    angle?: number;
+    stops: GradientStop[];
+}
+interface CanvasRadialGradient {
+    type: 'radial';
+    cx?: number;
+    cy?: number;
+    r?: number;
+    stops: GradientStop[];
+}
+type CanvasGradientDef = CanvasLinearGradient | CanvasRadialGradient;
+interface SvgGradientStop {
+    offset: string;
+    stopColor: string;
+    stopOpacity?: number;
+}
+interface SvgGradientDef {
+    id: string;
+    type: 'linear' | 'radial';
+    attrs: Record<string, string | number>;
+    stops: SvgGradientStop[];
+}
+declare const PIXERATE_BRAND_GRADIENT: CanvasLinearGradient;
+declare const CANVAS_GRADIENT_PRESETS: Record<string, CanvasLinearGradient>;
+/** Whether an arbitrary value matches a CanvasGradientDef object. */
+declare function isCanvasGradient(value: unknown): value is CanvasGradientDef;
+/**
+ * Parses CSS linear-gradient or radial-gradient strings into CanvasGradientDef.
+ * Supports forms like:
+ * - linear-gradient(90deg, #ff0000 0%, #0000ff 100%)
+ * - linear-gradient(to right, red, blue)
+ * - radial-gradient(circle, red 0%, blue 100%)
+ */
+declare function parseCssGradient(css: string): CanvasGradientDef | null;
+/**
+ * Resolves a paint value (which could be a CSS color, preset name, CSS gradient string, or CanvasGradientDef)
+ * into either a CanvasGradientDef (if gradient) or null (if solid color or invalid).
+ */
+declare function resolveCanvasGradient(value: unknown): CanvasGradientDef | null;
+/**
+ * Converts degrees clockwise (CSS angle: 0 = top, 90 = right, 180 = bottom, 270 = left)
+ * to SVG linearGradient vector coordinates (x1, y1, x2, y2) normalized [0, 1].
+ */
+declare function angleToSvgLinearCoords(angleDeg?: number): {
+    x1: number;
+    y1: number;
+    x2: number;
+    y2: number;
+};
+/**
+ * Converts a CanvasGradientDef to an SvgGradientDef descriptor ready for rendering `<linearGradient>` / `<radialGradient>`.
+ */
+declare function gradientToSvgDef(gradient: CanvasGradientDef, id: string): SvgGradientDef;
+
+export { type CanvasGradientDef as C, type GradientStop as G, PIXERATE_BRAND_GRADIENT as P, type SvgGradientDef as S, CANVAS_GRADIENT_PRESETS as a, type CanvasLinearGradient as b, type CanvasRadialGradient as c, type SvgGradientStop as d, angleToSvgLinearCoords as e, gradientToSvgDef as g, isCanvasGradient as i, parseCssGradient as p, resolveCanvasGradient as r };

package/dist/helpers-777mC6dc.d.cts

@@ -0,0 +1,253 @@
+import { J as JsonSchema, S as SchemaValidationError } from './schema-Di0CS6Pe.cjs';
+import { F as FlairSvgAnimation } from './flair-D7BxyBwL.cjs';
+
+/**
+ * The effects contract: how an editor finds, describes and renders effects that live in another
+ * package. This library ships no effects of its own here, only the shapes a provider fills in;
+ * a host passes a provider to an editor (`setEffectsProvider`) and the editor degrades to its
+ * old behaviour without one.
+ *
+ * Every time is in milliseconds. Pixels are straight-alpha RGBA rows, top to bottom.
+ */
+
+/** How an effect is drawn: a pixel shader, an animated vector picture, or motion applied to someone else's vector art. */
+type EffectKind = 'shader' | 'vector' | 'motion';
+/**
+ * What an effect is for. An effect may have several uses.
+ *
+ * - `filter`: changes an input picture (`inputs.source`).
+ * - `transition`: blends `inputs.from` into `inputs.to`; `progress` runs 0 → 1.
+ * - `generator`: draws a picture from nothing (a background, a texture).
+ * - `overlay`: draws something meant to sit over other content, usually with transparency.
+ * - `title`: draws type or a graphic meant as a title.
+ * - `motion`: animates vector art (`applyVectorEffect`).
+ * - `interactive`: reacts to pointer, scroll or audio input at run time.
+ */
+type EffectUse = 'filter' | 'transition' | 'generator' | 'overlay' | 'title' | 'motion' | 'interactive';
+declare const EFFECT_KINDS: readonly EffectKind[];
+declare const EFFECT_USES: readonly EffectUse[];
+/** One entry of a provider's catalog. */
+interface EffectSummary {
+    /** Stable id, saved in documents. Never reused for a different effect. */
+    id: string;
+    name: string;
+    kind: EffectKind;
+    /** The provider's own grouping (e.g. `gradient`, `light`, `transition`). */
+    category: string;
+    uses: readonly EffectUse[];
+    description?: string;
+    tags?: readonly string[];
+    /** True when the effect's output has transparent pixels (it can sit over other content). */
+    transparent: boolean;
+    /** True when the effect loops; its `duration` is then one cycle. */
+    loop: boolean;
+    /** Length of one play (ms). Absent for effects that do not change over time. */
+    duration?: number;
+}
+interface EffectSearchOptions {
+    kind?: EffectKind;
+    category?: string;
+    use?: EffectUse;
+    /** Most results to return. */
+    limit?: number;
+}
+/** One control value: a number, a `#rrggbb` colour or other string, a switch, or a vector of numbers. */
+type EffectValue = number | string | boolean | readonly number[];
+type EffectValues = Readonly<Record<string, EffectValue>>;
+/**
+ * The controls of an effect as a strict JSON Schema: `type: 'object'`, `additionalProperties:
+ * false`, and a `description` on every property (with units and range). `checkEffectProvider`
+ * checks this.
+ */
+type EffectControlSchema = JsonSchema & {
+    type: 'object';
+    properties: {
+        readonly [control: string]: JsonSchema;
+    };
+    additionalProperties: false;
+};
+interface EffectPreset {
+    name: string;
+    /** Values to apply over the defaults. */
+    values: EffectValues;
+}
+/**
+ * A named input the effect reads. Filters read `source`, transitions `from` and `to`; a mask is
+ * passed separately (`EffectRenderRequest.mask`), not as an input.
+ */
+interface EffectInputSpec {
+    name: string;
+    kind: 'image' | 'audio';
+    description: string;
+    required: boolean;
+}
+/** Everything an editor needs to show an effect's controls and render it. */
+interface EffectDescription extends EffectSummary {
+    controls: EffectControlSchema;
+    /** A value for every control. */
+    defaults: EffectValues;
+    presets: readonly EffectPreset[];
+    inputs: readonly EffectInputSpec[];
+}
+/**
+ * Pixels in and out of a renderer, shaped like `ImageData`.
+ *
+ * `data` is 8-bit sRGB with straight alpha and is always present. `float`, when present, is the
+ * same picture as 32-bit floats in **linear light** (sRGB primaries), straight alpha, where colour
+ * may exceed 1. Renderers created with `depth` 16 or 32 return `float` when the provider
+ * `supportsFloat`; `data` is then its clamped sRGB encoding.
+ */
+interface EffectPixels {
+    width: number;
+    height: number;
+    data: Uint8ClampedArray;
+    float?: Float32Array;
+}
+/**
+ * An input picture. Always accepted as `EffectPixels`; a provider whose capabilities include
+ * `supportsHostImages` also takes the host's own image objects, which saves a read back.
+ */
+type EffectImageSource = EffectPixels | ImageBitmap | OffscreenCanvas | VideoFrame;
+interface EffectRendererOptions {
+    /** Output size in pixels. */
+    width: number;
+    height: number;
+    /** Bits per channel of the target (default 8). 16 and 32 ask for `float` output. */
+    depth?: 8 | 16 | 32;
+}
+interface EffectRenderRequest {
+    /** Effect time (ms), from the start of the effect. */
+    time: number;
+    /** Control values; missing controls take their defaults. Invalid values reject with `EffectControlError`. */
+    values?: EffectValues;
+    /** Pictures for the effect's named inputs (see `EffectDescription.inputs`). */
+    inputs?: Readonly<Record<string, EffectImageSource>>;
+    /** Coverage (alpha channel, 0 = untouched) limiting where the effect applies. Only with `supportsMask`. */
+    mask?: EffectImageSource;
+    /** Transitions: how far from `from` to `to`, 0–1. Defaults to `time / duration`. */
+    progress?: number;
+}
+/** A live renderer for one effect at one size. Not safe for concurrent `render` calls. */
+interface EffectRenderer {
+    readonly effectId: string;
+    readonly width: number;
+    readonly height: number;
+    readonly depth: 8 | 16 | 32;
+    render(request: EffectRenderRequest): Promise<EffectPixels>;
+    /** Frees GPU or worker resources. Rendering afterwards rejects. */
+    dispose(): void;
+}
+/** One change of an animated SVG (the shape of Flair's `SvgAnimation`). */
+type EffectSvgAnimation = FlairSvgAnimation;
+/** An animated SVG: markup plus changes to its elements (the shape of Flair's `SvgMotion`). */
+interface EffectVectorMotion {
+    svg: string;
+    animate?: readonly EffectSvgAnimation[];
+    /** Length of one play (ms). */
+    duration: number;
+    loop: boolean;
+    /** Ms held on the last frame before looping. */
+    hold?: number;
+}
+/** What a vector or motion effect is applied to: SVG markup, optionally with the ids of the elements to animate (default: all). */
+type EffectVectorTarget = string | {
+    svg: string;
+    nodeIds?: readonly string[];
+};
+/** What a provider can do, so editors can degrade cleanly. */
+interface EffectProviderCapabilities {
+    /** Renders off the main thread. */
+    supportsWorker: boolean;
+    /** Returns `float` pixels for depth 16 and 32 renderers. */
+    supportsFloat: boolean;
+    /** Honours `EffectRenderRequest.mask`; otherwise the editor masks the result itself. */
+    supportsMask: boolean;
+    /** Takes `ImageBitmap`, `OffscreenCanvas` or `VideoFrame` inputs, not only `EffectPixels`. */
+    supportsHostImages: boolean;
+    /** Implements `applyVectorEffect`. */
+    supportsVector: boolean;
+    /** Largest width or height a renderer accepts (px). */
+    maxSize?: number;
+}
+type MaybePromise<T> = T | Promise<T>;
+/**
+ * A source of effects. Implementations live outside this library (for example Flair's
+ * `flairEffects()`); `createFakeEffectProvider` is a small reference implementation.
+ *
+ * Unknown ids reject or throw `UnknownEffectError`, invalid values `EffectControlError`, and an
+ * operation the provider cannot do `EffectUnsupportedError`.
+ */
+interface EffectProvider {
+    /** Stable id of the provider, saved next to effect ids (e.g. `flair`). */
+    readonly id: string;
+    readonly name: string;
+    readonly version?: string;
+    readonly capabilities: EffectProviderCapabilities;
+    list(options?: EffectSearchOptions): MaybePromise<readonly EffectSummary[]>;
+    /** Effects matching every word of `query` (in name, id, category, tags or description), best first. */
+    search(query: string, options?: EffectSearchOptions): MaybePromise<readonly EffectSummary[]>;
+    describe(id: string): MaybePromise<EffectDescription>;
+    /** A pixel renderer. A `vector` effect may refuse with `EffectUnsupportedError` where it cannot lay out SVG (a Worker). */
+    createRenderer(id: string, options: EffectRendererOptions): MaybePromise<EffectRenderer>;
+    /**
+     * Vector and motion effects as an animated SVG. Present when `capabilities.supportsVector`. A
+     * `motion` effect animates the target's elements (`nodeIds`, else each top-level element with an
+     * id); a `vector` effect brings its own picture and ignores the target. Refuse a target the
+     * effect cannot use with `EffectUnsupportedError`.
+     */
+    applyVectorEffect?(id: string, target: EffectVectorTarget, values?: EffectValues): MaybePromise<EffectVectorMotion>;
+}
+
+/**
+ * Helpers for providers and editors: value validation, catalog search, pixel buffers, masking,
+ * and a provider slot editors hold.
+ */
+
+/** Problems with `values` against an effect's control schema (unknown controls, types, ranges). Partial values are fine. */
+declare function effectValueErrors(description: Pick<EffectDescription, 'controls'>, values: unknown): SchemaValidationError[];
+/**
+ * `values` over the effect's defaults, validated against its control schema. Throws
+ * `EffectControlError` naming every bad control. Providers call this in `render`; editors call
+ * it before saving values.
+ */
+declare function resolveEffectValues(description: Pick<EffectDescription, 'id' | 'controls' | 'defaults'>, values?: EffectValues): Record<string, EffectValues[string]>;
+/**
+ * Filters a catalog and ranks it against `query` (every word must appear in the id, name,
+ * category, tags or description; name matches rank first). An empty query keeps catalog order.
+ * Providers can implement `list` and `search` with it.
+ */
+declare function searchEffectSummaries<T extends EffectSummary>(catalog: readonly T[], query?: string, options?: EffectSearchOptions): T[];
+/** A transparent picture, with float samples when `float` is set. */
+declare function createEffectPixels(width: number, height: number, float?: boolean): EffectPixels;
+/** True for an `EffectPixels` (rather than a host image object). */
+declare function isEffectPixels(source: EffectImageSource | unknown): source is EffectPixels;
+/** sRGB-encoded 0–1 to linear light. */
+declare const srgbToLinear: (v: number) => number;
+/** Linear light to sRGB-encoded (clamped below at 0; may exceed 1). */
+declare const linearToSrgb: (v: number) => number;
+/** Fills `pixels.data` from `pixels.float` (linear float to clamped 8-bit sRGB). */
+declare function encodeEffectFloat(pixels: EffectPixels): EffectPixels;
+/**
+ * Blends an effect `result` back over its `source` by `mask` coverage (alpha channel), in place
+ * on `result`: where the mask is 0 the source shows, where it is 255 the result. Without a
+ * source (generators), the result's alpha is multiplied by coverage. Editors use it when the
+ * provider does not `supportsMask`. All three must have the same size.
+ */
+declare function applyEffectMask(result: EffectPixels, mask: EffectPixels, source?: EffectPixels): EffectPixels;
+/**
+ * Holds an editor's effects provider. Controllers expose it as `effectsProvider`,
+ * `setEffectsProvider(provider | null)` and `useEffects(provider)`; listeners hear every change.
+ */
+declare class EffectsSlot {
+    private current;
+    private readonly listeners;
+    get provider(): EffectProvider | null;
+    set(provider: EffectProvider | null): void;
+    /** Sets `provider` and returns a function that clears it again (if it is still the one set). */
+    use(provider: EffectProvider): () => void;
+    /** The provider, or a `NoEffectsProviderError`. */
+    require(): EffectProvider;
+    subscribe(listener: (provider: EffectProvider | null) => void): () => void;
+}
+
+export { isEffectPixels as A, linearToSrgb as B, resolveEffectValues as C, searchEffectSummaries as D, type EffectProvider as E, srgbToLinear as F, type EffectUse as a, type EffectProviderCapabilities as b, type EffectRenderRequest as c, type EffectValue as d, type EffectDescription as e, type EffectPixels as f, type EffectSummary as g, EFFECT_KINDS as h, EFFECT_USES as i, type EffectControlSchema as j, type EffectImageSource as k, type EffectInputSpec as l, type EffectKind as m, type EffectPreset as n, type EffectRenderer as o, type EffectRendererOptions as p, type EffectSearchOptions as q, type EffectSvgAnimation as r, type EffectValues as s, type EffectVectorMotion as t, type EffectVectorTarget as u, EffectsSlot as v, applyEffectMask as w, createEffectPixels as x, effectValueErrors as y, encodeEffectFloat as z };

package/dist/helpers-DX2_7L5t.d.ts

@@ -0,0 +1,253 @@
+import { J as JsonSchema, S as SchemaValidationError } from './schema-Di0CS6Pe.js';
+import { F as FlairSvgAnimation } from './flair-CxB3fOcU.js';
+
+/**
+ * The effects contract: how an editor finds, describes and renders effects that live in another
+ * package. This library ships no effects of its own here, only the shapes a provider fills in;
+ * a host passes a provider to an editor (`setEffectsProvider`) and the editor degrades to its
+ * old behaviour without one.
+ *
+ * Every time is in milliseconds. Pixels are straight-alpha RGBA rows, top to bottom.
+ */
+
+/** How an effect is drawn: a pixel shader, an animated vector picture, or motion applied to someone else's vector art. */
+type EffectKind = 'shader' | 'vector' | 'motion';
+/**
+ * What an effect is for. An effect may have several uses.
+ *
+ * - `filter`: changes an input picture (`inputs.source`).
+ * - `transition`: blends `inputs.from` into `inputs.to`; `progress` runs 0 → 1.
+ * - `generator`: draws a picture from nothing (a background, a texture).
+ * - `overlay`: draws something meant to sit over other content, usually with transparency.
+ * - `title`: draws type or a graphic meant as a title.
+ * - `motion`: animates vector art (`applyVectorEffect`).
+ * - `interactive`: reacts to pointer, scroll or audio input at run time.
+ */
+type EffectUse = 'filter' | 'transition' | 'generator' | 'overlay' | 'title' | 'motion' | 'interactive';
+declare const EFFECT_KINDS: readonly EffectKind[];
+declare const EFFECT_USES: readonly EffectUse[];
+/** One entry of a provider's catalog. */
+interface EffectSummary {
+    /** Stable id, saved in documents. Never reused for a different effect. */
+    id: string;
+    name: string;
+    kind: EffectKind;
+    /** The provider's own grouping (e.g. `gradient`, `light`, `transition`). */
+    category: string;
+    uses: readonly EffectUse[];
+    description?: string;
+    tags?: readonly string[];
+    /** True when the effect's output has transparent pixels (it can sit over other content). */
+    transparent: boolean;
+    /** True when the effect loops; its `duration` is then one cycle. */
+    loop: boolean;
+    /** Length of one play (ms). Absent for effects that do not change over time. */
+    duration?: number;
+}
+interface EffectSearchOptions {
+    kind?: EffectKind;
+    category?: string;
+    use?: EffectUse;
+    /** Most results to return. */
+    limit?: number;
+}
+/** One control value: a number, a `#rrggbb` colour or other string, a switch, or a vector of numbers. */
+type EffectValue = number | string | boolean | readonly number[];
+type EffectValues = Readonly<Record<string, EffectValue>>;
+/**
+ * The controls of an effect as a strict JSON Schema: `type: 'object'`, `additionalProperties:
+ * false`, and a `description` on every property (with units and range). `checkEffectProvider`
+ * checks this.
+ */
+type EffectControlSchema = JsonSchema & {
+    type: 'object';
+    properties: {
+        readonly [control: string]: JsonSchema;
+    };
+    additionalProperties: false;
+};
+interface EffectPreset {
+    name: string;
+    /** Values to apply over the defaults. */
+    values: EffectValues;
+}
+/**
+ * A named input the effect reads. Filters read `source`, transitions `from` and `to`; a mask is
+ * passed separately (`EffectRenderRequest.mask`), not as an input.
+ */
+interface EffectInputSpec {
+    name: string;
+    kind: 'image' | 'audio';
+    description: string;
+    required: boolean;
+}
+/** Everything an editor needs to show an effect's controls and render it. */
+interface EffectDescription extends EffectSummary {
+    controls: EffectControlSchema;
+    /** A value for every control. */
+    defaults: EffectValues;
+    presets: readonly EffectPreset[];
+    inputs: readonly EffectInputSpec[];
+}
+/**
+ * Pixels in and out of a renderer, shaped like `ImageData`.
+ *
+ * `data` is 8-bit sRGB with straight alpha and is always present. `float`, when present, is the
+ * same picture as 32-bit floats in **linear light** (sRGB primaries), straight alpha, where colour
+ * may exceed 1. Renderers created with `depth` 16 or 32 return `float` when the provider
+ * `supportsFloat`; `data` is then its clamped sRGB encoding.
+ */
+interface EffectPixels {
+    width: number;
+    height: number;
+    data: Uint8ClampedArray;
+    float?: Float32Array;
+}
+/**
+ * An input picture. Always accepted as `EffectPixels`; a provider whose capabilities include
+ * `supportsHostImages` also takes the host's own image objects, which saves a read back.
+ */
+type EffectImageSource = EffectPixels | ImageBitmap | OffscreenCanvas | VideoFrame;
+interface EffectRendererOptions {
+    /** Output size in pixels. */
+    width: number;
+    height: number;
+    /** Bits per channel of the target (default 8). 16 and 32 ask for `float` output. */
+    depth?: 8 | 16 | 32;
+}
+interface EffectRenderRequest {
+    /** Effect time (ms), from the start of the effect. */
+    time: number;
+    /** Control values; missing controls take their defaults. Invalid values reject with `EffectControlError`. */
+    values?: EffectValues;
+    /** Pictures for the effect's named inputs (see `EffectDescription.inputs`). */
+    inputs?: Readonly<Record<string, EffectImageSource>>;
+    /** Coverage (alpha channel, 0 = untouched) limiting where the effect applies. Only with `supportsMask`. */
+    mask?: EffectImageSource;
+    /** Transitions: how far from `from` to `to`, 0–1. Defaults to `time / duration`. */
+    progress?: number;
+}
+/** A live renderer for one effect at one size. Not safe for concurrent `render` calls. */
+interface EffectRenderer {
+    readonly effectId: string;
+    readonly width: number;
+    readonly height: number;
+    readonly depth: 8 | 16 | 32;
+    render(request: EffectRenderRequest): Promise<EffectPixels>;
+    /** Frees GPU or worker resources. Rendering afterwards rejects. */
+    dispose(): void;
+}
+/** One change of an animated SVG (the shape of Flair's `SvgAnimation`). */
+type EffectSvgAnimation = FlairSvgAnimation;
+/** An animated SVG: markup plus changes to its elements (the shape of Flair's `SvgMotion`). */
+interface EffectVectorMotion {
+    svg: string;
+    animate?: readonly EffectSvgAnimation[];
+    /** Length of one play (ms). */
+    duration: number;
+    loop: boolean;
+    /** Ms held on the last frame before looping. */
+    hold?: number;
+}
+/** What a vector or motion effect is applied to: SVG markup, optionally with the ids of the elements to animate (default: all). */
+type EffectVectorTarget = string | {
+    svg: string;
+    nodeIds?: readonly string[];
+};
+/** What a provider can do, so editors can degrade cleanly. */
+interface EffectProviderCapabilities {
+    /** Renders off the main thread. */
+    supportsWorker: boolean;
+    /** Returns `float` pixels for depth 16 and 32 renderers. */
+    supportsFloat: boolean;
+    /** Honours `EffectRenderRequest.mask`; otherwise the editor masks the result itself. */
+    supportsMask: boolean;
+    /** Takes `ImageBitmap`, `OffscreenCanvas` or `VideoFrame` inputs, not only `EffectPixels`. */
+    supportsHostImages: boolean;
+    /** Implements `applyVectorEffect`. */
+    supportsVector: boolean;
+    /** Largest width or height a renderer accepts (px). */
+    maxSize?: number;
+}
+type MaybePromise<T> = T | Promise<T>;
+/**
+ * A source of effects. Implementations live outside this library (for example Flair's
+ * `flairEffects()`); `createFakeEffectProvider` is a small reference implementation.
+ *
+ * Unknown ids reject or throw `UnknownEffectError`, invalid values `EffectControlError`, and an
+ * operation the provider cannot do `EffectUnsupportedError`.
+ */
+interface EffectProvider {
+    /** Stable id of the provider, saved next to effect ids (e.g. `flair`). */
+    readonly id: string;
+    readonly name: string;
+    readonly version?: string;
+    readonly capabilities: EffectProviderCapabilities;
+    list(options?: EffectSearchOptions): MaybePromise<readonly EffectSummary[]>;
+    /** Effects matching every word of `query` (in name, id, category, tags or description), best first. */
+    search(query: string, options?: EffectSearchOptions): MaybePromise<readonly EffectSummary[]>;
+    describe(id: string): MaybePromise<EffectDescription>;
+    /** A pixel renderer. A `vector` effect may refuse with `EffectUnsupportedError` where it cannot lay out SVG (a Worker). */
+    createRenderer(id: string, options: EffectRendererOptions): MaybePromise<EffectRenderer>;
+    /**
+     * Vector and motion effects as an animated SVG. Present when `capabilities.supportsVector`. A
+     * `motion` effect animates the target's elements (`nodeIds`, else each top-level element with an
+     * id); a `vector` effect brings its own picture and ignores the target. Refuse a target the
+     * effect cannot use with `EffectUnsupportedError`.
+     */
+    applyVectorEffect?(id: string, target: EffectVectorTarget, values?: EffectValues): MaybePromise<EffectVectorMotion>;
+}
+
+/**
+ * Helpers for providers and editors: value validation, catalog search, pixel buffers, masking,
+ * and a provider slot editors hold.
+ */
+
+/** Problems with `values` against an effect's control schema (unknown controls, types, ranges). Partial values are fine. */
+declare function effectValueErrors(description: Pick<EffectDescription, 'controls'>, values: unknown): SchemaValidationError[];
+/**
+ * `values` over the effect's defaults, validated against its control schema. Throws
+ * `EffectControlError` naming every bad control. Providers call this in `render`; editors call
+ * it before saving values.
+ */
+declare function resolveEffectValues(description: Pick<EffectDescription, 'id' | 'controls' | 'defaults'>, values?: EffectValues): Record<string, EffectValues[string]>;
+/**
+ * Filters a catalog and ranks it against `query` (every word must appear in the id, name,
+ * category, tags or description; name matches rank first). An empty query keeps catalog order.
+ * Providers can implement `list` and `search` with it.
+ */
+declare function searchEffectSummaries<T extends EffectSummary>(catalog: readonly T[], query?: string, options?: EffectSearchOptions): T[];
+/** A transparent picture, with float samples when `float` is set. */
+declare function createEffectPixels(width: number, height: number, float?: boolean): EffectPixels;
+/** True for an `EffectPixels` (rather than a host image object). */
+declare function isEffectPixels(source: EffectImageSource | unknown): source is EffectPixels;
+/** sRGB-encoded 0–1 to linear light. */
+declare const srgbToLinear: (v: number) => number;
+/** Linear light to sRGB-encoded (clamped below at 0; may exceed 1). */
+declare const linearToSrgb: (v: number) => number;
+/** Fills `pixels.data` from `pixels.float` (linear float to clamped 8-bit sRGB). */
+declare function encodeEffectFloat(pixels: EffectPixels): EffectPixels;
+/**
+ * Blends an effect `result` back over its `source` by `mask` coverage (alpha channel), in place
+ * on `result`: where the mask is 0 the source shows, where it is 255 the result. Without a
+ * source (generators), the result's alpha is multiplied by coverage. Editors use it when the
+ * provider does not `supportsMask`. All three must have the same size.
+ */
+declare function applyEffectMask(result: EffectPixels, mask: EffectPixels, source?: EffectPixels): EffectPixels;
+/**
+ * Holds an editor's effects provider. Controllers expose it as `effectsProvider`,
+ * `setEffectsProvider(provider | null)` and `useEffects(provider)`; listeners hear every change.
+ */
+declare class EffectsSlot {
+    private current;
+    private readonly listeners;
+    get provider(): EffectProvider | null;
+    set(provider: EffectProvider | null): void;
+    /** Sets `provider` and returns a function that clears it again (if it is still the one set). */
+    use(provider: EffectProvider): () => void;
+    /** The provider, or a `NoEffectsProviderError`. */
+    require(): EffectProvider;
+    subscribe(listener: (provider: EffectProvider | null) => void): () => void;
+}
+
+export { isEffectPixels as A, linearToSrgb as B, resolveEffectValues as C, searchEffectSummaries as D, type EffectProvider as E, srgbToLinear as F, type EffectUse as a, type EffectProviderCapabilities as b, type EffectRenderRequest as c, type EffectValue as d, type EffectDescription as e, type EffectPixels as f, type EffectSummary as g, EFFECT_KINDS as h, EFFECT_USES as i, type EffectControlSchema as j, type EffectImageSource as k, type EffectInputSpec as l, type EffectKind as m, type EffectPreset as n, type EffectRenderer as o, type EffectRendererOptions as p, type EffectSearchOptions as q, type EffectSvgAnimation as r, type EffectValues as s, type EffectVectorMotion as t, type EffectVectorTarget as u, EffectsSlot as v, applyEffectMask as w, createEffectPixels as x, effectValueErrors as y, encodeEffectFloat as z };