@interlucent/pixel-stream-react 0.0.3 → 0.0.81

package/README.md

@@ -0,0 +1,5 @@
+# @interlucent/pixel-stream-react
+
+React bindings for the `@interlucent/pixel-stream` web component.
+
+For documentation, visit [interlucent.ai](https://interlucent.ai).

package/dist/index.d.ts

@@ -4,10 +4,11 @@
  * 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
+ * Follows the @lit/react `createComponent` pattern:
+ *  - Properties set directly on the element (not via setAttribute)
+ *  - useLayoutEffect for synchronous prop sync (before paint)
+ *  - Stable EventListener-interface objects (one addEventListener per event, ever)
+ *  - Previous-props tracking for clean removal
  */
 import React, { type RefObject } from 'react';
 import type { PixelStream as PixelStreamElement, PixelStreamStatus, ResolutionClampName, StreamResolutionClamp } from '@interlucent/pixel-stream';
@@ -141,10 +142,11 @@ export interface PixelStreamProps extends PixelStreamAttributeProps, PixelStream
 /**
  * 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
+ * Uses the same patterns as `@lit/react` / Stencil output targets:
+ * - Properties set directly on the element (preserves types)
+ * - `useLayoutEffect` for synchronous prop sync (no flash)
+ * - Stable `EventListener` interface objects (one `addEventListener` per event, ever)
+ * - Previous-props `Map` tracking for efficient diffing
  *
  * @example
  * ```tsx
@@ -158,7 +160,6 @@ export interface PixelStreamProps extends PixelStreamAttributeProps, PixelStream
  *       ref={ref}
  *       admissionToken="tok_..."
  *       onStatusChange={(e) => console.log(e.detail.newStatus)}
- *       onReady={() => console.log('ready')}
  *       style={{ width: '100%', height: '100%' }}
  *     />
  *   );

package/dist/index.js

@@ -1,17 +1,21 @@
+'use client';
 /**
  * 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
+ * Follows the @lit/react `createComponent` pattern:
+ *  - Properties set directly on the element (not via setAttribute)
+ *  - useLayoutEffect for synchronous prop sync (before paint)
+ *  - Stable EventListener-interface objects (one addEventListener per event, ever)
+ *  - Previous-props tracking for clean removal
  */
-import React, { useRef, useEffect, useState, useImperativeHandle, forwardRef, } from 'react';
+import React, { useRef, useEffect, useLayoutEffect, useState, useCallback, forwardRef, } from 'react';
 // ===== SSR guard =====
 const isBrowser = typeof window !== 'undefined';
+// useLayoutEffect warns in SSR — swap to useEffect on the server (which is a no-op anyway)
+const useIsomorphicLayoutEffect = isBrowser ? useLayoutEffect : useEffect;
 // Lazy web-component registration — called once on first mount
 let _registered = false;
 function ensureRegistered() {
@@ -58,61 +62,66 @@ const EVENT_MAP = {
     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',
+// ===== Mapping from React camelCase prop to element property name =====
+// These are set directly on the element via `el[prop] = value` (not setAttribute).
+const PROP_MAP = {
+    admissionToken: 'admissionToken',
+    appId: 'appId',
+    appVersion: 'appVersion',
+    noAutoConnect: 'noAutoConnect',
+    nativeTouch: 'nativeTouch',
+    pointerLock: 'pointerLock',
+    pointerLockRelease: 'pointerLockRelease',
+    suppressBrowserKeys: 'suppressBrowserKeys',
+    mute: 'mute',
+    volume: 'volume',
+    rendezvousPreference: 'rendezvousPreference',
+    lingerPreference: 'lingerPreference',
+    leftGracePeriod: 'leftGracePeriod',
+    apiEndpoint: 'apiEndpoint',
+    reconnectMode: 'reconnectMode',
+    reconnectAttempts: 'reconnectAttempts',
+    reconnectStrategy: 'reconnectStrategy',
+    reconnectInterval: 'reconnectInterval',
+    disconnectGraceMs: 'disconnectGraceMs',
+    resizeMode: 'resizeMode',
+    dprCap: 'dprCap',
+    resolutionClamp: 'resolutionClamp',
+    debug: 'debug',
+    logLevel: 'logLevel',
+    iceBatchDelay: 'iceBatchDelay',
+};
+// Props that must go through setAttribute (no matching JS property on the element)
+const ATTR_ONLY_MAP = {
     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',
+    controls: 'controls',
     swiftJobRequest: 'swift-job-request',
     streamerId: 'streamer-id',
+    lat: 'lat',
+    lng: 'lng',
     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)
+// Boolean attributes (for ATTR_ONLY props — 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',
+    'enableGamepad', 'enableXr', 'forceRelay', 'controls', 'swiftJobRequest',
 ]);
-// Props handled separately (not attributes or events)
-const SPECIAL_PROPS = new Set(['className', 'style', 'children']);
+// Props handled by React directly
+const REACT_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
+ * Uses the same patterns as `@lit/react` / Stencil output targets:
+ * - Properties set directly on the element (preserves types)
+ * - `useLayoutEffect` for synchronous prop sync (no flash)
+ * - Stable `EventListener` interface objects (one `addEventListener` per event, ever)
+ * - Previous-props `Map` tracking for efficient diffing
  *
  * @example
  * ```tsx
@@ -126,101 +135,140 @@ const SPECIAL_PROPS = new Set(['className', 'style', 'children']);
  *       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) {
+export const PixelStream = /*@__PURE__*/ 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]);
+    const prevPropsRef = useRef(new Map());
+    // Stable EventListener-interface objects: { handleEvent: fn }
+    // One addEventListener per event name, ever. On re-render we just swap handleEvent.
+    const eventHandlersRef = useRef(new Map());
+    // Merge internal + forwarded ref (Lit pattern)
+    const mergedRef = useCallback((node) => {
+        elementRef.current = node;
+        if (typeof ref === 'function') {
+            ref(node);
+        }
+        else if (ref && typeof ref === 'object') {
+            // eslint-disable-next-line @typescript-eslint/no-explicit-any
+            ref.current = node;
+        }
+    }, [ref]);
     // 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(() => {
+    // Sync properties + attributes + events (synchronous, before paint)
+    useIsomorphicLayoutEffect(() => {
         const el = elementRef.current;
-        if (!el || !mounted)
+        if (!el)
             return;
-        // Build desired attribute state
-        const desired = new Map();
+        const newProps = new Map();
         for (const [propName, value] of Object.entries(props)) {
-            if (SPECIAL_PROPS.has(propName) || propName in EVENT_MAP)
+            if (REACT_PROPS.has(propName))
                 continue;
-            if (!ALL_ATTR_NAMES.has(propName))
+            // --- Events ---
+            const eventName = EVENT_MAP[propName];
+            if (eventName !== undefined) {
+                let handler = eventHandlersRef.current.get(eventName);
+                if (typeof value === 'function') {
+                    if (handler === undefined) {
+                        // First time: create stable handler object, one addEventListener
+                        handler = { handleEvent: value };
+                        eventHandlersRef.current.set(eventName, handler);
+                        el.addEventListener(eventName, handler);
+                    }
+                    else {
+                        // Subsequent: just swap the function pointer
+                        handler.handleEvent = value;
+                    }
+                }
+                else if (handler !== undefined) {
+                    // Callback removed — tear down
+                    el.removeEventListener(eventName, handler);
+                    eventHandlersRef.current.delete(eventName);
+                }
                 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));
+            // --- Direct properties ---
+            const elProp = PROP_MAP[propName];
+            if (elProp !== undefined) {
+                const prev = prevPropsRef.current.get(propName);
+                if (value !== prev) {
+                    el[elProp] = value;
+                }
+                newProps.set(propName, value);
+                continue;
             }
-        }
-        // Set desired attributes
-        for (const [attr, value] of desired) {
-            if (el.getAttribute(attr) !== value) {
-                el.setAttribute(attr, value);
+            // --- Attribute-only props ---
+            const attrName = ATTR_ONLY_MAP[propName];
+            if (attrName !== undefined) {
+                const prev = prevPropsRef.current.get(propName);
+                if (value !== prev) {
+                    if (BOOLEAN_ATTRS.has(propName)) {
+                        if (value) {
+                            el.setAttribute(attrName, '');
+                        }
+                        else {
+                            el.removeAttribute(attrName);
+                        }
+                    }
+                    else if (value != null) {
+                        el.setAttribute(attrName, String(value));
+                    }
+                    else {
+                        el.removeAttribute(attrName);
+                    }
+                }
+                newProps.set(propName, value);
+                continue;
             }
         }
-        // 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)) {
+        // Unset any props that were present last render but are gone now
+        for (const [propName, prevValue] of prevPropsRef.current) {
+            if (newProps.has(propName))
+                continue;
+            const elProp = PROP_MAP[propName];
+            if (elProp !== undefined) {
+                el[elProp] = undefined;
+                continue;
+            }
+            const attrName = ATTR_ONLY_MAP[propName];
+            if (attrName !== undefined) {
                 el.removeAttribute(attrName);
+                continue;
+            }
+            // Removed event callback
+            const eventName = EVENT_MAP[propName];
+            if (eventName !== undefined && prevValue !== undefined) {
+                const handler = eventHandlersRef.current.get(eventName);
+                if (handler) {
+                    el.removeEventListener(eventName, handler);
+                    eventHandlersRef.current.delete(eventName);
+                }
             }
         }
+        prevPropsRef.current = newProps;
     });
-    // On the server, render a bare <pixel-stream> tag.
-    // On the client, also render <pixel-stream> and let effects handle attrs/events.
+    // Clean up all event listeners on unmount
+    useEffect(() => {
+        return () => {
+            const el = elementRef.current;
+            if (!el)
+                return;
+            for (const [eventName, handler] of eventHandlersRef.current) {
+                el.removeEventListener(eventName, handler);
+            }
+            eventHandlersRef.current.clear();
+        };
+    }, []);
     return React.createElement('pixel-stream', {
-        ref: elementRef,
-        className: props.className,
+        ref: mergedRef,
+        class: props.className,
         style: props.style,
         suppressHydrationWarning: true,
     }, props.children);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@interlucent/pixel-stream-react",
-  "version": "0.0.3",
+  "version": "0.0.81",
   "description": "React bindings for the @interlucent/pixel-stream web component",
   "type": "module",
   "main": "./dist/index.js",
@@ -18,18 +18,15 @@
     "dist",
     "README.md"
   ],
-  "scripts": {
-    "build": "tsc -p tsconfig.build.json"
-  },
   "peerDependencies": {
     "@interlucent/pixel-stream": ">=0.0.79",
     "react": ">=18.0.0"
   },
   "devDependencies": {
-    "@interlucent/pixel-stream": "workspace:*",
     "@types/react": "^18.0.0",
     "react": "^18.0.0",
-    "typescript": "^5.3.0"
+    "typescript": "^5.3.0",
+    "@interlucent/pixel-stream": "0.0.82"
   },
   "keywords": [
     "pixel-streaming",
@@ -42,5 +39,8 @@
   "license": "UNLICENSED",
   "publishConfig": {
     "access": "public"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json"
   }
-}
+}