@mlightcad/common/lib/AcCmYieldToUi.d.ts

[](https://opensource.org/licenses/MIT) [](https://www.npmjs.com/package/@mlightcad/common)

/**
 * Default work-slice budget (ms) before a cooperative UI yield during
 * main-thread work. Large enough to keep throughput high; small enough that
 * spinners and progress UI still update.
 */
export declare const ACCM_DEFAULT_UI_YIELD_BUDGET_MS = 50;
/**
 * Yields once to the event loop / next animation frame so the browser can
 * paint and handle input. Prefer this inside hot loops (time-gated via
 * {@link AcCmUiYieldGate}).
 *
 * Uses a single `requestAnimationFrame` when available (not a double-rAF),
 * falling back to `setTimeout(0)`.
 *
 * @returns Promise that resolves after one frame (or next timer tick).
 */
export declare function accmYieldToUi(): Promise<void>;
/**
 * Waits until after at least one paint (double rAF). Use sparingly — e.g. once
 * before a long sync stretch so a loading overlay can appear. Do not call this
 * per chunk on large files.
 *
 * @returns Promise that resolves after two animation frames (or one timer tick).
 */
export declare function accmYieldForPaint(): Promise<void>;
/**
 * Time-budgeted cooperative yields: only awaits {@link accmYieldToUi} when at
 * least `budgetMs` of wall time has elapsed since the previous yield completed.
 *
 * Typical usage: construct one gate per long job, then `await gate.maybeYield()`
 * inside each loop iteration.
 */
export declare class AcCmUiYieldGate {
    private readonly _budgetMs;
    /**
     * High-resolution timestamp (ms) of when the last yield finished, or when the
     * gate was constructed / {@link mark}ed.
     */
    private _lastYieldCompletedAt;
    /**
     * Creates a yield gate.
     *
     * @param _budgetMs - Minimum wall time between yields, in milliseconds.
     *   Defaults to {@link ACCM_DEFAULT_UI_YIELD_BUDGET_MS}.
     */
    constructor(_budgetMs?: number);
    /**
     * Minimum wall time between yields, in milliseconds.
     */
    get budgetMs(): number;
    /**
     * Yields when at least {@link budgetMs} has elapsed since the last completed
     * yield (or since construction / {@link mark}).
     *
     * @param yieldFn - Async yield implementation. Defaults to {@link accmYieldToUi}.
     * @returns Whether a yield actually ran.
     */
    maybeYield(yieldFn?: () => Promise<void>): Promise<boolean>;
    /**
     * Marks the timeline without yielding (e.g. after an explicit paint wait).
     * Resets the budget clock so the next {@link maybeYield} waits a full
     * {@link budgetMs} from this point.
     */
    mark(): void;
    /**
     * Current high-resolution time in milliseconds (`performance.now` when
     * available, otherwise `Date.now`).
     *
     * @returns Monotonic-ish timestamp in ms suitable for budget comparisons.
     */
    private static now;
}
//# sourceMappingURL=AcCmYieldToUi.d.ts.map