@rahdar/plugin-sdk 0.0.0-stage → 2026.10.50

package/types/kernel/shell/HomeView.d.ts

@@ -0,0 +1,6 @@
+/**
+ * The landing page, with no cluster open: what the features contribute for it. The clusters feature
+ * sends the operator to the first cluster, so the page is seen only while that is decided or while no
+ * cluster is registered, which is what it is titled for.
+ */
+export declare function HomeView(): import("react").JSX.Element;

package/types/kernel/shell/NavGroup.d.ts

@@ -0,0 +1,13 @@
+import { type ReactNode } from 'react';
+/**
+ * A group of navigation rows under a heading, shared by the sidebar and every section list. The
+ * heading names the group but is not an HTML heading: the page's headings are the page's own. Collapsed
+ * (the sidebar's rail), the heading is drawn as a rule in the same box, so the icons below it keep their
+ * place, and its name stays available to a screen reader.
+ */
+export declare function NavGroup({ label, collapsed, sticky, children, }: Readonly<{
+    label: string;
+    collapsed?: boolean;
+    sticky?: boolean;
+    children: ReactNode;
+}>): import("react").JSX.Element;

package/types/kernel/shell/NavItem.d.ts

@@ -0,0 +1,33 @@
+import { type ReactNode } from 'react';
+/**
+ * One navigation row, the only one: the sidebar's views and every section list (Settings,
+ * Administration, Configuration) use it, so they look and behave alike. It is a full-width block whose
+ * whole surface is the link, with its label on the same start edge as the group heading above it
+ * (`NavGroup`). Collapsed state hides the label visually but never from a screen reader: `aria-label`
+ * carries it, and the `Tooltip` supplies the mouse equivalent. The navbar's `Tooltip.Group` sets the
+ * delay: late enough that sweeping the rail doesn't flicker a tooltip per row, then instant from row to
+ * row. A label that is cut off by its ellipsis gets a `title`.
+ *
+ * A row with a `disabledReason` is not a link. It stays in the tab order, so the reason is reachable by
+ * keyboard: the tooltip opens on focus as well as hover, and a screen reader hears the reason as the
+ * row's description.
+ *
+ * `current` decides whether the row is the open one when the address alone cannot (a section list's
+ * open section is a search value, and the first one is open when there is none); without it the router
+ * decides from the path. The open row is marked `aria-current="page"`.
+ */
+export declare function NavItem({ to, search, current, label, leading, trailing, collapsed, disabledReason, onIntent, }: Readonly<{
+    to: string;
+    /** The search the link carries; a section list gives the section's. */
+    search?: Record<string, unknown>;
+    current?: boolean;
+    label: string;
+    /** An icon, a health mark, or a monogram — whatever leads the row. Section rows have none. */
+    leading?: ReactNode;
+    trailing?: ReactNode;
+    collapsed?: boolean;
+    /** Why the row cannot be opened; the row is disabled while this is set. */
+    disabledReason?: string;
+    /** The pointer or focus reached the row: a chance to load what it opens. */
+    onIntent?: () => void;
+}>): import("react").JSX.Element;

package/types/kernel/shell/NavToggle.d.ts

@@ -0,0 +1,13 @@
+/**
+ * A real button — `aria-expanded`/`aria-controls` so the collapse is announced. While the window is
+ * too narrow for the full sidebar (`forced`) it says why it does nothing: it is `aria-disabled`, not
+ * `disabled`, so it keeps its focus and its tooltip, and the reason stays reachable by keyboard.
+ * `onToggle` is a no-op while forced (`useNavCollapsed`).
+ */
+export declare function NavToggle({ collapsed, forced, onToggle, controls, }: Readonly<{
+    collapsed: boolean;
+    /** The window is narrower than the sidebar's threshold, so the rail is not the viewer's choice. */
+    forced?: boolean;
+    onToggle: () => void;
+    controls: string;
+}>): import("react").JSX.Element;

