Core runtime state, diagnostics, and debug

This reference describes the runtime read and diagnostic contracts of the Core Projection and Direct Renderer facades. Start with the Core API for methods, lifecycle, and events, or Core rendering for the integration protocols. The Core README owns configuration fields and package orientation.

Runtime read surfaces

TrackerSnapshot, its branch/item types, TrackerStats, TrackerDebugStats, TrackerDiagnosticStats, TrackerDiagnosticEntry, TrackerDiagnosticCode, and the error types are root exports from @rightxt/tracker-core. TrackerSnapshotListener is (snapshot: TrackerSnapshot) => void; TrackerSnapshotUnsubscribe is () => void. TrackerDiagnosticsSink is independently exported from /renderer. Advanced types are exported from /advanced; corresponding explicit /debug entries expose the same static type surfaces.

These contracts apply to original Core facades. An adapter's public object is governed by that package's API; sharing Core does not establish snapshot, subscription, or advanced-accessor parity.

Snapshots

Every snapshot is a detached, deeply frozen Tracker-owned graph. It contains no source Elements, root nodes, Events, or live application callback graphs. Later runtime changes cannot mutate an earlier snapshot. This differs from borrowed event payload details and renderer records.

Snapshot structure

TrackerSnapshot has these 15 top-level fields:

TrackerOptionsSnapshot includes orientation, placement, cssVariables, track, viewport, markerLayer, optional marker, clustering, interaction, and a11y. It omits updates, diagnostics, rules, and mount roots. It is not a complete TrackerOptions clone or a configuration-replacement payload. options.cssVariables retains committed strings, including blank strings; input null tombstones are absent from committed values.

The three name tables describe supported render hooks, not live DOM state or proof that a custom renderer materializes each hook. Their types are /renderer exports. The variable constant map is not the exhaustive configurable theme inventory; see Styling.

render.dirtyTarget is retained work, especially from unmounted changes or render: false; null means no retained dirty target. Render targets distinguish 'all', 'markers', 'marker-presentation', 'track', and 'viewport'. The declaration's support type is not independently root-exported. pending indicates a pending scheduler target and/or frame; running is reported execution state. Successful terminal render events and settlement snapshots observe running: false.

selection.enabled follows keyboard accessibility enablement; selection.key names a current render record, either a marker or a cluster. Item DTOs do not contain a selected boolean. Selection is a separate domain and does not automatically transfer identity when clustering changes the render key.

Marker items

TrackerMarkerSnapshot has 14 fields:

There is no element field. Clustered logical markers do not also appear in snapshot.markers; their keys appear in cluster membership. Use items when mixed spatial order matters. Equal start positions use rule order as the tie-breaker.

Cluster items

TrackerClusterSnapshot has 13 fields:

The first spatially ordered marker in a cluster is primary and owns its rule presentation. TrackerSnapshotItem is the union of marker and cluster snapshots, discriminated by kind. diagnostics.markers.current counts logical markers before clustering, so it can exceed snapshot.markers.length.

Viewport

The three TrackerViewportSnapshot fields are visible, start, and size. Start and size are track-axis percentages. Visibility requires enabled viewport output and a visible committed layout. Disabled, unavailable, suspended, unmounted, or destroyed output is { visible: false, start: 0, size: 0 }.

This DTO has no end, orientation, or raw pixel measurements. The richer renderer layout is documented under renderer records.

Snapshot identity and publication

Repeated getSnapshot() calls within the same observable revision return the same object. A later revision produces a new snapshot; no stable nested-object identity protocol is promised. The revision is not a public snapshot field. A read may lazily materialize a revision without invoking listeners, and snapshot publication does not mean browser paint or framework commit.

This is a settlement-oriented read surface, not an event for every internal write. Snapshot revision, snapshot publication, and Projection commit are distinct. A diagnostic or render-state revision need not change any Projection view domain.

Key lifetime

Marker keys follow source Element identity within one Core instance. The same Element preserves its key across ordinary renders, record rebuilds, owning-rule changes, disappearance/reappearance, and unmount/remount. A replacement Element gets a new key. Presentation, label, rule index, and selector can change while the key remains the same. Destroy terminates that instance's identity lifetime.

