Core API reference

This reference describes the public Core facades, configuration tooling, lifecycle settlement, and event contracts for custom integration authors. The Core README owns package orientation and option/rule fields. See custom integration for a workflow, rendering for protocols, and runtime state for snapshots, stats, diagnostics, and debug.

Package entry points

Neutral entries select debug behavior through the development export condition; production/default resolution selects production behavior. Explicit debug counterparts preserve the corresponding semantic entry's static public surface while selecting debug runtime behavior. Compatible integration/accessor composition is described under Debug builds.

@rightxt/tracker-core/style.css is the canonical stylesheet export; JavaScript does not inject it. @rightxt/tracker-core/package.json exposes package metadata. These are not JavaScript integration factories.

Public surface overview

The root entry contains helpers rather than an adapter class. Create a facade with createTrackerProjectionIntegration(configuration?) from /projection, or createTrackerRendererIntegration(configuration, { renderer }) from /renderer. Both start unmounted. A constructor-style TrackerConfiguration can omit options and rules; later TrackerConfigurationReplacement requires both channels.

Configuration and rule validation

The following functions and context/result types are exported from @rightxt/tracker-core:

validateOptions(options: unknown, context?: TrackerOptionsValidationContext): TrackerOptionsValidationResult;
validateRule(rule: unknown, context?: TrackerRuleValidationContext): TrackerRuleValidationResult;
validateRules(rules: unknown, context?: TrackerRuleValidationContext): TrackerRulesValidationResult;

They do not commit state, emit runtime events, call a diagnostics sink, or update stats. They return new mutable tooling arrays/objects; retained-runtime sanitation and freezing do not apply. TrackerValidationDiagnostic extends the diagnostic entry shape with type: 'warning' | 'error'. The separate warnings and errors arrays preserve order and share entry identities with their corresponding diagnostics entries.

TrackerNormalizedRule is independently importable from /renderer, not the root entry. Result fields referencing that type remain usable through inference from the root validators.

Context and recovery

TrackerOptionsValidationContext has optional previousOptions: Partial<TrackerOptions> and inputOptions: unknown. The former supplies recovery values, falling back to defaults when unusable. The latter supplies the raw input for unknown-key detection; an omitted/non-plain raw input contributes no unknown keys. Normalization and raw-input diagnostics are separate concerns: retain the original input when composing these helpers.

TrackerRuleValidationContext has optional selectorRoot: TrackerSourceRoot | null | undefined and hasSelector: (selector: string) => boolean. A real selector root enables DOM selector syntax validation. validateRule() uses hasSelector for duplicates; validateRules() supplies its own accumulating selector set. Before a source root exists, validation cannot necessarily prove environment-dependent selector syntax. Mount and mounted replacement revalidate against the actual source.

Invalid rule-marker CSS names produce diagnostics and are removed from recovered normalized rules; valid entries remain. This recovery does not imply permission to commit a diagnostic-bearing candidate. See rule validation behavior.

Strict mutation boundary

Normal configuration/rule operations reject any validation diagnostic, including warnings, with no partial candidate commit. The diagnostic-assertion path throws TrackerConfigurationError with ERR_TRACKER_INVALID_CONFIGURATION and the complete diagnostic array in native cause. Other configuration errors need not have that cause shape. Helper diagnostics are not automatically replayed as runtime warnings/errors during rejection.

An own known option/rule field set to undefined is invalid; omission is different. Replacement uses defaults for omitted options, while supported patches merge from committed options. A complete rules list preserves ordered first-match ownership. TrackerOperationParams supplies optional render?: boolean, defaulting to true. render: false preserves render-required work as dirty rather than scheduling it; it does not turn strict validation off. TrackerAddRuleParams adds optional insertion index; valid insertion indices run from zero through the current list length, while removal indices must identify an existing entry.

Configuration helpers

All helpers in this section are current public exports of @rightxt/tracker-core. They are usable independently of a mounted facade.

