@sigx/lynx-video 0.4.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025-2026 Andreas Ekdahl
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,61 @@
+# @sigx/lynx-video
+
+Native video player component for sigx-lynx. iOS uses `AVPlayer` + `AVPlayerLayer`; Android uses `androidx.media3` (`ExoPlayer` + `PlayerView`).
+
+Registers a `<video-player>` JSX intrinsic that participates in Lynx's layout tree. The typed `<VideoPlayer>` wrapper is the recommended entry point.
+
+## Install
+
+```bash
+pnpm add @sigx/lynx-video
+```
+
+`sigx prebuild` auto-discovers the package, registers the `<video-player>` UI element on both platforms, and pulls in the `media3` Gradle deps on Android.
+
+## Usage
+
+```tsx
+import { VideoPlayer } from '@sigx/lynx-video';
+
+function ClipScreen() {
+    return () => (
+        <VideoPlayer
+            src="https://commondatastorage.googleapis.com/gtv-videos-bucket/sample/BigBuckBunny.mp4"
+            autoplay
+            controls
+            resizeMode="contain"
+            onLoad={(e) => console.log('loaded', e.detail.durationMs)}
+            onEnd={() => console.log('done')}
+            onError={(e) => console.warn(e.detail.message)}
+            style={{ width: '100%', aspectRatio: 16 / 9 }}
+        />
+    );
+}
+```
+
+## API
+
+### `<VideoPlayer>` props
+
+| Prop          | Type                                  | Notes                                                  |
+| ------------- | ------------------------------------- | ------------------------------------------------------ |
+| `src`         | `string`                              | URL or `file://` URI. Setting reloads the player.      |
+| `poster`      | `string?`                             | Image to display before the first frame.               |
+| `autoplay`    | `boolean?`                            | Begin playback as soon as the asset is ready.          |
+| `playing`     | `boolean?`                            | Drive play/pause declaratively. Re-renders flip state. |
+| `loop`        | `boolean?`                            | Restart automatically at end-of-clip.                  |
+| `muted`       | `boolean?`                            | Mute audio output.                                     |
+| `volume`      | `number?`                             | 0..1. Independent of `muted`.                          |
+| `controls`    | `boolean?`                            | Show platform-default playback controls.               |
+| `resizeMode`  | `'contain' \| 'cover' \| 'stretch'`   | Default `'contain'`.                                   |
+| `onLoad`      | `(e) => void`                         | `detail: { durationMs, width, height }`                |
+| `onEnd`       | `(e) => void`                         | Playback reached end of clip.                          |
+| `onError`     | `(e) => void`                         | `detail: { message }`                                  |
+| `onTimeUpdate`| `(e) => void`                         | ~4×/sec. `detail: { positionMs }`                      |
+
+## Gotchas
+
+- **Imperative methods** (`seek(s)`, `getStatus()`) are tracked as a v2 follow-up — they need Lynx's `UIMethodInvoker` surface, which isn't wired through sigx-lynx yet (same blocker that `WebView.goBack` and `Map.animateToRegion` are waiting on). For now, drive the player declaratively via `playing` / `src` props.
+- **App Transport Security (iOS)** — playing an `http://` (non-HTTPS) URL requires an `NSAppTransportSecurity` exception in your app's `Info.plist`. The package itself does not relax ATS.
+- **Android media3 versions** — pinned to `1.4.1`. If your app already depends on a different `media3` version, align it via Gradle resolution to avoid duplicate-class errors.
+- **AudioSession (iOS)** — when playing audio-bearing video, this component sets `AVAudioSession` to `.playback`. Apps that also use `@sigx/lynx-audio` get a separate session ref-count.

package/android/com/sigx/video/VideoPlayerBehavior.kt

@@ -0,0 +1,19 @@
+package com.sigx.video
+
+import com.lynx.tasm.behavior.Behavior
+import com.lynx.tasm.behavior.LynxContext
+import com.lynx.tasm.behavior.ui.LynxUI
+
+/**
+ * Registers the `<video-player>` JSX tag with Lynx's UI registry.
+ *
+ * Discovered by the autolinker via `signalx-module.json`'s `android.behaviors`
+ * field; the generated `GeneratedBehaviors.attachAll(builder)` calls
+ * `builder.addBehavior(VideoPlayerBehavior())` for every `LynxViewBuilder`
+ * in the app (production + dev-client path).
+ */
+class VideoPlayerBehavior : Behavior("video-player") {
+    override fun createUI(context: LynxContext): LynxUI<*> {
+        return VideoPlayerUI(context)
+    }
+}

package/android/com/sigx/video/VideoPlayerUI.kt

