@vuer-ai/vuer-rtc 0.0.1

package/src/client/hooks.tsx

@@ -0,0 +1,249 @@
+/**
+ * React Hooks for vuer-rtc
+ *
+ * Usage:
+ * ```tsx
+ * function App() {
+ *   return (
+ *     <GraphProvider sessionId="my-session" onSend={sendToServer}>
+ *       <Scene />
+ *     </GraphProvider>
+ *   );
+ * }
+ *
+ * function Scene() {
+ *   const graph = useGraph();
+ *   const { edit, commit, undo, redo } = useGraphActions();
+ *   // ...
+ * }
+ * ```
+ */
+
+import React, {
+  createContext,
+  useContext,
+  useState,
+  useCallback,
+  useSyncExternalStore,
+  useMemo,
+  type ReactNode,
+} from 'react';
+import type { CRDTMessage, Operation, SceneGraph, SceneNode } from '../operations/OperationTypes.js';
+import { createGraph, type GraphStore, type Snapshot } from './createGraph.js';
+
+// ===========================================
+// Context
+// ===========================================
+
+const GraphContext = createContext<GraphStore | null>(null);
+
+// ===========================================
+// Provider
+// ===========================================
+
+export interface GraphProviderProps {
+  sessionId: string;
+  initialSnapshot?: Snapshot;
+  onSend?: (msg: CRDTMessage) => void;
+  children: ReactNode;
+}
+
+export function GraphProvider({
+  sessionId,
+  initialSnapshot,
+  onSend,
+  children,
+}: GraphProviderProps): React.ReactElement {
+  const [store] = useState(() =>
+    createGraph({
+      sessionId,
+      initialSnapshot,
+      onSend,
+    })
+  );
+
+  return (
+    <GraphContext.Provider value={store}>
+      {children}
+    </GraphContext.Provider>
+  );
+}
+
+// ===========================================
+// Hooks
+// ===========================================
+
+/**
+ * Get the graph store
+ */
+export function useGraphStore(): GraphStore {
+  const store = useContext(GraphContext);
+  if (!store) {
+    throw new Error('useGraphStore must be used within a GraphProvider');
+  }
+  return store;
+}
+
+/**
+ * Get the current graph (reactive)
+ */
+export function useGraph(): SceneGraph {
+  const store = useGraphStore();
+  return useSyncExternalStore(
+    store.subscribe,
+    () => store.getState().graph,
+    () => store.getState().graph
+  );
+}
+
+/**
+ * Get a specific node (reactive)
+ */
+export function useNode(key: string): SceneNode | undefined {
+  const store = useGraphStore();
+  return useSyncExternalStore(
+    store.subscribe,
+    () => store.getState().graph.nodes[key],
+    () => store.getState().graph.nodes[key]
+  );
+}
+
+/**
+ * Get node property (reactive)
+ */
+export function useNodeProperty<T>(key: string, path: string): T | undefined {
+  const store = useGraphStore();
+  return useSyncExternalStore(
+    store.subscribe,
+    () => {
+      const node = store.getState().graph.nodes[key];
+      return node ? (node[path] as T) : undefined;
+    },
+    () => {
+      const node = store.getState().graph.nodes[key];
+      return node ? (node[path] as T) : undefined;
+    }
+  );
+}
+
+/**
+ * Get graph actions
+ */
+export function useGraphActions() {
+  const store = useGraphStore();
+
+  const edit = useCallback(
+    (op: Operation) => {
+      store.edit(op);
+    },
+    [store]
+  );
+
+  const commit = useCallback(
+    (description?: string) => {
+      return store.commit(description);
+    },
+    [store]
+  );
+
+  const undoAction = useCallback(() => {
+    return store.undo();
+  }, [store]);
+
+  const redoAction = useCallback(() => {
+    return store.redo();
+  }, [store]);
+
+  const receive = useCallback(
+    (msg: CRDTMessage) => {
+      store.receive(msg);
+    },
+    [store]
+  );
+
+  const ack = useCallback(
+    (msgId: string) => {
+      store.ack(msgId);
+    },
+    [store]
+  );
+
+  const compact = useCallback(() => {
+    store.compact();
+  }, [store]);
+
+  return useMemo(
+    () => ({
+      edit,
+      commit,
+      undo: undoAction,
+      redo: redoAction,
+      receive,
+      ack,
+      compact,
+    }),
+    [edit, commit, undoAction, redoAction, receive, ack, compact]
+  );
+}
+
+/**
+ * Hook for drag operations
+ *
+ * Usage:
+ * ```tsx
+ * const { onDragStart, onDrag, onDragEnd, isDragging } = useDrag('cube', 'position');
+ * ```
+ */
+export function useDrag(nodeKey: string, path: string) {
+  const { edit, commit } = useGraphActions();
+  const [isDragging, setIsDragging] = useState(false);
+
+  const onDragStart = useCallback(() => {
+    setIsDragging(true);
+  }, []);
+
+  const onDrag = useCallback(
+    (delta: [number, number, number]) => {
+      edit({
+        otype: 'vector3.add',
+        key: nodeKey,
+        path,
+        value: delta,
+      });
+    },
+    [edit, nodeKey, path]
+  );
+
+  const onDragEnd = useCallback(() => {
+    setIsDragging(false);
+    commit(`Move ${nodeKey}`);
+  }, [commit, nodeKey]);
+
+  return useMemo(
+    () => ({ isDragging, onDragStart, onDrag, onDragEnd }),
+    [isDragging, onDragStart, onDrag, onDragEnd]
+  );
+}
+
+/**
+ * Hook for undo/redo keyboard shortcuts
+ */
+export function useUndoRedoShortcuts() {
+  const { undo, redo } = useGraphActions();
+
+  React.useEffect(() => {
+    const handleKeyDown = (e: KeyboardEvent) => {
+      if ((e.metaKey || e.ctrlKey) && e.key === 'z') {
+        e.preventDefault();
+        if (e.shiftKey) {
+          redo();
+        } else {
+          undo();
+        }
+      }
+    };
+
+    window.addEventListener('keydown', handleKeyDown);
+    return () => window.removeEventListener('keydown', handleKeyDown);
+  }, [undo, redo]);
+}