package/types/kernel/shell/RootLayout.d.ts

@@ -0,0 +1,15 @@
+/**
+ * The desktop workspace chrome: a fixed header, the collapsible sidebar (the features' way between
+ * clusters, then the open cluster's view nav, ADR-0034), and the routed detail column.
+ * Desktop-first: no phone or tablet layout (ADR-0164).
+ *
+ * The sidebar collapses to an icon rail rather than disappearing: `AppShell`'s
+ * own `collapsed` prop removes the navbar's width entirely, which is the wrong
+ * shape for a rail that stays present with icons, so `navbar.width` switches
+ * between two theme tokens (`--as-nav-w`, `--as-nav-rail-w`) instead. The switch
+ * is instant: `AppShell` animates neither the navbar's width nor anything but the
+ * main column's padding, so a transition only reflowed the whole page for its
+ * length, and ⌘B is a keyboard action repeated all day. The rail is also what a
+ * window narrower than 64rem gets (`useNavCollapsed`).
+ */
+export declare function RootLayout(): import("react").JSX.Element | null;

package/types/kernel/shell/SectionNav.d.ts

@@ -0,0 +1,41 @@
+import { type ReactNode } from 'react';
+export interface SectionTab {
+    id: string;
+    title: string;
+    panel: ReactNode;
+    /** Shown at the end of the row, such as a count or a marker; its words become part of the link's name. */
+    aside?: ReactNode;
+    /** Loads what the section needs; called when the pointer or focus reaches its link. */
+    preload?: () => void;
+}
+export interface SectionGroup {
+    id: string;
+    label: string;
+    tabs: SectionTab[];
+}
+/**
+ * Called by a form inside a section with whether it holds unsaved input. While it does, its row says
+ * Unsaved and opening another section asks first, because the section unmounts on a change and the input
+ * would be lost. Outside a section list it does nothing.
+ */
+export declare function useUnsavedSection(dirty: boolean): void;
+/**
+ * A page's sections as a list of links under fixed group headings, the open one beside the list. It is
+ * navigation, not an ARIA tab widget: every row is a link to the same page with `?tab=<id>`, the open one
+ * is `aria-current="page"`, and the open section is in the address, so it can be shared and survives a
+ * reload. Any other value opens the first section. A group with no sections is left out.
+ *
+ * Choosing a section never moves the page: the link does not reset the scroll, and the list scrolls the
+ * page only when the top of the new section is above the window. A keyboard user who activates a link
+ * lands in the section, which is named, so they read what they chose rather than staying in the list.
+ * The list is its own scroll area when it is taller than the window, its group headings sticky. Leaving a
+ * section whose form holds unsaved input ({@link useUnsavedSection}) asks first, by link or by history.
+ *
+ * @param keep the search values that survive a change of section (a filter that applies to every one);
+ *   the rest belong to the section that was open and are dropped.
+ */
+export declare function SectionNav({ label, groups, keep, }: Readonly<{
+    label: string;
+    groups: SectionGroup[];
+    keep?: string[];
+}>): import("react").JSX.Element;

package/types/kernel/shell/UserMenu.d.ts

@@ -0,0 +1,10 @@
+import { type MeView } from '../auth/api.ts';
+export interface UserMenuProps {
+    me: MeView | undefined;
+}
+/**
+ * The signed-in user's identity, admin entry point, account page, display choices, and logout
+ * (identity-and-sessions spec). The colour scheme (ADR-0159) and the table density (ADR-0162) are
+ * chosen here, each as one of its values; the command palette offers both as actions too.
+ */
+export declare function UserMenu({ me }: Readonly<UserMenuProps>): import("react").JSX.Element | null;

