@joewinke/jatui 0.38.6 → 0.39.0

package/dist/components/agent/contextMeter.d.ts

@@ -0,0 +1,97 @@
+/**
+ * ContextMeter — pure math (DOM-free, unit-tested in tests/unit/contextMeter.test.ts).
+ *
+ * Clean-room: built from the behaviour description of a segmented
+ * context-window meter (stacked bar per token bucket, "820k / 1M (82%)",
+ * expandable breakdown, deferred buckets listed but not counted).
+ */
+export interface ContextSegment {
+    id?: string;
+    label: string;
+    tokens: number;
+    /** Listed in the breakdown with a dash; excluded from the bar and the total. */
+    deferred?: boolean;
+    /** Any CSS colour (a token var, ideally). Default: the palette slot. */
+    color?: string;
+    /** Group id — the breakdown folds members under a collapsible header row. */
+    group?: string;
+}
+export interface ContextGroup {
+    id: string;
+    label: string;
+    /** Start unfolded. Default false. */
+    defaultExpanded?: boolean;
+}
+export type ContextTone = 'normal' | 'warning' | 'error';
+/**
+ * Palette slot `i`: the six semantic theme colours, then the same six mixed
+ * toward the page surface (so they lighten in light themes and darken in dark
+ * ones), then a fainter round; cycles after 18.
+ */
+export declare function segmentColor(i: number): string;
+/** Non-negative finite token count. */
+export declare function safeTokens(n: number | null | undefined): number;
+/**
+ * Compact number: 950 → "950", 12_345 → "12.3k", 820_000 → "820k",
+ * 1_000_000 → "1M", 1_250_000 → "1.25M". At most 3 significant-ish digits,
+ * trailing zeros trimmed; rounding that reaches the next unit rolls over
+ * (999_999 → "1M").
+ */
+export declare function formatCompact(value: number): string;
+/** Whole-percent label: 0 → "0%", 0.004 → "<1%", 0.82 → "82%", 1.05 → "105%". */
+export declare function formatPercent(ratio: number): string;
+export interface MeterSegment {
+    key: string;
+    label: string;
+    tokens: number;
+    deferred: boolean;
+    color: string;
+    group?: string;
+    /** Share of the BAR (0..100). 0 for deferred segments. */
+    width: number;
+    /** tokens / max (unclamped ratio; 0 for deferred). */
+    share: number;
+}
+export interface ContextMeterModel {
+    max: number;
+    /** Sum of counted (non-deferred) tokens. */
+    used: number;
+    /** max - used, floored at 0. */
+    free: number;
+    /** used / max (unclamped; 1 when max <= 0 and anything is used). */
+    ratio: number;
+    /** Width of the free-space remainder in the bar (0..100). */
+    freeWidth: number;
+    over: boolean;
+    tone: ContextTone;
+    segments: MeterSegment[];
+}
+/**
+ * Totals, shares and bar widths. Deferred segments keep their place (and
+ * palette slot is skipped for them so bar colours stay contiguous) but count
+ * for nothing. When used > max the bar is clamped: widths are rescaled to
+ * fill exactly 100% and free space is 0.
+ */
+export declare function computeContextMeter(max: number, segments: readonly ContextSegment[], warnAt?: number): ContextMeterModel;
+export type BreakdownRow = {
+    kind: 'segment';
+    segment: MeterSegment;
+} | {
+    kind: 'group';
+    id: string;
+    label: string;
+    /** Counted tokens of the members (deferred members excluded). */
+    tokens: number;
+    share: number;
+    /** True when every member is deferred (show a dash, not 0). */
+    allDeferred: boolean;
+    members: MeterSegment[];
+};
+/**
+ * Breakdown rows in first-appearance order: ungrouped segments as-is, grouped
+ * ones folded into one group row at the position of their first member.
+ * Labels come from `groups` (unknown ids fall back to the id).
+ */
+export declare function buildBreakdown(model: ContextMeterModel, groups?: readonly ContextGroup[]): BreakdownRow[];
+/** Screen-reader value text: "820,000 of 1,000,000 tokens used (82%)". */
+export declare function meterValueText(model: ContextMeterModel, unit?: string): string;