Cluster keys use ordered membership:

c:<markerKey>|<markerKey>|...

The same ordered membership preserves the key; a membership or order change produces a different key. Marker and cluster keys describe distinct render records, so clustering/declustering is not a semantic selection-identity transfer.

Snapshot subscriptions

Register a function, read the initial state explicitly, and release each owned registration:

import type { TrackerSnapshot } from '@rightxt/tracker-core';
import type { TrackerProjectionIntegration } from '@rightxt/tracker-core/projection';

function observe(integration: TrackerProjectionIntegration, consume: (state: TrackerSnapshot) => void) {
  const unsubscribe = integration.subscribeSnapshot(consume);
  consume(integration.getSnapshot());
  return unsubscribe;
}

Delivery is synchronous and future-only. Repeated registration of the same listener identity creates independently releasable ownership while invoking the listener once per publication. Each returned unsubscribe is idempotent; releasing one registration does not remove the others. An invalid non-function listener or registration after destroy returns an inert unsubscribe. Existing listeners are released after the final destroy publication.

Synchronous listener throws are contained and reported through the host error-reporting/async error transport; they do not become Core event-handler diagnostic counters or abort the state commit. Returned values, including thenables, are ignored and uninspected. A snapshot callback should handle its own asynchronous work and rejections. This differs from Core event handlers and Projection listeners, whose rejected thenables are observed.

Valid state-changing calls during public dispatch defer until that dispatch/enclosing operation exits; call-time validation can still throw. Synchronous feedback is bounded: more than 1,000 continuously generated snapshot emissions reaches the reentrancy limit and remaining work is bounded/dropped at that boundary. See transaction boundaries for the distinct behavior of renderer/lifecycle callbacks.

Stats

getStats() returns a detached clone. Unlike a snapshot, the standalone result is not runtime-frozen; modifying it cannot modify Core's counters. snapshot.diagnostics is the frozen value captured for its snapshot revision.

TrackerStats has nine declared top-level fields, including optional debug; normal production materializes eight. The counter groups contain 20 fixed public counters: 5 render, 5 rule, 3 marker, 1 cluster, 4 observer, and 2 diagnostic totals. Dynamic per-code maps, timing, and debug fields are additional values.

Observer counters are signals accepted by their respective transport stages, not a uniform raw-event count. There is no general ignored/dropped-event counter. See updates and refresh for scheduling and observation workflow.

TrackerDiagnosticStats.total counts that severity, byCode: Record<string, number> accumulates code counts, and last: TrackerDiagnosticEntry | null retains only the latest sanitized entry. It is not diagnostic history.

Timing and metrics

All counters continue updating regardless of diagnostics.metrics. That option gates render timing values only. Without metrics or a usable performance clock, lastRender.duration and lastRender.timestamp are null. Changing the flag does not itself request a render or rewrite an existing lastRender; a subsequent successful render reflects the new setting.

lastRender is the last successful result, not live geometry. It can survive unmount or geometry suspension while current marker/cluster counts are cleared. Timing uses the active performance-style clock and is not a wall-clock timestamp.

Stats reset and lifecycle

resetStats() requires an alive facade and participates in public-operation deferral. It zeros every fixed counter, including markers.current and clusters.current, clears byCode maps, sets retained diagnostics and lastRender to null, and clears debug trace. It leaves configuration, rules, logical records, selection, pending work, observers, and lifecycle in place.

Consequently, current counters may read zero immediately after reset while render items still exist. Reset does not remeasure them, request rendering, or force a Projection commit. It publishes a snapshot of the changed stats.

Reads remain available after destroy. Terminal stats include cleanup and callback failures already recorded at capture. A rejected event-handler thenable can be reported later and refresh retained final stats and the read revision; the previously retained snapshot remains unchanged. This does not reopen lifecycle operations or subscriptions. resetStats() after destroy rejects with ERR_TRACKER_DESTROYED.

Errors

