@osqd/bothandlerjs 0.3.0 → 0.5.0

package/dist/dashboard/client/actions.d.ts

@@ -0,0 +1,17 @@
+/**
+ * The three things you can do to one client, rather than to a class of request.
+ *
+ * Shared by the actor drill-down and the Actors screen, which offer the same three and
+ * would otherwise offer them slightly differently.
+ *
+ * Allowlisting is the consequential one and it is the one that asks twice. **An
+ * allowlisted address is not judged leniently; it is not judged at all** — detection
+ * does not run, no evidence is produced, no rule sees it — so the button states the
+ * address it is about to exempt and waits for a second click. That is deliberately not
+ * a dialog: a confirmation you can dismiss without reading is a click with extra steps,
+ * whereas a button that changes into the sentence it is about to enact has to be read
+ * to be pressed.
+ */
+export type AfterAction = () => void;
+export declare function isConfirming(): boolean;
+export declare function actorActions(key: string, after: AfterAction): HTMLElement[];

package/dist/dashboard/client/actor.d.ts

@@ -0,0 +1,5 @@
+/** Wires the panel's own Close button. Called once, and only when the panel exists. */
+export declare function initActor(): void;
+/** Opens the drill-down above the feed and scrolls it into view. */
+export declare function openActor(key: string): void;
+export declare function drawActor(): void;

package/dist/dashboard/client/api.d.ts

@@ -0,0 +1,15 @@
+/**
+ * The page's two ways of talking to its server.
+ *
+ * Every write is JSON with a JSON content type, and that is not a style choice: the
+ * server refuses a body it did not get as `application/json` precisely because an HTML
+ * form cannot send one, which is what stops somebody else's page from posting here
+ * with an operator's credentials attached.
+ */
+export declare function getJson<T>(path: string): Promise<T>;
+export interface PostResult<T> {
+    ok: boolean;
+    data: T;
+    error?: string;
+}
+export declare function postJson<T>(path: string, body: unknown): Promise<PostResult<T>>;

package/dist/dashboard/client/app.d.ts

@@ -0,0 +1,37 @@
+import type { TabName } from "./types.js";
+/**
+ * The handful of things every module needs to be able to do to the page as a whole.
+ *
+ * A mutable record filled in by `index.ts` at start-up, rather than each module
+ * importing the module that owns `draw`. The feed opens the actor panel, the actor
+ * panel drafts a rule into the policy editor, the policy editor switches to its own
+ * tab: written as direct imports that is a cycle, and a cycle in a bundle is a
+ * half-initialised module waiting to be discovered at run time. One indirection costs
+ * a property lookup and makes the shape obvious.
+ */
+export interface App {
+    /** Redraws the active view on the next frame. Coalesced; safe to call per event. */
+    draw: () => void;
+    /** Redraws immediately, for the cases where a click has to be reflected before the next frame. */
+    drawNow: () => void;
+    showTab: (tab: TabName, options?: {
+        focus?: boolean;
+        replace?: boolean;
+        push?: boolean;
+    }) => void;
+    /** Puts the feed's filter state into the URL, so a view can be sent to somebody. */
+    syncUrl: () => void;
+}
+export declare const app: App;
+/**
+ * A transient message in the corner.
+ *
+ * Lives here rather than in the policy editor because the guard form, the feed's
+ * exporter and the stream all raise them now, and three copies of a six-line function
+ * is how they end up looking different from each other.
+ */
+export declare function toast(kind: "ok" | "bad" | "warn", title: string, detail?: string): void;
+/** Hands the viewer a file. Used by the settings export and the feed export. */
+export declare function download(text: string, filename: string, type: string): void;
+/** Today, as a filename fragment. Every export the page produces is stamped with it. */
+export declare function today(): string;

package/dist/dashboard/client/bars.d.ts

@@ -0,0 +1,4 @@
+/** A horizontal bar list, sorted by value, capped at what a panel can show without scrolling. */
+export declare function drawBars(target: HTMLElement, rows: Iterable<[string, number]>, emptyText: string): void;
+/** A record of counters as bar rows. */
+export declare function pairs(record: Record<string, number> | undefined): Array<[string, number]>;

package/dist/dashboard/client/boot.d.ts