package/dist/components/agent/contextMeter.js

@@ -0,0 +1,156 @@
+/**
+ * ContextMeter — pure math (DOM-free, unit-tested in tests/unit/contextMeter.test.ts).
+ *
+ * Clean-room: built from the behaviour description of a segmented
+ * context-window meter (stacked bar per token bucket, "820k / 1M (82%)",
+ * expandable breakdown, deferred buckets listed but not counted).
+ */
+const BASE_PALETTE = [
+    '--color-primary',
+    '--color-secondary',
+    '--color-accent',
+    '--color-info',
+    '--color-success',
+    '--color-warning'
+];
+/** How much of the base colour each later palette round keeps (mixed into base-100). */
+const MIX_ROUNDS = [100, 60, 35];
+/**
+ * Palette slot `i`: the six semantic theme colours, then the same six mixed
+ * toward the page surface (so they lighten in light themes and darken in dark
+ * ones), then a fainter round; cycles after 18.
+ */
+export function segmentColor(i) {
+    const n = BASE_PALETTE.length;
+    const slot = ((Math.floor(i) % (n * MIX_ROUNDS.length)) + n * MIX_ROUNDS.length) % (n * MIX_ROUNDS.length);
+    const base = `var(${BASE_PALETTE[slot % n]})`;
+    const pct = MIX_ROUNDS[Math.floor(slot / n)];
+    return pct === 100 ? base : `color-mix(in oklab, ${base} ${pct}%, var(--color-base-100))`;
+}
+/** Non-negative finite token count. */
+export function safeTokens(n) {
+    return typeof n === 'number' && Number.isFinite(n) && n > 0 ? n : 0;
+}
+/**
+ * Compact number: 950 → "950", 12_345 → "12.3k", 820_000 → "820k",
+ * 1_000_000 → "1M", 1_250_000 → "1.25M". At most 3 significant-ish digits,
+ * trailing zeros trimmed; rounding that reaches the next unit rolls over
+ * (999_999 → "1M").
+ */
+export function formatCompact(value) {
+    if (!Number.isFinite(value))
+        return '—';
+    const sign = value < 0 ? '-' : '';
+    let v = Math.abs(value);
+    if (v < 1000)
+        return sign + String(Math.round(v));
+    const units = ['k', 'M', 'B', 'T'];
+    let u = -1;
+    while (u < units.length - 1 && v >= 1000) {
+        v /= 1000;
+        u++;
+    }
+    const round = (x) => {
+        const d = x < 10 ? 2 : x < 100 ? 1 : 0;
+        const f = 10 ** d;
+        return Math.round(x * f) / f;
+    };
+    let r = round(v);
+    if (r >= 1000 && u < units.length - 1) {
+        u++;
+        r = round(r / 1000);
+    }
+    return `${sign}${r}${units[u]}`;
+}
+/** Whole-percent label: 0 → "0%", 0.004 → "<1%", 0.82 → "82%", 1.05 → "105%". */
+export function formatPercent(ratio) {
+    if (!Number.isFinite(ratio) || ratio <= 0)
+        return '0%';
+    const p = ratio * 100;
+    if (p < 1)
+        return '<1%';
+    // Never round a not-yet-full meter up to 100%.
+    if (p < 100 && Math.round(p) === 100)
+        return '99%';
+    return `${Math.round(p)}%`;
+}
+/**
+ * Totals, shares and bar widths. Deferred segments keep their place (and
+ * palette slot is skipped for them so bar colours stay contiguous) but count
+ * for nothing. When used > max the bar is clamped: widths are rescaled to
+ * fill exactly 100% and free space is 0.
+ */
+export function computeContextMeter(max, segments, warnAt = 0.8) {
+    const cap = safeTokens(max);
+    let used = 0;
+    for (const s of segments)
+        if (!s.deferred)
+            used += safeTokens(s.tokens);
+    const ratio = cap > 0 ? used / cap : used > 0 ? 1 : 0;
+    const over = cap > 0 ? used > cap : used > 0;
+    // Bar denominator: the window, or the overflowing total so widths sum to 100.
+    const denom = Math.max(cap, used);
+    let slot = 0;
+    const out = segments.map((s, i) => {
+        const deferred = s.deferred === true;
+        const tokens = safeTokens(s.tokens);
+        const color = s.color ?? segmentColor(deferred ? slot : slot++);
+        return {
+            key: s.id ?? `${i}:${s.label}`,
+            label: s.label,
+            tokens,
+            deferred,
+            color,
+            group: s.group,
+            width: deferred || denom === 0 ? 0 : (tokens / denom) * 100,
+            share: deferred || cap === 0 ? 0 : tokens / cap
+        };
+    });
+    const freeWidth = denom === 0 ? 100 : Math.max(0, ((cap - used) / denom) * 100);
+    const tone = ratio >= 1 ? 'error' : ratio >= warnAt ? 'warning' : 'normal';
+    return { max: cap, used, free: Math.max(0, cap - used), ratio, freeWidth, over, tone, segments: out };
+}
+/**
+ * Breakdown rows in first-appearance order: ungrouped segments as-is, grouped
+ * ones folded into one group row at the position of their first member.
+ * Labels come from `groups` (unknown ids fall back to the id).
+ */
+export function buildBreakdown(model, groups = []) {
+    const labels = new Map(groups.map((g) => [g.id, g.label]));
+    const rows = [];
+    const byGroup = new Map();
+    for (const seg of model.segments) {
+        if (seg.group == null || seg.group === '') {
+            rows.push({ kind: 'segment', segment: seg });
+            continue;
+        }
+        let row = byGroup.get(seg.group);
+        if (!row) {
+            row = {
+                kind: 'group',
+                id: seg.group,
+                label: labels.get(seg.group) ?? seg.group,
+                tokens: 0,
+                share: 0,
+                allDeferred: true,
+                members: []
+            };
+            byGroup.set(seg.group, row);
+            rows.push(row);
+        }
+        row.members.push(seg);
+        if (!seg.deferred) {
+            row.tokens += seg.tokens;
+            row.share += seg.share;
+            row.allDeferred = false;
+        }
+    }
+    return rows;
+}
+/** Screen-reader value text: "820,000 of 1,000,000 tokens used (82%)". */
+export function meterValueText(model, unit = 'tokens') {
+    const n = (x) => x.toLocaleString('en-US');
+    const u = unit ? ` ${unit}` : '';
+    const base = `${n(model.used)} of ${n(model.max)}${u} used (${formatPercent(model.ratio)})`;
+    return model.over ? `${base}, over the limit` : base;
+}

