taleem-builder

Status: Stable
Audience: Presentation creators · Teachers · Students · Content teams
Output: Canonical deck-v1 JSON

taleem-builder is part of the Taleem ecosystem.

It is the authoring workspace where slide decks are created.

This is where decks are born.

What is taleem-builder?

taleem-builder is an authoring tool for creating Taleem slide decks using a simple, readable JavaScript format.

Instead of writing fragile JSON by hand, you describe your slides step-by-step using a builder API, and the builder produces correct, validated deck-v1 JSON that works everywhere in Taleem.

This is the layer where:

• lessons are written
• presentations are structured
• decks are generated (by humans or AI)

Who is this for?

taleem-builder is for:

• Teachers preparing lessons
• Students creating structured explanations
• Presentation creators who want clarity and consistency
• Content teams building large slide libraries
• AI systems generating decks automatically
• Developers and pipelines (secondary)

If your goal is to create slides, this is the right package.

Why not write JSON directly?

Because JSON is an output format — not a workspace.

taleem-builder is better than writing JSON by hand because:

1. JSON is fragile
   One missing comma or field breaks everything.
   JavaScript structure is safer and clearer.

2. The builder enforces rules

   • slide order
   • timing consistency
   • slide validity
   • (mobile mode restrictions — expanding over time)

3. The builder prevents small mistakes
   Many subtle errors are caught automatically instead of failing later in a player.

4. The format is AI-native
   Humans and AI can generate the same builder code.
   (Including future Taleem-provided GPTs 👀)

JSON is what you export.
Builder code is what you author.

How it fits in the Taleem system

Authoring (you / AI)
↓
taleem-builder   ← this package
↓
Canonical JSON (deck-v1)
↓
taleem-player / browser / renderers

• taleem-core defines the slide language
• taleem-builder creates decks in that language
• players decide how decks are shown

The builder always follows the core schema — never the other way around.

Golden builder example

This repository includes a golden builder deck:

src/samples/golden-builder-deck.js

This file:

• uses all 21 canonical slide types
• mirrors the golden JSON deck exactly
• is tested for lossless equivalence

It is the reference example for how to author decks correctly.

If this file builds, the builder is correct.

Documentation & examples

• Builder API (copy-paste ready): docs/api.md
• Golden authoring example: src/samples/golden-builder-deck.js
• Slide language & schema: see taleem-core / taleem-player docs

What this package does NOT do

taleem-builder does not:

• render slides
• play slides
• animate content
• manage UI, browser state, or audio

If something appears on screen, it belongs in a player — not here.

Stability promise

• The builder API evolves with deck-v1
• No breaking changes inside a deck version
• Future changes will arrive only with deck-v2

Existing decks must always continue to build.