@@ -0,0 +1,273 @@
+package com.sigx.video
+
+import android.content.Context
+import android.net.Uri
+import android.os.Handler
+import android.os.Looper
+import androidx.annotation.OptIn
+import androidx.media3.common.MediaItem
+import androidx.media3.common.PlaybackException
+import androidx.media3.common.Player
+import androidx.media3.common.VideoSize
+import androidx.media3.common.util.UnstableApi
+import androidx.media3.exoplayer.ExoPlayer
+import androidx.media3.ui.AspectRatioFrameLayout
+import androidx.media3.ui.PlayerView
+import com.lynx.tasm.behavior.LynxContext
+import com.lynx.tasm.behavior.LynxProp
+import com.lynx.tasm.behavior.ui.LynxUI
+import com.lynx.tasm.event.LynxDetailEvent
+
+/**
+ * Native UI for the `<video-player>` JSX element on Android.
+ *
+ * Backed by `androidx.media3` (`ExoPlayer` + `PlayerView`). The PlayerView
+ * is added directly to Lynx's view tree and decoded frames render inside it.
+ *
+ * Prop / event surface (v1):
+ *   - `src`           → URL or `file://` URI
+ *   - `poster`        → image displayed before the first frame (best-effort)
+ *   - `autoplay`      → start as soon as the asset is ready
+ *   - `playing`       → declarative play/pause toggle
+ *   - `loop`          → restart at end-of-clip
+ *   - `muted`         → mute audio
+ *   - `volume`        → 0..1
+ *   - `controls`      → show PlayerView's built-in transport controls
+ *   - `resize-mode`   → contain | cover | stretch
+ *   - `bindload`      → asset metadata ready
+ *   - `bindend`       → playback finished
+ *   - `binderror`     → load / playback failure
+ *   - `bindtimeupdate` → ~4×/sec position broadcast
+ *
+ * Imperative methods (`seek`, `getStatus`) are tracked as a v2 follow-up
+ * — same UIMethodInvoker blocker as `WebView`/`Map`. Drive playback
+ * declaratively via the `playing` / `src` props.
+ */
+@OptIn(UnstableApi::class)
+class VideoPlayerUI(context: LynxContext) : LynxUI<PlayerView>(context) {
+
+    companion object {
+        private const val TIME_UPDATE_INTERVAL_MS = 250L
+    }
+
+    private var exoPlayer: ExoPlayer? = null
+    private val handler = Handler(Looper.getMainLooper())
+    private var didEmitLoad = false
+
+    // Pending prop values applied either at createView() time or once the
+    // player transitions to STATE_READY (autoplay, playing, muted, volume).
+    private var pendingSrc: String? = null
+    private var pendingAutoplay = false
+    private var pendingPlaying: Boolean? = null
+    private var pendingLoop = false
+    private var pendingMuted = false
+    private var pendingVolume = 1f
+    private var pendingControls = false
+    private var pendingResizeMode = AspectRatioFrameLayout.RESIZE_MODE_FIT
+
+    private val timeUpdateRunnable = object : Runnable {
+        override fun run() {
+            // Self-rescheduling loop, but only while actively playing —
+            // otherwise we'd keep waking the main thread every 250 ms
+            // forever while the user is on a paused / ended clip.
+            // `onIsPlayingChanged` re-arms us when playback resumes.
+            val player = exoPlayer ?: return
+            if (!player.isPlaying) return
+            fireEvent("timeupdate", mapOf("positionMs" to player.currentPosition.coerceAtLeast(0L)))
+            handler.postDelayed(this, TIME_UPDATE_INTERVAL_MS)
+        }
+    }
+
+    override fun createView(context: Context): PlayerView {
+        val view = PlayerView(context)
+        view.useController = pendingControls
+        view.resizeMode = pendingResizeMode
+
+        val player = ExoPlayer.Builder(context).build()
+        player.volume = if (pendingMuted) 0f else pendingVolume
+        player.repeatMode = if (pendingLoop) Player.REPEAT_MODE_ONE else Player.REPEAT_MODE_OFF
+        player.addListener(playerListener)
+        view.player = player
+        exoPlayer = player
+
+        pendingSrc?.let { loadSource(it) }
+        return view
+    }
+
+    override fun onDetach() {
+        super.onDetach()
+        handler.removeCallbacks(timeUpdateRunnable)
+        runCatching { exoPlayer?.release() }
+        exoPlayer = null
+    }
+
+    private val playerListener = object : Player.Listener {
+        override fun onPlaybackStateChanged(state: Int) {
+            when (state) {
+                Player.STATE_READY -> {
+                    if (!didEmitLoad) {
+                        didEmitLoad = true
+                        val player = exoPlayer ?: return
+                        val duration = if (player.duration == androidx.media3.common.C.TIME_UNSET) 0L
+                                       else player.duration.coerceAtLeast(0L)
+                        // Video size may not be reported synchronously on
+                        // every codec — `onVideoSizeChanged` follows up.
+                        val size = player.videoSize
+                        fireEvent(
+                            "load",
+                            mapOf(
+                                "durationMs" to duration,
+                                "width" to size.width,
+                                "height" to size.height,
+                            ),
+                        )
+                        applyQueuedPlayState()
+                    }
+                }
+                Player.STATE_ENDED -> {
+                    // ExoPlayer.REPEAT_MODE_ONE handles looping natively, so
+                    // reaching STATE_ENDED means we truly finished.
+                    fireEvent("end", emptyMap())
+                }
+                else -> {}
+            }
+        }
+
+        override fun onIsPlayingChanged(isPlaying: Boolean) {
+            handler.removeCallbacks(timeUpdateRunnable)
+            if (isPlaying) {
+                handler.postDelayed(timeUpdateRunnable, TIME_UPDATE_INTERVAL_MS)
+            }
+        }
+
+        override fun onPlayerError(error: PlaybackException) {
+            fireEvent("error", mapOf("message" to (error.message ?: "Playback error")))
+        }
+
+        override fun onVideoSizeChanged(videoSize: VideoSize) {
+            // The initial bindload may have reported width/height=0 if the
+            // codec hadn't decoded a frame yet. We don't re-fire bindload
+            // here — apps that need the post-decode size can observe the
+            // element's measured layout. (Lynx fires `bindlayoutchange`
+            // through LynxCommonAttributes for that.)
+        }
+    }
+
+    // ── Prop setters ─────────────────────────────────────────────────────
+
+    @LynxProp(name = "src")
+    fun setSrc(value: String?) {
+        if (value.isNullOrEmpty()) {
+            // Clearing the prop must stop and unload the current item —
+            // otherwise a re-render that drops `src` would keep the
+            // previous clip playing. We stop the timer loop and clear
+            // any pending media item.
+            pendingSrc = null
+            didEmitLoad = false
+            handler.removeCallbacks(timeUpdateRunnable)
+            exoPlayer?.let { player ->
+                try { player.stop() } catch (_: Throwable) {}
+                try { player.clearMediaItems() } catch (_: Throwable) {}
+            }
+            return
+        }
+        pendingSrc = value
+        if (exoPlayer != null) loadSource(value)
+    }
+
+    @LynxProp(name = "poster")
+    fun setPoster(value: String?) {
+        // Best-effort: when a poster URL is provided we set it as the
+        // PlayerView's defaultArtwork via the artwork display flag once we
+        // get a frame. v1 keeps this minimal — apps that need a poster
+        // render an <image> sibling instead and toggle visibility on
+        // `bindload`.
+    }
+
+    @LynxProp(name = "autoplay")
+    fun setAutoplay(value: Boolean) {
+        pendingAutoplay = value
+        val player = exoPlayer ?: return
+        if (value && player.playbackState == Player.STATE_READY) {
+            player.playWhenReady = true
+            player.play()
+        }
+    }
+
+    @LynxProp(name = "playing")
+    fun setPlaying(value: Boolean) {
+        pendingPlaying = value
+        val player = exoPlayer ?: return
+        if (player.playbackState == Player.STATE_READY) {
+            if (value) player.play() else player.pause()
+        }
+    }
+
+    @LynxProp(name = "loop")
+    fun setLoop(value: Boolean) {
+        pendingLoop = value
+        exoPlayer?.repeatMode = if (value) Player.REPEAT_MODE_ONE else Player.REPEAT_MODE_OFF
+    }
+
+    @LynxProp(name = "muted")
+    fun setMuted(value: Boolean) {
+        pendingMuted = value
+        exoPlayer?.volume = if (value) 0f else pendingVolume
+    }
+
+    @LynxProp(name = "volume")
+    fun setVolume(value: Double) {
+        val v = value.coerceIn(0.0, 1.0).toFloat()
+        pendingVolume = v
+        if (!pendingMuted) exoPlayer?.volume = v
+    }
+
+    @LynxProp(name = "controls")
+    fun setControls(value: Boolean) {
+        pendingControls = value
+        mView.useController = value
+    }
+
+    @LynxProp(name = "resize-mode")
+    fun setResizeMode(value: String?) {
+        val mode = when (value) {
+            "cover"   -> AspectRatioFrameLayout.RESIZE_MODE_ZOOM
+            "stretch" -> AspectRatioFrameLayout.RESIZE_MODE_FILL
+            else      -> AspectRatioFrameLayout.RESIZE_MODE_FIT
+        }
+        pendingResizeMode = mode
+        mView.resizeMode = mode
+    }
+
+    // ── Internals ────────────────────────────────────────────────────────
+
+    private fun loadSource(source: String) {
+        val player = exoPlayer ?: return
+        didEmitLoad = false
+        val uri = if (source.startsWith("/")) Uri.fromFile(java.io.File(source))
+                  else Uri.parse(source)
+        val item = MediaItem.fromUri(uri)
+        player.setMediaItem(item)
+        player.prepare()
+        // playWhenReady stays governed by autoplay/playing props applied
+        // after STATE_READY in `applyQueuedPlayState`.
+        player.playWhenReady = false
+    }
+
+    private fun applyQueuedPlayState() {
+        val player = exoPlayer ?: return
+        val explicit = pendingPlaying
+        when {
+            explicit == true  -> player.play()
+            explicit == false -> player.pause()
+            pendingAutoplay   -> player.play()
+            else              -> player.pause()
+        }
+    }
+
+    private fun fireEvent(name: String, params: Map<String, Any?>) {
+        val event = LynxDetailEvent(sign, name)
+        for ((k, v) in params) event.addDetail(k, v)
+        lynxContext.eventEmitter.sendCustomEvent(event)
+    }
+}

