API reference: @pyric/ui/traffic

Interfaces

MetricPoint

Properties

Property	Type	Description
`end`	`number`	-
`index`	`number`	0-based bucket index, left (oldest) to right (newest).
`start`	`number`	Half-open bounds of this bucket `[start, end)` in epoch-ms.

MetricSeries

Properties

Property	Type	Description
`key`	`string`	-
`label`	`string`	-
`total`	`number`	Sum of `values` — the period total (the legend/card number).
`values`	`number`[]	One count per bucket, aligned with `points`.

RuleHeatmapEntry

Properties

Property	Type	Description
`allows`	`number`	-
`denies`	`number`	-
`denyRatio`	`number`	`denies / total` — 0 when the rule never denied.
`operations`	`string`[]	Union of all operations seen matching this rule.
`ruleIndex`	`number`	The rule’s index in the rules file.
`total`	`number`	Total events that matched this rule.
`unsupported`	`number`	-

RuleHeatmapProps

Properties

Property	Type	Description
`className?`	`string`	-
`emptyState?`	`ReactNode`	-
`entries`	`RuleHeatmapEntry`[]	Per-rule rollup from `useRuleHeatmap`.
`onSelectRule?`	(`ruleIndex`: `number`) => `void`	Fired when a rule row is clicked — wire this to the log filter for the cross-view “click a rule, see its traffic” interaction.
`selectedRuleIndex?`	`number`	Marks one rule row as the active selection.

TimeWindow

A half-open time window [start, end) in epoch-ms. The timeline buckets events whose at falls inside it; events outside are dropped from the histogram (but still counted in outOfWindow).

Properties

Property	Type
`end`	`number`
`start`	`number`

TrafficAuthState

Properties

Property	Type
`token?`	`Record`<`string`, `unknown`>
`uid`	`string`

TrafficBucket

Properties

Property	Type	Description
`allows`	`number`	`count - denies` — allowed + unsupported. The “non-deny” stack.
`count`	`number`	Total events that fell in this bucket.
`denies`	`number`	How many of `count` were denied.
`denyHeightRatio`	`number`	`denies / maxCount` — 0..1. The deny sub-stack height as a fraction of the tallest bucket, so the deny segment is drawn to the same scale as the full bar. Drives `--pyric-bucket-deny-h`.
`end`	`number`	-
`heightRatio`	`number`	`count / maxCount` across all buckets — 0..1. The full bar height as a fraction of the tallest bucket. Drives `--pyric-bucket-h`.
`index`	`number`	0-based bucket index, left (oldest) to right (newest).
`start`	`number`	Half-open bounds of this bucket `[start, end)` in epoch-ms.

TrafficCounts

Properties

Property	Type	Description
`denied`	`number`	Of those, how many were denied.
`listener`	`number`	Of those, how many are listener re-evals.
`total`	`number`	Events currently in the buffer.

TrafficDetailProps

Properties

Property	Type	Description
`className?`	`string`	-
`event`	`TrafficEvent`	-
`formatTime?`	(`at`: `number`) => `string`	Override the timestamp rendering. Default is `HH:MM:SS`.
`onBack?`	() => `void`	Fired by the back affordance. When absent, no back button.
`renderClassification?`	(`event`: `TrafficEvent`) => `ReactNode`	Render-prop slot below the header — the playground drops its denial overlay (classification + LLM analysis) here. The library doesn’t own that analysis.

TrafficEvent

Properties

Property	Type	Description
`at`	`number`	`Date.now()` at op start.
`auth`	`TrafficAuthState`	-
`durationMs?`	`number`	Canonical service-operation duration.
`evalMs?`	`number`	Simulator eval duration in ms. De-featured in the UI (local simulator) — present for the detail panel only.
`groupId?`	`string`	Shared across ops in one batch or transaction.
`groupKind?`	\| `"transaction"` \| `"batch"` \| `string` & { }	-
`id`	`string`	Unique per emission.
`kind?`	`"request"` \| `"operation"`	Source event kind. Firestore request events omit this in older adapters.
`matchedRule?`	`TrafficMatchedRule`	Parsed from the matched `Rule #N` debug line — absent if none.
`method`	`TrafficMethod`	-
`origin`	`TrafficOrigin`	-
`path`	`string`	-
`reasons`	`string`[]	Simulator debug messages — `Rule #N (op) → ALLOW` format.
`request?`	{ `data?`: `unknown`; `query?`: `unknown`; `resourceData?`: `unknown`; }	Proposed write payload — absent on reads + delete.
`request.data?`	`unknown`	-
`request.query?`	`unknown`	-
`request.resourceData?`	`unknown`	-
`resourceAfter?`	`TrafficResourceState`	Projected doc state after the write — absent on reads.
`resourceBefore?`	`TrafficResourceState`	Existing doc state before the write (or the read target).
`result`	`TrafficResult`	-
`service?`	\| `"firestore"` \| `"rtdb"` \| `"auth"` \| `"storage"` \| `string` & { }	Service that emitted the event. Omitted means Firestore.
`triggeredBy?`	{ `method`: `string`; `path?`: `string`; }	For listener re-evals — the originating user op.
`triggeredBy.method`	`string`	-
`triggeredBy.path?`	`string`	-

