@kodezen/player 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Kodezen
+
+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,89 @@
+# @kodezen/player
+
+A small, framework-agnostic media player core with a custom control bar.
+
+**Tracking-free by design.** The library plays media, renders controls, emits
+progress events, and accepts a resume position. It never persists anything and
+knows nothing about WordPress, courses, or completion — the host wires progress
+saving, resume, and completion gating on top of its events. That keeps it
+reusable and makes it a clean seam for a future analytics/verification layer.
+
+## Status
+
+Phase 1: `html5` (self-hosted / external mp4 & webm) + control bar + React
+adapter. `youtube` and `vimeo` providers implement the same `Provider`
+interface and land in Phase 2 — nothing else changes when they are added.
+
+## Install
+
+```bash
+npm install @kodezen/player
+```
+
+During local development against this repo directly (before a version is
+published), it can also be consumed from disk (e.g. a webpack alias to
+`dist/`):
+
+```bash
+npm install
+npm run build
+```
+
+## Vanilla usage
+
+```js
+import { createPlayer } from '@kodezen/player';
+import '@kodezen/player/styles.css';
+
+const player = createPlayer(document.getElementById('mount'), {
+  source: { type: 'html5', url: 'https://example.com/lesson.mp4' },
+  resumeAt: 312,        // seconds — host supplies from its own store
+  lockSeek: true,       // block seeking past the furthest watched point
+  speeds: [1, 1.25, 1.5, 2],
+});
+
+player.on('timeupdate', ({ current, furthest, duration, percent }) => {
+  // Host saves this (throttled) to its own backend.
+});
+player.on('ended', () => {/* host may auto-complete */});
+
+// player.play() / pause() / seek(s) / getState() / destroy()
+```
+
+## React usage
+
+```tsx
+import { KodezenPlayer } from '@kodezen/player/react';
+import '@kodezen/player/styles.css';
+
+<KodezenPlayer
+  source={{ type: 'html5', url: lessonUrl }}
+  resumeAt={savedPosition}
+  lockSeek={gatingEnabled}
+  onTimeUpdate={({ percent, current }) => saveProgress(percent, current)}
+  onEnded={() => maybeComplete()}
+/>
+```
+
+## API
+
+`createPlayer(container, options)` → instance.
+
+**Options:** `source {type,url,id,poster,mime}`, `resumeAt`, `lockSeek`,
+`autoplay`, `muted`, `speeds[]`, `controls{}`, `className`.
+
+**Instance:** `play()`, `pause()`, `toggle()`, `seek(s)`, `getState()`,
+`on(event, cb)`, `off(event, cb)`, `destroy()`.
+
+**Events:** `ready`, `play`, `pause`, `timeupdate`, `durationchange`, `ended`,
+`error`. `timeupdate` payload: `{ current, furthest, duration, percent }`
+(`percent` = furthest / duration, so it reflects watched coverage, not the
+scrub position).
+
+## Host integration notes
+
+- **Resume** = pass `resumeAt`; player seeks on `ready` unless within 2s of end.
+- **Watch gate** = enable `lockSeek` and read `percent` from `timeupdate`; the
+  furthest-position measure is only honest while seeking is locked.
+- **Completion** = the host decides (e.g. auto-complete at a threshold or on
+  `ended`); the library stays out of it.