@abloatai/ablo 0.3.0

package/dist/testing/helpers/react-wrapper.d.ts

@@ -0,0 +1,66 @@
+/**
+ * React test helpers for the sync engine SDK.
+ *
+ * These helpers wire the SDK's SyncProvider into @testing-library/react
+ * so consumers can test components and hooks that use useModel/useModels/useMutations.
+ */
+import * as React from 'react';
+import { type SyncStoreContract } from '../../react/context.js';
+import { MockSyncStore, createMockSyncStore } from '../mocks/MockSyncStore.js';
+export interface TestWrapperOptions {
+    /** Mock sync store. If omitted, a new MockSyncStore is created. */
+    store?: SyncStoreContract;
+    /** Organization ID. Default: "test-org-id". */
+    organizationId?: string;
+}
+/**
+ * Create a wrapper component for @testing-library/react's renderHook/render.
+ * Wraps children in the SDK's SyncProvider with a mock store.
+ *
+ * @example
+ * import { renderHook } from '@testing-library/react';
+ * import { createReactTestWrapper, createMockSyncStore } from '@ablo/sync-engine/testing';
+ *
+ * const mockStore = createMockSyncStore();
+ * mockStore.setModels(Task, [task1, task2]);
+ *
+ * const { result } = renderHook(
+ *   () => useModels(Task),
+ *   { wrapper: createReactTestWrapper({ store: mockStore }) }
+ * );
+ */
+export declare function createReactTestWrapper(options?: TestWrapperOptions): React.FC<{
+    children: React.ReactNode;
+}>;
+/**
+ * Drop-in replacement for @testing-library/react's `renderHook` that
+ * automatically provides the SDK's SyncProvider with a mock store.
+ *
+ * Note: This helper lazy-loads @testing-library/react to avoid forcing
+ * consumers without React tests to install it.
+ *
+ * @example
+ * import { renderSyncHook, createMockSyncStore } from '@ablo/sync-engine/testing';
+ *
+ * const mockStore = createMockSyncStore();
+ * mockStore.addModel(Task, myTask);
+ *
+ * const { result } = renderSyncHook(
+ *   () => useModel(Task, myTask.id),
+ *   { store: mockStore }
+ * );
+ * expect(result.current?.id).toBe(myTask.id);
+ */
+export declare function renderSyncHook<TProps, TResult>(callback: (props: TProps) => TResult, options?: TestWrapperOptions & {
+    initialProps?: TProps;
+}): {
+    result: {
+        current: TResult;
+    };
+    rerender: (props?: TProps) => void;
+    unmount: () => void;
+};
+/**
+ * Re-export MockSyncStore for convenience.
+ */
+export { MockSyncStore, createMockSyncStore };

package/dist/testing/helpers/react-wrapper.js