@@ -0,0 +1,5 @@
+import type { Boot } from "./types.js";
+export declare const BOOT: Boot;
+/** Every request the page makes is relative to the mount path. */
+export declare const API: string;
+export declare const SECTIONS: Required<import("./types.js").DashboardSections>;

package/dist/dashboard/client/charts.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Stacked bars, two series, plus a marker row for denials.
+ *
+ * Two series rather than three because served/mitigated/denied as three fills would
+ * need a third hue that survives colour-vision simulation beside these two, and none
+ * does; a denial is a status rather than a series, so it gets a status marker and a
+ * label instead.
+ */
+export declare function drawTraffic(): void;
+/**
+ * The score distribution: how close ordinary traffic runs to the line.
+ *
+ * Two populations, and the panel now says which one it is drawing rather than leaving
+ * the reader to assume. **Since start** comes from the same counters as the Prometheus
+ * endpoint, so it covers the whole run and agrees with whatever your alerting says.
+ * **This window** counts the few hundred requests the page is still holding, which is
+ * the right answer to "what is happening right now" and the wrong answer to "where
+ * should the threshold be" — and it was the only answer available before, sitting
+ * beside panels counting since start under an identical grey subtitle.
+ *
+ * Proven requests are excluded from both rather than piled into the last bucket: their
+ * score is 100 by definition and plays no part in any decision.
+ */
+export declare function drawScores(): void;
+export declare function drawLatency(): void;

package/dist/dashboard/client/css.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Selector escaping, on its own so both halves can have it.
+ *
+ * `dom.ts` is the browser client's entry into the document and carries module state that
+ * has to be initialised in order; the embeddable element imports it lazily for exactly
+ * that reason. But the element also assembles selectors from developer-supplied panel ids
+ * *synchronously*, before any of that has happened — so the escape lives here, in a leaf
+ * with nothing behind it, rather than being duplicated or dragging the client graph in
+ * early.
+ */
+export declare function cssEscape(value: string): string;

package/dist/dashboard/client/dom.d.ts

@@ -0,0 +1,55 @@
+/**
+ * The page's only way of putting something in the document.
+ *
+ * `textContent`, always. Every string that reaches this file — a User-Agent, a path, a
+ * detector's summary, a rule id somebody typed into the editor — was written by
+ * somebody else, and one `innerHTML` anywhere below turns a bot's User-Agent into
+ * script running in an operator's browser. A test asserts the served page contains
+ * none of the four ways to do that, and `scripts/build-client.mjs` refuses to bundle
+ * one.
+ */
+import { cssEscape } from "./css.js";
+export declare function el<K extends keyof HTMLElementTagNameMap>(tag: K, className?: string | null, value?: string | number | null): HTMLElementTagNameMap[K];
+export declare function svgEl(name: string, attributes?: Record<string, string | number>): SVGElement;
+export declare function svgText(attributes: Record<string, string | number>, text: string | number): SVGElement;
+export declare function clear(node: Node): void;
+/**
+ * Ids are base64url today, which needs no escaping — but a selector assembled from a
+ * value is only safe until somebody widens the alphabet, and `CSS.escape` costs
+ * nothing. It lives in its own module because the embeddable element needs it without
+ * loading this one; re-exported here so the rest of the client reads unchanged.
+ */
+export { cssEscape };
+/** Points the client at a shadow root. Call it before the rest of the client loads. */
+export declare function setRoot(node: Document | ShadowRoot | HTMLElement, host?: HTMLElement): void;
+/** Updates the element the theme hangs off, without disturbing the rest. */
+export declare function setThemeHost(host: HTMLElement): void;
+export declare function isEmbedded(): boolean;
+/**
+ * What global-ish events are listened on.
+ *
+ * The document when this owns the page. The dashboard's own subtree when it does not, so
+ * a digit pressed on the host's page is the host's business and not a tab change here.
+ */
+export declare function eventTarget(): EventTarget;
+/** The node every lookup runs against. */
+export declare function rootNode(): Document | ShadowRoot;
+/** The element carrying `data-theme` and the custom properties. */
+export declare function themeElement(): HTMLElement;
+export declare function $(id: string): HTMLElement;
+export declare function byId<T extends HTMLElement>(id: string): T;
+/** A CSS custom property's value, for the charts — which draw in the theme's own colours. */
+export declare function css(name: string): string;
+/**
+ * Ties a `<label>` to the control it names.
+ *
+ * A label sitting next to an input is a label to a reader who can see the layout and
+ * nothing at all to a screen reader: it announces "edit, blank" and moves on. Both form
+ * builders on this page had that defect, and both were caught by the automated
+ * accessibility pass rather than by anybody looking — which is the argument for having
+ * one.
+ *
+ * Only for the controls a label can point at. A group of chips or a segmented control is
+ * several buttons, and those carry their own names.
+ */
+export declare function label(text: string, control: HTMLElement | HTMLElement[]): HTMLLabelElement;