TrackerOptionsNormalizationContext exposes optional baseOptions and currentOptions, both partial option values. TrackerRuleNormalizationContext exposes optional index. TrackerOptionsCandidate is a partial options intermediate, not a guarantee of complete or validated state. TrackerRuleSource is a detached public-rule round-trip representation with trimmed selector; callback/platform identities are preserved.

Option diff domains

TrackerOptionsDiff has nine boolean fields:

These flags describe differences; invoking the helper does not schedule any work.

Support shapes and importability

Some support shapes appear in callable declarations without an independent entry export. Do not invent deep package imports for them. normalizeRule()'s candidate return shape is inferred; its support name TrackerNormalizedRuleCandidate is not a root-entry export. Likewise resolveTrackerOptions() references TrackerOptionsResolutionContext and TrackerResolvedOptions without exporting those names there. Its context structurally supplies optional previousOptions (a complete resolved value, for example inferred from a prior resolution) and replace?: boolean.

Use inferred return types or structural descriptions where needed. Publicly exported context/candidate/diff types above are ordinary supported public types; normalization still does not confer validation.

Projection integration API

Factory and facade types are imported from @rightxt/tracker-core/projection. createTrackerProjectionIntegration(configuration = {}) returns TrackerProjectionIntegration. The following is its complete 22-method inventory; specialized semantics are expanded in Projection protocol.

Projection exposes no options/rules/root getters, incremental rules methods, or public activateItem().

Direct Renderer integration API

Import createTrackerRendererIntegration, TrackerRendererIntegration, and TrackerRendererIntegrationOptions from @rightxt/tracker-core/renderer. The factory accepts (configuration, integrationOptions); configuration may be undefined, but integrationOptions.renderer is required. Missing renderer rejects construction. See renderer protocol.

These are all 26 methods. There is no Projection getter/subscription, flushRender(), or facade preflight/adapter-coordinator counterpart. TrackerActivateItemOptions is a renderer-entry type with optional sourceEvent; invalid/unknown keys warn and return false, and disabled/unavailable activation does not become a successful action.

Lifecycle capability matrix

Mount and cleanup settlement

Creation starts unmounted. Mount commits only after required provisional setup and initial synchronization succeed. Failed request normalization reports its diagnostic and leaves unmounted state; failure after acquisition triggers rollback, publishes stable unmounted state, and propagates the failure, possibly aggregated with cleanup errors. No successful initial sync pair escapes a failed mount.

Unmount is reversible and effectively idempotent at the public lifecycle level. Configuration/rules persist, while active roots, observer/listener/timer resources, and pending generation work do not. Cleanup failure can propagate after state has already become unmounted. A renderer-owned root left connected can prevent safe remount; see root cleanup.

Destroy is terminal even when cleanup throws. State commits destroyed, terminal notifications/publication are attempted, subscriptions are cleared, and retained failures are then rethrown. A sole failure can be rethrown directly; multiple failures can be an AggregateError. Repeating destroy is a no-op, not a retry of failed cleanup. whenDestroyed() resolves even when cleanup failure is propagated.

Events

Root exports EVENT_NAMES, EVENT_NAME_VALUES, and event types. TrackerEventName contains exactly the eight names below; TrackerEventNameConstants types the named constant map, TrackerEventPayloadMap maps names to payload types, and TrackerEventPayload is their union. TrackerTypedEventHandler<TName> narrows by name; TrackerEventHandler accepts the payload union. TrackerEventUnsubscribe is a no-argument cleanup function.

All notifications are synchronous and non-canceling. There are no generic public mount, unmount, configuration, render, or error events.

TrackerEventMarker is the marker's key, borrowed element, owning ruleIndex/selector, and nullable label; the marker-activation payload adds sourceEvent. Cluster envelopes, marker DTOs, arrays, and reason trees are Tracker-owned and frozen. Borrowed Elements and native Events are not frozen. Warning details is a deliberate live borrowed graph rather than a frozen/cloned nested DTO; retained diagnostic details have different ownership.

