@lagless/desync-diagnostics 0.0.48

package/LICENSE

@@ -0,0 +1,26 @@
+Creative Commons Attribution-NonCommercial 4.0 International
+
+Copyright (c) 2025 Lagless
+
+This work is licensed under the Creative Commons
+Attribution-NonCommercial 4.0 International License.
+
+You are free to:
+
+  Share — copy and redistribute the material in any medium or format
+  Adapt — remix, transform, and build upon the material
+
+Under the following terms:
+
+  Attribution — You must give appropriate credit, provide a link to
+  the license, and indicate if changes were made. You may do so in
+  any reasonable manner, but not in any way that suggests the licensor
+  endorses you or your use.
+
+  NonCommercial — You may not use the material for commercial purposes.
+
+  No additional restrictions — You may not apply legal terms or
+  technological measures that legally restrict others from doing
+  anything the license permits.
+
+Full license text: https://creativecommons.org/licenses/by-nc/4.0/legalcode

package/out-tsc/index.d.ts

@@ -0,0 +1,13 @@
+export { DiagnosticsCollector } from './lib/diagnostics-collector.js';
+export { hashBytes } from './lib/hash-bytes.js';
+export { analyzeDivergence } from './lib/divergence-analysis.js';
+export type { DivergenceAnalysis, CheckpointComparison, RollbackOverlapWindow } from './lib/divergence-analysis.js';
+export { attachDesyncDiagnostics } from './lib/attach.js';
+export { generateReport } from './lib/report-generator.js';
+export type { DiagnosticsConfig, TickRecord, RollbackEvent, DiagnosticsStats } from './lib/types.js';
+export type { DiagnosticsReport, CombinedDiagnosticsReport, DiagnosticsReportConfig, DiagnosticsReportSummary, DiagnosticsReportTickRecord, DiagnosticsReportRPC, } from './lib/report-generator.js';
+export { useDesyncDiagnostics, type UseDesyncDiagnosticsOptions } from './lib/use-desync-diagnostics.js';
+export { PerformanceProfiler } from './lib/performance-profiler.js';
+export type { PerformanceStats, SystemTimingStats, TimingStats } from './lib/performance-profiler.js';
+export type { DiagnosticsSummaryMessage, DiagnosticsReportMessage, PerformanceStatsMessage, DiagnosticsChildMessage, RequestDiagnosticsReportMessage, DiagnosticsParentMessage, } from './lib/diagnostics-protocol.js';
+//# sourceMappingURL=index.d.ts.map

package/out-tsc/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,oBAAoB,EAAE,MAAM,gCAAgC,CAAC;AACtE,OAAO,EAAE,SAAS,EAAE,MAAM,qBAAqB,CAAC;AAChD,OAAO,EAAE,iBAAiB,EAAE,MAAM,8BAA8B,CAAC;AACjE,YAAY,EAAE,kBAAkB,EAAE,oBAAoB,EAAE,qBAAqB,EAAE,MAAM,8BAA8B,CAAC;AACpH,OAAO,EAAE,uBAAuB,EAAE,MAAM,iBAAiB,CAAC;AAC1D,OAAO,EAAE,cAAc,EAAE,MAAM,2BAA2B,CAAC;AAC3D,YAAY,EAAE,iBAAiB,EAAE,UAAU,EAAE,aAAa,EAAE,gBAAgB,EAAE,MAAM,gBAAgB,CAAC;AACrG,YAAY,EACV,iBAAiB,EACjB,yBAAyB,EACzB,uBAAuB,EACvB,wBAAwB,EACxB,2BAA2B,EAC3B,oBAAoB,GACrB,MAAM,2BAA2B,CAAC;AACnC,OAAO,EAAE,oBAAoB,EAAE,KAAK,2BAA2B,EAAE,MAAM,iCAAiC,CAAC;AACzG,OAAO,EAAE,mBAAmB,EAAE,MAAM,+BAA+B,CAAC;AACpE,YAAY,EAAE,gBAAgB,EAAE,iBAAiB,EAAE,WAAW,EAAE,MAAM,+BAA+B,CAAC;AACtG,YAAY,EACV,yBAAyB,EACzB,wBAAwB,EACxB,uBAAuB,EACvB,uBAAuB,EACvB,+BAA+B,EAC/B,wBAAwB,GACzB,MAAM,+BAA+B,CAAC"}