package/dist/dashboard/client/draft.d.ts

@@ -0,0 +1,46 @@
+import type { DashboardEntry } from "./types.js";
+/** A rule as the editor holds it: plain JSON, plus the card's open/closed state. */
+export interface EditorRule {
+    id: string;
+    match: Record<string, unknown>;
+    action: string;
+    params?: Record<string, unknown>;
+    reason?: string;
+    /** Editor-only: whether this card is expanded. Stripped before anything is submitted. */
+    _open?: boolean;
+}
+export interface Draft {
+    rule: EditorRule;
+    /** One line saying what the draft matched on, and why that and not something else. */
+    because: string;
+}
+/**
+ * Turns a request you are looking at into a rule you can preview.
+ *
+ * This is the half of the loop the dashboard was missing. The row detail could already
+ * turn a request into a replay line and a corpus case — the offline loop, where a
+ * verdict you disagree with becomes a test. The online loop ran the other way and had
+ * no help at all: you saw an actor worth acting on, then went and hand-wrote a rule in
+ * a different tab, guessing at which field would catch it.
+ *
+ * Three decisions in here, and all three are about not being clever on somebody's
+ * behalf:
+ *
+ * **The action is always `tag`.** Never `block`, never `challenge`, whatever the
+ * request looks like. A drafted rule is a starting point that has not been reviewed by
+ * anyone, and the dashboard picking a terminal action for a request that annoyed you is
+ * exactly the reflex this library exists to interrupt. The operator picks the action;
+ * the guard still checks it afterwards either way.
+ *
+ * **It matches on the strongest thing the request actually proves**, in a fixed order:
+ * a claimed-and-checked identity, else the detectors whose evidence was proven, else
+ * the verdict with a score floor. Each of those is a fact about the client. A path
+ * would narrow it further and is deliberately left out — the request happens to have
+ * one, which is not the same as the rule being about it.
+ *
+ * **It goes last.** Appending is the only position that cannot change what any
+ * existing rule does, because first match wins. A rule that never fires shows up as
+ * "never matched" in the preview, which is a better way to learn it is shadowed than
+ * discovering it silently took over from something else.
+ */
+export declare function draftRule(entry: DashboardEntry, existingIds?: readonly string[]): Draft;

package/dist/dashboard/client/feed.d.ts

@@ -0,0 +1,22 @@
+export declare function initFeed(): void;
+/** Applies filter state that arrived in the URL rather than from a click. */
+export declare function reflectFilterButtons(): void;
+/**
+ * Fetches the entries this viewer never received, and merges them.
+ *
+ * They were never lost. The rate cap keeps a burst off the *stream* and the lag guard
+ * drops frames a slow socket cannot take, but both leave the ring alone — and the opening
+ * replay is droppable too, so a first load of a busy dashboard can arrive with most of the
+ * backlog missing. `/api/feed` serves that ring whole, and `ingest` is keyed on the request
+ * id, so merging it is idempotent: what is already held is refreshed, what is missing is
+ * added.
+ *
+ * On demand rather than on a timer. Skips happen exactly when the origin is busiest, and a
+ * dashboard that answered every skip by re-fetching the whole ring would be a load
+ * amplifier pointed at the process it is meant to be watching — which is the thing
+ * `maxEventsPerSecond` exists to prevent.
+ */
+export declare function loadSkipped(): Promise<void>;
+export declare function drawFeed(): void;
+/** Drops every cached node. Used when the feed is cleared under the page's feet. */
+export declare function resetFeedCache(): void;

package/dist/dashboard/client/format.d.ts

