@shortkitsdk/react-native 0.2.30 → 0.2.32

package/src/ShortKitContext.ts

@@ -55,7 +55,13 @@ export interface ShortKitContextValue {
 
   // Download
   downloadState: DownloadState;
-  downloadVideo: (itemId: string, mode?: 'nonInterruptive' | 'interruptive') => Promise<string>;
+  downloadVideo: (
+    itemId: string,
+    options?: {
+      mode?: 'interruptive' | 'nonInterruptive';
+      overlayMode?: 'none' | 'static' | 'deterministic';
+    }
+  ) => Promise<string>;
   cancelDownload: () => void;
 }
 

package/src/ShortKitWidget.tsx

@@ -1,13 +1,21 @@
-import React, { useContext, useLayoutEffect, useMemo } from 'react';
+import React, { useContext, useEffect, useLayoutEffect, useMemo, useRef } from 'react';
 import { View, StyleSheet } from 'react-native';
 import type { ShortKitWidgetProps } from './types';
 import ShortKitWidgetView from './specs/ShortKitWidgetViewNativeComponent';
+import NativeShortKitModule from './specs/NativeShortKitModule';
 import { ShortKitInitContext } from './ShortKitContext';
 import { serializeWidgetConfig } from './serialization';
 import { registerOverlayComponent } from './ShortKitOverlaySurface';
 import { registerCarouselOverlayComponent } from './ShortKitCarouselOverlaySurface';
 import { registerVideoCarouselOverlayComponent } from './ShortKitVideoCarouselOverlaySurface';
 
