taleem-player 0.5.0 → 0.7.0-rc

package/README.md

@@ -1,240 +1,263 @@
 
-# 📦 taleem-player
+# Taleem Player
 
-**taleem-player** is a **headless, time-driven playback engine** for Taleem slide decks.
 
-It is designed for:
+<img src="https://raw.githubusercontent.com/bilza2023/taleem-player/main/docs/images/taleem.webp" alt="Taleem Player — JSON to Web Presentations" />
 
-* timed presentations
-* narrated lessons
-* audio / video–synced slides
-* external playback control
+**Taleem Player** is a JavaScript library that converts **JSON slide data** into **web-based presentations**.
 
-At its core, `taleem-player` does one thing well:
+It provides multiple **modes** to display the same JSON presentation in different ways on the web.
 
-> **Given a valid deck and a clock, decide which slide should be active and when.**
+---
+###### Work in progress. Expect minor bugs, but no API breakages.
 
-It does **not** render slides.
-It does **not** define layouts.
-It does **not** ship CSS.
+Demo and Documentation
 
-Those responsibilities belong elsewhere.
+See Taleem Player in action:
 
----
+👉 https://bilza2023.github.io/taleem/
 
-## Core idea
+This live demo lets you explore:
 
-A slide deck can be interpreted in **time**, not just order.
+Browser Mode — instant, index-based slide rendering
 
-`taleem-player` treats a deck as a **timeline**, where each slide occupies a
-known interval:
+Player Mode — time-driven, progressive presentations
 
-```text
-[start ─────────── end)
-```
+Real Taleem slide JSON used in production
+
+Shared CSS system powering all display modes
 
-At any given moment:
+No screenshots. No mock data.
+What you see is the real engine running in the browser.
+---
 
-* exactly one slide may be active
-* or no slide (before / after the timeline)
+## What it does
 
-The player’s job is to **resolve time → slide** and notify a renderer.
+* Takes **Taleem slide JSON**
+* Renders it as a **web presentation**
+* Supports **multiple display modes**
+* Ships **ready-to-use CSS**
+* Includes **utilities** for real-world usage
 
 ---
 
-## What this library does
+## Installation
 
-`taleem-player`:
+```bash
+npm install taleem-player
+```
 
-* Accepts a **deck-v1 JSON object**
-* Enforces **strict timing validity**
-* Owns a single DOM stage
-* Resolves the active slide for a given time
-* Calls an injected **renderer**
-* Supports **scrubbing, autoplay, pause, stop**
-* Is completely **renderer-agnostic**
+---
+
+## Display Modes
+
+### 1. Browser Mode
+
+**Index-based slide viewer**.
 
-The public API is intentionally small:
+Use this when you want:
+
+* manual navigation
+* previews
+* galleries
+* syllabus / editor views
+
+#### API
 
 ```js
-player.renderAt(time)
-player.destroy()
+import { createTaleemBrowser } from "taleem-player";
+
+const browser = createTaleemBrowser({
+  mount: "#app",
+  deck
+});
+
+browser.render(0);      // render slide by index
+browser.getTotal();    // total number of slides
 ```
 
-Higher-level controls (play, pause, keyboard, UI) are built **on top**, not inside.
+Characteristics:
+
+* slide index driven
+* no timing
+* deterministic rendering
+* same slide JSON as other modes
 
 ---
 
-## What this library intentionally does NOT do
+### 2. Player Mode
 
-This is not accidental — it is a design boundary.
+**Time-based slide player**.
 
-`taleem-player` does **not**:
+Use this when you want:
 
-* define slide layouts
-* ship or inject CSS
-* depend on `taleem-slides`
-* interpret slide content
-* infer or auto-fix timings
-* manage audio or narration
-* expose internal state
-* depend on any framework
+* narrated lessons
+* video / audio sync
+* timed presentations
 
-If a deck is invalid, the player **throws**.
-If rendering looks wrong, the renderer is responsible.
+#### API
 
----
+```js
+import { createTaleemPlayer } from "taleem-player";
 
-## Strict timing model (important)
+const player = createTaleemPlayer({
+  mount: "#app",
+  deckDemo and Documentation
 
-`taleem-player` only accepts **player-ready decks**.
+Live demo and documentation are available here:
 
-Every slide **must** define:
+👉 https://bilza2023.github.io/taleem/
 
-```json
-{
-  "start": number,
-  "end": number
-}
-```
+The demo showcases:
 
-Rules:
+browser mode rendering
 
-* `start` and `end` are **absolute seconds**
-* `end` must be greater than `start`
-* No implicit inheritance
-* No auto-injection
-* No browser-style forgiveness
+player mode rendering
 
-This strictness is intentional and non-negotiable.
+real Taleem slide JSON
 
----
+shared CSS across modes
+});
 
-## Renderer contract
+player.renderAt(12.5); // render slide at time (seconds)
+player.destroy();
+```
 
-`taleem-player` does not know how slides look.
+Characteristics:
 
