taleem-player 1.0.6 → 1.0.8

package/README.md

@@ -1,31 +1,36 @@
 # Taleem Player
 
-<img src="./docs/images/taleem.webp"
-     alt="Taleem Player — JSON to Web Presentations"
-     width="100%" />
-
 **Taleem Player** converts **Taleem JSON slide data** into **web-based presentations**.
 
-It renders the _same taleem JSON_ in multiple ways using different display modes.
+It renders the **same Taleem JSON** in multiple display modes using a single, stable rendering engine.
 
-> **Stable 1.0 — API frozen.**  
+> **Stable · deck-v1 frozen**  
+> The slide language, schema, and registry are complete.  
 > Internal improvements may continue without breaking public contracts.
 
 ---
-
-## Demo & Documentation
-
+Demo & Documentation
 👉 https://bilza2023.github.io/taleem/
 
 The live demo shows:
 
-- Browser Mode (index-based rendering)
-- Player Mode (time-based rendering)
-- Real production Taleem JSON
-- Shared CSS across all modes
+ - Browser Mode (index-based rendering)
+ - Player Mode (time-based rendering)
+ - Real production Taleem JSON
+ - Shared CSS across all modes
+ - No screenshots. No mock data.
+ - What you see is the real engine running in the browser.
+---
+
+## What this project is
+
+Taleem Player is a **presentation engine**, not a slide editor.
 
-**No screenshots. No mock data.  
-What you see is the real engine running in the browser.**
+It takes **validated Taleem decks** and turns them into:
+- index-based presentations
+- time-based presentations
+
+The system is **declarative**, **predictable**, and **CSS-driven**.
 
 ---
 
@@ -33,15 +38,15 @@ What you see is the real engine running in the browser.**
 
 ```bash
 npm install taleem-player
-```
+````
 
 ---
 
 ## Display Modes
 
-### Browser Mode (Index-based)
+### Browser Mode (index-based)
 
-Use when you want **direct access to slides**.
+Use when you want **direct control over which slide is shown**.
 
 ```js
 import { createTaleemBrowser } from "taleem-player";
@@ -55,18 +60,18 @@ browser.render(0);
 browser.getTotal();
 ```
 
-**Ideal for**
+**Best for**
 
-- previews
-- galleries
-- editors
-- syllabus pages
+* previews
+* editors
+* galleries
+* syllabus pages
 
 ---
 
-### Player Mode (Time-based)
+### Player Mode (time-based)
 
-Use when slides must change **progressively over time**.
+Use when slides should progress according to **external timing**.
 
 ```js
 import { createTaleemPlayer } from "taleem-player";
@@ -75,32 +80,43 @@ const player = createTaleemPlayer({ mount: "#app" });
 player.renderAt(12.5);
 ```
 
-**Ideal for**
+**Best for**
 
-- narrated lessons
-- video / audio sync
-- recorded presentations
+* narrated lessons
+* recorded explanations
+* audio / video synchronization
 
 ---
 
-## Browser vs Player (Quick Comparison)
+## Browser vs Player
 
-| Feature         | Browser        | Player         |
-| --------------- | -------------- | -------------- |
-| Rendering       | Index-based    | Time-based     |
-| Timing required | No             | Yes            |
-| Navigation      | Manual         | Progressive    |
-| Control         | App-driven     | External clock |
-| Use case        | Preview / Edit | Playback       |
+| Feature    | Browser Mode | Player Mode |
+| ---------- | ------------ | ----------- |
+| Rendering  | Index-based  | Time-based  |
+| Timing     | Optional     | Required    |
+| Navigation | Manual       | Progressive |
+| Control    | App-driven   | External    |
+| Use case   | Preview      | Playback    |
 
-> ⚠️ Player Mode requires **valid, ordered timings**.
-> The library does not auto-correct or guess timing errors.
+> ⚠️ Player Mode assumes **valid timings**.
+> The library does not guess, correct, or mutate deck data.
 
 ---
 