package/dist/VideoPlayer.d.ts

@@ -0,0 +1,29 @@
+import { type Define } from '@sigx/lynx';
+import './jsx-augment.js';
+import type { VideoEndEvent, VideoErrorEvent, VideoLoadEvent, VideoResizeMode, VideoTimeUpdateEvent } from './jsx-augment.js';
+export type VideoPlayerProps = Define.Prop<'src', string, false> & Define.Prop<'poster', string, false> & Define.Prop<'autoplay', boolean, false> & Define.Prop<'playing', boolean, false> & Define.Prop<'loop', boolean, false> & Define.Prop<'muted', boolean, false> & Define.Prop<'volume', number, false> & Define.Prop<'controls', boolean, false> & Define.Prop<'resizeMode', VideoResizeMode, false> & Define.Prop<'class', string, false> & Define.Prop<'style', string | Record<string, string | number>, false> & Define.Prop<'onLoad', (e: VideoLoadEvent) => void, false> & Define.Prop<'onEnd', (e: VideoEndEvent) => void, false> & Define.Prop<'onError', (e: VideoErrorEvent) => void, false> & Define.Prop<'onTimeUpdate', (e: VideoTimeUpdateEvent) => void, false>;
+/**
+ * Native video player.
+ *
+ * On iOS this wraps an `AVPlayer` inside an `AVPlayerLayer`; on Android,
+ * `androidx.media3.exoplayer.ExoPlayer` inside a `PlayerView`. The element
+ * participates in Lynx's layout tree like any other view — give it a
+ * `width` / `height` (or `aspectRatio`) and it draws decoded frames there.
+ *
+ * @example
+ * ```tsx
+ * <VideoPlayer
+ *   src="https://example.com/clip.mp4"
+ *   autoplay
+ *   controls
+ *   onLoad={(e) => console.log('dur', e.detail.durationMs)}
+ *   onEnd={() => console.log('done')}
+ *   style={{ width: '100%', aspectRatio: 16 / 9 }}
+ * />
+ * ```
+ *
+ * @remarks
+ * Imperative methods (`seek`, `getStatus`) are not yet implemented — see the
+ * package README. v1 is declarative-only via the `playing` / `src` props.
+ */
+export declare const VideoPlayer: import("@sigx/runtime-core").ComponentFactory<VideoPlayerProps, void, {}>;

