mr-md 1.0.0

package/README.md

@@ -0,0 +1,24 @@
+# Mr Markdown
+
+Mr Markdown is an opinionated TypeScript SDK for building interactive, single-file learning pages. It is designed for lessons that mix prose, LaTeX, simulations, media, video, and quizzes without making every author build layout and interaction chrome from scratch.
+
+## Documentation
+
+The documentation has been split into dedicated guides. Start with the Quick Start, and then explore the core features:
+
+1. [Quick Start](./docs/quickstart.md) - Learn how to build your first lesson.
+2. [Core Blocks](./docs/core-blocks.md) - An overview of the API and layout components (markdown, math, media, callouts).
+3. [Simulations & Interactivity](./docs/simulations.md) - The definitive guide for building and integrating sandboxed JavaScript simulations, including zero-config companion files.
+4. [Themes and Styling](./docs/themes-and-styling.md) - Learn how to customize fonts, colors, and hook into Dark Mode.
+5. [Quizzes](./docs/quizzes.md) - Learn the JSON format for injecting interactive quizzes.
+6. [Production Checks](./docs/production-checks.md) - Understand Mr Markdown's strict mode and quality enforcement.
+
+## Example
+
+To see a full example in action, compile the included `charge.lesson.ts`:
+
+```bash
+npx ts-node example/charge.lesson.ts
+# or 
+bun example/charge.lesson.ts
+```

package/dist/builder.d.ts