package/dist/components/agent/questionnaire.d.ts

@@ -0,0 +1,104 @@
+/**
+ * Questionnaire answer-state logic — pure, DOM-free, immutable.
+ *
+ * The question shape mirrors Claude Code's AskUserQuestion tool payload
+ * (`{ question, header, options: { label, description }[], multiSelect }`) so a
+ * host can pass a tool call's `questions` straight through, and read the
+ * answers back as one `{ values, other? }` per question (values = the picked
+ * option LABELS, in option order).
+ *
+ * "Other" state: `other === undefined` means the free-text row is not ticked;
+ * a string (possibly empty while the user is still typing) means it is. In a
+ * single-select question an option pick and "Other" are mutually exclusive.
+ */
+export interface QuestionnaireOption {
+    label: string;
+    description?: string;
+    /** Optional monospace preview (code, a diff, a layout sketch) shown while focused/selected. */
+    preview?: string;
+}
+export interface QuestionnaireQuestion {
+    question: string;
+    /** Short chip text (AskUserQuestion's `header`), used on the step pill. */
+    header?: string;
+    options: QuestionnaireOption[];
+    multiSelect?: boolean;
+}
+export interface QuestionnaireAnswer {
+    /** Selected option labels, in option order. */
+    values: string[];
+    /** Free-text "Other" answer; present = the Other row is ticked. */
+    other?: string;
+}
+export type QuestionnaireAnswers = QuestionnaireAnswer[];
+/** Direction of travel between two steps: 1 forward, -1 back, 0 none. */
+export type StepDirection = -1 | 0 | 1;
+/** Digit keys address at most nine rows (1..9). */
+export declare const MAX_DIGIT_ROWS = 9;
+/** One empty answer per question. */
+export declare function emptyAnswers(questions: readonly QuestionnaireQuestion[]): QuestionnaireAnswers;
+/**
+ * Align a (possibly missing, short, long or stale) answers array to the
+ * questions: pads with blanks, truncates extras, drops values that are not an
+ * option label any more, and keeps a single-select answer to one value.
+ */
+export declare function normalizeAnswers(questions: readonly QuestionnaireQuestion[], answers: readonly (QuestionnaireAnswer | undefined | null)[] | undefined | null): QuestionnaireAnswers;
+/**
+ * Select an option. Single-select: replaces the answer (and unticks Other).
+ * Multi-select: adds it (idempotent). Unknown labels are ignored.
+ */
+export declare function pickOption(questions: readonly QuestionnaireQuestion[], answers: QuestionnaireAnswers, index: number, label: string): QuestionnaireAnswers;
+/**
+ * Toggle an option. Multi-select: add/remove. Single-select: picks it (a radio
+ * is not un-picked by pressing it again).
+ */
+export declare function toggleOption(questions: readonly QuestionnaireQuestion[], answers: QuestionnaireAnswers, index: number, label: string): QuestionnaireAnswers;
+/**
+ * Set the Other text. Typing ticks the Other row; in single-select it also
+ * clears the option pick. Pass `undefined` to untick.
+ */
+export declare function setOther(questions: readonly QuestionnaireQuestion[], answers: QuestionnaireAnswers, index: number, text: string | undefined): QuestionnaireAnswers;
+/** Tick/untick the Other row. Ticking starts with empty text; a single-select Other row is not unticked by pressing it again. */
+export declare function toggleOther(questions: readonly QuestionnaireQuestion[], answers: QuestionnaireAnswers, index: number): QuestionnaireAnswers;
+/** Is the Other row ticked? */
+export declare function isOtherTicked(answer: QuestionnaireAnswer | undefined): boolean;
+/** An answer counts once it has a picked option or non-blank Other text. */
+export declare function isAnswered(answer: QuestionnaireAnswer | undefined): boolean;
+/** Every question answered. */
+export declare function isComplete(questions: readonly QuestionnaireQuestion[], answers: readonly QuestionnaireAnswer[]): boolean;
+/** Index of the first unanswered question, or -1. */
+export declare function firstUnanswered(questions: readonly QuestionnaireQuestion[], answers: readonly QuestionnaireAnswer[]): number;
+/**
+ * The answers handed to `onComplete`: Other text trimmed, a ticked-but-blank
+ * Other dropped, everything aligned to the questions.
+ */
+export declare function finalizeAnswers(questions: readonly QuestionnaireQuestion[], answers: readonly QuestionnaireAnswer[]): QuestionnaireAnswers;
+/** Clamp a step index into range (0 when there are no questions). */
+export declare function clampStep(step: number, count: number): number;
+export declare function nextStep(step: number, count: number): number;
+export declare function prevStep(step: number, count: number): number;
+export declare function isLastStep(step: number, count: number): boolean;
+export declare function stepDirection(from: number, to: number): StepDirection;
+/** "Question 2 of 4". */
+export declare function stepLabel(step: number, count: number): string;
+/**
+ * Map a keydown `key` to a row: option index 0..N-1, `'other'` for digit N+1
+ * when the Other row is shown, or null. Digits are 1-based; only 1..9.
+ */
+export declare function digitToRow(key: string, optionCount: number, allowOther: boolean): number | 'other' | null;
+/** The digit hint for a row (1-based), or null past 9. */
+export declare function rowDigit(row: number): string | null;
+/**
+ * Roving-tabindex focus move over `count` rows: ArrowDown/Right +1,
+ * ArrowUp/Left -1 (wrapping), Home/End. Returns null for other keys.
+ */
+export declare function moveRow(key: string, current: number, count: number): number | null;
+/** The row that carries tabindex=0 in a single-select group: the picked row, else the first. */
+export declare function tabStopRow(question: QuestionnaireQuestion | undefined, answer: QuestionnaireAnswer | undefined): number | 'other';
+/**
+ * Which option's preview to show: the focused row if it has one, else the
+ * first selected option that has one, else null.
+ */
+export declare function previewOption(question: QuestionnaireQuestion | undefined, answer: QuestionnaireAnswer | undefined, focusedRow: number | null): number | null;
+/** Does any option in the question carry a preview? (lays out the preview pane) */
+export declare function hasPreviews(question: QuestionnaireQuestion | undefined): boolean;