@@ -0,0 +1,64 @@
+/**
+ * React test helpers for the sync engine SDK.
+ *
+ * These helpers wire the SDK's SyncProvider into @testing-library/react
+ * so consumers can test components and hooks that use useModel/useModels/useMutations.
+ */
+import * as React from 'react';
+import { SyncProvider } from '../../react/context.js';
+import { MockSyncStore, createMockSyncStore } from '../mocks/MockSyncStore.js';
+/**
+ * Create a wrapper component for @testing-library/react's renderHook/render.
+ * Wraps children in the SDK's SyncProvider with a mock store.
+ *
+ * @example
+ * import { renderHook } from '@testing-library/react';
+ * import { createReactTestWrapper, createMockSyncStore } from '@ablo/sync-engine/testing';
+ *
+ * const mockStore = createMockSyncStore();
+ * mockStore.setModels(Task, [task1, task2]);
+ *
+ * const { result } = renderHook(
+ *   () => useModels(Task),
+ *   { wrapper: createReactTestWrapper({ store: mockStore }) }
+ * );
+ */
+export function createReactTestWrapper(options = {}) {
+    const store = options.store ?? createMockSyncStore();
+    const organizationId = options.organizationId ?? 'test-org-id';
+    const Wrapper = ({ children }) => React.createElement(SyncProvider, { store, organizationId }, children);
+    return Wrapper;
+}
+/**
+ * Drop-in replacement for @testing-library/react's `renderHook` that
+ * automatically provides the SDK's SyncProvider with a mock store.
+ *
+ * Note: This helper lazy-loads @testing-library/react to avoid forcing
+ * consumers without React tests to install it.
+ *
+ * @example
+ * import { renderSyncHook, createMockSyncStore } from '@ablo/sync-engine/testing';
+ *
+ * const mockStore = createMockSyncStore();
+ * mockStore.addModel(Task, myTask);
+ *
+ * const { result } = renderSyncHook(
+ *   () => useModel(Task, myTask.id),
+ *   { store: mockStore }
+ * );
+ * expect(result.current?.id).toBe(myTask.id);
+ */
+export function renderSyncHook(callback, options = {}) {
+    // Lazy-load @testing-library/react so the SDK doesn't force consumers
+    // to install it unless they actually use these helpers.
+    // eslint-disable-next-line @typescript-eslint/no-require-imports
+    const rtl = require('@testing-library/react');
+    return rtl.renderHook(callback, {
+        wrapper: createReactTestWrapper(options),
+        initialProps: options.initialProps,
+    });
+}
+/**
+ * Re-export MockSyncStore for convenience.
+ */
+export { MockSyncStore, createMockSyncStore };

package/dist/testing/helpers/sync-engine-harness.d.ts

@@ -0,0 +1,55 @@
+/**
+ * Full sync engine test harness.
+ *
+ * Creates a complete stack (ModelRegistry, ObjectPool, TransactionQueue, etc.)
+ * with real implementations backed by mocked I/O for integration tests.
+ */
+import { ModelRegistry } from '../../ModelRegistry.js';
+import { ObjectPool } from '../../ObjectPool.js';
+import { MockMutationExecutor } from '../mocks/MockMutationExecutor.js';
+import { MockNetworkMonitor } from '../mocks/MockNetworkMonitor.js';
+import { MockWebSocket } from '../mocks/MockWebSocket.js';
+import { MockMutationDispatcher } from '../mocks/MockSyncContext.js';
+import type { TestContextResult } from '../mocks/MockSyncContext.js';
+export interface TestHarness {
+    /** Pre-registered ModelRegistry with test models */
+    registry: ModelRegistry;
+    /** Real ObjectPool with FK indexes configured */
+    pool: ObjectPool;
+    /** Mock WebSocket for delta injection */
+    webSocket: MockWebSocket;
+    /** DI context with all mocks */
+    context: TestContextResult;
+    /** Shorthand: mock mutation executor */
+    mutationExecutor: MockMutationExecutor;
+    /** Shorthand: mock network monitor */
+    networkMonitor: MockNetworkMonitor;
+    /** Shorthand: mock mutation dispatcher */
+    mutationDispatcher: MockMutationDispatcher;
+    /** Cleanup everything */
+    cleanup: () => void;
+}
+export interface TestHarnessOptions {
+    /** Start offline (default: false) */
+    startOffline?: boolean;
+    /** Initial sync ID for mutation executor */
+    initialSyncId?: number;
+    /** ObjectPool config overrides */
+    poolConfig?: {
+        maxSize?: number;
+        maxAge?: number;
+        gcInterval?: number;
+        useWeakRefs?: boolean;
+    };
+}
+/**
+ * Create a full test harness with real sync engine components + mocked I/O.
+ *
+ * Usage:
+ * ```ts
+ * let harness: TestHarness;
+ * beforeEach(() => { harness = createTestHarness(); });
+ * afterEach(() => { harness.cleanup(); });
+ * ```
+ */
+export declare function createTestHarness(options?: TestHarnessOptions): TestHarness;

package/dist/testing/helpers/sync-engine-harness.js