@@ -0,0 +1,169 @@
+import type { AnimationOptions, BuildOptions, CalloutBlock, Chapter, ColumnItem, ColumnsOptions, LatexOptions, Lesson, LessonMeta, MediaOptions, QuizBlock, SimulationOptions, YouTubeOptions } from "./types.js";
+export declare class LessonBuilder {
+    private meta;
+    private blocks;
+    private options;
+    private _rawOptions;
+    constructor(title: string, options?: BuildOptions);
+    /**
+     * Sets the URL slug for the generated HTML file.
+     * Automatically generated from the title by default.
+     */
+    slug(slug: string): this;
+    /**
+     * Sets the SEO meta description and subheading for the lesson.
+     */
+    description(text: string): this;
+    /** Assigns taxonomy tags to the lesson. */
+    tags(...tags: string[]): this;
+    /** Sets the author name for this lesson. */
+    author(name: string): this;
+    /**
+     * Sets the progression status of the lesson.
+     * Used to visually distinguish read/unread/locked lessons in Chapter timelines.
+     */
+    status(status: "read" | "unread" | "locked"): this;
+    /** Curated production defaults for the generated lesson shell. */
+    preset(preset: NonNullable<BuildOptions["preset"]>): this;
+    /** @internal Used by ChapterBuilder to push down shared config */
+    _inheritOptions(parentOpts: BuildOptions): void;
+    /** @internal Used by ChapterBuilder */
+    _setParentSlug(slug: string): void;
+    /** @internal Used by ChapterBuilder */
+    _setPrev(slug: string, title: string): void;
+    /** @internal Used by ChapterBuilder */
+    _setNext(slug: string, title: string): void;
+    /** @internal Used by ChapterBuilder */
+    _getMeta(): LessonMeta;
+    /**
+     * Smart helper that automatically infers the correct block type from the file extension or URL.
+     * Allows authors to quickly sequence a lesson without memorizing specific block methods.
+     */
+    add(src: `${string}.md` | `${string}.mdx`): this;
+    add(src: `${string}.json`, opts?: Pick<QuizBlock, "label" | "caption">): this;
+    add(src: `${string}.mp4` | `${string}.webm` | `${string}.mov`, opts?: Omit<MediaOptions, "kind">): this;
+    add(src: `${string}.mp3` | `${string}.wav` | `${string}.ogg` | `${string}.m4a`, opts?: Omit<MediaOptions, "kind">): this;
+    add(src: `${string}.png` | `${string}.jpg` | `${string}.jpeg` | `${string}.gif` | `${string}.svg` | `${string}.webp` | `${string}.avif`, opts?: Omit<MediaOptions, "kind">): this;
+    add(src: string, opts?: any): this;
+    /**
+     * Creates a major chapter heading (H2) and a top-level sidebar navigation entry.
+     * @param src Path to a markdown file or raw markdown string.
+     * @param title Optional title override for the sidebar and heading.
+     * @example lesson.heading("# Welcome to Physics")
+     */
+    heading(src: string, title?: string): this;
+    /**
+     * Adds standard markdown prose into the current section.
+     * @param src Path to a markdown file or raw markdown string.
+     * @example lesson.markdown("This is a **bold** statement.")
+     */
+    markdown(src: string): this;
+    /**
+     * Alias for `markdown()`. Keeps authoring readable in long lessons.
+     * @example lesson.content("content/intro.md")
+     */
+    content(src: string): this;
+    /**
+     * Creates a new subsection heading (H3) and a sub-entry in the sidebar.
+     * @param src Path to a markdown file or raw markdown string.
+     * @param label Optional title override for the sidebar label.
+     * @example lesson.section("### 1. Kinematics")
+     */
+    section(src: string, label?: string): this;
+    /**
+     * Adds an 'Important' highlighted callout.
+     * @example lesson.important("Do not touch the exposed wire.")
+     */
+    important(src: string): this;
+    /**
+     * Adds a 'Warning' highlighted callout.
+     * @example lesson.warning("This is deprecated.")
+     */
+    warning(src: string): this;
+    /**
+     * Adds a 'Tip' highlighted callout.
+     */
+    tip(src: string): this;
+    /**
+     * Adds a 'Note' highlighted callout.
+     */
+    note(src: string): this;
+    callout(type: CalloutBlock["type"], src: string): this;
+    /**
+     * Adds a syntax-highlighted code block.
+     * @param src Path to a code file or raw code string.
+     * @param lang Explicit language for highlighting (e.g. "ts", "python").
+     * @param label Optional file name or label to display above the code block.
+     */
+    code(src: string, lang?: string, label?: string): this;
+    latex(tex: string, opts?: LatexOptions): this;
+    columns(columns: ColumnItem[], opts?: ColumnsOptions): this;
+    private loadSimulationConfig;
+    /**
+     * Mounts a sandboxed JavaScript simulation or interactive applet.
+     * @param src Path to the JavaScript simulation code.
+     * @param opts Configuration options including tunables, height, and aspect ratio.
+     * @param height Optional fixed iframe height in pixels.
+     * @example lesson.simulation("sims/pendulum.js", { height: 500 })
+     */
+    simulation(src: string, opts?: SimulationOptions | Record<string, unknown>, height?: number): this;
+    /**
+     * Opinionated alias for `simulation()`, configured specifically for interactive physics/math labs.
+     * Sets the default interaction mode to fully interactive.
+     * @param src Path to the JavaScript simulation code.
+     * @param opts Configuration options.
+     * @example lesson.lab("sims/optics-lab.js")
+     */
+    lab(src: string, opts?: SimulationOptions): this;
+    /** Passive animation player */
+    animation(src: string, opts?: AnimationOptions): this;
+    media(src: string, opts?: MediaOptions): this;
+    image(src: string, opts?: Omit<MediaOptions, "kind">): this;
+    video(src: string, opts?: Omit<MediaOptions, "kind">): this;
+    youtube(idOrUrl: string, opts?: YouTubeOptions): this;
+    audio(src: string, opts?: Omit<MediaOptions, "kind">): this;
+    /**
+     * Injects an interactive multiple-choice quiz block.
+     * @param src Path to a .json file conforming to the `QuizFile` schema.
+     * @param opts Optional label and caption for the quiz block wrapper.
+     */
+    quiz(src: string, opts?: Pick<QuizBlock, "label" | "caption">): this;
+    /** Visual separator */
+    divider(): this;
+    /** Returns the raw Lesson object (useful for testing or custom rendering) */
+    toJSON(): Lesson;
+    /** Compiles everything and writes a single .html file to outDir */
+    build(): string;
+}
+/**
+ * Starts building a new interactive lesson.
+ * @param title The display title for the lesson.
+ * @param options Build configuration for this specific lesson.
+ * @example const l = lesson("Introduction to Kinematics").markdown("intro.md");
+ */
+export declare function lesson(title: string, options?: BuildOptions): LessonBuilder;
+export declare class ChapterBuilder {
+    private meta;
+    private lessonBuilders;
+    private options;
+    constructor(title: string, options?: BuildOptions);
+    slug(slug: string): this;
+    description(text: string): this;
+    status(status: "completed" | "active" | "locked"): this;
+    lesson(lessonBuilder: LessonBuilder): this;
+    build(): string;
+    /** Returns the raw Chapter object */
+    toJSON(): Chapter;
+}
+/**
+ * Starts building a new chapter that groups multiple lessons together.
+ * @param title The display title for the chapter.
+ * @param options Shared build configuration that cascades to all child lessons.
+ * @example
+ * chapter("Mechanics")
+ *   .lesson(kinematicsLesson)
+ *   .lesson(dynamicsLesson)
+ *   .build();
+ */
+export declare function chapter(title: string, options?: BuildOptions): ChapterBuilder;
+//# sourceMappingURL=builder.d.ts.map