TrafficFilterState

Properties

Property	Type
`origin`	`TrafficOriginFilter`
`pathQuery`	`string`
`result`	`TrafficResultFilter`

TrafficGroup

Properties

Property	Type	Description
`count`	`number`	-
`denies`	`number`	-
`events`	`TrafficEvent`[]	-
`key`	`string`	`groupId` for batch/transaction; a synthetic key for listener runs. Stable enough for a React key.
`kind`	`TrafficGroupKind`	-
`type`	`"group"`	-

TrafficGroupRowProps

Properties

Property	Type	Description
`className?`	`string`	-
`defaultExpanded?`	`boolean`	Whether the group starts expanded. Default false — grouping exists to collapse volume, so collapsed is the useful default.
`formatTime?`	(`at`: `number`) => `string`	Passed through to each member `<TrafficRow>`.
`group`	`TrafficGroup`	-
`onSelect?`	(`event`: `TrafficEvent`) => `void`	-
`renderClassification?`	(`event`: `TrafficEvent`) => `ReactNode`	Passed through to each member `<TrafficRow>`.
`selectedId?`	`string`	-

TrafficLineChartProps

Properties

Property	Type	Description
`className?`	`string`	-
`emptyState?`	`ReactNode`	-
`formatTime?`	(`t`: `number`) => `string`	-
`formatValue?`	(`n`: `number`) => `string`	-
`omitZeroSeries?`	`boolean`	Omit all-zero series from the plot and tooltip while retaining their explicit total in the accompanying metric strip.
`points`	readonly `MetricPoint`[]	-
`series`	readonly `MetricSeries`[]	-
`visible?`	`ReadonlySet`<`string`>	Series keys currently drawn. Omit to draw every series. Pair with TrafficMetricCards’ `visible`/`onToggle` so the legend cards and the chart’s lines toggle in lockstep.

TrafficLogProps

Properties

Property	Type	Description
`className?`	`string`	-
`emptyState?`	`ReactNode`	-
`events`	`TrafficEvent`[]	Events to render, in display order. The hook layer decides the order — `<TrafficLog>` renders the array as given.
`formatTime?`	(`at`: `number`) => `string`	Passed through to each `<TrafficRow>`.
`items?`	`TrafficLogItem`[]	Grouped items from `useTrafficGroups`. When provided, the log renders singles + collapsible group rows and does NOT virtualize — grouping is itself the volume reducer (a 250-event listener storm becomes one group row). `events` is ignored.
`onSelect?`	(`event`: `TrafficEvent`) => `void`	-
`renderClassification?`	(`event`: `TrafficEvent`) => `ReactNode`	Passed through to each `<TrafficRow>`.
`renderRow?`	(`event`: `TrafficEvent`, `selected`: `boolean`) => `ReactNode`	Full escape hatch — render a row yourself instead of the default `<TrafficRow>`. Receives the event and its selected state. Applies to the flat (`events`) path only.
`rowHeight?`	`number` \| (`index`: `number`) => `number`	Estimated row height when virtualizing. Default 28.
`selectedId?`	`string`	The selected event’s id, marked with `data-pyric-selected`.
`virtualizedHeight?`	`string` \| `number`	Pixel height the virtualized scroll container fills. Default `'60vh'`.
`virtualizeThreshold?`	`number`	Above this row count, the list virtualizes via `<VirtualList>`. Default 100 — a `load-test`-shaped session can emit 100k+ events, so virtualization is load-bearing, not polish.

TrafficMatchedRule

Properties

Property	Type
`operations`	`string`[]
`ruleIndex`	`number`

TrafficMetricCardsProps

Properties

