taleem-browser 0.1.3 → 1.0.0-rc.1

package/README.md

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