@@ -0,0 +1,37 @@
+/** Number, duration and window formatting. Pure, so the awkward cases can be tested. */
+export declare function n(value: number | undefined): string;
+export declare function pct(part: number, whole: number): string;
+export declare function ms(value: number): string;
+export declare function uptime(milliseconds: number): string;
+export declare function rangeLabel(milliseconds: number): string;
+/** Wall-clock time for a feed row. Local, seconds included, because a feed moves in seconds. */
+/**
+ * A time, always as 24-hour HH:MM:SS.
+ *
+ * Built from the local components rather than handed to `toLocaleTimeString`, which
+ * answers in whatever the viewer's locale prefers — so the same feed read "4:40:46 PM" on
+ * one operator's screen and "16:40:46" on the next, and a dashboard two people look at
+ * together should not disagree with itself about what time it is. Local time, not UTC:
+ * this is the clock on the wall next to the server somebody is watching.
+ */
+export declare function clockTime(at: number): string;
+/** A date, always as DD-MM-YYYY. */
+export declare function clockDate(at: number): string;
+/**
+ * Both, for the places where the time alone is ambiguous.
+ *
+ * An actor's first sighting can be days back, and "first seen 09:14:02" invites the reader
+ * to assume it was this morning.
+ */
+export declare function clockStamp(at: number): string;
+/**
+ * What "this window" actually holds, said out loud.
+ *
+ * Half the panels on the Statistics screen count the retained ring and half count
+ * since the process started, and until now both wore the same quiet grey subtitle.
+ * They are different populations — on a busy server the ring can be ninety seconds of
+ * a three-week run — so comparing a panel from one against a panel from the other is a
+ * mistake the page was inviting. Every "this window" label now says how much window
+ * there is.
+ */
+export declare function windowLabel(count: number, oldestAt: number | undefined, now: number): string;

package/dist/dashboard/client/guard.d.ts

@@ -0,0 +1,3 @@
+export declare function drawGuard(): void;
+/** Forgets an in-progress edit, so a reload of the policy document is reflected. */
+export declare function resetGuardDraft(): void;

package/dist/dashboard/client/index.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/dashboard/client/outcome.d.ts

@@ -0,0 +1,33 @@
+import type { DashboardEntry } from "./types.js";
+/**
+ * One request has one of four outcomes, and every part of the page agrees on which.
+ *
+ * Served, mitigated (something happened that a legitimate client can still get past),
+ * denied, or pending — assessed, with no decision recorded, which is what `assess()`
+ * on its own produces and what a row looks like for the moment between the two events.
+ *
+ * Pure, and exported on its own, because the table, the left edges, the timeline, the
+ * actor mix and the statistics panels all classify the same way. Two of them disagreeing
+ * about what a denial is would be a bug nobody could see.
+ */
+export type Outcome = "allow" | "mitigate" | "deny" | "pending";
+export declare function outcome(entry: Pick<DashboardEntry, "action">): Outcome;
+/** The same classification for a bare action name, which is what the rule editor has. */
+export declare function actionKind(action: string | undefined): Outcome;
+/** The verdict badge: its class, and the word on it. */
+export declare function verdictBadge(entry: Pick<DashboardEntry, "verdict" | "bypass">): [className: string, label: string];
+/**
+ * How many assessments proved a *bot*.
+ *
+ * Not `metrics.proven`, which is what the tile used to show. That counter is honestly
+ * named for what it holds — assessments resting on at least one piece of proven evidence —
+ * and evidence has a direction: a client holding an operator or interaction clearance
+ * produces *certain human* evidence, so it lands there too. A dashboard watching nothing
+ * but cleared humans therefore read "Proven bots: 100% of traffic", and the same requests
+ * were counted again under Unremarkable.
+ *
+ * The two proven-bot verdicts are the exact answer. Only the proven path can reach them —
+ * the probabilistic path produces `suspected-bot`, `human` or `unknown` and nothing else —
+ * so this is a rename of the truth rather than an approximation of it.
+ */
+export declare function provenBots(verdicts: Record<string, number>): number;

package/dist/dashboard/client/pager.d.ts