Property	Type	Description
`className?`	`string`	-
`formatValue?`	(`n`: `number`) => `string`	-
`onToggle?`	(`key`: `string`) => `void`	-
`series`	readonly `MetricSeries`[]	-
`visible?`	`ReadonlySet`<`string`>	When supplied (with `onToggle`), each card gets a checkbox and doubles as the chart’s legend — Console reference semantics (“toggle series visibility”). Omit for a read-only totals strip.

TrafficMetricsResult

Properties

Property	Type	Description
`maxValue`	`number`	The largest single-bucket value across every series — the shared y-scale divisor a chart would use by default.
`points`	`MetricPoint`[]	-
`series`	`MetricSeries`[]	-

TrafficResourceState

Properties

Property	Type
`data`	`unknown`
`exists`	`boolean`

TrafficRowProps

Properties

Property	Type	Description
`className?`	`string`	-
`event`	`TrafficEvent`	-
`formatTime?`	(`at`: `number`) => `string`	Override the timestamp rendering. Default is `HH:MM:SS`.
`onSelect?`	(`event`: `TrafficEvent`) => `void`	-
`renderClassification?`	(`event`: `TrafficEvent`) => `ReactNode`	Render-prop slot for a consumer-specific classification badge — e.g. the playground’s `expected`/`ambiguous`/`unexpected` verdict, which is app-source analysis the library doesn’t own. Returns `null` to render nothing.
`selected?`	`boolean`	Marks the row as the active selection (`data-pyric-selected`).

TrafficSingle

Properties

Property	Type
`event`	`TrafficEvent`
`type`	`"single"`

TrafficStatBucket

Properties

Property	Type
`count`	`number`
`key`	`string`

TrafficStatsProps

Properties

Property	Type
`className?`	`string`
`stats`	`TrafficStatsSummary`

TrafficStatsSummary

Properties

Property	Type	Description
`allows`	`number`	-
`byMethod`	`TrafficStatBucket`[]	Counts by method, sorted descending.
`byOrigin`	`TrafficStatBucket`[]	Counts by origin, sorted descending.
`byPath`	`TrafficStatBucket`[]	Counts by path, sorted descending, capped at `topPaths`.
`denies`	`number`	-
`denyRate`	`number`	`denies / total` — 0 for an empty buffer.
`total`	`number`	-
`unsupported`	`number`	-

TrafficTimelineProps

Properties

Property	Type	Description
`axis?`	`ReactNode` \| (`window`: `TimeWindow`) => `ReactNode`	Axis slot — tick labels below the bars inside `[data-pyric-timeline-axis]`. The mock puts “14m ago · 7m · now” here. Receives the resolved window so labels can be derived.
`brush?`	`TimeWindow`	A brushed sub-range (`[start, end)`) drawn as an overlay over the bars. Position is derived from where it falls inside `window`, so a partly-out-of-window brush clamps to the chart edges.
`bucketCount?`	`number`	Number of bars. Default 30. Only used on the `events` path.
`buckets?`	`UseTrafficBucketsResult`	Pre-bucketed counts — the escape hatch when the caller already ran useTrafficBuckets (or `bucketTraffic`) upstream, e.g. to share one bucketing pass across the timeline + a stats header. Takes precedence over `events`.
`className?`	`string`	-
`emptyState?`	`ReactNode`	-
`events?`	`TrafficEvent`[]	Raw traffic events to bucket. Ignored when `buckets` is supplied (the consumer pre-bucketed). Exactly one of `events` / `buckets` should drive the histogram.
`header?`	`ReactNode`	Header slot — title, deny summary, live label. Rendered above the bars inside `[data-pyric-timeline-header]`. The mock puts “142 requests · 16 denied · live” here.
`liveAt?`	`number`	Where the live edge marker sits, in epoch-ms. Defaults to `window.end` (the right edge = “now”). Omit / pass `null` to hide the marker entirely (e.g. a frozen, non-live window).
`onBrush?`	(`window`: `TimeWindow`) => `void`	Fired when a bar inside the brush region is clicked-through — the component itself is presentation-agnostic about drag, so the primary brush gesture is owned by the consumer. As a built-in affordance, clicking a bucket calls this with a one-bucket-wide window so a bare consumer still gets a working selection.
`renderBucketSummary?`	(`bucket`: `TrafficBucket`) => `ReactNode`	Direct annotation shown while a bucket is hovered or keyboard-focused. The timeline owns preview state and positioning; the consumer owns the words and number formatting.
`window`	`TimeWindow`	The time range the histogram spans.