@@ -0,0 +1,70 @@
+/**
+ * Full sync engine test harness.
+ *
+ * Creates a complete stack (ModelRegistry, ObjectPool, TransactionQueue, etc.)
+ * with real implementations backed by mocked I/O for integration tests.
+ */
+import { ModelRegistry, setActiveRegistry } from '../../ModelRegistry.js';
+import { ObjectPool } from '../../ObjectPool.js';
+import { MockWebSocket } from '../mocks/MockWebSocket.js';
+import { createTestContext } from '../mocks/MockSyncContext.js';
+import { registerTestModels, createTestConfig, resetFixtureCounter, } from '../fixtures/models.js';
+import { resetDeltaCounter } from '../fixtures/deltas.js';
+/**
+ * Create a full test harness with real sync engine components + mocked I/O.
+ *
+ * Usage:
+ * ```ts
+ * let harness: TestHarness;
+ * beforeEach(() => { harness = createTestHarness(); });
+ * afterEach(() => { harness.cleanup(); });
+ * ```
+ */
+export function createTestHarness(options = {}) {
+    // Reset counters for deterministic tests
+    resetFixtureCounter();
+    resetDeltaCounter();
+    // Create and register test models
+    const registry = new ModelRegistry();
+    setActiveRegistry(registry);
+    registerTestModels(registry);
+    // Create DI context with test config
+    const testConfig = createTestConfig();
+    const context = createTestContext({
+        config: testConfig,
+        startOffline: options.startOffline,
+        mutationExecutorOptions: {
+            initialSyncId: options.initialSyncId ?? 1,
+        },
+    });
+    // Create real ObjectPool with FK indexes
+    const pool = new ObjectPool({
+        maxSize: options.poolConfig?.maxSize ?? 10000,
+        maxAge: options.poolConfig?.maxAge ?? 5 * 60 * 1000,
+        gcInterval: options.poolConfig?.gcInterval ?? 0, // Disable auto-GC in tests
+        useWeakRefs: options.poolConfig?.useWeakRefs ?? false, // Disable WeakRefs for predictable tests
+    }, registry);
+    // Register FK indexes for test models
+    pool.registerForeignKey('Task', 'projectId');
+    pool.registerForeignKey('Comment', 'taskId');
+    pool.registerForeignKey('Slide', 'deckId');
+    pool.registerForeignKey('SlideLayer', 'slideId');
+    // Create mock WebSocket
+    const webSocket = new MockWebSocket();
+    return {
+        registry,
+        pool,
+        webSocket,
+        context,
+        mutationExecutor: context.mocks.mutationExecutor,
+        networkMonitor: context.mocks.networkMonitor,
+        mutationDispatcher: context.mocks.mutationDispatcher,
+        cleanup: () => {
+            pool.clear();
+            webSocket.reset();
+            context.cleanup();
+            resetFixtureCounter();
+            resetDeltaCounter();
+        },
+    };
+}

package/dist/testing/helpers/wait.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Async test helpers for timing-sensitive sync engine tests.
+ */
+/**
+ * Flush all pending microtasks (Promise.resolve, queueMicrotask).
+ * Critical for testing TransactionQueue's microtask batching.
+ */
+export declare function flushMicrotasks(): Promise<void>;
+/**
+ * Wait for a condition to become true, polling at intervals.
+ * Times out after maxWait ms.
+ */
+export declare function waitFor(condition: () => boolean, options?: {
+    maxWait?: number;
+    interval?: number;
+}): Promise<void>;
+/**
+ * Wait for N milliseconds. Use sparingly — prefer flushMicrotasks() or waitFor().
+ */
+export declare function delay(ms: number): Promise<void>;
+/**
+ * Run a callback after flushing microtasks.
+ * Useful for asserting state after TransactionQueue batch processing.
+ */
+export declare function afterMicrotasks<T>(fn: () => T): Promise<T>;

package/dist/testing/helpers/wait.js

