manim-web 0.24.0 → 0.26.0

package/dist/export/SlideDeckExporter.d.ts

@@ -0,0 +1,210 @@
+/**
+ * SlideDeckExporter - export an interactive manim-web slide deck to a static
+ * document: one still image per slide, assembled into a PDF (or PPTX).
+ *
+ * Interactive slides play to video/GIF/SVG/PNG, but educators often want a flat
+ * handout: a PDF where each slide is one page. This exporter walks the player's
+ * slides (built by `MasterTimeline.finalizeSlides()`), seeks the scene to each
+ * slide's representative frame, captures it as a raster image, and places one
+ * image per page.
+ *
+ * The heavy document libraries are not bundled. `jspdf` is lazy-loaded through a
+ * dynamic `import()` only when the caller uses the default PDF factory, so the
+ * base bundle stays light. `pptxgenjs` is fully optional: PPTX works when the
+ * caller passes `pptxFactory`, or installs `pptxgenjs` so the default optional
+ * import resolves.
+ *
+ * Every external dependency is a dependency-injection seam (`pdfFactory`,
+ * `pptxFactory`, `captureSlide`), so tests run with lightweight stubs and need
+ * neither the real libraries, a GPU, nor a DOM.
+ */
+/**
+ * A slide's time span on the timeline. Matches the `Slide` interface produced
+ * by `MasterTimeline.getSlides()` (only the two fields this exporter reads).
+ */
+export interface SlideBounds {
+    /** Slide start time in seconds (first frame). */
+    readonly startTime: number;
+    /** Slide end time in seconds (last frame). */
+    readonly endTime: number;
+}
+/**
+ * Duck-typed scene the default capturer needs: seek to a time, read the canvas,
+ * and report the pixel size. `Scene` matches this structurally.
+ */
+export interface SlideCaptureScene {
+    seek(time: number): void;
+    getCanvas(): HTMLCanvasElement;
+    getWidth(): number;
+    getHeight(): number;
+}
+/**
+ * Duck-typed source of slides plus the scene to capture. A `Player` matches
+ * this: `player.timeline.getSlides()` and `player.scene`.
+ */
+export interface SlideDeckSource {
+    /** The timeline that exposes the finalized slide list. */
+    readonly timeline: {
+        getSlides(): readonly SlideBounds[];
+    };
+    /** The scene the capturer seeks and reads. */
+    readonly scene: SlideCaptureScene;
+}
+/** One captured slide still: an image data URL and its pixel dimensions. */
+export interface CapturedSlide {
+    /** Image data URL (for example a PNG `data:` URL) ready for `addImage`. */
+    dataUrl: string;
+    /** Captured image width in pixels. */
+    width: number;
+    /** Captured image height in pixels. */
+    height: number;
+}
+/**
+ * Per-slide frame capturer. Seeks the scene to `time` and returns the still.
+ * Injectable so tests avoid a GPU and a DOM.
+ */
+export type SlideCapturer = (scene: SlideCaptureScene, time: number) => CapturedSlide | Promise<CapturedSlide>;
+/** jsPDF measurement unit for page size. */
+export type PdfUnit = 'pt' | 'mm' | 'cm' | 'in' | 'px';
+/** Page orientation. */
+export type PdfOrientation = 'landscape' | 'portrait';
+/** jsPDF page format: a named size (`a4`, `letter`) or `[width, height]`. */
+export type PdfPageFormat = string | [number, number];
+/** Options the PDF factory receives, matching the jsPDF constructor options. */
+export interface PdfInitOptions {
+    orientation: PdfOrientation;
+    unit: PdfUnit;
+    format: PdfPageFormat;
+}
+/**
+ * Minimal jsPDF document surface this exporter uses. A real `jsPDF` instance
+ * satisfies it; tests pass a recording stub.
+ */
+export interface PdfDocument {
+    addPage(format?: PdfPageFormat, orientation?: PdfOrientation): PdfDocument;
+    addImage(data: string, format: string, x: number, y: number, w: number, h: number): PdfDocument;
+    setFillColor(r: number, g: number, b: number): PdfDocument;
+    rect(x: number, y: number, w: number, h: number, style?: string): PdfDocument;
+    output(type: 'blob'): Blob;
+    save(filename: string): void;
+    internal: {
+        pageSize: {
+            getWidth(): number;
+            getHeight(): number;
+        };
+    };
+}
+/** Builds a PDF document. Injectable; the default lazy-imports `jspdf`. */
+export type PdfFactory = (options: PdfInitOptions) => PdfDocument | Promise<PdfDocument>;
+/** Options for {@link exportSlidesToPDF}. */
+export interface SlidePdfExportOptions {
+    /** Which still of each slide to capture: 'first' or 'last' frame. Default 'last'. */
+    still?: 'first' | 'last';
+    /** Page orientation. Default 'landscape' (slides are usually wide). */
+    orientation?: PdfOrientation;
+    /** Page size: a jsPDF format name or `[width, height]` in `unit`. Default 'a4'. */
+    pageSize?: PdfPageFormat;
+    /** Measurement unit for the page size. Default 'pt'. */
+    unit?: PdfUnit;
+    /** Page background fill as `[r, g, b]` (0-255). Omit for no fill (white page). */
+    background?: [number, number, number];
+    /** Image format passed to `addImage`. Default 'PNG'. */
+    imageFormat?: string;
+    /** DI: PDF document factory. Default lazy-imports `jspdf`. */
+    pdfFactory?: PdfFactory;
+    /** DI: per-slide frame capturer. Default seeks and reads `canvas.toDataURL`. */
+    captureSlide?: SlideCapturer;
+    /** Progress callback in `[0, 1]`. */
+    onProgress?: (progress: number) => void;
+}
+/**
+ * Export a slide deck to a PDF, one page per slide.
+ *
+ * For each slide the scene seeks to the chosen still (first or last frame), the
+ * frame is captured, and the image is placed centered on its own page. An empty
+ * deck produces no document and resolves to `null`.
+ *
+ * @param source - The slide source (a `Player` works directly)
+ * @param options - Export options
+ * @returns A Promise that resolves to the PDF Blob, or `null` for an empty deck
+ */
+export declare function exportSlidesToPDF(source: SlideDeckSource, options?: SlidePdfExportOptions): Promise<Blob | null>;
+/**
+ * Export a slide deck to a PDF and download it in the browser.
+ *
+ * Degrades without throwing: when no `document` is available (worker, headless,
+ * SSR) it logs a warning and returns. An empty deck is a no-op (no download).
+ *
+ * @param source - The slide source (a `Player` works directly)
+ * @param filename - The download filename. Defaults to 'slides.pdf'.
+ * @param options - Export options
+ */
+export declare function exportAndDownloadSlidesToPDF(source: SlideDeckSource, filename?: string, options?: SlidePdfExportOptions): Promise<void>;
+/** Options a slide's `addImage` accepts (a subset of pptxgenjs). */
+export interface PptxImageOptions {
+    data: string;
+    x: number;
+    y: number;
+    w: number;
+    h: number;
+    sizing?: {
+        type: 'contain' | 'cover' | 'crop';
+        w: number;
+        h: number;
+    };
+}
+/** Minimal pptxgenjs slide surface this exporter uses. */
+export interface PptxSlide {
+    addImage(options: PptxImageOptions): void;
+    background?: {
+        color: string;
+    };
+}
+/** Minimal pptxgenjs presentation surface this exporter uses. */
+export interface PptxDocument {
+    addSlide(): PptxSlide;
+    write(options: {
+        outputType: 'blob';
+    }): Blob | Promise<Blob>;
+    writeFile(options: {
+        fileName: string;
+    }): void | Promise<string>;
+    defineLayout?(options: {
+        name: string;
+        width: number;
+        height: number;
+    }): void;
+    layout?: string;
+}
+/** Builds a PPTX presentation. Injectable; the default optionally imports `pptxgenjs`. */
+export type PptxFactory = () => PptxDocument | Promise<PptxDocument>;
+/** Options for {@link exportSlidesToPPTX}. */
+export interface SlidePptxExportOptions {
+    /** Which still of each slide to capture: 'first' or 'last' frame. Default 'last'. */
+    still?: 'first' | 'last';
+    /** Slide width in inches. Default 13.333 (16:9 wide). */
+    slideWidth?: number;
+    /** Slide height in inches. Default 7.5 (16:9 wide). */
+    slideHeight?: number;
+    /** Slide background color as a hex string (no leading '#'), for example 'FFFFFF'. */
+    background?: string;
+    /** DI: presentation factory. Default optionally imports `pptxgenjs`. */
+    pptxFactory?: PptxFactory;
+    /** DI: per-slide frame capturer. Default seeks and reads `canvas.toDataURL`. */
+    captureSlide?: SlideCapturer;
+    /** Progress callback in `[0, 1]`. */
+    onProgress?: (progress: number) => void;
+}
+/**
+ * Export a slide deck to a PPTX presentation, one slide per deck slide.
+ *
+ * PPTX support is optional: pass `pptxFactory`, or install `pptxgenjs` so the
+ * default optional import resolves. Each captured still is placed to fit the
+ * slide, preserving aspect. An empty deck resolves to `null`.
+ *
+ * @param source - The slide source (a `Player` works directly)
+ * @param options - Export options
+ * @returns A Promise that resolves to the PPTX Blob, or `null` for an empty deck
+ */
+export declare function exportSlidesToPPTX(source: SlideDeckSource, options?: SlidePptxExportOptions): Promise<Blob | null>;
+//# sourceMappingURL=SlideDeckExporter.d.ts.map