package/dist/VideoPlayer.js

@@ -0,0 +1,30 @@
+import { jsx as _jsx } from "@sigx/lynx/jsx-runtime";
+import { component } from '@sigx/lynx';
+import './jsx-augment.js';
+/**
+ * Native video player.
+ *
+ * On iOS this wraps an `AVPlayer` inside an `AVPlayerLayer`; on Android,
+ * `androidx.media3.exoplayer.ExoPlayer` inside a `PlayerView`. The element
+ * participates in Lynx's layout tree like any other view — give it a
+ * `width` / `height` (or `aspectRatio`) and it draws decoded frames there.
+ *
+ * @example
+ * ```tsx
+ * <VideoPlayer
+ *   src="https://example.com/clip.mp4"
+ *   autoplay
+ *   controls
+ *   onLoad={(e) => console.log('dur', e.detail.durationMs)}
+ *   onEnd={() => console.log('done')}
+ *   style={{ width: '100%', aspectRatio: 16 / 9 }}
+ * />
+ * ```
+ *
+ * @remarks
+ * Imperative methods (`seek`, `getStatus`) are not yet implemented — see the
+ * package README. v1 is declarative-only via the `playing` / `src` props.
+ */
+export const VideoPlayer = component(({ props }) => {
+    return () => (_jsx("video-player", { src: props.src, poster: props.poster, autoplay: props.autoplay, playing: props.playing, loop: props.loop, muted: props.muted, volume: props.volume, controls: props.controls, "resize-mode": props.resizeMode, class: props.class, style: props.style, bindload: props.onLoad, bindend: props.onEnd, binderror: props.onError, bindtimeupdate: props.onTimeUpdate }));
+});

package/dist/index.d.ts

@@ -0,0 +1,4 @@
+import './jsx-augment.js';
+export { VideoPlayer } from './VideoPlayer.js';
+export type { VideoPlayerProps } from './VideoPlayer.js';
+export type { VideoPlayerAttributes, VideoResizeMode, VideoLoadEvent, VideoLoadEventDetail, VideoEndEvent, VideoEndEventDetail, VideoErrorEvent, VideoErrorEventDetail, VideoTimeUpdateEvent, VideoTimeUpdateEventDetail, } from './jsx-augment.js';

package/dist/index.js

@@ -0,0 +1,2 @@
+import './jsx-augment.js';
+export { VideoPlayer } from './VideoPlayer.js';

package/dist/jsx-augment.d.ts