package/out-tsc/lib/attach.d.ts

@@ -0,0 +1,5 @@
+import type { ECSRunner } from '@lagless/core';
+import { DiagnosticsCollector } from './diagnostics-collector.js';
+import type { DiagnosticsConfig } from './types.js';
+export declare function attachDesyncDiagnostics(runner: ECSRunner, config?: DiagnosticsConfig): DiagnosticsCollector;
+//# sourceMappingURL=attach.d.ts.map

package/out-tsc/lib/attach.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"attach.d.ts","sourceRoot":"","sources":["../../src/lib/attach.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,eAAe,CAAC;AAC/C,OAAO,EAAE,oBAAoB,EAAE,MAAM,4BAA4B,CAAC;AAClE,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAC;AAEpD,wBAAgB,uBAAuB,CACrC,MAAM,EAAE,SAAS,EACjB,MAAM,CAAC,EAAE,iBAAiB,GACzB,oBAAoB,CAEtB"}

package/out-tsc/lib/diagnostics-collector.d.ts

@@ -0,0 +1,41 @@
+import type { ECSRunner } from '@lagless/core';
+import type { DiagnosticsConfig, TickRecord, RollbackEvent, DiagnosticsStats } from './types.js';
+export declare class DiagnosticsCollector {
+    private readonly _runner;
+    private readonly _maxPlayers;
+    private readonly _bufferSize;
+    private readonly _ticks;
+    private readonly _hashes;
+    private readonly _physicsHashes;
+    private readonly _velocityHashes;
+    private readonly _verifiedTicks;
+    private readonly _wasRollback;
+    private readonly _inputCounts;
+    private readonly _physicsHashFn;
+    private readonly _velocityHashFn;
+    private _head;
+    private _count;
+    private readonly _maxRollbackEvents;
+    private readonly _rollbackEvents;
+    private _totalRollbacks;
+    private _lastRollbackTick;
+    private _isResimulating;
+    private _preRollbackTick;
+    private _lastTickSeen;
+    private _prevVerifiedTick;
+    private _verifiedTickGapCount;
+    private _removeTickHandler;
+    private _removeRollbackHandler;
+    private _disposed;
+    constructor(runner: ECSRunner, config?: DiagnosticsConfig);
+    get runner(): ECSRunner;
+    get bufferSize(): number;
+    get count(): number;
+    getTimeline(): TickRecord[];
+    getRollbacks(): ReadonlyArray<RollbackEvent>;
+    getStats(): DiagnosticsStats;
+    dispose(): void;
+    private _onRollback;
+    private _onTick;
+}
+//# sourceMappingURL=diagnostics-collector.d.ts.map

package/out-tsc/lib/diagnostics-collector.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"diagnostics-collector.d.ts","sourceRoot":"","sources":["../../src/lib/diagnostics-collector.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,eAAe,CAAC;AAC/C,OAAO,KAAK,EAAE,iBAAiB,EAAE,UAAU,EAAE,aAAa,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC;AAKjG,qBAAa,oBAAoB;IAC/B,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAY;IACpC,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAS;IACrC,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAS;IAGrC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAc;IACrC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAc;IACtC,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAc;IAC7C,OAAO,CAAC,QAAQ,CAAC,eAAe,CAAc;IAC9C,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAa;IAC5C,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAa;IAC1C,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAa;IAE1C,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAwB;IACvD,OAAO,CAAC,QAAQ,CAAC,eAAe,CAAwB;IAExD,OAAO,CAAC,KAAK,CAAK;IAClB,OAAO,CAAC,MAAM,CAAK;IAGnB,OAAO,CAAC,QAAQ,CAAC,kBAAkB,CAAS;IAC5C,OAAO,CAAC,QAAQ,CAAC,eAAe,CAAuB;IACvD,OAAO,CAAC,eAAe,CAAK;IAC5B,OAAO,CAAC,iBAAiB,CAAK;IAG9B,OAAO,CAAC,eAAe,CAAS;IAChC,OAAO,CAAC,gBAAgB,CAAK;IAC7B,OAAO,CAAC,aAAa,CAAK;IAG1B,OAAO,CAAC,iBAAiB,CAAM;IAC/B,OAAO,CAAC,qBAAqB,CAAK;IAGlC,OAAO,CAAC,kBAAkB,CAA6B;IACvD,OAAO,CAAC,sBAAsB,CAA6B;IAC3D,OAAO,CAAC,SAAS,CAAS;gBAEd,MAAM,EAAE,SAAS,EAAE,MAAM,CAAC,EAAE,iBAAiB;IA4BzD,IAAW,MAAM,IAAI,SAAS,CAE7B;IAED,IAAW,UAAU,IAAI,MAAM,CAE9B;IAED,IAAW,KAAK,IAAI,MAAM,CAEzB;IAEM,WAAW,IAAI,UAAU,EAAE;IAqB3B,YAAY,IAAI,aAAa,CAAC,aAAa,CAAC;IAI5C,QAAQ,IAAI,gBAAgB;IAiB5B,OAAO,IAAI,IAAI;IAWtB,OAAO,CAAC,WAAW;IAoBnB,OAAO,CAAC,OAAO;CAkDhB"}