package/dist/components/agent/questionnaire.js

@@ -0,0 +1,225 @@
+/**
+ * Questionnaire answer-state logic — pure, DOM-free, immutable.
+ *
+ * The question shape mirrors Claude Code's AskUserQuestion tool payload
+ * (`{ question, header, options: { label, description }[], multiSelect }`) so a
+ * host can pass a tool call's `questions` straight through, and read the
+ * answers back as one `{ values, other? }` per question (values = the picked
+ * option LABELS, in option order).
+ *
+ * "Other" state: `other === undefined` means the free-text row is not ticked;
+ * a string (possibly empty while the user is still typing) means it is. In a
+ * single-select question an option pick and "Other" are mutually exclusive.
+ */
+/** Digit keys address at most nine rows (1..9). */
+export const MAX_DIGIT_ROWS = 9;
+const blank = () => ({ values: [] });
+/** One empty answer per question. */
+export function emptyAnswers(questions) {
+    return questions.map(blank);
+}
+/**
+ * Align a (possibly missing, short, long or stale) answers array to the
+ * questions: pads with blanks, truncates extras, drops values that are not an
+ * option label any more, and keeps a single-select answer to one value.
+ */
+export function normalizeAnswers(questions, answers) {
+    return questions.map((q, i) => {
+        const a = answers?.[i];
+        if (!a)
+            return blank();
+        const labels = q.options.map((o) => o.label);
+        let values = labels.filter((l) => Array.isArray(a.values) && a.values.includes(l));
+        let other = typeof a.other === 'string' ? a.other : undefined;
+        if (!q.multiSelect) {
+            if (values.length > 1)
+                values = values.slice(0, 1);
+            if (values.length && other !== undefined)
+                other = undefined;
+        }
+        return other === undefined ? { values } : { values, other };
+    });
+}
+function replaceAt(answers, index, next) {
+    if (index < 0 || index >= answers.length)
+        return answers;
+    const copy = answers.slice();
+    copy[index] = next;
+    return copy;
+}
+/** Labels of `q` in option order, keeping only those in `set`. */
+function ordered(q, set) {
+    return q.options.map((o) => o.label).filter((l) => set.has(l));
+}
+/**
+ * Select an option. Single-select: replaces the answer (and unticks Other).
+ * Multi-select: adds it (idempotent). Unknown labels are ignored.
+ */
+export function pickOption(questions, answers, index, label) {
+    const q = questions[index];
+    const a = answers[index];
+    if (!q || !a || !q.options.some((o) => o.label === label))
+        return answers;
+    if (!q.multiSelect)
+        return replaceAt(answers, index, { values: [label] });
+    if (a.values.includes(label))
+        return answers;
+    return replaceAt(answers, index, { ...a, values: ordered(q, new Set([...a.values, label])) });
+}
+/**
+ * Toggle an option. Multi-select: add/remove. Single-select: picks it (a radio
+ * is not un-picked by pressing it again).
+ */
+export function toggleOption(questions, answers, index, label) {
+    const q = questions[index];
+    const a = answers[index];
+    if (!q || !a)
+        return answers;
+    if (!q.multiSelect || !a.values.includes(label))
+        return pickOption(questions, answers, index, label);
+    return replaceAt(answers, index, { ...a, values: a.values.filter((v) => v !== label) });
+}
+/**
+ * Set the Other text. Typing ticks the Other row; in single-select it also
+ * clears the option pick. Pass `undefined` to untick.
+ */
+export function setOther(questions, answers, index, text) {
+    const q = questions[index];
+    const a = answers[index];
+    if (!q || !a)
+        return answers;
+    if (text === undefined)
+        return replaceAt(answers, index, { values: a.values });
+    return replaceAt(answers, index, { values: q.multiSelect ? a.values : [], other: text });
+}
+/** Tick/untick the Other row. Ticking starts with empty text; a single-select Other row is not unticked by pressing it again. */
+export function toggleOther(questions, answers, index) {
+    const a = answers[index];
+    if (!a)
+        return answers;
+    const q = questions[index];
+    // A single-select Other row behaves like a radio: pressing it again keeps it.
+    if (a.other !== undefined)
+        return q?.multiSelect ? setOther(questions, answers, index, undefined) : answers;
+    return setOther(questions, answers, index, '');
+}
+/** Is the Other row ticked? */
+export function isOtherTicked(answer) {
+    return answer?.other !== undefined;
+}
+/** An answer counts once it has a picked option or non-blank Other text. */
+export function isAnswered(answer) {
+    if (!answer)
+        return false;
+    return answer.values.length > 0 || (answer.other ?? '').trim().length > 0;
+}
+/** Every question answered. */
+export function isComplete(questions, answers) {
+    return questions.every((_, i) => isAnswered(answers[i]));
+}
+/** Index of the first unanswered question, or -1. */
+export function firstUnanswered(questions, answers) {
+    return questions.findIndex((_, i) => !isAnswered(answers[i]));
+}
+/**
+ * The answers handed to `onComplete`: Other text trimmed, a ticked-but-blank
+ * Other dropped, everything aligned to the questions.
+ */
+export function finalizeAnswers(questions, answers) {
+    return normalizeAnswers(questions, answers).map((a) => {
+        const other = a.other?.trim();
+        return other ? { values: a.values, other } : { values: a.values };
+    });
+}
+/** Clamp a step index into range (0 when there are no questions). */
+export function clampStep(step, count) {
+    if (count <= 0 || !Number.isFinite(step))
+        return 0;
+    return Math.min(Math.max(Math.trunc(step), 0), count - 1);
+}
+export function nextStep(step, count) {
+    return clampStep(step + 1, count);
+}
+export function prevStep(step, count) {
+    return clampStep(step - 1, count);
+}
+export function isLastStep(step, count) {
+    return count > 0 && clampStep(step, count) === count - 1;
+}
+export function stepDirection(from, to) {
+    return to > from ? 1 : to < from ? -1 : 0;
+}
+/** "Question 2 of 4". */
+export function stepLabel(step, count) {
+    return `Question ${clampStep(step, count) + 1} of ${count}`;
+}
+/**
+ * Map a keydown `key` to a row: option index 0..N-1, `'other'` for digit N+1
+ * when the Other row is shown, or null. Digits are 1-based; only 1..9.
+ */
+export function digitToRow(key, optionCount, allowOther) {
+    if (!/^[1-9]$/.test(key))
+        return null;
+    const n = Number(key) - 1;
+    if (n < Math.min(optionCount, MAX_DIGIT_ROWS))
+        return n;
+    if (allowOther && n === optionCount && n < MAX_DIGIT_ROWS)
+        return 'other';
+    return null;
+}
+/** The digit hint for a row (1-based), or null past 9. */
+export function rowDigit(row) {
+    return row >= 0 && row < MAX_DIGIT_ROWS ? String(row + 1) : null;
+}
+/**
+ * Roving-tabindex focus move over `count` rows: ArrowDown/Right +1,
+ * ArrowUp/Left -1 (wrapping), Home/End. Returns null for other keys.
+ */
+export function moveRow(key, current, count) {
+    if (count <= 0)
+        return null;
+    switch (key) {
+        case 'ArrowDown':
+        case 'ArrowRight':
+            return (current + 1 + count) % count;
+        case 'ArrowUp':
+        case 'ArrowLeft':
+            return (current - 1 + count) % count;
+        case 'Home':
+            return 0;
+        case 'End':
+            return count - 1;
+        default:
+            return null;
+    }
+}
+/** The row that carries tabindex=0 in a single-select group: the picked row, else the first. */
+export function tabStopRow(question, answer) {
+    if (!question)
+        return 0;
+    if (answer?.other !== undefined && !question.multiSelect)
+        return 'other';
+    const picked = answer?.values[0];
+    const idx = picked === undefined ? -1 : question.options.findIndex((o) => o.label === picked);
+    return idx >= 0 ? idx : 0;
+}
+/**
+ * Which option's preview to show: the focused row if it has one, else the
+ * first selected option that has one, else null.
+ */
+export function previewOption(question, answer, focusedRow) {
+    if (!question)
+        return null;
+    if (focusedRow !== null && question.options[focusedRow]?.preview)
+        return focusedRow;
+    for (const v of answer?.values ?? []) {
+        const i = question.options.findIndex((o) => o.label === v);
+        if (i >= 0 && question.options[i].preview)
+            return i;
+    }
+    return null;
+}
+/** Does any option in the question carry a preview? (lays out the preview pane) */
+export function hasPreviews(question) {
+    return !!question?.options.some((o) => o.preview);
+}

