@interlucent/pixel-stream-react 0.0.1

package/dist/index.d.ts

@@ -0,0 +1,253 @@
+/**
+ * React bindings for the <pixel-stream> web component.
+ *
+ * SSR-safe: renders an empty <pixel-stream> tag on the server, hydrates
+ * on the client by lazily importing the web component definition.
+ *
+ * Provides:
+ *  - A <PixelStream> React component with typed props and event callbacks
+ *  - JSX IntrinsicElements augmentation so bare <pixel-stream> also type-checks
+ *  - Re-exports of key types from @interlucent/pixel-stream
+ */
+import React, { type RefObject } from 'react';
+import type { PixelStream as PixelStreamElement, PixelStreamStatus, ResolutionClampName, StreamResolutionClamp } from '@interlucent/pixel-stream';
+export type { PixelStreamStatus, ResolutionClampName, StreamResolutionClamp, } from '@interlucent/pixel-stream';
+export interface ChangeDetail<T = string | null> {
+    oldValue: T;
+    newValue: T;
+}
+export interface SessionStateChangeDetail {
+    oldState: string;
+    newState: string;
+}
+export interface StreamStateChangeDetail {
+    oldState: string;
+    newState: string;
+    detail?: string;
+}
+export interface StatusChangeDetail {
+    oldStatus: PixelStreamStatus;
+    newStatus: PixelStreamStatus;
+}
+export interface SessionErrorDetail {
+    message: string;
+    code?: string;
+}
+export interface AdmissionErrorDetail {
+    reason: string;
+}
+export interface StreamResolutionChangeDetail {
+    width: number;
+    height: number;
+    clamp?: StreamResolutionClamp | null;
+}
+export interface PeerDetail {
+    peerId: string;
+}
+export interface MuteChangeDetail {
+    oldValue: boolean;
+    newValue: boolean;
+    muted: boolean;
+}
+export interface PermissionChangeDetail {
+    permission: string;
+    status: string;
+}
+export interface ResizeModeDetectedDetail {
+    mode: string;
+}
+export interface XRStreamDetectedDetail {
+    isXRStream: boolean;
+}
+export interface PixelStreamEventProps {
+    onReady?: (e: CustomEvent) => void;
+    onAdmissionTokenChange?: (e: CustomEvent<ChangeDetail>) => void;
+    onAppIdChange?: (e: CustomEvent<ChangeDetail>) => void;
+    onAppVersionChange?: (e: CustomEvent<ChangeDetail>) => void;
+    onAdmitted?: (e: CustomEvent) => void;
+    onAdmissionRevoked?: (e: CustomEvent) => void;
+    onAdmissionError?: (e: CustomEvent<AdmissionErrorDetail>) => void;
+    onNoAutoConnectChange?: (e: CustomEvent<ChangeDetail<boolean>>) => void;
+    onSessionStateChange?: (e: CustomEvent<SessionStateChangeDetail>) => void;
+    onSessionError?: (e: CustomEvent<SessionErrorDetail>) => void;
+    onJobStateChange?: (e: CustomEvent) => void;
+    onStreamStateChange?: (e: CustomEvent<StreamStateChangeDetail>) => void;
+    onStreamResolutionChange?: (e: CustomEvent<StreamResolutionChangeDetail>) => void;
+    onStatusChange?: (e: CustomEvent<StatusChangeDetail>) => void;
+    onRendezvousStarted?: (e: CustomEvent) => void;
+    onRendezvousTimeout?: (e: CustomEvent) => void;
+    onRendezvousCancelled?: (e: CustomEvent) => void;
+    onLingerStarted?: (e: CustomEvent) => void;
+    onLingerTimeout?: (e: CustomEvent) => void;
+    onLingerCancelled?: (e: CustomEvent) => void;
+    onPeerConnected?: (e: CustomEvent<PeerDetail>) => void;
+    onPeerDisconnected?: (e: CustomEvent<PeerDetail>) => void;
+    onMuteChange?: (e: CustomEvent<MuteChangeDetail>) => void;
+    onVolumeChange?: (e: CustomEvent<ChangeDetail<number>>) => void;
+    onPermissionChange?: (e: CustomEvent<PermissionChangeDetail>) => void;
+    onRendezvousPreferenceChange?: (e: CustomEvent<ChangeDetail<number | null>>) => void;
+    onLingerPreferenceChange?: (e: CustomEvent<ChangeDetail<number | null>>) => void;
+    onLeftGracePeriodChange?: (e: CustomEvent<ChangeDetail<number | null>>) => void;
+    onApiEndpointChange?: (e: CustomEvent<ChangeDetail>) => void;
+    onResizeModeDetected?: (e: CustomEvent<ResizeModeDetectedDetail>) => void;
+    onXRStreamDetected?: (e: CustomEvent<XRStreamDetectedDetail>) => void;
+    onLog?: (e: CustomEvent) => void;
+}
+export interface PixelStreamAttributeProps {
+    admissionToken?: string | null;
+    appId?: string | null;
+    appVersion?: string | null;
+    noAutoConnect?: boolean;
+    nativeTouch?: boolean;
+    pointerLock?: boolean;
+    pointerLockRelease?: boolean;
+    suppressBrowserKeys?: boolean;
+    enableGamepad?: boolean;
+    enableXr?: boolean;
+    mute?: boolean;
+    volume?: number;
+    rendezvousPreference?: number;
+    lingerPreference?: number;
+    leftGracePeriod?: number;
+    apiEndpoint?: string;
+    forceRelay?: boolean;
+    queueWaitTolerance?: number;
+    webrtcNegotiationTolerance?: number;
+    reconnectMode?: 'none' | 'recover' | 'always';
+    reconnectAttempts?: number;
+    reconnectStrategy?: 'periodic' | 'exponential-backoff';
+    reconnectInterval?: number;
+    disconnectGraceMs?: number;
+    resizeMode?: 'none' | 'auto' | 'pureweb' | 'pre-5.4' | '5.4+';
+    dprCap?: number;
+    resolutionClamp?: ResolutionClampName;
+    debug?: boolean;
+    controls?: boolean;
+    swiftJobRequest?: boolean;
+    streamerId?: string;
+    lat?: number;
+    lng?: number;
+    streamQuality?: 'low-latency' | 'balanced' | 'quality';
+    videoBitrateMin?: number;
+    videoBitrateStart?: number;
+    videoBitrateMax?: number;
+    logLevel?: 'error' | 'warn' | 'info' | 'debug';
+}
+export interface PixelStreamProps extends PixelStreamAttributeProps, PixelStreamEventProps {
+    className?: string;
+    style?: React.CSSProperties;
+    children?: React.ReactNode;
+}
+/**
+ * React component wrapping the `<pixel-stream>` web component.
+ *
+ * - SSR-safe: renders `<pixel-stream>` on the server (no crash), hydrates on client
+ * - Full typed props for all 51 HTML attributes
+ * - Event callbacks for all custom events (`onStatusChange`, `onReady`, etc.)
+ * - Ref forwarding — access the underlying element for imperative methods
+ *
+ * @example
+ * ```tsx
+ * import { PixelStream } from '@interlucent/pixel-stream-react';
+ *
+ * function App() {
+ *   const ref = useRef<PixelStreamElement>(null);
+ *
+ *   return (
+ *     <PixelStream
+ *       ref={ref}
+ *       admissionToken="tok_..."
+ *       onStatusChange={(e) => console.log(e.detail.newStatus)}
+ *       onReady={() => console.log('ready')}
+ *       style={{ width: '100%', height: '100%' }}
+ *     />
+ *   );
+ * }
+ * ```
+ */
+export declare const PixelStream: React.ForwardRefExoticComponent<PixelStreamProps & React.RefAttributes<PixelStreamElement>>;
+/**
+ * Convenience hook providing a typed ref for the `<pixel-stream>` element.
+ *
+ * @example
+ * ```tsx
+ * function App() {
+ *   const psRef = usePixelStreamRef();
+ *   return <PixelStream ref={psRef} admissionToken="tok_..." />;
+ * }
+ * ```
+ */
+export declare function usePixelStreamRef(): RefObject<PixelStreamElement | null>;
+/**
+ * Hook that tracks the `status` of a `<pixel-stream>` element reactively.
+ *
+ * @example
+ * ```tsx
+ * function App() {
+ *   const psRef = usePixelStreamRef();
+ *   const status = usePixelStreamStatus(psRef);
+ *   return (
+ *     <div>
+ *       <PixelStream ref={psRef} admissionToken="tok_..." />
+ *       <p>Status: {status}</p>
+ *     </div>
+ *   );
+ * }
+ * ```
+ */
+export declare function usePixelStreamStatus(ref: RefObject<PixelStreamElement | null>): PixelStreamStatus;
+type PixelStreamHTMLAttributes = {
+    'admission-token'?: string;
+    'app-id'?: string;
+    'app-version'?: string;
+    'no-auto-connect'?: boolean | string;
+    'native-touch'?: boolean | string;
+    'pointer-lock'?: boolean | string;
+    'pointer-lock-release'?: boolean | string;
+    'suppress-browser-keys'?: boolean | string;
+    'enable-gamepad'?: boolean | string;
+    'enable-xr'?: boolean | string;
+    mute?: boolean | string;
+    volume?: number | string;
+    'rendezvous-preference'?: number | string;
+    'linger-preference'?: number | string;
+    'left-grace-period'?: number | string;
+    'api-endpoint'?: string;
+    'force-relay'?: boolean | string;
+    'queue-wait-tolerance'?: number | string;
+    'webrtc-negotiation-tolerance'?: number | string;
+    'reconnect-mode'?: 'none' | 'recover' | 'always';
+    'reconnect-attempts'?: number | string;
+    'reconnect-strategy'?: 'periodic' | 'exponential-backoff';
+    'reconnect-interval'?: number | string;
+    'disconnect-grace-ms'?: number | string;
+    'resize-mode'?: 'none' | 'auto' | 'pureweb' | 'pre-5.4' | '5.4+';
+    'dpr-cap'?: number | string;
+    'resolution-clamp'?: ResolutionClampName;
+    debug?: boolean | string;
+    controls?: boolean | string;
+    'swift-job-request'?: boolean | string;
+    'streamer-id'?: string;
+    lat?: number | string;
+    lng?: number | string;
+    'stream-quality'?: 'low-latency' | 'balanced' | 'quality';
+    'video-bitrate-min'?: number | string;
+    'video-bitrate-start'?: number | string;
+    'video-bitrate-max'?: number | string;
+    'log-level'?: 'error' | 'warn' | 'info' | 'debug';
+    class?: string;
+    className?: string;
+    id?: string;
+    style?: React.CSSProperties | string;
+    slot?: string;
+    children?: React.ReactNode;
+    ref?: React.Ref<PixelStreamElement>;
+    suppressHydrationWarning?: boolean;
+};
+declare global {
+    namespace JSX {
+        interface IntrinsicElements {
+            'pixel-stream': PixelStreamHTMLAttributes;
+        }
+    }
+}