sync:start.reason is structurally { source?: string; scheduled?: boolean; reasons?: readonly ...[] } | null | undefined. Its support names TrackerRenderReason and TrackerRenderReasonSource are not root-entry imports. Reasons include observation and manual sources and can combine several origins. scheduled: true can accompany synchronous render() because it immediately flushes scheduler-owned work. Timing fields are null without enabled/available metrics. See scheduling reasons.

Activation and selection ordering

Marker/cluster scroll and focus are attempted before their event. Return values, thrown handlers, and late preventDefault() do not cancel those actions. interaction.activation: false suppresses marker, cluster, discrete track, and selected-item keyboard activation. Drag is separately controlled and does not emit track:activate for its movement.

Ordinary successful synchronization orders sync:start, rendering/Projection commit, completed stats, sync:end, an optional real selection transition, then snapshot publication. Initial mount commits lifecycle and Projection first, then releases the staged initial sync pair and snapshot batch. A failed render has no sync:end.

A standalone logical selection transition can emit without sync events. Failure to render its selection does not erase the committed logical transition. Selected key is therefore not proof that every backend painted selection successfully. See rule behavior.

Event subscription and ordering

on(eventName, handler) requires an alive facade, known event name, and function handler. Destroyed subscription throws ERR_TRACKER_DESTROYED; invalid names/handlers throw TypeError. off() returns false after destroy; otherwise invalid names/handlers throw, absent valid pairs return false, and removal returns true.

Duplicate handler identity is delivered once per emission but has reference-counted registration owners. Each returned unsubscribe releases only its own owner and is idempotent. The last owner removes delivery. off() removes all current owners for the pair; an old unsubscribe cannot affect a new registration created after removal.

Core facade handlers are integration-owned bridges. Return values are ignored; synchronous throws are contained, returned thenables are not awaited, and later rejections are observed. Both failures produce integration-event-handler-error without rolling back the emitting operation. Do not transfer this contract to adapter-native callbacks, outputs, emits, or CustomEvents.

Valid state-changing operations requested during public event/snapshot dispatch queue until dispatch exits. Many arguments are validated and captured before queuing, so invalid calls can still throw synchronously within a handler. Later deferred-operation failure is diagnosed rather than retroactively changing the already-returned call. Active renderer/lifecycle callbacks have different reentrancy rules.

Snapshot and stats entry points

Both facades expose getSnapshot(), subscribeSnapshot(), getStats(), and resetStats(). Snapshots are immutable DOM-free observation data; standalone stats are detached mutable clones. Projection subscriptions are a separate integration protocol. Full shapes, publication/identity rules, listener failure boundaries, metrics, reset, and terminal retention belong to Core runtime.

Low-level public helpers and types

The following grouped root-entry types describe configuration rather than introducing another option schema. Their field authority remains in the Core README; workflow references explain composition and runtime effects.

Configuration normalization/validation types are documented with their helpers above. Event types are documented with payloads. Root snapshot/stat/diagnostic/error/debug types have their semantic home in Core runtime. Renderer-specific attribute, record, context, constant, and normalized-rule types are imported from /renderer and described in renderer DTOs. Projection types belong to /projection, and advanced trace types to /advanced; none requires an invented deep import.

Error classes and codes

Root exports TrackerError, TrackerConfigurationError, and TrackerLifecycleError as runtime classes and TypeScript types, with TrackerErrorOptions and TrackerErrorCode. Native TypeError, original thrown values, and AggregateError can also cross public operation boundaries. Branch on a known Tracker error's stable code rather than human message text. The nine error codes and separate diagnostic-code catalog are in the runtime reference.

Related reference

• Rendering protocols: root ownership, DTOs, hooks, coordination, and cleanup.
• Runtime state and diagnostics: snapshots, stats, error channels, debug trace.
• Custom integration guide: applying the facades in a complete workflow.
• Environments, updates, rules, and styling: shared behavioral depth without replacing package APIs.