UseRuleHeatmapOptions

Properties

Property	Type
`events`	`TrafficEvent`[]

UseRuleHeatmapResult

Properties

Property	Type	Description
`entries`	`RuleHeatmapEntry`[]	Per-rule rollup, sorted by `total` descending (busiest first), ties broken by `ruleIndex` ascending.
`unmatchedCount`	`number`	Events that matched no rule — counted here, not attributed to any entry.

UseTrafficBucketsOptions

Properties

Property	Type	Description
`bucketCount?`	`number`	Number of buckets to divide the window into. Default 30.
`events`	`TrafficEvent`[]	-
`window`	`TimeWindow`	The time range to bucket over.

UseTrafficBucketsResult

Properties

Property	Type	Description
`buckets`	`TrafficBucket`[]	-
`denies`	`number`	Sum of `denies` across buckets.
`maxCount`	`number`	The largest single-bucket `count` — the height-ratio divisor.
`outOfWindow`	`number`	Events whose `at` fell outside `[window.start, window.end)`.
`total`	`number`	Sum of `count` across buckets (events inside the window).

UseTrafficFilterOptions

Properties

Property	Type	Description
`events`	`TrafficEvent`[]	-
`initialOrigin?`	`TrafficOriginFilter`	Default `user` — the probe found listener traffic is 94–99.6% of events, so it’s hidden until explicitly asked for.
`initialPathQuery?`	`string`	-
`initialResult?`	`TrafficResultFilter`	Default `all` — the probe found ~75–80% allow in realistic sessions, so hiding either side loses diagnostic signal.

UseTrafficFilterResult

Properties

Property	Type	Description
`filter`	`TrafficFilterState`	-
`filtered`	`TrafficEvent`[]	Events passing all three filters, in the input order.
`setOrigin`	(`origin`: `TrafficOriginFilter`) => `void`	-
`setPathQuery`	(`pathQuery`: `string`) => `void`	-
`setResult`	(`result`: `TrafficResultFilter`) => `void`	-

UseTrafficGroupsOptions

Properties

Property	Type	Description
`events`	`TrafficEvent`[]	-
`groupBatches?`	`boolean`	Collapse consecutive ops sharing a `groupId`. Default true.
`groupListenerRuns?`	`boolean`	Collapse a consecutive run of listener re-evals from the same originating op into one group — the probe found a single write can trigger 250+ re-evals. Default true.

UseTrafficGroupsResult

Properties

Property	Type	Description
`items`	`TrafficLogItem`[]	Events folded into a flat list of singles and groups, in the input order.

UseTrafficMetricsOptions

Properties

Property	Type	Description
`bucketCount?`	`number`	Number of buckets to divide the window into. The window itself should already be sized to the session (sandbox sessions run minutes, not days) — bucket count doesn’t need to change, only the window a caller passes in. Default 24.
`events`	`TrafficEvent`[]	-
`isAdmin?`	(`event`: `Pick`<`TrafficEvent`, `"origin"`>) => `boolean`	Override admin classification (e.g. a Studio caller with `authLens` provenance available — see the module doc). Defaults to `origin === 'admin'`.
`window`	`TimeWindow`	-

UseTrafficMonitorOptions

Properties

Property	Type	Description
`bufferSize?`	`number`	Ring-buffer cap. Once exceeded, the oldest events are dropped. Default 5000 (~3 MB worst case — see the traffic-monitor probe findings).
`paused?`	`boolean`	Whether the buffer starts paused. Default false.
`source`	`TrafficSource`	The subscription function — `sandbox.onRequest` satisfies this directly. Pass a stable reference; the hook re-subscribes on identity change.
`transform?`	(`event`: `TrafficEvent`) => `TrafficEvent`	Runs per event before buffering — return a (possibly trimmed) event. Lets the consumer shrink oversized payloads without the library knowing payload semantics. Identity is read fresh on each event, so it need not be memoized.

UseTrafficMonitorResult

Properties

Property	Type	Description
`clear`	() => `void`	Empty the buffer.
`counts`	`TrafficCounts`	-
`events`	`TrafficEvent`[]	The buffered events, oldest first.
`isPaused`	`boolean`	-
`pause`	() => `void`	Stop appending — incoming events are dropped while paused.
`resume`	() => `void`	Resume appending.

UseTrafficStatsOptions

Properties

Property	Type	Description
`events`	`TrafficEvent`[]	-
`topPaths?`	`number`	Cap on `byPath` entries — paths are unbounded. Default 10.

