@wholisphere.ai/react

Official React hooks + provider for the Wholisphere SDK.

Install

npm install @wholisphere.ai/react @wholisphere.ai/sdk
# (peer dependency: react >= 18)

Setup

import { WholisphereProvider } from '@wholisphere.ai/react';

export function App() {
  return (
    <WholisphereProvider apiKey={import.meta.env.VITE_WHOLISPHERE_API_KEY}>
      <Routes />
    </WholisphereProvider>
  );
}

Hooks

Every per-route hook returns { data, loading, error, run, reset }.

import { useDescribe, useSimplify } from '@wholisphere.ai/react';

export function ImageDescriber({ blob }: { blob: Blob }) {
  const { data, loading, error, run } = useDescribe();
  return (
    <div>
      <button onClick={() => run({ image: await blobToImage(blob) })} disabled={loading}>
        {loading ? 'Describing…' : 'Describe image'}
      </button>
      {error && <p role="alert">{error.message}</p>}
      {data && <p>{data.description}</p>}
    </div>
  );
}

Available hooks:

• useDescribe() — image → screen-reader narration
• useSimplify() — rewrite text at chosen reading level
• useSummarize() — overview + bullets
• useVoiceAction() — voice transcript + DOM → action plan
• useIntent() — page intent extraction
• useFindingsSubmit(), useFindingsLatest()
• useCacheInvalidate()
• useVpatGenerate()

For escape-hatch access:

import { useWholisphere } from '@wholisphere.ai/react';

const client = useWholisphere(); // the underlying Wholisphere instance
await client.telemetry.send([...]);

Why action-style hooks instead of use(...) suspense?

Most accessibility actions are user-initiated (button click, keyboard shortcut). Action hooks let the component own when the call fires. If you want auto-fetch behavior, wrap in useEffect:

const { run, data } = useFindingsLatest();
useEffect(() => {
  void run({ productName: 'Acme', productVersion: '1.0' });
}, [run]);

SSR

The hooks call fetch only inside event handlers / effects, so they're safe to render on the server. The provider is a client component (uses useMemo).