taleem-slides 0.3.0

package/README.md

@@ -0,0 +1,224 @@
+
+# 📦 taleem-slides
+
+> **Deterministic slide interpretation & rendering engine for deck-v1**
+
+`taleem-slides` is a **pure, test-locked rendering layer**.
+It takes a validated `deck-v1` JSON and produces **deterministic HTML output** through a strict public API.
+
+This project does **not**:
+
+* build decks
+* mutate data
+* manage timing state
+* expose slide internals
+
+It only **interprets** and **renders**.
+
+---
+
+## 🧠 Mental Model
+
+```
+deck-v1 JSON
+   ↓
+slideBuilder()
+   ↓
+SlideManager
+   ↓
+renderSlide(index [, showAt])
+```
+
+Key idea:
+**Slides are private. Rendering is the only contract.**
+
+---
+
+## ✅ What This Project Guarantees
+
+* Deterministic rendering (same input → same HTML)
+* Strict validation per slide type
+* Zero mutation after build
+* No access to internal slide objects
+* Full test coverage across all slide types
+
+---
+
+## 🔑 Public API
+
+### `slideBuilder(deckV1Json) → SlideManager`
+
+Builds and validates a deck, returning a `SlideManager`.
+
+```js
+import { slideBuilder } from "taleem-slides";
+
+const manager = slideBuilder(deckJson);
+```
+
+Throws immediately on:
+
+* invalid deck structure
+* unsupported slide types
+* invalid slide data
+
+---
+
+### `SlideManager.renderSlide(index, showAt?) → string`
+
+Renders **one slide** to HTML.
+
+```js
+const html = manager.renderSlide(0);
+```
+
+Notes:
+
+* `index` is zero-based
+* `showAt` is optional (for time-aware slides)
+* return value is **plain HTML string**
+
+---
+
+### `SlideManager.renderAll() → string`
+
+Renders **all slides** as a static HTML dump.
+
+```js
+const fullHtml = manager.renderAll();
+```
+
+---
+
+## 🔒 Encapsulation Rules (By Design)
+
+* `SlideManager` does **not** expose slides
+* Slides are frozen internally
+* Rendered output is a string (immutable by nature)
+
+If you want to *inspect structure*, that belongs in **taleem-core**, not here.
+
+---
+
+## 🧪 Testing Philosophy
+
+This project has **56 passing tests** covering:
+
+* slideBuilder validation
+* every slide type
+* deterministic rendering
+* error handling
+* edge cases
+
+Tests assert **behavior**, not snapshots.
+
+This test suite is the **living specification**.
+
+---
+
+## 🎞️ Supported Slide Types
+
+`taleem-slides` supports all canonical `deck-v1` slide types, including:
+
+* titleSlide
+* titleAndSubtitle
+* titleAndPara
+* bulletList
+* twoColumnText
+* imageSlide
+* imageWithTitle
+* imageWithCaption
+* imageLeftBulletsRight
+* imageRightBulletsLeft
+* table
+* statistic
+* donutChart
+* barChart
+* bigNumber
+* quoteSlide
+* quoteWithImage
+* cornerWordsSlide
+* contactSlide
+* fillImage
+* eq
+* svgPointer
+
+All validation rules are enforced at build time.
+
+---
+
+## 🧊 Versioning & Stability
+
+* This project targets **deck-v1 only**
+* No breaking changes without `deck-v2`
+* Rendering output is intentionally simple HTML
+* Styling is the responsibility of the consuming app
+
+---
+
+## 📍 When to Use This
+
+Use `taleem-slides` when you want:
+
+* a **trustworthy rendering engine**
+* clean separation from content generation
+* confidence that slides behave exactly as specified
+
+Do **not** use it for:
+
+* authoring decks
+* editing slides
+* managing playback state
+
+---
+
+---
+
+# 🧠 taleem-core (Contextual Overview)
+
+> **Authoring & specification layer for deck-v1**
+
+`taleem-core` is responsible for **creating valid decks**.
+`taleem-slides` is responsible for **rendering them**.
+
+They are intentionally separate.
+
+---
+
+## Responsibility Split
+
+| Concern             | taleem-core | taleem-slides |
+| ------------------- | ----------- | ------------- |
+| Deck creation       | ✅           | ❌             |
+| Schema validation   | ✅           | ❌             |
+| EQ expansion        | ✅           | ❌             |
+| Timing rules        | ✅           | ❌             |
+| Rendering HTML      | ❌           | ✅             |
+| Slide encapsulation | ❌           | ✅             |
+
+---
+
+## Core Artifacts
+
+From the docs you uploaded:
+
+* `api.md` → defines **deck-v1 contract**
+* `eq.md` → defines **EQ slide expansion rules**
+* `timings.md` → defines **global timing semantics**
+
+`taleem-slides` **trusts** these documents.
+It does not reinterpret them.
+
+---
+
+## Architectural Law (Important)
+
+> **Authoring and rendering must never mix**
+
+Once a deck enters `taleem-slides`, it is:
+
+* assumed valid
+* treated as immutable
+* rendered deterministically
+
+This is why the system scales cleanly.