-Instead, it calls a renderer with this contract:
+* time driven
+* external clock control
+* no play / pause logic
+* one active slide at a time
 
-```js
-renderer.render({
-  mount,   // HTMLElement
-  slide,   // full slide JSON
-  time     // absolute time (seconds)
-})
-```
+---
+## Browser Mode vs Player Mode
 
-That’s it.
+Both modes render the same JSON presentation, but they serve very different purposes.
 
-How the slide is rendered — HTML, SVG, Canvas, WebGL — is **not the player’s concern**.
+| Feature | Browser Mode | Player Mode |
+|-------|-------------|-------------|
+| Rendering model | Index-based | Time-based |
+| Navigation | Manual (by slide index) | Progressive (by time) |
+| Timing required | No | Yes (required) |
+| Rendering behavior | One slide at a time | Slides change over time |
+| Control source | Application-driven | External clock / media |
+| Best suited for | Previews, galleries, editors | Narration, video, audio sync |
 
 ---
 
-## Relationship to other Taleem libraries
+### Browser Mode
+
+Use Browser Mode when you want direct access to slides.
+
+**Characteristics**
+- Index-based rendering  
+- No timing data required  
+- Deterministic output  
+
+**Ideal for**
+- previews  
+- galleries  
+- editors  
+- syllabus pages  
 
-`taleem-player` is part of a **layered system**.
 
-### Lower-level
+⚠️ Important:
+In Player Mode, the user must provide valid and ordered timings (start, end).
+The library does not auto-fix or guess timings.
 
-**taleem-slides**
-Pure slide renderer.
-Converts slide JSON into HTML + CSS.
+---
 
-### Higher-level
+## Utilities
 
-**Taleem demo app**
-Wires together:
+Taleem Player includes small helper utilities for preparing decks.
 
-* `taleem-player`
-* `taleem-slides`
-* playback controls
-* UI
+### assignMockTimings
 
-### Sibling
+Convert a non-timed deck into a player-ready deck.
 
-**taleem-browser**
-Index-based slide viewer (no time).
+```js
+import { assignMockTimings } from "taleem-player";
 
-Each library has **one responsibility**.
-They are composed — never merged.
+const timedDeck = assignMockTimings(deck, 5);
+```
 
 ---
 
-## Why this library exists
+### resolveAssetPaths
 
-`taleem-browser` treats slides as a **document**.
-`taleem-player` treats slides as a **timeline**.
+Resolve image paths for deployment.
 
-Both are valid interpretations.
+```js
+import { resolveAssetPaths } from "taleem-player";
 
-By separating them:
+resolveAssetPaths(deck, "/images/");
+```
+
+---
 
-* timed playback does not pollute browsing logic
-* rendering does not pollute playback logic
-* decks remain portable JSON documents
+### resolveBackground
 
-This separation allows:
+Normalize and resolve background configuration.
 
-* narration sync
-* recorded lessons
-* adaptive playback
-* multiple renderers
+```js
+import { resolveBackground } from "taleem-player";
 
-without rewriting the core.
+resolveBackground(deck, "/images/");
+```
 
 ---
 
-## Typical usage (composition layer)
+## CSS
 
-```js
-import { createTaleemPlayer } from "taleem-player";
-import { createSlidesRenderer } from "taleem-slides";
-import "taleem-slides/dist/taleem.css";
+Taleem Player ships with built-in styles.
 
-const renderer = createSlidesRenderer();
+### Base styles
 
-const player = createTaleemPlayer({
-  mount: "#app",
-  deck,
-  renderer
-});
+```js
+import "taleem-player/css";
+```
 
-// external clock
-player.renderAt(12.5);
+### Themes
+
+```js
+import "taleem-player/css/dark";
+import "taleem-player/css/light";
+import "taleem-player/css/paper";
 ```
 
-The **player** never imports slides.
-The **slides** never import the player.
-The **app** composes them.
+CSS controls layout, visibility, and visual behavior.
+Modes share the same CSS.
 
 ---
 
-## Design philosophy (locked)
+## Input format
 
-* Time is external
-* Rendering is replaceable
-* Strictness beats convenience
-* Libraries stay small
-* Composition happens at the edge
+Taleem Player does **not** define slide structure.
 
-> **A player decides *when*.
-> A renderer decides *how*.
-> An app decides *why*.**
+It renders JSON produced for **taleem-slides**.
+
+* Player Mode requires slides with `start` / `end`
+* Browser Mode only needs ordered slides
 
 ---
 
-## Project status
+## What Taleem Player does NOT do
+
+* create slides
+* edit JSON
+* validate schemas
+* manage time or playback
+* handle audio or narration
+* provide UI controls
 
-**Core complete and stable.**
+Those belong to the **application**, not the library.
 
-Future work belongs in:
+---
 
-* demo applications
-* playback UI layers
-* renderers
-* authoring tools
+## Status
 
-The player itself should change rarely.
+**Release Candidate (API stable)**
 
 ---