@xnetjs/react 0.0.2 → 0.0.3

package/dist/context-CFu9i136.d.ts

@@ -0,0 +1,392 @@
+import { SyncManager, BlobStoreForSync, SyncStatus, ConnectionManager } from '@xnetjs/runtime';
+import { DID } from '@xnetjs/core';
+import { SecurityLevel } from '@xnetjs/crypto';
+import { NodeStorageAdapter, NodeStore } from '@xnetjs/data';
+import { Identity, PQKeyRegistry, HybridKeyBundle } from '@xnetjs/identity';
+import { SyncReplicationConfig } from '@xnetjs/sync';
+import * as react from 'react';
+import { ReactNode } from 'react';
+import { DataBridge, RemoteNodeQueryClient, NodeQueryRouterThresholds } from '@xnetjs/data-bridge';
+import { UndoManager } from '@xnetjs/history';
+import { Platform, PluginRegistry } from '@xnetjs/plugins';
+import { T as TelemetryReporter } from './telemetry-context-B7r6H1KW.js';
+
+/**
+ * Runtime configuration helpers for @xnetjs/react
+ */
+
+type XNetRuntimeMode = 'main-thread' | 'worker' | 'ipc';
+type XNetRuntimeFallback = 'main-thread' | 'error';
+type XNetRuntimePhase = 'initializing' | 'ready' | 'error';
+interface XNetRuntimeWorkerConfig {
+    /**
+     * Worker entry URL for the data runtime.
+     * When omitted, worker mode will fall back or error explicitly.
+     */
+    url?: string | URL;
+    /**
+     * Optional database name for worker-backed storage.
+     */
+    dbName?: string;
+    /**
+     * Optional signaling URL override for worker-backed sync.
+     */
+    signalingUrl?: string;
+    /**
+     * Optional MessagePort connected to the SQLite worker (from
+     * `WebSQLiteProxy.createMessagePort()`). Transferred to the data worker
+     * so its storage calls run worker-to-worker; without it the data worker
+     * uses in-memory storage.
+     */
+    storagePort?: MessagePort;
+}
+interface XNetRuntimeConfig {
+    /**
+     * Requested runtime mode for data and sync orchestration.
+     */
+    mode: XNetRuntimeMode;
+    /**
+     * Fallback behavior when the requested runtime cannot be activated.
+     */
+    fallback?: XNetRuntimeFallback;
+    /**
+     * Emit runtime diagnostics through console logging.
+     */
+    diagnostics?: boolean;
+    /**
+     * Worker-specific bootstrap options.
+     */
+    worker?: XNetRuntimeWorkerConfig;
+}
+interface XNetRuntimeStatus {
+    /**
+     * Runtime mode requested by app bootstrap.
+     */
+    requestedMode: XNetRuntimeMode;
+    /**
+     * Runtime mode currently active.
+     * Null while initializing or when runtime activation failed.
+     */
+    activeMode: XNetRuntimeMode | null;
+    /**
+     * Fallback mode that was used, if any.
+     */
+    fallbackMode: XNetRuntimeMode | null;
+    /**
+     * Whether the provider had to deviate from the requested runtime mode.
+     */
+    usedFallback: boolean;
+    /**
+     * Runtime initialization phase.
+     */
+    phase: XNetRuntimePhase;
+    /**
+     * Human-readable reason for fallback or failure.
+     */
+    reason: string | null;
+}
+
+/**
+ * Tracing context for @xnetjs/react (exploration 0190).
+ *
+ * Provides an optional duck-typed TracingReporter to the React tree. When
+ * present, useQuery/useMutate open a per-call trace and record main-thread
+ * stage spans. Mirrors the telemetry-context duck-typing so @xnetjs/react
+ * never has to depend on @xnetjs/telemetry (which would be circular).
+ *
+ * The reporter is satisfied by @xnetjs/telemetry's `TraceCollector`. When no
+ * reporter is supplied the hooks pay nothing — `tracing?.startTrace(...)` is a
+ * no-op and the optional chaining short-circuits.
+ */
+declare const TRACE_STAGES: {
+    readonly queryDescriptor: "data.query.descriptor";
+    readonly queryBridge: "data.query.bridge";
+    readonly queryFlatten: "data.query.flatten";
+    readonly queryCommit: "data.query.commit";
+    readonly mutateBridge: "data.mutate.bridge";
+};
+type TracingRootKind = 'query' | 'mutate' | 'sync' | 'other';
+type TracingAttributes = Record<string, string | number | boolean | undefined>;
+interface TracingSpanInput {
+    name: string;
+    startOffsetMs: number;
+    durationMs: number;
+    parentSpanId?: string;
+    attributes?: TracingAttributes;
+}
+/** A handle to an in-progress trace. Inert when the trace is not being captured. */
+interface TracingHandle {
+    readonly traceId: string;
+    readonly active: boolean;
+    /** Start timing a stage; the returned fn records the span when called. */
+    mark(name: string, parentSpanId?: string): (attributes?: TracingAttributes) => string;
+    addSpan(span: TracingSpanInput): string;
+    end(): unknown;
+}
+/**
+ * Duck-typed interface for opening traces. Satisfied by @xnetjs/telemetry's
+ * `TraceCollector` (structurally — `startTrace` returns a compatible handle).
+ */
+interface TracingReporter {
+    startTrace(rootKind: TracingRootKind, rootName: string, traceId?: string): TracingHandle;
+}
+declare const TracingContext: react.Context<TracingReporter | null>;
+/**
+ * Hook to access the tracing reporter (null if no tracing configured).
+ * @internal Used by useQuery/useMutate — not part of the public hook API.
+ */
+declare function useTracingReporter(): TracingReporter | null;
+
+/**
+ * XNet React context provider
+ *
+ * Provides NodeStore and optional identity to the React tree.
+ * All data access happens through useQuery/useMutate/useNode hooks.
+ */
+
+/**
+ * XNet configuration
+ */
+interface XNetConfig {
+    /** Node storage adapter for NodeStore (defaults to MemoryNodeStorageAdapter) */
+    nodeStorage?: NodeStorageAdapter;
+    /** Author's DID for signing changes */
+    authorDID?: DID;
+    /** Ed25519 signing key */
+    signingKey?: Uint8Array;
+    /** User identity */
+    identity?: Identity;
+    /** Signaling server URLs for sync (default: ['ws://localhost:4444']) */
+    signalingServers?: string[];
+    /** Hub WebSocket URL for always-on sync (overrides signalingServers[0]) */
+    hubUrl?: string;
+    /**
+     * Optional billing config (exploration 0187), surfaced to `useBilling`. The
+     * default redirect-checkout flow needs neither field — the hub creates checkout
+     * sessions server-side with the secret key. Use `apiBase` only to point billing
+     * at a different origin than the hub, and `publishableKey` only for future
+     * embedded (Stripe Elements) checkout.
+     */
+    billing?: {
+        /** Base URL for the hub billing routes. Defaults to the hub's HTTP URL. */
+        apiBase?: string;
+        /** Stripe publishable key (`pk_…`). The secret key NEVER goes on the client. */
+        publishableKey?: string;
+    };
+    /** Hub integration options */
+    hubOptions?: {
+        /** Auto-generate UCAN for hub auth (default: true) */
+        autoAuth?: boolean;
+        /** Static UCAN token override for pre-authorized share sessions */
+        authToken?: string;
+        /** Enable auto-backup on document updates (default: false) */
+        autoBackup?: boolean;
+        /** Backup debounce delay in ms (default: 5000) */
+        backupDebounceMs?: number;
+        /** Enable search indexing on NodeStore changes (default: false) */
+        enableSearchIndex?: boolean;
+        /** Room name for node-change relay (defaults to author DID) */
+        nodeSyncRoom?: string;
+    };
+    /** Encryption key for hub backups (XChaCha20-Poly1305) */
+    encryptionKey?: Uint8Array;
+    /** Disable Background Sync Manager (default: false) */
+    disableSyncManager?: boolean;
+    /** Provide an external SyncManager (e.g., IPC-based for Electron desktop).
+     *  When provided, the internal SyncManager creation is skipped. */
+    syncManager?: SyncManager;
+    /** Blob store for P2P blob sync (images, files). If provided, the SyncManager
+     *  will sync blobs alongside Y.Doc state. Typically a BlobStore from @xnetjs/storage. */
+    blobStore?: BlobStoreForSync;
+    /** Platform for plugin compatibility ('web' | 'electron' | 'mobile'). Defaults to 'web'. */
+    platform?: Platform;
+    /** Signed replication policy for document sync. */
+    sync?: SyncReplicationConfig;
+    /** Disable plugin system (default: false) */
+    disablePlugins?: boolean;
+    /**
+     * Explicit runtime selection for bridge and sync bootstrap.
+     */
+    runtime?: XNetRuntimeConfig;
+    /**
+     * Custom DataBridge instance.
+     *
+     * When provided, this bridge is used for data access instead of creating
+     * a MainThreadBridge. This allows using WorkerBridge or other off-main-thread
+     * implementations.
+     *
+     * The bridge must already be initialized before passing to XNetProvider.
+     *
+     * Note: When using a custom bridge, NodeStore is still created on the main
+     * thread for SyncManager and other integrations. The custom bridge is used
+     * only for React hook data access (useQuery, useMutate).
+     *
+     * @example
+     * ```tsx
+     * // Using WorkerBridge
+     * const bridge = new WorkerBridge(workerUrl)
+     * await bridge.initialize({ authorDID, signingKey, dbName: 'xnet' })
+     *
+     * <XNetProvider config={{ dataBridge: bridge, ... }}>
+     *   <App />
+     * </XNetProvider>
+     * ```
+     */
+    dataBridge?: DataBridge;
+    /**
+     * Optional remote Node query client for progressive `useQuery` reads.
+     *
+     * When provided with the main-thread bridge, queries using
+     * `mode: 'local-then-remote'` render the local snapshot first and then merge
+     * hub/federated results. Queries using `mode: 'remote'` use this client as
+     * their primary source.
+     */
+    remoteNodeQueryClient?: RemoteNodeQueryClient;
+    /**
+     * Optional routing thresholds for `source: "auto"` Node descriptor reads.
+     *
+     * These thresholds are used by the main-thread bridge after the first local
+     * snapshot to decide whether a remote client should refresh the same query.
+     */
+    remoteNodeQueryRouting?: Partial<NodeQueryRouterThresholds>;
+    /**
+     * Security configuration for multi-level cryptography.
+     */
+    security?: {
+        /** Default security level for new signatures (default: 0 for Ed25519-only) */
+        level?: SecurityLevel;
+        /** Minimum acceptable level for verification (default: 0) */
+        minVerificationLevel?: SecurityLevel;
+        /** Verification policy (default: 'strict') */
+        verificationPolicy?: 'strict' | 'permissive';
+        /** Custom PQ key registry */
+        registry?: PQKeyRegistry;
+    };
+    /**
+     * Hybrid key bundle for multi-level cryptography.
+     *
+     * When provided, enables signing at higher security levels (1, 2).
+     * The bundle includes Ed25519 keys and optionally ML-DSA (post-quantum) keys.
+     *
+     * @example
+     * ```tsx
+     * const bundle = createKeyBundle({ includePQ: true })
+     *
+     * <XNetProvider config={{ keyBundle: bundle, ... }}>
+     *   <App />
+     * </XNetProvider>
+     * ```
+     */
+    keyBundle?: HybridKeyBundle;
+    /**
+     * Optional telemetry reporter for hook instrumentation.
+     *
+     * When provided, useQuery and useMutate hooks will report:
+     * - Query timing (first-load latency)
+     * - Cache hit/miss rates
+     * - Mutation success/failure rates
+     * - Subscription churn (mount/unmount frequency)
+     *
+     * Uses a duck-typed interface to avoid circular dependencies with @xnetjs/telemetry.
+     *
+     * @example
+     * ```tsx
+     * import { TelemetryCollector, ConsentManager } from '@xnetjs/telemetry'
+     * const consent = new ConsentManager()
+     * const telemetry = new TelemetryCollector({ consent })
+     *
+     * <XNetProvider config={{ telemetry, ... }}>
+     *   <App />
+     * </XNetProvider>
+     * ```
+     */
+    telemetry?: TelemetryReporter;
+    /**
+     * Optional full-stack tracing reporter (exploration 0190).
+     *
+     * When provided, useQuery/useMutate open a per-call trace and record
+     * main-thread stage spans, assembled into a local waterfall (devtools) and
+     * — when sampled — folded into bucketed performance metrics. Satisfied by
+     * @xnetjs/telemetry's `TraceCollector`. Duck-typed to avoid a circular dep.
+     */
+    tracing?: TracingReporter;
+}
+/**
+ * XNet context value
+ */
+interface XNetContextValue {
+    /** NodeStore for Node operations */
+    nodeStore: NodeStore | null;
+    /** Whether NodeStore is initialized */
+    nodeStoreReady: boolean;
+    /** User identity (if provided) */
+    identity?: Identity;
+    /** Author DID (resolved from config.authorDID or config.identity.did) */
+    authorDID: string | null;
+    /** Background Sync Manager (null if disabled or not yet initialized) */
+    syncManager: SyncManager | null;
+    /** Hub URL (if configured) */
+    hubUrl: string | null;
+    /** Hub connection status */
+    hubStatus: SyncStatus;
+    /** Hub connection (shares SyncManager connection when available) */
+    hubConnection: ConnectionManager | null;
+    /** Hub auth token provider (for HTTP requests) */
+    getHubAuthToken?: () => Promise<string>;
+    /** Billing config (exploration 0187), surfaced to useBilling. */
+    billing?: {
+        apiBase?: string;
+        publishableKey?: string;
+    };
+    /** Encryption key for hub backups */
+    encryptionKey: Uint8Array | null;
+    /** Blob store for content-addressed storage (null if not configured) */
+    blobStore: BlobStoreForSync | null;
+    /** Plugin Registry (null if disabled or not yet initialized) */
+    pluginRegistry: PluginRegistry | null;
+    /** Runtime mode request, fallback behavior, and active runtime status */
+    runtimeStatus: XNetRuntimeStatus;
+    /**
+     * App-wide undo manager — one stack across every node-backed surface
+     * (folders, tasks, databases, chat, settings). Drives Cmd+Z via
+     * undoLatest/redoLatest. Null until the NodeStore is ready (0179).
+     */
+    undoManager: UndoManager | null;
+}
+type XNetInternalContextValue = {
+    authorDID: string | null;
+    signingKey: Uint8Array | null;
+    sync: SyncReplicationConfig | undefined;
+};
+/**
+ * Hook to access the DataBridge.
+ * Returns null while the bridge is initializing.
+ *
+ * @internal Used by useQuery/useMutate hooks - not part of public API yet.
+ */
+declare function useDataBridge(): DataBridge | null;
+/**
+ * XNet provider props
+ */
+interface XNetProviderProps {
+    config: XNetConfig;
+    children: ReactNode;
+}
+/**
+ * XNet provider component
+ *
+ * Initializes NodeStore and provides it to the React tree.
+ */
+declare function XNetProvider({ config, children }: XNetProviderProps): JSX.Element;
+/**
+ * Hook to access XNet context
+ *
+ * @internal Used by useIdentity. Not part of public API.
+ */
+declare function useXNet(): XNetContextValue;
+/**
+ * @internal Internal access to sync credentials and replication policy.
+ */
+declare function useXNetInternal(): XNetInternalContextValue;
+
+export { TracingContext as T, type XNetContextValue as X, useXNet as a, useXNetInternal as b, type XNetInternalContextValue as c, type XNetRuntimeStatus as d, XNetProvider as e, type XNetConfig as f, type XNetProviderProps as g, type XNetRuntimeConfig as h, type XNetRuntimeFallback as i, type XNetRuntimeMode as j, type XNetRuntimePhase as k, type XNetRuntimeWorkerConfig as l, useTracingReporter as m, TRACE_STAGES as n, type TracingReporter as o, type TracingHandle as p, type TracingSpanInput as q, type TracingRootKind as r, type TracingAttributes as s, useDataBridge as u };