package/decks/angles_and_transversals.json

@@ -0,0 +1,85 @@
+{
+  "name": "Angles and Transversals",
+  "description": "Intro to angle types formed by a transversal — with memory trick",
+  "tags": [
+    "geometry",
+    "angles",
+    "class9"
+  ],
+  "status": "ready",
+  "createdAt": "2025-07-25T16:04:36.820Z",
+  "editedAt": "2025-07-25T16:04:36.820Z",
+  "version": "deck-v1",
+  "background": {
+    "backgroundColor": "#F3E5AB",
+    "backgroundImage": "/media/images/taleem.webp",
+    "backgroundImageOpacity": 0.1
+  },
+  "deck": [
+    {
+      "start": 0,
+      "end": 9.02,
+      "type": "titleSlide",
+      "data": [
+        {
+          "name": "title",
+          "content": "Angles and Transversals",
+          "showAt": 0
+        }
+      ]
+    },
+    {
+      "start": 9.02,
+      "end": 33.87,
+      "type": "imageSlide",
+      "data": [
+        {
+          "name": "image",
+          "content": "/media/images/traversal.webp",
+          "showAt": 0
+        }
+      ]
+    },
+    {
+      "start": 33.87,
+      "end": 52.85,
+      "type": "titleAndSubtitle",
+      "data": [
+        {
+          "name": "title",
+          "content": "Memory Line",
+          "showAt": 0
+        },
+        {
+          "name": "subtitle",
+          "content": "Jahan angles milay — Alternate aur Corresponding barabar, Interior mil ke 180!",
+          "showAt": 0
+        }
+      ]
+    },
+    {
+      "start": 52.85,
+      "end": 188.09,
+      "type": "imageSlide",
+      "data": [
+        {
+          "name": "image",
+          "content": "/media/images/angles.jpg",
+          "showAt": 0
+        }
+      ]
+    },
+    {
+      "start": 188.09,
+      "end": 196.18,
+      "type": "titleSlide",
+      "data": [
+        {
+          "name": "title",
+          "content": "Jahan angles milay — Alternate aur Corresponding barabar, Interior mil ke 180!",
+          "showAt": 0
+        }
+      ]
+    }
+  ]
+}

package/decks/congruent_triangles.json