package/types/kernel/shell/lastPlace.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Where the operator last was inside a cluster, so a page outside any cluster (Administration, the inbox,
+ * an account) can lead straight back to it. Browser-local and per viewer, like the palette's recents: a
+ * convenience that is fine to lose with site data, never state anything depends on.
+ */
+export interface LastPlace {
+    clusterId: string;
+    clusterName: string;
+    /** The view the operator was in, such as "Queues". */
+    label: string;
+    /** The address, and the search it was opened with. */
+    to: string;
+    search: Record<string, unknown>;
+}
+export declare function readLastPlace(): LastPlace | null;
+export declare function recordLastPlace(place: LastPlace): void;
+export declare function useLastPlace(): LastPlace | null;

package/types/kernel/shell/pageTitle.d.ts

@@ -0,0 +1,13 @@
+/**
+ * The parts of "where the operator is" that the shell cannot derive from the address itself
+ * (ADR-0109): the cluster's name, which only the clusters feature knows, and the open resource,
+ * which only its view knows. The shell combines them with the view it matches from the address into
+ * the document title and the breadcrumb.
+ */
+export interface TitleParts {
+    cluster?: string;
+    resource?: string;
+}
+export declare function useTitleParts(): TitleParts;
+/** Declares one part of the title while the calling component is mounted. */
+export declare function useTitlePart(part: keyof TitleParts, value: string | null | undefined): void;

package/types/kernel/shell/recents.d.ts

@@ -0,0 +1,16 @@
+/**
+ * The views and resources an operator opened most recently on a cluster, for the palette's Recent
+ * group (ADR-0109). Browser-local and per viewer: a convenience that is fine to lose with site data,
+ * never state anything depends on.
+ */
+export interface Recent {
+    label: string;
+    /** Where it is: the pathname, and the search it was opened with. */
+    to: string;
+    search: Record<string, unknown>;
+    /** What kind of place it is, shown as the entry's description. */
+    kind: string;
+}
+export declare function readRecents(clusterId: string): Recent[];
+/** Records a visit, most recent first, one entry per label. */
+export declare function recordRecent(clusterId: string, recent: Recent): void;

package/types/kernel/shell/useColorSchemeToggle.d.ts

@@ -0,0 +1,10 @@
+/**
+ * The command palette's colour scheme action and its name (the user menu offers the three schemes as a
+ * choice). It cycles following the system, light, dark (ADR-0159). The name says where the action goes,
+ * not where it is, and while the system decides it also says what the system chose.
+ */
+export declare function useColorSchemeToggle(): {
+    scheme: import("@mantine/core").MantineColorScheme;
+    toggle: () => void;
+    label: string;
+};

package/types/kernel/shell/useFreshness.d.ts

@@ -0,0 +1,25 @@
+/** What the header can say about the data on the screen right now (ADR-0052). */
+export interface Freshness {
+    /** Newest successful fetch among the queries this screen is observing, in epoch ms. */
+    lastUpdatedAt: number | null;
+    isFetching: boolean;
+    /** At least one query the screen depends on is in error. */
+    hasError: boolean;
+    /** How many queries the screen is observing. Zero means there is nothing to report. */
+    observed: number;
+}
+/**
+ * Freshness derived from the query cache rather than wired per screen.
+ *
+ * The queries with **active observers** are exactly the ones the screen on the
+ * display depends on, so no screen can forget to opt in and a screen added later
+ * is covered the day it is written. A query nobody is watching has no freshness
+ * worth reporting.
+ *
+ * `lastUpdatedAt` is the *newest* success, not the oldest: the oldest is
+ * pessimistic in a misleading way — one slow background query would make a live
+ * screen read as stale — and the honesty lives in `hasError` instead, which puts
+ * the whole indicator into its offline state rather than letting a fresh sibling
+ * paper over a failing one.
+ */
+export declare function useFreshness(): Freshness;

