@forgedevstack/torch

The media engine of ForgeStack: React components for video, audio, vertical reels, and ads, with a configurable TorchTracker pipeline for analytics and CMS-driven settings.

Install

npm install @forgedevstack/torch react react-dom

Import the bundled stylesheet once (Tailwind-based; required for layout and animations):

import '@forgedevstack/torch/styles.css';

Quick start

Wrap your app (or a subtree) with TorchProvider so players share accent color, default tracking, and optional icon overrides.

import { TorchProvider, TorchPlayer } from '@forgedevstack/torch';
import '@forgedevstack/torch/styles.css';

export function App() {
  return (
    <TorchProvider
      config={{
        accentColor: '#f97316',
        tracking: { enabled: true, onEvent: (e) => console.log(e) },
      }}
    >
      <TorchPlayer src="https://example.com/video.mp4" poster="https://example.com/poster.jpg" size="md" />
    </TorchProvider>
  );
}

TorchProvider

| Option | Type | Description | |--------|------|-------------| | config.accentColor | string | Default accent for controls, progress, highlights (hex/CSS color). | | config.defaultSize | 'sm' \| 'md' \| 'lg' \| 'full' | Reserved for future defaults. | | config.defaultMode | 'static' \| 'sticky' | Reserved for future defaults. | | config.tracking | TorchTrackingConfig | Global tracking defaults (see below). | | config.icons | Partial<TorchIcons> | Slot overrides for play/pause/fullscreen/etc. (optional). |

Use useTorchContext() to read { accentColor, tracking, icons } inside custom UI.

Tracking (TorchTrackingConfig + TorchTracker)

| Field | Type | Description | |-------|------|-------------| | enabled | boolean | Master switch. | | onEvent | (event: TorchEvent) => void | Fires for each tracked event. | | batchInterval | number | Ms between flushes; 0 = immediate. | | include | TorchEventName[] | Allow-list; omit = all events. | | exclude | TorchEventName[] | Deny-list. |

Event names include: play, pause, stop, ended, seek, mute, unmute, fullscreen, error, ad-impression, ad-click, ad-skip, ad-complete, reel-swipe, reel-like, reel-share, reel-follow, track-change, and others (see TorchEventName in types).

Construct TorchTracker directly when you need the same batching/filtering outside React (e.g. custom players).

TorchPlayer (standard video / audio)

| Prop | Type | Default | Description | |------|------|---------|-------------| | src | string | — | Required. Media URL. | | type | 'video' \| 'audio' | 'video' | Media kind. | | poster | string | — | Poster / cover image. | | size | 'sm' \| 'md' \| 'lg' \| 'full' | 'md' | Max width & control sizing. | | autoPlay | boolean | false | | | loop | boolean | false | With a playlist, loop is managed per track. | | muted | boolean | false | | | accentColor | string | from provider | | | centerOverlay | boolean | false | Large center play/pause on video. | | mode | 'static' \| 'sticky' | 'static' | sticky = scroll-following mini player (video). | | stickyPosition | 'top-left' \| 'top-right' \| 'bottom-left' \| 'bottom-right' | 'bottom-right' | Corner when sticky. | | stickySize | number | library default | Width of sticky frame (px). | | playlist | TorchTrack[] | — | Enables gallery + skip prev/next. | | onTrackChange | (index, track) => void | — | | | tracking | TorchTrackingConfig | from provider | | | containerStyle | CSSProperties | — | Wrapper styles. | | testId | string | — | data-testid. |

Also accepts standard HTMLAttributes<HTMLDivElement> (excluding children).

ReelPlayer (vertical feed)

| Prop | Type | Default | Description | |------|------|---------|-------------| | items | TorchReelItem[] | — | Required. Each item extends TorchTrack with optional avatar, username, description, counts, liked, following. | | startIndex | number | 0 | | | autoPlay | boolean | true | | | loop | boolean | true | Per-clip loop. | | muted | boolean | true | | | accentColor | string | from provider | | | showActions | boolean | true | Like / comment / share / follow UI (callbacks only — no network). | | callbacks | TorchReelCallbacks | — | onLike, onShare, onFollow, onComment with (index, item). | | tracking | TorchTrackingConfig | from provider | |

AdPlayer (pre/post-roll, skip, CTA)

| Prop | Type | Default | Description | |------|------|---------|-------------| | src | string | — | Required. Main content URL. | | poster | string | — | Main poster. | | type | 'video' \| 'audio' | 'video' | | | ads | TorchAdItem[] | — | Required. Each ad: src, optional poster, skipAfter (seconds until skip; -1 = no skip), clickUrl, adId, position (pre-roll | mid-roll | post-roll). | | size | 'sm' \| 'md' \| 'lg' \| 'full' | 'md' | | | autoPlay | boolean | true | | | muted | boolean | false | | | accentColor | string | from provider | | | onAdSkip | (ad) => void | — | | | onAdComplete | (ad) => void | — | | | onAdClick | (ad) => void | — | | | tracking | TorchTrackingConfig | from provider | |

Hooks

| Hook | Purpose | |------|---------| | useTorchPlayer | Shared playback state for custom TorchPlayer-like UIs (tracks, seek, playlist index). | | useTorchSticky | Scroll-following / PiP-style positioning for mode="sticky". | | useReelPlayer | Reel index, gestures, mute, progress, and tracking for ReelPlayer. |

Constants (SDK)

Re-exported from the package (see src/constants/torch.const.ts): DEFAULT_ACCENT, SIZE_MAP, REEL_ASPECT_RATIO, REEL_MAX_WIDTH, AD_SKIP_COUNTDOWN_DEFAULT, etc.

Monorepo / contributor aliases

Inside the Torch package source, imports use:

• @torch-types/* — not @types/* (reserved for DefinitelyTyped)
• @const/*, @core/*, @hooks/*, @context/*, @utils/*, @components/*

Docs site

See forge/torch-portal for a Bear UI + Forge Compass demo (EN/ES), embed code samples, and live players.

License

MIT