@xnetjs/react 0.0.2 → 0.1.0

package/dist/{instrumentation-Cn94kn8-.d.ts → instrumentation-CpIuG2y5.d.ts}

@@ -1,6 +1,35 @@
 import * as react from 'react';
+import { QueryCompletenessMetadata, QueryStalenessMetadata, QueryVerificationMetadata, QueryStreamMetadata } from '@xnetjs/data-bridge';
 import * as Y from 'yjs';
 
+interface QueryTrackerPlanInfo {
+    strategy?: string;
+    candidateNodeCount?: number;
+    hydratedNodeCount?: number;
+    returnedNodeCount?: number;
+    durationMs?: number;
+    descriptorHash?: string;
+    candidateAccelerators?: string[];
+    materializedViewId?: string;
+    materializedCacheHit?: boolean;
+    materializedRefreshReason?: string;
+}
+interface QueryTrackerMaterializedInfo {
+    viewId: string;
+    cacheHit: boolean;
+    generatedAt: number;
+    invalidatedAt?: number;
+    rowCount: number;
+}
+interface QueryTrackerUpdateMetadata {
+    source?: string;
+    plan?: QueryTrackerPlanInfo | null;
+    materialized?: QueryTrackerMaterializedInfo | null;
+    completeness?: QueryCompletenessMetadata | null;
+    staleness?: QueryStalenessMetadata | null;
+    verification?: QueryVerificationMetadata | null;
+    stream?: QueryStreamMetadata | null;
+}
 /**
  * Query tracker interface (implemented by @xnetjs/devtools QueryTracker)
  */
@@ -10,10 +39,12 @@ interface QueryTrackerLike {
         schemaId: string;
         mode: 'list' | 'single' | 'filtered' | 'document';
         filter?: Record<string, unknown>;
+        descriptorKey?: string;
         nodeId?: string;
         callerInfo?: string;
     }): void;
-    recordUpdate(id: string, resultCount: number, renderTime: number): void;
+    recordUpdate(id: string, resultCount: number, renderTime: number, metadata?: QueryTrackerUpdateMetadata): void;
+    recordStreamEvent?(id: string, stream: QueryStreamMetadata, resultCount: number, metadata?: Pick<QueryTrackerUpdateMetadata, 'source'>): void;
     recordError(id: string, error: string): void;
     unregister(id: string): void;
 }

package/dist/internal.d.ts

@@ -1,31 +1,41 @@
-import { NodeStore } from '@xnetjs/data';
-export { I as InstrumentationContext, a as InstrumentationContextValue, Q as QueryTrackerLike, Y as YDocRegistryLike, u as useInstrumentation } from './instrumentation-Cn94kn8-.js';
+export { N as NodeStoreContextValue, u as useNodeStore } from './useNodeStore-DTCSBF51.js';
+import { DID } from '@xnetjs/core';
+import { NodeId } from '@xnetjs/data';
+import { UndoManagerOptions } from '@xnetjs/history';
+export { I as InstrumentationContext, a as InstrumentationContextValue, Q as QueryTrackerLike, Y as YDocRegistryLike, u as useInstrumentation } from './instrumentation-CpIuG2y5.js';
+export { X as XNetContextValue, c as XNetInternalContextValue, d as XNetRuntimeStatus, u as useDataBridge, a as useXNet, b as useXNetInternal } from './context-CFu9i136.js';
 import 'react';
+import '@xnetjs/data-bridge';
 import 'yjs';
+import '@xnetjs/runtime';
+import '@xnetjs/crypto';
+import '@xnetjs/identity';
+import '@xnetjs/sync';
+import '@xnetjs/plugins';
+import './telemetry-context-B7r6H1KW.js';
 
 /**
- * useNodeStore hook - internal access to the NodeStore from XNetProvider context.
+ * useUndoScope - Internal hook for scoped undo/redo across multiple nodes.
  *
- * This is NOT part of the public API. Use useQuery/useMutate/useNode instead.
- * Only @xnetjs/devtools uses this via the @xnetjs/react/internal subpath.
+ * Wraps UndoManager's scoped helpers so app surfaces can treat a composite
+ * model like "database node plus visible rows" as one undo domain.
  */
 