@@ -0,0 +1,44 @@
+/**
+ * Async test helpers for timing-sensitive sync engine tests.
+ */
+import { AbloConnectionError } from '../../errors.js';
+/**
+ * Flush all pending microtasks (Promise.resolve, queueMicrotask).
+ * Critical for testing TransactionQueue's microtask batching.
+ */
+export function flushMicrotasks() {
+    return new Promise((resolve) => {
+        // Use setTimeout(0) to yield to the microtask queue
+        setTimeout(resolve, 0);
+    });
+}
+/**
+ * Wait for a condition to become true, polling at intervals.
+ * Times out after maxWait ms.
+ */
+export async function waitFor(condition, options = {}) {
+    const { maxWait = 5000, interval = 10 } = options;
+    const start = Date.now();
+    while (!condition()) {
+        if (Date.now() - start > maxWait) {
+            throw new AbloConnectionError(`waitFor timed out after ${maxWait}ms`, {
+                code: 'wait_for_timeout',
+            });
+        }
+        await new Promise((resolve) => setTimeout(resolve, interval));
+    }
+}
+/**
+ * Wait for N milliseconds. Use sparingly — prefer flushMicrotasks() or waitFor().
+ */
+export function delay(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+/**
+ * Run a callback after flushing microtasks.
+ * Useful for asserting state after TransactionQueue batch processing.
+ */
+export async function afterMicrotasks(fn) {
+    await flushMicrotasks();
+    return fn();
+}

package/dist/testing/index.d.ts

@@ -0,0 +1,21 @@
+/**
+ * @ablo/sync-engine/testing — Public test utilities for SDK consumers.
+ *
+ * Provides mock implementations, fixture factories, and test harnesses
+ * for writing integration tests against the sync engine.
+ */
+export { MockMutationExecutor } from './mocks/MockMutationExecutor.js';
+export type { CapturedMutation, MockMutationExecutorOptions } from './mocks/MockMutationExecutor.js';
+export { MockNetworkMonitor } from './mocks/MockNetworkMonitor.js';
+export { MockWebSocket } from './mocks/MockWebSocket.js';
+export type { MockDelta, MockBootstrapHint } from './mocks/MockWebSocket.js';
+export { createTestContext, MockMutationDispatcher, } from './mocks/MockSyncContext.js';
+export type { TestContextOptions, TestContextResult } from './mocks/MockSyncContext.js';
+export { TestProject, TestTask, TestComment, TestSlideDeck, TestSlide, TestSlideLayer, TEST_MODEL_PRIORITIES, registerTestModels, createTestConfig, resetFixtureCounter, createProjectFixture, createTaskFixture, createCommentFixture, createSlideDeckFixture, createSlideFixture, createSlideLayerFixture, } from './fixtures/models.js';
+export { createDelta, createInsertDelta, createUpdateDelta, createDeleteDelta, createArchiveDelta, createUnarchiveDelta, createCoveringDelta, createGroupAddedDelta, createLegacyGroupChangeDelta, createGroupRemovedDelta, createDeltaBatch, createConfirmationDelta, resetDeltaCounter, } from './fixtures/deltas.js';
+export { createFullBootstrapResponse, createPartialBootstrapResponse, createTestBootstrapResponse, } from './fixtures/bootstrap.js';
+export type { BootstrapModelData, BootstrapResponse } from './fixtures/bootstrap.js';
+export { createTestHarness, } from './helpers/sync-engine-harness.js';
+export type { TestHarness, TestHarnessOptions } from './helpers/sync-engine-harness.js';
+export { flushMicrotasks, waitFor, delay, afterMicrotasks, } from './helpers/wait.js';
+export { createReactTestWrapper, renderSyncHook, MockSyncStore, createMockSyncStore, type TestWrapperOptions, } from './helpers/react-wrapper.js';

package/dist/testing/index.js

@@ -0,0 +1,32 @@
+/**
+ * @ablo/sync-engine/testing — Public test utilities for SDK consumers.
+ *
+ * Provides mock implementations, fixture factories, and test harnesses
+ * for writing integration tests against the sync engine.
+ */
+// ─────────────────────────────────────────────
+// Mocks
+// ─────────────────────────────────────────────
+export { MockMutationExecutor } from './mocks/MockMutationExecutor.js';
+export { MockNetworkMonitor } from './mocks/MockNetworkMonitor.js';
+export { MockWebSocket } from './mocks/MockWebSocket.js';
+export { createTestContext, MockMutationDispatcher, } from './mocks/MockSyncContext.js';
+// ─────────────────────────────────────────────
+// Fixtures: Models
+// ─────────────────────────────────────────────
+export { TestProject, TestTask, TestComment, TestSlideDeck, TestSlide, TestSlideLayer, TEST_MODEL_PRIORITIES, registerTestModels, createTestConfig, resetFixtureCounter, createProjectFixture, createTaskFixture, createCommentFixture, createSlideDeckFixture, createSlideFixture, createSlideLayerFixture, } from './fixtures/models.js';
+// ─────────────────────────────────────────────
+// Fixtures: Deltas
+// ─────────────────────────────────────────────
+export { createDelta, createInsertDelta, createUpdateDelta, createDeleteDelta, createArchiveDelta, createUnarchiveDelta, createCoveringDelta, createGroupAddedDelta, createLegacyGroupChangeDelta, createGroupRemovedDelta, createDeltaBatch, createConfirmationDelta, resetDeltaCounter, } from './fixtures/deltas.js';
+// ─────────────────────────────────────────────
+// Fixtures: Bootstrap
+// ─────────────────────────────────────────────
+export { createFullBootstrapResponse, createPartialBootstrapResponse, createTestBootstrapResponse, } from './fixtures/bootstrap.js';
+// ─────────────────────────────────────────────
+// Helpers
+// ─────────────────────────────────────────────
+export { createTestHarness, } from './helpers/sync-engine-harness.js';
+export { flushMicrotasks, waitFor, delay, afterMicrotasks, } from './helpers/wait.js';
+// React testing helpers
+export { createReactTestWrapper, renderSyncHook, MockSyncStore, createMockSyncStore, } from './helpers/react-wrapper.js';

package/dist/testing/mocks/MockMutationExecutor.d.ts

@@ -0,0 +1,65 @@
+/**
+ * MockMutationExecutor — Test double for the MutationExecutor interface.
+ *
+ * Captures all mutation calls, allows controlled responses (success/failure/latency),
+ * and returns configurable lastSyncId for delta confirmation testing.
+ */
+import type { MutationExecutor, MutationOperation, MutationOptions, CommitResult } from '../../interfaces/index.js';
+export interface CapturedMutation {
+    method: string;
+    modelName?: string;
+    modelId?: string;
+    input?: Record<string, unknown>;
+    operations?: MutationOperation[];
+    options?: MutationOptions;
+    clientMutationId?: string;
+    timestamp: number;
+}
+export interface MockMutationExecutorOptions {
+    /** Starting lastSyncId — increments by 1 per commit call */
+    initialSyncId?: number;
+    /** Whether mutations should succeed by default */
+    shouldSucceed?: boolean;
+    /** Simulated network latency in ms */
+    latencyMs?: number;
+}
+export declare class MockMutationExecutor implements MutationExecutor {
+    /** All captured mutation calls in order */
+    readonly calls: CapturedMutation[];
+    /** Current sync ID — incremented on each successful commit */
+    private _syncId;
+    private _shouldSucceed;
+    private _latencyMs;
+    /** Per-method failure overrides: method name → error */
+    private _failureOverrides;
+    /** Per-method response overrides */
+    private _responseOverrides;
+    constructor(options?: MockMutationExecutorOptions);
+    /** Get current sync ID without incrementing */
+    get currentSyncId(): number;
+    /** Set the next sync ID to return */
+    setSyncId(id: number): void;
+    /** Make all mutations fail with given error */
+    failAll(error?: Error): void;
+    /** Make all mutations succeed again */
+    succeedAll(): void;
+    /** Make a specific method fail */
+    failMethod(method: string, error?: Error): void;
+    /** Clear failure override for a method */
+    clearFailure(method: string): void;
+    /** Get calls filtered by method */
+    getCallsByMethod(method: string): CapturedMutation[];
+    /** Get the last call made */
+    get lastCall(): CapturedMutation | undefined;
+    /** Reset all state */
+    reset(options?: MockMutationExecutorOptions): void;
+    commit(operations: MutationOperation[], options?: MutationOptions): Promise<CommitResult>;
+    executeCreate(modelName: string, id: string, input: Record<string, unknown>, clientMutationId?: string): Promise<void>;
+    executeUpdate(modelName: string, modelId: string, data: Record<string, unknown>, clientMutationId?: string): Promise<CommitResult | null>;
+    executeDelete(modelName: string, modelId: string, clientMutationId?: string): Promise<void>;
+    executeArchive(modelName: string, modelId: string, clientMutationId?: string): Promise<void>;
+    executeUnarchive(modelName: string, modelId: string, clientMutationId?: string): Promise<void>;
+    private _capture;
+    private _maybeDelay;
+    private _maybeThrow;
+}

package/dist/testing/mocks/MockMutationExecutor.js

@@ -0,0 +1,139 @@
+/**
+ * MockMutationExecutor — Test double for the MutationExecutor interface.
+ *
+ * Captures all mutation calls, allows controlled responses (success/failure/latency),
+ * and returns configurable lastSyncId for delta confirmation testing.
+ */
+import { AbloError } from '../../errors.js';
+export class MockMutationExecutor {
+    /** All captured mutation calls in order */
+    calls = [];
+    /** Current sync ID — incremented on each successful commit */
+    _syncId;
+    _shouldSucceed;
+    _latencyMs;
+    /** Per-method failure overrides: method name → error */
+    _failureOverrides = new Map();
+    /** Per-method response overrides */
+    _responseOverrides = new Map();
+    constructor(options = {}) {
+        this._syncId = options.initialSyncId ?? 1;
+        this._shouldSucceed = options.shouldSucceed ?? true;
+        this._latencyMs = options.latencyMs ?? 0;
+    }
+    // ─────────────────────────────────────────────
+    // Test control API
+    // ─────────────────────────────────────────────
+    /** Get current sync ID without incrementing */
+    get currentSyncId() {
+        return this._syncId;
+    }
+    /** Set the next sync ID to return */
+    setSyncId(id) {
+        this._syncId = id;
+    }
+    /** Make all mutations fail with given error */
+    failAll(error) {
+        this._shouldSucceed = false;
+        if (error) {
+            this._failureOverrides.set('*', error);
+        }
+    }
+    /** Make all mutations succeed again */
+    succeedAll() {
+        this._shouldSucceed = true;
+        this._failureOverrides.clear();
+    }
+    /** Make a specific method fail */
+    failMethod(method, error) {
+        this._failureOverrides.set(method, error ?? new Error(`Mock ${method} failed`));
+    }
+    /** Clear failure override for a method */
+    clearFailure(method) {
+        this._failureOverrides.delete(method);
+    }
+    /** Get calls filtered by method */
+    getCallsByMethod(method) {
+        return this.calls.filter((c) => c.method === method);
+    }
+    /** Get the last call made */
+    get lastCall() {
+        return this.calls[this.calls.length - 1];
+    }
+    /** Reset all state */
+    reset(options) {
+        this.calls.length = 0;
+        this._syncId = options?.initialSyncId ?? 1;
+        this._shouldSucceed = options?.shouldSucceed ?? true;
+        this._latencyMs = options?.latencyMs ?? 0;
+        this._failureOverrides.clear();
+        this._responseOverrides.clear();
+    }
+    // ─────────────────────────────────────────────
+    // MutationExecutor interface implementation
+    // ─────────────────────────────────────────────
+    async commit(operations, options) {
+        this._capture('commit', { operations, options });
+        await this._maybeDelay();
+        this._maybeThrow('commit');
+        const syncId = this._syncId++;
+        return { lastSyncId: syncId };
+    }
+    async executeCreate(modelName, id, input, clientMutationId) {
+        this._capture('executeCreate', { modelName, modelId: id, input, clientMutationId });
+        await this._maybeDelay();
+        this._maybeThrow('executeCreate');
+    }
+    async executeUpdate(modelName, modelId, data, clientMutationId) {
+        this._capture('executeUpdate', { modelName, modelId, input: data, clientMutationId });
+        await this._maybeDelay();
+        this._maybeThrow('executeUpdate');
+        return { lastSyncId: this._syncId++ };
+    }
+    async executeDelete(modelName, modelId, clientMutationId) {
+        this._capture('executeDelete', { modelName, modelId, clientMutationId });
+        await this._maybeDelay();
+        this._maybeThrow('executeDelete');
+    }
+    async executeArchive(modelName, modelId, clientMutationId) {
+        this._capture('executeArchive', { modelName, modelId, clientMutationId });
+        await this._maybeDelay();
+        this._maybeThrow('executeArchive');
+    }
+    async executeUnarchive(modelName, modelId, clientMutationId) {
+        this._capture('executeUnarchive', { modelName, modelId, clientMutationId });
+        await this._maybeDelay();
+        this._maybeThrow('executeUnarchive');
+    }
+    // ─────────────────────────────────────────────
+    // Internal helpers
+    // ─────────────────────────────────────────────
+    _capture(method, data) {
+        this.calls.push({
+            method,
+            timestamp: Date.now(),
+            ...data,
+        });
+    }
+    async _maybeDelay() {
+        if (this._latencyMs > 0) {
+            await new Promise((r) => setTimeout(r, this._latencyMs));
+        }
+    }
+    _maybeThrow(method) {
+        // Check specific method override first
+        const methodError = this._failureOverrides.get(method);
+        if (methodError)
+            throw methodError;
+        // Check global override
+        const globalError = this._failureOverrides.get('*');
+        if (globalError)
+            throw globalError;
+        // Check global flag
+        if (!this._shouldSucceed) {
+            throw new AbloError(`Mock mutation failed: ${method}`, {
+                code: 'mock_mutation_failed',
+            });
+        }
+    }
+}

package/dist/testing/mocks/MockNetworkMonitor.d.ts

@@ -0,0 +1,20 @@
+/**
+ * MockNetworkMonitor — Test double for OnlineStatusProvider.
+ *
+ * Allows tests to programmatically toggle online/offline state
+ * and trigger visibility change events.
+ */
+import type { OnlineStatusProvider } from '../../interfaces/index.js';
+export declare class MockNetworkMonitor implements OnlineStatusProvider {
+    private _online;
+    constructor(initialOnline?: boolean);
+    isOnline(): boolean;
+    /** Simulate going online */
+    goOnline(): void;
+    /** Simulate going offline */
+    goOffline(): void;
+    /** Toggle online state and return new value */
+    toggle(): boolean;
+    /** Reset to initial state (online) */
+    reset(): void;
+}

package/dist/testing/mocks/MockNetworkMonitor.js

@@ -0,0 +1,46 @@
+/**
+ * MockNetworkMonitor — Test double for OnlineStatusProvider.
+ *
+ * Allows tests to programmatically toggle online/offline state
+ * and trigger visibility change events.
+ */
+export class MockNetworkMonitor {
+    _online;
+    constructor(initialOnline = true) {
+        this._online = initialOnline;
+    }
+    isOnline() {
+        return this._online;
+    }
+    /** Simulate going online */
+    goOnline() {
+        this._online = true;
+        // Also update navigator.onLine for code that reads it directly
+        Object.defineProperty(navigator, 'onLine', {
+            writable: true,
+            value: true,
+        });
+    }
+    /** Simulate going offline */
+    goOffline() {
+        this._online = false;
+        Object.defineProperty(navigator, 'onLine', {
+            writable: true,
+            value: false,
+        });
+    }
+    /** Toggle online state and return new value */
+    toggle() {
+        if (this._online) {
+            this.goOffline();
+        }
+        else {
+            this.goOnline();
+        }
+        return this._online;
+    }
+    /** Reset to initial state (online) */
+    reset() {
+        this.goOnline();
+    }
+}