Type Aliases

BillableSeriesKey

type BillableSeriesKey = "reads" | "writes" | "deletes";

RulesSeriesKey

type RulesSeriesKey = "allows" | "denies" | "errors";

TrafficGroupKind

type TrafficGroupKind = "batch" | "transaction" | "listener-run";

TrafficLogItem

type TrafficLogItem = TrafficGroup | TrafficSingle;

TrafficMethod

type TrafficMethod =
  | "get"
  | "list"
  | "create"
  | "update"
  | "set"
  | "delete"
  | "remove"
  | "push"
  | "listen"
  | "transaction"
  | string & {
};

The traffic domain types. TrafficEvent is structurally identical to pyric/sandbox’s RequestEvent (locked in the design rationale) — but the library defines its own copy so it never imports pyric/sandbox. sandbox.onRequest is assignable as a TrafficSource with zero adapter code; a prod log feed can satisfy the same shape.

TrafficOrigin

type TrafficOrigin = "user" | "listener" | "transaction" | "batch" | "admin" | "system";

TrafficOriginFilter

type TrafficOriginFilter = "user" | "all" | "listener";

user keeps everything that isn’t a listener re-eval (user ops plus their transaction/batch sub-ops); listener keeps only listener re-evals; all keeps everything.

TrafficResult

type TrafficResult = "allow" | "deny" | "unsupported" | "error" | "not-applicable";

TrafficResultFilter

type TrafficResultFilter = "all" | "allow" | "deny";

TrafficSource()

type TrafficSource = (cb: (event: TrafficEvent) => void) => () => void;

A subscription function: register a callback, get back an unsubscribe. pyric/sandbox’s Sandbox.onRequest matches this signature exactly.

Parameters

Parameter	Type
`cb`	(`event`: `TrafficEvent`) => `void`

Returns

(): void;

Returns

void

Variables

BILLABLE_SERIES_DEFS

const BILLABLE_SERIES_DEFS: ReadonlyArray<{
  key: BillableSeriesKey;
  label: string;
}>;

RULES_SERIES_DEFS

const RULES_SERIES_DEFS: ReadonlyArray<{
  key: RulesSeriesKey;
  label: string;
}>;

Functions

bucketBillableMetrics()

function bucketBillableMetrics(
   events: readonly TrafficEvent[],
   window: TimeWindow,
   bucketCount?: number,
   isAdmin?: (event: Pick<TrafficEvent, "origin">) => boolean): TrafficMetricsResult;

Pure kernel behind useBillableMetrics — usable outside React.

Parameters

Parameter	Type
`events`	readonly `TrafficEvent`[]
`window`	`TimeWindow`
`bucketCount?`	`number`
`isAdmin?`	(`event`: `Pick`<`TrafficEvent`, `"origin"`>) => `boolean`

Returns

TrafficMetricsResult

bucketRulesMetrics()

function bucketRulesMetrics(
   events: readonly TrafficEvent[],
   window: TimeWindow,
   bucketCount?: number,
   isAdmin?: (event: Pick<TrafficEvent, "origin">) => boolean): TrafficMetricsResult;

Pure kernel behind useRulesMetrics — usable outside React.

Parameters

Parameter	Type
`events`	readonly `TrafficEvent`[]
`window`	`TimeWindow`
`bucketCount?`	`number`
`isAdmin?`	(`event`: `Pick`<`TrafficEvent`, `"origin"`>) => `boolean`

Returns

TrafficMetricsResult

bucketTraffic()

function bucketTraffic(
   events: TrafficEvent[],
   window: TimeWindow,
   bucketCount?: number): UseTrafficBucketsResult;

The pure bucketing kernel behind useTrafficBuckets — usable outside React. Returns an empty result for a non-positive bucketCount or a zero/negative-width window.

Parameters

Parameter	Type
`events`	`TrafficEvent`[]
`window`	`TimeWindow`
`bucketCount?`	`number`

Returns

UseTrafficBucketsResult

classifyBillable()

function classifyBillable(event: Pick<TrafficEvent, "method" | "result" | "origin">, isAdmin?: (event: Pick<TrafficEvent, "origin">) => boolean): BillableSeriesKey;

Classify a billable op, or null if it isn’t one / never ran.

Parameters

Parameter	Type
`event`	`Pick`<`TrafficEvent`, `"method"` \| `"result"` \| `"origin"`>
`isAdmin?`	(`event`: `Pick`<`TrafficEvent`, `"origin"`>) => `boolean`