package/dist/export/SlideDeckExporter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"SlideDeckExporter.d.ts","sourceRoot":"","sources":["../../src/export/SlideDeckExporter.ts"],"names":[],"mappings":"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"}

package/dist/export/index.d.ts

@@ -4,4 +4,5 @@ export { exportFramePNG, exportPNGSequence, downloadBlob, exportAndDownloadPNG,
 export { WebCodecsExporter, createWebCodecsExporter, type WebCodecsExportOptions, type WebCodecsVideoCodec, } from './WebCodecsExporter';
 export { chooseVideoExporterStrategy, type VideoExporterStrategy } from './chooseExporter';
 export { sceneToSVG, exportSVG, exportAndDownloadSVG, type SvgExportOptions, type SvgExportableScene, type SvgExportableCamera, } from './SvgExporter';
+export { exportSlidesToPDF, exportAndDownloadSlidesToPDF, exportSlidesToPPTX, type SlideBounds, type SlideCaptureScene, type SlideDeckSource, type CapturedSlide, type SlideCapturer, type PdfUnit, type PdfOrientation, type PdfPageFormat, type PdfInitOptions, type PdfDocument, type PdfFactory, type SlidePdfExportOptions, type PptxImageOptions, type PptxSlide, type PptxDocument, type PptxFactory, type SlidePptxExportOptions, } from './SlideDeckExporter';
 //# sourceMappingURL=index.d.ts.map

package/dist/export/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/export/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,iBAAiB,EAAE,KAAK,gBAAgB,EAAE,MAAM,eAAe,CAAC;AACtF,OAAO,EAAE,aAAa,EAAE,mBAAmB,EAAE,KAAK,kBAAkB,EAAE,MAAM,iBAAiB,CAAC;AAG9F,OAAO,EACL,cAAc,EACd,iBAAiB,EACjB,YAAY,EACZ,oBAAoB,EACpB,KAAK,kBAAkB,EACvB,KAAK,kBAAkB,GACxB,MAAM,iBAAiB,CAAC;AACzB,OAAO,EACL,iBAAiB,EACjB,uBAAuB,EACvB,KAAK,sBAAsB,EAC3B,KAAK,mBAAmB,GACzB,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EAAE,2BAA2B,EAAE,KAAK,qBAAqB,EAAE,MAAM,kBAAkB,CAAC;AAC3F,OAAO,EACL,UAAU,EACV,SAAS,EACT,oBAAoB,EACpB,KAAK,gBAAgB,EACrB,KAAK,kBAAkB,EACvB,KAAK,mBAAmB,GACzB,MAAM,eAAe,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/export/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,iBAAiB,EAAE,KAAK,gBAAgB,EAAE,MAAM,eAAe,CAAC;AACtF,OAAO,EAAE,aAAa,EAAE,mBAAmB,EAAE,KAAK,kBAAkB,EAAE,MAAM,iBAAiB,CAAC;AAG9F,OAAO,EACL,cAAc,EACd,iBAAiB,EACjB,YAAY,EACZ,oBAAoB,EACpB,KAAK,kBAAkB,EACvB,KAAK,kBAAkB,GACxB,MAAM,iBAAiB,CAAC;AACzB,OAAO,EACL,iBAAiB,EACjB,uBAAuB,EACvB,KAAK,sBAAsB,EAC3B,KAAK,mBAAmB,GACzB,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EAAE,2BAA2B,EAAE,KAAK,qBAAqB,EAAE,MAAM,kBAAkB,CAAC;AAC3F,OAAO,EACL,UAAU,EACV,SAAS,EACT,oBAAoB,EACpB,KAAK,gBAAgB,EACrB,KAAK,kBAAkB,EACvB,KAAK,mBAAmB,GACzB,MAAM,eAAe,CAAC;AACvB,OAAO,EACL,iBAAiB,EACjB,4BAA4B,EAC5B,kBAAkB,EAClB,KAAK,WAAW,EAChB,KAAK,iBAAiB,EACtB,KAAK,eAAe,EACpB,KAAK,aAAa,EAClB,KAAK,aAAa,EAClB,KAAK,OAAO,EACZ,KAAK,cAAc,EACnB,KAAK,aAAa,EAClB,KAAK,cAAc,EACnB,KAAK,WAAW,EAChB,KAAK,UAAU,EACf,KAAK,qBAAqB,EAC1B,KAAK,gBAAgB,EACrB,KAAK,SAAS,EACd,KAAK,YAAY,EACjB,KAAK,WAAW,EAChB,KAAK,sBAAsB,GAC5B,MAAM,qBAAqB,CAAC"}