taleem-browser 0.1.0 → 0.1.3

package/README.md

@@ -1,30 +1,41 @@
-
 # taleem-browser
 
-**taleem-browser** is a minimal, index-based slide document browser.
+**taleem-browser** provides a simple and reliable way to create **JSON-based slide presentations** and display them in the browser.
+
+It is designed for:
+- students
+- teachers
+- academics
+- anyone who wants structured, content-driven slides without complex tools
+
+At its core, `taleem-browser` does one thing well:
 
-At its core, it is a **JSON → Slides engine**:
+> **Take a slide deck written in JSON and display it as slides.**
 
-> **JSON in →  slides out**
+You give it a valid deck, and it renders the slides — one at a time — into the page.
 
-It takes a structured slide deck (JSON) and renders one slide at a time into the DOM, allowing simple, reliable navigation by index.
+That’s it.
 
-There is **no timeline**, **no autoplay**, and **no animation logic** by design.
+There is no autoplay, no animation system, and no timing dependency.  
+Slides always render, regardless of how simple or complex the deck is.
 
 ---
 
 ## Core idea
 
-Slides are **documents**, not animations.
+A slide deck is treated as a **document**, not a video or animation.
+
+Slides are shown in a fixed order, and the browser moves between them by position (previous, next, or jump to a slide).
 
-A deck is an **ordered list of slides**.  
-`taleem-browser` lets you **view and navigate** that list safely and deterministically.
+This makes slide creation:
+- predictable
+- easy to debug
+- safe to modify
+- suitable for learning and teaching material
 
-- No matter how simple or complex the deck is
-- Whether timing metadata exists or not
-- Even if timing metadata is incomplete or wrong
+You focus on **content and structure**.  
+`taleem-browser` handles display and navigation.
 
-Slides always render.
 
 ---
 
@@ -39,47 +50,127 @@ Slides always render.
 - Navigates slides by **index**
 - Always succeeds at rendering content
 
-Navigation is explicit and controlled via a small API:
+The public API is intentionally small:
 
-- `next()`
-- `prev()`
-- `goTo(index)`
+```js
+browser.next()
+browser.prev()
+browser.goTo(index)
+
+browser.getIndex()
+browser.getTotal()
+
+browser.render()
+browser.destroy()
+````
+
+That’s the entire contract.
 
 ---
 
 ## What this library intentionally does NOT do
 
+This is not an omission — it is a design choice.
+
 `taleem-browser` does **not**:
 
-- interpret `start`, `end`, or `showAt`
-- manage time or intervals
-- autoplay slides
-- sync audio or narration
-- perform animations
-- depend on any framework (React, Svelte, etc.)
+* interpret `start`, `end`, or `showAt`
+* manage time, intervals, or autoplay
+* perform animations or transitions
+* sync audio or narration
+* depend on any framework (React, Svelte, Vue, etc.)
+* grow configuration options endlessly
 
-These concerns belong to a **separate playback layer**, not a document browser.
+These concerns belong to **different layers or different libraries**.
 
+---
+“Canonical slide styles live at src/styles/taleem.css and are shipped as a release asset.”
 ---
 
 ## Relationship to other Taleem libraries
 
-`taleem-browser` sits above lower-level libraries:
+`taleem-browser` is part of a small, layered ecosystem.
+
+### Lower-level libraries
 
-- **taleem-core**  
-  Defines schemas and core data rules.
+* **taleem-core**
+  Defines deck schemas, validation rules, and core concepts.
+  📄 API reference:
+  [https://github.com/bilza2023/taleem-core/blob/master/docs/api.md](https://github.com/bilza2023/taleem-core/blob/master/docs/api.md)
 
-- **taleem-slides**  
+* **taleem-slides**
   Converts slide JSON into HTML.
+  This is the renderer used internally by `taleem-browser`.
+  🔗 Repository:
+  [https://github.com/bilza2023/taleem-slides](https://github.com/bilza2023/taleem-slides)
 
-`taleem-browser` uses `taleem-slides` internally so users don’t have to wire renderers manually.
+`taleem-browser` sits **above** these libraries so users do not need to wire renderers or schemas manually.
 
-If you want full control over rendering, you can use `taleem-slides` directly.  
+If you want low-level control over rendering, use `taleem-slides` directly.
 If you want a **ready-to-use slide viewer**, use `taleem-browser`.
 
 ---
 
-## Usage (minimal)
+## Example deck (gold standard)
+
+A complete, production-quality example deck is available here:
+
+🔗 **Demo gold-standard deck**
+[https://github.com/bilza2023/taleem/blob/master/decks/demo-gold.json](https://github.com/bilza2023/taleem/blob/master/decks/demo-gold.json)
+
+This deck is used as a visual and structural reference for:
+
+* slide layout
+* spacing
+* typography
+* JSON structure
+
+---
+
+## Advanced playback (out of scope)
+
+Timed playback, animations, narration, or video-like behavior are **explicitly out of scope** for this library.
+
+Timing-related fields such as `start`, `end`, and `showAt` are treated as **metadata**, not requirements.
+
+For deeper reading on timing concepts and EQ-style slides:
+
+* 📄 EQ slide format (advanced, optional):
+  [https://github.com/bilza2023/taleem-core/blob/master/docs/eq.md](https://github.com/bilza2023/taleem-core/blob/master/docs/eq.md)
+
+* 📄 Timing rules (for playback layers, not the browser):
+  [https://github.com/bilza2023/taleem-core/blob/master/docs/timings.md](https://github.com/bilza2023/taleem-core/blob/master/docs/timings.md)
+
+A future playback layer (e.g. `taleem-player`) may interpret these fields, but `taleem-browser` never depends on them.
+
+---
+
+## Project discipline (important)
+
+To keep the core strong, we follow strict rules:
+
+### ❌ Things we do NOT do
+
+* Do **not** add new slide types (too early)
+* Do **not** add new features casually
+* Do **not** blur browser and player responsibilities
+* Do **not** over-optimize
+* Do **not** grow the API
+* Do **not** chase frameworks or trends
+
+### ✅ Things we focus on
+
+* More example decks
+* CSS and rendering bug fixes
+* Navigation correctness
+* Documentation clarity
+* Stability over novelty
+
+Every “no” protects the core.
+
+---
+
+## Minimal usage
 
 ```js
 import { createTaleemBrowser } from "taleem-browser";
@@ -93,9 +184,7 @@ const browser = createTaleemBrowser({
 browser.next();
 browser.prev();
 browser.goTo(3);
-````
-
-That’s it.
+```
 
 ---
 
@@ -103,7 +192,7 @@ That’s it.
 
 * Slides are **content-first**
 * Index is more fundamental than time
-* Rendering should never fail because of timing
+* Rendering should never fail
 * Static viewing is the default
 * Playback is an optional interpretation
 
@@ -112,14 +201,17 @@ That’s it.
 
 ---
 
-## Advanced playback
+### Related project (optional)
 
-If you need timed playback (e.g. animations, narration, or video-like behavior), use a higher-level utility (such as a future `taleem-player`) that **drives** `taleem-browser`.
+`taleem-browser` is actively used in the **Taleem demo project**, which showcases real decks, layouts, and usage patterns as they evolve.
 
-The browser itself remains simple, stable, and predictable.
+The demo project is a work in progress and is provided as a reference, not a dependency:
+
+https://github.com/bilza2023/taleem
 
 ---
 
 ## License
 
 MIT
+