@scalemule/gallop 0.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 ScaleMule Inc.
+
+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,201 @@
+# Gallop Web SDK
+
+**ScaleMule's Video Player for Web Applications**
+
+*TypeScript • MSE • Zero Dependencies*
+
+---
+
+## Overview
+
+The Gallop Web SDK is a high-performance video player built with TypeScript and native browser APIs. It provides ScaleMule customers with a premium streaming experience including social features, deep analytics, and optimized playback.
+
+### Key Features
+
+- **Instant Start** - Pre-warming system for TikTok-like instant playback
+- **50% Bandwidth Savings** - VP9/HEVC codec support
+- **Timeline Comments** - Social video features via scalemule-chat
+- **Deep Analytics** - Heatmaps, engagement tracking, TTFF metrics
+- **Zero Dependencies** - Custom engine (Phase 3+), no HLS.js in production
+
+---
+
+## Installation
+
+```bash
+npm install @scalemule/gallop
+```
+
+---
+
+## Quick Start
+
+### React
+
+```tsx
+import { GallopPlayer } from '@scalemule/gallop/react';
+
+function VideoPage() {
+  return (
+    <GallopPlayer
+      videoId="your-video-id"
+      apiKey="sm_live_xxx"
+      onPlay={() => console.log('Playing')}
+    />
+  );
+}
+```
+
+### Playback Analytics + Debugging
+
+```tsx
+import { GallopPlayer } from '@scalemule/gallop/react';
+
+<GallopPlayer
+  videoId="your-video-id"
+  apiKey="sm_live_xxx"
+  analytics={{
+    enabled: true,
+    progressIntervalSeconds: 10,
+    includeNetworkInfo: true,
+    includeDeviceInfo: true,
+    debug: false,
+  }}
+  onEngineStats={({ stats }) => {
+    console.log('HLS stats', stats);
+  }}
+/>;
+```
+
+When `analytics.enabled` is on, the player sends playback telemetry to `POST /v1/videos/{id}/track` with:
+- Core events: `play`, `pause`, `seek`, `complete`, `buffer`, `error`
+- Session ID and playback position
+- QoE metadata (TTFF, rebuffer ratio, quality switches)
+- Network/device context (when available)
+
+### Web Component
+
+```html
+<script type="module">
+  import '@scalemule/gallop/element';
+</script>
+
+<gallop-player
+  video-id="your-video-id"
+  api-key="sm_live_xxx"
+></gallop-player>
+```
+
+### Pre-warming (Instant Start)
+
+```typescript
+import { gallop } from '@scalemule/gallop';
+
+// Prewarm on hover for instant playback
+thumbnail.addEventListener('mouseenter', () => {
+  gallop.prewarm('video-id');
+});
+
+// Or use IntersectionObserver for feeds
+const observer = new IntersectionObserver((entries) => {
+  entries.forEach(entry => {
+    if (entry.isIntersecting) {
+      gallop.prewarm(entry.target.dataset.videoId);
+    }
+  });
+}, { rootMargin: '200px' });
+```
+
+---
+
+## Architecture
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│                         Gallop Web                               │
+├─────────────────────────────────────────────────────────────────┤
+│  UI Layer                                                        │
+│  ├── React Components / Web Components                          │
+│  ├── Controls (play, seek, volume, quality)                     │
+│  └── Social Features (timeline comments, share)                 │
+├─────────────────────────────────────────────────────────────────┤
+│  Engine Abstraction                                              │
+│  ├── HLSJSEngine (Phase 1-2, temporary)                         │
+│  ├── GallopEngine (Phase 3+, custom)                            │
+│  └── NativeHLSEngine (iOS Safari fallback)                      │
+├─────────────────────────────────────────────────────────────────┤
+│  Performance Layer                                               │
+│  ├── Pre-warming System                                         │
+│  ├── Low-Latency Startup Profile                                │
+│  └── Hot-Swap Fallback                                          │
+├─────────────────────────────────────────────────────────────────┤
+│  Browser APIs                                                    │
+│  ├── Media Source Extensions (MSE)                              │
+│  ├── Encrypted Media Extensions (EME)                           │
+│  └── Web Workers                                                │
+└─────────────────────────────────────────────────────────────────┘
+```
+
+---
+
+## Browser Support
+
+| Browser | Version | MSE | DRM |
+|---------|---------|-----|-----|
+| Chrome | 70+ | ✅ | Widevine |
+| Firefox | 78+ | ✅ | Widevine |
+| Safari | 14+ | ✅ | FairPlay |
+| Edge | 79+ | ✅ | Widevine |
+| iOS Safari | 14+ | Native HLS | FairPlay |
+| Android Chrome | 70+ | ✅ | Widevine |
+
+---
+
+## Development
+
+### Technology Stack
+
+| Tool | Purpose |
+|------|---------|
+| TypeScript | Primary language (strict mode) |
+| tsup | Build pipeline (ESM + CJS + UMD) |
+| Vitest | Unit testing |
+| Playwright | E2E testing |
+
+### Scripts
+
+```bash
+# Development
+npm run dev          # Start dev server with hot reload
+npm run build        # Production build
+npm run test         # Run unit tests
+npm run test:e2e     # Run Playwright tests
+
+# Quality
+npm run lint         # ESLint
+npm run typecheck    # TypeScript type checking
+```
+
+---
+
+## Documentation
+
+| Document | Description |
+|----------|-------------|
+| [IMPLEMENTATION_PLAN.md](./IMPLEMENTATION_PLAN.md) | Development phases, technical details |
+| [Core Architecture](../scalemule-gallop/docs/ARCHITECTURE.md) | Shared architecture decisions |
+| [Cross-Platform](../scalemule-gallop/docs/CROSS_PLATFORM.md) | Platform comparison |
+
+---
+
+## Related Repos
+
+- **[scalemule-gallop](../scalemule-gallop)** - Core documentation (shared architecture)
+- **[scalemule-gallop-ios](../scalemule-gallop-ios)** - iOS SDK (Swift)
+- **[scalemule-gallop-android](../scalemule-gallop-android)** - Android SDK (Kotlin)
+
+---
+
+## License
+
+Proprietary - ScaleMule, Inc.

package/dist/EventEmitter-CiUv3YL_.d.cts

@@ -0,0 +1,12 @@
+import { d as GallopEventMap, c as GallopEventCallback } from './types-D9Oqcpr1.cjs';
+
+declare class EventEmitter {
+    private listeners;
+    on<K extends keyof GallopEventMap>(event: K, callback: GallopEventCallback<GallopEventMap[K]>): void;
+    off<K extends keyof GallopEventMap>(event: K, callback: GallopEventCallback<GallopEventMap[K]>): void;
+    once<K extends keyof GallopEventMap>(event: K, callback: GallopEventCallback<GallopEventMap[K]>): void;
+    protected emit<K extends keyof GallopEventMap>(event: K, ...args: GallopEventMap[K] extends void ? [] : [GallopEventMap[K]]): void;
+    removeAllListeners(): void;
+}
+
+export { EventEmitter as E };

package/dist/EventEmitter-CkfpgRij.d.ts

@@ -0,0 +1,12 @@
+import { d as GallopEventMap, c as GallopEventCallback } from './types-D9Oqcpr1.js';
+
+declare class EventEmitter {
+    private listeners;
+    on<K extends keyof GallopEventMap>(event: K, callback: GallopEventCallback<GallopEventMap[K]>): void;
+    off<K extends keyof GallopEventMap>(event: K, callback: GallopEventCallback<GallopEventMap[K]>): void;
+    once<K extends keyof GallopEventMap>(event: K, callback: GallopEventCallback<GallopEventMap[K]>): void;
+    protected emit<K extends keyof GallopEventMap>(event: K, ...args: GallopEventMap[K] extends void ? [] : [GallopEventMap[K]]): void;
+    removeAllListeners(): void;
+}
+
+export { EventEmitter as E };

package/dist/chunk-2JQGJ7NX.cjs

@@ -0,0 +1,40 @@
+'use strict';
+
+// src/core/EventEmitter.ts
+var EventEmitter = class {
+  constructor() {
+    this.listeners = /* @__PURE__ */ new Map();
+  }
+  on(event, callback) {
+    if (!this.listeners.has(event)) {
+      this.listeners.set(event, /* @__PURE__ */ new Set());
+    }
+    this.listeners.get(event).add(callback);
+  }
+  off(event, callback) {
+    this.listeners.get(event)?.delete(callback);
+  }
+  once(event, callback) {
+    const wrapper = ((...args) => {
+      this.off(event, wrapper);
+      callback(...args);
+    });
+    this.on(event, wrapper);
+  }
+  emit(event, ...args) {
+    const set = this.listeners.get(event);
+    if (!set) return;
+    for (const listener of set) {
+      try {
+        listener(...args);
+      } catch (err) {
+        console.error(`[Gallop] Error in ${event} listener:`, err);
+      }
+    }
+  }
+  removeAllListeners() {
+    this.listeners.clear();
+  }
+};
+
+exports.EventEmitter = EventEmitter;

package/dist/chunk-PKRNWEEX.cjs

@@ -0,0 +1,265 @@
+'use strict';
+
+var chunk2JQGJ7NX_cjs = require('./chunk-2JQGJ7NX.cjs');
+
+// src/iframe/GallopIframeController.ts
+var HASH_CONFIG_ALLOWLIST = [
+  "autoplay",
+  "muted",
+  "loop",
+  "controls",
+  "startTime",
+  "preferredQuality",
+  "aspectRatio",
+  "theme",
+  "debug",
+  "doNotTrack",
+  "analytics",
+  "pageUrl"
+];
+var MAX_HASH_CONFIG_BYTES = 4096;
+function sanitizeConfigForHash(config) {
+  const safe = {};
+  for (const key of HASH_CONFIG_ALLOWLIST) {
+    if (config[key] !== void 0) {
+      safe[key] = config[key];
+    }
+  }
+  return safe;
+}
+var GallopIframeController = class extends chunk2JQGJ7NX_cjs.EventEmitter {
+  constructor(container, config) {
+    super();
+    this.container = container;
+    this.config = config;
+    this.targetOrigin = null;
+    this.isConnected = false;
+    this.pendingCalls = /* @__PURE__ */ new Map();
+    this.stateCache = {};
+    this.cachedQualityLevels = [];
+    this.cachedCurrentQuality = -1;
+    this.cachedDiagnostics = {};
+    this.sessionId = Math.random().toString(36).substring(7);
+    this.handshakeInterval = null;
+    this.iframe = this.createIframe();
+    this.container.appendChild(this.iframe);
+    this.boundHandler = this.handleMessage.bind(this);
+    window.addEventListener("message", this.boundHandler);
+    this.startHandshake();
+  }
+  createIframe() {
+    const iframe = document.createElement("iframe");
+    const videoId = this.config.videoId || "unknown";
+    const baseUrl = this.config.apiBaseUrl ? `${this.config.apiBaseUrl.replace(/\/$/, "")}/v1/videos/embed` : "https://api.scalemule.com/v1/videos/embed";
+    const url = new URL(`${baseUrl}/${videoId}`);
+    if (this.config.embedToken) {
+      url.searchParams.set("token", this.config.embedToken);
+    }
+    const safeConfig = sanitizeConfigForHash(this.config);
+    if (!safeConfig.pageUrl && typeof window !== "undefined") {
+      safeConfig.pageUrl = window.location.href;
+    }
+    const json = JSON.stringify(safeConfig);
+    const encoded = btoa(json).replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
+    if (encoded.length > MAX_HASH_CONFIG_BYTES) {
+      console.warn("[Gallop] Config too large for hash, using defaults");
+    } else {
+      url.hash = `config=${encoded}`;
+    }
+    iframe.src = url.toString();
+    iframe.style.width = "100%";
+    iframe.style.height = "100%";
+    iframe.style.border = "0";
+    iframe.allow = "autoplay; fullscreen; picture-in-picture; encrypted-media";
+    iframe.title = "Gallop Video Player";
+    return iframe;
+  }
+  startHandshake() {
+    let attempts = 0;
+    this.handshakeInterval = setInterval(() => {
+      if (this.isConnected || attempts >= 3) {
+        if (this.handshakeInterval) clearInterval(this.handshakeInterval);
+        this.handshakeInterval = null;
+        if (!this.isConnected && attempts >= 3) {
+          this.emit("error", { code: "CONNECT_TIMEOUT", message: "iframe handshake timed out" });
+        }
+        return;
+      }
+      this.sendMessage("gallop:ping", { sessionId: this.sessionId }, "*");
+      attempts++;
+    }, 1e3);
+  }
+  handleMessage(event) {
+    const data = event.data;
+    if (!data || typeof data.type !== "string" || !data.type.startsWith("gallop:")) return;
+    if (event.source !== this.iframe.contentWindow) return;
+    if (!this.isConnected) {
+      if (data.type === "gallop:hello") {
+        this.sendMessage("gallop:ping", { sessionId: this.sessionId }, "*");
+        return;
+      }
+      if (data.type === "gallop:pong") {
+        this.targetOrigin = event.origin;
+        this.isConnected = true;
+        if (this.handshakeInterval) {
+          clearInterval(this.handshakeInterval);
+          this.handshakeInterval = null;
+        }
+        if (data.diagnostics) {
+          this.cachedDiagnostics = data.diagnostics;
+        }
+        return;
+      }
+      if (data.type === "gallop:error") {
+        this.emit("error", { code: data.code || "EMBED_LOAD_FAILED", message: data.message || "Embed error" });
+        return;
+      }
+      return;
+    }
+    if (event.origin !== this.targetOrigin) return;
+    switch (data.type) {
+      case "gallop:event":
+        if (data.event === "qualitylevels" && data.data?.levels) {
+          this.cachedQualityLevels = data.data.levels;
+        }
+        if (data.event === "qualitychange" && data.data?.level) {
+          this.cachedCurrentQuality = data.data.level.index ?? -1;
+        }
+        this.emit(data.event, data.data);
+        break;
+      case "gallop:state":
+        this.stateCache = data.state;
+        break;
+      case "gallop:response":
+        this.handleResponse(data);
+        break;
+      case "gallop:error":
+        this.emit("error", { code: data.code || "UNKNOWN", message: data.message || "Unknown error" });
+        break;
+    }
+  }
+  handleResponse(data) {
+    const call = this.pendingCalls.get(data.callId);
+    if (call) {
+      clearTimeout(call.timeout);
+      if (data.error) {
+        call.reject(data.error);
+      } else {
+        call.resolve(data.result);
+      }
+      this.pendingCalls.delete(data.callId);
+    }
+  }
+  sendMessage(type, payload = {}, overrideOrigin) {
+    const target = overrideOrigin || this.targetOrigin;
+    if (!target) return;
+    this.iframe.contentWindow?.postMessage({
+      type,
+      ...payload,
+      version: 1
+    }, target);
+  }
+  callMethod(method, ...args) {
+    return new Promise((resolve, reject) => {
+      if (!this.isConnected && method !== "destroy") {
+        reject(new Error("Player not connected"));
+        return;
+      }
+      if (this.pendingCalls.size >= 20) {
+        reject(new Error("Too many pending calls"));
+        return;
+      }
+      const callId = crypto.randomUUID ? crypto.randomUUID() : Math.random().toString(36).substring(2);
+      const timeout = setTimeout(() => {
+        this.pendingCalls.delete(callId);
+        reject(new Error(`Method ${method} timed out`));
+      }, 5e3);
+      this.pendingCalls.set(callId, { resolve, reject, timeout });
+      this.sendMessage("gallop:method", { method, args, callId });
+    });
+  }
+  // --- GallopPlayer Implementation ---
+  get currentTime() {
+    return this.stateCache.currentTime ?? 0;
+  }
+  get duration() {
+    return this.stateCache.duration ?? 0;
+  }
+  get paused() {
+    return this.stateCache.paused ?? true;
+  }
+  get status() {
+    return this.stateCache.status ?? "loading";
+  }
+  get isFullscreen() {
+    return this.stateCache.isFullscreen ?? false;
+  }
+  get volume() {
+    return this.stateCache.volume ?? 1;
+  }
+  set volume(v) {
+    void this.callMethod("setVolume", v);
+  }
+  get muted() {
+    return this.stateCache.muted ?? false;
+  }
+  set muted(m) {
+    void this.callMethod("setMuted", m);
+  }
+  get playbackRate() {
+    return this.stateCache.playbackRate ?? 1;
+  }
+  set playbackRate(r) {
+    void this.callMethod("setPlaybackRate", r);
+  }
+  play() {
+    return this.callMethod("play");
+  }
+  pause() {
+    return this.callMethod("pause");
+  }
+  seek(time) {
+    return this.callMethod("seek", time);
+  }
+  setQualityLevel(index) {
+    return this.callMethod("setQualityLevel", index);
+  }
+  setAutoQuality() {
+    return this.callMethod("setAutoQuality");
+  }
+  toggleFullscreen() {
+    return this.callMethod("toggleFullscreen");
+  }
+  getQualityLevels() {
+    return this.cachedQualityLevels;
+  }
+  getCurrentQuality() {
+    return this.cachedCurrentQuality;
+  }
+  getDiagnostics() {
+    return this.cachedDiagnostics;
+  }
+  query(key) {
+    return this.callMethod("query", key);
+  }
+  get connected() {
+    return this.isConnected;
+  }
+  destroy() {
+    if (this.handshakeInterval) {
+      clearInterval(this.handshakeInterval);
+      this.handshakeInterval = null;
+    }
+    for (const [, call] of this.pendingCalls) {
+      clearTimeout(call.timeout);
+      call.reject(new Error("Player destroyed"));
+    }
+    this.pendingCalls.clear();
+    window.removeEventListener("message", this.boundHandler);
+    this.iframe.remove();
+    this.emit("destroy");
+    this.removeAllListeners();
+  }
+};
+
+exports.GallopIframeController = GallopIframeController;