The root exports three runtime classes: TrackerError extends Error, TrackerConfigurationError extends TrackerError, and TrackerLifecycleError extends TrackerError. Their construction uses a message and TrackerErrorOptions, which extends native ErrorOptions with required code: TrackerErrorCode and supports native cause.

The concrete class sets name; code is readonly at the TypeScript boundary, not a runtime-freeze guarantee. Strict diagnostic assertion can put the complete validation array in cause; do not assume every Tracker error has that cause shape.

These nine codes do not cover every public thrown value. Native TypeError, AggregateError, and original renderer/callback failures can also propagate. Cleanup failure can throw after unmounted/destroyed state has already committed; see lifecycle settlement.

Diagnostic channels

A warning need not throw, and an error-level runtime diagnostic need not throw. Strict mutation rejection does not automatically route every validation diagnostic through runtime channels. The validator reference explains recovered candidates and atomic rejection.

TrackerDiagnosticEntry has code: TrackerDiagnosticCode, message: string, and details: Readonly<Record<string, unknown>> | null. TrackerWarningEventPayload uses this entry shape. TrackerValidationDiagnostic adds type: 'warning' | 'error'. Codes are stable branching keys; human-readable messages and incidental detail keys are not stable per-code schemas.

Warning delivery

The ordinary warning order is:

sanitized retained copy / warning stats
→ configured output.warn or console.warn fallback
→ Core warning event

diagnostics.warnings controls only fallback console.warn. Setting it to false leaves a configured output.warn, warning counters, and the Core warning event active. It does not control errors or console.error.

The warning event envelope is frozen; its contextual details is borrowed and can contain live objects. Output/event consumers should copy what they need rather than assuming retained-stats sanitation applies to the immediate path. Handler return values do not cancel the warning or prior work.

Diagnostic output sink

TrackerDiagnosticsOptions.output accepts a TrackerDiagnosticsSink | null. Import the named sink type from @rightxt/tracker-core/renderer:

import type { TrackerDiagnosticCode } from '@rightxt/tracker-core';
import type { TrackerDiagnosticsSink } from '@rightxt/tracker-core/renderer';

const output: TrackerDiagnosticsSink = {
  warn(code: TrackerDiagnosticCode, message: string, details?: Record<string, unknown>) {
    console.info('Tracker warning', code, message, details);
  },
  error(code: TrackerDiagnosticCode, message: string, details?: Record<string, unknown>) {
    console.error('Tracker error', code, message, details);
  },
};

Both methods are optional independently, return void, and replace console fallback only for their own severity. They complement stats and warning events. output: null clears the sink; complete option replacement can also restore the default of no sink.

The sink is caller-owned. Its identity survives configuration cloning; Core does not freeze, flush, close, or dispose it. Destroy releases Core's references. Synchronous sink throws are swallowed. Returned thenables are not awaited; rejections are observed and swallowed without recursively generating a sink-failure diagnostic. A sink cannot change the operation's original success/failure outcome.

Diagnostic codes and retained details

TrackerDiagnosticCode contains 83 stable values. The catalog identifies normal severity and emission surface; it does not promise an exact human message or a typed details object. Some defensive/internal-boundary diagnostics remain public union values even though normal facade validation prevents callers from reaching those paths. Integration-owned values are included to account for the union, without defining adapter API behavior here.

invalid-rule-index belongs to strict insertion/removal validation and is not returned by the three pure validators. duplicate-rule-selector is warning-level but can invalidate the result. Recovered rule CSS values exclude invalid names as well as unsupported values. Normal Tracker mutations still reject any diagnostic. render-error is warning-level despite its spelling; severity cannot be inferred from the suffix.

Retained detail ownership

Stats retain a sanitized copy before output/event delivery. Primitives are preserved, including values that are not JSON-compatible. Plain objects and arrays are recursively copied with bounded depth; functions become compact markers, DOM/Events become non-live descriptions, Errors become { name, message }, and other instances become type tags. Cross-realm/platform objects are not deliberately retained as live application graphs.