package/types/kernel/shell/useNavCollapsed.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Sidebar collapse state, persisted per browser (ADR-0034). A boolean local to
+ * one component doesn't need a global store (non-negotiable #9) — `localStorage`
+ * is the whole state layer. `getInitialValueInEffect: false` reads synchronously
+ * so there is no expand→collapse flash on first paint.
+ *
+ * `forced` says the rail is the window's doing, not the viewer's: the toggle then changes
+ * nothing, and the viewer's own choice is kept for when the window is wide again.
+ */
+export declare function useNavCollapsed(): {
+    collapsed: boolean;
+    forced: boolean;
+    toggle: () => void;
+};

package/types/kernel/slots.d.ts

@@ -0,0 +1,206 @@
+import type { ComponentType } from 'react';
+import type { ActionProps, ActionSection, AddressTarget, ClientTarget, ConnectionTarget, ConsumerTarget, DivertTarget, LinkProps, MessageTarget, ProducerTarget, QueueTarget, SessionTarget } from './actions/types.ts';
+import type { HeldOperationDetail } from './approvals/api.ts';
+import type { MetricRange } from './time/ranges.ts';
+/** Queues picked by name, or every queue matching the queues screen's filter (`q`, blank for all). */
+export type QueueSelection = {
+    kind: 'names';
+    names: string[];
+} | {
+    kind: 'filter';
+    q: string;
+    total: number;
+};
+/** Messages picked by id, every message matching the messages screen's selector, or the whole queue. */
+export type MessageSelection = {
+    kind: 'ids';
+    ids: number[];
+} | {
+    kind: 'filter';
+    filter: string;
+} | {
+    kind: 'all';
+};
+/**
+ * The kernel-owned slots and what each hands its contributions (ADR-0070). A slot lets a screen
+ * show another feature's panel without importing that feature, and without a placeholder when the
+ * feature is disabled.
+ */
+export interface SlotProps {
+    /** In the application header, after the product name: status across clusters that needs attention. */
+    'shell.header': object;
+    /** In the sidebar, above the open cluster's views: how the operator moves between clusters. */
+    'shell.navbar': {
+        collapsed: boolean;
+    };
+    /** The landing page, when no cluster is open. */
+    'home.empty': object;
+    /** Above every view of a cluster: what identifies it, and what needs saying about its state. */
+    'cluster.header': {
+        clusterId: string;
+    };
+    /** Below a passing registration check: what the enabled features added to it, by feature id. */
+    'cluster.registration.afterProbe': {
+        contributions: Record<string, unknown>;
+    };
+    /** In a queue's detail drawer, below its per-node breakdown. `onClose` closes the drawer before navigating. */
+    'queue.detail.panels': {
+        clusterId: string;
+        queueName: string;
+        onClose: () => void;
+    };
+    /**
+     * Beside the queues screen's selection: what can be done to the selected queues. `count` is how
+     * many are selected, and may be zero: an action then stays visible and disabled. `clear` empties
+     * the selection.
+     */
+    'queues.selection': {
+        clusterId: string;
+        selection: QueueSelection;
+        count: number;
+        clear: () => void;
+    };
+    /**
+     * Beside the messages screen's selection: what can be done to the selected messages elsewhere.
+     * `node` is the Rahdar node being browsed, absent for the live node; `total` is how many messages
+     * the selection holds, null when the screen does not know. `clear` empties the selection.
+     */
+    'messages.selection': {
+        clusterId: string;
+        queueName: string;
+        node?: string;
+        selection: MessageSelection;
+        total: number | null;
+        clear: () => void;
+    };
+    /** At the foot of a cluster's metrics view. */
+    'metrics.panels': {
+        clusterId: string;
+    };
+    /** In the flow view's monitoring pane, when a queue is selected: its history over `range`, per node. */
+    'flow.selection.panels': {
+        clusterId: string;
+        queueName: string;
+        range: MetricRange;
+    };
+    /** Inside a box on the topology graph, after its name. `nodeIds` are the broker endpoints the box stands for. */
+    'topology.node.marks': {
+        clusterId: string;
+        nodeIds: string[];
+    };
+    /** A section of a cluster's Settings page, under the contribution's title. */
+    'settings.sections': {
+        clusterId: string;
+    };
+    /** A tab of a cluster's Routing page, after Diverts and Bridges, labelled with the contribution's title; its id is the tab's `?tab=`. */
+    'routing.tabs': {
+        clusterId: string;
+    };
+    /**
+     * A tab of the Administration page, labelled with the contribution's title and listed under its
+     * `group`; its id is the tab's `?tab=`.
+     */
+    'admin.tabs': object;
+    /** A section of the signed-in user's Account page, under the contribution's title. */
+    'account.sections': object;
+    /**
+     * On an approval request's page, above Rahdar's own Approve and Reject: what an installed approval provider
+     * shows an approver, such as its policy's checks or its own decision controls. `heldOperation` is the request
+     * as the page shows it; `refresh` fetches it again after the contribution changed it.
+     */
+    'approval.decision': {
+        heldOperation: HeldOperationDetail;
+        refresh: () => void;
+    };
+    /**
+     * A dialog opened from the user menu. The menu lists the contribution's title after Account and hosts
+     * the dialog outside the menu, so it outlives the menu closing.
+     */
+    'shell.userMenu': {
+        opened: boolean;
+        onClose: () => void;
+    };
+    'queue.actions': ActionProps<QueueTarget>;
+    'address.actions': ActionProps<AddressTarget>;
+    'connection.actions': ActionProps<ConnectionTarget>;
+    'session.actions': ActionProps<SessionTarget>;
+    'consumer.actions': ActionProps<ConsumerTarget>;
+    'producer.actions': ActionProps<ProducerTarget>;
+    'message.actions': ActionProps<MessageTarget>;
+    'divert.actions': ActionProps<DivertTarget>;
+    'client.actions': ActionProps<ClientTarget>;
+    'queue.link': LinkProps<QueueTarget>;
+    'address.link': LinkProps<AddressTarget>;
+    'connection.link': LinkProps<ConnectionTarget>;
+    'session.link': LinkProps<SessionTarget>;
+}
+export type SlotName = keyof SlotProps;
+/**
+ * The closed, ordered headings a Settings page groups its tabs under, in the order an operator's
+ * reach widens: their own preferences, then what is shared across Rahdar, then this cluster, then
+ * what plugins added. Adding one is a kernel change, like a navigation group (ADR-0070).
+ */
+export declare const SETTINGS_GROUPS: readonly [{
+    readonly id: "personal";
+    readonly label: "Yours";
+}, {
+    readonly id: "rahdar";
+    readonly label: "Rahdar";
+}, {
+    readonly id: "cluster";
+    readonly label: "This cluster";
+}, {
+    readonly id: "plugins";
+    readonly label: "Plugins";
+}];
+export type SettingsGroupId = (typeof SETTINGS_GROUPS)[number]['id'];
+/**
+ * The closed, ordered headings the Administration page groups its tabs under: who may do what, what
+ * is installed and where, what rules data and changes follow, then what helps when something is
+ * wrong. Every `admin.tabs` contribution names one. Adding one is a kernel change, like a navigation
+ * group (ADR-0070).
+ */
+export declare const ADMIN_GROUPS: readonly [{
+    readonly id: "access";
+    readonly label: "Access";
+}, {
+    readonly id: "installation";
+    readonly label: "Installation";
+}, {
+    readonly id: "governance";
+    readonly label: "Governance";
+}, {
+    readonly id: "support";
+    readonly label: "Support";
+}];
+export type AdminGroupId = (typeof ADMIN_GROUPS)[number]['id'];
+export interface SlotContribution<P> {
+    /** Unique within the slot. */
+    id: string;
+    /** Position within the slot; lower comes first. */
+    order: number;
+    /** The heading or tab label, in the slots that show one. */
+    title?: string;
+    /**
+     * The heading its tab sits under, in the grouped slots: a `SettingsGroupId` for `settings.sections`
+     * (listed under Plugins without one), and an `AdminGroupId`, required, for `admin.tabs`.
+     */
+    group?: string;
+    /** `*.actions` only: the menu section the item is listed under. */
+    section?: ActionSection;
+    Component: ComponentType<P>;
+}
+/** What a contribution to a grouped slot names as its heading. */
+type SlotGroup<K extends SlotName> = K extends 'admin.tabs' ? {
+    group: AdminGroupId;
+} : K extends 'settings.sections' ? {
+    group?: SettingsGroupId;
+} : object;
+/** One contribution to the named slot, with the heading that slot groups it under. */
+export type SlotEntry<K extends SlotName> = SlotContribution<SlotProps[K]> & SlotGroup<K>;
+export type SlotContributions = {
+    [K in SlotName]?: SlotEntry<K>[];
+};
+/** The enabled features' contributions to one slot, in order. */
+export declare function useSlot<K extends SlotName>(name: K): SlotEntry<K>[];
+export {};