-/**
- * NodeStore context value
- */
-interface NodeStoreContextValue {
-    /** The NodeStore instance */
-    store: NodeStore | null;
-    /** Whether the store is initialized and ready */
-    isReady: boolean;
-    /** Any initialization error */
-    error: Error | null;
+interface UseUndoScopeOptions {
+    /** The local user's DID. When absent, undo is disabled until identity is ready. */
+    localDID: DID | null;
+    /** UndoManager configuration overrides */
+    options?: Partial<UndoManagerOptions>;
 }
-/**
- * Hook to access the NodeStore from XNetProvider context.
- *
- * @internal Not part of the public API.
- */
-declare function useNodeStore(): NodeStoreContextValue;
+interface UseUndoScopeResult {
+    undo: () => Promise<boolean>;
+    redo: () => Promise<boolean>;
+    canUndo: boolean;
+    canRedo: boolean;
+    undoCount: number;
+    redoCount: number;
+    clear: () => void;
+}
+declare function useUndoScope(nodeIds: NodeId[], opts: UseUndoScopeOptions): UseUndoScopeResult;
 
-export { type NodeStoreContextValue, useNodeStore };
+export { type UseUndoScopeOptions, type UseUndoScopeResult, useUndoScope };

package/dist/internal.js

@@ -1,10 +1,22 @@
+import {
+  useUndoScope
+} from "./chunk-EJ5RW5GI.js";
 import {
   InstrumentationContext,
-  useInstrumentation,
-  useNodeStore
-} from "./chunk-CWHCGYDW.js";
+  useInstrumentation
+} from "./chunk-JCOFKBOB.js";
+import {
+  useDataBridge,
+  useNodeStore,
+  useXNet,
+  useXNetInternal
+} from "./chunk-IHTMVTTE.js";
 export {
   InstrumentationContext,
+  useDataBridge,
   useInstrumentation,
-  useNodeStore
+  useNodeStore,
+  useUndoScope,
+  useXNet,
+  useXNetInternal
 };

package/dist/telemetry-context-B7r6H1KW.d.ts

@@ -0,0 +1,35 @@
+import * as react from 'react';
+
+/**
+ * Telemetry context for @xnetjs/react
+ *
+ * Provides an optional duck-typed TelemetryReporter to the React tree.
+ * When present, hooks report performance timing, usage counts, and errors.
+ *
+ * Uses the same duck-typed interface pattern as other xNet packages to
+ * avoid circular dependencies with @xnetjs/telemetry.
+ */
+/**
+ * Duck-typed interface for telemetry reporting.
+ * Satisfied by @xnetjs/telemetry's TelemetryCollector or any compatible object.
+ *
+ * @example
+ * ```ts
+ * import { TelemetryCollector } from '@xnetjs/telemetry'
+ * const telemetry = new TelemetryCollector({ consent })
+ * // Pass to XNetProvider via config.telemetry
+ * ```
+ */
+interface TelemetryReporter {
+    reportPerformance(metricName: string, durationMs: number): void;
+    reportUsage(metricName: string, count: number): void;
+    reportCrash(error: Error, context?: Record<string, unknown>): void;
+}
+declare const TelemetryContext: react.Context<TelemetryReporter | null>;
+/**
+ * Hook to access the telemetry reporter (null if no telemetry configured).
+ * @internal Used by useQuery/useMutate - not part of public API.
+ */
+declare function useTelemetryReporter(): TelemetryReporter | null;
+
+export { type TelemetryReporter as T, TelemetryContext as a, useTelemetryReporter as u };

package/dist/useNodeStore-DTCSBF51.d.ts