package/out-tsc/lib/diagnostics-protocol.d.ts

@@ -0,0 +1,52 @@
+import type { DiagnosticsReport } from './report-generator.js';
+export interface DiagnosticsSummaryMessage {
+    type: 'dev-bridge:diagnostics-summary';
+    instanceId: string;
+    rollbackCount: number;
+    lastRollbackTick: number;
+    verifiedTickGapCount: number;
+    ticksRecorded: number;
+    latestHash: number;
+    latestPhysicsHash: number;
+    latestVelocityHash: number;
+}
+export interface DiagnosticsReportMessage {
+    type: 'dev-bridge:diagnostics-report';
+    instanceId: string;
+    report: DiagnosticsReport;
+}
+export interface PerformanceStatsMessage {
+    type: 'dev-bridge:performance-stats';
+    instanceId: string;
+    tickTime: {
+        latest: number;
+        min: number;
+        max: number;
+        avg: number;
+    };
+    snapshotTime: {
+        latest: number;
+        min: number;
+        max: number;
+        avg: number;
+    };
+    overheadTime: {
+        latest: number;
+        min: number;
+        max: number;
+        avg: number;
+    };
+    systems: Array<{
+        name: string;
+        latest: number;
+        min: number;
+        max: number;
+        avg: number;
+    }>;
+}
+export type DiagnosticsChildMessage = DiagnosticsSummaryMessage | DiagnosticsReportMessage | PerformanceStatsMessage;
+export interface RequestDiagnosticsReportMessage {
+    type: 'dev-bridge:request-diagnostics-report';
+}
+export type DiagnosticsParentMessage = RequestDiagnosticsReportMessage;
+//# sourceMappingURL=diagnostics-protocol.d.ts.map