package/dist/index.js

@@ -0,0 +1,283 @@
+/**
+ * React bindings for the <pixel-stream> web component.
+ *
+ * SSR-safe: renders an empty <pixel-stream> tag on the server, hydrates
+ * on the client by lazily importing the web component definition.
+ *
+ * Provides:
+ *  - A <PixelStream> React component with typed props and event callbacks
+ *  - JSX IntrinsicElements augmentation so bare <pixel-stream> also type-checks
+ *  - Re-exports of key types from @interlucent/pixel-stream
+ */
+import React, { useRef, useEffect, useState, useImperativeHandle, forwardRef, } from 'react';
+// ===== SSR guard =====
+const isBrowser = typeof window !== 'undefined';
+// Lazy web-component registration — called once on first mount
+let _registered = false;
+function ensureRegistered() {
+    if (_registered || !isBrowser)
+        return;
+    _registered = true;
+    // Dynamic import so Node.js never evaluates the web component at module scope
+    import('@interlucent/pixel-stream').catch(() => {
+        // Web component already registered or unavailable — not fatal
+    });
+}
+// ===== Mapping from callback prop to DOM event name =====
+const EVENT_MAP = {
+    onReady: 'ready',
+    onAdmissionTokenChange: 'admission-token-change',
+    onAppIdChange: 'app-id-change',
+    onAppVersionChange: 'app-version-change',
+    onAdmitted: 'admitted',
+    onAdmissionRevoked: 'admission-revoked',
+    onAdmissionError: 'admission-error',
+    onNoAutoConnectChange: 'no-auto-connect-change',
+    onSessionStateChange: 'session-state-change',
+    onSessionError: 'session-error',
+    onJobStateChange: 'job-state-change',
+    onStreamStateChange: 'stream-state-change',
+    onStreamResolutionChange: 'stream-resolution-change',
+    onStatusChange: 'status-change',
+    onRendezvousStarted: 'rendezvous-started',
+    onRendezvousTimeout: 'rendezvous-timeout',
+    onRendezvousCancelled: 'rendezvous-cancelled',
+    onLingerStarted: 'linger-started',
+    onLingerTimeout: 'linger-timeout',
+    onLingerCancelled: 'linger-cancelled',
+    onPeerConnected: 'peer-connected',
+    onPeerDisconnected: 'peer-disconnected',
+    onMuteChange: 'mute-change',
+    onVolumeChange: 'volume-change',
+    onPermissionChange: 'permission-change',
+    onRendezvousPreferenceChange: 'rendezvous-preference-change',
+    onLingerPreferenceChange: 'linger-preference-change',
+    onLeftGracePeriodChange: 'left-grace-period-change',
+    onApiEndpointChange: 'api-endpoint-change',
+    onResizeModeDetected: 'resize-mode-detected',
+    onXRStreamDetected: 'xr-stream-detected',
+    onLog: 'interlucent:log',
+};
+// ===== Mapping from React prop to HTML attribute =====
+const ATTR_MAP = {
+    admissionToken: 'admission-token',
+    appId: 'app-id',
+    appVersion: 'app-version',
+    noAutoConnect: 'no-auto-connect',
+    nativeTouch: 'native-touch',
+    pointerLock: 'pointer-lock',
+    pointerLockRelease: 'pointer-lock-release',
+    suppressBrowserKeys: 'suppress-browser-keys',
+    enableGamepad: 'enable-gamepad',
+    enableXr: 'enable-xr',
+    forceRelay: 'force-relay',
+    queueWaitTolerance: 'queue-wait-tolerance',
+    webrtcNegotiationTolerance: 'webrtc-negotiation-tolerance',
+    reconnectMode: 'reconnect-mode',
+    reconnectAttempts: 'reconnect-attempts',
+    reconnectStrategy: 'reconnect-strategy',
+    reconnectInterval: 'reconnect-interval',
+    disconnectGraceMs: 'disconnect-grace-ms',
+    resizeMode: 'resize-mode',
+    dprCap: 'dpr-cap',
+    resolutionClamp: 'resolution-clamp',
+    swiftJobRequest: 'swift-job-request',
+    streamerId: 'streamer-id',
+    streamQuality: 'stream-quality',
+    videoBitrateMin: 'video-bitrate-min',
+    videoBitrateStart: 'video-bitrate-start',
+    videoBitrateMax: 'video-bitrate-max',
+    logLevel: 'log-level',
+    rendezvousPreference: 'rendezvous-preference',
+    lingerPreference: 'linger-preference',
+    leftGracePeriod: 'left-grace-period',
+    apiEndpoint: 'api-endpoint',
+};
+// Props that are boolean HTML attributes (presence = true, absence = false)
+const BOOLEAN_ATTRS = new Set([
+    'noAutoConnect', 'nativeTouch', 'pointerLock', 'pointerLockRelease',
+    'suppressBrowserKeys', 'enableGamepad', 'enableXr', 'mute', 'debug',
+    'controls', 'forceRelay', 'swiftJobRequest',
+]);
+// All known attribute prop names (for removal tracking)
+const ALL_ATTR_NAMES = new Set([
+    ...Object.keys(ATTR_MAP),
+    'mute', 'volume', 'debug', 'controls', 'lat', 'lng',
+]);
+// Props handled separately (not attributes or events)
+const SPECIAL_PROPS = new Set(['className', 'style', 'children']);
+/**
+ * React component wrapping the `<pixel-stream>` web component.
+ *
+ * - SSR-safe: renders `<pixel-stream>` on the server (no crash), hydrates on client
+ * - Full typed props for all 51 HTML attributes
+ * - Event callbacks for all custom events (`onStatusChange`, `onReady`, etc.)
+ * - Ref forwarding — access the underlying element for imperative methods
+ *
+ * @example
+ * ```tsx
+ * import { PixelStream } from '@interlucent/pixel-stream-react';
+ *
+ * function App() {
+ *   const ref = useRef<PixelStreamElement>(null);
+ *
+ *   return (
+ *     <PixelStream
+ *       ref={ref}
+ *       admissionToken="tok_..."
+ *       onStatusChange={(e) => console.log(e.detail.newStatus)}
+ *       onReady={() => console.log('ready')}
+ *       style={{ width: '100%', height: '100%' }}
+ *     />
+ *   );
+ * }
+ * ```
+ */
+export const PixelStream = forwardRef(function PixelStream(props, ref) {
+    const elementRef = useRef(null);
+    const [mounted, setMounted] = useState(false);
+    // Expose the raw element to the parent ref
+    useImperativeHandle(ref, () => elementRef.current, [mounted]);
+    // Register the web component on first client mount
+    useEffect(() => {
+        ensureRegistered();
+        setMounted(true);
+    }, []);
+    // Sync custom event listeners.
+    // We store the latest props in a ref so the effect doesn't need to
+    // teardown/re-add listeners on every render — only when the set of
+    // subscribed event names changes.
+    const propsRef = useRef(props);
+    propsRef.current = props;
+    // Compute which event names are currently subscribed
+    const activeEvents = Object.keys(EVENT_MAP)
+        .filter(k => typeof props[k] === 'function')
+        .join(',');
+    useEffect(() => {
+        const el = elementRef.current;
+        if (!el || !mounted)
+            return;
+        const listeners = [];
+        for (const [propName, eventName] of Object.entries(EVENT_MAP)) {
+            const handler = propsRef.current[propName];
+            if (typeof handler !== 'function')
+                continue;
+            // Wrap so we always call the latest prop version
+            const wrapped = (e) => {
+                const fn = propsRef.current[propName];
+                if (typeof fn === 'function')
+                    fn(e);
+            };
+            el.addEventListener(eventName, wrapped);
+            listeners.push([eventName, wrapped]);
+        }
+        return () => {
+            for (const [eventName, handler] of listeners) {
+                el.removeEventListener(eventName, handler);
+            }
+        };
+        // eslint-disable-next-line react-hooks/exhaustive-deps
+    }, [mounted, activeEvents]);
+    // Sync HTML attributes from props
+    useEffect(() => {
+        const el = elementRef.current;
+        if (!el || !mounted)
+            return;
+        // Build desired attribute state
+        const desired = new Map();
+        for (const [propName, value] of Object.entries(props)) {
+            if (SPECIAL_PROPS.has(propName) || propName in EVENT_MAP)
+                continue;
+            if (!ALL_ATTR_NAMES.has(propName))
+                continue;
+            const attrName = ATTR_MAP[propName] ?? propName;
+            if (BOOLEAN_ATTRS.has(propName)) {
+                if (value)
+                    desired.set(attrName, '');
+            }
+            else if (value != null) {
+                desired.set(attrName, String(value));
+            }
+        }
+        // Set desired attributes
+        for (const [attr, value] of desired) {
+            if (el.getAttribute(attr) !== value) {
+                el.setAttribute(attr, value);
+            }
+        }
+        // Remove attributes that are no longer in props
+        const allKnownAttrNames = [
+            ...Object.values(ATTR_MAP),
+            'mute', 'volume', 'debug', 'controls', 'lat', 'lng',
+        ];
+        for (const attrName of allKnownAttrNames) {
+            if (!desired.has(attrName) && el.hasAttribute(attrName)) {
+                el.removeAttribute(attrName);
+            }
+        }
+    });
+    // On the server, render a bare <pixel-stream> tag.
+    // On the client, also render <pixel-stream> and let effects handle attrs/events.
+    return React.createElement('pixel-stream', {
+        ref: elementRef,
+        class: props.className,
+        style: props.style
+            ? Object.entries(props.style).reduce((css, [k, v]) => {
+                const kebab = k.replace(/[A-Z]/g, m => `-${m.toLowerCase()}`);
+                return `${css}${kebab}:${v};`;
+            }, '')
+            : undefined,
+        // Suppress React hydration warnings for attributes set by effects
+        suppressHydrationWarning: true,
+    }, props.children);
+});
+// ===== usePixelStreamRef hook =====
+/**
+ * Convenience hook providing a typed ref for the `<pixel-stream>` element.
+ *
+ * @example
+ * ```tsx
+ * function App() {
+ *   const psRef = usePixelStreamRef();
+ *   return <PixelStream ref={psRef} admissionToken="tok_..." />;
+ * }
+ * ```
+ */
+export function usePixelStreamRef() {
+    return useRef(null);
+}
+// ===== usePixelStreamStatus hook =====
+/**
+ * Hook that tracks the `status` of a `<pixel-stream>` element reactively.
+ *
+ * @example
+ * ```tsx
+ * function App() {
+ *   const psRef = usePixelStreamRef();
+ *   const status = usePixelStreamStatus(psRef);
+ *   return (
+ *     <div>
+ *       <PixelStream ref={psRef} admissionToken="tok_..." />
+ *       <p>Status: {status}</p>
+ *     </div>
+ *   );
+ * }
+ * ```
+ */
+export function usePixelStreamStatus(ref) {
+    const [status, setStatus] = useState('idle');
+    useEffect(() => {
+        const el = ref.current;
+        if (!el)
+            return;
+        // Read initial status
+        if (el.status)
+            setStatus(el.status);
+        const handler = (e) => {
+            setStatus(e.detail.newStatus);
+        };
+        el.addEventListener('status-change', handler);
+        return () => el.removeEventListener('status-change', handler);
+    }, [ref]);
+    return status;
+}

package/package.json

@@ -0,0 +1,47 @@
+{
+  "name": "@interlucent/pixel-stream-react",
+  "version": "0.0.1",
+  "description": "React bindings for the @interlucent/pixel-stream web component",
+  "type": "module",
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json"
+  },
+  "dependencies": {
+    "@interlucent/pixel-stream": "workspace:*"
+  },
+  "peerDependencies": {
+    "react": ">=18.0.0"
+  },
+  "devDependencies": {
+    "@types/react": "^18.0.0",
+    "react": "^18.0.0",
+    "typescript": "^5.3.0"
+  },
+  "keywords": [
+    "pixel-streaming",
+    "react",
+    "webcomponent",
+    "webrtc",
+    "interlucent"
+  ],
+  "author": "Interlucent",
+  "license": "UNLICENSED",
+  "publishConfig": {
+    "access": "public"
+  }
+}