@@ -0,0 +1,32 @@
+/**
+ * The pager both tables use.
+ *
+ * One renderer rather than two, because the feed pages in the browser and the Actors
+ * table pages on the server and *neither of those facts belongs in the control*. What it
+ * needs to know is where you are and what it should do when you press something.
+ *
+ * Rendered twice per table, above and below. A table of fifty rows is taller than the
+ * window on most screens, and a pager only at the bottom means scrolling to the end to go
+ * back to the top of the next page.
+ */
+export interface PagerModel {
+    /** Zero-based. */
+    page: number;
+    /** What the range reads: `1–50 of 212`. Total omitted where the total is not known. */
+    from: number;
+    to: number;
+    total?: number;
+    atStart: boolean;
+    atEnd: boolean;
+    /** Shown next to the range when the list is being held still. */
+    held?: string;
+    go: (page: number) => void;
+    size?: {
+        current: number;
+        choices: readonly number[];
+        set: (size: number) => void;
+    };
+}
+export declare function renderPager(host: HTMLElement, model: PagerModel, options: {
+    withSize: boolean;
+}): void;

package/dist/dashboard/client/panels.d.ts

@@ -0,0 +1,40 @@
+export declare function drawTiles(force?: boolean): void;
+/**
+ * The configuration facts at the end of the tab strip.
+ *
+ * Label first, value second, every time — "suspect at 60", not "60 suspect at" — and
+ * as plain text, which is the one treatment nothing else on the page uses for a
+ * control.
+ */
+export declare function drawChips(): void;
+/**
+ * Every panel that counts the retained ring says how much ring there is.
+ *
+ * Half the Statistics screen counts the window and half counts since the process
+ * started; they were wearing the same grey subtitle, which invited exactly the
+ * comparison that does not hold.
+ */
+export declare function updateWindowLabels(): void;
+export declare function drawLivePanels(): void;
+export declare function drawStatsPanels(): void;
+/**
+ * The audit panel: the window against its baseline.
+ *
+ * Both, side by side, because that is the only way the audit's output means anything.
+ * A bot share of 60% is a number; a bot share of 60% against a baseline of 12% is an
+ * incident.
+ */
+export declare function drawAudit(): void;
+/** The count on the Policy tab. Cheap, so it runs on every frame; the panel itself does not. */
+export declare function drawNoticeBadge(): void;
+export declare function drawNotices(): void;
+/**
+ * What somebody did to this process, and when.
+ *
+ * The same list the traffic timeline marks, written out — because a marker answers
+ * "was there a change here?" and a person auditing wants "what were they, in order".
+ * Bounded and in memory, which the panel says: the durable copy is the change events.
+ */
+export declare function drawChanges(): void;
+/** Sibling instances, when the operator listed any. */
+export declare function drawPeers(): void;

package/dist/dashboard/client/policy.d.ts

@@ -0,0 +1,25 @@
+import type { DashboardEntry } from "./types.js";
+/**
+ * The rule editor works on a model — an array of plain rule objects — and both views
+ * render from it. The GUI mutates the model in place on each keystroke, which is what
+ * keeps focus and cursor position while somebody types; only structural changes (add,
+ * remove, move, a different action) re-render a card.
+ */
+export declare function loadPolicy(): Promise<void>;
+export declare function drawPolicyTab(): void;
+/**
+ * Starts a rule from a request the operator was looking at.
+ *
+ * Appended, expanded, and previewed straight away — the three things somebody would
+ * otherwise do by hand between noticing an actor and having a rule they can judge.
+ * Nothing is applied: this fills the editor, exactly like an import.
+ *
+ * It loads the policy document first, and that `await` is load-bearing rather than
+ * tidy. Drafting is reachable from the Live tab, which somebody can use for an hour
+ * without ever opening the Policy one — and appending to an editor that has not been
+ * filled yet leaves it holding the draft *and nothing else*, while marking it dirty so
+ * the load that follows will not correct it. Apply that and the running policy becomes
+ * one drafted rule.
+ */
+export declare function draftIntoEditor(entry: DashboardEntry): Promise<void>;
+export declare function initPolicy(): void;

package/dist/dashboard/client/query.d.ts