package/out-tsc/lib/diagnostics-protocol.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"diagnostics-protocol.d.ts","sourceRoot":"","sources":["../../src/lib/diagnostics-protocol.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,uBAAuB,CAAC;AAI/D,MAAM,WAAW,yBAAyB;IACxC,IAAI,EAAE,gCAAgC,CAAC;IACvC,UAAU,EAAE,MAAM,CAAC;IACnB,aAAa,EAAE,MAAM,CAAC;IACtB,gBAAgB,EAAE,MAAM,CAAC;IACzB,oBAAoB,EAAE,MAAM,CAAC;IAC7B,aAAa,EAAE,MAAM,CAAC;IACtB,UAAU,EAAE,MAAM,CAAC;IACnB,iBAAiB,EAAE,MAAM,CAAC;IAC1B,kBAAkB,EAAE,MAAM,CAAC;CAC5B;AAED,MAAM,WAAW,wBAAwB;IACvC,IAAI,EAAE,+BAA+B,CAAC;IACtC,UAAU,EAAE,MAAM,CAAC;IACnB,MAAM,EAAE,iBAAiB,CAAC;CAC3B;AAED,MAAM,WAAW,uBAAuB;IACtC,IAAI,EAAE,8BAA8B,CAAC;IACrC,UAAU,EAAE,MAAM,CAAC;IACnB,QAAQ,EAAE;QAAE,MAAM,EAAE,MAAM,CAAC;QAAC,GAAG,EAAE,MAAM,CAAC;QAAC,GAAG,EAAE,MAAM,CAAC;QAAC,GAAG,EAAE,MAAM,CAAA;KAAE,CAAC;IACpE,YAAY,EAAE;QAAE,MAAM,EAAE,MAAM,CAAC;QAAC,GAAG,EAAE,MAAM,CAAC;QAAC,GAAG,EAAE,MAAM,CAAC;QAAC,GAAG,EAAE,MAAM,CAAA;KAAE,CAAC;IACxE,YAAY,EAAE;QAAE,MAAM,EAAE,MAAM,CAAC;QAAC,GAAG,EAAE,MAAM,CAAC;QAAC,GAAG,EAAE,MAAM,CAAC;QAAC,GAAG,EAAE,MAAM,CAAA;KAAE,CAAC;IACxE,OAAO,EAAE,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAC;QAAC,GAAG,EAAE,MAAM,CAAC;QAAC,GAAG,EAAE,MAAM,CAAC;QAAC,GAAG,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;CACzF;AAED,MAAM,MAAM,uBAAuB,GAC/B,yBAAyB,GACzB,wBAAwB,GACxB,uBAAuB,CAAC;AAI5B,MAAM,WAAW,+BAA+B;IAC9C,IAAI,EAAE,uCAAuC,CAAC;CAC/C;AAED,MAAM,MAAM,wBAAwB,GAChC,+BAA+B,CAAC"}

package/out-tsc/lib/divergence-analysis.d.ts

@@ -0,0 +1,21 @@
+import type { DiagnosticsReport } from './report-generator.js';
+export interface CheckpointComparison {
+    tick: number;
+    ecsHashes: Record<number, number>;
+    physicsHashes: Record<number, number>;
+    ecsMatch: boolean;
+    physicsMatch: boolean;
+}
+export interface RollbackOverlapWindow {
+    startTick: number;
+    endTick: number;
+    affectedSlots: number[];
+}
+export interface DivergenceAnalysis {
+    firstEcsDivergenceTick: number | null;
+    firstPhysicsDivergenceTick: number | null;
+    checkpointComparison: CheckpointComparison[];
+    rollbackOverlapWindows: RollbackOverlapWindow[];
+}
+export declare function analyzeDivergence(clients: DiagnosticsReport[], checkpointInterval?: number): DivergenceAnalysis;
+//# sourceMappingURL=divergence-analysis.d.ts.map

package/out-tsc/lib/divergence-analysis.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"divergence-analysis.d.ts","sourceRoot":"","sources":["../../src/lib/divergence-analysis.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,uBAAuB,CAAC;AAE/D,MAAM,WAAW,oBAAoB;IACnC,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAClC,aAAa,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACtC,QAAQ,EAAE,OAAO,CAAC;IAClB,YAAY,EAAE,OAAO,CAAC;CACvB;AAED,MAAM,WAAW,qBAAqB;IACpC,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,EAAE,MAAM,CAAC;IAChB,aAAa,EAAE,MAAM,EAAE,CAAC;CACzB;AAED,MAAM,WAAW,kBAAkB;IACjC,sBAAsB,EAAE,MAAM,GAAG,IAAI,CAAC;IACtC,0BAA0B,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1C,oBAAoB,EAAE,oBAAoB,EAAE,CAAC;IAC7C,sBAAsB,EAAE,qBAAqB,EAAE,CAAC;CACjD;AAsBD,wBAAgB,iBAAiB,CAC/B,OAAO,EAAE,iBAAiB,EAAE,EAC5B,kBAAkB,SAA8B,GAC/C,kBAAkB,CA8EpB"}

package/out-tsc/lib/hash-bytes.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Polynomial hash (same algorithm as Mem.getHash) but using direct Uint8Array indexing
+ * instead of DataView for better performance on large buffers (e.g. Rapier snapshots).
+ */
+export declare function hashBytes(data: Uint8Array): number;
+//# sourceMappingURL=hash-bytes.d.ts.map