Returns

BillableSeriesKey

classifyRules()

function classifyRules(event: Pick<TrafficEvent, "result" | "origin">, isAdmin?: (event: Pick<TrafficEvent, "origin">) => boolean): RulesSeriesKey;

Classify a rules-engine verdict, or null if it isn’t one (bypassed, unsupported, or not-applicable).

Parameters

Parameter	Type
`event`	`Pick`<`TrafficEvent`, `"result"` \| `"origin"`>
`isAdmin?`	(`event`: `Pick`<`TrafficEvent`, `"origin"`>) => `boolean`

Returns

RulesSeriesKey

defaultFormatTime()

function defaultFormatTime(at: number): string;

Default HH:MM:SS timestamp formatter. Components accept a formatTime prop to override — this is just the fallback so the library has no hard locale dependency.

Parameters

Parameter	Type
`at`	`number`

Returns

string

isAdminEvent()

function isAdminEvent(event: Pick<TrafficEvent, "origin">): boolean;

Default admin predicate: the one signal the public TrafficEvent type declares. See the module doc for the known Firestore gap.

Parameters

Parameter	Type
`event`	`Pick`<`TrafficEvent`, `"origin"`>

Returns

boolean

reasonVerdict()

function reasonVerdict(reason: string): "allow" | "deny" | "neutral";

Classifies a simulator debug line as a deny / allow / neutral verdict so consumers can tint reason rows via [data-pyric-reason-verdict="…"].

Parameters

Parameter	Type
`reason`	`string`

Returns

"allow" | "deny" | "neutral"

RuleHeatmap()

function RuleHeatmap(__namedParameters: RuleHeatmapProps): Element;

Headless rule heatmap — one row per rule, busiest first. Each row exposes two styling channels:

data-pyric-rule-heat — a discrete bucket (none/low/ medium/high) by deny ratio, for threshold-based coloring.
--pyric-deny-ratio — the raw 0–1 ratio as a CSS custom property, for a proportional bar / gradient.

Counts render as separate elements (data-pyric-rule-total, -allows, -denies) so the consumer can show numbers, bars, or both.

Styling hooks: [data-pyric-ui="rule-heatmap"], [data-pyric-rule-row] (with data-pyric-rule-index, data-pyric-rule-heat, data-pyric-selected).

Parameters

Parameter	Type
`__namedParameters`	`RuleHeatmapProps`

Returns

Element

TrafficDetail()

function TrafficDetail(__namedParameters: TrafficDetailProps): Element;

Headless drill-in panel for a single traffic event. Renders the header (result + origin + timestamp + method/path + matched rule), a consumer classification slot, then JSON sections for auth, request payload, and resource before/after via <JsonView>, plus the reasons list, triggeredBy, and groupId.

evalMs appears here as a minor header field only — it is not a log column (local simulator; latency is de-featured per the design rationale).

Styling hooks: [data-pyric-ui="traffic-detail"], [data-pyric-traffic-section] (with data-pyric-section-label), [data-pyric-traffic-reason] (with data-pyric-reason-verdict).

Parameters

Parameter	Type
`__namedParameters`	`TrafficDetailProps`

Returns

Element

TrafficGroupRow()

function TrafficGroupRow(__namedParameters: TrafficGroupRowProps): Element;

A collapsible group row — one header summarizing a batch, transaction, or listener-run, expanding to the member rows. The header carries data-pyric-group-kind and a data-pyric-group-* count/deny rollup; expansion state is data-pyric-expanded.

Styling hooks: [data-pyric-traffic-group], [data-pyric-traffic-group-header] (with data-pyric-group-kind), [data-pyric-traffic-group-members].

Parameters

Parameter	Type
`__namedParameters`	`TrafficGroupRowProps`

Returns

Element

TrafficLineChart()

function TrafficLineChart(__namedParameters: TrafficLineChartProps): Element;

Hand-rolled SVG line chart, no charting dependency — plain lines over a 0..100 viewBox so CSS drives the actual size (intrinsic layout, no fixed pixel chart). Each series draws only when visible includes its key (or visible is omitted). The y-scale is the max value across the currently VISIBLE series only, so toggling a tall series off rescales the rest up — matching the Console reference.

Interaction: hovering (or focusing, via the invisible per-bucket hit targets) shows a tooltip with the bucket’s time range and each visible series’ value at that bucket — [data-pyric-chart-tooltip], positioned via --pyric-hover-x.

