@stuly/anode-react 0.1.0 → 0.1.2

package/README.md

@@ -1,7 +1,6 @@
-# anode-react
+# @stuly/anode-react
 
-React bindings and components for Anode, providing a declarative layer over
-the headless core engine.
+React bindings and components for Anode, providing a declarative layer over the headless core engine.
 
 ## Installation
 
@@ -9,14 +8,26 @@ the headless core engine.
 npm install @stuly/anode-react @stuly/anode
 ```
 
-## Components & Hooks
+## Quick Start
 
-- **World:** The primary canvas component for rendering the node graph.
-- **Socket:** A component for rendering connection points within nodes.
-- **Hooks:**
-  - `useAnode()`: Access the core engine.
-  - `useSocketValue()`: Subscribe to reactive data flow.
-  - `useVisibleNodes()`: Optimized spatial culling.
-  - `useEntitySockets()`: Reactive socket management.
+```tsx
+import { AnodeProvider, World } from '@stuly/anode-react';
 
-For detailed documentation and usage examples, see the [root README](../../README.md).
+export default function App() {
+  return (
+    <AnodeProvider>
+      <World />
+    </AnodeProvider>
+  );
+}
+```
+
+## Key Components & Hooks
+
+- **`World`**: Primary canvas component.
+- **`AnodeProvider`**: Context provider for the engine.
+- **`useAnode()`**: Access the core engine instance.
+- **`useSocketValue()`**: Subscribe to reactive data flow.
+- **`useVisibleNodes()`**: Optimized spatial culling for large graphs.
+
+For detailed documentation, usage examples, and core principles, see the [Full README](https://github.com/stulyproject/anode?tab=readme-ov-file).

package/dist/context.d.ts

@@ -7,7 +7,18 @@ interface Viewport {
   y: number;
   k: number;
 }
+/**
+ * Accesses the underlying headless Anode engine instance.
+ *
+ * @returns The `Context` instance for direct graph manipulation.
+ */
 declare const useAnode: () => Context<any>;
+/**
+ * Accesses the current viewport transformation (pan/zoom) and coordinate
+ * conversion utilities.
+ *
+ * @returns An object containing the current `viewport` and functions to update it.
+ */
 declare const useViewport: () => {
   viewport: Viewport;
   setViewport: (v: Viewport) => void;
@@ -16,6 +27,11 @@ declare const useViewport: () => {
     y: number;
   };
 };
+/**
+ * Accesses the current selection state for nodes and links.
+ *
+ * @returns An object containing the `selection` sets and a `setSelection` updater.
+ */
 declare const useSelection: () => {
   selection: {
     nodes: Set<number>;
@@ -26,6 +42,20 @@ declare const useSelection: () => {
     links: Set<number>;
   }>>;
 };
+/**
+ * The root provider for any Anode React application.
+ * Wraps the internal headless engine and provides reactive state for
+ * viewport and selection.
+ *
+ * **Usage:**
+ * ```tsx
+ * <AnodeProvider>
+ *   <World>
+ *     <Background />
+ *   </World>
+ * </AnodeProvider>
+ * ```
+ */
 declare const AnodeProvider: React.FC<{
   children: React.ReactNode;
   context?: Context;

package/dist/context.js

@@ -3,12 +3,27 @@ import { Context } from "@stuly/anode";
 import { jsx } from "react/jsx-runtime";
 
 //#region src/context.tsx
+/**
+* Internal context for Anode's React state, including the engine instance,
+* viewport transformation, and selection state.
+*/
 const AnodeReactContext = createContext(null);
+/**
+* Accesses the underlying headless Anode engine instance.
+*
+* @returns The `Context` instance for direct graph manipulation.
+*/
 const useAnode = () => {
 	const value = useContext(AnodeReactContext);
 	if (!value) throw new Error("useAnode must be used within an AnodeProvider");
 	return value.ctx;
 };
+/**
+* Accesses the current viewport transformation (pan/zoom) and coordinate
+* conversion utilities.
+*
+* @returns An object containing the current `viewport` and functions to update it.
+*/
 const useViewport = () => {
 	const value = useContext(AnodeReactContext);
 	if (!value) throw new Error("useViewport must be used within an AnodeProvider");
@@ -18,6 +33,11 @@ const useViewport = () => {
 		screenToWorld: value.screenToWorld
 	};
 };
+/**
+* Accesses the current selection state for nodes and links.
+*
+* @returns An object containing the `selection` sets and a `setSelection` updater.
+*/
 const useSelection = () => {
 	const value = useContext(AnodeReactContext);
 	if (!value) throw new Error("useSelection must be used within an AnodeProvider");
@@ -26,6 +46,20 @@ const useSelection = () => {
 		setSelection: value.setSelection
 	};
 };
+/**
+* The root provider for any Anode React application.
+* Wraps the internal headless engine and provides reactive state for
+* viewport and selection.
+*
+* **Usage:**
+* ```tsx
+* <AnodeProvider>
+*   <World>
+*     <Background />
+*   </World>
+* </AnodeProvider>
+* ```
+*/
 const AnodeProvider = ({ children, context }) => {
 	const [ctx] = useState(() => context ?? new Context());
 	const [viewport, setViewport] = useState({

package/dist/elements/Background.d.ts

@@ -7,6 +7,17 @@ interface BackgroundProps {
   gap?: number;
   pattern?: 'dots' | 'lines';
 }
+/**
+ * A decorative grid or dot pattern overlay for the canvas.
+ * Automatically pans and scales with the viewport.
+ *
+ * **Usage:**
+ * ```tsx
+ * <World>
+ *   <Background pattern="dots" color="#ccc" />
+ * </World>
+ * ```
+ */
 declare const Background: React.FC<BackgroundProps>;
 //#endregion
 export { Background };

package/dist/elements/Background.js

@@ -3,6 +3,17 @@ import React from "react";
 import { jsx } from "react/jsx-runtime";
 
 //#region src/elements/Background.tsx
+/**
+* A decorative grid or dot pattern overlay for the canvas.
+* Automatically pans and scales with the viewport.
+*
+* **Usage:**
+* ```tsx
+* <World>
+*   <Background pattern="dots" color="#ccc" />
+* </World>
+* ```
+*/
 const Background = ({ color = "#cbd5e1", size = 1, gap = 20, pattern = "dots" }) => {
 	const { viewport } = useViewport();
 	const scaledGap = gap * viewport.k;

package/dist/elements/Controls.d.ts

@@ -1,6 +1,17 @@
 import React from "react";
 
 //#region src/elements/Controls.d.ts
+/**
+ * A floating UI control panel providing standard canvas interactions
+ * like zooming in/out and fitting all nodes into the current view.
+ *
+ * **Usage:**
+ * ```tsx
+ * <World>
+ *   <Controls />
+ * </World>
+ * ```
+ */
 declare const Controls: React.FC<{
   style?: React.CSSProperties;
 }>;

package/dist/elements/Controls.js

@@ -3,6 +3,17 @@ import React from "react";
 import { jsx, jsxs } from "react/jsx-runtime";
 
 //#region src/elements/Controls.tsx
+/**
+* A floating UI control panel providing standard canvas interactions
+* like zooming in/out and fitting all nodes into the current view.
+*
+* **Usage:**
+* ```tsx
+* <World>
+*   <Controls />
+* </World>
+* ```
+*/
 const Controls = ({ style }) => {
 	const { viewport, setViewport } = useViewport();
 	const ctx = useAnode();

package/dist/elements/Group.js

@@ -1,10 +1,10 @@
 import { useAnode, useViewport } from "../context.js";
 import React, { useState } from "react";
-import { Rect, Vec2 } from "@stuly/anode";
+import { Group, Rect, Vec2 } from "@stuly/anode";
 import { jsx, jsxs } from "react/jsx-runtime";
 
 //#region src/elements/Group.tsx
-const Group = ({ id, children }) => {
+const Group$1 = ({ id, children }) => {
 	const ctx = useAnode();
 	const { viewport } = useViewport();
 	const group = ctx.groups.get(id);
@@ -83,4 +83,4 @@ const Group = ({ id, children }) => {
 };
 
 //#endregion
-export { Group };
+export { Group$1 as Group };

package/dist/elements/MiniMap.d.ts

@@ -1,6 +1,17 @@
 import React from "react";
 
 //#region src/elements/MiniMap.d.ts
+/**
+ * A simplified bird's-eye view of the entire graph, providing
+ * context and a visual indicator of the current viewport.
+ *
+ * **Usage:**
+ * ```tsx
+ * <World>
+ *   <MiniMap width={200} height={150} />
+ * </World>
+ * ```
+ */
 declare const MiniMap: React.FC<{
   width?: number;
   height?: number;

package/dist/elements/MiniMap.js

@@ -3,6 +3,17 @@ import React, { useMemo } from "react";
 import { jsx, jsxs } from "react/jsx-runtime";
 
 //#region src/elements/MiniMap.tsx
+/**
+* A simplified bird's-eye view of the entire graph, providing
+* context and a visual indicator of the current viewport.
+*
+* **Usage:**
+* ```tsx
+* <World>
+*   <MiniMap width={200} height={150} />
+* </World>
+* ```
+*/
 const MiniMap = ({ width = 200, height = 150, style }) => {
 	const ctx = useAnode();
 	const { viewport } = useViewport();

package/dist/elements/Panel.d.ts

@@ -2,6 +2,19 @@ import React from "react";
 
 //#region src/elements/Panel.d.ts
 type PanelPosition = 'top-left' | 'top-right' | 'bottom-left' | 'bottom-right';
+/**
+ * A helper component to overlay custom UI elements (like toolbars or sidebars)
+ * at specific anchor points on the canvas.
+ *
+ * **Usage:**
+ * ```tsx
+ * <World>
+ *   <Panel position="top-right">
+ *     <button>Custom Action</button>
+ *   </Panel>
+ * </World>
+ * ```
+ */
 declare const Panel: React.FC<{
   position?: PanelPosition;
   children?: React.ReactNode;

package/dist/elements/Panel.js

@@ -2,6 +2,19 @@ import React from "react";
 import { jsx } from "react/jsx-runtime";
 
 //#region src/elements/Panel.tsx
+/**
+* A helper component to overlay custom UI elements (like toolbars or sidebars)
+* at specific anchor points on the canvas.
+*
+* **Usage:**
+* ```tsx
+* <World>
+*   <Panel position="top-right">
+*     <button>Custom Action</button>
+*   </Panel>
+* </World>
+* ```
+*/
 const Panel = ({ position = "top-left", children, style }) => {
 	const getPositionStyle = () => {
 		switch (position) {

package/dist/elements/World.d.ts

@@ -4,41 +4,82 @@ import React from "react";
 import { Context, LinkKind } from "@stuly/anode";
 
 //#region src/elements/World.d.ts
+/** Represents the minimal data for a node in declarative sync mode. */
 interface NodeData {
+  /** The unique ID for the node. */
   id: number;
+  /** The absolute world position. */
   position: {
     x: number;
     y: number;
   };
+  /** Type key for the `nodeTypes` map. */
   type?: string;
+  /** Custom data stored in `entity.inner`. */
   data?: any;
 }
+/** Represents the minimal data for a link in declarative sync mode. */
 interface LinkData {
+  /** The unique ID for the link. */
   id: number;
+  /** Source entity ID. */
   source: number;
+  /** Name of the source socket. */
   sourceHandle: string;
+  /** Target entity ID. */
   target: number;
+  /** Name of the target socket. */
   targetHandle: string;
+  /** Type key for the `linkTypes` map. */
   type?: string;
+  /** Custom data stored in `link.inner`. */
   data?: any;
+  /** Routing style for the link. */
   kind?: LinkKind;
+  /** Optional custom waypoints. */
   waypoints?: {
     x: number;
     y: number;
   }[];
 }
+/**
+ * The primary canvas component for Anode.
+ * Handles interaction (zoom, pan, selection) and synchronizes the React component
+ * tree with the internal headless engine.
+ *
+ * **Behaviors:**
+ * 1. **Zoom/Pan:** Standard wheel zoom and drag-to-pan interaction.
+ * 2. **Selection:** Multi-select with `Shift + Click`, Box select with `Alt + Click`.
+ * 3. **Keybindings:**
+ *    - `Backspace` / `Delete`: Remove selected nodes and links.
+ *    - `Ctrl + Z` / `Cmd + Z`: Undo the last action.
+ *    - `Ctrl + Shift + Z` / `Ctrl + Y`: Redo the last undone action.
+ * 4. **Declarative Sync:** If `nodes` or `links` are passed, the core engine
+ *    automatically mirrors these arrays. Changes made directly in the UI
+ *    (dragging, deleting) will trigger the corresponding `onNodesChange` callback.
+ * 5. **Spatial Culling:** Automatically uses `useVisibleNodes` to optimize rendering.
+ *
+ * **Usage:**
+ * ```tsx
+ * <World
+ *   nodeTypes={{ math: MathNode }}
+ *   nodes={state.nodes}
+ *   onNodesChange={newNodes => setState({ nodes: newNodes })}
+ * />
+ * ```
+ */
 declare const World: React.FC<{
-  children?: React.ReactNode;
-  style?: React.CSSProperties;
-  selectionBoxStyle?: React.CSSProperties;
-  nodeTypes?: Record<string, React.ComponentType<NodeComponentProps>>;
-  linkTypes?: Record<string, React.ComponentType<LinkComponentProps>>;
-  defaultLinkKind?: LinkKind;
-  onConnect?: (fromId: number, toId: number, ctx: Context<any>) => void;
-  isValidConnection?: (from: any, to: any, ctx: Context<any>) => boolean;
-  nodes?: NodeData[];
-  links?: LinkData[];
-  onNodesChange?: (nodes: NodeData[], ctx: Context<any>) => void;
+  /** Elements to overlay on the world (Background, MiniMap, etc.). */children?: React.ReactNode; /** Styles applied to the outer container. */
+  style?: React.CSSProperties; /** Styles applied to the selection box overlay. */
+  selectionBoxStyle?: React.CSSProperties; /** Map of custom node components by their `type` key. */
+  nodeTypes?: Record<string, React.ComponentType<NodeComponentProps>>; /** Map of custom link overlays/UI components by their `type` key. */
+  linkTypes?: Record<string, React.ComponentType<LinkComponentProps>>; /** Default style for newly created links. */
+  defaultLinkKind?: LinkKind; /** Callback triggered when a user completes a connection via drag-and-drop. */
+  onConnect?: (fromId: number, toId: number, ctx: Context<any>) => void; /** Custom validation for link creation. Return false to prevent a connection. */
+  isValidConnection?: (from: any, to: any, ctx: Context<any>) => boolean; /** Declarative list of nodes. Use for state-controlled synchronization. */
+  nodes?: NodeData[]; /** Declarative list of links. Use for state-controlled synchronization. */
+  links?: LinkData[]; /** Callback triggered when nodes are moved or dropped. */
+  onNodesChange?: (nodes: NodeData[], ctx: Context<any>) => void; /** Callback triggered when links are updated or deleted. */
   onLinksChange?: (links: LinkData[], ctx: Context<any>) => void;
 }>;
 //#endregion

package/dist/elements/World.js

@@ -1,7 +1,7 @@
 import { AnodeReactContext, useAnode, useSelection, useViewport } from "../context.js";
 import { useEdges, useGroups, useVisibleNodes } from "../hooks.js";
 import { Node } from "./Node.js";
-import { Group } from "./Group.js";
+import { Group as Group$1 } from "./Group.js";
 import { Link as Link$1 } from "./Link.js";
 import React, { useContext, useEffect, useRef, useState } from "react";
 import { Context, LinkKind, Rect, Vec2 } from "@stuly/anode";
@@ -26,6 +26,32 @@ const getCenter = (t1, t2) => {
 		y: (t1.clientY + t2.clientY) / 2
 	};
 };
+/**
+* The primary canvas component for Anode.
+* Handles interaction (zoom, pan, selection) and synchronizes the React component
+* tree with the internal headless engine.
+*
+* **Behaviors:**
+* 1. **Zoom/Pan:** Standard wheel zoom and drag-to-pan interaction.
+* 2. **Selection:** Multi-select with `Shift + Click`, Box select with `Alt + Click`.
+* 3. **Keybindings:**
+*    - `Backspace` / `Delete`: Remove selected nodes and links.
+*    - `Ctrl + Z` / `Cmd + Z`: Undo the last action.
+*    - `Ctrl + Shift + Z` / `Ctrl + Y`: Redo the last undone action.
+* 4. **Declarative Sync:** If `nodes` or `links` are passed, the core engine
+*    automatically mirrors these arrays. Changes made directly in the UI
+*    (dragging, deleting) will trigger the corresponding `onNodesChange` callback.
+* 5. **Spatial Culling:** Automatically uses `useVisibleNodes` to optimize rendering.
+*
+* **Usage:**
+* ```tsx
+* <World
+*   nodeTypes={{ math: MathNode }}
+*   nodes={state.nodes}
+*   onNodesChange={newNodes => setState({ nodes: newNodes })}
+* />
+* ```
+*/
 const World = ({ children, style, nodeTypes = {}, linkTypes = {}, defaultLinkKind = LinkKind.BEZIER, onConnect, isValidConnection, selectionBoxStyle, nodes, links: linksProp, onNodesChange, onLinksChange }) => {
 	const ctx = useAnode();
 	const { viewport: transform, setViewport: setTransform, screenToWorld } = useViewport();
@@ -392,6 +418,8 @@ const World = ({ children, style, nodeTypes = {}, linkTypes = {}, defaultLinkKin
 			const rect = worldRef.current.getBoundingClientRect();
 			const startX = e.clientX - rect.left;
 			const startY = e.clientY - rect.top;
+			let currentX = startX;
+			let currentY = startY;
 			setSelectionBox({
 				startX,
 				startY,
@@ -399,33 +427,34 @@ const World = ({ children, style, nodeTypes = {}, linkTypes = {}, defaultLinkKin
 				endY: startY
 			});
 			const onMouseMove = (moveEvent) => {
-				setSelectionBox((prev) => prev ? {
-					...prev,
-					endX: moveEvent.clientX - rect.left,
-					endY: moveEvent.clientY - rect.top
-				} : null);
+				currentX = moveEvent.clientX - rect.left;
+				currentY = moveEvent.clientY - rect.top;
+				setSelectionBox({
+					startX,
+					startY,
+					endX: currentX,
+					endY: currentY
+				});
 			};
 			const onMouseUp = () => {
 				document.removeEventListener("mousemove", onMouseMove);
 				document.removeEventListener("mouseup", onMouseUp);
-				setSelectionBox((prev) => {
-					if (!prev) return null;
-					const rect = worldRef.current?.getBoundingClientRect();
-					if (!rect) return null;
-					const x1 = Math.min(prev.startX, prev.endX);
-					const y1 = Math.min(prev.startY, prev.endY);
-					const x2 = Math.max(prev.startX, prev.endX);
-					const y2 = Math.max(prev.startY, prev.endY);
-					const worldTopLeft = screenToWorld(x1 + rect.left, y1 + rect.top);
-					const worldBottomRight = screenToWorld(x2 + rect.left, y2 + rect.top);
+				const x1 = Math.min(startX, currentX);
+				const y1 = Math.min(startY, currentY);
+				const x2 = Math.max(startX, currentX);
+				const y2 = Math.max(startY, currentY);
+				const worldRect = worldRef.current?.getBoundingClientRect();
+				if (worldRect) {
+					const worldTopLeft = screenToWorld(x1 + worldRect.left, y1 + worldRect.top);
+					const worldBottomRight = screenToWorld(x2 + worldRect.left, y2 + worldRect.top);
 					const queryRect = new Rect(worldTopLeft.x, worldTopLeft.y, worldBottomRight.x - worldTopLeft.x, worldBottomRight.y - worldTopLeft.y);
 					const selectedIds = ctx.quadTree.query(queryRect);
 					setSelection({
 						nodes: new Set(selectedIds),
 						links: /* @__PURE__ */ new Set()
 					});
-					return null;
-				});
+				}
+				setSelectionBox(null);
 			};
 			document.addEventListener("mousemove", onMouseMove);
 			document.addEventListener("mouseup", onMouseUp);
@@ -595,7 +624,7 @@ const World = ({ children, style, nodeTypes = {}, linkTypes = {}, defaultLinkKin
 						zIndex: 1,
 						pointerEvents: "none"
 					},
-					children: [groups.map((group) => /* @__PURE__ */ jsx(Group, { id: group.id }, group.id)), entities.map((entity) => {
+					children: [groups.map((group) => /* @__PURE__ */ jsx(Group$1, { id: group.id }, group.id)), entities.map((entity) => {
 						const Component = nodeTypes[entity.inner?.type || "default"] || DefaultNode;
 						return /* @__PURE__ */ jsx(Node, {
 							id: entity.id,

package/dist/hooks.d.ts

@@ -1,15 +1,59 @@
-import * as _stuly_anode0 from "@stuly/anode";
-import { Entity, Link } from "@stuly/anode";
+import { Entity, Group, Link } from "@stuly/anode";
 
 //#region src/hooks.d.ts
+/**
+ * Returns an array of all entities currently in the graph.
+ * Reactively updates when nodes are created, deleted, or moved.
+ *
+ * **Usage:**
+ * ```tsx
+ * const nodes = useNodes();
+ * ```
+ */
 declare const useNodes: () => Entity<any>[];
+/**
+ * Optimized hook for rendering a large-scale node graph.
+ * Performs a spatial query on the QuadTree to return only the nodes
+ * that are currently within the user's viewport (with padding).
+ *
+ * **Side Effects:** Triggers re-renders only when nodes enter or exit the viewport
+ * OR when a visible node is moved.
+ *
+ * @param containerRect The dimensions of the canvas container. If omitted, defaults to window size.
+ * @returns Array of visible Entity objects.
+ */
 declare const useVisibleNodes: (containerRect?: {
   width: number;
   height: number;
 }) => Entity<any>[];
+/**
+ * Returns an array of all links currently in the graph.
+ * Reactively updates when links are created, deleted, or updated,
+ * or when an endpoint entity moves (triggering path recalculation).
+ */
 declare const useEdges: () => Link<any>[];
+/**
+ * Returns an array of all sockets associated with a specific entity.
+ * Reactively updates when sockets are added or removed from the entity.
+ *
+ * @param entityId The unique ID of the entity.
+ */
 declare const useEntitySockets: (entityId: number) => any[];
+/**
+ * Subscribes to the reactive value of a specific socket.
+ *
+ * **Cause:** Triggers a re-render only when the value of the socket
+ * changes due to engine propagation.
+ *
+ * @template T The type of the value held by the socket.
+ * @param socketId The unique ID of the socket.
+ * @returns The current socket value, or null if the socket doesn't exist.
+ */
 declare function useSocketValue<T = any>(socketId: number | null): T;
-declare const useGroups: () => _stuly_anode0.Group[];
+/**
+ * Returns an array of all groups currently in the graph.
+ * Reactively updates when groups are created or deleted.
+ */
+declare const useGroups: () => Group[];
 //#endregion
 export { useEdges, useEntitySockets, useGroups, useNodes, useSocketValue, useVisibleNodes };

package/dist/hooks.js

@@ -1,8 +1,17 @@
 import { useAnode, useViewport } from "./context.js";
-import React, { useMemo, useSyncExternalStore } from "react";
-import { Entity, Link, Rect } from "@stuly/anode";
+import { useMemo, useSyncExternalStore } from "react";
+import { Entity, Group, Link, Rect } from "@stuly/anode";
 
 //#region src/hooks.ts
+/**
+* Returns an array of all entities currently in the graph.
+* Reactively updates when nodes are created, deleted, or moved.
+*
+* **Usage:**
+* ```tsx
+* const nodes = useNodes();
+* ```
+*/
 const useNodes = () => {
 	const ctx = useAnode();
 	const store = useMemo(() => {
@@ -27,6 +36,17 @@ const useNodes = () => {
 	}, [ctx]);
 	return useSyncExternalStore(store.subscribe, store.getSnapshot);
 };
+/**
+* Optimized hook for rendering a large-scale node graph.
+* Performs a spatial query on the QuadTree to return only the nodes
+* that are currently within the user's viewport (with padding).
+*
+* **Side Effects:** Triggers re-renders only when nodes enter or exit the viewport
+* OR when a visible node is moved.
+*
+* @param containerRect The dimensions of the canvas container. If omitted, defaults to window size.
+* @returns Array of visible Entity objects.
+*/
 const useVisibleNodes = (containerRect) => {
 	const ctx = useAnode();
 	const { viewport } = useViewport();
@@ -45,6 +65,11 @@ const useVisibleNodes = (containerRect) => {
 		useNodes()
 	]);
 };
+/**
+* Returns an array of all links currently in the graph.
+* Reactively updates when links are created, deleted, or updated,
+* or when an endpoint entity moves (triggering path recalculation).
+*/
 const useEdges = () => {
 	const ctx = useAnode();
 	const store = useMemo(() => {
@@ -69,6 +94,12 @@ const useEdges = () => {
 	}, [ctx]);
 	return useSyncExternalStore(store.subscribe, store.getSnapshot);
 };
+/**
+* Returns an array of all sockets associated with a specific entity.
+* Reactively updates when sockets are added or removed from the entity.
+*
+* @param entityId The unique ID of the entity.
+*/
 const useEntitySockets = (entityId) => {
 	const ctx = useAnode();
 	const store = useMemo(() => {
@@ -104,6 +135,16 @@ const useEntitySockets = (entityId) => {
 	}, [ctx, entityId]);
 	return useSyncExternalStore(store.subscribe, store.getSnapshot);
 };
+/**
+* Subscribes to the reactive value of a specific socket.
+*
+* **Cause:** Triggers a re-render only when the value of the socket
+* changes due to engine propagation.
+*
+* @template T The type of the value held by the socket.
+* @param socketId The unique ID of the socket.
+* @returns The current socket value, or null if the socket doesn't exist.
+*/
 function useSocketValue(socketId) {
 	const ctx = useAnode();
 	const store = useMemo(() => {
@@ -127,6 +168,10 @@ function useSocketValue(socketId) {
 	}, [ctx, socketId]);
 	return useSyncExternalStore(store.subscribe, store.getSnapshot);
 }
+/**
+* Returns an array of all groups currently in the graph.
+* Reactively updates when groups are created or deleted.
+*/
 const useGroups = () => {
 	const ctx = useAnode();
 	const store = useMemo(() => {

package/package.json

@@ -1,23 +1,37 @@
 {
   "name": "@stuly/anode-react",
-  "version": "0.1.0",
-  "description": "Anode react wrapper",
+  "version": "0.1.2",
+  "description": "First-class React bindings for building interactive, declarative node editors with Anode.",
   "main": "dist/index.js",
   "module": "dist/index.js",
   "types": "dist/index.d.ts",
   "publishConfig": {
     "access": "public"
   },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/stulyproject/anode.git"
+  },
+  "bugs": {
+    "url": "https://github.com/stulyproject/anode/issues"
+  },
+  "homepage": "https://github.com/stulyproject/anode#readme",
   "files": [
     "dist"
   ],
-  "keywords": [],
+  "keywords": [
+    "react",
+    "node-editor",
+    "node-graph",
+    "anode",
+    "declarative"
+  ],
   "author": "",
   "type": "module",
   "license": "MIT",
   "peerDependencies": {
     "react": "^19.2.4",
-    "@stuly/anode": "^0.1.0"
+    "@stuly/anode": "^0.1.2"
   },
   "devDependencies": {
     "@types/react": "^19.2.14",