@file-viewer/pptx 3.3.0 → 3.3.1

package/dist/chart.js

@@ -1,6 +1,9 @@
-import { createPptxCartesianChart } from "./chart-config.js";
+import { createPptxCartesianChart } from './chart-config.js';
+import { createPptxChartTextPlugin, mergePptxChartFonts, stylePptxChartText } from './chart-text.js';
+import { createPptxChartLegend } from './chart-legend.js';
 let chartLibraryLoader = null;
 let chartRenderer = null;
+/** Register a renderer receiving the preserved Worker model, without reopening the ZIP. */
 export const registerPptxChartRenderer = (renderer) => {
     chartRenderer = renderer;
 };
@@ -44,6 +47,7 @@ const formatEastAsianNumber = (index) => {
     return digits[Math.floor(index / 10000)] + '万' +
         (remainder ? (remainder < 1000 ? digits[0] : '') + group(remainder, false) : '');
 };
+/** DrawingML numbering, including the authored suffix punctuation. */
 export const getNumericBulletText = (type, index) => {
     if (!Number.isInteger(index) || index < 1 || index > 32767) {
         return String(index);
@@ -175,6 +179,8 @@ const applyTextFitScale = (block, scale) => {
 const hasTextOverflow = (block, fitWidth = true) => block.scrollHeight > block.clientHeight + TEXT_FIT_TOLERANCE ||
     (fitWidth && block.scrollWidth > block.clientWidth + TEXT_FIT_TOLERANCE);
 const fitOverflowingTextBlock = (block, fitWidth = true) => {
+    // noAutofit/spAutoFit preserve authored typography. Only normal AutoFit may
+    // shrink text; unmarked legacy/table content retains its existing policy.
     const mode = block.dataset.pptxAutofit;
     if (mode && mode !== 'normal')
         return;
@@ -217,7 +223,7 @@ const fitOverflowingTextBlocks = (root) => {
         .forEach(block => fitOverflowingTextBlock(block, false));
 };
 const renderChart = async (message, root) => {
-    var _a, _b, _c, _d, _e, _f, _g, _h, _j, _k, _l, _m, _o, _p;
+    var _a, _b, _c, _d, _e, _f, _g, _h, _j, _k, _l, _m, _o, _p, _q, _r, _s, _t, _u, _v;
     const payload = message.data;
     if (!(payload === null || payload === void 0 ? void 0 : payload.chartID) || !payload.chartType || !payload.chartData) {
         return;
@@ -238,10 +244,14 @@ const renderChart = async (message, root) => {
     const { billboard, d3Format } = await chartLibraryLoader();
     const bb = billboard.default || billboard;
     const { area, bar, line, pie, donut, scatter } = billboard;
+    // Billboard 4 exposes grid focus as a separately registered ESM module.
+    // Bundled or custom loaders may already provide it without this export.
     if (typeof billboard.grid === 'function') {
         billboard.grid();
     }
     const chart = {
+        // A selector makes Billboard query the main document. That misses chart
+        // placeholders inside the viewer Shadow DOM and makes it fall back to body.
         bindto: chartTarget,
     };
     const chartData = payload.chartData;
@@ -266,6 +276,8 @@ const renderChart = async (message, root) => {
                 const names = {};
                 const colors = {};
                 for (const [index, point] of ((series === null || series === void 0 ? void 0 : series.values) || []).entries()) {
+                    // Keep one library id per indexed point, not per label. Duplicate/empty
+                    // labels are valid and must never merge sectors. Null is not zero.
                     if (typeof point.y !== 'number' || !Number.isFinite(point.y) || point.y === 0)
                         continue;
                     const id = `point-${index}`;
@@ -288,6 +300,11 @@ const renderChart = async (message, root) => {
                     },
                     transition: { duration: 0 },
                     onrendered() {
+                        // Billboard accepts an absolute ring width, while DrawingML specifies
+                        // a ratio. Read its finished SVG geometry and update through the public
+                        // config API. This also tracks library resize without private state or
+                        // assumptions about legend/font layout. The re-entrancy guard bounds
+                        // the corrective redraw to one pass per changed radius.
                         if (adjustingWidth || typeof this.config !== 'function')
                             return;
                         let radius = 0;
@@ -401,10 +418,15 @@ const renderChart = async (message, root) => {
             chart.legend = {
                 show: options.legend.show !== false,
                 position: options.legend.position === 'b' ? 'bottom' : 'right',
+                // The chart library cannot measure an empty SVG text node. Use an
+                // invisible measuring character only in legend presentation; names and
+                // tooltip data still retain the document's actual empty string.
                 format: (label) => label === '' ? '\u200b' : label,
             };
         }
         if (!cartesian && ['barChart', 'areaChart', 'lineChart'].includes(payload.chartType)) {
+            // Distinct series can legitimately share a display name. Billboard groups
+            // by id, so disambiguate only duplicate ids and preserve authored labels.
             const used = new Set();
             const reserved = new Set(chart.data.columns.map((column) => String(column[0])));
             const names = {};
@@ -437,27 +459,50 @@ const renderChart = async (message, root) => {
             if (Object.keys(colors).length)
                 chart.data.colors = colors;
         }
+        // Billboard resets the bind target's position to relative. Keep DrawingML
+        // placement on the outer frame; only let the library own its inner surface.
         const surface = chartTarget.ownerDocument.createElement('div');
         surface.className = 'pptx-chart-surface';
         surface.style.cssText = 'width:100%;height:100%;min-width:0;min-height:0;flex:1 1 auto';
         chartTarget.replaceChildren(surface);
         chart.bindto = surface;
+        const legend = createPptxChartLegend(surface, chart, options === null || options === void 0 ? void 0 : options.legend, mergePptxChartFonts((_q = payload.chartModel) === null || _q === void 0 ? void 0 : _q.font, (_r = options === null || options === void 0 ? void 0 : options.legend) === null || _r === void 0 ? void 0 : _r.font));
+        const fontStyle = stylePptxChartText(surface, payload.chartModel, chart, (_t = (_s = payload.chartOptions) === null || _s === void 0 ? void 0 : _s.legend) === null || _t === void 0 ? void 0 : _t.font);
+        const textPlugin = createPptxChartTextPlugin(surface);
+        if (textPlugin)
+            chart.plugins = [...(chart.plugins || []), textPlugin];
+        // DrawingML fixes the chart's size in slide coordinates. Billboard's
+        // automatic measurement uses transformed screen rectangles (or a visible
+        // ancestor for hidden slides), which applies presentation scaling twice.
+        // Keep fractional authored dimensions; the viewer scales the whole slide.
+        const logicalSize = [((_u = chartTarget.style) === null || _u === void 0 ? void 0 : _u.width) || '', ((_v = chartTarget.style) === null || _v === void 0 ? void 0 : _v.height) || '']
+            .map(value => /^\d+(?:\.\d+)?px$/.test(value) ? Number.parseFloat(value) : NaN);
+        if (logicalSize.every(value => Number.isFinite(value) && value > 0)) {
+            const plotSize = legend === null || legend === void 0 ? void 0 : legend.size();
+            chart.size = plotSize && plotSize.width > 0 && plotSize.height > 0 ? plotSize : { width: logicalSize[0], height: logicalSize[1] };
+            chart.resize = { auto: false };
+        }
         try {
             const instance = bb.generate(chart);
+            legend === null || legend === void 0 ? void 0 : legend.bind(instance);
             return {
                 destroy() {
                     var _a;
                     try {
+                        legend === null || legend === void 0 ? void 0 : legend.destroy();
                         (_a = instance.destroy) === null || _a === void 0 ? void 0 : _a.call(instance);
                     }
                     finally {
                         surface.remove();
+                        fontStyle === null || fontStyle === void 0 ? void 0 : fontStyle.remove();
                     }
                 },
             };
         }
         catch (error) {
             surface.remove();
+            fontStyle === null || fontStyle === void 0 ? void 0 : fontStyle.remove();
+            legend === null || legend === void 0 ? void 0 : legend.destroy();
             throw error;
         }
     }
@@ -493,6 +538,7 @@ export const renderPptxPostProcessing = async (charts, root) => {
                     (_a = chart.destroy) === null || _a === void 0 ? void 0 : _a.call(chart);
                 }
                 catch {
+                    // The DOM may already be detached during framework unmount.
                 }
             }
             chartInstances.length = 0;

package/dist/index.d.ts

@@ -1,9 +1,9 @@
-export { PptxViewer } from "./viewer.js";
-export { PptxPresentation } from "./presentation.js";
-export type { PptxPresentationLabels, PptxPresentationState } from "./presentation.js";
-export { createPptxWorker, resolvePptxPackageWorkerUrl } from "./worker.js";
-export { registerPptxChartLibraryLoader, registerPptxChartRenderer } from "./chart.js";
-export type { PptxChartLibraries, PptxChartLibraryLoader } from "./chart.js";
-export type { PptxChartType, PptxChartLabels, PptxChartOptions, PptxChartSeries, PptxChartAxis, PptxChartGroup, PptxChartModel, PptxChartMessage, PptxChartCollection, PptxChartRenderer, } from "./chart-types.js";
-export { RECOMMENDED_ZIP_LIMITS, createDefaultPptxOptions, resolvePptxEngineOptions, } from "./options.js";
-export type { NativePptxEngineOptions, PptxDiagnosticError, PptxDiagnosticErrorCode, PptxFitMode, PptxListOptions, PptxSlideSize, PptxViewerOptions, PptxWorkerFactoryOptions, PptxWorkerMessage, PptxZipLimits, } from "./types.js";
+export { PptxViewer } from './viewer.js';
+export { PptxPresentation } from './presentation.js';
+export type { PptxPresentationLabels, PptxPresentationState } from './presentation.js';
+export { createPptxWorker, resolvePptxPackageWorkerUrl } from './worker.js';
+export { registerPptxChartLibraryLoader, registerPptxChartRenderer } from './chart.js';
+export type { PptxChartLibraries, PptxChartLibraryLoader } from './chart.js';
+export type { PptxChartType, PptxChartFont, PptxChartLabels, PptxChartOptions, PptxChartSeries, PptxChartAxis, PptxChartGroup, PptxChartModel, PptxChartMessage, PptxChartCollection, PptxChartRenderer, } from './chart-types.js';
+export { RECOMMENDED_ZIP_LIMITS, createDefaultPptxOptions, resolvePptxEngineOptions, } from './options.js';
+export type { NativePptxEngineOptions, PptxDiagnosticError, PptxDiagnosticErrorCode, PptxFitMode, PptxListOptions, PptxSlideSize, PptxViewerOptions, PptxWorkerFactoryOptions, PptxWorkerMessage, PptxZipLimits, } from './types.js';

package/dist/index.js

@@ -1,5 +1,5 @@
-export { PptxViewer } from "./viewer.js";
-export { PptxPresentation } from "./presentation.js";
-export { createPptxWorker, resolvePptxPackageWorkerUrl } from "./worker.js";
-export { registerPptxChartLibraryLoader, registerPptxChartRenderer } from "./chart.js";
-export { RECOMMENDED_ZIP_LIMITS, createDefaultPptxOptions, resolvePptxEngineOptions, } from "./options.js";
+export { PptxViewer } from './viewer.js';
+export { PptxPresentation } from './presentation.js';
+export { createPptxWorker, resolvePptxPackageWorkerUrl } from './worker.js';
+export { registerPptxChartLibraryLoader, registerPptxChartRenderer } from './chart.js';
+export { RECOMMENDED_ZIP_LIMITS, createDefaultPptxOptions, resolvePptxEngineOptions, } from './options.js';

package/dist/options.d.ts

@@ -1,4 +1,4 @@
-import type { NativePptxEngineOptions, PptxZipLimits } from "./types.js";
+import type { NativePptxEngineOptions, PptxZipLimits } from './types.js';
 export declare const RECOMMENDED_ZIP_LIMITS: Required<PptxZipLimits>;
 export declare const createDefaultPptxOptions: () => NativePptxEngineOptions;
 export declare const resolvePptxEngineOptions: (options?: Partial<NativePptxEngineOptions>) => NativePptxEngineOptions;

package/dist/presentation.d.ts

@@ -1,4 +1,4 @@
-import type { PptxViewer } from "./viewer.js";
+import type { PptxViewer } from './viewer.js';
 export interface PptxPresentationState {
     active: boolean;
     slideNumber: number;
@@ -10,6 +10,14 @@ export interface PptxPresentationLabels {
     next?: string;
     previous?: string;
 }
+/**
+ * Full-screen slideshow for a rendered PPTX deck.
+ *
+ * The slides stay where the viewer put them: the whole scale box is moved into an overlay and the
+ * inactive slots are hidden with CSS, so the engine's scoped `.flyfish-pptx-content .slide` rules
+ * keep applying and no node is cloned. A placeholder marks the original position so exiting puts
+ * everything back exactly where it was.
+ */
 export declare class PptxPresentation {
     private readonly viewer;
     private readonly labels;
@@ -32,10 +40,21 @@ export declare class PptxPresentation {
     goTo(slideNumber: number): void;
     next(): void;
     previous(): void;
+    /** Scale the active slide to fit the overlay, letterboxing whichever axis has slack. */
     layout(): void;
     destroy(): void;
     private slots;
+    /**
+     * The nodes the slideshow toggles between. Windowed decks wrap each slide in a
+     * slot; the default (non-windowed) deck appends slides directly to the content
+     * node, so those are the containers there.
+     */
     private slideContainers;
+    /**
+     * Chromium reports the fullscreen element of a shadow root on the shadow root
+     * itself while document.fullscreenElement stays on the host, so both have to
+     * be checked before deciding who owns fullscreen.
+     */
     private isFullscreenElement;
     private scheduleLayout;
     private notify;

package/dist/presentation.js

@@ -1,4 +1,12 @@
 const clamp = (value, min, max) => Math.min(Math.max(value, min), max);
+/**
+ * Full-screen slideshow for a rendered PPTX deck.
+ *
+ * The slides stay where the viewer put them: the whole scale box is moved into an overlay and the
+ * inactive slots are hidden with CSS, so the engine's scoped `.flyfish-pptx-content .slide` rules
+ * keep applying and no node is cloned. A placeholder marks the original position so exiting puts
+ * everything back exactly where it was.
+ */
 export class PptxPresentation {
     constructor(viewer, labels = {}, fullscreen = true) {
         this.overlay = null;
@@ -54,8 +62,11 @@ export class PptxPresentation {
         this.overlay = overlay;
         this.stage = stage;
         this.counter = counter;
+        // Keep the overlay inside whichever root holds the slide styles, or the engine's scoped CSS
+        // would not reach the slides once they move.
         const styleRoot = this.viewer.presentationRoot;
         styleRoot.appendChild(overlay);
+        // Park a comment where the scale box lived so exit() can restore the exact position.
         this.placeholder = documentRef.createComment('flyfish-pptx-presentation');
         this.viewer.saveScrollPosition();
         this.viewer.scaleBox.replaceWith(this.placeholder);
@@ -69,9 +80,13 @@ export class PptxPresentation {
                 this.ownsFullscreen = this.isFullscreenElement(overlay);
             }
             catch {
+                // Fullscreen needs a user gesture and can be blocked by permissions policy. The overlay is
+                // position:fixed, so the slideshow still fills the viewport without it.
                 this.ownsFullscreen = false;
             }
         }
+        // exit() may have run while fullscreen was being requested. Leave the
+        // browser out of fullscreen rather than stranded with no overlay.
         if (this.overlay !== overlay) {
             if (this.ownsFullscreen) {
                 void ((_b = documentRef.exitFullscreen) === null || _b === void 0 ? void 0 : _b.call(documentRef).catch(() => undefined));
@@ -90,6 +105,8 @@ export class PptxPresentation {
             return;
         }
         const documentRef = this.viewer.target.ownerDocument || document;
+        // Capture before the overlay leaves the DOM: a detached node's getRootNode()
+        // is the document, so the fullscreen check would fail after removal.
         const shouldExitFullscreen = this.ownsFullscreen && this.isFullscreenElement(overlay);
         this.detach();
         if (this.layoutFrame) {
@@ -132,8 +149,11 @@ export class PptxPresentation {
         }
         this.current = clamp(Math.round(slideNumber) || 1, 1, total);
         this.viewer.ensureSlideRendered(this.current);
+        // Rendering the neighbour keeps the next step instant without defeating virtualization.
         this.viewer.ensureSlideRendered(this.current + 1);
         const containers = this.slideContainers();
+        // Windowed decks tag each slot with its slide number; non-windowed decks
+        // append slides in order, so the active one is found by index.
         const byNumber = containers.some(container => Boolean(container.dataset.slideNumber));
         containers.forEach((container, index) => {
             const isActive = byNumber
@@ -159,6 +179,7 @@ export class PptxPresentation {
             this.goTo(this.current - 1);
         }
     }
+    /** Scale the active slide to fit the overlay, letterboxing whichever axis has slack. */
     layout() {
         const overlay = this.overlay;
         if (!overlay) {
@@ -170,6 +191,7 @@ export class PptxPresentation {
             }
             return index === this.current - 1;
         });
+        // Windowed decks wrap the slide in a slot; non-windowed decks are the slide.
         const slide = container && container.classList.contains('flyfish-pptx-slide-slot')
             ? container.firstElementChild
             : container;
@@ -198,6 +220,11 @@ export class PptxPresentation {
     slots() {
         return Array.from(this.viewer.content.querySelectorAll(':scope > .flyfish-pptx-slide-slot'));
     }
+    /**
+     * The nodes the slideshow toggles between. Windowed decks wrap each slide in a
+     * slot; the default (non-windowed) deck appends slides directly to the content
+     * node, so those are the containers there.
+     */
     slideContainers() {
         const slots = this.slots();
         if (slots.length > 0) {
@@ -205,6 +232,11 @@ export class PptxPresentation {
         }
         return Array.from(this.viewer.content.querySelectorAll(':scope > .slide'));
     }
+    /**
+     * Chromium reports the fullscreen element of a shadow root on the shadow root
+     * itself while document.fullscreenElement stays on the host, so both have to
+     * be checked before deciding who owns fullscreen.
+     */
     isFullscreenElement(overlay) {
         const documentRef = this.viewer.target.ownerDocument || document;
         if (documentRef.fullscreenElement === overlay) {
@@ -243,6 +275,8 @@ export class PptxPresentation {
         });
         this.on(view, 'resize', () => this.scheduleLayout());
         this.on(documentRef, 'fullscreenchange', () => {
+            // Leaving fullscreen with the browser's own Esc must close the slideshow too, otherwise the
+            // overlay would stay up as a plain fixed layer.
             if (this.ownsFullscreen && !this.isFullscreenElement(overlay)) {
                 this.ownsFullscreen = false;
                 this.exit();
@@ -261,6 +295,7 @@ export class PptxPresentation {
         if (!overlay || ((_a = event.target) === null || _a === void 0 ? void 0 : _a.closest('.flyfish-pptx-presentation-exit'))) {
             return;
         }
+        // PowerPoint advances on click; the left edge is the only place that goes back.
         const bounds = overlay.getBoundingClientRect();
         const ratio = (event.clientX - bounds.left) / (bounds.width || 1);
         if (ratio < 0.2) {
@@ -274,12 +309,16 @@ export class PptxPresentation {
         if (!this.active || event.altKey || event.metaKey || event.ctrlKey) {
             return;
         }
+        // Enter/Space on a focused control (the exit button) must activate that
+        // control, not advance the slide. Let the browser's default run instead.
         const target = event.target;
         if (target &&
             typeof target.closest === 'function' &&
             target.closest('button, a, input, textarea, select, [contenteditable="true"], [contenteditable=""]')) {
             return;
         }
+        // With two slideshows open, a key pressed inside the other overlay belongs
+        // to that overlay; only the focused one advances.
         if (target && typeof target.closest === 'function') {
             const otherOverlay = target.closest('.flyfish-pptx-presentation');
             if (otherOverlay && otherOverlay !== this.overlay) {

package/dist/styles.d.ts

@@ -1,3 +1,8 @@
+/**
+ * The legacy engine emits class-only selector lists. Prefix each top-level
+ * class rule so light-DOM consumers do not inherit generic `.slide` or
+ * generated `._css_*` rules from a renderer-local style element.
+ */
 export declare const scopePptxContentStyleText: (cssText: string) => string;
 export declare const pptxViewerCss: string;
 export declare const ensurePptxViewerStyles: (documentRef: Document, root?: Document | ShadowRoot) => void;

package/dist/styles.js

@@ -51,6 +51,11 @@ const legacyPptxCss = `
 
 `;
 const PPTX_CONTENT_STYLE_SCOPE = '.flyfish-pptx-content';
+/**
+ * The legacy engine emits class-only selector lists. Prefix each top-level
+ * class rule so light-DOM consumers do not inherit generic `.slide` or
+ * generated `._css_*` rules from a renderer-local style element.
+ */
 export const scopePptxContentStyleText = (cssText) => cssText.replace(/(^|})\s*(\.[^{}]+)\{/g, (_match, boundary, selectorList) => {
     const scopedSelectors = selectorList
         .split(',')

package/dist/types.d.ts

@@ -1,5 +1,5 @@
-import type { PptxPresentationLabels, PptxPresentationState } from "./presentation.js";
-import type { PptxChartCollection } from "./chart-types.js";
+import type { PptxPresentationLabels, PptxPresentationState } from './presentation.js';
+import type { PptxChartCollection } from './chart-types.js';
 export type PptxFitMode = 'contain' | 'none';
 export interface PptxZipLimits {
     maxFileBytes?: number;

package/dist/viewer.d.ts

@@ -1,5 +1,5 @@
-import type { PptxPresentationState } from "./presentation.js";
-import type { PptxViewerOptions } from "./types.js";
+import type { PptxPresentationState } from './presentation.js';
+import type { PptxViewerOptions } from './types.js';
 export declare class PptxViewer {
     static open(buffer: ArrayBuffer, target: HTMLElement, options?: PptxViewerOptions): Promise<PptxViewer>;
     readonly target: HTMLElement;
@@ -41,9 +41,19 @@ export declare class PptxViewer {
     get presenting(): boolean;
     get presentationSlideNumber(): number;
     private get styleRoot();
+    /**
+     * Where the slideshow overlay is mounted. It has to share a root with the injected slide styles,
+     * or the engine's scoped CSS stops applying once the slides move into the overlay.
+     */
     get presentationRoot(): ShadowRoot | HTMLElement;
+    /** Force a slide out of the virtualized window so the slideshow can show it immediately. */
     ensureSlideRendered(slideNumber: number): Element | null;
     refreshLayout(): void;
+    /**
+     * Remember where the deck was scrolled before the slideshow moves the scale
+     * box into the overlay. Moving it collapses the scroller and clamps scrollTop
+     * to zero, so the position has to be captured up front and restored on exit.
+     */
     saveScrollPosition(): void;
     restoreScrollPosition(): void;
     emitPresentationChange(state: PptxPresentationState): void;
@@ -79,6 +89,7 @@ export declare class PptxViewer {
     private findSlideWindowTarget;
     private postProcessRenderedContent;
     private postProcessSlideRecord;
+    /** Materializes every lazy slide only for the duration of an export snapshot. */
     cloneForExport(): Promise<HTMLElement>;
     private complete;
     private fail;

package/dist/viewer.js

@@ -1,9 +1,9 @@
-import { renderPptxPostProcessing } from "./chart.js";
-import { resolvePptxEngineOptions, RECOMMENDED_ZIP_LIMITS } from "./options.js";
-import { PptxPresentation } from "./presentation.js";
-import { sanitizePptxCss, sanitizePptxMarkup } from "./sanitize.js";
-import { ensurePptxViewerStyles } from "./styles.js";
-import { createPptxWorker } from "./worker.js";
+import { renderPptxPostProcessing } from './chart.js';
+import { resolvePptxEngineOptions, RECOMMENDED_ZIP_LIMITS } from './options.js';
+import { PptxPresentation } from './presentation.js';
+import { sanitizePptxCss, sanitizePptxMarkup } from './sanitize.js';
+import { ensurePptxViewerStyles } from './styles.js';
+import { createPptxWorker } from './worker.js';
 const clamp = (value, min, max) => {
     return Math.min(max, Math.max(min, value));
 };
@@ -97,6 +97,10 @@ export class PptxViewer {
         this.previewThumbnailDataUrl = null;
         this.slideSize = null;
         this.slideRecords = [];
+        // Total slides received from the worker. The windowed path mirrors this in
+        // slideRecords, but the default (non-windowed) path appends slides straight
+        // into the content node without creating records, so the deck size has to be
+        // counted independently of the virtualization bookkeeping.
         this.totalSlides = 0;
         this.savedScroll = null;
         this.pendingScrollRestore = null;
@@ -160,6 +164,10 @@ export class PptxViewer {
             ? root
             : documentRef;
     }
+    /**
+     * Where the slideshow overlay is mounted. It has to share a root with the injected slide styles,
+     * or the engine's scoped CSS stops applying once the slides move into the overlay.
+     */
     get presentationRoot() {
         const documentRef = this.target.ownerDocument || document;
         const styleRoot = this.styleRoot;
@@ -168,6 +176,7 @@ export class PptxViewer {
         }
         return documentRef.body || documentRef.documentElement;
     }
+    /** Force a slide out of the virtualized window so the slideshow can show it immediately. */
     ensureSlideRendered(slideNumber) {
         const record = this.slideRecords.find(item => item.slideNumber === slideNumber);
         if (!record) {
@@ -181,6 +190,11 @@ export class PptxViewer {
     refreshLayout() {
         this.scheduleResize();
     }
+    /**
+     * Remember where the deck was scrolled before the slideshow moves the scale
+     * box into the overlay. Moving it collapses the scroller and clamps scrollTop
+     * to zero, so the position has to be captured up front and restored on exit.
+     */
     saveScrollPosition() {
         const view = this.target.ownerDocument.defaultView || window;
         const HTMLElementCtor = view.HTMLElement;
@@ -522,6 +536,9 @@ export class PptxViewer {
         }
         const windowOptions = this.getSlideWindowOptions();
         const indexesToRender = this.getWindowedSlideIndexes(windowOptions);
+        // While presenting, the active slide and its neighbour live inside the fixed
+        // overlay, outside the scroll-view geometry the windowing code measures. Keep
+        // them mounted so a resize cannot unmount the slide that is on screen.
         const presentation = this.presentation;
         if (presentation === null || presentation === void 0 ? void 0 : presentation.active) {
             const activeIndex = this.slideRecords.findIndex(record => record.slideNumber === presentation.slideNumber);
@@ -694,6 +711,7 @@ export class PptxViewer {
         }
         await record.postProcessPromise;
     }
+    /** Materializes every lazy slide only for the duration of an export snapshot. */
     async cloneForExport() {
         if (!this.shouldWindowSlides()) {
             return this.target.cloneNode(true);
@@ -860,6 +878,7 @@ export class PptxViewer {
     }
     resize() {
         var _a, _b, _c;
+        // While presenting, the slideshow owns the transform of the same nodes.
         if ((_a = this.presentation) === null || _a === void 0 ? void 0 : _a.active) {
             this.presentation.layout();
             return;
@@ -882,6 +901,8 @@ export class PptxViewer {
         this.scaleBox.style.width = `${Math.ceil(slideWidth * effectiveScale)}px`;
         this.scaleBox.style.height = `${Math.ceil(this.content.scrollHeight * effectiveScale)}px`;
         this.scaleBox.style.minHeight = '';
+        // The scale box height is recomputed above; only now can the saved scroll
+        // position be applied without the scroller clamping it back to zero.
         if (this.pendingScrollRestore) {
             const { top, left } = this.pendingScrollRestore;
             this.pendingScrollRestore = null;