@particle-academy/dark-slide 0.6.2 → 0.7.0

package/dist/index.d.cts

@@ -3,7 +3,9 @@
  * agent JSON, so most fields are optional and extra keys are tolerated; the
  * Validator is the gate.
  */
-type ElementType = "text" | "image" | "chart" | "code" | "table" | "shape" | "embed";
+type ElementType = "text" | "image" | "chart" | "code" | "table" | "shape" | "embed"
+/** Composites — expand into a `table` before the writer sees them. */
+ | "kpiBand" | "metadataGrid";
 interface ThemeColors {
     background?: string;
     text?: string;
@@ -76,8 +78,11 @@ interface SlideElement {
     columns?: {
         key: string;
         label: string;
+        width?: number;
+        align?: string;
     }[];
     rows?: Record<string, unknown>[];
+    items?: Record<string, unknown>[];
     option?: Record<string, unknown>;
     chartTheme?: string;
     image?: string;
@@ -215,7 +220,14 @@ declare class Repairer {
  */
 declare const Schema: {
     VERSION: string;
-    ELEMENT_TYPES: readonly ["text", "image", "chart", "code", "table", "shape", "embed"];
+    /**
+     * `kpiBand` and `metadataGrid` are COMPOSITES: they expand into a `table`
+     * before the writer serialises anything, so they add no OOXML surface and
+     * read back as the table they became. See table/composites.
+     */
+    ELEMENT_TYPES: readonly ["text", "image", "chart", "code", "table", "shape", "embed", "kpiBand", "metadataGrid"];
+    /** The subset of ELEMENT_TYPES that is sugar over a `table`. */
+    COMPOSITE_ELEMENT_TYPES: readonly ["kpiBand", "metadataGrid"];
     SLIDE_LAYOUTS: readonly ["blank", "title", "title-content", "two-column", "section-divider", "image-text", "text-image", "quote"];
     SHAPE_KINDS: readonly ["rect", "rounded-rect", "ellipse", "triangle", "line", "arrow"];
     TEXT_FORMATS: readonly ["markdown", "html", "plain"];
@@ -250,7 +262,24 @@ declare class PptxWriter {
     private mediaFiles;
     /** Ordered list of chart part XML queued for the archive. */
     private chartFiles;
+    /** Extension uri under which the deck's mono typeface is recorded in theme1.xml. */
+    static readonly MONO_FONT_EXT_URI = "urn:particle-academy:dark-slide:mono-font";
+    /** Namespace for DarkSlide's own elements inside an `<a:ext>`. */
+    static readonly NS_DARK_SLIDE = "urn:particle-academy:dark-slide";
     private themeAccent;
+    /** The deck's theme, kept whole so the table resolver can read its colours. */
+    private deckTheme;
+    /**
+     * Monospace typeface for code runs, from `theme.fonts.mono`.
+     *
+     * There is no third slot in OOXML's `<a:fontScheme>` — a theme carries a
+     * major and a minor font and nothing else — so unlike heading and body this
+     * cannot ride along in theme1.xml and has to be written onto each code run.
+     * That is why it was missed in all three engines: accepted by every
+     * validator, published in the JSON Schema handed to an LLM as the tool
+     * definition, named in the writers' own docblocks, and applied nowhere.
+     */
+    private themeMono;
     private tnId;
     private pendingSlideRels;
     constructor(tempDir?: string | null, allowHttpImages?: boolean);
@@ -304,7 +333,22 @@ declare class PptxWriter {
     private buildCodeShape;
     private buildHighlightedCodeBody;
     private buildTable;
+    /**
+     * Serialise one resolved cell. Makes no styling decisions — every value here
+     * was decided by the resolver.
+     *
+     * Three things in here are load-bearing and easy to get wrong:
+     *
+     *   - `gridSpan` / `rowSpan` / `hMerge` / `vMerge` are attributes of
+     *     `<a:tc>`, NOT of `<a:tcPr>`. On `tcPr` they parse fine and are silently
+     *     ignored, so the table renders unmerged with no error anywhere.
+     *   - `<a:tcPr>` has a FIXED child order: lnL, lnR, lnT, lnB, then the fill.
+     *     Emitting the fill first produces a file whose fill a reader drops.
+     *   - "No border" is STATED. An absent `<a:lnL>` is an UNSPECIFIED rule, not
+     *     an absent one, and a reader supplies its own.
+     */
     private buildTableCell;
+    private buildCellRun;
     private buildChart;
     private chartPreRenderSrc;
     private buildChartFrame;
@@ -326,6 +370,28 @@ declare class PptxWriter {
     private buildPlaceholder;
     private buildTextBody;
     private buildRun;
+    /**
+     * `<a:lnSpc>` / `<a:spcBef>` / `<a:spcAft>` for a paragraph.
+     *
+     * `lineHeight` is a MULTIPLE (1.4 = 140%), matching CSS and the fancy-slides
+     * editor; `spaceBefore` / `spaceAfter` are points. Empty when the style is
+     * silent, so decks that predate this keep their bytes.
+     */
+    private paragraphSpacing;
+    /**
+     * The bullet markup for a list paragraph.
+     *
+     * `none` suppresses it, `number` makes an auto-numbered list, and anything
+     * else is taken as the literal character — which is all a check-mark list is.
+     * The default stays the round bullet the writer has always emitted.
+     */
+    private bulletMarkup;
+    /**
+     * Run attributes that apply to every run in the body: letter spacing and
+     * capitalisation. Both are `<a:rPr>` attributes, so they have to be built as
+     * a string and appended rather than nested.
+     */
+    private runExtraAttrs;
     private weightToBold;
     private alignToAlgn;
     private xfrmFromFractions;
@@ -344,10 +410,25 @@ declare class PptxWriter {
  */
 declare class PptxReader {
     private currentSlideRels;
+    /**
+     * The mono typeface this deck was written with, read back from the theme's
+     * `<a:extLst>`. Empty when the package does not record one — anything not
+     * written by a current DarkSlide — in which case the name sniff below is the
+     * only signal available.
+     */
+    private monoTypeface;
     private parts;
     /** Read a PPTX file's bytes into a Deck schema object. */
     read(bytes: Uint8Array): Record<string, unknown>;
     fromBytes(bytes: Uint8Array): Record<string, unknown>;
+    /**
+     * The mono typeface recorded in `theme1.xml`'s `<a:extLst>`, or `""`.
+     *
+     * Deliberately a regex rather than a parse: this runs before the deck is
+     * built, the element is one attribute deep, and a theme part that does not
+     * carry the extension is the common case rather than an error.
+     */
+    private readMonoTypeface;
     private getPart;
     private extract;
     private parseSlideRels;

package/dist/index.d.ts

@@ -3,7 +3,9 @@
  * agent JSON, so most fields are optional and extra keys are tolerated; the
  * Validator is the gate.
  */
-type ElementType = "text" | "image" | "chart" | "code" | "table" | "shape" | "embed";
+type ElementType = "text" | "image" | "chart" | "code" | "table" | "shape" | "embed"
+/** Composites — expand into a `table` before the writer sees them. */
+ | "kpiBand" | "metadataGrid";
 interface ThemeColors {
     background?: string;
     text?: string;
@@ -76,8 +78,11 @@ interface SlideElement {
     columns?: {
         key: string;
         label: string;
+        width?: number;
+        align?: string;
     }[];
     rows?: Record<string, unknown>[];
+    items?: Record<string, unknown>[];
     option?: Record<string, unknown>;
     chartTheme?: string;
     image?: string;
@@ -215,7 +220,14 @@ declare class Repairer {
  */
 declare const Schema: {
     VERSION: string;
-    ELEMENT_TYPES: readonly ["text", "image", "chart", "code", "table", "shape", "embed"];
+    /**
+     * `kpiBand` and `metadataGrid` are COMPOSITES: they expand into a `table`
+     * before the writer serialises anything, so they add no OOXML surface and
+     * read back as the table they became. See table/composites.
+     */
+    ELEMENT_TYPES: readonly ["text", "image", "chart", "code", "table", "shape", "embed", "kpiBand", "metadataGrid"];
+    /** The subset of ELEMENT_TYPES that is sugar over a `table`. */
+    COMPOSITE_ELEMENT_TYPES: readonly ["kpiBand", "metadataGrid"];
     SLIDE_LAYOUTS: readonly ["blank", "title", "title-content", "two-column", "section-divider", "image-text", "text-image", "quote"];
     SHAPE_KINDS: readonly ["rect", "rounded-rect", "ellipse", "triangle", "line", "arrow"];
     TEXT_FORMATS: readonly ["markdown", "html", "plain"];
@@ -250,7 +262,24 @@ declare class PptxWriter {
     private mediaFiles;
     /** Ordered list of chart part XML queued for the archive. */
     private chartFiles;
+    /** Extension uri under which the deck's mono typeface is recorded in theme1.xml. */
+    static readonly MONO_FONT_EXT_URI = "urn:particle-academy:dark-slide:mono-font";
+    /** Namespace for DarkSlide's own elements inside an `<a:ext>`. */
+    static readonly NS_DARK_SLIDE = "urn:particle-academy:dark-slide";
     private themeAccent;
+    /** The deck's theme, kept whole so the table resolver can read its colours. */
+    private deckTheme;
+    /**
+     * Monospace typeface for code runs, from `theme.fonts.mono`.
+     *
+     * There is no third slot in OOXML's `<a:fontScheme>` — a theme carries a
+     * major and a minor font and nothing else — so unlike heading and body this
+     * cannot ride along in theme1.xml and has to be written onto each code run.
+     * That is why it was missed in all three engines: accepted by every
+     * validator, published in the JSON Schema handed to an LLM as the tool
+     * definition, named in the writers' own docblocks, and applied nowhere.
+     */
+    private themeMono;
     private tnId;
     private pendingSlideRels;
     constructor(tempDir?: string | null, allowHttpImages?: boolean);
@@ -304,7 +333,22 @@ declare class PptxWriter {
     private buildCodeShape;
     private buildHighlightedCodeBody;
     private buildTable;
+    /**
+     * Serialise one resolved cell. Makes no styling decisions — every value here
+     * was decided by the resolver.
+     *
+     * Three things in here are load-bearing and easy to get wrong:
+     *
+     *   - `gridSpan` / `rowSpan` / `hMerge` / `vMerge` are attributes of
+     *     `<a:tc>`, NOT of `<a:tcPr>`. On `tcPr` they parse fine and are silently
+     *     ignored, so the table renders unmerged with no error anywhere.
+     *   - `<a:tcPr>` has a FIXED child order: lnL, lnR, lnT, lnB, then the fill.
+     *     Emitting the fill first produces a file whose fill a reader drops.
+     *   - "No border" is STATED. An absent `<a:lnL>` is an UNSPECIFIED rule, not
+     *     an absent one, and a reader supplies its own.
+     */
     private buildTableCell;
+    private buildCellRun;
     private buildChart;
     private chartPreRenderSrc;
     private buildChartFrame;
@@ -326,6 +370,28 @@ declare class PptxWriter {
     private buildPlaceholder;
     private buildTextBody;
     private buildRun;
+    /**
+     * `<a:lnSpc>` / `<a:spcBef>` / `<a:spcAft>` for a paragraph.
+     *
+     * `lineHeight` is a MULTIPLE (1.4 = 140%), matching CSS and the fancy-slides
+     * editor; `spaceBefore` / `spaceAfter` are points. Empty when the style is
+     * silent, so decks that predate this keep their bytes.
+     */
+    private paragraphSpacing;
+    /**
+     * The bullet markup for a list paragraph.
+     *
+     * `none` suppresses it, `number` makes an auto-numbered list, and anything
+     * else is taken as the literal character — which is all a check-mark list is.
+     * The default stays the round bullet the writer has always emitted.
+     */
+    private bulletMarkup;
+    /**
+     * Run attributes that apply to every run in the body: letter spacing and
+     * capitalisation. Both are `<a:rPr>` attributes, so they have to be built as
+     * a string and appended rather than nested.
+     */
+    private runExtraAttrs;
     private weightToBold;
     private alignToAlgn;
     private xfrmFromFractions;
@@ -344,10 +410,25 @@ declare class PptxWriter {
  */
 declare class PptxReader {
     private currentSlideRels;
+    /**
+     * The mono typeface this deck was written with, read back from the theme's
+     * `<a:extLst>`. Empty when the package does not record one — anything not
+     * written by a current DarkSlide — in which case the name sniff below is the
+     * only signal available.
+     */
+    private monoTypeface;
     private parts;
     /** Read a PPTX file's bytes into a Deck schema object. */
     read(bytes: Uint8Array): Record<string, unknown>;
     fromBytes(bytes: Uint8Array): Record<string, unknown>;
+    /**
+     * The mono typeface recorded in `theme1.xml`'s `<a:extLst>`, or `""`.
+     *
+     * Deliberately a regex rather than a parse: this runs before the deck is
+     * built, the element is one attribute deep, and a theme part that does not
+     * carry the extension is the common case rather than an error.
+     */
+    private readMonoTypeface;
     private getPart;
     private extract;
     private parseSlideRels;