package/types/kernel/stream/sse.d.ts

@@ -0,0 +1,22 @@
+/** What both of the console's event streams share: the server's control frames and how to reconnect (ADR-0052). */
+/** The server's keep-alive (`SseHub.PING`). Not a topic — every subscriber gets it. */
+export declare const PING = "ping";
+/** The server is about to close this stream (`SseHub.RECONNECT`): reconnect at once, without backoff. */
+export declare const RECONNECT = "reconnect";
+/**
+ * The server closed this stream for a newer one of the same user past their limit (`SseHub.EVICTED`): wait
+ * until the tab is in use again before reconnecting, or the user's tabs would keep closing each other.
+ */
+export declare const EVICTED = "evicted";
+/** Frames were lost (`SseHub.RESYNC`): the bus came back, or a replay was capped. Refetch the views. */
+export declare const RESYNC = "resync";
+/**
+ * A connection with no frame for this long is treated as dead. Comfortably above
+ * the server's keep-alive interval so one missed beat is not read as death; if
+ * `sse.heartbeat-interval` is raised past a third of this, raise this with it.
+ */
+export declare const SILENCE_MS = 45000;
+/** Failures past this read as "the server is gone", not "the connection blipped". */
+export declare const OFFLINE_AFTER = 3;
+/** Capped exponential backoff with full jitter, so a restart is not stampeded. */
+export declare function backoff(failures: number): number;