@@ -0,0 +1,28 @@
+import { NodeStore } from '@xnetjs/data';
+
+/**
+ * useNodeStore hook - internal access to the NodeStore from XNetProvider context.
+ *
+ * This is NOT part of the public API. Use useQuery/useMutate/useNode instead.
+ * Only @xnetjs/devtools uses this via the @xnetjs/react/internal subpath.
+ */
+
+/**
+ * NodeStore context value
+ */
+interface NodeStoreContextValue {
+    /** The NodeStore instance */
+    store: NodeStore | null;
+    /** Whether the store is initialized and ready */
+    isReady: boolean;
+    /** Any initialization error */
+    error: Error | null;
+}
+/**
+ * Hook to access the NodeStore from XNetProvider context.
+ *
+ * @internal Not part of the public API.
+ */
+declare function useNodeStore(): NodeStoreContextValue;
+
+export { type NodeStoreContextValue as N, useNodeStore as u };

package/dist/useQuery-D7ajycrc.d.ts

@@ -0,0 +1,302 @@
+import { PropertyBuilder, SchemaIRI, MigrationInfo, InferCreateProps, NodeState, MigratedNodeState, DefinedSchema } from '@xnetjs/data';
+import { QuerySource, QueryMaterializedMetadata, QueryCompletenessMetadata, QueryStalenessMetadata, QueryVerificationMetadata, QueryStreamMetadata, QueryPageInfo, QueryPageOptions, QuerySpatialFilter, QuerySearchFilter, QueryMaterializedViewOptions, QueryExecutionMode, QuerySourcePreference } from '@xnetjs/data-bridge';
+import { DID } from '@xnetjs/core';
+
+/**
+ * FlatNode utilities - Flatten NodeState properties to top level
+ *
+ * This module provides type-safe flattening of Node properties so developers
+ * can access `node.title` instead of `node.properties.title`.
+ */
+
+/**
+ * Base node fields (always present on any node)
+ */
+interface NodeBase {
+    /** Unique node identifier */
+    id: string;
+    /** Schema IRI this node conforms to */
+    schemaId: SchemaIRI;
+    /** Creation timestamp */
+    createdAt: number;
+    /** Creator's DID */
+    createdBy: DID;
+    /** Last update timestamp */
+    updatedAt: number;
+    /** Last updater's DID */
+    updatedBy: DID;
+    /** Whether node is soft-deleted */
+    deleted: boolean;
+    /**
+     * True if this node's schema is not registered/known to the current app version.
+     * The node data is still accessible but may not have proper type information.
+     * UI should render a generic "Unknown data type" component for these nodes.
+     */
+    _unknownSchema?: boolean;
+    /**
+     * Properties from future schema versions that aren't known to the current schema.
+     * Preserved for forward compatibility - can be displayed in a "raw data" view.
+     */
+    _unknown?: Record<string, unknown>;
+    /**
+     * The schema version that last wrote to this node.
+     * Useful for detecting when migrations might be needed.
+     */
+    _schemaVersion?: string;
+    /**
+     * The original schema IRI this node was migrated from.
+     * Only present if the node was automatically migrated on read.
+     */
+    _migratedFrom?: SchemaIRI;
+    /**
+     * Full migration info if the node was migrated.
+     * Includes lossless flag and any warnings about data loss.
+     */
+    _migrationInfo?: MigrationInfo;
+}
+/**
+ * A flattened node with properties at the top level.
+ *
+ * Instead of `node.properties.title`, access `node.title` directly.
+ * All property types are correctly inferred from the schema.
+ *
+ * @example
+ * ```tsx
+ * const { data } = useQuery(TaskSchema, id)
+ * // data is FlatNode<typeof TaskSchema._properties>
+ *
+ * console.log(data.title)   // string - correctly typed!
+ * console.log(data.status)  // 'todo' | 'done' - union type!
+ * ```
+ */
+type FlatNode<P extends Record<string, PropertyBuilder>> = NodeBase & InferCreateProps<P>;
+/**
+ * Options for flattenNode function
+ */
+interface FlattenNodeOptions {
+    /**
+     * Mark this node as having an unknown schema.
+     * This happens when the node's schemaId is not registered in the current app version.
+     */
+    unknownSchema?: boolean;
+    /**
+     * Migration info if the node was migrated from a different schema version.
+     */
+    migrationInfo?: MigrationInfo;
+}
+/**
+ * Flatten a NodeState by spreading properties to top level.
+ *
+ * @param node - The NodeState with nested properties
+ * @param options - Optional settings for handling unknown schemas
+ * @returns A new object with properties flattened to top level
+ *
+ * @example
+ * ```ts
+ * const nodeState = {
+ *   id: '123',
+ *   schemaId: 'xnet://xnet.fyi/Task',
+ *   properties: { title: 'My Task', status: 'todo' },
+ *   // ...
+ * }
+ *
+ * const flat = flattenNode(nodeState)
+ * // { id: '123', schemaId: '...', title: 'My Task', status: 'todo', ... }
+ * ```
+ */
+declare function flattenNode<P extends Record<string, PropertyBuilder>>(node: NodeState | MigratedNodeState, options?: FlattenNodeOptions): FlatNode<P>;
+/**
+ * Flatten an array of NodeState objects.
+ */
+declare function flattenNodes<P extends Record<string, PropertyBuilder>>(nodes: (NodeState | MigratedNodeState)[], options?: FlattenNodeOptions): FlatNode<P>[];
+/**
+ * Create a FlatNode with unknown schema flag.
+ * Use this when displaying nodes whose schema is not registered.
+ */
+declare function flattenUnknownSchemaNode(node: NodeState): FlatNode<Record<string, PropertyBuilder>>;
+/**
+ * Create FlatNodes from an array, marking those with unknown schemas.
+ *
+ * @param nodes - Array of NodeState objects
+ * @param isSchemaKnown - Function to check if a schema is registered
+ * @returns Array of FlatNodes with _unknownSchema set appropriately
+ */
+declare function flattenNodesWithSchemaCheck<P extends Record<string, PropertyBuilder>>(nodes: NodeState[], isSchemaKnown: (schemaId: string) => boolean): FlatNode<P>[];
+
+/**
+ * Shared derivations from bridge query metadata used by the read hooks
+ * (useQuery, useSavedView, useInfiniteQuery).
+ */
+
+interface QueryPlanSummary {
+    strategy?: string;
+    candidateNodeCount?: number;
+    hydratedNodeCount?: number;
+    returnedNodeCount?: number;
+    durationMs?: number;
+    descriptorHash?: string;
+    candidateAccelerators?: string[];
+    materializedViewId?: string;
+    materializedCacheHit?: boolean;
+    materializedRefreshReason?: string;
+}
+
+/**
+ * useQuery - Unified read hook for Nodes via DataBridge
+ *
+ * A single hook for all read operations:
+ * - List all nodes of a schema
+ * - Get a single node by ID
+ * - Query with filters
+ *
+ * Returns FlatNode with properties at top level for ergonomic access.
+ *
+ * Uses DataBridge for off-main-thread data access. The bridge handles
+ * caching and provides useSyncExternalStore-compatible subscriptions.
+ *
+ * @example
+ * ```tsx
+ * // List all tasks
+ * const { data: tasks } = useQuery(TaskSchema)
+ * tasks.forEach(task => console.log(task.title))  // Direct access!
+ *
+ * // Get single task by ID
+ * const { data: task } = useQuery(TaskSchema, taskId)
+ * console.log(task?.status)  // Typed correctly!
+ *
+ * // Query with filters
+ * const { data: urgent } = useQuery(TaskSchema, {
+ *   where: { status: 'urgent' },
+ *   orderBy: { createdAt: 'desc' }
+ * })
+ * ```
+ */
+
+/**
+ * Sort direction
+ */
+type SortDirection = 'asc' | 'desc';
+/**
+ * System fields that can be used for ordering
+ */
+type SystemOrderField = 'createdAt' | 'updatedAt';
+/**
+ * Query filter options
+ */
+interface QueryFilter<P extends Record<string, PropertyBuilder> = Record<string, PropertyBuilder>> {
+    /** Filter conditions (property: value) */
+    where?: Partial<InferCreateProps<P>>;
+    /** Include soft-deleted nodes */
+    includeDeleted?: boolean;
+    /** Sort by property or system field (createdAt, updatedAt) */
+    orderBy?: {
+        [K in keyof InferCreateProps<P> | SystemOrderField]?: SortDirection;
+    };
+    /** Limit results */
+    limit?: number;
+    /** Offset for pagination */
+    offset?: number;
+    /** Recommended pagination option. `page.first` maps to the current bounded read limit. */
+    page?: QueryPageOptions;
+    /** Spatial filtering for viewport windows or radius-based 2D queries */
+    spatial?: QuerySpatialFilter;
+    /** Tokenized full-text search over searchable node fields */
+    search?: string | QuerySearchFilter;
+    /** Stable view cache key for storage-backed materialized result sets */
+    materializedView?: string | QueryMaterializedViewOptions;
+    /** Future execution mode hint. Current runtimes execute locally. */
+    mode?: QueryExecutionMode;
+    /** Future source preference hint for hub or federated reads. */
+    source?: QuerySourcePreference;
+    /** Disable bridge subscription while preserving a typed empty result. */
+    enabled?: boolean;
+}
+type QueryStatus = 'loading' | 'success' | 'error';
+
+interface QueryBaseResult {
+    /** Query lifecycle status */
+    status: QueryStatus;
+    /** Whether currently loading */
+    loading: boolean;
+    /** Alias for loading */
+    isLoading: boolean;
+    /** Whether a fetch/reload is currently active */
+    isFetching: boolean;
+    /** Whether the query is backed by a live subscription */
+    isLive: boolean;
+    /** Source that produced the current snapshot */
+    source: QuerySource;
+    /** Any error that occurred */
+    error: Error | null;
+    /** Reload the query */
+    reload: () => void;
+    /** Optional bridge/runtime plan summary */
+    plan: QueryPlanSummary | null;
+    /** Optional materialized view metadata */
+    materialized: QueryMaterializedMetadata | null;
+    /** Remote/federated completeness metadata when available */
+    completeness: QueryCompletenessMetadata | null;
+    /** Remote/federated staleness metadata when available */
+    staleness: QueryStalenessMetadata | null;
+    /** Remote/federated verification metadata when available */
+    verification: QueryVerificationMetadata | null;
+    /** Streaming lifecycle metadata when a live or stream query is active */
+    stream: QueryStreamMetadata | null;
+}
+/**
+ * Migration warning info
+ */
+interface MigrationWarning {
+    /** The node ID that was migrated */
+    nodeId: string;
+    /** The original schema IRI */
+    from: string;
+    /** The target schema IRI */
+    to: string;
+    /** Warning messages about potential data loss */
+    warnings: string[];
+}
+/**
+ * Result when querying a list of nodes
+ */
+interface QueryListResult<P extends Record<string, PropertyBuilder>> extends QueryBaseResult {
+    /** The queried nodes (flattened - access properties directly) */
+    data: FlatNode<P>[];
+    /** Pagination and count metadata */
+    pageInfo: QueryPageInfo;
+    /** Total matching count when known. Null means unavailable or intentionally not counted. */
+    totalCount: number | null;
+    /** Whether more results may be available. Exact when totalCount is known. */
+    hasMore: boolean;
+    /**
+     * Migration warnings for nodes that were migrated from different schema versions.
+     * Only populated if nodes required migration and the migration was lossy.
+     */
+    migrationWarnings: MigrationWarning[];
+}
+/**
+ * Result when querying a single node
+ */
+interface QuerySingleResult<P extends Record<string, PropertyBuilder>> extends QueryBaseResult {
+    /** The queried node (flattened - access properties directly), null if not found */
+    data: FlatNode<P> | null;
+    /**
+     * Migration warnings if the node was migrated from a different schema version.
+     * Only populated if the node required migration and the migration was lossy.
+     */
+    migrationWarnings: MigrationWarning[];
+}
+/**
+ * Query all nodes of a schema
+ */
+declare function useQuery<P extends Record<string, PropertyBuilder>>(schema: DefinedSchema<P>): QueryListResult<P>;
+/**
+ * Query a single node by ID
+ */
+declare function useQuery<P extends Record<string, PropertyBuilder>>(schema: DefinedSchema<P>, id: string): QuerySingleResult<P>;
+/**
+ * Query nodes with filters
+ */
+declare function useQuery<P extends Record<string, PropertyBuilder>>(schema: DefinedSchema<P>, filter: QueryFilter<P>): QueryListResult<P>;
+
+export { type FlatNode as F, type MigrationWarning as M, type QueryFilter as Q, type SortDirection as S, type QueryStatus as a, type QueryPlanSummary as b, type QueryListResult as c, type QuerySingleResult as d, flattenNodes as e, flattenNode as f, flattenUnknownSchemaNode as g, flattenNodesWithSchemaCheck as h, type FlattenNodeOptions as i, type QueryBaseResult as j, useQuery as u };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xnetjs/react",
-  "version": "0.0.2",
+  "version": "0.1.0",
   "license": "MIT",
   "repository": {
     "type": "git",
@@ -14,6 +14,18 @@
       "import": "./dist/index.js",
       "types": "./dist/index.d.ts"
     },
