pptx-viewer-core 1.1.36 → 1.1.38

package/dist/index.d.mts

@@ -997,6 +997,14 @@ interface IPptxHandlerRuntime {
      * @returns Array of layout options belonging to the same slide master.
      */
     getAvailableLayoutsForSlide(slideIndex: number, slides: PptxSlide[]): Promise<PptxLayoutOption[]>;
+    /**
+     * Resolve the editable template (master + layout) elements a slide
+     * inherits, each carrying a `master-` / `layout-` prefixed id. Excludes
+     * placeholders; returns only decorative shapes/pictures/graphic frames.
+     *
+     * @param slideId - The slide's archive path (`PptxSlide.id`).
+     */
+    getTemplateElementsForSlide(slideId: string): Promise<PptxElement[]>;
     /**
      * Scan the loaded PPTX archive for all theme parts.
      */
@@ -6372,6 +6380,14 @@ declare class PptxHandlerRuntime$11 extends PptxHandlerRuntime$12 {
 declare class PptxHandlerRuntime$10 extends PptxHandlerRuntime$11 {
     protected textStylesEqual(left: TextStyle | undefined, right: TextStyle | undefined): boolean;
     protected hasMixedTextStyles(textSegments: TextSegment[]): boolean;
+    /**
+     * Whether a segment carries run-level content that the flat `el.text` string
+     * cannot represent: an OOXML field (`a:fld`), an inline equation, or a ruby
+     * (phonetic) annotation. Such segments must survive a save: collapsing them
+     * to the plain-text path silently downgrades a field to static text (e.g. a
+     * slide-number field becomes a frozen number) or drops the equation/ruby.
+     */
+    protected isStructuralTextSegment(segment: TextSegment): boolean;
     protected areTextSegmentsUniform(textSegments: TextSegment[] | undefined): boolean;
     protected parseBooleanAttr(value: unknown): boolean;
     protected parseOptionalBooleanAttr(value: unknown): boolean | undefined;
@@ -8564,6 +8580,35 @@ declare class PptxHandlerRuntime$2 extends PptxHandlerRuntime$3 {
      * Find the master path for a slide by walking: slide -> layout -> master.
      */
     protected findMasterPathForSlide(slidePath: string): string | undefined;
+    /**
+     * Resolve the editable template (master + layout) elements a slide
+     * inherits, each carrying a `master-` / `layout-` prefixed id.
+     *
+     * This is the canonical entry point for an "edit template/master"
+     * feature: it returns the same decorative master/layout shapes that the
+     * loader already merges in front of slide-authored content (master shapes
+     * behind, layout shapes on top), reusing the cached
+     * {@link getLayoutElements} parse. Resolving a slide that has not been
+     * loaded yet (no relationships cached) yields an empty array.
+     *
+     * Important scope notes for callers:
+     *  - Placeholder shapes (`<p:ph>`) are intentionally excluded; those are
+     *    resolved separately into each slide's own placeholders. Only
+     *    non-placeholder decorations (shapes, pictures, graphic frames) are
+     *    returned, which is exactly what the save writeback path supports.
+     *  - The returned elements are shared by every slide that inherits the
+     *    same layout/master. Editing one element and saving updates the shared
+     *    layout/master part, so the change is visible on all sibling slides.
+     *  - To persist an edit the binding must keep the mutated template element
+     *    inside the `slide.elements` array it passes to {@link save}; the save
+     *    writer reads template elements from `ctx.slide.elements` and writes
+     *    their shape XML back into the owning `p:spTree`.
+     *
+     * @param slideId - The slide's archive path (the `PptxSlide.id`, e.g.
+     *   `ppt/slides/slide1.xml`).
+     * @returns Master + layout elements with prefixed ids (may be empty).
+     */
+    getTemplateElementsForSlide(slideId: string): Promise<PptxElement[]>;
     /**
      * Get layouts available for a specific slide, scoped to that slide's
      * master. If the slide's master cannot be determined, returns all
@@ -9032,6 +9077,37 @@ declare class PptxHandlerCore {
      * ```
      */
     getAvailableLayoutsForSlide(slideIndex: number, slides: PptxSlide[]): Promise<PptxLayoutOption[]>;
+    /**
+     * Resolve the editable template (master + layout) elements a slide
+     * inherits, each carrying a `master-` / `layout-` prefixed id.
+     *
+     * This is the foundation for an "edit template/master" feature. The
+     * returned elements are the decorative master/layout shapes the loader
+     * already merges behind slide-authored content (master shapes behind,
+     * layout shapes on top); placeholders are excluded. The same elements are
+     * shared by every slide inheriting the layout/master, so editing one and
+     * saving updates the shared part.
+     *
+     * To persist an edit, keep the mutated template element inside the
+     * `slide.elements` array passed to {@link save}; the save writer reads
+     * template elements from there and writes their shape XML back into the
+     * owning layout/master `p:spTree`.
+     *
+     * @param slideId - The slide's archive path (the `PptxSlide.id`).
+     * @returns Master + layout elements with prefixed ids (may be empty).
+     *
+     * @example
+     * ```ts
+     * const templateEls = await handler.getTemplateElementsForSlide(slide.id);
+     * const logo = templateEls.find((e) => e.id.startsWith("master-"));
+     * if (logo) {
+     *   logo.x += 10;
+     *   slide.elements = [...slide.elements, logo];
+     *   await handler.save(data.slides);
+     * }
+     * ```
+     */
+    getTemplateElementsForSlide(slideId: string): Promise<PptxElement[]>;
     /**
      * Apply a different layout to an existing slide.
      *

package/dist/index.d.ts

@@ -997,6 +997,14 @@ interface IPptxHandlerRuntime {
      * @returns Array of layout options belonging to the same slide master.
      */
     getAvailableLayoutsForSlide(slideIndex: number, slides: PptxSlide[]): Promise<PptxLayoutOption[]>;
+    /**
+     * Resolve the editable template (master + layout) elements a slide
+     * inherits, each carrying a `master-` / `layout-` prefixed id. Excludes
+     * placeholders; returns only decorative shapes/pictures/graphic frames.
+     *
+     * @param slideId - The slide's archive path (`PptxSlide.id`).
+     */
+    getTemplateElementsForSlide(slideId: string): Promise<PptxElement[]>;
     /**
      * Scan the loaded PPTX archive for all theme parts.
      */
@@ -6372,6 +6380,14 @@ declare class PptxHandlerRuntime$11 extends PptxHandlerRuntime$12 {
 declare class PptxHandlerRuntime$10 extends PptxHandlerRuntime$11 {
     protected textStylesEqual(left: TextStyle | undefined, right: TextStyle | undefined): boolean;
     protected hasMixedTextStyles(textSegments: TextSegment[]): boolean;
+    /**
+     * Whether a segment carries run-level content that the flat `el.text` string
+     * cannot represent: an OOXML field (`a:fld`), an inline equation, or a ruby
+     * (phonetic) annotation. Such segments must survive a save: collapsing them
+     * to the plain-text path silently downgrades a field to static text (e.g. a
+     * slide-number field becomes a frozen number) or drops the equation/ruby.
+     */
+    protected isStructuralTextSegment(segment: TextSegment): boolean;
     protected areTextSegmentsUniform(textSegments: TextSegment[] | undefined): boolean;
     protected parseBooleanAttr(value: unknown): boolean;
     protected parseOptionalBooleanAttr(value: unknown): boolean | undefined;
@@ -8564,6 +8580,35 @@ declare class PptxHandlerRuntime$2 extends PptxHandlerRuntime$3 {
      * Find the master path for a slide by walking: slide -> layout -> master.
      */
     protected findMasterPathForSlide(slidePath: string): string | undefined;
+    /**
+     * Resolve the editable template (master + layout) elements a slide
+     * inherits, each carrying a `master-` / `layout-` prefixed id.
+     *
+     * This is the canonical entry point for an "edit template/master"
+     * feature: it returns the same decorative master/layout shapes that the
+     * loader already merges in front of slide-authored content (master shapes
+     * behind, layout shapes on top), reusing the cached
+     * {@link getLayoutElements} parse. Resolving a slide that has not been
+     * loaded yet (no relationships cached) yields an empty array.
+     *
+     * Important scope notes for callers:
+     *  - Placeholder shapes (`<p:ph>`) are intentionally excluded; those are
+     *    resolved separately into each slide's own placeholders. Only
+     *    non-placeholder decorations (shapes, pictures, graphic frames) are
+     *    returned, which is exactly what the save writeback path supports.
+     *  - The returned elements are shared by every slide that inherits the
+     *    same layout/master. Editing one element and saving updates the shared
+     *    layout/master part, so the change is visible on all sibling slides.
+     *  - To persist an edit the binding must keep the mutated template element
+     *    inside the `slide.elements` array it passes to {@link save}; the save
+     *    writer reads template elements from `ctx.slide.elements` and writes
+     *    their shape XML back into the owning `p:spTree`.
+     *
+     * @param slideId - The slide's archive path (the `PptxSlide.id`, e.g.
+     *   `ppt/slides/slide1.xml`).
+     * @returns Master + layout elements with prefixed ids (may be empty).
+     */
+    getTemplateElementsForSlide(slideId: string): Promise<PptxElement[]>;
     /**
      * Get layouts available for a specific slide, scoped to that slide's
      * master. If the slide's master cannot be determined, returns all
@@ -9032,6 +9077,37 @@ declare class PptxHandlerCore {
      * ```
      */
     getAvailableLayoutsForSlide(slideIndex: number, slides: PptxSlide[]): Promise<PptxLayoutOption[]>;
+    /**
+     * Resolve the editable template (master + layout) elements a slide
+     * inherits, each carrying a `master-` / `layout-` prefixed id.
+     *
+     * This is the foundation for an "edit template/master" feature. The
+     * returned elements are the decorative master/layout shapes the loader
+     * already merges behind slide-authored content (master shapes behind,
+     * layout shapes on top); placeholders are excluded. The same elements are
+     * shared by every slide inheriting the layout/master, so editing one and
+     * saving updates the shared part.
+     *
+     * To persist an edit, keep the mutated template element inside the
+     * `slide.elements` array passed to {@link save}; the save writer reads
+     * template elements from there and writes their shape XML back into the
+     * owning layout/master `p:spTree`.
+     *
+     * @param slideId - The slide's archive path (the `PptxSlide.id`).
+     * @returns Master + layout elements with prefixed ids (may be empty).
+     *
+     * @example
+     * ```ts
+     * const templateEls = await handler.getTemplateElementsForSlide(slide.id);
+     * const logo = templateEls.find((e) => e.id.startsWith("master-"));
+     * if (logo) {
+     *   logo.x += 10;
+     *   slide.elements = [...slide.elements, logo];
+     *   await handler.save(data.slides);
+     * }
+     * ```
+     */
+    getTemplateElementsForSlide(slideId: string): Promise<PptxElement[]>;
     /**
      * Apply a different layout to an existing slide.
      *

package/dist/index.js

@@ -30523,8 +30523,24 @@ var PptxHandlerRuntime17 = class extends PptxHandlerRuntime16 {
       (segment, index) => index > 0 && !this.textStylesEqual(segment.style, baseStyle)
     );
   }
+  /**
+   * Whether a segment carries run-level content that the flat `el.text` string
+   * cannot represent: an OOXML field (`a:fld`), an inline equation, or a ruby
+   * (phonetic) annotation. Such segments must survive a save: collapsing them
+   * to the plain-text path silently downgrades a field to static text (e.g. a
+   * slide-number field becomes a frozen number) or drops the equation/ruby.
+   */
+  isStructuralTextSegment(segment) {
+    return Boolean(segment.fieldType || segment.equationXml || segment.rubyText);
+  }
   areTextSegmentsUniform(textSegments) {
-    if (!textSegments || textSegments.length <= 1) {
+    if (!textSegments || textSegments.length === 0) {
+      return true;
+    }
+    if (textSegments.some((segment) => this.isStructuralTextSegment(segment))) {
+      return false;
+    }
+    if (textSegments.length === 1) {
       return true;
     }
     return !this.hasMixedTextStyles(textSegments);
@@ -46123,6 +46139,37 @@ var PptxHandlerRuntime79 = class extends PptxHandlerRuntime78 {
     }
     return this.findMasterPathForLayout(layoutPath);
   }
+  /**
+   * Resolve the editable template (master + layout) elements a slide
+   * inherits, each carrying a `master-` / `layout-` prefixed id.
+   *
+   * This is the canonical entry point for an "edit template/master"
+   * feature: it returns the same decorative master/layout shapes that the
+   * loader already merges in front of slide-authored content (master shapes
+   * behind, layout shapes on top), reusing the cached
+   * {@link getLayoutElements} parse. Resolving a slide that has not been
+   * loaded yet (no relationships cached) yields an empty array.
+   *
+   * Important scope notes for callers:
+   *  - Placeholder shapes (`<p:ph>`) are intentionally excluded; those are
+   *    resolved separately into each slide's own placeholders. Only
+   *    non-placeholder decorations (shapes, pictures, graphic frames) are
+   *    returned, which is exactly what the save writeback path supports.
+   *  - The returned elements are shared by every slide that inherits the
+   *    same layout/master. Editing one element and saving updates the shared
+   *    layout/master part, so the change is visible on all sibling slides.
+   *  - To persist an edit the binding must keep the mutated template element
+   *    inside the `slide.elements` array it passes to {@link save}; the save
+   *    writer reads template elements from `ctx.slide.elements` and writes
+   *    their shape XML back into the owning `p:spTree`.
+   *
+   * @param slideId - The slide's archive path (the `PptxSlide.id`, e.g.
+   *   `ppt/slides/slide1.xml`).
+   * @returns Master + layout elements with prefixed ids (may be empty).
+   */
+  async getTemplateElementsForSlide(slideId) {
+    return this.getLayoutElements(slideId);
+  }
   /**
    * Get layouts available for a specific slide, scoped to that slide's
    * master. If the slide's master cannot be determined, returns all
@@ -46795,6 +46842,39 @@ var PptxHandlerCore = class {
   async getAvailableLayoutsForSlide(slideIndex, slides) {
     return this.runtime.getAvailableLayoutsForSlide(slideIndex, slides);
   }
+  /**
+   * Resolve the editable template (master + layout) elements a slide
+   * inherits, each carrying a `master-` / `layout-` prefixed id.
+   *
+   * This is the foundation for an "edit template/master" feature. The
+   * returned elements are the decorative master/layout shapes the loader
+   * already merges behind slide-authored content (master shapes behind,
+   * layout shapes on top); placeholders are excluded. The same elements are
+   * shared by every slide inheriting the layout/master, so editing one and
+   * saving updates the shared part.
+   *
+   * To persist an edit, keep the mutated template element inside the
+   * `slide.elements` array passed to {@link save}; the save writer reads
+   * template elements from there and writes their shape XML back into the
+   * owning layout/master `p:spTree`.
+   *
+   * @param slideId - The slide's archive path (the `PptxSlide.id`).
+   * @returns Master + layout elements with prefixed ids (may be empty).
+   *
+   * @example
+   * ```ts
+   * const templateEls = await handler.getTemplateElementsForSlide(slide.id);
+   * const logo = templateEls.find((e) => e.id.startsWith("master-"));
+   * if (logo) {
+   *   logo.x += 10;
+   *   slide.elements = [...slide.elements, logo];
+   *   await handler.save(data.slides);
+   * }
+   * ```
+   */
+  async getTemplateElementsForSlide(slideId) {
+    return this.runtime.getTemplateElementsForSlide(slideId);
+  }
   /**
    * Apply a different layout to an existing slide.
    *

package/dist/index.mjs

@@ -30518,8 +30518,24 @@ var PptxHandlerRuntime17 = class extends PptxHandlerRuntime16 {
       (segment, index) => index > 0 && !this.textStylesEqual(segment.style, baseStyle)
     );
   }
+  /**
+   * Whether a segment carries run-level content that the flat `el.text` string
+   * cannot represent: an OOXML field (`a:fld`), an inline equation, or a ruby
+   * (phonetic) annotation. Such segments must survive a save: collapsing them
+   * to the plain-text path silently downgrades a field to static text (e.g. a
+   * slide-number field becomes a frozen number) or drops the equation/ruby.
+   */
+  isStructuralTextSegment(segment) {
+    return Boolean(segment.fieldType || segment.equationXml || segment.rubyText);
+  }
   areTextSegmentsUniform(textSegments) {
-    if (!textSegments || textSegments.length <= 1) {
+    if (!textSegments || textSegments.length === 0) {
+      return true;
+    }
+    if (textSegments.some((segment) => this.isStructuralTextSegment(segment))) {
+      return false;
+    }
+    if (textSegments.length === 1) {
       return true;
     }
     return !this.hasMixedTextStyles(textSegments);
@@ -46118,6 +46134,37 @@ var PptxHandlerRuntime79 = class extends PptxHandlerRuntime78 {
     }
     return this.findMasterPathForLayout(layoutPath);
   }
+  /**
+   * Resolve the editable template (master + layout) elements a slide
+   * inherits, each carrying a `master-` / `layout-` prefixed id.
+   *
+   * This is the canonical entry point for an "edit template/master"
+   * feature: it returns the same decorative master/layout shapes that the
+   * loader already merges in front of slide-authored content (master shapes
+   * behind, layout shapes on top), reusing the cached
+   * {@link getLayoutElements} parse. Resolving a slide that has not been
+   * loaded yet (no relationships cached) yields an empty array.
+   *
+   * Important scope notes for callers:
+   *  - Placeholder shapes (`<p:ph>`) are intentionally excluded; those are
+   *    resolved separately into each slide's own placeholders. Only
+   *    non-placeholder decorations (shapes, pictures, graphic frames) are
+   *    returned, which is exactly what the save writeback path supports.
+   *  - The returned elements are shared by every slide that inherits the
+   *    same layout/master. Editing one element and saving updates the shared
+   *    layout/master part, so the change is visible on all sibling slides.
+   *  - To persist an edit the binding must keep the mutated template element
+   *    inside the `slide.elements` array it passes to {@link save}; the save
+   *    writer reads template elements from `ctx.slide.elements` and writes
+   *    their shape XML back into the owning `p:spTree`.
+   *
+   * @param slideId - The slide's archive path (the `PptxSlide.id`, e.g.
+   *   `ppt/slides/slide1.xml`).
+   * @returns Master + layout elements with prefixed ids (may be empty).
+   */
+  async getTemplateElementsForSlide(slideId) {
+    return this.getLayoutElements(slideId);
+  }
   /**
    * Get layouts available for a specific slide, scoped to that slide's
    * master. If the slide's master cannot be determined, returns all
@@ -46790,6 +46837,39 @@ var PptxHandlerCore = class {
   async getAvailableLayoutsForSlide(slideIndex, slides) {
     return this.runtime.getAvailableLayoutsForSlide(slideIndex, slides);
   }
+  /**
+   * Resolve the editable template (master + layout) elements a slide
+   * inherits, each carrying a `master-` / `layout-` prefixed id.
+   *
+   * This is the foundation for an "edit template/master" feature. The
+   * returned elements are the decorative master/layout shapes the loader
+   * already merges behind slide-authored content (master shapes behind,
+   * layout shapes on top); placeholders are excluded. The same elements are
+   * shared by every slide inheriting the layout/master, so editing one and
+   * saving updates the shared part.
+   *
+   * To persist an edit, keep the mutated template element inside the
+   * `slide.elements` array passed to {@link save}; the save writer reads
+   * template elements from there and writes their shape XML back into the
+   * owning layout/master `p:spTree`.
+   *
+   * @param slideId - The slide's archive path (the `PptxSlide.id`).
+   * @returns Master + layout elements with prefixed ids (may be empty).
+   *
+   * @example
+   * ```ts
+   * const templateEls = await handler.getTemplateElementsForSlide(slide.id);
+   * const logo = templateEls.find((e) => e.id.startsWith("master-"));
+   * if (logo) {
+   *   logo.x += 10;
+   *   slide.elements = [...slide.elements, logo];
+   *   await handler.save(data.slides);
+   * }
+   * ```
+   */
+  async getTemplateElementsForSlide(slideId) {
+    return this.runtime.getTemplateElementsForSlide(slideId);
+  }
   /**
    * Apply a different layout to an existing slide.
    *

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "pptx-viewer-core",
-	"version": "1.1.36",
+	"version": "1.1.38",
 	"description": "PowerPoint PPTX engine: parse, edit, serialize, and convert .pptx files. Framework-agnostic TypeScript SDK.",
 	"keywords": [
 		"converter",