package/types/kernel/stream/useClusterStream.d.ts

@@ -0,0 +1,27 @@
+/** What the UI reports about the live connection (ADR-0052). */
+export type StreamStatus = 'connecting' | 'live' | 'reconnecting' | 'offline';
+/** The live-stream state, or `null` on a route that mounts no stream. */
+export declare function useStreamStatus(): StreamStatus | null;
+/**
+ * One `EventSource` per mounted cluster view (ADR-0003, ADR-0018, ADR-0027).
+ *
+ * - Each topic's frames go to the handler its feature contributes (ADR-0070). A
+ *   signal topic's handler invalidates the matching TanStack Query keys and the
+ *   normal `queryFn` refetches; a topic of a disabled feature has no handler.
+ * - `onFrame` also hands the view every frame of the topics it mounted, for a topic
+ *   that carries data with no server-side resource behind it, such as the live
+ *   broker-event feed. A new `EventSource` never sends `Last-Event-ID` itself, so the
+ *   hook remembers the last frame id and presents it as `lastEventId` on every connect,
+ *   on whichever replica it lands; the server replays what was missed.
+ * - `reconnect` (the server is draining) reopens at once with the backoff reset and is
+ *   not a failure. `resync`, or the first successful connect after a failure, refetches
+ *   every query of the cluster: change signals sent while the client was away are not
+ *   replayed.
+ *
+ * It reconnects indefinitely with capped exponential backoff and full jitter, and
+ * treats silence as failure (ADR-0052): an intermediary that drops the connection
+ * without a clean close fires no `error`, so the only way to notice is to miss a
+ * keep-alive. The returned status is what the freshness indicator reports; the
+ * per-hook `refetchInterval` keeps every view updating while it is not `live`.
+ */
+export declare function useClusterStream(clusterId: string, topics: string[], onFrame?: (topic: string, data: string) => void): StreamStatus;