package/src/client/index.ts

@@ -0,0 +1,35 @@
+/**
+ * Client module exports
+ */
+
+// Types
+export type {
+  ClientState,
+  JournalEntry,
+  EditBuffer,
+  Snapshot,
+  CreateGraphOptions,
+  GraphStore,
+} from './types.js';
+
+// Factory
+export { createGraph, createGraphFromServer } from './createGraph.js';
+
+// Actions (for advanced usage)
+export {
+  createInitialState,
+  rebuildGraph,
+  onEdit,
+  commitEdits,
+  cancelEdits,
+  onServerAck,
+  onRemoteMessage,
+  undo,
+  redo,
+  compact,
+  initFromServer,
+  generateUUID,
+} from './actions.js';
+
+// Edit buffer utilities
+export { isAdditiveOp, mergeValues, EditBufferImpl } from './EditBuffer.js';

package/src/client/types.ts

@@ -0,0 +1,94 @@
+/**
+ * Client State Types
+ *
+ * Defines the state model for CRDT clients with:
+ * - graph: current computed state
+ * - journal: committed messages with ack and deletedAt
+ * - edits: uncommitted operations (edit buffer)
+ * - snapshot: checkpoint for fast replay
+ */
+
+import type { CRDTMessage, Operation, SceneGraph } from '../operations/OperationTypes.js';
+import type { VectorClock } from '../state/VectorClock.js';
+
+/**
+ * Journal entry - a committed message with metadata
+ */
+export interface JournalEntry {
+  msg: CRDTMessage;
+  ack: boolean;           // Has server acknowledged?
+  deletedAt?: number;     // If set, message is "undone"
+}
+
+/**
+ * Edit buffer - uncommitted operations
+ */
+export interface EditBuffer {
+  ops: Operation[];       // Pending operations (merged)
+  startGraph: SceneGraph | null; // Graph state when edits started
+}
+
+/**
+ * Snapshot - checkpoint for fast replay
+ */
+export interface Snapshot {
+  graph: SceneGraph;
+  vectorClock: VectorClock;
+  journalIndex: number;   // How many entries are baked in
+}
+
+/**
+ * Client state - complete client-side state
+ */
+export interface ClientState {
+  // Current computed value (derived from snapshot + journal + edits)
+  graph: SceneGraph;
+
+  // Committed edits (sent or pending acknowledgement)
+  journal: JournalEntry[];
+
+  // Uncommitted operations (in-progress edits)
+  edits: EditBuffer;
+
+  // Checkpoint for fast replay
+  snapshot: Snapshot;
+
+  // Clocks
+  lamportTime: number;
+  vectorClock: VectorClock;
+  sessionId: string;
+}
+
+/**
+ * Options for creating a graph store
+ */
+export interface CreateGraphOptions {
+  sessionId: string;
+  initialSnapshot?: Snapshot;
+  onSend?: (msg: CRDTMessage) => void;
+  onStateChange?: (state: ClientState) => void;
+}
+
+/**
+ * Graph store - the public API
+ */
+export interface GraphStore {
+  // State access
+  getState: () => ClientState;
+  subscribe: (listener: () => void) => () => void;
+
+  // Edit operations
+  edit: (op: Operation) => void;
+  commit: (description?: string) => CRDTMessage | null;
+
+  // Server communication
+  receive: (msg: CRDTMessage) => void;
+  ack: (msgId: string) => void;
+
+  // Undo/redo
+  undo: () => { msg: CRDTMessage | null };
+  redo: () => { msg: CRDTMessage | null };
+
+  // Maintenance
+  compact: () => void;
+}

package/src/hooks.ts

@@ -0,0 +1,20 @@
+/**
+ * React hooks for @vuer-ai/vuer-rtc
+ *
+ * Import from '@vuer-ai/vuer-rtc/hooks'
+ */
+
+export {
+  GraphProvider,
+  useGraphStore,
+  useGraph,
+  useNode,
+  useNodeProperty,
+  useGraphActions,
+  useDrag,
+  useUndoRedoShortcuts,
+  type GraphProviderProps,
+} from './client/hooks.js';
+
+// Re-export types
+export type { GraphStore, ClientState, Snapshot } from './client/types.js';

package/src/index.ts

@@ -0,0 +1,14 @@
+/**
+ * @vuer-ai/vuer-rtc
+ *
+ * CRDT-based real-time collaborative data structures
+ */
+
+// Operations
+export * from './operations/index.js';
+
+// State utilities
+export * from './state/index.js';
+
+// Client (state management, createGraph, etc.)
+export * from './client/index.js';