@miliastry/quasar 1.0.6 → 1.2.0

package/dist/types/Utils/EffectMath.d.ts

@@ -0,0 +1,643 @@
+import { type ColorStop } from './ColorMath';
+/** FNV-1a over a string → 32-bit unsigned seed. */
+export declare function hashSeed(input: string): number;
+/**
+ * Stateless hash → [0,1) for one (seed, index) pair.
+ *
+ * Stateless matters: layers are evaluated per text node and per range, in
+ * an order the user can change by dragging. A stateful generator would
+ * hand character #7 a different number depending on how the document was
+ * split into nodes. Addressing by index makes the value a pure function
+ * of the character's position.
+ */
+export declare function randAt(seed: number, index: number): number;
+/** Smooth (cosine-interpolated) value noise over a 1-D axis. */
+export declare function valueNoise(x: number, seed: number): number;
+/** Fractal Brownian motion: octaves of value noise at halving amplitude. */
+export declare function fbm(x: number, seed: number, octaves?: number): number;
+/**
+ * Variables an `expr(...)` waveform can read.
+ *
+ * `u` is the raw axis position, `t` its alias, `i`/`n` the character's
+ * index and the unit count, `line`/`col` its 2-D address, and `rnd` a
+ * deterministic per-character random draw.
+ */
+export interface ExpressionVars {
+    u: number;
+    t: number;
+    x: number;
+    i: number;
+    n: number;
+    line: number;
+    lines: number;
+    col: number;
+    cols: number;
+    word: number;
+    words: number;
+    rnd: number;
+}
+export declare const EXPRESSION_VARS: readonly (keyof ExpressionVars)[];
+export type CompiledExpression = (vars: ExpressionVars) => number;
+/**
+ * Validate that `src` is pure arithmetic over the allowed vocabulary.
+ *
+ * The check is allowlist-based in both directions: every identifier must
+ * be a known variable or `Math` member, and every remaining character
+ * must be an operator or a digit. That rejects property access
+ * (`constructor`, `__proto__`), string and template literals, array and
+ * object syntax, and statement separators — the whole surface an
+ * injected payload would need — without trying to enumerate attacks.
+ */
+export declare function validateExpression(src: string): {
+    ok: true;
+} | {
+    ok: false;
+    reason: string;
+};
+/** Compile a validated expression, or return null if it is rejected. */
+export declare function compileExpression(src: string): CompiledExpression | null;
+export type WaveKind = 'none' | 'sine' | 'cosine' | 'triangle' | 'sawtooth' | 'square' | 'bounce' | 'elastic' | 'exponential' | 'pulse' | 'edges' | 'alternate' | 'noise' | 'fbm' | 'steps' | 'bezier' | 'expr';
+export declare const WAVE_KINDS: readonly WaveKind[];
+export interface WaveOptions {
+    /** How many times the waveform repeats across the axis. */
+    cycles: number;
+    /** Shifts the waveform along the axis, in cycles. */
+    phase: number;
+    /** Control points for `bezier`. */
+    bezier: readonly [number, number, number, number];
+    /** Source for `expr`. */
+    expression?: string;
+    /** Octaves for `fbm`. */
+    octaves: number;
+    /** Quantisation levels for `steps`, and post-quantisation for any wave. */
+    steps: number;
+    /** Seed for `noise` / `fbm`. */
+    seed: number;
+    /** Index used to address deterministic noise and index-parity waves. */
+    index: number;
+    /** Unit count in the scope, for index-based waves. */
+    count: number;
+    /** Full variable bag, for `expr`. */
+    vars?: ExpressionVars;
+}
+export declare const DEFAULT_WAVE_OPTIONS: WaveOptions;
+/**
+ * Evaluate a waveform at axis position `u`, returning [0,1].
+ *
+ * `cycles`/`phase` are applied first so every periodic wave shares one
+ * notion of frequency, and the non-periodic ones (`bezier`, `steps`,
+ * `edges`) read the wrapped position too so a cycles slider still does
+ * something sensible for them.
+ */
+export declare function waveform(kind: WaveKind, u: number, opts?: Partial<WaveOptions>): number;
+export declare function clamp01(v: number): number;
+export type BlendMode = 'normal' | 'multiply' | 'screen' | 'overlay' | 'darken' | 'lighten' | 'colorDodge' | 'colorBurn' | 'hardLight' | 'softLight' | 'difference' | 'exclusion' | 'hue' | 'saturation' | 'color' | 'luminosity';
+export declare const BLEND_MODES: readonly BlendMode[];
+/**
+ * Composite `layer` over `base` with a blend mode and opacity.
+ *
+ * Follows the W3C compositing spec (the same maths Photoshop uses), so
+ * the separable modes match what a designer expects and the four
+ * non-separable ones (hue/saturation/color/luminosity) transplant one
+ * property while preserving the rest.
+ */
+export declare function blendHex(base: string, layer: string, mode: BlendMode, opacity?: number): string;
+export declare function rgbToHex(r: number, g: number, b: number): string;
+/** Shift or set a colour's HSL components. Amounts are absolute. */
+export declare function adjustHsl(hex: string, opts: {
+    hue?: number;
+    sat?: number;
+    light?: number;
+    absolute?: boolean;
+}): string;
+/** Snap each channel to `levels` evenly spaced values. */
+export declare function posterizeHex(hex: string, levels: number): string;
+export declare function clampRange(v: number, min: number, max: number): number;
+/** One character's address within the document. */
+export interface CharSample {
+    /** Code-point offset in the plain text. */
+    offset: number;
+    /** True for whitespace, which carries no visual index. */
+    isSpace: boolean;
+    /** Running index among non-whitespace characters, document-wide. -1 for spaces. */
+    index: number;
+    /** Zero-based line number. */
+    line: number;
+    /** Running index among non-whitespace characters within the line. -1 for spaces. */
+    col: number;
+    /**
+     * Visual column: every character on the line counted, spaces included.
+     *
+     * `col` deliberately skips whitespace so a gradient does not spend a
+     * step of its ramp on a space — the right rule for a ramp, and the
+     * wrong one for a picture. In ASCII art the spaces ARE the layout, so
+     * `"  \u2588\u2588"` has its blocks at visual columns 2 and 3 while `col`
+     * calls them 0 and 1. A spatial effect that read `col` would shear
+     * every line left by its own indentation.
+     *
+     * Both coordinates therefore exist side by side: `col` for ramps,
+     * `rawCol` for geometry.
+     */
+    rawCol: number;
+    /** Zero-based word number, document-wide. -1 for spaces. */
+    word: number;
+}
+/** The whole document's coordinate table. */
+export interface SampleTable {
+    /** One entry per code point of the plain text. */
+    samples: CharSample[];
+    /** Non-whitespace character count. */
+    count: number;
+    lineCount: number;
+    /** Non-whitespace character count per line. */
+    lineLengths: number[];
+    /** Every-character length per line, for geometry. */
+    rawLineLengths: number[];
+    /** The widest line, in visual columns. The grid's width. */
+    maxCols: number;
+    wordCount: number;
+}
+/**
+ * Build the coordinate table for a plain-text document.
+ *
+ * Whitespace is addressed but never indexed: it keeps its offset and line
+ * so ranges can span it, but gets `index = -1` so it does not consume a
+ * step of a gradient. That is what stops "a b" from spending a third of
+ * its colour ramp on the space.
+ */
+export declare function buildSampleTable(plainText: string): SampleTable;
+/**
+ * A character range with its own local coordinate system.
+ *
+ * Local matters: a gradient applied to characters 40–60 should run its
+ * full ramp across those twenty characters, not show the slice of a
+ * document-wide ramp that happens to fall there. Every layer reads local
+ * coordinates; only `sample` keeps the document-wide ones, for effects
+ * that deliberately want the global picture.
+ */
+export interface RangeScope {
+    start: number;
+    end: number;
+    /** Non-whitespace count inside the range. */
+    count: number;
+    /** Local index per offset, `-1` for whitespace and out-of-range. */
+    localIndex: Int32Array;
+    /** Local line number per offset, `-1` out of range. */
+    localLine: Int32Array;
+    /** Local column per offset, `-1` for whitespace and out-of-range. */
+    localCol: Int32Array;
+    /** Local word number per offset, `-1` for whitespace and out-of-range. */
+    localWord: Int32Array;
+    /**
+     * Visual column per offset, spaces counted, `-1` out of range.
+     *
+     * Unlike `localCol` this is NOT re-based per line: it keeps the
+     * document's own column so a range starting mid-line still sits where
+     * the reader sees it. `rawColMin`/`rawColMax` carry the bounding box
+     * that turns it into a [0,1] coordinate.
+     */
+    localRawCol: Int32Array;
+    /** Left edge of the range's painted bounding box, in visual columns. */
+    rawColMin: number;
+    /** Right edge of that box. Equal to `rawColMin` for a single column. */
+    rawColMax: number;
+    lineCount: number;
+    lineLengths: number[];
+    wordCount: number;
+}
+/**
+ * Derive a range's local coordinate system from the document table.
+ *
+ * Cost is O(range length) and it is computed once per compile per range,
+ * which is what lets `applyLayer` be a straight indexed lookup no matter
+ * how many layers the range stacks.
+ */
+export declare function buildRangeScope(table: SampleTable, start: number, end: number): RangeScope;
+/** A scope covering the whole document. */
+export declare function documentScope(table: SampleTable): RangeScope;
+/**
+ * How a character's address collapses into the single number `u ∈ [0,1]`
+ * that drives a layer.
+ */
+export type Axis = 'index' | 'word' | 'line' | 'column' | 'diagonal' | 'radial' | 'angular' | 'random' | 'wave' | 'spot' | 'sweep' | 'linear';
+export declare const AXES: readonly Axis[];
+/** Axes that read an origin, an angle and a radius. */
+export declare const SPATIAL_AXES: ReadonlySet<Axis>;
+/** Everything a layer needs to place one character. */
+export interface SampleContext {
+    sample: CharSample;
+    scope: RangeScope;
+    table: SampleTable;
+    /** Local index within the scope, `-1` for whitespace. */
+    local: number;
+}
+/**
+ * Width ÷ height of one character cell.
+ *
+ * Monospace faces cluster around 0.5–0.6; this is the middle of that
+ * range and the value every shape assumes unless the document says
+ * otherwise.
+ */
+export declare const DEFAULT_CELL_ASPECT = 0.55;
+/** Where a placeable effect sits and how far it reaches. */
+export interface SpatialOptions {
+    /** Origin across the box, 0 = left edge, 1 = right edge. */
+    originX: number;
+    /** Origin down the box, 0 = top, 1 = bottom. */
+    originY: number;
+    /** Rotation of `linear` and `sweep`, in degrees, clockwise from east. */
+    angle: number;
+    /** Reach of `spot` and `linear`, in units of the box's longer side. */
+    radius: number;
+    /** Width ÷ height of a character cell. */
+    aspect: number;
+}
+export declare const DEFAULT_SPATIAL: SpatialOptions;
+/**
+ * A character's place on the page, in a square-ish coordinate system.
+ *
+ * `x`/`y` are the plain [0,1] fractions across the range's painted
+ * bounding box. `w`/`h` are that box's physical proportions, normalised
+ * so the longer side is 1 — multiplying the fractions by them is what
+ * makes a circle round instead of an oval.
+ *
+ * A single-line range has no vertical extent, so every character reports
+ * `y = 0.5`: the text is one line tall and sits at its own middle. The
+ * same holds for `x` in a single-column range.
+ */
+export interface SpatialPoint {
+    x: number;
+    y: number;
+    w: number;
+    h: number;
+}
+export declare function spatialPoint(ctx: SampleContext, cellAspect?: number): SpatialPoint;
+/**
+ * Project a character onto the [0,1] axis a layer reads.
+ *
+ * `radial` and `angular` treat the range as a rectangle of lines by
+ * columns, which is what makes a multi-line block behave like a canvas
+ * rather than a single ribbon of text. They are centred and uncorrected,
+ * and stay that way: documents written against them must keep rendering
+ * identically. `spot`, `sweep` and `linear` are their placeable,
+ * aspect-corrected successors — same idea, with an origin the author
+ * chooses and a circle that comes out round.
+ */
+export declare function axisValue(axis: Axis, ctx: SampleContext, seed?: number, geo?: Partial<SpatialOptions>): number;
+export type MaskShape = 'none' | 'circle' | 'ellipse' | 'square' | 'rect' | 'diamond' | 'triangle' | 'star' | 'ring' | 'half';
+export declare const MASK_SHAPES: readonly MaskShape[];
+/** Placement and form of one layer's mask. */
+export interface MaskOptions {
+    shape: MaskShape;
+    /** Centre across the box, 0 = left edge, 1 = right edge. */
+    x: number;
+    /** Centre down the box, 0 = top, 1 = bottom. */
+    y: number;
+    /** Half-width, in units of the box's longer side. */
+    width: number;
+    /** Half-height. Read only by `ellipse` and `rect`. */
+    height: number;
+    /** Rotation in degrees, clockwise. */
+    rotate: number;
+    /**
+     * Width of the soft edge, in the same units as `width`.
+     *
+     * Zero gives a hard cut — the right choice for block art, where a
+     * half-lit character reads as a mistake. Anything above it fades, which
+     * is what stops a circle over prose from looking stamped on.
+     */
+    feather: number;
+    /** Keep what falls OUTSIDE the shape instead of inside. */
+    invert: boolean;
+    /** Points, for `star`. */
+    points: number;
+    /** Spike depth for `star` (0 = thin, 1 = polygon); thickness for `ring`. */
+    inner: number;
+    /** Width ÷ height of a character cell. */
+    aspect: number;
+}
+export declare const DEFAULT_MASK: MaskOptions;
+/**
+ * Signed distance from a character to a shape's edge, negative inside.
+ *
+ * Exported so a preview can draw the outline from the same maths that
+ * decides which characters the shape covers. Two implementations of a
+ * shape is two shapes.
+ */
+export declare function maskDistance(ctx: SampleContext, opts?: Partial<MaskOptions>): number;
+/**
+ * How strongly a mask covers one character, in [0,1].
+ *
+ * 1 is fully inside, 0 fully outside. A layer multiplies its opacity by
+ * this, so a masked layer composites exactly like an unmasked one at
+ * reduced strength — no separate code path, and stacking three masked
+ * layers is the same operation as stacking three plain ones.
+ */
+export declare function maskValue(ctx: SampleContext, opts?: Partial<MaskOptions>): number;
+/** Build the variable bag an `expr()` waveform sees for one character. */
+export declare function expressionVars(ctx: SampleContext, u: number, seed: number): {
+    u: number;
+    t: number;
+    x: number;
+    i: number;
+    n: number;
+    line: number;
+    lines: number;
+    col: number;
+    cols: number;
+    word: number;
+    words: number;
+    rnd: number;
+};
+/** Palette entries a grid can name, the transparent slot excluded. */
+export declare const PAINT_MAX_COLORS: number;
+/** An image reduced to something a tag can carry. */
+export interface PaintGrid {
+    cols: number;
+    rows: number;
+    /** Hex colours, `#RRGGBB`. At most `PAINT_MAX_COLORS` of them. */
+    palette: string[];
+    /** `rows * cols` indices into `palette`; `-1` paints nothing. */
+    cells: Int16Array;
+}
+/** Serialise a grid's cells to the alphabet. */
+export declare function stringifyPaintCells(grid: PaintGrid): string;
+/**
+ * Read a grid back from its parts.
+ *
+ * Returns `null` rather than a partial grid when the cell count does not
+ * match `cols * rows`: a grid off by one cell is sheared diagonally
+ * across the whole paragraph, which is far worse than not painting.
+ */
+export declare function parsePaintGrid(cols: number, rows: number, paletteStr: string, cellsStr: string): PaintGrid | null;
+/** Serialise a palette to the attribute form, `#` stripped. */
+export declare function stringifyPaintPalette(palette: readonly string[]): string;
+/**
+ * The colour a grid paints at a point of the box, or `undefined` for a
+ * hole.
+ *
+ * `smooth` interpolates between the four surrounding cells, which is what
+ * you want over prose — the grid is coarser than the text and hard cells
+ * read as banding. It is the wrong choice for block art, where the grid
+ * and the characters line up one to one and any interpolation invents
+ * colours that belong to neither neighbour, so it defaults off.
+ */
+export declare function samplePaintGrid(grid: PaintGrid, x: number, y: number, smooth?: boolean, perceptual?: boolean): string | undefined;
+/** Everything an effect tag can carry, after parsing. */
+export interface EffectParams {
+    /** Colour list for gradient / rainbow ramps. */
+    colors?: string[];
+    /** Raw stop list, positions included. */
+    stops?: ColorStop[];
+    axis?: Axis;
+    wave?: WaveKind;
+    cycles?: number;
+    phase?: number;
+    easing?: string;
+    bezier?: [number, number, number, number];
+    parabolaCenter?: number;
+    parabolaPower?: number;
+    invert?: boolean;
+    steps?: number;
+    octaves?: number;
+    expression?: string;
+    seed?: number;
+    unit?: EffectUnit;
+    opacity?: number;
+    perceptual?: boolean;
+    saturation?: number;
+    lightness?: number;
+    spread?: number;
+    offset?: number;
+    preserveSL?: boolean;
+    min?: number;
+    max?: number;
+    freq?: number;
+    step?: 'char' | 'word';
+    originX?: number;
+    originY?: number;
+    /** Degrees, clockwise from east. */
+    angle?: number;
+    /** Reach, in units of the box's longer side. */
+    radius?: number;
+    /** Width \u00f7 height of a character cell. */
+    aspect?: number;
+    maskShape?: MaskShape;
+    maskX?: number;
+    maskY?: number;
+    maskWidth?: number;
+    maskHeight?: number;
+    maskRotate?: number;
+    maskFeather?: number;
+    maskInvert?: boolean;
+    maskPoints?: number;
+    maskInner?: number;
+    gridCols?: number;
+    gridRows?: number;
+    /** Comma-separated hex colours, `#` stripped. */
+    palette?: string;
+    /** One character per cell, in the paint alphabet. */
+    cells?: string;
+    /** Interpolate between cells instead of snapping to the nearest. */
+    smooth?: boolean;
+    /**
+     * The colour underneath, so a partial weight has something to fade to.
+     *
+     * A colour tag paints; unlike a studio layer it has nothing to
+     * composite against, which is why `opacity` was never expressible
+     * natively. A mask makes the weight vary per character, so the question
+     * stops being avoidable: carrying the base colour is what lets a
+     * feathered edge and a partial opacity survive as one tag instead of
+     * expanding to one `[color]` per letter.
+     *
+     * Absent, a partial weight falls back to a hard cut at half strength.
+     */
+    baseColor?: string;
+    /**
+     * Position of this tag's text inside a longer effect, in visible
+     * characters. Set when one logical effect is split across several tags
+     * — a gradient down a multi-paragraph block — so each tag continues the
+     * ramp instead of restarting it.
+     */
+    globalOffset?: number;
+    /** Total visible characters of that longer effect. */
+    documentLength?: number;
+}
+export type EffectUnit = 'character' | 'word' | 'line';
+/**
+ * The stepping units, as data.
+ *
+ * The type alone cannot be enumerated at runtime, so every UI that offered
+ * these had to retype them — and a tool that wants to *validate* `unit=`
+ * had nothing to validate against at all.
+ */
+export declare const EFFECT_UNITS: readonly EffectUnit[];
+/**
+ * The axis a layer actually reads, given its stepping unit.
+ *
+ * Stepping per word while measuring per character is almost never what
+ * someone means: a word-unit gradient over "one two three" would give
+ * every word the colour of its first letter, so the ramp reached 60% of
+ * the way to its end colour and stopped. `unit` therefore promotes the
+ * default `index` axis to the matching coordinate. An axis the user
+ * chose deliberately — radial, line, random — is left alone.
+ */
+export declare function effectiveAxis(axis: Axis, unit: EffectUnit | undefined): Axis;
+/** Short attribute keys, so a tag stays readable in a document. */
+/**
+ * The attribute key each parameter is written as, and the only place that
+ * mapping exists.
+ *
+ * Exported because it is the answer to "what can be spelled inside
+ * `[gradient=…]`" — the same question `TagVocabulary` answers for the tags
+ * whose attribute is a plain enum. A consumer that retyped `pc`, `oct` or
+ * `mrat` would be a second transcription of a grammar that already has
+ * exactly one, which is the drift this module was written to end.
+ *
+ * Note this says how a parameter is SPELLED, not which effect kinds read
+ * it: `sat` is rainbow's and `min` is grow's, and a caller that offers
+ * every key on every tag would be promising things the evaluator ignores.
+ */
+export declare const EFFECT_PARAM_KEYS: {
+    readonly axis: 'axis';
+    readonly wave: 'wave';
+    readonly cycles: 'cycles';
+    readonly phase: 'phase';
+    readonly easing: 'easing';
+    readonly bezier: 'bezier';
+    readonly parabolaCenter: 'pc';
+    readonly parabolaPower: 'pp';
+    readonly invert: 'invert';
+    readonly steps: 'steps';
+    readonly octaves: 'oct';
+    readonly expression: 'expr';
+    readonly seed: 'seed';
+    readonly unit: 'unit';
+    readonly opacity: 'opacity';
+    readonly perceptual: 'oklab';
+    readonly saturation: 'sat';
+    readonly lightness: 'light';
+    readonly spread: 'spread';
+    readonly offset: 'offset';
+    readonly preserveSL: 'keepsl';
+    readonly min: 'min';
+    readonly max: 'max';
+    readonly freq: 'freq';
+    readonly step: 'step';
+    readonly originX: 'ox';
+    readonly originY: 'oy';
+    readonly angle: 'ang';
+    readonly radius: 'rad';
+    readonly aspect: 'asp';
+    readonly maskShape: 'mask';
+    readonly maskX: 'mx';
+    readonly maskY: 'my';
+    readonly maskWidth: 'mw';
+    readonly maskHeight: 'mh';
+    readonly maskRotate: 'mrot';
+    readonly maskFeather: 'mfea';
+    readonly maskInvert: 'minv';
+    readonly maskPoints: 'mpts';
+    readonly maskInner: 'mrat';
+    readonly gridCols: 'cols';
+    readonly gridRows: 'rows';
+    readonly palette: 'pal';
+    readonly cells: 'map';
+    readonly smooth: 'smooth';
+    readonly baseColor: 'base';
+    readonly globalOffset: 'at';
+    readonly documentLength: 'of';
+};
+/**
+ * Parse a stop list, `"#hex 0%, #hex 50%, #hex"`.
+ *
+ * Unpositioned stops are spread evenly between their positioned
+ * neighbours, matching CSS gradient semantics.
+ *
+ * Cached because a gradient layer asks for the same string once per
+ * character; the result is treated as immutable by every caller.
+ */
+export declare function parseColorStops(colorsStr: string): ColorStop[];
+/** Serialise stops to the canonical `"#hex 0.0%, …"` form. */
+export declare function stringifyColorStops(stops: readonly ColorStop[]): string;
+/** Parse an effect tag's attribute value into parameters. */
+export declare function parseEffectParams(value: string): EffectParams;
+/**
+ * Serialise parameters back to an attribute value.
+ *
+ * Only what differs from `defaults` is written, so a plain gradient stays
+ * `[gradient=#a,#b]` and only a configured one grows an attribute tail.
+ */
+export declare function stringifyEffectParams(params: EffectParams, defaults?: Partial<EffectParams>): string;
+/** A run of text with the style its effect computed. */
+export interface StyledSegment {
+    text: string;
+    color?: string;
+    size?: number;
+}
+/** Which effect a set of parameters describes. */
+export type EffectKind = 'gradient' | 'rainbow' | 'grow' | 'sinewave' | 'paint';
+/** The size a character has with no size effect on it, in percent. */
+export declare const NEUTRAL_SIZE = 100;
+/** Where a node sits in a larger logical effect that spans several nodes. */
+export interface EffectSpan {
+    globalOffset?: number;
+    documentLength?: number;
+}
+export declare const GRADIENT_DEFAULTS: Partial<EffectParams>;
+export declare const RAINBOW_DEFAULTS: Partial<EffectParams>;
+export declare const GROW_DEFAULTS: Partial<EffectParams>;
+export declare const PAINT_DEFAULTS: Partial<EffectParams>;
+/**
+ * The placement and mask subset of the shared defaults.
+ *
+ * Every effect kind already carries these; this names them separately so
+ * a UI can reset just the placement without touching the modulation.
+ */
+export declare const SPATIAL_DEFAULTS: Partial<EffectParams>;
+/** Read a tag's placement parameters, filling in the defaults. */
+export declare function spatialFromParams(p: EffectParams): SpatialOptions;
+/** Read a tag's mask parameters, filling in the defaults. */
+export declare function maskFromParams(p: EffectParams): MaskOptions;
+/** Read a tag's paint grid, or `null` when it carries none. */
+export declare function gridFromParams(p: EffectParams): PaintGrid | null;
+/**
+ * Evaluate an effect over a plain string, one styled run per unit.
+ *
+ * This is the single implementation the tag registry's BBCode export, the
+ * HTML renderer's preview and the studio's own compiler all call, so a
+ * document cannot render one way and export another.
+ *
+ * `span` carries the document-wide position when one logical effect is
+ * split across several nodes — without it, a gradient interrupted by a
+ * `[b]` would restart at its first colour on the other side.
+ */
+export declare function evaluateEffect(text: string, kind: EffectKind, params: EffectParams, span?: EffectSpan): StyledSegment[];
+/**
+ * Collapse neighbouring runs that resolved to the same style.
+ *
+ * Every consumer wins: the export writes `[color=#f00]ab[/color]` instead
+ * of two tags, and the preview builds one span instead of two. It matters
+ * most exactly where the output is largest — a quantised gradient, a
+ * word- or line-stepped effect, a long flat tail — which is where the
+ * 60 000-character budget actually gets spent.
+ *
+ * A whitespace run between two identical styles is absorbed rather than
+ * splitting them; between different ones it stays unstyled, so a space
+ * never picks up a colour it would have to pay a tag for.
+ */
+export declare function mergeStyledSegments(segments: StyledSegment[]): StyledSegment[];
+/**
+ * Upper-case an emitted hex colour.
+ *
+ * @remarks Exported so the studio's own compiler can apply the same rule;
+ * the two must agree byte for byte or the same document exports
+ * differently depending on which path produced it.
+ *
+ * Interpolated colours come back lower-case while a stop copied straight
+ * from the attribute keeps whatever the author typed, so a single
+ * gradient used to export `#FF0000` next to `#bf4000`. Normalising here
+ * — the one place every effect colour passes through — keeps the output
+ * uniform without touching the colour maths.
+ */
+export declare function normalizeHex(hex: string): string;