package/out-tsc/lib/hash-bytes.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"hash-bytes.d.ts","sourceRoot":"","sources":["../../src/lib/hash-bytes.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,wBAAgB,SAAS,CAAC,IAAI,EAAE,UAAU,GAAG,MAAM,CAMlD"}

package/out-tsc/lib/performance-profiler.d.ts

@@ -0,0 +1,43 @@
+import type { ECSRunner } from '@lagless/core';
+export interface TimingStats {
+    latest: number;
+    min: number;
+    max: number;
+    avg: number;
+}
+export interface SystemTimingStats extends TimingStats {
+    name: string;
+}
+export interface PerformanceStats {
+    tickTime: TimingStats;
+    snapshotTime: TimingStats;
+    overheadTime: TimingStats;
+    systems: SystemTimingStats[];
+}
+export declare class PerformanceProfiler {
+    private readonly _windowSize;
+    private _entries;
+    private _attached;
+    private _tickTimeBuffer;
+    private _tickTimeWriteIndex;
+    private _tickTimeCount;
+    private _tickStartTime;
+    private _snapshotTimeBuffer;
+    private _snapshotTimeWriteIndex;
+    private _snapshotTimeCount;
+    private _overheadTimeBuffer;
+    private _overheadTimeWriteIndex;
+    private _overheadTimeCount;
+    private _lastSimulateElapsed;
+    private _lastSnapshotElapsed;
+    private _originalSimulate;
+    private _originalSaveSnapshot;
+    private _removeTickHandler;
+    private _simulation;
+    constructor(windowSize?: number);
+    attach(runner: ECSRunner): void;
+    detach(): void;
+    getStats(): PerformanceStats;
+    dispose(): void;
+}
+//# sourceMappingURL=performance-profiler.d.ts.map

package/out-tsc/lib/performance-profiler.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"performance-profiler.d.ts","sourceRoot":"","sources":["../../src/lib/performance-profiler.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAA6B,MAAM,eAAe,CAAC;AAE1E,MAAM,WAAW,WAAW;IAC1B,MAAM,EAAE,MAAM,CAAC;IACf,GAAG,EAAE,MAAM,CAAC;IACZ,GAAG,EAAE,MAAM,CAAC;IACZ,GAAG,EAAE,MAAM,CAAC;CACb;AAED,MAAM,WAAW,iBAAkB,SAAQ,WAAW;IACpD,IAAI,EAAE,MAAM,CAAC;CACd;AAED,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,EAAE,WAAW,CAAC;IACtB,YAAY,EAAE,WAAW,CAAC;IAC1B,YAAY,EAAE,WAAW,CAAC;IAC1B,OAAO,EAAE,iBAAiB,EAAE,CAAC;CAC9B;AAyCD,qBAAa,mBAAmB;IAC9B,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAS;IACrC,OAAO,CAAC,QAAQ,CAAqB;IACrC,OAAO,CAAC,SAAS,CAAS;IAG1B,OAAO,CAAC,eAAe,CAAgB;IACvC,OAAO,CAAC,mBAAmB,CAAK;IAChC,OAAO,CAAC,cAAc,CAAK;IAC3B,OAAO,CAAC,cAAc,CAAK;IAG3B,OAAO,CAAC,mBAAmB,CAAgB;IAC3C,OAAO,CAAC,uBAAuB,CAAK;IACpC,OAAO,CAAC,kBAAkB,CAAK;IAG/B,OAAO,CAAC,mBAAmB,CAAgB;IAC3C,OAAO,CAAC,uBAAuB,CAAK;IACpC,OAAO,CAAC,kBAAkB,CAAK;IAG/B,OAAO,CAAC,oBAAoB,CAAM;IAClC,OAAO,CAAC,oBAAoB,CAAK;IAGjC,OAAO,CAAC,iBAAiB,CAAyC;IAClE,OAAO,CAAC,qBAAqB,CAAyC;IACtE,OAAO,CAAC,kBAAkB,CAA6B;IACvD,OAAO,CAAC,WAAW,CAA8B;gBAErC,UAAU,SAAsB;IAIrC,MAAM,CAAC,MAAM,EAAE,SAAS,GAAG,IAAI;IAwF/B,MAAM,IAAI,IAAI;IAsCd,QAAQ,IAAI,gBAAgB;IAqB5B,OAAO,IAAI,IAAI;CAGvB"}