Styling hooks: [data-pyric-ui="traffic-line-chart"], [data-pyric-chart-svg], [data-pyric-chart-line] (with data-pyric-series-key, data-pyric-series-index — the same index a TrafficMetricCards card carries, so line + card colors line up), [data-pyric-chart-hit] (with data-pyric-point-index), [data-pyric-chart-tooltip], [data-pyric-tooltip-row].

Parameters

Parameter	Type
`__namedParameters`	`TrafficLineChartProps`

Returns

Element

TrafficLog()

function TrafficLog(__namedParameters: TrafficLogProps): Element;

Headless traffic log — a Chrome DevTools Network-panel-style event stream. Below virtualizeThreshold it renders a plain <ul>; above it, TanStack-Virtual via <VirtualList>.

Styling hooks: [data-pyric-ui="traffic-log"], [data-pyric-traffic-entry] (the list item wrapper), plus the <TrafficRow> hooks.

Parameters

Parameter	Type
`__namedParameters`	`TrafficLogProps`

Returns

Element

TrafficMetricCards()

function TrafficMetricCards(__namedParameters: TrafficMetricCardsProps): Element;

The period-total strip: one card per series, each showing the series’ total for the current window. Doubles as BOTH the chart’s legend row (pass visible + onToggle to get the checkbox-toggle semantics) AND the standalone fallback presentation when a chart isn’t warranted — this component never depends on TrafficLineChart.

Styling hooks: [data-pyric-ui="traffic-metric-cards"], [data-pyric-metric-card] (with data-pyric-metric-key, data-pyric-series-index — the color channel a chart’s lines also key off of, so a card and its line always match), [data-pyric-metric-hidden] when toggled off.

Parameters

Parameter	Type
`__namedParameters`	`TrafficMetricCardsProps`

Returns

Element

TrafficRow()

function TrafficRow(__namedParameters: TrafficRowProps): Element;

One headless traffic row — timestamp, method badge, path, and an optional consumer classification slot. The raw result is exposed as data-pyric-result on the row (for tinting/filtering); rendering a verdict/outcome label is the consumer’s job via renderClassification — the row itself draws no result chip, so a consumer verdict never collides with a built-in one. Latency is intentionally absent: this is a local simulator, so evalMs lives in <TrafficDetail> only.

Styling hooks:

[data-pyric-traffic-row] — the row button, with data-pyric-result, data-pyric-origin, data-pyric-method
[data-pyric-traffic-row][data-pyric-selected] — active row
[data-pyric-traffic-time] / [data-pyric-traffic-path]
[data-pyric-traffic-service] — the service label (firestore / rtdb / storage / auth), rendered even when unknown (empty) so fixed-width styling keeps the columns aligned
method renders as <Badge> (data-pyric-badge-kind)

Parameters

Parameter	Type
`__namedParameters`	`TrafficRowProps`

Returns

Element

TrafficStats()

function TrafficStats(__namedParameters: TrafficStatsProps): Element;

Headless aggregation panel. Renders the totals, the deny rate, and count breakdowns by method / origin / path. The deny rate is exposed both as text and as a --pyric-deny-rate CSS custom property on the root for a proportional meter.

Styling hooks: [data-pyric-ui="traffic-stats"], [data-pyric-stat] (with data-pyric-stat-key), [data-pyric-stat-group] (with data-pyric-stat-group-label), [data-pyric-stat-bucket].

Parameters

Parameter	Type
`__namedParameters`	`TrafficStatsProps`

Returns

Element

TrafficTimeline()

function TrafficTimeline(__namedParameters: TrafficTimelineProps): Element;

Headless volume-over-time histogram — the time axis for the traffic lens. Buckets events into N bars; each bar stacks denies (dark, at the base) under the allow remainder, matching the Studio mock.

Per-bucket styling channels (on [data-pyric-bucket]):

data-pyric-bucket-count / -denies — raw integers.
--pyric-bucket-h — full bar height, 0..1 of the tallest bucket.
--pyric-bucket-deny-h — deny sub-stack height, same scale. The deny segment ([data-pyric-bucket-deny]) and allow segment ([data-pyric-bucket-allow]) are separate children so the consumer colors them independently.

A [data-pyric-brush] overlay marks a sub-range via --pyric-brush-left / --pyric-brush-right (0..1 fractions). The [data-pyric-live] edge marker sits at --pyric-live-x.