package/dist/builder.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"builder.d.ts","sourceRoot":"","sources":["../src/builder.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAEX,gBAAgB,EAEhB,YAAY,EACZ,YAAY,EACZ,OAAO,EAGP,UAAU,EAEV,cAAc,EAId,YAAY,EACZ,MAAM,EACN,UAAU,EAGV,YAAY,EACZ,SAAS,EAIT,iBAAiB,EAEjB,cAAc,EACd,MAAM,YAAY,CAAC;AAIpB,qBAAa,aAAa;IACzB,OAAO,CAAC,IAAI,CAAa;IACzB,OAAO,CAAC,MAAM,CAAe;IAC7B,OAAO,CAAC,OAAO,CAAe;IAC9B,OAAO,CAAC,WAAW,CAAe;gBAEtB,KAAK,EAAE,MAAM,EAAE,OAAO,GAAE,YAAiB;IA2BrD;;;OAGG;IACH,IAAI,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI;IAKxB;;OAEG;IACH,WAAW,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI;IAK/B,2CAA2C;IAC3C,IAAI,CAAC,GAAG,IAAI,EAAE,MAAM,EAAE,GAAG,IAAI;IAK7B,4CAA4C;IAC5C,MAAM,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI;IAK1B;;;OAGG;IACH,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,QAAQ,GAAG,QAAQ,GAAG,IAAI;IAKlD,kEAAkE;IAClE,MAAM,CAAC,MAAM,EAAE,WAAW,CAAC,YAAY,CAAC,QAAQ,CAAC,CAAC,GAAG,IAAI;IASzD,kEAAkE;IAClE,eAAe,CAAC,UAAU,EAAE,YAAY;IAqBxC,uCAAuC;IACvC,cAAc,CAAC,IAAI,EAAE,MAAM;IAI3B,uCAAuC;IACvC,QAAQ,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM;IAKpC,uCAAuC;IACvC,QAAQ,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM;IAKpC,uCAAuC;IACvC,QAAQ,IAAI,UAAU;IAMtB;;;OAGG;IACH,GAAG,CAAC,GAAG,EAAE,GAAG,MAAM,KAAK,GAAG,GAAG,MAAM,MAAM,GAAG,IAAI;IAChD,GAAG,CAAC,GAAG,EAAE,GAAG,MAAM,OAAO,EAAE,IAAI,CAAC,EAAE,IAAI,CAAC,SAAS,EAAE,OAAO,GAAG,SAAS,CAAC,GAAG,IAAI;IAC7E,GAAG,CACF,GAAG,EAAE,GAAG,MAAM,MAAM,GAAG,GAAG,MAAM,OAAO,GAAG,GAAG,MAAM,MAAM,EACzD,IAAI,CAAC,EAAE,IAAI,CAAC,YAAY,EAAE,MAAM,CAAC,GAC/B,IAAI;IACP,GAAG,CACF,GAAG,EAAE,GAAG,MAAM,MAAM,GAAG,GAAG,MAAM,MAAM,GAAG,GAAG,MAAM,MAAM,GAAG,GAAG,MAAM,MAAM,EAC1E,IAAI,CAAC,EAAE,IAAI,CAAC,YAAY,EAAE,MAAM,CAAC,GAC/B,IAAI;IACP,GAAG,CACF,GAAG,EACA,GAAG,MAAM,MAAM,GACf,GAAG,MAAM,MAAM,GACf,GAAG,MAAM,OAAO,GAChB,GAAG,MAAM,MAAM,GACf,GAAG,MAAM,MAAM,GACf,GAAG,MAAM,OAAO,GAChB,GAAG,MAAM,OAAO,EACnB,IAAI,CAAC,EAAE,IAAI,CAAC,YAAY,EAAE,MAAM,CAAC,GAC/B,IAAI;IAEP,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,GAAG,GAAG,IAAI;IA2BlC;;;;;OAKG;IACH,OAAO,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,MAAM,GAAG,IAAI;IAK1C;;;;OAIG;IACH,QAAQ,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI;IAK3B;;;OAGG;IACH,OAAO,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI;IAI1B;;;;;OAKG;IACH,OAAO,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,MAAM,GAAG,IAAI;IAK1C;;;OAGG;IACH,SAAS,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI;IAK5B;;;OAGG;IACH,OAAO,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI;IAK1B;;OAEG;IACH,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI;IAKtB;;OAEG;IACH,IAAI,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI;IAKvB,OAAO,CAAC,IAAI,EAAE,YAAY,CAAC,MAAM,CAAC,EAAE,GAAG,EAAE,MAAM,GAAG,IAAI;IAKtD;;;;;OAKG;IACH,IAAI,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,MAAM,GAAG,IAAI;IAKtD,KAAK,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,GAAE,YAAiB,GAAG,IAAI;IAWjD,OAAO,CAAC,OAAO,EAAE,UAAU,EAAE,EAAE,IAAI,GAAE,cAAmB,GAAG,IAAI;IAO/D,OAAO,CAAC,oBAAoB;IAe5B;;;;;;OAMG;IACH,UAAU,CACT,GAAG,EAAE,MAAM,EACX,IAAI,GAAE,iBAAiB,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAM,EACtD,MAAM,SAAM,GACV,IAAI;IAYP;;;;;;OAMG;IACH,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,GAAE,iBAAsB,GAAG,IAAI;IAIpD,+BAA+B;IAC/B,SAAS,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,GAAE,gBAAqB,GAAG,IAAI;IAazD,KAAK,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,GAAE,YAAiB,GAAG,IAAI;IAejD,KAAK,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,GAAE,IAAI,CAAC,YAAY,EAAE,MAAM,CAAM,GAAG,IAAI;IAI/D,KAAK,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,GAAE,IAAI,CAAC,YAAY,EAAE,MAAM,CAAM,GAAG,IAAI;IAI/D,OAAO,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,GAAE,cAAmB,GAAG,IAAI;IAWzD,KAAK,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,GAAE,IAAI,CAAC,YAAY,EAAE,MAAM,CAAM,GAAG,IAAI;IAI/D;;;;OAIG;IACH,IAAI,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,GAAE,IAAI,CAAC,SAAS,EAAE,OAAO,GAAG,SAAS,CAAM,GAAG,IAAI;IAKxE,uBAAuB;IACvB,OAAO,IAAI,IAAI;IAOf,6EAA6E;IAC7E,MAAM,IAAI,MAAM;IAKhB,mEAAmE;IACnE,KAAK,IAAI,MAAM;CAef;AAID;;;;;GAKG;AACH,wBAAgB,MAAM,CACrB,KAAK,EAAE,MAAM,EACb,OAAO,GAAE,YAAiB,GACxB,aAAa,CAEf;AAiHD,qBAAa,cAAc;IAC1B,OAAO,CAAC,IAAI,CAAc;IAC1B,OAAO,CAAC,cAAc,CAAuB;IAC7C,OAAO,CAAC,OAAO,CAAe;gBAElB,KAAK,EAAE,MAAM,EAAE,OAAO,GAAE,YAAiB;IAwBrD,IAAI,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI;IAKxB,WAAW,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI;IAK/B,MAAM,CAAC,MAAM,EAAE,WAAW,GAAG,QAAQ,GAAG,QAAQ,GAAG,IAAI;IAKvD,MAAM,CAAC,aAAa,EAAE,aAAa,GAAG,IAAI;IAO1C,KAAK,IAAI,MAAM;IAuCf,qCAAqC;IACrC,MAAM,IAAI,OAAO;CAOjB;AAED;;;;;;;;;GASG;AACH,wBAAgB,OAAO,CACtB,KAAK,EAAE,MAAM,EACb,OAAO,GAAE,YAAiB,GACxB,cAAc,CAEhB"}