ranui/dist/components/token-meter/index.d.ts

A framework-agnostic Web Components UI library built on native custom elements, with TypeScript types, light/dark theming, SSR and PWA support.

import { RanElement } from '../../utils';
/** How full the context window is. */
export type TokenMeterLevel = 'ok' | 'warn' | 'over';
/**
 * `<r-token-meter>` — how much of the context window a conversation is using.
 *
 * Every chat client that omits this works for a week and then stops working: each turn
 * carries the whole history, the request grows monotonically, and one day the provider
 * refuses it. The refusal arrives as a wall. This is the instrument that makes the growth
 * visible before then.
 *
 * ```ts
 * const meter = document.querySelector('r-token-meter');
 * meter.limit = 65536;
 * meter.used = 41200;      // context the next request will carry
 * meter.spent = 128431;    // tokens billed across the conversation, optional
 * ```
 *
 * `level` is reflected (`ok` / `warn` / `over`) so a page can react to the same escalation
 * the bar shows, and `title` always states the numbers — colour is never the only carrier.
 *
 * Attributes: `limit`, `used`, `spent`, `label`, `sheet`. `level` is set by the element and
 * writing it from outside is overwritten on the next update.
 */
export declare class TokenMeter extends RanElement {
    _shadowDom: ShadowRoot;
    _fill: HTMLElement;
    _text: HTMLElement;
    _root: HTMLElement;
    static get observedAttributes(): string[];
    constructor();
    /** Context window size in tokens. Zero or absent hides the bar and shows only counts. */
    get limit(): number;
    set limit(value: number);
    /** Tokens the next request will carry — the history, not the whole conversation. */
    get used(): number;
    set used(value: number);
    /**
     * Tokens billed across the conversation so far.
     *
     * Distinct from {@link TokenMeter.used} and not derivable from it: a conversation that
     * has been compacted has spent far more than it currently carries, and that difference is
     * the whole reason someone looks at this.
     */
    get spent(): number;
    set spent(value: number);
    /** Prefix for the readout. Defaults to `Context`; an empty string leaves only the counts. */
    get label(): string;
    set label(value: string);
    /** How full the window is. Derived; assigning it is overwritten on the next update. */
    get level(): TokenMeterLevel;
    get sheet(): string;
    set sheet(value: string);
    connectedCallback(): void;
    attributeChangedCallback(name: string, old: string | null, next: string | null): void;
    handlerExternalCss: () => void;
    /**
     * Reads a numeric attribute.
     *
     * @param name The attribute.
     * @returns Its value, or zero when absent or not a usable count. A meter is decoration on
     *   someone else's screen; a malformed number must not be able to throw in a render path.
     */
    private _number;
    private _render;
}
export default TokenMeter;