+    "./core": {
+      "import": "./dist/core.js",
+      "types": "./dist/core.d.ts"
+    },
+    "./database": {
+      "import": "./dist/database.js",
+      "types": "./dist/database.d.ts"
+    },
+    "./experimental": {
+      "import": "./dist/experimental.js",
+      "types": "./dist/experimental.d.ts"
+    },
     "./internal": {
       "import": "./dist/internal.js",
       "types": "./dist/internal.d.ts"
@@ -29,15 +41,20 @@
     "provenance": true
   },
   "dependencies": {
+    "@tanstack/react-virtual": "^3.13.18",
+    "lucide-react": "^0.453.0",
     "y-protocols": "^1.0.6",
     "yjs": "^13.6.24",
-    "@xnetjs/core": "0.0.2",
-    "@xnetjs/crypto": "0.0.2",
-    "@xnetjs/data": "0.0.2",
-    "@xnetjs/data-bridge": "0.0.2",
-    "@xnetjs/history": "0.0.2",
-    "@xnetjs/identity": "0.0.2",
-    "@xnetjs/plugins": "0.0.2"
+    "@xnetjs/billing": "0.0.2",
+    "@xnetjs/core": "0.1.0",
+    "@xnetjs/crypto": "0.1.0",
+    "@xnetjs/data": "0.1.0",
+    "@xnetjs/data-bridge": "0.1.0",
+    "@xnetjs/history": "0.1.0",
+    "@xnetjs/identity": "0.1.0",
+    "@xnetjs/plugins": "0.1.0",
+    "@xnetjs/runtime": "0.1.0",
+    "@xnetjs/sync": "0.1.0"
   },
   "peerDependencies": {
     "react": "^18.0.0 || ^19.0.0"
@@ -50,10 +67,11 @@
     "react-dom": "^18.3.1",
     "tsup": "^8.0.0",
     "typescript": "^5.4.0",
-    "vitest": "^4.0.0"
+    "vitest": "^4.0.0",
+    "y-webrtc": "^10.3.0"
   },
   "scripts": {
-    "build": "tsup src/index.ts src/internal.ts --format esm --dts --external react",
+    "build": "tsup src/index.ts src/core.ts src/database.ts src/experimental.ts src/internal.ts --format esm --dts --external react",
     "test": "vitest run",
     "typecheck": "tsc --noEmit",
     "clean": "rm -rf dist"