taleem-player 1.0.9 → 1.0.11

package/README.md

@@ -1,25 +1,29 @@
+
 # Taleem Player
 
 **Taleem Player** converts **Taleem JSON slide data** into **web-based presentations**.
 
 It renders the **same Taleem JSON** in multiple display modes using a single, stable rendering engine.
 
-> **Stable · deck-v1 frozen**  
-> The slide language, schema, and registry are complete.  
+> **Stable · deck-v1 frozen**
+> The slide language, schema, and registry are complete.
 > Internal improvements may continue without breaking public contracts.
 
 ---
-Demo & Documentation
-👉 https://bilza2023.github.io/taleem/
+
+## Demo & Documentation
+
+👉 [https://bilza2023.github.io/taleem/](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
- - No screenshots. No mock data.
- - What you see is the real engine running in the browser.
+* 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
@@ -27,8 +31,9 @@ The live demo shows:
 Taleem Player is a **presentation engine**, not a slide editor.
 
 It takes **validated Taleem decks** and turns them into:
-- index-based presentations
-- time-based presentations
+
+* index-based presentations
+* time-based presentations
 
 The system is **declarative**, **predictable**, and **CSS-driven**.
 
@@ -38,7 +43,7 @@ The system is **declarative**, **predictable**, and **CSS-driven**.
 
 ```bash
 npm install taleem-player
-````
+```
 
 ---
 
@@ -137,6 +142,87 @@ They never change slide meaning.
 
 ---
 
+## Validation & Authoring Utilities (offline)
+
+Taleem Player also exposes **optional authoring utilities** for **offline use**
+during deck creation, build steps, or publishing pipelines.
+
+These utilities are **not runtime concerns** and are intentionally kept
+separate from the player rendering path.
+
+```js
+import {
+  validateDeckV1,
+  validatePlayerDeckV1,
+  normalizeDeckForPlayerV1,
+} from "taleem-player/validation";
+```
+
+---
+
+### `validateDeckV1(deck)`
+
+Schema-level validation.
+
+* Ensures the deck conforms to **deck-v1**
+* Validates slide types and data shapes
+* Does **not** validate timing semantics
+
+Returns `{ ok, value }` or `{ ok: false, errors }`.
+
+---
+
+### `validatePlayerDeckV1(deck)`
+
+Player-level semantic validation.
+
+* Assumes schema validation has already passed
+* Enforces:
+
+  * slide start / end correctness
+  * strict slide sequencing
+  * `showAt` within slide bounds
+  * EQ slide timing rules
+* Does **not** mutate or fix data
+
+This validator answers:
+
+> “Can time safely move forward without ambiguity?”
+
+---
+
+### `normalizeDeckForPlayerV1(deck, options?)`
+
+Offline normalization utility.
+
+* Patches missing or invalid timing
+* Assigns deterministic mock timings
+* Ensures the deck is **safe for player playback**
+* Intended for build steps, CLIs, or publishing workflows
+
+This is **not validation** — it is a controlled fixer.
+
+---
+
+### Usage model
+
+**Static editors / CDN usage**
+
+* no validation
+* no fixing
+* UX hints only
+
+**Authoring / build / publish step**
+
+```
+normalize → validate → publish
+```
+
+These utilities are **explicit opt-in** and are never executed
+by the player runtime.
+
+---
+
 ## CSS
 
 ```js
@@ -186,7 +272,8 @@ The core registry supports **additive registration only**.
 
 The `eq` slide type is implemented and tested.
 
-It represents **structured symbolic content** and intentionally marks the **upper boundary** of the system.
+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.
 

package/dist/css/taleem.css

@@ -405,9 +405,9 @@
 /* ---------- Side panel items ---------- */
 
 .slide.eq.imageRightBulletsLeft .eq-explain-item {
-  font-size: 1.4rem;
-  line-height: 1.45;
-  text-align: center;
+  font-size: 1.6rem;
+  line-height: 1.75;
+  text-align:justify;
 
   word-wrap: break-word;
   overflow-wrap: break-word;
@@ -415,6 +415,8 @@
   background: rgba(255, 255, 255, 0.06);
   padding: 14px 18px;
   border-radius: 12px;
+
+  
 }
 
 /* ---------- Side panel image ---------- */

package/dist/spec/index.js

@@ -50,7 +50,9 @@ var goldenDeckV1 = {
       type: "imageSlide",
       start: 15,
       end: 20,
-      data: [{ name: "image", content: "image.png", showAt: 15 }]
+      data: [
+        { name: "image", content: "image.png", showAt: 15 }
+      ]
     },
     {
       type: "imageWithTitle",
@@ -121,7 +123,9 @@ var goldenDeckV1 = {
       type: "progressbar",
       start: 50,
       end: 55,
-      data: [{ name: "bar", label: "Lesson Coverage", value: 60, showAt: 50 }]
+      data: [
+        { name: "bar", label: "Lesson Coverage", value: 60, showAt: 50 }
+      ]
     },
     {
       type: "quoteSlide",
@@ -148,7 +152,12 @@ var goldenDeckV1 = {
       start: 65,
       end: 75,
       data: [
-        { name: "line", type: "heading", content: "Eq Slide - under construction", showAt: 65 },
+        {
+          name: "line",
+          type: "heading",
+          content: "Eq Slide - under construction",
+          showAt: 65
+        },
         {
           name: "line",
           type: "math",
@@ -156,7 +165,7 @@ var goldenDeckV1 = {
           showAt: 66,
           spItems: [
             { type: "spText", content: "The square means the bracket is multiplied by itself." },
-            { type: "spImage", content: "box.webp" }
+            { type: "spImage", content: "image.png" }
           ]
         },
         {
@@ -166,7 +175,7 @@ var goldenDeckV1 = {
           showAt: 67,
           spItems: [
             { type: "spText", content: "The square means the bracket is multiplied by itself." },
-            { type: "spImage", content: "image.webp" }
+            { type: "spImage", content: "image.png" }
           ]
         }
       ]
@@ -175,7 +184,9 @@ var goldenDeckV1 = {
       type: "fillImage",
       start: 75,
       end: 80,
-      data: [{ name: "image", content: "image.png", showAt: 75 }]
+      data: [
+        { name: "image", content: "image.png", showAt: 75 }
+      ]
     },
     {
       type: "titleAndPara",

package/dist/validation/index.js

@@ -13960,7 +13960,179 @@ function validateDeckV1(deck) {
   const r = zodDeckV1.safeParse(deck);
   return r.success ? { ok: true, value: r.data } : { ok: false, errors: r.error.issues };
 }
+
+// src/validation/validatePlayerDeckV1.js
+function validatePlayerDeckV1(deck) {
+  const errors = [];
+  if (!deck || !Array.isArray(deck.deck)) {
+    return fail("DECK_INVALID", "deck.deck must be an array");
+  }
+  const slides = deck.deck;
+  validateSlideTiming(slides, errors);
+  validateSlideSequence(slides, errors);
+  validateShowAtRanges(slides, errors);
+  validateEqSlides(slides, errors);
+  return errors.length === 0 ? { ok: true } : { ok: false, errors };
+}
+function validateSlideTiming(slides, errors) {
+  slides.forEach((slide, i) => {
+    if (typeof slide.start !== "number" || typeof slide.end !== "number") {
+      errors.push(err(
+        "SLIDE_TIME_MISSING",
+        `Slide ${i} must have numeric start/end`
+      ));
+      return;
+    }
+    if (slide.start >= slide.end) {
+      errors.push(err(
+        "SLIDE_TIME_ORDER",
+        `Slide ${i} start (${slide.start}) must be < end (${slide.end})`
+      ));
+    }
+    if (i === 0 && slide.start !== 0) {
+      errors.push(err(
+        "DECK_START_NOT_ZERO",
+        `First slide must start at 0 (got ${slide.start})`
+      ));
+    }
+  });
+}
+function validateSlideSequence(slides, errors) {
+  for (let i = 0; i < slides.length - 1; i++) {
+    const a = slides[i];
+    const b = slides[i + 1];
+    if (a.end !== b.start) {
+      errors.push(err(
+        "SLIDE_SEQUENCE_BREAK",
+        `Slide ${i} ends at ${a.end} but next starts at ${b.start}`
+      ));
+    }
+    if (b.start < a.start) {
+      errors.push(err(
+        "SLIDE_TIME_REVERSE",
+        `Slide ${i + 1} starts before previous slide`
+      ));
+    }
+  }
+}
+function validateShowAtRanges(slides, errors) {
+  slides.forEach((slide, si) => {
+    let lastShowAt = null;
+    if (!Array.isArray(slide.data)) return;
+    slide.data.forEach((item, di) => {
+      if (typeof item.showAt !== "number") return;
+      if (item.showAt < slide.start || item.showAt >= slide.end) {
+        errors.push(err(
+          "SHOWAT_OUT_OF_RANGE",
+          `Slide ${si} item ${di} showAt ${item.showAt} outside [${slide.start}, ${slide.end})`
+        ));
+      }
+      if (lastShowAt !== null && item.showAt < lastShowAt) {
+        errors.push(err(
+          "SHOWAT_ORDER",
+          `Slide ${si} item ${di} showAt decreases (${item.showAt} < ${lastShowAt})`
+        ));
+      }
+      lastShowAt = item.showAt;
+    });
+  });
+}
+function validateEqSlides(slides, errors) {
+  slides.forEach((slide, si) => {
+    if (slide.type !== "eq") return;
+    let lastLineShowAt = null;
+    slide.data.forEach((line, li) => {
+      if (typeof line.showAt === "number") {
+        if (line.showAt < slide.start || line.showAt >= slide.end) {
+          errors.push(err(
+            "EQ_LINE_SHOWAT_RANGE",
+            `EQ slide ${si} line ${li} showAt ${line.showAt} outside slide range`
+          ));
+        }
+        if (lastLineShowAt !== null && line.showAt < lastLineShowAt) {
+          errors.push(err(
+            "EQ_LINE_ORDER",
+            `EQ slide ${si} line ${li} showAt decreases`
+          ));
+        }
+        lastLineShowAt = line.showAt;
+      }
+      if (Array.isArray(line.spItems)) {
+        line.spItems.forEach((sp, spi) => {
+          if ("showAt" in sp) {
+            errors.push(err(
+              "EQ_SPITEM_SHOWAT_FORBIDDEN",
+              `EQ slide ${si} line ${li} spItem ${spi} must not define showAt`
+            ));
+          }
+        });
+      }
+    });
+  });
+}
+function err(code, message) {
+  return { code, message };
+}
+function fail(code, message) {
+  return { ok: false, errors: [{ code, message }] };
+}
+
+// src/validation/normalizeDeckForPlayerV1.js
+function normalizeDeckForPlayerV1(deck, opts = {}) {
+  const {
+    slideDuration = 5,
+    // default seconds per slide
+    itemStep = 1
+    // default gap between showAt items
+  } = opts;
+  let time3 = 0;
+  const slides = deck.deck.map((slide) => {
+    const start = isNumber(slide.start) ? slide.start : time3;
+    const end = isNumber(slide.end) && slide.end > start ? slide.end : start + slideDuration;
+    const fixedSlide = {
+      ...slide,
+      start,
+      end,
+      data: fixShowAt(slide.data, start, end, itemStep)
+    };
+    time3 = end;
+    return fixedSlide;
+  });
+  return {
+    ...deck,
+    deck: slides
+  };
+}
+function fixShowAt(data, start, end, step) {
+  if (!Array.isArray(data)) return data;
+  let t = start;
+  return data.map((item) => {
+    const showAt2 = isNumber(item.showAt) ? clamp(item.showAt, start, end - 1e-4) : t;
+    t = showAt2 + step;
+    if (item.name === "line" && Array.isArray(item.spItems)) {
+      return {
+        ...item,
+        showAt: showAt2,
+        spItems: item.spItems.map((sp) => stripShowAt(sp))
+      };
+    }
+    return { ...item, showAt: showAt2 };
+  });
+}
+function stripShowAt(obj) {
+  if (!obj || typeof obj !== "object") return obj;
+  const { showAt: showAt2, ...rest } = obj;
+  return rest;
+}
+function clamp(v, min, max) {
+  return Math.min(Math.max(v, min), max);
+}
+function isNumber(v) {
+  return typeof v === "number" && !Number.isNaN(v);
+}
 export {
+  normalizeDeckForPlayerV1,
   validateDeckV1,
+  validatePlayerDeckV1,
   zodDeckV1
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "taleem-player",
-  "version": "1.0.9",
+  "version": "1.0.11",
   "type": "module",
   "main": "./dist/taleem-player.umd.js",
   "module": "./dist/taleem-player.esm.js",