+// Local UUID generator. We don't pull in a runtime dep just for this; a
+// timestamp + random suffix is more than unique enough to disambiguate
+// concurrently-mounted widgets within a single app session.
+function generateWidgetId(): string {
+  return `widget-${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 10)}`;
+}
+
 /**
  * Horizontal carousel widget component. Displays a row of video cards
  * with automatic rotation. Wraps a native Fabric view.
@@ -15,13 +23,36 @@ import { registerVideoCarouselOverlayComponent } from './ShortKitVideoCarouselOv
  * Must be rendered inside a `<ShortKitProvider>`.
  */
 export function ShortKitWidget(props: ShortKitWidgetProps) {
-  const { config, items, style } = props;
+  const { config, items, onCardTap, style } = props;
 
   const isInitialized = useContext(ShortKitInitContext);
   if (!isInitialized) {
     throw new Error('ShortKitWidget must be used within a ShortKitProvider');
   }
 
+  // Stable widget ID for the lifetime of this component, ONLY when the host
+  // wires `onCardTap`. Skipping it when unset means the native side leaves
+  // `widgetVC.onCardTap` nil, which means the SDK's existing
+  // `clickAction: 'feed'` modal-presentation path stays intact for hosts
+  // that don't opt in. Backwards compatible.
+  const widgetId = useMemo(
+    () => (onCardTap ? generateWidgetId() : undefined),
+    // We deliberately compute this once per "host wired callback" lifetime,
+    // not per render. The boolean test on first render is what matters; if
+    // the host swaps onCardTap from set → unset later we keep the same
+    // widgetId (harmless — no events will fire because the JS subscription
+    // below tears down). Going the other way (unset → set), we generate a
+    // fresh id then.
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+    [Boolean(onCardTap)],
+  );
+
+  // Keep a stable ref to the latest onCardTap so the subscription doesn't
+  // need to tear down + rebuild every time the host re-renders with a new
+  // closure identity.
+  const onCardTapRef = useRef(onCardTap);
+  onCardTapRef.current = onCardTap;
+
   useLayoutEffect(() => {
     if (config?.overlay && config.overlay !== 'none') {
       registerOverlayComponent(config.overlay.name, config.overlay.component);
@@ -40,6 +71,19 @@ export function ShortKitWidget(props: ShortKitWidgetProps) {
     }
   }, [config?.overlay, config?.feedConfig]);
 
+  // Subscribe to the global widget-card-tap event, filtered to this
+  // instance's widgetId.
+  useEffect(() => {
+    if (!NativeShortKitModule || !onCardTap) return;
+
+    const subscription = NativeShortKitModule.onWidgetCardTap((event) => {
+      if (event.widgetId !== widgetId) return;
+      onCardTapRef.current?.(event.playbackId, event.index);
+    });
+
+    return () => subscription.remove();
+  }, [widgetId, onCardTap]);
+
   const serializedConfig = useMemo(() => {
     return serializeWidgetConfig(config ?? {});
   }, [config]);
@@ -55,6 +99,7 @@ export function ShortKitWidget(props: ShortKitWidgetProps) {
         style={styles.widget}
         config={serializedConfig}
         items={serializedItems}
+        widgetId={widgetId}
       />
     </View>
   );

package/src/specs/NativeShortKitModule.ts

@@ -127,6 +127,12 @@ type VideoCarouselCellTapEvent = Readonly<{
   pageIndex: Int32;
 }>;
 
+type WidgetCardTapEvent = Readonly<{
+  widgetId: string;
+  playbackId: string;
+  index: Int32;
+}>;
+
 type DownloadStartedEvent = Readonly<{
   itemId: string;
 }>;
@@ -134,6 +140,7 @@ type DownloadStartedEvent = Readonly<{
 type DownloadProgressEvent = Readonly<{
   itemId: string;
   progress: number;
+  phase: 'downloading' | 'compositing' | 'finalizing';
 }>;
 
 type DownloadCompletedEvent = Readonly<{
@@ -300,7 +307,7 @@ export interface Spec extends TurboModule {
   getStoryboardData(playbackId: string): Promise<string>;
 
   // --- Download ---
-  downloadVideo(itemId: string, mode: string): Promise<string>;
+  downloadVideo(itemId: string, mode: string, overlayMode: string): Promise<string>;
   cancelDownload(): void;
 
   // --- Carousel accessors ---
@@ -329,6 +336,7 @@ export interface Spec extends TurboModule {
   readonly onDidFetchContentItems: EventEmitter<DidFetchContentItemsEvent>;
   readonly onFeedReady: EventEmitter<FeedReadyEvent>;
   readonly onVideoCarouselCellTap: EventEmitter<VideoCarouselCellTapEvent>;
+  readonly onWidgetCardTap: EventEmitter<WidgetCardTapEvent>;
 
   // --- Overlay per-surface events ---
   readonly onOverlayActiveChanged: EventEmitter<OverlayActiveEvent>;

package/src/specs/ShortKitWidgetViewNativeComponent.ts

@@ -4,6 +4,12 @@ import { codegenNativeComponent } from 'react-native';
 export interface NativeProps extends ViewProps {
   config: string;
   items?: string;
+  /**
+   * Stable per-instance widget identifier. Used to route the global
+   * `NativeShortKitModule.onWidgetCardTap` event back to the originating
+   * `<ShortKitWidget>` when multiple widgets are mounted.
+   */
+  widgetId?: string;
 }
 
 export default codegenNativeComponent<NativeProps>(

package/src/types.ts

@@ -73,6 +73,10 @@ export interface ContentItem {
 
 export type DownloadStatus = 'idle' | 'downloading' | 'completed' | 'failed';
 
+export type DownloadOverlayMode = 'none' | 'static' | 'deterministic';
+
+export type DownloadPhase = 'downloading' | 'compositing' | 'finalizing';
+
 export interface DownloadState {
   status: DownloadStatus;
   /** ID of the content item being downloaded, if any. */
@@ -484,6 +488,17 @@ export interface ShortKitWidgetProps {
    * how `<ShortKitFeed feedItems={...} />` works.
    */
   items?: WidgetInput[];
+  /**
+   * Per-card tap callback. When set, the SDK skips the built-in
+   * `clickAction: 'feed'` modal-presentation path and hands the tap to the
+   * host — typically used to push a feed screen via the host's navigator
+   * instead of letting the SDK present a UIKit modal that escapes the host's
+   * navigation hierarchy.
+   *
+   * Mirrors `ShortKitPlayer.onTap`. `clickAction: 'mute'` continues to work
+   * regardless (per-cell mute toggle runs alongside `onCardTap`).
+   */
+  onCardTap?: (playbackId: string, index: number) => void;
   style?: ViewStyle;
 }
 

package/ios/DebugPanelView.swift

@@ -1,302 +0,0 @@
-import UIKit
-import Combine
-import ShortKitSDK
-
-private enum AdjacentSlot {
-    case previous, next
-}
-
-final class DebugPanelView: UIView {
-    static let panelWidth: CGFloat = 310
-    static let panelHeight: CGFloat = 296  // +20 for collapsed header row
-    static let expandedExtraHeight: CGFloat = 80  // 4 labels × ~20pt
-
-    /// Currently selected swipe curve — FeedViewController reads SwipeCurve.selected.
-    static var selectedSwipeCurve: SwipeCurve {
-        get { SwipeCurve.selected }
-        set { SwipeCurve.selected = newValue }
-    }
-
-    private let stackView = UIStackView()
-    private let headerLabel = UILabel()
-    private let curveSegment = UISegmentedControl()
-    private let positionLabel = UILabel()
-    private let intentTtffLabel = UILabel()
-    private let transitionTtffLabel = UILabel()
-    private let prerollBufferLabel = UILabel()
-    private let videoQualityLabel = UILabel()
-    private let thumbnailLabel = UILabel()
-    private let prefetchLabel = UILabel()
-    private let bitrateLabel = UILabel()
-    private let rebufferLabel = UILabel()
-    private let loopWatchLabel = UILabel()
-
-    // Adjacent players section
-    private let adjacentHeader = UILabel()
-    private let prevHeaderLabel = UILabel()
-    private let prevDetailLabel = UILabel()
-    private let nextHeaderLabel = UILabel()
-    private let nextDetailLabel = UILabel()
-    private let separatorView = UIView()
-    private var adjacentLabels: [UIView] = []
-    private var isAdjacentExpanded = false
-    private var prevCancellable: AnyCancellable?
-    private var nextCancellable: AnyCancellable?
-
-    private var cancellable: AnyCancellable?
-    private var dragOffset: CGPoint = .zero
-
-    override init(frame: CGRect) {
-        super.init(frame: frame)
-        setupViews()
-    }
-
-    required init?(coder: NSCoder) {
-        fatalError("init(coder:) has not been implemented")
-    }
-
-    private func setupViews() {
-        backgroundColor = UIColor.black.withAlphaComponent(0.75)
-        layer.cornerRadius = 10
-        clipsToBounds = true
-
-        let pan = UIPanGestureRecognizer(target: self, action: #selector(handlePan(_:)))
-        addGestureRecognizer(pan)
-
-        let labels = [headerLabel, positionLabel, intentTtffLabel, transitionTtffLabel, prerollBufferLabel, videoQualityLabel, thumbnailLabel, prefetchLabel, bitrateLabel, rebufferLabel, loopWatchLabel]
-        for label in labels {
-            label.font = UIFont.monospacedSystemFont(ofSize: 12, weight: .regular)
-            label.textColor = .white
-            label.numberOfLines = 1
-        }
-        headerLabel.font = UIFont.monospacedSystemFont(ofSize: 12, weight: .bold)
-
-        stackView.axis = .vertical
-        stackView.spacing = 4
-        stackView.alignment = .leading
-        stackView.translatesAutoresizingMaskIntoConstraints = false
-        addSubview(stackView)
-
-        for label in labels {
-            stackView.addArrangedSubview(label)
-        }
-
-        // Swipe curve picker
-        for (i, curve) in SwipeCurve.allCases.enumerated() {
-            curveSegment.insertSegment(withTitle: curve.label, at: i, animated: false)
-        }
-        curveSegment.selectedSegmentIndex = SwipeCurve.quarticOut.rawValue
-        curveSegment.setTitleTextAttributes([.foregroundColor: UIColor.white, .font: UIFont.monospacedSystemFont(ofSize: 10, weight: .medium)], for: .normal)
-        curveSegment.setTitleTextAttributes([.foregroundColor: UIColor.black], for: .selected)
-        curveSegment.backgroundColor = UIColor.white.withAlphaComponent(0.15)
-        curveSegment.selectedSegmentTintColor = UIColor.white.withAlphaComponent(0.9)
-        curveSegment.addTarget(self, action: #selector(curveChanged), for: .valueChanged)
-        stackView.addArrangedSubview(curveSegment)
-
-        // Separator
-        separatorView.backgroundColor = UIColor.white.withAlphaComponent(0.3)
-        separatorView.translatesAutoresizingMaskIntoConstraints = false
-        separatorView.heightAnchor.constraint(equalToConstant: 0.5).isActive = true
-        stackView.addArrangedSubview(separatorView)
-
-        // Adjacent header (tap target)
-        adjacentHeader.font = UIFont.monospacedSystemFont(ofSize: 12, weight: .bold)
-        adjacentHeader.textColor = .white
-        adjacentHeader.text = "▶ Adjacent Players"
-        adjacentHeader.isUserInteractionEnabled = true
-        adjacentHeader.addGestureRecognizer(UITapGestureRecognizer(target: self, action: #selector(toggleAdjacent)))
-        stackView.addArrangedSubview(adjacentHeader)
-
-        // Adjacent player labels (initially hidden)
-        let adjLabels = [prevHeaderLabel, prevDetailLabel, nextHeaderLabel, nextDetailLabel]
-        for label in adjLabels {
-            label.font = UIFont.monospacedSystemFont(ofSize: 11, weight: .regular)
-            label.textColor = UIColor.white.withAlphaComponent(0.85)
-            label.numberOfLines = 1
-            label.isHidden = true
-            stackView.addArrangedSubview(label)
-        }
-        adjacentLabels = adjLabels
-
-        prevHeaderLabel.text = "▲ Prev  — not assigned"
-        prevDetailLabel.text = ""
-        nextHeaderLabel.text = "▼ Next  — not assigned"
-        nextDetailLabel.text = ""
-
-        NSLayoutConstraint.activate([
-            stackView.topAnchor.constraint(equalTo: topAnchor, constant: 10),
-            stackView.leadingAnchor.constraint(equalTo: leadingAnchor, constant: 12),
-            stackView.trailingAnchor.constraint(equalTo: trailingAnchor, constant: -12),
-        ])
-
-        // Initial state
-        update(DebugMetrics())
-    }
-
-    @objc private func handlePan(_ gesture: UIPanGestureRecognizer) {
-        guard let parent = superview else { return }
-        switch gesture.state {
-        case .began:
-            dragOffset = gesture.location(in: self)
-        case .changed:
-            let location = gesture.location(in: parent)
-            var newCenter = CGPoint(
-                x: location.x - dragOffset.x + bounds.width / 2,
-                y: location.y - dragOffset.y + bounds.height / 2
-            )
-            // Keep panel within parent bounds
-            let hw = bounds.width / 2, hh = bounds.height / 2
-            newCenter.x = max(hw, min(parent.bounds.width - hw, newCenter.x))
-            newCenter.y = max(hh, min(parent.bounds.height - hh, newCenter.y))
-            center = newCenter
-        default:
-            break
-        }
-    }
-
-    @objc private func curveChanged(_ sender: UISegmentedControl) {
-        guard let curve = SwipeCurve(rawValue: sender.selectedSegmentIndex) else { return }
-        Self.selectedSwipeCurve = curve
-    }
-
-    @objc private func toggleAdjacent() {
-        isAdjacentExpanded.toggle()
-        adjacentHeader.text = isAdjacentExpanded ? "▼ Adjacent Players" : "▶ Adjacent Players"
-
-        UIView.animate(withDuration: 0.25) {
-            for label in self.adjacentLabels {
-                label.isHidden = !self.isAdjacentExpanded
-                label.alpha = self.isAdjacentExpanded ? 1 : 0
-            }
-            // Resize panel
-            var newFrame = self.frame
-            let baseHeight = Self.panelHeight
-            newFrame.size.height = self.isAdjacentExpanded
-                ? baseHeight + Self.expandedExtraHeight
-                : baseHeight
-            self.frame = newFrame
-            self.layoutIfNeeded()
-        }
-    }
-
-    func subscribe(to subject: CurrentValueSubject<DebugMetrics, Never>) {
-        cancellable = subject
-            .receive(on: DispatchQueue.main)
-            .sink { [weak self] metrics in
-                self?.update(metrics)
-            }
-    }
-
-    func subscribeAdjacent(
-        prev: CurrentValueSubject<DebugMetrics, Never>,
-        next: CurrentValueSubject<DebugMetrics, Never>
-    ) {
-        prevCancellable = prev
-            .receive(on: DispatchQueue.main)
-            .sink { [weak self] metrics in
-                self?.updateAdjacent(metrics, slot: .previous)
-            }
-        nextCancellable = next
-            .receive(on: DispatchQueue.main)
-            .sink { [weak self] metrics in
-                self?.updateAdjacent(metrics, slot: .next)
-            }
-    }
-
-    private func updateAdjacent(_ m: DebugMetrics, slot: AdjacentSlot) {
-        let headerLabel = slot == .previous ? prevHeaderLabel : nextHeaderLabel
-        let detailLabel = slot == .previous ? prevDetailLabel : nextDetailLabel
-        let arrow = slot == .previous ? "▲ Prev" : "▼ Next"
-
-        guard m.contentId != nil else {
-            headerLabel.text = "\(arrow)  — not assigned"
-            detailLabel.text = ""
-            return
-        }
-
-        let id = m.contentId.map { String($0.prefix(8)) } ?? "—"
-        let stateIcon: String
-        switch m.playerState {
-        case .playing: stateIcon = "▶"
-        case .paused: stateIcon = "⏸"
-        case .buffering: stateIcon = "⏳"
-        default: stateIcon = "○"
-        }
-        headerLabel.text = "\(arrow)  #\(m.feedIndex) \(id)  \(stateIcon) \(m.playerState)"
-
-        let buf = String(format: "%.1f", m.bufferAhead)
-        let preroll = m.prerollCompleted ? "✓" : "✗"
-        let mbps = m.observedBitrateBps / 1_000_000
-        var detail = "  buf: \(buf)s  preroll: \(preroll)"
-        if mbps > 0 {
-            detail += String(format: "  %.1f Mbps", mbps)
-        }
-        if m.videoWidth > 0 {
-            let codec = m.codec ?? ""
-            detail += "  \(m.videoWidth)×\(m.videoHeight) \(codec)"
-        }
-        detailLabel.text = detail
-    }
-
-    private func update(_ m: DebugMetrics) {
-        let id = m.contentId.map { String($0.prefix(8)) } ?? "—"
-        let stateIcon: String
-        switch m.playerState {
-        case .playing: stateIcon = "▶"
-        case .paused: stateIcon = "⏸"
-        case .buffering: stateIcon = "⏳"
-        case .seeking: stateIcon = "⏩"
-        case .error: stateIcon = "⚠️"
-        default: stateIcon = "○"
-        }
-        headerLabel.text = "#\(m.feedIndex)  \(id)  \(stateIcon) \(m.playerState)"
-
-        let cur = String(format: "%.1f", m.currentTime)
-        let dur = String(format: "%.1f", m.duration)
-        positionLabel.text = "Position: \(cur)s / \(dur)s"
-
-        if let intent = m.intentToFrameMs {
-            intentTtffLabel.text = "Intent:     \(intent)ms"
-        } else {
-            intentTtffLabel.text = "Intent:     N/A"
-        }
-
-        if let transition = m.transitionToFrameMs {
-            let net = m.networkMs.map { "\($0)" } ?? "?"
-            let dec = m.decodeMs.map { "\($0)" } ?? "?"
-            transitionTtffLabel.text = "Transition:  \(transition)ms  (net: \(net) + dec: \(dec))"
-        } else {
-            transitionTtffLabel.text = "Transition:  measuring..."
-        }
-
-        let preroll = m.prerollCompleted ? "✓" : "✗"
-        let buffer = String(format: "%.1f", m.bufferAhead)
-        prerollBufferLabel.text = "Preroll: \(preroll)    Buffer: \(buffer)s"
-
-        let codec = m.codec ?? "—"
-        if m.videoWidth > 0 {
-            videoQualityLabel.text = "Video: \(m.videoWidth)×\(m.videoHeight)  \(codec)"
-        } else {
-            videoQualityLabel.text = "Video: —"
-        }
-
-        thumbnailLabel.text = "Thumbnail: \(m.thumbnailVisible ? "visible" : "removed")"
-        prefetchLabel.text = "Prefetch: \(m.thumbsCachedAhead)/\(m.metadataAhead) thumbs  \(m.metadataAhead) meta"
-
-        let obsMbps = m.observedBitrateBps / 1_000_000
-        let indMbps = m.indicatedBitrateBps / 1_000_000
-        if obsMbps > 0 {
-            bitrateLabel.text = String(format: "Bitrate: %.1f Mbps (ind: %.1f)", obsMbps, indMbps)
-        } else {
-            bitrateLabel.text = "Bitrate: —"
-        }
-
-        if let lastMs = m.lastRebufferDurationMs {
-            rebufferLabel.text = "Rebuffers: \(m.rebufferCount)  (last: \(lastMs)ms)"
-        } else {
-            rebufferLabel.text = "Rebuffers: \(m.rebufferCount)"
-        }
-
-        loopWatchLabel.text = "Loops: \(m.loopCount)"
-    }
-}