package/out-tsc/lib/report-generator.d.ts

@@ -0,0 +1,55 @@
+import type { DiagnosticsCollector } from './diagnostics-collector.js';
+export interface DiagnosticsReportConfig {
+    fps: number;
+    maxPlayers: number;
+    frameLength: number;
+    snapshotRate: number;
+    maxEntities: number;
+}
+export interface DiagnosticsReportSummary {
+    totalTicks: number;
+    totalRollbacks: number;
+    firstDivergenceTick: number | null;
+    verifiedTickGapCount: number;
+    latestPhysicsHash: number;
+    oldestTick: number;
+    newestTick: number;
+}
+export interface DiagnosticsReportTickRecord {
+    tick: number;
+    hash: number;
+    physicsHash: number;
+    velocityHash: number;
+    verifiedTick: number;
+    wasRollback: boolean;
+    inputCountBySlot: number[];
+}
+export interface DiagnosticsReportRPC {
+    inputId: number;
+    seq: number;
+    playerSlot: number;
+    ordinal: number;
+    data: unknown;
+}
+export interface DiagnosticsReport {
+    version: number;
+    generatedAt: string;
+    playerSlot: number;
+    config: DiagnosticsReportConfig;
+    summary: DiagnosticsReportSummary;
+    timeline: DiagnosticsReportTickRecord[];
+    rollbacks: Array<{
+        atSimTick: number;
+        rollbackToTick: number;
+        timestamp: number;
+    }>;
+    inputHistory: Record<string, DiagnosticsReportRPC[]>;
+}
+export interface CombinedDiagnosticsReport {
+    version: number;
+    generatedAt: string;
+    clients: DiagnosticsReport[];
+    divergenceAnalysis?: import('./divergence-analysis.js').DivergenceAnalysis;
+}
+export declare function generateReport(collector: DiagnosticsCollector): DiagnosticsReport;
+//# sourceMappingURL=report-generator.d.ts.map

package/out-tsc/lib/report-generator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"report-generator.d.ts","sourceRoot":"","sources":["../../src/lib/report-generator.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,4BAA4B,CAAC;AAIvE,MAAM,WAAW,uBAAuB;IACtC,GAAG,EAAE,MAAM,CAAC;IACZ,UAAU,EAAE,MAAM,CAAC;IACnB,WAAW,EAAE,MAAM,CAAC;IACpB,YAAY,EAAE,MAAM,CAAC;IACrB,WAAW,EAAE,MAAM,CAAC;CACrB;AAED,MAAM,WAAW,wBAAwB;IACvC,UAAU,EAAE,MAAM,CAAC;IACnB,cAAc,EAAE,MAAM,CAAC;IACvB,mBAAmB,EAAE,MAAM,GAAG,IAAI,CAAC;IACnC,oBAAoB,EAAE,MAAM,CAAC;IAC7B,iBAAiB,EAAE,MAAM,CAAC;IAC1B,UAAU,EAAE,MAAM,CAAC;IACnB,UAAU,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,2BAA2B;IAC1C,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,YAAY,EAAE,MAAM,CAAC;IACrB,YAAY,EAAE,MAAM,CAAC;IACrB,WAAW,EAAE,OAAO,CAAC;IACrB,gBAAgB,EAAE,MAAM,EAAE,CAAC;CAC5B;AAED,MAAM,WAAW,oBAAoB;IACnC,OAAO,EAAE,MAAM,CAAC;IAChB,GAAG,EAAE,MAAM,CAAC;IACZ,UAAU,EAAE,MAAM,CAAC;IACnB,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,OAAO,CAAC;CACf;AAED,MAAM,WAAW,iBAAiB;IAChC,OAAO,EAAE,MAAM,CAAC;IAChB,WAAW,EAAE,MAAM,CAAC;IACpB,UAAU,EAAE,MAAM,CAAC;IACnB,MAAM,EAAE,uBAAuB,CAAC;IAChC,OAAO,EAAE,wBAAwB,CAAC;IAClC,QAAQ,EAAE,2BAA2B,EAAE,CAAC;IACxC,SAAS,EAAE,KAAK,CAAC;QAAE,SAAS,EAAE,MAAM,CAAC;QAAC,cAAc,EAAE,MAAM,CAAC;QAAC,SAAS,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IACnF,YAAY,EAAE,MAAM,CAAC,MAAM,EAAE,oBAAoB,EAAE,CAAC,CAAC;CACtD;AAED,MAAM,WAAW,yBAAyB;IACxC,OAAO,EAAE,MAAM,CAAC;IAChB,WAAW,EAAE,MAAM,CAAC;IACpB,OAAO,EAAE,iBAAiB,EAAE,CAAC;IAC7B,kBAAkB,CAAC,EAAE,OAAO,0BAA0B,EAAE,kBAAkB,CAAC;CAC5E;AAED,wBAAgB,cAAc,CAAC,SAAS,EAAE,oBAAoB,GAAG,iBAAiB,CA0DjF"}

