Package Exports

@forgedevstack/torch
@forgedevstack/torch/context
@forgedevstack/torch/hooks
@forgedevstack/torch/styles.css

Readme

@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