@@ -0,0 +1,42 @@
+import type { DashboardEntry } from "./types.js";
+/**
+ * The feed's search.
+ *
+ * It used to be one `indexOf` over every field of a request joined into a string,
+ * which answers "does this word appear anywhere" and nothing else. That is the wrong
+ * question in the two cases somebody actually reaches for the box: an address that
+ * also appears inside a User-Agent, and a path that is a prefix of ten others.
+ *
+ * So terms can name a field, and can be negated:
+ *
+ * ```text
+ * actor:203.0.113.4 -path:/health      that address, except its health checks
+ * rule:no-scrapers action:tag          the rule that fired, and what it settled on
+ * score:>70 -certain                   probabilistic traffic close to the line
+ * "GET /api/v2/orders"                 a phrase, spaces and all
+ * ```
+ *
+ * Every term must match — this is an `AND`, because that is what narrowing means and
+ * a filter box that quietly `OR`s is a filter box that lies. Anything that does not
+ * parse as a field term is matched against the whole request, so a plain word still
+ * behaves exactly as it did.
+ *
+ * Kept free of the DOM so it can be unit-tested, which is the point: this is the piece
+ * of the page most likely to be wrong in a way nobody notices.
+ */
+export interface Term {
+    /** The field named before the colon, already resolved to a canonical name. */
+    field: string | undefined;
+    value: string;
+    negated: boolean;
+    /** For numeric fields: how `value` should be compared. */
+    compare?: "<" | ">" | "=" | undefined;
+}
+export declare function parseQuery(input: string): Term[];
+/** Everything about a request, as one lower-case string. What a free term is matched against. */
+export declare function searchableText(entry: DashboardEntry): string;
+/** True when every term is satisfied. An empty query matches everything. */
+export declare function matchesQuery(terms: readonly Term[], entry: DashboardEntry, haystack: string): boolean;
+/** The named filter buttons, which are a second, independent narrowing. */
+export type FilterName = "all" | "proven" | "suspected" | "human" | "guard" | "deny" | "mitigate" | "allow";
+export declare function matchesFilter(filter: FilterName, entry: DashboardEntry): boolean;

package/dist/dashboard/client/ranges.d.ts

@@ -0,0 +1,2 @@
+export declare function loadRanges(): Promise<void>;
+export declare function drawRanges(): void;

package/dist/dashboard/client/registry.d.ts

@@ -0,0 +1,4 @@
+export declare function loadActors(): Promise<void>;
+/** Polls while the screen is showing, and stops the moment it is not. */
+export declare function trackActors(): void;
+export declare function drawActors(): void;

package/dist/dashboard/client/replay.d.ts

@@ -0,0 +1,14 @@
+import type { DashboardEntry } from "./types.js";
+/**
+ * A request as a line `bothandlerjs replay` can read.
+ *
+ * The point of the button this backs: a verdict you disagree with on screen becomes a
+ * fixture you can re-run offline, and then a corpus case that stops it coming back.
+ * Values the dashboard redacted stay redacted — the shape is what replays, and a
+ * session cookie is not part of the shape.
+ */
+export declare function replayLine(entry: DashboardEntry): string;
+/** Every shown request as replay JSONL, oldest first — the whole filtered window at once. */
+export declare function replayFile(entries: readonly DashboardEntry[]): string;
+/** The same request as a traffic-corpus case, ready to paste into a fixture file. */
+export declare function corpusCase(entry: DashboardEntry): string;

package/dist/dashboard/client/result.d.ts

@@ -0,0 +1,10 @@
+import type { Preview } from "./types.js";
+/** The result box under the editor. One box, whichever of the two forms wrote to it. */
+export declare function showResult(kind: "ok" | "bad" | "warn", build: (box: HTMLElement) => void): void;
+/**
+ * What a candidate would have done to the traffic still in the window.
+ *
+ * `newDenials` is called out on its own because it is the one direction of change that
+ * costs somebody their access, and it is easy to miss in a table of counts.
+ */
+export declare function renderPreview(preview: Preview, notes?: readonly string[]): void;

package/dist/dashboard/client/store.d.ts