The depth bound also terminates ordinary cyclic data. There is no breadth, array-item, or byte cap, so very wide metadata can still produce a large retained copy. This is a retention contract, not a guarantee of JSON serialization or containment of every possible custom getter/proxy.

Core retains totals, code maps, and one last entry per severity rather than an unbounded diagnostic history. Pure validation entries and immediate sink/warning details use their own ownership contracts and are not covered by this retained-copy guarantee.

Debug builds

Neutral semantic entries select debug runtime behavior with the development export condition. Explicit debug paths provide deterministic debug selection:

@rightxt/tracker-core/debug
@rightxt/tracker-core/projection/debug
@rightxt/tracker-core/renderer/debug
@rightxt/tracker-core/advanced/debug

Each has static public-surface parity with its corresponding neutral entry. Successful trace lookup requires both a debug-capable integration and a compatible debug advanced accessor. Enabling debug only for the accessor does not retrofit a production integration; a production accessor returns null even for a debug integration.

Use compatible entries from the same resolved package instance. An original facade is the lookup identity; a spread copy, wrapper/proxy, foreign package copy, or unrelated object does not acquire trace access merely by resembling the public interface.

Advanced trace

The /advanced and /advanced/debug entries export:

getTrackerDebugTrace(integration: TrackerDebugIntegration): TrackerDebugTraceEntry[] | null;

TrackerDebugIntegration is the union of Core TrackerProjectionIntegration and TrackerRendererIntegration. TrackerDebugTraceEntry has readonly declared fields:

{
  type: string;
  timestamp: number | null;
  payload: Readonly<Record<string, unknown>>;
}

There is no sequence number, ID, or closed discriminated trace-label union. Lookup does not mutate integration state or emit diagnostics. Unsupported/production mismatches return null; a recognized debug facade before mount returns an empty array.

An explicit-entry composition example:

import { createTrackerProjectionIntegration } from '@rightxt/tracker-core/projection/debug';
import { getTrackerDebugTrace } from '@rightxt/tracker-core/advanced/debug';

const integration = createTrackerProjectionIntegration();
const initialTrace = getTrackerDebugTrace(integration); // []
integration.destroy();
const clearedTrace = getTrackerDebugTrace(integration); // []

Current execution boundaries

These nine labels describe current emitted boundaries; type remains an open-ended string:

Trace records selected execution boundaries, not every warning, error, activation, selection, validation result, or observer signal. Provisional initial boundaries can appear in trace even when mount later rolls back and successful public initial sync events are withheld. Payload fields are contextual metadata, not a closed per-label type schema.

Trace retention and timestamps

Trace uses FIFO retention with a current limit of 100 entries, observable through debug stats and not configurable. Payload retention uses sanitized copies. Every retrieval returns a detached copy with mutable runtime arrays/objects despite readonly declaration fields; it does not expose or freeze the retained store. Editing a returned copy cannot change later lookup results.

Array insertion order is authoritative. Entry timestamps use a performance-style active/fallback clock when available and may be null. Realm/clock changes across lifecycle transitions do not guarantee globally comparable or numerically monotonic timestamps. They are not wall-clock times.

Trace entry timestamps are independent of diagnostics.metrics. The nested render timing values in a sync:end payload remain subject to the render metrics gate.

Debug stats, reset, and destroy

TrackerDebugStats is a root type; debug stats expose debug.traceLength and debug.traceLimit. Production stats omit debug rather than materializing an empty branch.

Destroy can capture terminal debug stats after recording its destroy entry but before trace storage is cleared. Thus captured debug.traceLength may be nonzero while a subsequent trace lookup returns []. A later terminal stats refresh can observe length zero. Already retained snapshots/stats copies keep their captured values.

Related reference and examples

• Core API — validation, lifecycle capabilities, and event payload/order contracts.
• Core rendering — Projection publication and Direct Renderer callback ownership.
• Updates and refresh and environments — observation and geometry workflows.
• Diagnostics demo source — adapter-based warning/stat/metrics exploration, not an advanced trace API template.
• Vanilla events demo source — event-oriented workflow; Core handler ownership/failure semantics remain defined in the Core references.