taleem-player 0.0.1

package/README.md

@@ -0,0 +1,267 @@
+
+# 🧠 `@taleem/player`
+
+**Version:** v1.0.0
+**Status:** STABLE
+**Scope:** Slide interpretation (NO UI)
+**Depends on:** `deck-v1` (from `taleem-core`)
+**Renders:** ❌ Nothing
+
+---
+
+## Purpose
+
+`@taleem/player` is the **semantic interpreter** for Taleem slide decks.
+
+It takes a validated `deck-v1` document and answers one question only:
+
+> **“What does this slide mean?”**
+
+It does **not** render HTML, does **not** touch the DOM, and does **not** know where or how slides will be displayed.
+
+If you are looking for UI, CSS, animations, audio, or frameworks —
+**you are in the wrong repository.**
+
+---
+
+## What this package DOES
+
+`@taleem/player` is responsible for:
+
+1. Interpreting slide **types** (`titleSlide`, `eq`, `twoColumnText`, …)
+2. Grouping **flat slide data** into semantic regions
+3. Enforcing **slide meaning contracts**
+4. Producing **render-ready frames** (pure data)
+5. Failing loudly on unsupported slide types
+
+It is the **single authority** on what a slide *means*.
+
+---
+
+## What this package does NOT do
+
+This package intentionally does **NOT**:
+
+* Render HTML
+* Use `document`, `window`, or the DOM
+* Load files or URLs
+* Manage time loops or playback
+* Handle user input
+* Know about CSS, layouts, or screen sizes
+* Store state or progress
+* Perform validation (that’s `taleem-core`)
+
+If you feel tempted to add any of the above here — stop.
+
+---
+
+## Architectural position
+
+```
+Deck JSON (deck-v1)
+        ↓
+   taleem-core
+        ↓
+   @taleem/player
+        ↓
+ Renderer (web / pdf / video / cli)
+```
+
+The Player **sits between content and rendering**.
+
+* Everything above it can change.
+* Everything below it can change.
+* The Player must remain **pure and stable**.
+
+---
+
+## Mental model (IMPORTANT)
+
+> **Slides are documents, not components.**
+> **The Player interprets.**
+> **Renderers paint.**
+
+This repository exists because violating that boundary causes years of pain.
+
+---
+
+## Public API
+
+### Import
+
+```js
+import { Player } from "@taleem/player";
+```
+
+---
+
+### Creating a Player
+
+```js
+const player = new Player(deck);
+```
+
+Where `deck` is a valid `deck-v1` document.
+
+---
+
+### Frame generation (index-based)
+
+```js
+const frame = player.getFrameByIndex(0);
+```
+
+Returns a **render instruction**:
+
+```js
+{
+  type: "titleSlide",
+  regions: {
+    title: "Angles and Transversals"
+  },
+  meta: {
+    start: 0,
+    end: 10
+  }
+}
+```
+
+* `type` → slide semantic type
+* `regions` → grouped, interpreted data
+* `meta` → timing metadata (passed through, not used)
+
+---
+
+### Time-based access (future / optional)
+
+```js
+const frame = player.getFrame(timeInSeconds);
+```
+
+Time support exists but is **not required** for basic rendering.
+Navigation and playback loops live **outside** the Player.
+
+---
+
+## Slide semantics (core responsibility)
+
+### Example: `twoColumnText`
+
+Input (flat):
+
+```js
+[
+  { name: "title", content: "Topic", showAt: 0 },
+  { name: "left", content: "Left text", showAt: 1 },
+  { name: "right", content: "Right text", showAt: 2 }
+]
+```
+
+Output (interpreted):
+
+```js
+{
+  title: "Topic",
+  left: ["Left text"],
+  right: ["Right text"]
+}
+```
+
+The **grouping logic lives here**, not in the renderer.
+
+---
+
+## EQ slide support (gold standard)
+
+This Player fully supports the **flat EQ authoring model** defined in `eq.md`.
+
+Key rules (frozen):
+
+* EQ input is a **flat array**
+* Non-`sp*` items start a new line
+* All following `sp*` items attach to the last line
+* Sidebars are semantic, not structural
+
+This logic is implemented and **covered by tests**.
+
+---
+
+## Tests and trust
+
+This package has automated tests that verify:
+
+* Basic frame generation
+* Index-based navigation
+* EQ sidebar grouping behavior
+* Boundary enforcement
+
+If tests pass:
+
+* the Player is correct
+* slide meaning is stable
+* future refactors are safe
+
+---
+
+## Design rules (DO NOT BREAK)
+
+1. No DOM access
+2. No renderer imports
+3. No CSS
+4. No framework assumptions
+5. No silent behavior changes
+6. No auto-mutation of decks
+7. New slide types require **explicit Player support**
+
+If a new slide type appears in a deck and the Player does not support it,
+**the Player must throw**.
+
+Silent fallbacks are forbidden.
+
+---
+
+## Relationship to other packages
+
+* **`taleem-core`**
+  Defines *what a deck is* and *how time maps to slides*
+
+* **`@taleem/player`** (this repo)
+  Defines *what slides mean*
+
+* **Renderers (web / pdf / video)**
+  Define *how slides look*
+
+This separation is intentional and permanent.
+
+---
+
+## When to modify this repo
+
+Only modify `@taleem/player` if:
+
+* a new slide semantic is introduced
+* an existing slide semantic is incorrect
+* tests reveal a broken interpretation rule
+
+If you are adding UI features — you are in the wrong repo.
+
+---
+
+## Final warning (read twice)
+
+> **A previous version of this system failed because UI logic leaked into the Player.
+> This repository exists to make that mistake impossible.**
+
+Treat this README as **law**, not guidance.
+
+---
+
+## Status
+
+✔ Boundaries enforced
+✔ Tests passing
+✔ Semantics stable
+✔ Ready for long-term use
+
+This is a **completed deliverable**.
+

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,67 @@
+{
+    "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": [
+          { "type": "heading",  "content": "Test All Sidebar Types",                "showAt": 5  },
+          { "type": "spHeading","content": "SP Heading"                                           },
+          { "type": "spText",   "content": "This is a sidebar comment."                           },
+          { "type": "spMath",   "content": "a^2 + b^2 = c^2"                                      },
+          { "type": "spImage",  "content": "/media/images/box.webp"                               },
+  
+          { "type": "math",     "content": "E = mc^2",                                            "showAt": 12 },
+          { "type": "spHeading","content": "Einstein's Law"                                                   },
+          { "type": "spText",   "content": "Energy–mass equivalence"                                          },
+          { "type": "spImage",  "content": "/media/images/box.webp"                                           },
+  
+          { "type": "math",     "content": "\\\\int_0^\\\\pi \\\\sin x \\\\,dx = 2",              "showAt": 20 },
+          { "type": "spHeading","content": "Integral Result"                                                  },
+          { "type": "spText",   "content": "Area under sine from 0 to π"                                      },
+          { "type": "spMath",   "content": "\\\\int_0^\\\\pi \\\\sin x \\\\,dx = 2"                            },
+  
+          { "type": "math",     "content": "\\\\sum_{n=1}^{\\\\infty} \\\\frac{1}{n^2} = \\\\frac{\\\\pi^2}{6}", "showAt": 28 },
+          { "type": "spHeading","content": "Basel Problem"                                                     },
+          { "type": "spText",   "content": "Euler's celebrated result"                                         },
+          { "type": "spImage",  "content": "/media/images/box.webp"                                            },
+  
+          { "type": "text",     "content": "Ohm’s Law",                                         "showAt": 36 },
+          { "type": "spMath",   "content": "V = I R"                                                          },
+          { "type": "spText",   "content": "Voltage = Current × Resistance"                                  },
+  
+          { "type": "math",     "content": "p = m v",                                          "showAt": 42 },
+          { "type": "spText",   "content": "Momentum = mass × velocity"                                     },
+  
+          { "type": "math",     "content": "KE = \\u00BD m v^2",                               "showAt": 46 },
+          { "type": "spText",   "content": "Kinetic energy formula"                                          },
+  
+          { "type": "math",     "content": "PE = m g h",                                      "showAt": 50 },
+          { "type": "spText",   "content": "Potential energy at height h"                                  },
+  
+          { "type": "text",     "content": "End of test. All sidebar types shown.",            "showAt": 54 },
+          { "type": "spText",   "content": "Thanks for testing EQ format!"                                   }
+        ]
+      }
+    ]
+  }
+