package/out-tsc/lib/types.d.ts

@@ -0,0 +1,39 @@
+export interface DiagnosticsConfig {
+    /** Number of ticks to keep in the ring buffer. Default: 18000 (5 min at 60fps). */
+    bufferSize?: number;
+    /** Max rollback events to keep. Default: 1000. */
+    maxRollbackEvents?: number;
+    /** Optional callback that returns a hash of physics state (e.g. Rapier snapshot). Called every tick. */
+    physicsHashFn?: () => number;
+    /** Optional callback that returns a hash of velocity state (e.g. all body velocities). Called every tick. */
+    velocityHashFn?: () => number;
+}
+export interface TickRecord {
+    tick: number;
+    hash: number;
+    physicsHash: number;
+    velocityHash: number;
+    verifiedTick: number;
+    wasRollback: boolean;
+    inputCountBySlot: Uint8Array;
+}
+export interface RollbackEvent {
+    /** Simulation tick when rollback was triggered. */
+    atSimTick: number;
+    /** Tick we rolled back to. */
+    rollbackToTick: number;
+    /** Performance.now() timestamp. */
+    timestamp: number;
+}
+export interface DiagnosticsStats {
+    ticksRecorded: number;
+    totalRollbacks: number;
+    lastRollbackTick: number;
+    verifiedTickGapCount: number;
+    latestHash: number;
+    latestPhysicsHash: number;
+    latestVelocityHash: number;
+    oldestTick: number;
+    newestTick: number;
+}
+//# sourceMappingURL=types.d.ts.map

package/out-tsc/lib/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/lib/types.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,iBAAiB;IAChC,mFAAmF;IACnF,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,kDAAkD;IAClD,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,wGAAwG;IACxG,aAAa,CAAC,EAAE,MAAM,MAAM,CAAC;IAC7B,6GAA6G;IAC7G,cAAc,CAAC,EAAE,MAAM,MAAM,CAAC;CAC/B;AAED,MAAM,WAAW,UAAU;IACzB,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,YAAY,EAAE,MAAM,CAAC;IACrB,YAAY,EAAE,MAAM,CAAC;IACrB,WAAW,EAAE,OAAO,CAAC;IACrB,gBAAgB,EAAE,UAAU,CAAC;CAC9B;AAED,MAAM,WAAW,aAAa;IAC5B,mDAAmD;IACnD,SAAS,EAAE,MAAM,CAAC;IAClB,8BAA8B;IAC9B,cAAc,EAAE,MAAM,CAAC;IACvB,mCAAmC;IACnC,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,gBAAgB;IAC/B,aAAa,EAAE,MAAM,CAAC;IACtB,cAAc,EAAE,MAAM,CAAC;IACvB,gBAAgB,EAAE,MAAM,CAAC;IACzB,oBAAoB,EAAE,MAAM,CAAC;IAC7B,UAAU,EAAE,MAAM,CAAC;IACnB,iBAAiB,EAAE,MAAM,CAAC;IAC1B,kBAAkB,EAAE,MAAM,CAAC;IAC3B,UAAU,EAAE,MAAM,CAAC;IACnB,UAAU,EAAE,MAAM,CAAC;CACpB"}

package/out-tsc/lib/use-desync-diagnostics.d.ts

