playron 1.0.2 → 1.0.3

package/README.md

@@ -11,7 +11,7 @@ Playron is a modular, tree-shakeable video player library designed for OTT platf
 
 ```tsx
 import { Player } from 'playron'
-import 'playron/dist/playron.css'
+import 'playron/style.css'
 
 <Player src="https://example.com/stream.m3u8" />
 ```
@@ -42,11 +42,11 @@ npx yalc add playron
 
 ## Quick Start
 
-### React / Next.js
+### React (Vite / CRA)
 
 ```tsx
 import { Player } from 'playron'
-import 'playron/dist/playron.css'
+import 'playron/style.css'
 
 export default function VideoPage() {
   return (
@@ -54,10 +54,7 @@ export default function VideoPage() {
       src="https://example.com/stream.m3u8"
       poster="https://example.com/poster.jpg"
       config={{
-        player: {
-          defaultVolume: 0.8,
-          skipSeconds: 10,
-        },
+        player: { defaultVolume: 0.8, skipSeconds: 10 },
         features: {
           pip: true,
           fullscreen: true,
@@ -67,34 +64,74 @@ export default function VideoPage() {
           playbackSpeed: true,
           keyboardShortcuts: true,
         },
-        branding: {
-          primaryColor: '#e50914',
-        },
+        branding: { primaryColor: '#e50914' },
       }}
     />
   )
 }
 ```
 
-### Next.js App Router
+### Next.js — App Router
+
+> **Important:** Playron uses browser-only APIs (MediaSource, EME, hls.js, dash.js).
+> You **must** use `dynamic()` with `ssr: false`. Using only `'use client'` is not enough —
+> Next.js still pre-renders client components on the server for the initial HTML.
+
+**Step 1** — Create a client wrapper with `dynamic`:
 
 ```tsx
+// components/VideoPlayer.tsx
 'use client'
-import { Player } from 'playron'
-import 'playron/dist/playron.css'
+import dynamic from 'next/dynamic'
+import 'playron/style.css'
+
+const Player = dynamic(
+  () => import('playron').then(m => m.Player),
+  {
+    ssr: false,
+    loading: () => (
+      <div style={{ width: '100%', aspectRatio: '16/9', background: '#000' }} />
+    ),
+  }
+)
+
+export default function VideoPlayer({ src }: { src: string }) {
+  return <Player src={src} />
+}
+```
+
+**Step 2** — Use it in your page (Server Component is fine here):
+
+```tsx
+// app/page.tsx
+import VideoPlayer from '@/components/VideoPlayer'
+
+export default function Page() {
+  return <VideoPlayer src="https://example.com/stream.m3u8" />
+}
 ```
 
-### Next.js Pages Router
+### Next.js — Pages Router
 
 ```tsx
+// pages/video.tsx
 import dynamic from 'next/dynamic'
-const Player = dynamic(() => import('playron').then(m => m.Player), { ssr: false })
+import 'playron/style.css'
+
+const Player = dynamic(
+  () => import('playron').then(m => m.Player),
+  { ssr: false }
+)
+
+export default function VideoPage() {
+  return <Player src="https://example.com/stream.m3u8" />
+}
 ```
 
 ### Vanilla JavaScript
 
 ```html
-<link rel="stylesheet" href="playron/dist/playron.css" />
+<link rel="stylesheet" href="node_modules/playron/dist/playron.css" />
 
 <div id="player"></div>
 
@@ -482,6 +519,64 @@ npm run lint         # ESLint
 
 ---
 
+## Troubleshooting
+
+### `window is not defined` (Next.js)
+
+**Cause:** Playron bundles hls.js and dash.js which access browser APIs at module evaluation time. Next.js pre-renders even `'use client'` components on the server for the initial HTML — `'use client'` alone is not sufficient.
+
+**Fix:** Always wrap Playron in `dynamic()` with `ssr: false`:
+
+```tsx
+// ❌ Wrong — causes "window is not defined" on the server
+'use client'
+import { Player } from 'playron'
+
+// ✅ Correct
+'use client'
+import dynamic from 'next/dynamic'
+
+const Player = dynamic(
+  () => import('playron').then(m => m.Player),
+  { ssr: false }
+)
+```
+
+---
+
+### `Module not found: Can't resolve 'playron/dist/playron.css'`
+
+**Cause:** The correct CSS export path is `playron/style.css`, not `playron/dist/playron.css`.
+
+```tsx
+// ❌ Wrong
+import 'playron/dist/playron.css'
+
+// ✅ Correct
+import 'playron/style.css'
+```
+
+Both paths now work as of v1.0.3, but `playron/style.css` is the canonical import.
+
+---
+
+### Player renders but has no styles
+
+Make sure you import the CSS **once** at the top level of your app (e.g. `layout.tsx`, `_app.tsx`, or `globals.css`):
+
+```tsx
+// app/layout.tsx
+import 'playron/style.css'
+```
+
+---
+
+### Video plays but DRM content fails on Safari
+
+FairPlay (Safari/iOS) is not yet implemented. Playron will automatically show a DRM error overlay with browser recommendations when Widevine content is loaded in Safari. See the [DRM section](#drm-usage) for the current support matrix.
+
+---
+
 ## License
 
 MIT © Suat Erkilic

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "playron",
-  "version": "1.0.2",
+  "version": "1.0.3",
   "description": "Modern OTT video player for React, Next.js, and vanilla JS",
   "type": "module",
   "main": "./dist/playron.cjs.js",
@@ -12,8 +12,14 @@
       "import": "./dist/playron.es.js",
       "require": "./dist/playron.cjs.js"
     },
-    "./style.css": "./dist/playron.css"
+    "./style.css": "./dist/playron.css",
+    "./dist/playron.css": "./dist/playron.css",
+    "./dist/*": "./dist/*"
   },
+  "sideEffects": [
+    "*.css",
+    "./dist/playron.css"
+  ],
   "files": [
     "dist"
   ],