import { DimensionalUnit, DimensionalValue } from '../types';

/**
 * CSS-style length units for dimensional props.
 *
 * A dimensional prop (a shape's position/size, or any prop marked `ui.dimensional`) may carry a
 * unit, written either as a CSS-like string (`'50vw'`, `'12px'`, `'-10%'`) or in the stored object
 * form (`{ value: 50, unit: 'vw' }`). A plain number keeps its original meaning (UV — canvas
 * relative), so every existing preset resolves byte-identically.
 *
 *   px                     CSS pixels
 *   %                      the containing box (the nearest frame; the canvas until frames exist),
 *                          on props tied to an axis only: x / width → its width, y / height → its height
 *   cw  ch  cmin  cmax     1% of the canvas width / height / smaller side / larger side
 *   vw  vh  vmin  vmax     1% of the browser viewport, measured exactly as CSS does
 *   rem                    the root element's font size
 *   uv                     the legacy unit (a bare number); each conversion keeps its own meaning
 *
 * Everything here converts to CSS pixels; the callers in dimensionalProps turn pixels into the
 * shader's UV space with the conversion they already had for `px`.
 */
export declare const DIMENSIONAL_UNITS: readonly DimensionalUnit[];
/** Whether `v` is a dimensional value in its stored object form. */
export declare function isDimensionalValue(v: any): v is DimensionalValue;
/** Parses a CSS-like length string (`'50vw'`) into its object form; null when it isn't one. */
export declare function parseLength(s: string): DimensionalValue | null;
/**
 * Normalizes a raw prop value to a DimensionalValue when it carries a unit (object or string).
 * Plain numbers and everything else return null — callers keep their legacy handling for those.
 */
export declare function toDimensional(v: unknown): DimensionalValue | null;
/** Whether a raw value carries a unit that depends on the browser viewport or root font size. */
export declare function usesViewportUnits(v: unknown): boolean;
interface UnitEnvironment {
    viewportWidth: number;
    viewportHeight: number;
    rem: number;
}
/**
 * The current viewport size and root font size. Without a browser (SSR, workers, headless) the
 * viewport falls back to the canvas size and `rem` to 16.
 */
export declare function getUnitEnvironment(canvasWidth: number, canvasHeight: number): UnitEnvironment;
/** Drops the cached viewport / root font size so the next conversion re-measures. */
export declare function invalidateUnitEnvironment(): void;
/** Pins the viewport / root font size (tests, headless renders). Pass null to clear. */
export declare function setUnitEnvironmentOverride(env: Partial<UnitEnvironment> | null): void;
/**
 * Which side of the containing box a `%` value measures against. Props with no axis (a radius,
 * a stroke, a softness) don't accept `%` — CSS refuses it on such properties too.
 */
export type LengthAxis = 'x' | 'y' | 'none';
export interface LengthContext {
    /** Canvas size, CSS px. */
    canvasWidth: number;
    canvasHeight: number;
    /** The containing box `%` resolves against, CSS px. Defaults to the canvas (no frames yet). */
    boxWidth?: number;
    boxHeight?: number;
}
/** Warns once per distinct message; a bad unit on a prop animated every frame stays one line. */
export declare function warnUnitOnce(message: string): void;
/**
 * Converts a unit-carrying value to CSS pixels. Returns null for `uv` (the caller owns that
 * conversion — it differs per prop) and for a `%` on a prop with no axis (unsupported).
 */
export declare function lengthToPx(v: DimensionalValue, axis: LengthAxis, ctx: LengthContext): number | null;
export {};
//# sourceMappingURL=units.d.ts.map