Module @hiyve/react-semantic-relay

@hiyve/react-semantic-relay — React provider + hooks for the Hiyve Semantic Relay (WebTransport datagram service).

Wraps @hiyve/semantic-relay-client with a context provider that owns the client lifecycle, plus a topic-scoped pub/sub hook for everyday use.

Example

import { SemanticRelayProvider, useRelayTopic } from '@hiyve/react-semantic-relay';

function App() {
  return (
    <SemanticRelayProvider
      url="https://semantic.hiyve.tv:4443/relay"
      roomId="lesson-abc"
      userId="alice@example.com"
      token={jwt}
      serverCertificateHashes={certHashes}
    >
      <Instruments />
    </SemanticRelayProvider>
  );
}

function Instruments() {
  const { publish, subscribe } = useRelayTopic<{ midi: number; on: boolean }>('instrument-notes');
  useEffect(() => subscribe(({ payload, userId }) => console.log(userId, payload)), [subscribe]);
  return <button onClick={() => publish({ midi: 60, on: true })}>Play C</button>;
}

@hiyve/react-semantic-relay

React provider + hooks for the Hiyve Semantic Relay — high-frequency, fire-and-forget, room-scoped messaging via WebTransport datagrams.

Installation

npm install @hiyve/react-semantic-relay @hiyve/semantic-relay-client

Quick start

import { SemanticRelayProvider, useRelayTopic } from '@hiyve/react-semantic-relay';

function App() {
  return (
    <SemanticRelayProvider
      url="https://semantic.hiyve.tv:4443/relay"
      roomId="lesson-abc"
      userId="alice@example.com"
      token={jwtFromBackend}
      serverCertificateHashes={certHashes}
    >
      <Instruments />
    </SemanticRelayProvider>
  );
}

function Instruments() {
  const { publish, subscribe, isConnected } = useRelayTopic<{ midi: number; on: boolean }>(
    'instrument-notes',
  );

  useEffect(() => subscribe(({ payload, userId }) => {
    console.log(`${userId} played`, payload);
  }), [subscribe]);

  return (
    <button disabled={!isConnected} onClick={() => publish({ midi: 60, on: true })}>
      Play C
    </button>
  );
}

Requirements

A running Hiyve Semantic Relay server reachable over WebTransport (HTTPS/3).
A short-lived JWT minted by your backend, scoped to a roomId + userId.
For self-signed development certs, the SHA-256 certificate hashes (serverCertificateHashes) — browsers refuse to connect over WebTransport without this when not using a public CA.
Modern browser with WebTransport support (Chrome / Edge stable; Firefox / Safari support varies — check current compatibility).
Peer dependencies: react ^18, @hiyve/semantic-relay-client.

API

`<SemanticRelayProvider>`

Provides a relay connection to descendants. Reconnects automatically when connection identity (url / roomId / userId / token) changes.

Prop	Type	Required	Description
`url`	`string`	yes	Base WebTransport URL.
`roomId`	`string`	yes	Room identifier.
`userId`	`string`	yes	Sender identity attached to every published message.
`token`	`string`	yes	Short-lived auth token minted by your backend.
`serverCertificateHashes`	`RelayCertHash[]`	no	SHA-256 certificate hashes for self-signed dev certs. See WebTransport docs for derivation.
`disabled`	`boolean`	no	When `true`, the provider does not connect.
`onError`	`(error: Error) => void`	no	Called on connection or transport errors.
`onConnectionChange`	`(state: RelayConnectionState) => void`	no	Called whenever the connection state changes.
`onDebug`	`(message: string) => void`	no	Optional debug callback for diagnostic output.
`maxSeenMessages`	`number`	no	Cap for the deduplication ring buffer.
`pruneCount`	`number`	no	Number of entries pruned when the ring buffer is full.
`retryDelaysMs`	`number[]`	no	Custom backoff schedule for reconnection attempts.

`useSemanticRelay()`

Returns { client, state, session, isConnected, error }. Use this for lower-level access — most consumers only need useRelayTopic.

`useRelayTopic<T>(topic)`

Returns { publish, subscribe, isConnected }. The subscribe callback returns an unsubscribe function suitable for a useEffect cleanup.

Key Types

Type	Description
`SemanticRelayProviderProps`	Props accepted by `<SemanticRelayProvider>`.
`UseSemanticRelayResult`	Return shape of `useSemanticRelay()`.
`UseRelayTopicResult<T>`	Return shape of `useRelayTopic<T>()`.
`RelayConnectionState`	Connection state reported by the provider (`'idle' \| 'connecting' \| 'connected' \| 'error' \| 'closed'`).
`RelayMessage<T>`	Shape of a received message: `{ topic, payload, userId, ... }`.
`RelaySubscribeHandler<T>`	Callback signature for `subscribe`.
`SessionInfo`	Session metadata returned by the relay (e.g. server-stamped session id).

License

MIT

Interfaces

RelayMessage
RelaySubProtocolMessageMeta
SemanticRelayProviderProps
SessionInfo
UseRelaySnapshotExchangeOptions
UseRelaySubProtocolOptions
UseRelaySubProtocolResult
UseRelayTopicResult
UseSemanticRelayResult

Type Aliases

RelayConnectionState
RelaySubscribeHandler

Variables

SemanticRelayProvider

Functions

isRelaySupported
useRelaySnapshotExchange
useRelayStoreBridge
useRelaySubProtocol
useRelayTopic
useSemanticRelay
useSemanticRelayContext