Styling hooks: [data-pyric-ui="traffic-timeline"], [data-pyric-timeline-header], [data-pyric-timeline-bars], [data-pyric-bucket] (with data-pyric-bucket-index, data-pyric-has-denies, data-pyric-bucket-selected), [data-pyric-bucket-summary], [data-pyric-brush], [data-pyric-live], [data-pyric-timeline-axis].

Parameters

Parameter	Type
`__namedParameters`	`TrafficTimelineProps`

Returns

Element

useBillableMetrics()

function useBillableMetrics(__namedParameters: UseTrafficMetricsOptions): TrafficMetricsResult;

Reads / writes / deletes, bucketed over window. See the module doc for the billable mapping + the “read ops, not billable reads” caveat.

Parameters

Parameter	Type
`__namedParameters`	`UseTrafficMetricsOptions`

Returns

TrafficMetricsResult

useRuleHeatmap()

function useRuleHeatmap(__namedParameters: UseRuleHeatmapOptions): UseRuleHeatmapResult;

Rolls a traffic buffer up by matchedRule.ruleIndex: how often each rule fired, and how that split across allow / deny / unsupported. Pure derivation — feed it the filtered or full event list depending on what the heatmap should reflect.

Parameters

Parameter	Type
`__namedParameters`	`UseRuleHeatmapOptions`

Returns

UseRuleHeatmapResult

useRulesMetrics()

function useRulesMetrics(__namedParameters: UseTrafficMetricsOptions): TrafficMetricsResult;

Allows / denies / errors, bucketed over window. Excludes rules-bypassed (admin) ops — see the module doc.

Parameters

Parameter	Type
`__namedParameters`	`UseTrafficMetricsOptions`

Returns

TrafficMetricsResult

useTrafficBuckets()

function useTrafficBuckets(__namedParameters: UseTrafficBucketsOptions): UseTrafficBucketsResult;

Buckets a traffic buffer into bucketCount equal time slices over window, counting total + denied events per slice. Pure derivation — the histogram component renders the result, this hook (and bucketTraffic under it) owns the math.

Each bucket carries a heightRatio and denyHeightRatio (0..1, scaled to the tallest bucket) so the consumer can map them straight onto a bar height without re-finding the max.

Parameters

Parameter	Type
`__namedParameters`	`UseTrafficBucketsOptions`

Returns

UseTrafficBucketsResult

useTrafficFilter()

function useTrafficFilter(__namedParameters: UseTrafficFilterOptions): UseTrafficFilterResult;

Derives a filtered view over a traffic buffer along three dimensions: origin, result, and a case-insensitive path substring. Owns the filter state; pure derivation otherwise.

Parameters

Parameter	Type
`__namedParameters`	`UseTrafficFilterOptions`

Returns

UseTrafficFilterResult

useTrafficGroups()

function useTrafficGroups(__namedParameters: UseTrafficGroupsOptions): UseTrafficGroupsResult;

Folds a traffic buffer into a list of singles and collapsible groups. Two grouping modes, both over consecutive events:

groupId — batch/transaction sub-ops sharing an id collapse into one batch / transaction group.
listener runs — a consecutive run of listener re-evals from the same originating op collapses into one listener-run group. A run of length 1 stays a single (no point collapsing one row).

Pure derivation; the input order is preserved.

Parameters

Parameter	Type
`__namedParameters`	`UseTrafficGroupsOptions`

Returns

UseTrafficGroupsResult

useTrafficMonitor()

function useTrafficMonitor(__namedParameters: UseTrafficMonitorOptions): UseTrafficMonitorResult;

Buffers a traffic stream into a capped ring buffer with pause/resume/clear. Decoupled from pyric/sandbox — source is just a (cb) => unsubscribe function.

Pause is consumer-side: while paused, the subscription stays attached but incoming events are dropped (not queued). This matches the probe decision — a load-test-shaped session can emit 100k+ events, so queueing-while-paused would defeat the point.

Parameters

Parameter	Type
`__namedParameters`	`UseTrafficMonitorOptions`

Returns

UseTrafficMonitorResult

useTrafficStats()

function useTrafficStats(__namedParameters: UseTrafficStatsOptions): TrafficStatsSummary;

Aggregations over a traffic buffer: totals, deny rate, and counts broken down by method, origin, and path. Pure derivation — feed it the filtered or full event list depending on what the panel should reflect.

Parameters

Parameter	Type
`__namedParameters`	`UseTrafficStatsOptions`

Returns

TrafficStatsSummary