@@ -0,0 +1,96 @@
+/**
+ * JSX intrinsic type augmentation for `<video-player>`.
+ *
+ * Importing this module registers `'video-player'` as a valid JSX intrinsic
+ * with the prop + event surface implemented by `VideoPlayerUI` (iOS) and
+ * `VideoPlayerUI.kt` (Android). Pulled in automatically by
+ * `@sigx/lynx-video`'s entry point so consumers do not need to import it
+ * directly.
+ *
+ * Element availability requires `sigx prebuild` to have run after adding
+ * this package as a dependency — the autolinker emits the `LynxConfig`
+ * registration (iOS) and `Behavior` attachment (Android) that bind the tag
+ * to the native UI class.
+ */
+import type { LynxCommonAttributes, LynxEventHandler } from '@sigx/lynx-runtime';
+export interface VideoLoadEventDetail {
+    /** Total duration in milliseconds. 0 if unknown (live streams). */
+    durationMs: number;
+    /** Natural width in pixels. */
+    width: number;
+    /** Natural height in pixels. */
+    height: number;
+    [k: string]: unknown;
+}
+export interface VideoLoadEvent {
+    type: 'load';
+    detail: VideoLoadEventDetail;
+}
+export interface VideoEndEventDetail {
+    [k: string]: unknown;
+}
+export interface VideoEndEvent {
+    type: 'end';
+    detail: VideoEndEventDetail;
+}
+export interface VideoErrorEventDetail {
+    message: string;
+    [k: string]: unknown;
+}
+export interface VideoErrorEvent {
+    type: 'error';
+    detail: VideoErrorEventDetail;
+}
+export interface VideoTimeUpdateEventDetail {
+    /** Current playback position in milliseconds. */
+    positionMs: number;
+    [k: string]: unknown;
+}
+export interface VideoTimeUpdateEvent {
+    type: 'timeupdate';
+    detail: VideoTimeUpdateEventDetail;
+}
+export type VideoResizeMode = 'contain' | 'cover' | 'stretch';
+export interface VideoPlayerAttributes extends LynxCommonAttributes {
+    /** URL or `file://` URI of the asset to play. */
+    src?: string;
+    /** Image displayed before the first frame is decoded. */
+    poster?: string;
+    /** Begin playback as soon as the asset is ready. Default: false. */
+    autoplay?: boolean;
+    /**
+     * Drive play/pause declaratively. `true` resumes, `false` pauses. Apps
+     * that prefer imperative control can flip a signal that drives this prop.
+     */
+    playing?: boolean;
+    /** Restart automatically at end-of-clip. Default: false. */
+    loop?: boolean;
+    /** Mute audio output, independent of `volume`. Default: false. */
+    muted?: boolean;
+    /** Output volume 0..1. Default: 1. */
+    volume?: number;
+    /** Show platform-default playback controls overlay. Default: false. */
+    controls?: boolean;
+    /** How the video frame fits inside the element box. Default: `'contain'`. */
+    'resize-mode'?: VideoResizeMode;
+    /** Fires once asset metadata is available (duration, dimensions). */
+    bindload?: LynxEventHandler<VideoLoadEvent>;
+    /** Fires when playback reaches the end of the clip (not when looping). */
+    bindend?: LynxEventHandler<VideoEndEvent>;
+    /** Fires on a non-recoverable load or playback error. */
+    binderror?: LynxEventHandler<VideoErrorEvent>;
+    /**
+     * Fires ~4×/sec while playing with the current position. Use sparingly —
+     * this crosses the bridge per call. For high-frequency animations,
+     * subscribe to the asset duration once and animate locally instead.
+     */
+    bindtimeupdate?: LynxEventHandler<VideoTimeUpdateEvent>;
+}
+declare global {
+    namespace JSX {
+        interface IntrinsicElements {
+            'video-player': VideoPlayerAttributes;
+        }
+    }
+}
+export {};

package/dist/jsx-augment.js

@@ -0,0 +1 @@
+export {};

package/ios/VideoPlayerUI.swift