-## Utilities (Runtime-safe)
+## Slide System
 
-These **Utilities (Runtime-safe)** are exported :
+* The core system defines **16 canonical slide types**
+* The slide registry is **stable and frozen**
+* Slides express **visual state**, not interaction
+* All motion and emphasis are **CSS-based**
+
+If a deck validates against `deck-v1`, it is correct Taleem data.
+
+---
+
+## Utilities (runtime-safe)
+
+The following helpers are exported for **application use**:
 
 ```js
 import {
@@ -111,12 +127,13 @@ import {
 } from "taleem-player";
 ```
 
-- `assignMockTimings(deck, seconds)`
-- `resolveAssetPaths(deck, basePath)`
-- `resolveBackground(deck, basePath)`
-- `getDeckEndTime(deck)`
+* `assignMockTimings(deck, seconds)`
+* `resolveAssetPaths(deck, basePath)`
+* `resolveBackground(deck, basePath)`
+* `getDeckEndTime(deck)`
 
-These helpers prepare decks for real usage and runtime playback.
+These functions **prepare** decks for runtime usage.
+They never change slide meaning.
 
 ---
 
@@ -129,31 +146,63 @@ import "taleem-player/css/light";
 import "taleem-player/css/paper";
 ```
 
-CSS must be imported explicitly by the host app.
-All modes share the same styling system.
+CSS is **explicitly imported** by the host application.
+
+* No JS-driven interaction
+* No runtime behavior logic
+* Visual changes are handled via **CSS state**
 
 ---
 
 ## What Taleem Player does NOT do
 
-- create slides
-- edit JSON
-- manage clocks or media playback
-- handle audio or narration
-- auto-validate or repair data
+Taleem Player does **not**:
+
+* create slides
+* edit JSON
+* manage playback clocks
+* handle audio or narration
+* auto-fix invalid data
+* provide interactive UI controls
 
-Those responsibilities belong to the **application layer**.
+Those responsibilities belong to **application-level projects** or **slide bundles**.
+
+---
+
+## Slide Extensions
+
+The core slide language is **closed**.
+
+Additional slides should be developed as:
+
+* external slide bundles
+* application-specific extensions
+
+The core registry supports **additive registration only**.
+
+---
+
+## EQ slide
+
+The `eq` slide type is implemented and tested.
+
+It represents **structured symbolic content** and intentionally marks the **upper boundary** of the system.
+
+Anything more complex than this belongs in a **separate product**, not in the core player.
 
 ---
 
 ## Status
 
-**Stable — Version 1.0**
+**Stable · deck-v1 frozen**
+
+The system is complete and production-safe.
+
+Future work should focus on:
 
-The `eq` slide type is **experimental**:
-- it is implemented but intentionally limited
-- it should not be relied on for production math rendering
-- its behavior may evolve without breaking the core player API
+* content
+* slide bundles
+* authoring tools
 
 ---
 

package/dist/css/taleem.css

@@ -273,9 +273,6 @@
     }
     
 
-
-    /* ///////fixes  */
-
     /* -------------------------------
    Image + Bullets (Side by Side)
    ------------------------------- */
@@ -346,19 +343,211 @@
 }
   
 
+/* =====================================================
+   EQ — Final visual behavior
+   ===================================================== */
+
+/* EQ should grow from TOP, not vertical center */
+.slide.eq.imageRightBulletsLeft {
+  align-items: flex-start;
+}
+
+/* ---------- EQ: equation lines as table rows ---------- */
+
+.slide.eq.imageRightBulletsLeft .eq-lines {
+  flex: 1;
+  list-style: none;          /* remove bullet visuals */
+  padding: 0;
+  margin: 0;
+
+  display: flex;
+  flex-direction: column;
+  gap: 0;
+}
+
+.slide.eq.imageRightBulletsLeft .eq-lines li {
+  padding: 14px 18px;
+  font-size: 2.6rem;
+  line-height: 1.45;
+
+  border-bottom: 1px solid rgba(255, 255, 255, 0.18);
+  background: rgba(255, 255, 255, 0.03);
+
+  transition: background 0.25s ease, color 0.25s ease;
+}
+
+/* selected (latest) line */
+.slide.eq.imageRightBulletsLeft .eq-lines li:last-child {
+  background: rgba(245, 197, 66, 0.18); /* soft yellow */
+  color: #ffd7a3;                      /* warm / reddish */
+  font-weight: 600;
+}
+
+/* ---------- RIGHT: fixed explanation panel ---------- */
+
+.slide.eq.imageRightBulletsLeft .eq-side-panel {
+  flex: 1;
+  height: 75vh;               /* FIXED height → no shaking */
+  overflow: hidden;           /* contain layout */
+
+  padding: 28px 32px;
+
+  background: rgba(0, 0, 0, 0.35);
+  border: 1px solid rgba(255, 255, 255, 0.18);
+  border-radius: 16px;
+
+  box-shadow: 0 12px 30px rgba(0, 0, 0, 0.45);
+
+  display: flex;
+  flex-direction: column;
+}
+
+/* ---------- Side panel items ---------- */
+
+.slide.eq.imageRightBulletsLeft .eq-explain-item {
+  font-size: 1.4rem;
+  line-height: 1.45;
+  text-align: center;
+
+  word-wrap: break-word;
+  overflow-wrap: break-word;
+
+  background: rgba(255, 255, 255, 0.06);
+  padding: 14px 18px;
+  border-radius: 12px;
+}
+
+/* ---------- Side panel image ---------- */
+
+.slide.eq.imageRightBulletsLeft .eq-explain-image img {
+  width: 70%;
+  margin: 0 auto;            /* center image */
+  display: block;
+
+  border-radius: 12px;
+}
+
+/* =====================================================
+   Bar Chart Slide
+   ===================================================== */
+
+   .slide.barChart {
+    justify-content: center;
+    align-items: center;
+    text-align: left;
+  }
+  
+  .slide.barChart .bar-chart {
+    width: 100%;
+    max-width: 900px;
+  
+    display: flex;
+    flex-direction: column;
+    gap: 22px;
+  }
+  
+  /* one bar row */
+  .slide.barChart .bar-row {
+    display: flex;
+    align-items: center;
+    gap: 20px;
+  }
+  
+  /* label on the left */
+  .slide.barChart .bar-label {
+    width: 220px;
+    font-size: 2.2rem;
+    opacity: 0.9;
+    flex-shrink: 0;
+  }
+  
+  /* bar background */
+  .slide.barChart .bar-track {
+    flex: 1;
+    height: 26px;
+  
+    background: rgba(255, 255, 255, 0.15);
+    border-radius: 13px;
+    overflow: hidden;
+  }
+  
+  /* actual bar */
+  .slide.barChart .bar-fill {
+    height: 100%;
+    width: 0;
+  
+    background: #ff9900;
+    border-radius: 13px;
+  }
+  
+  /* numeric value on right */
+  .slide.barChart .bar-value {
+    width: 48px;
+    text-align: right;
+    font-size: 2rem;
+    opacity: 0.85;
+  }
+
+  
+  /* -------------------------------
+   Progress Bar Slide
+   ------------------------------- */
+
+.slide.progressbar {
+  justify-content: center;
+  align-items: center;
+  text-align: left;
+}
+
+.slide.progressbar .progressbar-item {
+  width: 100%;
+  max-width: 900px;
+
+  display: flex;
+  flex-direction: column;
+  gap: 14px;
+
+  margin-bottom: 28px;
+}
+
+.slide.progressbar .progressbar-label {
+  font-size: 2.4rem;
+  font-weight: 600;
+  opacity: 0.9;
+}
+
+.slide.progressbar .progressbar-track {
+  width: 100%;
+  height: 28px;
+
+  background: rgba(255, 255, 255, 0.18);
+  border-radius: 14px;
+  overflow: hidden;
+}
+
+.slide.progressbar .progressbar-fill {
+  height: 100%;
+  width: 0;
+
+  background: #ff9900;
+  border-radius: 14px;
+
+  transition: width 0.6s ease;
+}
+
 /* -------------------------------
-   Corner Words Slide (4 Quadrants)
+   Key Ideas Slide (Corner Words / 4 Quadrants)
    ------------------------------- */
 
-   .slide.cornerWordsSlide {
+   .slide.keyIdeasSlide {
     position: relative;
     width: 100%;
     height: 100vh;
     padding: 0;
   }
   
-  /* base card */
-  .cornerWordsSlide .corner-card {
+  /* base idea block */
+  .slide.keyIdeasSlide .key-idea {
     position: absolute;
     width: 45%;
     height: 45%;
@@ -375,114 +564,36 @@
     text-align: center;
   }
   
-  /* emoji / icon */
-  .cornerWordsSlide .corner-card .icon {
+  /* icon */
+  .slide.keyIdeasSlide .key-idea .icon {
     font-size: 5.2rem;
     line-height: 1;
   }
   
-  /* label text */
-  .cornerWordsSlide .corner-card .label {
+  /* label */
+  .slide.keyIdeasSlide .key-idea .label {
     font-size: 3.6rem;
     font-weight: 600;
   }
   
   /* quadrants */
-  .cornerWordsSlide .corner-1 {
+  .slide.keyIdeasSlide .key-idea:nth-child(1) {
     top: 0;
     left: 0;
   }
   
-  .cornerWordsSlide .corner-2 {
+  .slide.keyIdeasSlide .key-idea:nth-child(2) {
     top: 0;
     right: 0;
   }
   
-  .cornerWordsSlide .corner-3 {
+  .slide.keyIdeasSlide .key-idea:nth-child(3) {
     bottom: 0;
     left: 0;
   }
   
-  .cornerWordsSlide .corner-4 {
+  .slide.keyIdeasSlide .key-idea:nth-child(4) {
     bottom: 0;
     right: 0;
   }
-
-  
-
-  /* =====================================================
-   EQ — TWO COLUMN (FIXED EXPLANATION PANEL)
-   ===================================================== */
-
-.slide.eq.eq-two-column {
-  display: flex;
-  flex-direction: row;
-  align-items: center;
-  justify-content: center;
-
-  gap: 64px;
-  text-align: left;
-}
-
-/* LEFT PANEL — explanation (replaces image area) */
-.eq-explain-panel {
-  flex: 1;
-  max-width: 520px;
-
-  background: rgba(0, 0, 0, 0.35);
-  border: 1px solid rgba(255, 255, 255, 0.15);
-  border-radius: 14px;
-
-  padding: 28px 32px;
-
-  display: flex;
-  flex-direction: column;
-  gap: 18px;
-
-  box-shadow: 0 12px 30px rgba(0, 0, 0, 0.45);
-}
-
-/* explanation item */
-.eq-explain-item {
-  font-size: 2.4rem;
-  line-height: 1.45;
-  opacity: 0.95;
-}
-
-/* placeholder when nothing active */
-.eq-explain-placeholder {
-  opacity: 0.5;
-  font-style: italic;
-}
-
-/* RIGHT PANEL — equation lines */
-.eq-lines-panel {
-  flex: 1;
-  max-width: 520px;
-
-  display: flex;
-  flex-direction: column;
-  gap: 16px;
-}
-
-/* equation line */
-.eq-line {
-  background: rgba(255, 255, 255, 0.04);
-  border: 1px solid rgba(255, 255, 255, 0.18);
-  border-radius: 10px;
-
-  padding: 14px 18px;
-
-  font-size: 2.6rem;
-  line-height: 1.5;
-
-  transition:
-    background 0.25s ease,
-    border-color 0.25s ease;
-}
-
-/* active line */
-.eq-line.active {
-  background: rgba(255, 255, 255, 0.08);
-  border-color: rgba(120, 160, 255, 0.65);
-}
+