@@ -0,0 +1,169 @@
+{
+  "name": "congruent_triangles",
+  "description": "Class 9 Geometry — Congruent Triangles Summary",
+  "tags": [
+    "math",
+    "geometry",
+    "triangles"
+  ],
+  "status": "draft",
+  "createdAt": "2025-07-21T00:00:00Z",
+  "editedAt": "2025-07-21T00:00:00Z",
+  "version": "deck-v1",
+  "background": {
+    "backgroundColor": "#F3E5AB",
+    "backgroundImage": "/images/taleem.webp",
+    "backgroundImageOpacity": 0.07
+  },
+  "deck": [
+    {
+      "start": 0,
+      "end": 10,
+      "type": "imageWithTitle",
+      "data": [
+        {
+          "name": "image",
+          "content": "/images/congruent_triangle.webp",
+          "showAt": 0
+        },
+        {
+          "name": "title",
+          "content": "Congruent Triangles",
+          "showAt": 2
+        }
+      ]
+    },
+    {
+      "start": 10,
+      "end": 30,
+      "type": "imageLeftBulletsRight",
+      "data": [
+        {
+          "name": "image",
+          "content": "/images/congruent_triangle2.webp",
+          "showAt": 10
+        },
+        {
+          "name": "bullet",
+          "content": "Same shape and same size",
+          "showAt": 13
+        },
+        {
+          "name": "bullet",
+          "content": "All sides and angles are equal",
+          "showAt": 16
+        },
+        {
+          "name": "bullet",
+          "content": "Can fit exactly on top of each other",
+          "showAt": 19
+        }
+      ]
+    },
+    {
+      "start": 30,
+      "end": 35,
+      "type": "titleAndSubtitle",
+      "data": [
+        {
+          "name": "title",
+          "content": "4 Rules to Prove Congruence",
+          "showAt": 30
+        },
+        {
+          "name": "subtitle",
+          "content": "SAS, ASA, SSS, RHS",
+          "showAt": 32
+        }
+      ]
+    },
+    {
+      "start": 35,
+      "end": 50,
+      "type": "bulletList",
+      "data": [
+        {
+          "name": "bullet",
+          "content": "SAS: Side–Angle–Side",
+          "showAt": 36
+        },
+        {
+          "name": "bullet",
+          "content": "ASA: Angle–Side–Angle",
+          "showAt": 38
+        },
+        {
+          "name": "bullet",
+          "content": "SSS: Side–Side–Side",
+          "showAt": 41
+        },
+        {
+          "name": "bullet",
+          "content": "RHS: Right-angle–Hypotenuse–Side",
+          "showAt": 44
+        }
+      ]
+    },
+    {
+      "start": 50,
+      "end": 55,
+      "type": "titleAndSubtitle",
+      "data": [
+        {
+          "name": "title",
+          "content": "Similar vs Congruent",
+          "showAt": 50
+        },
+        {
+          "name": "subtitle",
+          "content": "Not all triangles that look alike are congruent",
+          "showAt": 52
+        }
+      ]
+    },
+    {
+      "start": 55,
+      "end": 75,
+      "type": "imageLeftBulletsRight",
+      "data": [
+        {
+          "name": "image",
+          "content": "/images/congruent_triangle2.webp",
+          "showAt": 55
+        },
+        {
+          "name": "bullet",
+          "content": "Congruent: exact match in size and shape",
+          "showAt": 58
+        },
+        {
+          "name": "bullet",
+          "content": "Similar: same shape, different size",
+          "showAt": 61
+        },
+        {
+          "name": "bullet",
+          "content": "Similar ≠ Congruent (they don’t “fit”)",
+          "showAt": 64
+        }
+      ]
+    },
+    {
+      "start": 75,
+      "end": 85,
+      "type": "quoteSlide",
+      "data": [
+        {
+          "name": "quoteLine",
+          "content": "Congruent triangles are the building blocks of geometric proof.",
+          "showAt": 75
+        },
+        {
+          "name": "author",
+          "content": "— Taleem.Help",
+          "showAt": 78
+        }
+      ]
+    }
+  ]
+}

package/decks/demo_deck.json

@@ -0,0 +1,22 @@
+{
+  "version": "deck-v1",
+  "name": "demo-minimal",
+  "deck": [
+    {
+      "start": 0,
+      "end": 10,
+      "type": "titleSlide",
+      "data": [
+        { "name": "title", "content": "Angles and Transversals", "showAt": 0 }
+      ]
+    },
+    {
+      "start": 10,
+      "end": 20,
+      "type": "titleSlide",
+      "data": [
+        { "name": "title", "content": "Parallel Lines and Transversals", "showAt": 0 }
+      ]
+    }
+  ]
+}

package/decks/eq_28aug2025.json

@@ -0,0 +1,67 @@
+{
+    "name": "eq_long_test",
+    "description": "Title + 1 long eq slide with 15 lines",
+    "tags": ["test", "eq"],
+    "status": "draft",
+    "version": "deck-v1",
+    "background": {
+      "backgroundColor": "#F3E5AB",
+      "backgroundImage": "/images/taleem.webp",
+      "backgroundImageOpacity": 0.07
+    },
+    "deck": [
+      {
+        "type": "imageWithTitle",
+        "start": 0,
+        "end": 5,
+        "data": [
+          {
+            "name": "image",
+            "content": "/images/box.webp",
+            "showAt": 0
+          },
+          {
+            "name": "title",
+            "content": "Equations Test Deck",
+            "showAt": 0
+          }
+        ]
+      },
+      {
+        "type": "eq",
+        "start": 5,
+        "end": 50,
+        "data": [
+          { "name": "line", "type": "heading", "content": "Algebra & Physics Equations", "showAt": 5 },
+  
+          { "name": "line", "type": "math", "content": "a^2 + b^2 = c^2", "showAt": 7, "spItems": [{ "type": "spText", "content": "Pythagoras theorem" }] },
+          { "name": "line", "type": "text", "content": "This relates the sides of a right triangle.", "showAt": 9 },
+  
+          { "name": "line", "type": "math", "content": "F = m \\times a", "showAt": 11, "spItems": [{ "type": "spHeading", "content": "Newton's Second Law" }] },
+          { "name": "line", "type": "text", "content": "Force equals mass times acceleration.", "showAt": 13 },
+  
+          { "name": "line", "type": "math", "content": "E = m c^2", "showAt": 15, "spItems": [{ "type": "spMath", "content": "c = speed of light" }] },
+          { "name": "line", "type": "text", "content": "Energy-mass equivalence from Einstein.", "showAt": 17 },
+  
+          { "name": "line", "type": "math", "content": "V = I R", "showAt": 19 },
+          { "name": "line", "type": "text", "content": "Ohm's Law: voltage, current, resistance.", "showAt": 21 },
+  
+          { "name": "line", "type": "math", "content": "p = m v", "showAt": 23 },
+          { "name": "line", "type": "text", "content": "Momentum equals mass times velocity.", "showAt": 25 },
+  
+          { "name": "line", "type": "math", "content": "KE = 1/2 m v^2", "showAt": 27 },
+          { "name": "line", "type": "text", "content": "Kinetic energy formula.", "showAt": 29 },
+  
+          { "name": "line", "type": "math", "content": "PE = m g h", "showAt": 31 },
+          { "name": "line", "type": "text", "content": "Potential energy at height h.", "showAt": 33 },
+  
+          { "name": "line", "type": "math", "content": "Q = m c ΔT", "showAt": 35 },
+          { "name": "line", "type": "text", "content": "Heat energy gained or lost.", "showAt": 37 },
+  
+          { "name": "line", "type": "math", "content": "v = d / t", "showAt": 39 },
+          { "name": "line", "type": "text", "content": "Velocity is distance over time.", "showAt": 41 }
+        ]
+      }
+    ]
+  }
+  