@@ -0,0 +1,387 @@
+import Foundation
+import UIKit
+import AVFoundation
+import Lynx
+
+/// Native UI for the `<video-player>` JSX element.
+///
+/// Registered via the autolinker — `signalx-module.json`'s `ios.uiComponents`
+/// produces `config.registerUI(VideoPlayerUI.self, withName: "video-player")`
+/// in the generated `GeneratedComponentRegistry.swift`.
+///
+/// Prop / event surface (v1):
+///   - `src`           → URL (URL-loaded) or `file://` (local file)
+///   - `poster`        → image displayed before the first frame
+///   - `autoplay`      → start as soon as the asset is ready
+///   - `playing`       → declarative play/pause toggle
+///   - `loop`          → restart at end-of-clip
+///   - `muted`         → mute audio
+///   - `volume`        → 0..1
+///   - `controls`      → show platform-default controls overlay
+///   - `resize-mode`   → contain | cover | stretch
+///   - `bindload`      → asset metadata ready
+///   - `bindend`       → playback finished
+///   - `binderror`     → load / playback failure
+///   - `bindtimeupdate` → ~4×/sec position broadcast
+///
+/// Imperative methods (`seek`, `getStatus`) are tracked as a v2 follow-up
+/// — they need the Lynx UIMethodInvoker surface that isn't wired through
+/// sigx-lynx yet (same blocker as `WebView.goBack` / `Map.animateToRegion`).
+@objc public class VideoPlayerUI: LynxUI<UIView> {
+
+    private var player: AVPlayer?
+    private var playerLayer: AVPlayerLayer?
+    private var posterView: UIImageView?
+    private var controlsView: UIView?
+    private var timeObserver: Any?
+    private var statusObservation: NSKeyValueObservation?
+    private var didReachEndObserver: NSObjectProtocol?
+
+    // Pending prop values applied after createView() and after the asset
+    // reaches `.readyToPlay` (volume, muted, autoplay/playing).
+    private var pendingAutoplay = false
+    private var pendingPlaying: Bool?
+    private var pendingLoop = false
+    private var pendingMuted = false
+    private var pendingVolume: Float = 1.0
+    private var pendingResizeMode: AVLayerVideoGravity = .resizeAspect
+    private var pendingControls = false
+    private var pendingPosterURL: URL?
+    private var didEmitLoad = false
+
+    // MARK: - LynxUI overrides
+
+    public override func createView() -> UIView? {
+        let container = UIView(frame: .zero)
+        container.backgroundColor = .black
+        container.clipsToBounds = true
+        return container
+    }
+
+    public override func layoutDidFinished() {
+        super.layoutDidFinished()
+        guard let container = view else { return }
+        playerLayer?.frame = container.bounds
+        posterView?.frame = container.bounds
+        controlsView?.frame = container.bounds
+    }
+
+    deinit {
+        teardownPlayer()
+    }
+
+    // MARK: - Prop setters
+
+    @objc public func setSrc(_ value: NSString?, requestReset: Bool) {
+        let raw = (value as String?) ?? ""
+        if raw.isEmpty {
+            // Clearing the prop must actually stop and release the current
+            // asset — otherwise a re-render that drops `src` would leave
+            // the previous clip playing.
+            teardownPlayer()
+            didEmitLoad = false
+            return
+        }
+        guard let url = resolveURL(raw) else {
+            teardownPlayer()
+            didEmitLoad = false
+            fireEvent("error", params: ["message": "Invalid src: \(raw)"])
+            return
+        }
+        loadAsset(url: url)
+    }
+
+    @objc(__lynx_prop_config__src)
+    public class func __lynxPropConfigSrc() -> [String] {
+        return ["src", "setSrc:requestReset:", "NSString *"]
+    }
+
+    @objc public func setPoster(_ value: NSString?, requestReset: Bool) {
+        guard let raw = value as String?, !raw.isEmpty, let url = resolveURL(raw) else {
+            posterView?.removeFromSuperview()
+            posterView = nil
+            return
+        }
+        pendingPosterURL = url
+        loadPoster(url: url)
+    }
+
+    @objc(__lynx_prop_config__poster)
+    public class func __lynxPropConfigPoster() -> [String] {
+        return ["poster", "setPoster:requestReset:", "NSString *"]
+    }
+
+    @objc public func setAutoplay(_ value: Bool, requestReset: Bool) {
+        pendingAutoplay = value
+        if value, let player = player, player.currentItem?.status == .readyToPlay {
+            player.play()
+        }
+    }
+
+    @objc(__lynx_prop_config__autoplay)
+    public class func __lynxPropConfigAutoplay() -> [String] {
+        return ["autoplay", "setAutoplay:requestReset:", "BOOL"]
+    }
+
+    @objc public func setPlaying(_ value: Bool, requestReset: Bool) {
+        pendingPlaying = value
+        guard let player = player else { return }
+        if player.currentItem?.status == .readyToPlay {
+            if value { player.play() } else { player.pause() }
+        }
+    }
+
+    @objc(__lynx_prop_config__playing)
+    public class func __lynxPropConfigPlaying() -> [String] {
+        return ["playing", "setPlaying:requestReset:", "BOOL"]
+    }
+
+    @objc public func setLoop(_ value: Bool, requestReset: Bool) {
+        pendingLoop = value
+    }
+
+    @objc(__lynx_prop_config__loop)
+    public class func __lynxPropConfigLoop() -> [String] {
+        return ["loop", "setLoop:requestReset:", "BOOL"]
+    }
+
+    @objc public func setMuted(_ value: Bool, requestReset: Bool) {
+        pendingMuted = value
+        player?.isMuted = value
+    }
+
+    @objc(__lynx_prop_config__muted)
+    public class func __lynxPropConfigMuted() -> [String] {
+        return ["muted", "setMuted:requestReset:", "BOOL"]
+    }
+
+    @objc public func setVolume(_ value: NSNumber?, requestReset: Bool) {
+        let v = Float(max(0, min(1, (value?.doubleValue ?? 1.0))))
+        pendingVolume = v
+        player?.volume = v
+    }
+
+    @objc(__lynx_prop_config__volume)
+    public class func __lynxPropConfigVolume() -> [String] {
+        return ["volume", "setVolume:requestReset:", "NSNumber *"]
+    }
+
+    @objc public func setControls(_ value: Bool, requestReset: Bool) {
+        pendingControls = value
+        // Native-controls UI is intentionally minimal in v1 — the iOS
+        // AVPlayerViewController would conflict with Lynx's view tree
+        // (it owns its own VC). We render a simple tap-to-play overlay
+        // instead. Apps that want full transport controls today can
+        // build their own overlay using the `playing` prop.
+        if value {
+            attachTapToggleOverlay()
+        } else {
+            controlsView?.removeFromSuperview()
+            controlsView = nil
+        }
+    }
+
+    @objc(__lynx_prop_config__controls)
+    public class func __lynxPropConfigControls() -> [String] {
+        return ["controls", "setControls:requestReset:", "BOOL"]
+    }
+
+    @objc public func setResizeMode(_ value: NSString?, requestReset: Bool) {
+        let mode = (value as String?) ?? "contain"
+        let gravity: AVLayerVideoGravity
+        switch mode {
+        case "cover":   gravity = .resizeAspectFill
+        case "stretch": gravity = .resize
+        default:        gravity = .resizeAspect
+        }
+        pendingResizeMode = gravity
+        playerLayer?.videoGravity = gravity
+    }
+
+    @objc(__lynx_prop_config__resize_mode)
+    public class func __lynxPropConfigResizeMode() -> [String] {
+        return ["resize-mode", "setResizeMode:requestReset:", "NSString *"]
+    }
+
+    // MARK: - Asset lifecycle
+
+    private func loadAsset(url: URL) {
+        teardownPlayer()
+
+        let item = AVPlayerItem(url: url)
+        let player = AVPlayer(playerItem: item)
+        player.isMuted = pendingMuted
+        player.volume = pendingVolume
+
+        let layer = AVPlayerLayer(player: player)
+        layer.videoGravity = pendingResizeMode
+        if let view = view {
+            layer.frame = view.bounds
+            view.layer.insertSublayer(layer, at: 0)
+        }
+
+        self.player = player
+        self.playerLayer = layer
+        self.didEmitLoad = false
+
+        // KVO on item.status — first time we hit `.readyToPlay`, fire
+        // `bindload` with the asset's duration + natural size and apply
+        // the queued autoplay/playing prop.
+        statusObservation = item.observe(\.status, options: [.new]) { [weak self] item, _ in
+            guard let self = self else { return }
+            switch item.status {
+            case .readyToPlay:
+                self.handleReadyToPlay(item: item)
+            case .failed:
+                let message = item.error?.localizedDescription ?? "Asset failed to load"
+                self.fireEvent("error", params: ["message": message])
+            default:
+                break
+            }
+        }
+
+        didReachEndObserver = NotificationCenter.default.addObserver(
+            forName: .AVPlayerItemDidPlayToEndTime,
+            object: item,
+            queue: .main,
+        ) { [weak self] _ in
+            self?.handleDidReachEnd()
+        }
+
+        timeObserver = player.addPeriodicTimeObserver(
+            forInterval: CMTime(seconds: 0.25, preferredTimescale: CMTimeScale(NSEC_PER_SEC)),
+            queue: .main,
+        ) { [weak self] time in
+            // Same NaN/Inf trap as duration on live streams — guard the
+            // position-observer cast too. `CMTimeGetSeconds` returns NaN
+            // for indefinite / unknown times, and `Int(.nan)` traps.
+            let positionMs = msFromSeconds(CMTimeGetSeconds(time))
+            self?.fireEvent("timeupdate", params: ["positionMs": positionMs])
+        }
+    }
+
+    private func handleReadyToPlay(item: AVPlayerItem) {
+        guard !didEmitLoad else { return }
+        didEmitLoad = true
+
+        // Live streams and assets with indeterminate duration return
+        // `CMTime.indefinite` whose `CMTimeGetSeconds` is `NaN` (and some
+        // edge cases produce `+Inf`). `Int(Double.nan)` traps, so funnel
+        // through a finite-check helper before reporting.
+        let durationMs = msFromSeconds(CMTimeGetSeconds(item.duration))
+        var width = 0
+        var height = 0
+        if let track = item.asset.tracks(withMediaType: .video).first {
+            let size = track.naturalSize.applying(track.preferredTransform)
+            width = Int(abs(size.width))
+            height = Int(abs(size.height))
+        }
+        fireEvent("load", params: [
+            "durationMs": durationMs,
+            "width": width,
+            "height": height,
+        ])
+
+        // Apply queued props. `playing` overrides `autoplay` if both set.
+        if let playing = pendingPlaying {
+            if playing { player?.play() } else { player?.pause() }
+        } else if pendingAutoplay {
+            player?.play()
+        }
+        // First frame painted — hide the poster.
+        posterView?.removeFromSuperview()
+        posterView = nil
+    }
+
+    private func handleDidReachEnd() {
+        if pendingLoop {
+            player?.seek(to: .zero)
+            player?.play()
+            return
+        }
+        fireEvent("end", params: [:])
+    }
+
+    private func teardownPlayer() {
+        if let observer = timeObserver { player?.removeTimeObserver(observer) }
+        timeObserver = nil
+        statusObservation?.invalidate()
+        statusObservation = nil
+        if let observer = didReachEndObserver {
+            NotificationCenter.default.removeObserver(observer)
+        }
+        didReachEndObserver = nil
+
+        player?.pause()
+        playerLayer?.removeFromSuperlayer()
+        player = nil
+        playerLayer = nil
+    }
+
+    private func loadPoster(url: URL) {
+        // Best-effort, async, no caching layer. Apps that need a CDN-aware
+        // image pipeline can roll their own and pass a `file://` poster.
+        URLSession.shared.dataTask(with: url) { [weak self] data, _, _ in
+            guard let self = self, let data = data, let image = UIImage(data: data) else { return }
+            DispatchQueue.main.async {
+                // Race guard — if `poster` was reset or replaced while this
+                // request was in flight, drop the stale image. Without
+                // this, a fast Settings flip from PosterA → PosterB could
+                // land PosterA on screen if its download completed second.
+                guard self.pendingPosterURL == url,
+                      self.posterView == nil,
+                      !self.didEmitLoad,
+                      let container = self.view else { return }
+                let iv = UIImageView(image: image)
+                iv.frame = container.bounds
+                iv.contentMode = .scaleAspectFit
+                container.addSubview(iv)
+                self.posterView = iv
+            }
+        }.resume()
+    }
+
+    private func attachTapToggleOverlay() {
+        guard controlsView == nil, let container = view else { return }
+        let overlay = UIView(frame: container.bounds)
+        overlay.backgroundColor = UIColor.clear
+        let tap = UITapGestureRecognizer(target: self, action: #selector(togglePlayPause))
+        overlay.addGestureRecognizer(tap)
+        container.addSubview(overlay)
+        controlsView = overlay
+    }
+
+    @objc private func togglePlayPause() {
+        guard let player = player else { return }
+        if player.timeControlStatus == .playing {
+            player.pause()
+        } else {
+            player.play()
+        }
+    }
+
+    // MARK: - Helpers
+
+    private func resolveURL(_ source: String) -> URL? {
+        if source.hasPrefix("file://") || source.hasPrefix("http://") || source.hasPrefix("https://") {
+            return URL(string: source)
+        }
+        if source.hasPrefix("/") {
+            return URL(fileURLWithPath: source)
+        }
+        return URL(string: source)
+    }
+
+    fileprivate func fireEvent(_ name: String, params: [String: Any]) {
+        let event = LynxCustomEvent(name: name, targetSign: sign, params: params)
+        context?.eventEmitter?.sendCustomEvent(event)
+    }
+}
+
+/// Convert seconds (possibly `NaN` or `±Inf`) to clamped milliseconds.
+/// `Int(Double.nan)` and `Int(.infinity)` trap, so live streams and
+/// indeterminate durations would crash the app without this guard.
+fileprivate func msFromSeconds(_ seconds: Double) -> Int {
+    guard seconds.isFinite, seconds > 0 else { return 0 }
+    return Int(seconds * 1000.0)
+}

package/package.json

@@ -0,0 +1,61 @@
+{
+  "name": "@sigx/lynx-video",
+  "version": "0.4.1",
+  "description": "Native video player component for sigx-lynx (AVPlayer on iOS, ExoPlayer on Android).",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    },
+    "./signalx-module.json": "./signalx-module.json",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist",
+    "ios",
+    "android",
+    "signalx-module.json",
+    "README.md"
+  ],
+  "peerDependencies": {
+    "@sigx/lynx": "^0.4.1"
+  },
+  "devDependencies": {
+    "@typescript/native-preview": "7.0.0-dev.20260521.1",
+    "typescript": "^6.0.3",
+    "@sigx/lynx": "^0.4.1"
+  },
+  "author": "Andreas Ekdahl",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/signalxjs/lynx.git",
+    "directory": "packages/lynx-video"
+  },
+  "homepage": "https://github.com/signalxjs/lynx/tree/main/packages/lynx-video",
+  "bugs": {
+    "url": "https://github.com/signalxjs/lynx/issues"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "keywords": [
+    "signalx",
+    "sigx",
+    "lynx",
+    "video",
+    "avplayer",
+    "exoplayer",
+    "ios",
+    "android"
+  ],
+  "scripts": {
+    "build": "node ../../scripts/clean.mjs dist && tsgo",
+    "dev": "tsgo --watch",
+    "clean": "node ../../scripts/clean.mjs dist .turbo"
+  }
+}

package/signalx-module.json

@@ -0,0 +1,22 @@
+{
+    "name": "Video",
+    "package": "@sigx/lynx-video",
+    "description": "Native video player component (AVPlayer / ExoPlayer)",
+    "platforms": ["android", "ios"],
+    "ios": {
+        "sourceDir": "ios",
+        "uiComponents": [
+            { "name": "video-player", "uiClass": "VideoPlayerUI" }
+        ]
+    },
+    "android": {
+        "sourceDir": "android",
+        "behaviors": [
+            { "name": "video-player", "behaviorClass": "com.sigx.video.VideoPlayerBehavior" }
+        ],
+        "dependencies": [
+            "androidx.media3:media3-exoplayer:1.4.1",
+            "androidx.media3:media3-ui:1.4.1"
+        ]
+    }
+}