package/types/kernel/stream/useUserStream.d.ts

@@ -0,0 +1,11 @@
+import type { StreamStatus } from './useClusterStream.ts';
+/**
+ * The signed-in user's own event stream (`GET /api/v1/me/stream`): their inbox and their held operations,
+ * on every page rather than only a cluster's. Each signal invalidates the queries it covers, and a
+ * `resync`, or a reconnect after a failure, refetches all of them. It reconnects indefinitely with capped,
+ * jittered backoff and treats silence as failure, as the cluster stream does. A stream the server closed for
+ * a newer tab (`evicted`) waits until this tab is in use again.
+ *
+ * Returns the connection's state, so a view can poll while it is not `live`.
+ */
+export declare function useUserStream(): StreamStatus;

package/types/kernel/time/Ago.d.ts

@@ -0,0 +1,9 @@
+/**
+ * A moment in words (or, with `future`, how long from now) inside a `<time>`, with the exact time as text
+ * a screen reader reads and a hover shows. For running text, where {@link When} would take a block of its own.
+ */
+export declare function Ago({ at, now, future }: Readonly<{
+    at: string;
+    now: number;
+    future?: boolean;
+}>): import("react").JSX.Element;

package/types/kernel/time/ranges.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Preset relative metric windows, shared by every view that charts history (metrics, and the
+ * Flow pane that shows its panels). Kept out of `router.tsx` so importing it (a
+ * component like `RangePicker` needs the runtime array, not just the type)
+ * never has to evaluate the whole route tree — that module calls
+ * `createRootRoute`/`createRoute` at import time, which only a real router
+ * context (or a full mock of it) can satisfy.
+ */
+export declare const METRIC_RANGES: readonly ["15m", "1h", "6h", "24h", "7d"];
+export type MetricRange = (typeof METRIC_RANGES)[number];
+/**
+ * Each range's width and the bucket it asks the server for, in one place.
+ *
+ * The two travel together on purpose: the window advances in whole buckets
+ * (ADR-0055), the axis chooses its tick format from the range, and the poll
+ * cadence is derived from both. Splitting them across three modules is how they
+ * drift.
+ *
+ * `step` is a hint. The server clamps it to the fastest sampling tier and widens
+ * it to keep a response under its point cap, and reports what it actually used;
+ * nothing here assumes the hint was honoured.
+ */
+export interface RangeSpec {
+    /** Window width. */
+    windowMs: number;
+    /** Requested bucket width, as the ISO-8601 duration the endpoint takes. */
+    step: string;
+    /** The same bucket width in ms — what the window quantizes to. */
+    stepMs: number;
+}
+export declare const RANGE_SPEC: Record<MetricRange, RangeSpec>;
+export declare function rangeSpec(range: MetricRange): RangeSpec;

package/types/kernel/time/time.d.ts

