taleem-browser 0.2.0 → 1.0.0-rc.1

package/README.md

@@ -1,228 +1,251 @@
 
 # taleem-browser
 
-**taleem-browser** provides a simple and reliable way to display **JSON-based slide decks** in the browser.
+**taleem-browser** is a small, reliable JavaScript library for displaying
+**JSON-based Taleem slide decks** in the browser.
 
-It is designed for:
-- students  
-- teachers  
-- academics  
-- anyone who wants structured, content-driven slides without complex tools  
+It is intentionally simple.
 
-At its core, `taleem-browser` does one thing well:
+> **Given a valid deck and an index, it renders that slide into the DOM.**
 
-> **Take a slide deck written in JSON and display it as slides.**
+No timing.  
+No autoplay.  
+No hidden state.
 
-You give it a valid deck, and it renders the slides — one at a time — into the page.
+---
 
-That’s it.
+## Why taleem-browser exists
 
-There is no autoplay, no animation system, and no timing dependency.  
-Slides always render, regardless of how simple or complex the deck is.
+Most slide systems mix too many responsibilities:
+- rendering
+- timing
+- navigation
+- animation
+- state
+- UI controls
 
----
+`taleem-browser` deliberately avoids this.
+
+It treats a slide deck as a **document**, not a video.
+
+This makes it:
+- predictable
+- easy to debug
+- easy to test
+- safe for educational content
+- reusable in any UI or framework
 
-## Core idea
+---
 
-A slide deck is treated as a **document**, not a video or animation.
+## What it is
 
-Slides are shown in a fixed order, and the browser moves between them by position (previous, next, or jump to a slide).
+`taleem-browser` is:
 
-This makes slide creation:
-- predictable  
-- easy to debug  
-- safe to modify  
-- suitable for learning and teaching material  
+- an **index-based slide viewer**
+- a **thin DOM wrapper**
+- a **consumer of Taleem decks**
+- a **renderer, not a player**
 
-You focus on **content and structure**.  
-`taleem-browser` handles display and navigation.
+You decide *which slide index to show*.  
+The browser renders it.
 
 ---
 
-## What this library does
+## What it does
 
 `taleem-browser`:
 
 - Accepts a **deck JSON object**
-- Uses `taleem-slides` to render slides into HTML
-- Owns a single DOM mount point
+- Uses **taleem-slides** to convert slide JSON into HTML
+- Injects a fixed DOM structure into a mount point
 - Displays **exactly one slide at a time**
-- Navigates slides by **index**
-- Always succeeds at rendering valid content
+- Renders slides **by numeric index**
+- Never mutates the deck
+- Throws immediately on invalid slide types
 
-The public API is intentionally small:
+The API is intentionally small and stable.
 
-```js
-browser.next()
-browser.prev()
-browser.goTo(index)
-browser.render()
+---
+
+## Installation
+
+```bash
+npm install taleem-browser
 ````
 
-That’s the entire contract.
+---
+
+## Basic usage
+
+```js
+import { createTaleemBrowser } from "taleem-browser";
+import deck from "./deck.json";
+
+const browser = createTaleemBrowser({
+  mount: "#app",
+  deck
+});
 
-There are **no state getters** and **no lifecycle hooks** exposed.
-The browser is controlled purely by commands, and verified by what appears in the DOM.
+browser.render(0);   // render first slide
+browser.render(1);   // render second slide
+```
 
 ---
 
-## What this library intentionally does NOT do
+## Public API
 
-This is not an omission — it is a design choice.
+### `createTaleemBrowser(options)`
 
-`taleem-browser` does **not**:
+Creates a browser instance.
 
-* interpret `start`, `end`, or `showAt`
-* manage time, intervals, or autoplay
-* perform animations or transitions
-* sync audio or narration
-* expose internal state (index, total, slides)
-* depend on any framework (React, Svelte, Vue, etc.)
-* grow configuration options endlessly
+```ts
+createTaleemBrowser({
+  mount: HTMLElement | string,
+  deck: TaleemDeck
+})
+```
+
+#### Parameters
+
+* `mount`
+  A DOM element or a CSS selector where slides will be rendered.
 
-These concerns belong to **different layers or different libraries**.
+* `deck`
+  A **valid Taleem deck JSON object**.
 
 ---
 
-## Styling
+### `browser.render(index)`
 
-Canonical slide styles live in:
+Renders the slide at the given index.
 