@@ -0,0 +1,128 @@
+import type { EditorRule } from "./draft.js";
+import type { FilterName, Term } from "./query.js";
+import type { ActorRow, DashboardEntry, Policy, Row, Snapshot, TabName } from "./types.js";
+/** Rows built into the table at once. Beyond this a feed is scrolled past, not read. */
+export declare const FEED_LIMIT = 300;
+export interface State {
+    rows: Row[];
+    byId: Map<string, Row>;
+    snapshot: Snapshot | undefined;
+    policy: Policy | undefined;
+    /** The Actors screen's list, fetched rather than streamed. See `registry.ts`. */
+    actors: ActorRow[];
+    actorsTracked: number;
+    paused: boolean;
+    filter: FilterName;
+    search: string;
+    terms: Term[];
+    tab: TabName;
+    open: Set<string>;
+    actor: string | undefined;
+    rangeMs: number;
+    /** Which population the score distribution is drawn from. See `charts.drawScores`. */
+    scoreScope: "run" | "window";
+    editorRules: EditorRule[];
+    editorDirty: boolean;
+    editorMode: "gui" | "json";
+    guardDirty: boolean;
+    /** Rows that arrived while paused, so the button can say what resuming will show. */
+    bufferedWhilePaused: number;
+    /** Frames the server dropped because *this* connection was too slow to take them. */
+    laggedDrops: number;
+    /**
+     * Which page of the feed is showing, newest first, zero-based.
+     *
+     * Zero follows the live feed. Any other page is a position in history, so arriving
+     * requests must not shuffle it under the reader — see `feedFrozen`.
+     */
+    feedPage: number;
+    /**
+     * The matching rows as they stood when the reader left page zero.
+     *
+     * Without this, one request arriving while somebody reads page three moves every row
+     * down by one and they are silently reading different rows than the ones they were
+     * looking at. Frozen on leaving page zero, dropped on returning to it.
+     */
+    feedFrozen: Row[] | undefined;
+    /** Which page of the Actors table is showing. Paged on the server, by offset. */
+    actorsPage: number;
+    /** How many rows a page of each table holds. Chosen in the page, not configured. */
+    feedPageSize: number;
+    actorsPageSize: number;
+    /**
+     * How many skipped entries have already been fetched back and merged.
+     *
+     * The server's `skipped` only ever grows, so the badge subtracts this to say how many
+     * are *still* missing rather than how many ever were.
+     */
+    caughtUp: number;
+}
+export declare const state: State;
+/**
+ * Files one entry into the ring.
+ *
+ * The same request arrives twice — once when it is assessed and again when the
+ * decision lands, and again after a reconnect that replays what was missed — so this
+ * is an upsert keyed by request id, and `rev` is what tells the renderer that a row on
+ * screen is now stale. Rebuilding a row nothing changed about is what used to wipe a
+ * text selection every time a request came in.
+ */
+export declare function ingest(entry: DashboardEntry): void;
+export declare function clearFeed(): void;
+export declare function setSearch(value: string): void;
+/** Back to the live first page, thawed. Called whenever what matches changes. */
+export declare function resetPaging(): void;
+/**
+ * Puts the ring back in time order after a bulk merge.
+ *
+ * `ingest` appends, because the stream delivers in order and appending is what that
+ * costs. A backlog fetched over HTTP is not in order relative to what is already held —
+ * it is *older* — so merging without this leaves yesterday's requests sitting at the
+ * newest end, which is where the feed reads from.
+ */
+export declare function sortRows(): void;
+export declare function matches(row: Row): boolean;
+/**
+ * Every row matching the filter, newest first.
+ *
+ * The whole set rather than a screenful: the feed pages through it, and the export means
+ * "what I am looking at" rather than "the first page of it".
+ */
+export declare function matchingRows(limit?: number): Row[];
+/** The rows the feed would draw, newest first. Also what "export what I am looking at" means. */
+export declare function visibleRows(limit?: number): Row[];
+/**
+ * One page of the feed, and what the pager needs to describe itself.
+ *
+ * Page zero reads live and is recomputed every draw. Any other page reads the list as it
+ * was when the reader left page zero, because a feed that renumbers itself under somebody
+ * paging through it is a feed they cannot read.
+ */
+export declare function feedPage(size: number): {
+    rows: Row[];
+    page: number;
+    pages: number;
+    total: number;
+};
+/** Moves to a page, freezing the list on the way off page zero and thawing on the way back. */
+export declare function goToFeedPage(page: number): void;
+export declare function matchingCount(): number;
+export declare function oldestAt(): number | undefined;
+export interface Aggregates {
+    detectors: Map<string, number>;
+    actors: Map<string, number>;
+    identities: Map<string, number>;
+    paths: Map<string, number>;
+    deniedPaths: Map<string, number>;
+    guardStops: Map<string, number>;
+    ruleHits: Map<string, number>;
+    bypassed: Map<string, number>;
+}
+/**
+ * Everything the window-scoped panels count, in one pass over the ring.
+ *
+ * One pass rather than eight, and — more to the point — it is now called only by the
+ * screen that draws them. It used to run on every frame of the live feed to fill in
+ * panels on a tab nobody was looking at.
+ */
+export declare function aggregate(rows: readonly Row[]): Aggregates;