@continuum-dev/react 0.1.1 → 0.1.2

package/README.md

@@ -343,6 +343,34 @@ Scans current snapshot values for suggestions and provides accept-all / reject-a
 const { hasSuggestions, acceptAll, rejectAll } = useContinuumSuggestions();
 ```
 
+#### `useContinuumAction(intentId)`
+
+Handles action dispatch with built-in loading and result state.
+
+```ts
+const { dispatch, isDispatching, lastResult } = useContinuumAction('submit_form');
+```
+
+Example action component:
+
+```tsx
+function SubmitButton({ definition }: ContinuumNodeProps) {
+  const intentId = definition.intentId ?? '';
+  const { dispatch, isDispatching, lastResult } = useContinuumAction(intentId);
+
+  return (
+    <div>
+      <button disabled={isDispatching} onClick={() => dispatch(definition.id)}>
+        {isDispatching ? 'Working...' : definition.label}
+      </button>
+      {lastResult && (
+        <span>{lastResult.success ? 'Done' : 'Failed'}</span>
+      )}
+    </div>
+  );
+}
+```
+
 ---
 
 ## The node contract

package/lib/context.d.ts

@@ -2,22 +2,48 @@ import type { Session } from '@continuum-dev/session';
 import type { ContinuitySnapshot, NodeValue, ViewportState } from '@continuum-dev/contract';
 import type { ContinuumNodeMap, ContinuumProviderProps } from './types.js';
 type Listener = () => void;
+/**
+ * Subscription-oriented store facade over Continuum session state.
+ */
 export interface ContinuumStore {
+    /** Returns the latest continuity snapshot. */
     getSnapshot(): ContinuitySnapshot | null;
+    /** Subscribes to snapshot updates. */
     subscribeSnapshot(listener: Listener): () => void;
+    /** Subscribes to diagnostics-related updates. */
     subscribeDiagnostics(listener: Listener): () => void;
+    /** Returns a node value by canonical id. */
     getNodeValue(nodeId: string): NodeValue | undefined;
+    /** Returns viewport state by canonical node id. */
     getNodeViewport(nodeId: string): ViewportState | undefined;
+    /** Subscribes to updates for a specific node id. */
     subscribeNode(nodeId: string, listener: Listener): () => void;
+    /** Releases store subscriptions and listeners. */
     destroy(): void;
 }
+/**
+ * Value shape exposed through `ContinuumContext`.
+ */
 export interface ContinuumContextValue {
+    /** Backing Continuum session instance. */
     session: Session;
+    /** Subscription-friendly store facade over session state. */
     store: ContinuumStore;
+    /** Resolved node type to component map. */
     componentMap: ContinuumNodeMap;
+    /** True when provider loaded from existing persisted state. */
     wasHydrated: boolean;
 }
+/**
+ * React context backing all `@continuum-dev/react` hooks and renderer behavior.
+ */
 export declare const ContinuumContext: import("react").Context<ContinuumContextValue | null>;
+/**
+ * Initializes and provides Continuum session context to the React subtree.
+ *
+ * Creates (or hydrates) a session once, wires optional persistence, and
+ * provides a reactive store used by hooks and renderer components.
+ */
 export declare function ContinuumProvider({ components, persist, storageKey, maxPersistBytes, onPersistError, sessionOptions, children, }: ContinuumProviderProps): import("react/jsx-runtime").JSX.Element;
 export {};
 //# sourceMappingURL=context.d.ts.map

package/lib/context.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"context.d.ts","sourceRoot":"","sources":["../../../../packages/react/src/lib/context.tsx"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,oBAAoB,CAAC;AAClD,OAAO,KAAK,EAAE,kBAAkB,EAAE,SAAS,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AACxF,OAAO,KAAK,EAAE,gBAAgB,EAAE,sBAAsB,EAAE,MAAM,YAAY,CAAC;AAE3E,KAAK,QAAQ,GAAG,MAAM,IAAI,CAAC;AA+C3B,MAAM,WAAW,cAAc;IAC7B,WAAW,IAAI,kBAAkB,GAAG,IAAI,CAAC;IACzC,iBAAiB,CAAC,QAAQ,EAAE,QAAQ,GAAG,MAAM,IAAI,CAAC;IAClD,oBAAoB,CAAC,QAAQ,EAAE,QAAQ,GAAG,MAAM,IAAI,CAAC;IACrD,YAAY,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,GAAG,SAAS,CAAC;IACpD,eAAe,CAAC,MAAM,EAAE,MAAM,GAAG,aAAa,GAAG,SAAS,CAAC;IAC3D,aAAa,CAAC,MAAM,EAAE,MAAM,EAAE,QAAQ,EAAE,QAAQ,GAAG,MAAM,IAAI,CAAC;IAC9D,OAAO,IAAI,IAAI,CAAC;CACjB;AAoFD,MAAM,WAAW,qBAAqB;IACpC,OAAO,EAAE,OAAO,CAAC;IACjB,KAAK,EAAE,cAAc,CAAC;IACtB,YAAY,EAAE,gBAAgB,CAAC;IAC/B,WAAW,EAAE,OAAO,CAAC;CACtB;AAED,eAAO,MAAM,gBAAgB,uDAAoD,CAAC;AAuClF,wBAAgB,iBAAiB,CAAC,EAChC,UAAU,EACV,OAAe,EACf,UAAgC,EAChC,eAAe,EACf,cAAc,EACd,cAAc,EACd,QAAQ,GACT,EAAE,sBAAsB,2CAsDxB"}
+{"version":3,"file":"context.d.ts","sourceRoot":"","sources":["../../../../packages/react/src/lib/context.tsx"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,oBAAoB,CAAC;AAClD,OAAO,KAAK,EAAE,kBAAkB,EAAE,SAAS,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AACxF,OAAO,KAAK,EAAE,gBAAgB,EAAE,sBAAsB,EAAE,MAAM,YAAY,CAAC;AAE3E,KAAK,QAAQ,GAAG,MAAM,IAAI,CAAC;AA+C3B;;GAEG;AACH,MAAM,WAAW,cAAc;IAC7B,8CAA8C;IAC9C,WAAW,IAAI,kBAAkB,GAAG,IAAI,CAAC;IACzC,sCAAsC;IACtC,iBAAiB,CAAC,QAAQ,EAAE,QAAQ,GAAG,MAAM,IAAI,CAAC;IAClD,iDAAiD;IACjD,oBAAoB,CAAC,QAAQ,EAAE,QAAQ,GAAG,MAAM,IAAI,CAAC;IACrD,4CAA4C;IAC5C,YAAY,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,GAAG,SAAS,CAAC;IACpD,mDAAmD;IACnD,eAAe,CAAC,MAAM,EAAE,MAAM,GAAG,aAAa,GAAG,SAAS,CAAC;IAC3D,oDAAoD;IACpD,aAAa,CAAC,MAAM,EAAE,MAAM,EAAE,QAAQ,EAAE,QAAQ,GAAG,MAAM,IAAI,CAAC;IAC9D,kDAAkD;IAClD,OAAO,IAAI,IAAI,CAAC;CACjB;AAoFD;;GAEG;AACH,MAAM,WAAW,qBAAqB;IACpC,0CAA0C;IAC1C,OAAO,EAAE,OAAO,CAAC;IACjB,6DAA6D;IAC7D,KAAK,EAAE,cAAc,CAAC;IACtB,2CAA2C;IAC3C,YAAY,EAAE,gBAAgB,CAAC;IAC/B,+DAA+D;IAC/D,WAAW,EAAE,OAAO,CAAC;CACtB;AAED;;GAEG;AACH,eAAO,MAAM,gBAAgB,uDAAoD,CAAC;AAuClF;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAAC,EAChC,UAAU,EACV,OAAe,EACf,UAAgC,EAChC,eAAe,EACf,cAAc,EACd,cAAc,EACd,QAAQ,GACT,EAAE,sBAAsB,2CAsDxB"}

package/lib/context.js

@@ -112,6 +112,9 @@ function createContinuumStore(session) {
         },
     };
 }
+/**
+ * React context backing all `@continuum-dev/react` hooks and renderer behavior.
+ */
 export const ContinuumContext = createContext(null);
 const DEFAULT_STORAGE_KEY = 'continuum_session';
 function resolveStorage(persist) {
@@ -143,6 +146,12 @@ function useStableMap(map) {
     ref.current = map;
     return map;
 }
+/**
+ * Initializes and provides Continuum session context to the React subtree.
+ *
+ * Creates (or hydrates) a session once, wires optional persistence, and
+ * provides a reactive store used by hooks and renderer components.
+ */
 export function ContinuumProvider({ components, persist = false, storageKey = DEFAULT_STORAGE_KEY, maxPersistBytes, onPersistError, sessionOptions, children, }) {
     const storage = resolveStorage(persist);
     const stableComponents = useStableMap(components);

package/lib/error-boundary.d.ts

@@ -7,6 +7,9 @@ interface NodeErrorBoundaryState {
     hasError: boolean;
     message: string;
 }
+/**
+ * Per-node error boundary used by the renderer to isolate component failures.
+ */
 export declare class NodeErrorBoundary extends Component<NodeErrorBoundaryProps, NodeErrorBoundaryState> {
     state: NodeErrorBoundaryState;
     static getDerivedStateFromError(error: unknown): NodeErrorBoundaryState;

package/lib/error-boundary.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"error-boundary.d.ts","sourceRoot":"","sources":["../../../../packages/react/src/lib/error-boundary.tsx"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,KAAK,SAAS,EAAE,MAAM,OAAO,CAAC;AAElD,UAAU,sBAAsB;IAC9B,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,SAAS,CAAC;CACrB;AAED,UAAU,sBAAsB;IAC9B,QAAQ,EAAE,OAAO,CAAC;IAClB,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,qBAAa,iBAAkB,SAAQ,SAAS,CAC9C,sBAAsB,EACtB,sBAAsB,CACvB;IACU,KAAK,EAAE,sBAAsB,CAGpC;IAEF,MAAM,CAAC,wBAAwB,CAAC,KAAK,EAAE,OAAO,GAAG,sBAAsB;IAO9D,MAAM;CAUhB"}
+{"version":3,"file":"error-boundary.d.ts","sourceRoot":"","sources":["../../../../packages/react/src/lib/error-boundary.tsx"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,KAAK,SAAS,EAAE,MAAM,OAAO,CAAC;AAElD,UAAU,sBAAsB;IAC9B,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,SAAS,CAAC;CACrB;AAED,UAAU,sBAAsB;IAC9B,QAAQ,EAAE,OAAO,CAAC;IAClB,OAAO,EAAE,MAAM,CAAC;CACjB;AAED;;GAEG;AACH,qBAAa,iBAAkB,SAAQ,SAAS,CAC9C,sBAAsB,EACtB,sBAAsB,CACvB;IACU,KAAK,EAAE,sBAAsB,CAGpC;IAEF,MAAM,CAAC,wBAAwB,CAAC,KAAK,EAAE,OAAO,GAAG,sBAAsB;IAO9D,MAAM;CAUhB"}

package/lib/error-boundary.js

@@ -1,5 +1,8 @@
 import { jsxs as _jsxs } from "react/jsx-runtime";
 import { Component } from 'react';
+/**
+ * Per-node error boundary used by the renderer to isolate component failures.
+ */
 export class NodeErrorBoundary extends Component {
     state = {
         hasError: false,

package/lib/fallback.d.ts

@@ -1,3 +1,6 @@
 import type { ContinuumNodeProps } from './types.js';
+/**
+ * Default renderer used when no component exists for a node type.
+ */
 export declare function FallbackComponent({ value, onChange, definition, }: ContinuumNodeProps): import("react/jsx-runtime").JSX.Element;
 //# sourceMappingURL=fallback.d.ts.map

package/lib/fallback.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"fallback.d.ts","sourceRoot":"","sources":["../../../../packages/react/src/lib/fallback.tsx"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,YAAY,CAAC;AAErD,wBAAgB,iBAAiB,CAAC,EAChC,KAAK,EACL,QAAQ,EACR,UAAU,GACX,EAAE,kBAAkB,2CAoCpB"}
+{"version":3,"file":"fallback.d.ts","sourceRoot":"","sources":["../../../../packages/react/src/lib/fallback.tsx"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,YAAY,CAAC;AAErD;;GAEG;AACH,wBAAgB,iBAAiB,CAAC,EAChC,KAAK,EACL,QAAQ,EACR,UAAU,GACX,EAAE,kBAAkB,2CAoCpB"}

package/lib/fallback.js

@@ -1,4 +1,7 @@
 import { jsxs as _jsxs, jsx as _jsx } from "react/jsx-runtime";
+/**
+ * Default renderer used when no component exists for a node type.
+ */
 export function FallbackComponent({ value, onChange, definition, }) {
     const raw = value;
     const textValue = typeof raw?.['value'] === 'string' || typeof raw?.['value'] === 'number'

package/lib/hooks.d.ts

@@ -1,32 +1,76 @@
 import type { Session } from '@continuum-dev/session';
-import type { ContinuitySnapshot, NodeValue, ViewportState, ProposedValue } from '@continuum-dev/contract';
+import type { ContinuitySnapshot, NodeValue, ViewportState, ProposedValue, ActionResult } from '@continuum-dev/contract';
 interface NodeStateScope {
     subscribeNode: (nodeId: string, listener: () => void) => () => void;
     getNodeValue: (nodeId: string) => NodeValue | undefined;
     setNodeValue: (nodeId: string, value: NodeValue) => void;
 }
+/**
+ * Internal scope context used by collection item renderers to map local node ids
+ * onto collection-backed values.
+ */
 export declare const NodeStateScopeContext: import("react").Context<NodeStateScope | null>;
+/**
+ * Returns the active Continuum session from provider context.
+ */
 export declare function useContinuumSession(): Session;
+/**
+ * Subscribes to and updates a specific node value by canonical node id.
+ *
+ * @param nodeId Canonical node id.
+ */
 export declare function useContinuumState(nodeId: string): [NodeValue | undefined, (value: NodeValue) => void];
+/**
+ * Subscribes to the full continuity snapshot.
+ */
 export declare function useContinuumSnapshot(): ContinuitySnapshot | null;
+/**
+ * Subscribes to and updates viewport state for a specific node.
+ *
+ * @param nodeId Canonical node id.
+ */
 export declare function useContinuumViewport(nodeId: string): [ViewportState | undefined, (state: ViewportState) => void];
+/**
+ * Subscribes to session diagnostics (`issues`, `diffs`, `resolutions`, checkpoints).
+ */
 export declare function useContinuumDiagnostics(): {
     issues: ReturnType<Session["getIssues"]>;
     diffs: ReturnType<Session["getDiffs"]>;
     resolutions: ReturnType<Session["getResolutions"]>;
     checkpoints: ReturnType<Session["getCheckpoints"]>;
 };
+/**
+ * Indicates whether the provider session was restored from persistence.
+ */
 export declare function useContinuumHydrated(): boolean;
+/**
+ * Returns conflict state and resolution actions for one node.
+ *
+ * @param nodeId Canonical node id.
+ */
 export declare function useContinuumConflict(nodeId: string): {
     hasConflict: boolean;
     proposal: ProposedValue | null;
     accept: () => void;
     reject: () => void;
 };
+/**
+ * Aggregates suggestion state and exposes bulk accept/reject operations.
+ */
 export declare function useContinuumSuggestions(): {
     hasSuggestions: boolean;
     acceptAll: () => void;
     rejectAll: () => void;
 };
+/**
+ * Returns an action dispatcher bound to an intent id with dispatch state.
+ *
+ * @param intentId Registered action intent id to dispatch.
+ */
+export declare function useContinuumAction(intentId: string): {
+    dispatch: (nodeId: string) => Promise<ActionResult>;
+    isDispatching: boolean;
+    lastResult: ActionResult | null;
+};
 export {};
 //# sourceMappingURL=hooks.d.ts.map

package/lib/hooks.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"hooks.d.ts","sourceRoot":"","sources":["../../../../packages/react/src/lib/hooks.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,oBAAoB,CAAC;AAClD,OAAO,KAAK,EAAE,kBAAkB,EAAE,SAAS,EAAE,aAAa,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AAwDvG,UAAU,cAAc;IACtB,aAAa,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,IAAI,KAAK,MAAM,IAAI,CAAC;IACpE,YAAY,EAAE,CAAC,MAAM,EAAE,MAAM,KAAK,SAAS,GAAG,SAAS,CAAC;IACxD,YAAY,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,SAAS,KAAK,IAAI,CAAC;CAC1D;AAED,eAAO,MAAM,qBAAqB,gDAA6C,CAAC;AAEhF,wBAAgB,mBAAmB,IAAI,OAAO,CAQ7C;AAED,wBAAgB,iBAAiB,CAC/B,MAAM,EAAE,MAAM,GACb,CAAC,SAAS,GAAG,SAAS,EAAE,CAAC,KAAK,EAAE,SAAS,KAAK,IAAI,CAAC,CAiDrD;AAED,wBAAgB,oBAAoB,IAAI,kBAAkB,GAAG,IAAI,CAiDhE;AAED,wBAAgB,oBAAoB,CAClC,MAAM,EAAE,MAAM,GACb,CAAC,aAAa,GAAG,SAAS,EAAE,CAAC,KAAK,EAAE,aAAa,KAAK,IAAI,CAAC,CAkC7D;AAED,wBAAgB,uBAAuB;YAS3B,UAAU,CAAC,OAAO,CAAC,WAAW,CAAC,CAAC;WACjC,UAAU,CAAC,OAAO,CAAC,UAAU,CAAC,CAAC;iBACzB,UAAU,CAAC,OAAO,CAAC,gBAAgB,CAAC,CAAC;iBACrC,UAAU,CAAC,OAAO,CAAC,gBAAgB,CAAC,CAAC;EAmCrD;AAED,wBAAgB,oBAAoB,IAAI,OAAO,CAQ9C;AAED,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,MAAM,GAAG;IACpD,WAAW,EAAE,OAAO,CAAC;IACrB,QAAQ,EAAE,aAAa,GAAG,IAAI,CAAC;IAC/B,MAAM,EAAE,MAAM,IAAI,CAAC;IACnB,MAAM,EAAE,MAAM,IAAI,CAAC;CACpB,CAsCA;AAED,wBAAgB,uBAAuB,IAAI;IACzC,cAAc,EAAE,OAAO,CAAC;IACxB,SAAS,EAAE,MAAM,IAAI,CAAC;IACtB,SAAS,EAAE,MAAM,IAAI,CAAC;CACvB,CAgEA"}
+{"version":3,"file":"hooks.d.ts","sourceRoot":"","sources":["../../../../packages/react/src/lib/hooks.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,oBAAoB,CAAC;AAClD,OAAO,KAAK,EAAE,kBAAkB,EAAE,SAAS,EAAE,aAAa,EAAE,aAAa,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AAwDrH,UAAU,cAAc;IACtB,aAAa,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,IAAI,KAAK,MAAM,IAAI,CAAC;IACpE,YAAY,EAAE,CAAC,MAAM,EAAE,MAAM,KAAK,SAAS,GAAG,SAAS,CAAC;IACxD,YAAY,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,SAAS,KAAK,IAAI,CAAC;CAC1D;AAED;;;GAGG;AACH,eAAO,MAAM,qBAAqB,gDAA6C,CAAC;AAEhF;;GAEG;AACH,wBAAgB,mBAAmB,IAAI,OAAO,CAQ7C;AAED;;;;GAIG;AACH,wBAAgB,iBAAiB,CAC/B,MAAM,EAAE,MAAM,GACb,CAAC,SAAS,GAAG,SAAS,EAAE,CAAC,KAAK,EAAE,SAAS,KAAK,IAAI,CAAC,CAiDrD;AAED;;GAEG;AACH,wBAAgB,oBAAoB,IAAI,kBAAkB,GAAG,IAAI,CAiDhE;AAED;;;;GAIG;AACH,wBAAgB,oBAAoB,CAClC,MAAM,EAAE,MAAM,GACb,CAAC,aAAa,GAAG,SAAS,EAAE,CAAC,KAAK,EAAE,aAAa,KAAK,IAAI,CAAC,CAkC7D;AAED;;GAEG;AACH,wBAAgB,uBAAuB;YAS3B,UAAU,CAAC,OAAO,CAAC,WAAW,CAAC,CAAC;WACjC,UAAU,CAAC,OAAO,CAAC,UAAU,CAAC,CAAC;iBACzB,UAAU,CAAC,OAAO,CAAC,gBAAgB,CAAC,CAAC;iBACrC,UAAU,CAAC,OAAO,CAAC,gBAAgB,CAAC,CAAC;EAmCrD;AAED;;GAEG;AACH,wBAAgB,oBAAoB,IAAI,OAAO,CAQ9C;AAED;;;;GAIG;AACH,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,MAAM,GAAG;IACpD,WAAW,EAAE,OAAO,CAAC;IACrB,QAAQ,EAAE,aAAa,GAAG,IAAI,CAAC;IAC/B,MAAM,EAAE,MAAM,IAAI,CAAC;IACnB,MAAM,EAAE,MAAM,IAAI,CAAC;CACpB,CAsCA;AAED;;GAEG;AACH,wBAAgB,uBAAuB,IAAI;IACzC,cAAc,EAAE,OAAO,CAAC;IACxB,SAAS,EAAE,MAAM,IAAI,CAAC;IACtB,SAAS,EAAE,MAAM,IAAI,CAAC;CACvB,CAgEA;AAED;;;;GAIG;AACH,wBAAgB,kBAAkB,CAAC,QAAQ,EAAE,MAAM,GAAG;IACpD,QAAQ,EAAE,CAAC,MAAM,EAAE,MAAM,KAAK,OAAO,CAAC,YAAY,CAAC,CAAC;IACpD,aAAa,EAAE,OAAO,CAAC;IACvB,UAAU,EAAE,YAAY,GAAG,IAAI,CAAC;CACjC,CA0BA"}

package/lib/hooks.js

@@ -1,4 +1,4 @@
-import { createContext, useContext, useCallback, useRef, useSyncExternalStore } from 'react';
+import { createContext, useContext, useCallback, useRef, useState, useSyncExternalStore } from 'react';
 import { ContinuumContext } from './context.js';
 function shallowArrayEqual(left, right) {
     if (left.length !== right.length) {
@@ -38,7 +38,14 @@ function shallowViewportEqual(left, right) {
         left.isExpanded === right.isExpanded &&
         left.isFocused === right.isFocused);
 }
+/**
+ * Internal scope context used by collection item renderers to map local node ids
+ * onto collection-backed values.
+ */
 export const NodeStateScopeContext = createContext(null);
+/**
+ * Returns the active Continuum session from provider context.
+ */
 export function useContinuumSession() {
     const ctx = useContext(ContinuumContext);
     if (!ctx) {
@@ -46,6 +53,11 @@ export function useContinuumSession() {
     }
     return ctx.session;
 }
+/**
+ * Subscribes to and updates a specific node value by canonical node id.
+ *
+ * @param nodeId Canonical node id.
+ */
 export function useContinuumState(nodeId) {
     const ctx = useContext(ContinuumContext);
     const scope = useContext(NodeStateScopeContext);
@@ -81,6 +93,9 @@ export function useContinuumState(nodeId) {
     }, [scope, session, nodeId]);
     return [value, setValue];
 }
+/**
+ * Subscribes to the full continuity snapshot.
+ */
 export function useContinuumSnapshot() {
     const ctx = useContext(ContinuumContext);
     if (!ctx) {
@@ -114,6 +129,11 @@ export function useContinuumSnapshot() {
     }, [store]);
     return useSyncExternalStore(subscribe, getSnapshot, getSnapshot);
 }
+/**
+ * Subscribes to and updates viewport state for a specific node.
+ *
+ * @param nodeId Canonical node id.
+ */
 export function useContinuumViewport(nodeId) {
     const ctx = useContext(ContinuumContext);
     if (!ctx) {
@@ -137,6 +157,9 @@ export function useContinuumViewport(nodeId) {
     }, [session, nodeId]);
     return [viewport, setViewport];
 }
+/**
+ * Subscribes to session diagnostics (`issues`, `diffs`, `resolutions`, checkpoints).
+ */
 export function useContinuumDiagnostics() {
     const ctx = useContext(ContinuumContext);
     if (!ctx) {
@@ -165,6 +188,9 @@ export function useContinuumDiagnostics() {
     const subscribe = useCallback((onStoreChange) => store.subscribeDiagnostics(onStoreChange), [store]);
     return useSyncExternalStore(subscribe, getSnapshot, getSnapshot);
 }
+/**
+ * Indicates whether the provider session was restored from persistence.
+ */
 export function useContinuumHydrated() {
     const ctx = useContext(ContinuumContext);
     if (!ctx) {
@@ -172,6 +198,11 @@ export function useContinuumHydrated() {
     }
     return ctx.wasHydrated;
 }
+/**
+ * Returns conflict state and resolution actions for one node.
+ *
+ * @param nodeId Canonical node id.
+ */
 export function useContinuumConflict(nodeId) {
     const ctx = useContext(ContinuumContext);
     if (!ctx) {
@@ -203,6 +234,9 @@ export function useContinuumConflict(nodeId) {
         reject,
     };
 }
+/**
+ * Aggregates suggestion state and exposes bulk accept/reject operations.
+ */
 export function useContinuumSuggestions() {
     const ctx = useContext(ContinuumContext);
     if (!ctx) {
@@ -260,3 +294,29 @@ export function useContinuumSuggestions() {
         rejectAll,
     };
 }
+/**
+ * Returns an action dispatcher bound to an intent id with dispatch state.
+ *
+ * @param intentId Registered action intent id to dispatch.
+ */
+export function useContinuumAction(intentId) {
+    const ctx = useContext(ContinuumContext);
+    if (!ctx) {
+        throw new Error('useContinuumAction must be used within a <ContinuumProvider>');
+    }
+    const { session } = ctx;
+    const [isDispatching, setIsDispatching] = useState(false);
+    const [lastResult, setLastResult] = useState(null);
+    const dispatch = useCallback(async (nodeId) => {
+        setIsDispatching(true);
+        try {
+            const result = await session.dispatchAction(intentId, nodeId);
+            setLastResult(result);
+            return result;
+        }
+        finally {
+            setIsDispatching(false);
+        }
+    }, [session, intentId]);
+    return { dispatch, isDispatching, lastResult };
+}

package/lib/renderer.d.ts

@@ -1,4 +1,7 @@
 import type { ViewDefinition } from '@continuum-dev/contract';
+/**
+ * Renders a `ViewDefinition` tree using components registered in `ContinuumProvider`.
+ */
 export declare function ContinuumRenderer({ view }: {
     view: ViewDefinition;
 }): import("react/jsx-runtime").JSX.Element;

package/lib/renderer.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"renderer.d.ts","sourceRoot":"","sources":["../../../../packages/react/src/lib/renderer.tsx"],"names":[],"mappings":"AACA,OAAO,KAAK,EAIV,cAAc,EAEf,MAAM,qBAAqB,CAAC;AA+W7B,wBAAgB,iBAAiB,CAAC,EAAE,IAAI,EAAE,EAAE;IAAE,IAAI,EAAE,cAAc,CAAA;CAAE,2CAQnE"}
+{"version":3,"file":"renderer.d.ts","sourceRoot":"","sources":["../../../../packages/react/src/lib/renderer.tsx"],"names":[],"mappings":"AACA,OAAO,KAAK,EAIV,cAAc,EAEf,MAAM,qBAAqB,CAAC;AA+W7B;;GAEG;AACH,wBAAgB,iBAAiB,CAAC,EAAE,IAAI,EAAE,EAAE;IAAE,IAAI,EAAE,cAAc,CAAA;CAAE,2CAQnE"}

package/lib/renderer.js

@@ -201,6 +201,9 @@ const NodeRenderer = memo(function NodeRenderer({ definition, parentPath }) {
     }
     return _jsx(StatefulNodeRenderer, { definition: definition, parentPath: parentPath });
 });
+/**
+ * Renders a `ViewDefinition` tree using components registered in `ContinuumProvider`.
+ */
 export function ContinuumRenderer({ view }) {
     return (_jsx("div", { "data-continuum-view": view.viewId, children: (view.nodes ?? []).map((node) => (_jsx(NodeRenderer, { definition: node, parentPath: "" }, node.id))) }));
 }

package/lib/types.d.ts

@@ -1,31 +1,71 @@
 import type { ViewNode, NodeValue } from '@continuum-dev/contract';
 import type { SessionOptions } from '@continuum-dev/session';
 import type { ComponentType } from 'react';
+/**
+ * Props passed to node renderer components in the Continuum map.
+ *
+ * @template T Node value shape consumed by the component.
+ */
 export interface ContinuumNodeProps<T = NodeValue> {
+    /** Current node value from session state. */
     value: T | undefined;
+    /** Writes a new node value into session state. */
     onChange: (value: T) => void;
+    /** Raw node definition from the active view. */
     definition: ViewNode;
+    /** Canonical node id, including parent path for nested nodes. */
     nodeId?: string;
+    /** Rendered children for container-like nodes. */
     children?: React.ReactNode;
+    /** Additional mapped props provided by renderers/integrations. */
     [prop: string]: unknown;
 }
+/**
+ * Component registry keyed by Continuum node `type`.
+ */
 export type ContinuumNodeMap = Record<string, ComponentType<ContinuumNodeProps<any>>>;
+/**
+ * Backward-compatible alias for `ContinuumNodeProps`.
+ *
+ * @template T Node value shape consumed by the component.
+ */
 export type ContinuumComponentProps<T = NodeValue> = ContinuumNodeProps<T>;
+/**
+ * Backward-compatible alias for `ContinuumNodeMap`.
+ */
 export type ContinuumComponentMap = ContinuumNodeMap;
+/**
+ * Error metadata emitted when persistence fails in the provider.
+ */
 export interface ContinuumPersistError {
+    /** Persistence failure category. */
     reason: 'size_limit' | 'storage_error';
+    /** Storage key used for persistence. */
     key: string;
+    /** Serialized payload size in bytes. */
     attemptedBytes?: number;
+    /** Configured max byte limit for persistence. */
     maxBytes?: number;
+    /** Original error/cause when available. */
     cause?: unknown;
 }
+/**
+ * Props for `ContinuumProvider`.
+ */
 export interface ContinuumProviderProps {
+    /** Node type to component map used by `ContinuumRenderer`. */
     components: ContinuumNodeMap;
+    /** Optional browser persistence mode. */
     persist?: 'sessionStorage' | 'localStorage' | false;
+    /** Storage key for persisted session data. */
     storageKey?: string;
+    /** Maximum serialized bytes allowed for persisted payloads. */
     maxPersistBytes?: number;
+    /** Callback invoked when persistence errors occur. */
     onPersistError?: (error: ContinuumPersistError) => void;
+    /** Options forwarded to `@continuum-dev/session`. */
     sessionOptions?: SessionOptions;
+    /** React subtree that consumes Continuum context. */
     children: React.ReactNode;
 }
 //# sourceMappingURL=types.d.ts.map

package/lib/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../../packages/react/src/lib/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,SAAS,EAAE,MAAM,qBAAqB,CAAC;AAC/D,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAC;AACzD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,OAAO,CAAC;AAE3C,MAAM,WAAW,kBAAkB,CAAC,CAAC,GAAG,SAAS;IAC/C,KAAK,EAAE,CAAC,GAAG,SAAS,CAAC;IACrB,QAAQ,EAAE,CAAC,KAAK,EAAE,CAAC,KAAK,IAAI,CAAC;IAC7B,UAAU,EAAE,QAAQ,CAAC;IACrB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,QAAQ,CAAC,EAAE,KAAK,CAAC,SAAS,CAAC;IAC3B,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC;CACzB;AAED,MAAM,MAAM,gBAAgB,GAAG,MAAM,CACnC,MAAM,EACN,aAAa,CAAC,kBAAkB,CAAC,GAAG,CAAC,CAAC,CACvC,CAAC;AAEF,MAAM,MAAM,uBAAuB,CAAC,CAAC,GAAG,SAAS,IAAI,kBAAkB,CAAC,CAAC,CAAC,CAAC;AAC3E,MAAM,MAAM,qBAAqB,GAAG,gBAAgB,CAAC;AAErD,MAAM,WAAW,qBAAqB;IACpC,MAAM,EAAE,YAAY,GAAG,eAAe,CAAC;IACvC,GAAG,EAAE,MAAM,CAAC;IACZ,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,KAAK,CAAC,EAAE,OAAO,CAAC;CACjB;AAED,MAAM,WAAW,sBAAsB;IACrC,UAAU,EAAE,gBAAgB,CAAC;IAC7B,OAAO,CAAC,EAAE,gBAAgB,GAAG,cAAc,GAAG,KAAK,CAAC;IACpD,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,cAAc,CAAC,EAAE,CAAC,KAAK,EAAE,qBAAqB,KAAK,IAAI,CAAC;IACxD,cAAc,CAAC,EAAE,cAAc,CAAC;IAChC,QAAQ,EAAE,KAAK,CAAC,SAAS,CAAC;CAC3B"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../../packages/react/src/lib/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,SAAS,EAAE,MAAM,qBAAqB,CAAC;AAC/D,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAC;AACzD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,OAAO,CAAC;AAE3C;;;;GAIG;AACH,MAAM,WAAW,kBAAkB,CAAC,CAAC,GAAG,SAAS;IAC/C,6CAA6C;IAC7C,KAAK,EAAE,CAAC,GAAG,SAAS,CAAC;IACrB,kDAAkD;IAClD,QAAQ,EAAE,CAAC,KAAK,EAAE,CAAC,KAAK,IAAI,CAAC;IAC7B,gDAAgD;IAChD,UAAU,EAAE,QAAQ,CAAC;IACrB,iEAAiE;IACjE,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,kDAAkD;IAClD,QAAQ,CAAC,EAAE,KAAK,CAAC,SAAS,CAAC;IAC3B,kEAAkE;IAClE,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC;CACzB;AAED;;GAEG;AACH,MAAM,MAAM,gBAAgB,GAAG,MAAM,CACnC,MAAM,EACN,aAAa,CAAC,kBAAkB,CAAC,GAAG,CAAC,CAAC,CACvC,CAAC;AAEF;;;;GAIG;AACH,MAAM,MAAM,uBAAuB,CAAC,CAAC,GAAG,SAAS,IAAI,kBAAkB,CAAC,CAAC,CAAC,CAAC;AAC3E;;GAEG;AACH,MAAM,MAAM,qBAAqB,GAAG,gBAAgB,CAAC;AAErD;;GAEG;AACH,MAAM,WAAW,qBAAqB;IACpC,oCAAoC;IACpC,MAAM,EAAE,YAAY,GAAG,eAAe,CAAC;IACvC,wCAAwC;IACxC,GAAG,EAAE,MAAM,CAAC;IACZ,wCAAwC;IACxC,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,iDAAiD;IACjD,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,2CAA2C;IAC3C,KAAK,CAAC,EAAE,OAAO,CAAC;CACjB;AAED;;GAEG;AACH,MAAM,WAAW,sBAAsB;IACrC,8DAA8D;IAC9D,UAAU,EAAE,gBAAgB,CAAC;IAC7B,yCAAyC;IACzC,OAAO,CAAC,EAAE,gBAAgB,GAAG,cAAc,GAAG,KAAK,CAAC;IACpD,8CAA8C;IAC9C,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,+DAA+D;IAC/D,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,sDAAsD;IACtD,cAAc,CAAC,EAAE,CAAC,KAAK,EAAE,qBAAqB,KAAK,IAAI,CAAC;IACxD,iDAAiD;IACjD,cAAc,CAAC,EAAE,cAAc,CAAC;IAChC,qDAAqD;IACrD,QAAQ,EAAE,KAAK,CAAC,SAAS,CAAC;CAC3B"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@continuum-dev/react",
-  "version": "0.1.1",
+  "version": "0.1.2",
   "publishConfig": {
     "access": "public"
   },
@@ -44,7 +44,7 @@
     "react": ">=18"
   },
   "dependencies": {
-    "@continuum-dev/contract": "^0.1.1",
-    "@continuum-dev/session": "^0.1.1"
+    "@continuum-dev/contract": "^0.1.2",
+    "@continuum-dev/session": "^0.1.2"
   }
 }