package/decks/goldstandar_eq_28aug25.json

@@ -0,0 +1,69 @@
+{
+    "name": "goldstandard_eq_28aug25",
+    "description": "Title + one long EQ slide (FLAT authoring) covering all sidebar types",
+    "tags": ["eq", "gold-standard", "flat-authoring"],
+    "status": "draft",
+    "version": "deck-v1",
+    "background": {
+      "backgroundColor": "#0e0f14",
+      "backgroundImage": "/media/images/box.webp",
+      "backgroundImageOpacity": 0.07
+    },
+    "deck": [
+      {
+        "type": "imageWithTitle",
+        "start": 0,
+        "end": 5,
+        "data": [
+          { "name": "image", "content": "/media/images/box.webp", "showAt": 0 },
+          { "name": "title", "content": "EQ Sidebar Gold Standard", "showAt": 0 }
+        ]
+      },
+      {
+        "type": "eq",
+        "start": 5,
+        "end": 55,
+        "data": [
+          { "name": "heading", "content": "Test All Sidebar Types", "showAt": 5 },
+      
+          { "name": "spHeading", "content": "SP Heading" },
+          { "name": "spText", "content": "This is a sidebar comment." },
+          { "name": "spMath", "content": "a^2 + b^2 = c^2" },
+          { "name": "spImage", "content": "/media/images/box.webp" },
+      
+          { "name": "math", "content": "E = mc^2", "showAt": 12 },
+          { "name": "spHeading", "content": "Einstein's Law" },
+          { "name": "spText", "content": "Energy–mass equivalence" },
+          { "name": "spImage", "content": "/media/images/box.webp" },
+      
+          { "name": "math", "content": "\\int_0^\\pi \\sin x \\,dx = 2", "showAt": 20 },
+          { "name": "spHeading", "content": "Integral Result" },
+          { "name": "spText", "content": "Area under sine from 0 to π" },
+          { "name": "spMath", "content": "\\int_0^\\pi \\sin x \\,dx = 2" },
+      
+          { "name": "math", "content": "\\sum_{n=1}^{\\infty} \\frac{1}{n^2} = \\frac{\\pi^2}{6}", "showAt": 28 },
+          { "name": "spHeading", "content": "Basel Problem" },
+          { "name": "spText", "content": "Euler's celebrated result" },
+          { "name": "spImage", "content": "/media/images/box.webp" },
+      
+          { "name": "text", "content": "Ohm’s Law", "showAt": 36 },
+          { "name": "spMath", "content": "V = I R" },
+          { "name": "spText", "content": "Voltage = Current × Resistance" },
+      
+          { "name": "math", "content": "p = m v", "showAt": 42 },
+          { "name": "spText", "content": "Momentum = mass × velocity" },
+      
+          { "name": "math", "content": "KE = ½ m v^2", "showAt": 46 },
+          { "name": "spText", "content": "Kinetic energy formula" },
+      
+          { "name": "math", "content": "PE = m g h", "showAt": 50 },
+          { "name": "spText", "content": "Potential energy at height h" },
+      
+          { "name": "text", "content": "End of test. All sidebar types shown.", "showAt": 54 },
+          { "name": "spText", "content": "Thanks for testing EQ format!" }
+      
+        ]
+      }
+    ]
+  }
+