-```
-src/styles/taleem.css
+```js
+browser.render(3);
 ```
 
-They are bundled and shipped as part of the release assets.
+* Index is zero-based
+* Out-of-range indexes are ignored
+* Rendering always replaces previous slide content
 
-The browser does not generate styles dynamically.
-Styling is deterministic, inspectable, and override-friendly.
+---
+
+### `browser.getTotal()`
+
+Returns the total number of slides in the deck.
+
+```js
+const total = browser.getTotal();
+```
 
 ---
 
-## Relationship to other Taleem libraries
+## DOM contract
 
-`taleem-browser` is part of a small, layered ecosystem.
+`taleem-browser` injects the following structure into the mount element:
 
-### Lower-level libraries
+```html
+<div class="taleem-browser-bg"></div>
+<div class="taleem-browser-slide"></div>
+```
 
-**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)
+### Meaning
 
-**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-bg`
+  Deck-level background layer
 
-`taleem-browser` sits **above** these libraries so users do not need to wire renderers or schemas manually.
+* `.taleem-browser-slide`
+  Container for the rendered slide HTML
 
-If you want low-level control over rendering, use `taleem-slides` directly.
-If you want a **ready-to-use slide viewer**, use `taleem-browser`.
+These class names are **public and stable** and may be styled by consumers.
 
 ---
 
-## Example deck (gold standard)
+## Styling
 
-A complete, production-quality example deck is available here:
+`taleem-browser` does **not** generate slide styles.
 
-🔗 **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)
+Slide HTML and CSS are defined by **taleem-slides** and/or the consuming application.
 
-This deck is used as a reference for:
+This ensures:
 
-* slide layout
-* spacing
-* typography
-* JSON structure
+* deterministic output
+* inspectable markup
+* no runtime styling surprises
 
 ---
 
-## Advanced playback (out of scope)
+## What this library intentionally does NOT do
 
-Timed playback, animations, narration, or video-like behavior are **explicitly out of scope** for this library.
+This is a design choice, not a limitation.
 
-Timing-related fields such as `start`, `end`, and `showAt` are treated as **metadata**, not requirements.
+`taleem-browser` does **not**:
 
-For deeper reading on timing concepts and EQ-style slides:
+* interpret timing (`start`, `end`, `showAt`)
+* manage playback or autoplay
+* handle animations or transitions
+* validate slide field content
+* expose internal state
+* provide UI controls
+* depend on any framework (React, Svelte, Vue, etc.)
 
-* 📄 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)
+These concerns belong to **other layers**.
 
-* 📄 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.
+## Relationship to other Taleem libraries
 
----
+`taleem-browser` is part of a layered ecosystem.
 
-## Project discipline (important)
+### taleem-core
 
-To keep the core strong, we follow strict rules.
+Defines deck schemas and validation rules.
 
-### ❌ Things we do NOT do
+### taleem-slides
 
-* Do **not** add new slide types casually
-* Do **not** add timing or playback logic
-* Do **not** blur browser and player responsibilities
-* Do **not** expose internal state
-* Do **not** grow the API
-* Do **not** chase frameworks or trends
+Converts slide JSON into HTML templates.
+Used internally by `taleem-browser`.
 
-### ✅ Things we focus on
+`taleem-browser` sits **above** these libraries to provide
+a ready-to-use, index-based slide viewer.
 
-* More example decks
-* CSS and rendering bug fixes
-* Navigation correctness
-* Documentation clarity
-* Stability over novelty
+If you need:
 
-Every “no” protects the core.
+* schema validation → use `taleem-core`
+* raw HTML rendering → use `taleem-slides`
+* timed playback or narration → use a playback layer (e.g. `taleem-player`)
 
 ---
 
-## Minimal usage
+## Testing philosophy
 
-```js
-import { createTaleemBrowser } from "taleem-browser";
-import deck from "./deck.json";
+`taleem-browser` tests **do not validate decks or slides**.
 
-const browser = createTaleemBrowser({
-  mount: "#app",
-  deck
-});
+Tests use a **minimal, known-valid deck** to verify:
 
-browser.next();
-browser.prev();
-browser.goTo(3);
-```
+* DOM injection
+* template resolution
+* deterministic rendering
+* index-based behavior
+
+Slide correctness is explicitly **out of scope** for this library.
 
 ---
 
 ## Design philosophy
 
-* Slides are **content-first**
+* Slides are documents
 * Index is more fundamental than time
-* Rendering should never fail
-* Static viewing is the default
-* Playback is an optional interpretation
+* Rendering should be deterministic
+* State belongs to the caller
+* Small libraries stay correct longer
 
-> **Slides are documents.
-> Timing is an optional playback layer.**
+> **Render by index.
+> Everything else is interpretation.**
 
 ---
 
-## Related project (optional)
-
-`taleem-browser` is actively used in the **Taleem demo project**, which showcases real decks, layouts, and usage patterns as they evolve.
-
-The demo project is provided as a reference, not a dependency:
-
-[https://github.com/bilza2023/taleem](https://github.com/bilza2023/taleem)
+## License
 
----
+MIT
 
-## License
 
-MIT