@@ -0,0 +1,89 @@
+/**
+ * Ask the server what time it is and fold the answer in.
+ *
+ * Failures are silent on purpose: the probe is not a screen and has no operator
+ * waiting on it. A 401 or a dropped network leaves the previous estimate standing,
+ * which is strictly better than reverting to the browser's clock, and the real
+ * queries on the screen are what report that the server is unreachable.
+ *
+ * Concurrent callers join the request in flight rather than starting another.
+ */
+export declare function syncServerTime(): Promise<void>;
+/**
+ * The SSE keep-alive as a drift detector — never as a measurement.
+ *
+ * `SseHub.heartbeat` puts the server's clock in every `ping`, so the client is
+ * told the time every twenty seconds for free. It is one-way with unmeasurable
+ * latency, so it cannot teach the estimator; what it can do is notice that the
+ * estimate has gone wrong and ask for a real probe.
+ */
+export declare function offerPing(data: unknown): void;
+/** Rahdar's clock, as best the browser can tell. The only wall-clock read in the app. */
+export declare function serverNow(): number;
+/**
+ * Put a browser-stamped instant on Rahdar's timeline.
+ *
+ * The only such instants are TanStack Query's `dataUpdatedAt`, which it stamps
+ * with its own `Date.now()` when a response lands. Comparing one against
+ * {@link serverNow} without this would reintroduce exactly the error this module
+ * removes — and silently, because the number looks right.
+ */
+export declare function toServerMs(browserMs: number): number;
+/** How far the browser's clock is from Rahdar's, in ms. Positive means the browser is ahead. */
+export declare function browserOffsetMs(): number;
+/**
+ * Keep the estimate honest for as long as the tab lives.
+ *
+ * Three triggers, because clocks go wrong in three ways: they drift (the
+ * interval), they are corrected or the machine wakes from sleep (the step check
+ * and `visibilitychange`), and the tab is backgrounded long enough that neither
+ * timer ran (`visibilitychange` again — browsers throttle background timers).
+ *
+ * The step check is the client-side `MonotonicClockWatch`: `performance.now()`
+ * advances monotonically, so comparing its delta against the wall clock's
+ * separates a jump from ordinary drift. A step means the offset is now wrong by
+ * the size of the jump, and unlearning that slowly through the EWMA would leave
+ * every label wrong in the meantime.
+ *
+ * Called once from the application root. Returns a teardown for tests.
+ */
+export declare function startServerTimeSync(): () => void;
+/**
+ * A clock that ticks to re-render a relative label, on Rahdar's time.
+ *
+ * Also re-renders when the offset itself changes, which matters more than it
+ * looks: `MetricsView` ticks at the metric bucket width, up to an hour, and would
+ * otherwise hold a window computed before the first probe resolved for that long.
+ */
+export declare function useServerNow(intervalMs?: number): number;
+/**
+ * `4s`, `3m`, `2h`, `1d` — short enough to sit in a header or a table cell.
+ *
+ * Floors rather than rounds. An age is a lower bound on how long ago something
+ * happened, and `59s` reading as `1m` overstates it; the operator reading a
+ * staleness label before a destructive action is the reason to prefer the
+ * conservative direction.
+ */
+export declare function elapsedLabel(ms: number): string;
+/**
+ * A server instant, written down in the operator's chosen timezone.
+ *
+ * Fixed-width `YYYY-MM-DD HH:mm:ss` so a column of these sorts and scans by eye,
+ * and **always suffixed with the zone it is in** — `Z` for UTC, `+03:30`
+ * otherwise. The suffix is not decoration: the whole reason an operator picks a
+ * zone is to line a screen up against something else, and a timestamp that does
+ * not say which offset it is in is the one way this feature could mislead them.
+ *
+ * The offset is computed for *that instant*, not for now, so an event from last
+ * winter carries the offset that was in force when it happened.
+ *
+ * Accepts both wire shapes: the ISO-8601 strings every DTO carries, and the
+ * epoch-millis a broker's own message timestamps arrive as. Those are `0` when the
+ * broker set none, which is not a time and is rendered as such.
+ *
+ * Reads the zone from module state rather than a hook so it can be called from a
+ * table's column accessor. The consequence is that a view rendering one of these
+ * must subscribe with `useDisplayZone()` or it will not repaint when the zone
+ * changes.
+ */
+export declare function absoluteLabel(value: string | number | null | undefined): string;