@@ -0,0 +1,9 @@
+import type { ECSRunner } from '@lagless/core';
+export interface UseDesyncDiagnosticsOptions {
+    physicsHashFn?: () => number;
+    velocityHashFn?: () => number;
+    /** When false, don't create collector or stream diagnostics. Defaults to true. */
+    enabled?: boolean;
+}
+export declare function useDesyncDiagnostics(runner: ECSRunner | null, options?: UseDesyncDiagnosticsOptions): void;
+//# sourceMappingURL=use-desync-diagnostics.d.ts.map

package/out-tsc/lib/use-desync-diagnostics.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"use-desync-diagnostics.d.ts","sourceRoot":"","sources":["../../src/lib/use-desync-diagnostics.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,eAAe,CAAC;AAU/C,MAAM,WAAW,2BAA2B;IAC1C,aAAa,CAAC,EAAE,MAAM,MAAM,CAAC;IAC7B,cAAc,CAAC,EAAE,MAAM,MAAM,CAAC;IAC9B,kFAAkF;IAClF,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB;AAED,wBAAgB,oBAAoB,CAClC,MAAM,EAAE,SAAS,GAAG,IAAI,EACxB,OAAO,CAAC,EAAE,2BAA2B,GACpC,IAAI,CA+EN"}

package/package.json

@@ -0,0 +1,38 @@
+{
+  "name": "@lagless/desync-diagnostics",
+  "version": "0.0.48",
+  "license": "CC-BY-NC-4.0",
+  "type": "module",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/GbGr/lagless.git",
+    "directory": "libs/desync-diagnostics"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "main": "./src/index.ts",
+  "types": "./src/index.ts",
+  "exports": {
+    "./package.json": "./package.json",
+    ".": {
+      "@lagless/source": "./src/index.ts",
+      "types": "./src/index.ts",
+      "import": "./src/index.ts",
+      "default": "./src/index.ts"
+    }
+  },
+  "peerDependencies": {
+    "react": "^18.0.0 || ^19.0.0",
+    "@lagless/core": "0.0.48",
+    "@lagless/react": "0.0.48"
+  },
+  "peerDependenciesMeta": {
+    "@lagless/react": {
+      "optional": true
+    },
+    "react": {
+      "optional": true
+    }
+  }
+}

package/src/index.ts

@@ -0,0 +1,26 @@
+export { DiagnosticsCollector } from './lib/diagnostics-collector.js';
+export { hashBytes } from './lib/hash-bytes.js';
+export { analyzeDivergence } from './lib/divergence-analysis.js';
+export type { DivergenceAnalysis, CheckpointComparison, RollbackOverlapWindow } from './lib/divergence-analysis.js';
+export { attachDesyncDiagnostics } from './lib/attach.js';
+export { generateReport } from './lib/report-generator.js';
+export type { DiagnosticsConfig, TickRecord, RollbackEvent, DiagnosticsStats } from './lib/types.js';
+export type {
+  DiagnosticsReport,
+  CombinedDiagnosticsReport,
+  DiagnosticsReportConfig,
+  DiagnosticsReportSummary,
+  DiagnosticsReportTickRecord,
+  DiagnosticsReportRPC,
+} from './lib/report-generator.js';
+export { useDesyncDiagnostics, type UseDesyncDiagnosticsOptions } from './lib/use-desync-diagnostics.js';
+export { PerformanceProfiler } from './lib/performance-profiler.js';
+export type { PerformanceStats, SystemTimingStats, TimingStats } from './lib/performance-profiler.js';
+export type {
+  DiagnosticsSummaryMessage,
+  DiagnosticsReportMessage,
+  PerformanceStatsMessage,
+  DiagnosticsChildMessage,
+  RequestDiagnosticsReportMessage,
+  DiagnosticsParentMessage,
+} from './lib/diagnostics-protocol.js';

package/src/lib/attach.ts

@@ -0,0 +1,10 @@
+import type { ECSRunner } from '@lagless/core';
+import { DiagnosticsCollector } from './diagnostics-collector.js';
+import type { DiagnosticsConfig } from './types.js';
+
+export function attachDesyncDiagnostics(
+  runner: ECSRunner,
+  config?: DiagnosticsConfig,
+): DiagnosticsCollector {
+  return new DiagnosticsCollector(runner, config);
+}