package/dist/components/agent/revealCore.d.ts

@@ -0,0 +1,74 @@
+/**
+ * Reveal ticker — the pacing core behind AgentLog / AgentTaskList.
+ *
+ * Counts how many units of a streaming log are visible. Two modes:
+ *
+ *   timer       one unit per tick: `startDelay` before the first, then
+ *               `stepInterval` between the rest, or `delayFor(i)` per unit
+ *               (the dwell before unit `i` appears) when given.
+ *   controlled  pass `revealed` and the timer is off: real events drive
+ *               the count, clamped to [0, total].
+ *
+ * `onComplete` fires exactly once each time the count reaches `total`
+ * (total > 0). Dropping back below total (total grew, `replay()`, a lower
+ * controlled value) re-arms it.
+ *
+ * Framework-free and DOM-free, with an injectable clock, so
+ * tests/unit/revealTicker.test.ts drives it with fake timers. The Svelte
+ * rune wrapper is createRevealTicker in revealTicker.svelte.ts.
+ *
+ * Behaviour adapted from BoardUI's agent-log `useRevealTicker`:
+ *   MIT License — Copyright (c) 2026 Mertcan Dundar Esmergul (BoardUI)
+ * Differences: framework-free class, an in-flight tick survives option
+ * updates that do not change the next unit (a log whose `total` grows while
+ * streaming does not stall), and switching from controlled back to timer
+ * mode resumes from the controlled count instead of jumping back.
+ */
+export declare const DEFAULT_STEP_INTERVAL = 850;
+export declare const DEFAULT_START_DELAY = 320;
+export interface RevealCoreOptions {
+    /** How many units the log has. */
+    total: number;
+    /** ms between units after the first (timer mode). */
+    stepInterval?: number;
+    /** ms before the first unit (timer mode). */
+    startDelay?: number;
+    /** Controlled count — when defined, the timer is off. */
+    revealed?: number;
+    /** Dwell before unit `index` appears; overrides startDelay/stepInterval. */
+    delayFor?: (index: number) => number;
+    /** false pauses the timer (no effect in controlled mode). Default true. */
+    run?: boolean;
+}
+export interface RevealClock {
+    setTimeout(fn: () => void, ms: number): unknown;
+    clearTimeout(id: unknown): void;
+}
+export interface RevealCoreHooks {
+    /** Called whenever the visible count changes. */
+    onChange?: (revealed: number) => void;
+    /** Called once per completion. */
+    onComplete?: () => void;
+    clock?: RevealClock;
+}
+/** The delay before unit `index` (pure; exported for tests and hosts). */
+export declare function revealDelay(index: number, opts: Pick<RevealCoreOptions, 'stepInterval' | 'startDelay' | 'delayFor'>): number;
+export declare class RevealCore {
+    #private;
+    constructor(opts: RevealCoreOptions, hooks?: RevealCoreHooks);
+    get total(): number;
+    get controlled(): boolean;
+    /** Units currently visible. */
+    get revealed(): number;
+    get complete(): boolean;
+    /** True while a tick is scheduled. */
+    get pending(): boolean;
+    /** Begin scheduling (call on mount — never during SSR). */
+    start(): void;
+    /** Merge new options (any subset) and reconcile. */
+    update(next: Partial<RevealCoreOptions>): void;
+    /** Back to zero and run again (timer mode). */
+    replay(): void;
+    /** Stop the timer for good (call on unmount). */
+    destroy(): void;
+}