@jsamuel1/pptxgenjs 4.1.2 → 4.1.4

package/dist/utils.cjs.js

@@ -0,0 +1,148 @@
+/* PptxGenJS 4.1.4 @ 2026-06-08T05:10:40.789Z */
+'use strict';
+
+/**
+ * PptxGenJS — Theme Extraction utility (docs/feature-theme-extraction.md)
+ *
+ * Parses CSS `:root { --var: value; }` custom properties and maps known variable-name
+ * patterns to a theme palette (background/accent/text/font + an extended colour set).
+ * Pure, dependency-free, regex-based parsing — no DOM and no browser required, so it runs
+ * in Node.js. This is an OPTIONAL utility (imported from `@jsamuel1/pptxgenjs/utils`), not
+ * part of the main `PptxGenJS` class, keeping the core library focused on OOXML generation.
+ */
+/** Built-in dark preset (matches docs/feature-theme-extraction.md). */
+const DARK_PRESET = {
+    bg: '121218',
+    bgSecondary: '1A1A24',
+    accent: '7C3AED',
+    accentSoft: 'A78BFA',
+    text: 'E4E4ED',
+    textSecondary: '8A8A9A',
+    font: 'Inter',
+    sky: '38BDF8',
+    green: '10B981',
+    orange: 'FF9900',
+    red: 'EF4444',
+};
+/** Built-in light preset. */
+const LIGHT_PRESET = {
+    bg: 'FFFFFF',
+    bgSecondary: 'F4F4F7',
+    accent: '7C3AED',
+    accentSoft: 'A78BFA',
+    text: '121218',
+    textSecondary: '5A5A6A',
+    font: 'Inter',
+    sky: '0EA5E9',
+    green: '059669',
+    orange: 'EA580C',
+    red: 'DC2626',
+};
+/**
+ * Exact CSS-variable-name → theme-slot map. Names are matched exactly (NOT by substring) so
+ * `--bg` and `--bg-card` resolve to different slots. Mirrors the table in the feature spec.
+ */
+const VAR_TO_SLOT = {
+    // bg
+    bg: 'bg', 'color-bg': 'bg', background: 'bg', 'bg-deep': 'bg',
+    // bgSecondary
+    'bg-card': 'bgSecondary', card: 'bgSecondary', 'color-bg-secondary': 'bgSecondary', 'bg-surface': 'bgSecondary',
+    // accent
+    purple: 'accent', accent: 'accent', 'color-primary': 'accent', primary: 'accent',
+    // accentSoft
+    'purple-soft': 'accentSoft', 'accent-soft': 'accentSoft', 'color-primary-light': 'accentSoft',
+    // text
+    white: 'text', text: 'text', 'color-text': 'text', foreground: 'text',
+    // textSecondary
+    gray: 'textSecondary', muted: 'textSecondary', 'color-text-secondary': 'textSecondary',
+    // sky
+    sky: 'sky', blue: 'sky', info: 'sky',
+    // green
+    green: 'green', success: 'green',
+    // orange
+    orange: 'orange', warning: 'orange',
+    // red
+    red: 'red', error: 'red', danger: 'red',
+    // font
+    font: 'font', 'font-family': 'font',
+};
+/** Slots whose value is a colour (vs. a font family) — used to decide value normalisation. */
+const COLOR_SLOTS = new Set(['bg', 'bgSecondary', 'accent', 'accentSoft', 'text', 'textSecondary', 'sky', 'green', 'orange', 'red']);
+/** Normalise a colour value to a 6-digit hex (no `#`). 3-digit hex is expanded; non-hex returned as-is. */
+function normalizeColor(raw) {
+    let v = raw.trim().replace(/^#/, '');
+    // Expand 3-digit shorthand (#abc -> AABBCC)
+    if (/^[0-9a-fA-F]{3}$/.test(v))
+        v = v.split('').map(c => c + c).join('');
+    // Uppercase 6/8-digit hex for consistency with the rest of the library
+    if (/^[0-9a-fA-F]{6}([0-9a-fA-F]{2})?$/.test(v))
+        return v.toUpperCase();
+    // rgb()/hsl()/named colours are returned trimmed but unconverted (documented limitation)
+    return v;
+}
+/** Normalise a font-family value: strip surrounding quotes and take the first family. */
+function normalizeFont(raw) {
+    const first = raw.split(',')[0].trim();
+    return first.replace(/^['"]/, '').replace(/['"]$/, '').trim();
+}
+/**
+ * Extract `--name: value;` custom-property declarations from CSS text.
+ * Prefers declarations inside `:root { … }` blocks; if none are found, falls back to scanning
+ * the entire string (covers inline/style-block custom props without a `:root` selector).
+ * @returns map of bare variable name (no leading `--`) -> value
+ */
+function parseCssVars(css) {
+    const out = {};
+    const declRegex = /--([\w-]+)\s*:\s*([^;]+);/g;
+    const collect = (text) => {
+        let m;
+        while ((m = declRegex.exec(text)) !== null) {
+            out[m[1].trim().toLowerCase()] = m[2].trim();
+        }
+    };
+    // 1) :root blocks (there can be more than one)
+    const rootRegex = /:root\s*\{([^}]*)\}/g;
+    let rootMatch;
+    let foundRoot = false;
+    while ((rootMatch = rootRegex.exec(css)) !== null) {
+        foundRoot = true;
+        declRegex.lastIndex = 0;
+        collect(rootMatch[1]);
+    }
+    // 2) Fallback: no :root vars — scan the whole CSS for custom-prop declarations
+    if (!foundRoot) {
+        declRegex.lastIndex = 0;
+        collect(css);
+    }
+    return out;
+}
+/**
+ * Parse CSS `:root` custom properties into a theme palette, falling back to a preset for any
+ * slot not present in the CSS.
+ * @param {string} css - CSS text (or any text containing `--name: value;` declarations)
+ * @param {ExtractThemeOptions} [options] - presets + which preset to fall back to
+ * @returns {ThemePalette} the resolved palette (always complete — preset fills the gaps)
+ * @example
+ * const theme = extractThemeFromCSS(':root{ --bg:#121218; --purple:#7C3AED; }')
+ * // => { bg: '121218', accent: '7C3AED', ... }
+ */
+function extractThemeFromCSS(css, options = {}) {
+    const presets = Object.assign({ dark: DARK_PRESET, light: LIGHT_PRESET }, (options.presets || {}));
+    const presetName = options.defaultPreset || 'dark';
+    const base = presets[presetName] || DARK_PRESET;
+    // Start from a complete palette (dark) then layer the chosen preset so the result is always whole
+    const theme = Object.assign(Object.assign({}, DARK_PRESET), base);
+    if (typeof css === 'string' && css.length > 0) {
+        const vars = parseCssVars(css);
+        Object.keys(vars).forEach(name => {
+            const slot = VAR_TO_SLOT[name];
+            if (!slot)
+                return;
+            const value = vars[name];
+            theme[slot] = slot === 'font' || !COLOR_SLOTS.has(slot) ? normalizeFont(value) : normalizeColor(value);
+        });
+    }
+    return theme;
+}
+
+exports.extractThemeFromCSS = extractThemeFromCSS;

package/dist/utils.es.js

@@ -0,0 +1,146 @@
+/* PptxGenJS 4.1.4 @ 2026-06-08T05:10:40.789Z */
+/**
+ * PptxGenJS — Theme Extraction utility (docs/feature-theme-extraction.md)
+ *
+ * Parses CSS `:root { --var: value; }` custom properties and maps known variable-name
+ * patterns to a theme palette (background/accent/text/font + an extended colour set).
+ * Pure, dependency-free, regex-based parsing — no DOM and no browser required, so it runs
+ * in Node.js. This is an OPTIONAL utility (imported from `@jsamuel1/pptxgenjs/utils`), not
+ * part of the main `PptxGenJS` class, keeping the core library focused on OOXML generation.
+ */
+/** Built-in dark preset (matches docs/feature-theme-extraction.md). */
+const DARK_PRESET = {
+    bg: '121218',
+    bgSecondary: '1A1A24',
+    accent: '7C3AED',
+    accentSoft: 'A78BFA',
+    text: 'E4E4ED',
+    textSecondary: '8A8A9A',
+    font: 'Inter',
+    sky: '38BDF8',
+    green: '10B981',
+    orange: 'FF9900',
+    red: 'EF4444',
+};
+/** Built-in light preset. */
+const LIGHT_PRESET = {
+    bg: 'FFFFFF',
+    bgSecondary: 'F4F4F7',
+    accent: '7C3AED',
+    accentSoft: 'A78BFA',
+    text: '121218',
+    textSecondary: '5A5A6A',
+    font: 'Inter',
+    sky: '0EA5E9',
+    green: '059669',
+    orange: 'EA580C',
+    red: 'DC2626',
+};
+/**
+ * Exact CSS-variable-name → theme-slot map. Names are matched exactly (NOT by substring) so
+ * `--bg` and `--bg-card` resolve to different slots. Mirrors the table in the feature spec.
+ */
+const VAR_TO_SLOT = {
+    // bg
+    bg: 'bg', 'color-bg': 'bg', background: 'bg', 'bg-deep': 'bg',
+    // bgSecondary
+    'bg-card': 'bgSecondary', card: 'bgSecondary', 'color-bg-secondary': 'bgSecondary', 'bg-surface': 'bgSecondary',
+    // accent
+    purple: 'accent', accent: 'accent', 'color-primary': 'accent', primary: 'accent',
+    // accentSoft
+    'purple-soft': 'accentSoft', 'accent-soft': 'accentSoft', 'color-primary-light': 'accentSoft',
+    // text
+    white: 'text', text: 'text', 'color-text': 'text', foreground: 'text',
+    // textSecondary
+    gray: 'textSecondary', muted: 'textSecondary', 'color-text-secondary': 'textSecondary',
+    // sky
+    sky: 'sky', blue: 'sky', info: 'sky',
+    // green
+    green: 'green', success: 'green',
+    // orange
+    orange: 'orange', warning: 'orange',
+    // red
+    red: 'red', error: 'red', danger: 'red',
+    // font
+    font: 'font', 'font-family': 'font',
+};
+/** Slots whose value is a colour (vs. a font family) — used to decide value normalisation. */
+const COLOR_SLOTS = new Set(['bg', 'bgSecondary', 'accent', 'accentSoft', 'text', 'textSecondary', 'sky', 'green', 'orange', 'red']);
+/** Normalise a colour value to a 6-digit hex (no `#`). 3-digit hex is expanded; non-hex returned as-is. */
+function normalizeColor(raw) {
+    let v = raw.trim().replace(/^#/, '');
+    // Expand 3-digit shorthand (#abc -> AABBCC)
+    if (/^[0-9a-fA-F]{3}$/.test(v))
+        v = v.split('').map(c => c + c).join('');
+    // Uppercase 6/8-digit hex for consistency with the rest of the library
+    if (/^[0-9a-fA-F]{6}([0-9a-fA-F]{2})?$/.test(v))
+        return v.toUpperCase();
+    // rgb()/hsl()/named colours are returned trimmed but unconverted (documented limitation)
+    return v;
+}
+/** Normalise a font-family value: strip surrounding quotes and take the first family. */
+function normalizeFont(raw) {
+    const first = raw.split(',')[0].trim();
+    return first.replace(/^['"]/, '').replace(/['"]$/, '').trim();
+}
+/**
+ * Extract `--name: value;` custom-property declarations from CSS text.
+ * Prefers declarations inside `:root { … }` blocks; if none are found, falls back to scanning
+ * the entire string (covers inline/style-block custom props without a `:root` selector).
+ * @returns map of bare variable name (no leading `--`) -> value
+ */
+function parseCssVars(css) {
+    const out = {};
+    const declRegex = /--([\w-]+)\s*:\s*([^;]+);/g;
+    const collect = (text) => {
+        let m;
+        while ((m = declRegex.exec(text)) !== null) {
+            out[m[1].trim().toLowerCase()] = m[2].trim();
+        }
+    };
+    // 1) :root blocks (there can be more than one)
+    const rootRegex = /:root\s*\{([^}]*)\}/g;
+    let rootMatch;
+    let foundRoot = false;
+    while ((rootMatch = rootRegex.exec(css)) !== null) {
+        foundRoot = true;
+        declRegex.lastIndex = 0;
+        collect(rootMatch[1]);
+    }
+    // 2) Fallback: no :root vars — scan the whole CSS for custom-prop declarations
+    if (!foundRoot) {
+        declRegex.lastIndex = 0;
+        collect(css);
+    }
+    return out;
+}
+/**
+ * Parse CSS `:root` custom properties into a theme palette, falling back to a preset for any
+ * slot not present in the CSS.
+ * @param {string} css - CSS text (or any text containing `--name: value;` declarations)
+ * @param {ExtractThemeOptions} [options] - presets + which preset to fall back to
+ * @returns {ThemePalette} the resolved palette (always complete — preset fills the gaps)
+ * @example
+ * const theme = extractThemeFromCSS(':root{ --bg:#121218; --purple:#7C3AED; }')
+ * // => { bg: '121218', accent: '7C3AED', ... }
+ */
+function extractThemeFromCSS(css, options = {}) {
+    const presets = Object.assign({ dark: DARK_PRESET, light: LIGHT_PRESET }, (options.presets || {}));
+    const presetName = options.defaultPreset || 'dark';
+    const base = presets[presetName] || DARK_PRESET;
+    // Start from a complete palette (dark) then layer the chosen preset so the result is always whole
+    const theme = Object.assign(Object.assign({}, DARK_PRESET), base);
+    if (typeof css === 'string' && css.length > 0) {
+        const vars = parseCssVars(css);
+        Object.keys(vars).forEach(name => {
+            const slot = VAR_TO_SLOT[name];
+            if (!slot)
+                return;
+            const value = vars[name];
+            theme[slot] = slot === 'font' || !COLOR_SLOTS.has(slot) ? normalizeFont(value) : normalizeColor(value);
+        });
+    }
+    return theme;
+}
+
+export { extractThemeFromCSS };

package/dist/utils.js

@@ -0,0 +1,148 @@
+/* PptxGenJS 4.1.4 @ 2026-06-08T05:10:40.789Z */
+'use strict';
+
+/**
+ * PptxGenJS — Theme Extraction utility (docs/feature-theme-extraction.md)
+ *
+ * Parses CSS `:root { --var: value; }` custom properties and maps known variable-name
+ * patterns to a theme palette (background/accent/text/font + an extended colour set).
+ * Pure, dependency-free, regex-based parsing — no DOM and no browser required, so it runs
+ * in Node.js. This is an OPTIONAL utility (imported from `@jsamuel1/pptxgenjs/utils`), not
+ * part of the main `PptxGenJS` class, keeping the core library focused on OOXML generation.
+ */
+/** Built-in dark preset (matches docs/feature-theme-extraction.md). */
+const DARK_PRESET = {
+    bg: '121218',
+    bgSecondary: '1A1A24',
+    accent: '7C3AED',
+    accentSoft: 'A78BFA',
+    text: 'E4E4ED',
+    textSecondary: '8A8A9A',
+    font: 'Inter',
+    sky: '38BDF8',
+    green: '10B981',
+    orange: 'FF9900',
+    red: 'EF4444',
+};
+/** Built-in light preset. */
+const LIGHT_PRESET = {
+    bg: 'FFFFFF',
+    bgSecondary: 'F4F4F7',
+    accent: '7C3AED',
+    accentSoft: 'A78BFA',
+    text: '121218',
+    textSecondary: '5A5A6A',
+    font: 'Inter',
+    sky: '0EA5E9',
+    green: '059669',
+    orange: 'EA580C',
+    red: 'DC2626',
+};
+/**
+ * Exact CSS-variable-name → theme-slot map. Names are matched exactly (NOT by substring) so
+ * `--bg` and `--bg-card` resolve to different slots. Mirrors the table in the feature spec.
+ */
+const VAR_TO_SLOT = {
+    // bg
+    bg: 'bg', 'color-bg': 'bg', background: 'bg', 'bg-deep': 'bg',
+    // bgSecondary
+    'bg-card': 'bgSecondary', card: 'bgSecondary', 'color-bg-secondary': 'bgSecondary', 'bg-surface': 'bgSecondary',
+    // accent
+    purple: 'accent', accent: 'accent', 'color-primary': 'accent', primary: 'accent',
+    // accentSoft
+    'purple-soft': 'accentSoft', 'accent-soft': 'accentSoft', 'color-primary-light': 'accentSoft',
+    // text
+    white: 'text', text: 'text', 'color-text': 'text', foreground: 'text',
+    // textSecondary
+    gray: 'textSecondary', muted: 'textSecondary', 'color-text-secondary': 'textSecondary',
+    // sky
+    sky: 'sky', blue: 'sky', info: 'sky',
+    // green
+    green: 'green', success: 'green',
+    // orange
+    orange: 'orange', warning: 'orange',
+    // red
+    red: 'red', error: 'red', danger: 'red',
+    // font
+    font: 'font', 'font-family': 'font',
+};
+/** Slots whose value is a colour (vs. a font family) — used to decide value normalisation. */
+const COLOR_SLOTS = new Set(['bg', 'bgSecondary', 'accent', 'accentSoft', 'text', 'textSecondary', 'sky', 'green', 'orange', 'red']);
+/** Normalise a colour value to a 6-digit hex (no `#`). 3-digit hex is expanded; non-hex returned as-is. */
+function normalizeColor(raw) {
+    let v = raw.trim().replace(/^#/, '');
+    // Expand 3-digit shorthand (#abc -> AABBCC)
+    if (/^[0-9a-fA-F]{3}$/.test(v))
+        v = v.split('').map(c => c + c).join('');
+    // Uppercase 6/8-digit hex for consistency with the rest of the library
+    if (/^[0-9a-fA-F]{6}([0-9a-fA-F]{2})?$/.test(v))
+        return v.toUpperCase();
+    // rgb()/hsl()/named colours are returned trimmed but unconverted (documented limitation)
+    return v;
+}
+/** Normalise a font-family value: strip surrounding quotes and take the first family. */
+function normalizeFont(raw) {
+    const first = raw.split(',')[0].trim();
+    return first.replace(/^['"]/, '').replace(/['"]$/, '').trim();
+}
+/**
+ * Extract `--name: value;` custom-property declarations from CSS text.
+ * Prefers declarations inside `:root { … }` blocks; if none are found, falls back to scanning
+ * the entire string (covers inline/style-block custom props without a `:root` selector).
+ * @returns map of bare variable name (no leading `--`) -> value
+ */
+function parseCssVars(css) {
+    const out = {};
+    const declRegex = /--([\w-]+)\s*:\s*([^;]+);/g;
+    const collect = (text) => {
+        let m;
+        while ((m = declRegex.exec(text)) !== null) {
+            out[m[1].trim().toLowerCase()] = m[2].trim();
+        }
+    };
+    // 1) :root blocks (there can be more than one)
+    const rootRegex = /:root\s*\{([^}]*)\}/g;
+    let rootMatch;
+    let foundRoot = false;
+    while ((rootMatch = rootRegex.exec(css)) !== null) {
+        foundRoot = true;
+        declRegex.lastIndex = 0;
+        collect(rootMatch[1]);
+    }
+    // 2) Fallback: no :root vars — scan the whole CSS for custom-prop declarations
+    if (!foundRoot) {
+        declRegex.lastIndex = 0;
+        collect(css);
+    }
+    return out;
+}
+/**
+ * Parse CSS `:root` custom properties into a theme palette, falling back to a preset for any
+ * slot not present in the CSS.
+ * @param {string} css - CSS text (or any text containing `--name: value;` declarations)
+ * @param {ExtractThemeOptions} [options] - presets + which preset to fall back to
+ * @returns {ThemePalette} the resolved palette (always complete — preset fills the gaps)
+ * @example
+ * const theme = extractThemeFromCSS(':root{ --bg:#121218; --purple:#7C3AED; }')
+ * // => { bg: '121218', accent: '7C3AED', ... }
+ */
+function extractThemeFromCSS(css, options = {}) {
+    const presets = Object.assign({ dark: DARK_PRESET, light: LIGHT_PRESET }, (options.presets || {}));
+    const presetName = options.defaultPreset || 'dark';
+    const base = presets[presetName] || DARK_PRESET;
+    // Start from a complete palette (dark) then layer the chosen preset so the result is always whole
+    const theme = Object.assign(Object.assign({}, DARK_PRESET), base);
+    if (typeof css === 'string' && css.length > 0) {
+        const vars = parseCssVars(css);
+        Object.keys(vars).forEach(name => {
+            const slot = VAR_TO_SLOT[name];
+            if (!slot)
+                return;
+            const value = vars[name];
+            theme[slot] = slot === 'font' || !COLOR_SLOTS.has(slot) ? normalizeFont(value) : normalizeColor(value);
+        });
+    }
+    return theme;
+}
+
+exports.extractThemeFromCSS = extractThemeFromCSS;

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@jsamuel1/pptxgenjs",
-	"version": "4.1.2",
+	"version": "4.1.4",
 	"author": {
 		"name": "Joshua Samuel",
 		"url": "https://github.com/jsamuel1/"
@@ -15,22 +15,31 @@
 	"homepage": "https://github.com/jsamuel1/PptxGenJS#readme",
 	"license": "MIT",
 	"exports": {
-		"types": "./types/index.d.ts",
-		"import": "./dist/pptxgen.es.js",
-		"require": "./dist/pptxgen.cjs.js"
+		".": {
+			"types": "./types/index.d.ts",
+			"import": "./dist/pptxgen.es.js",
+			"require": "./dist/pptxgen.cjs.js"
+		},
+		"./utils": {
+			"types": "./types/utils.d.ts",
+			"import": "./dist/utils.es.js",
+			"require": "./dist/utils.cjs.js"
+		}
 	},
 	"main": "dist/pptxgen.cjs.js",
 	"module": "dist/pptxgen.es.js",
+	"sideEffects": false,
 	"files": [
 		"dist",
 		"types"
 	],
 	"types": "types",
 	"scripts": {
-		"build": "rollup -c --bundleConfigAsCjs",
-		"start": "gulp",
-		"ship": "gulp ship",
-		"defs": "gulp reactTestDefs",
+		"build": "rollup -c",
+		"lint": "eslint src",
+		"lint:fix": "eslint src --fix",
+		"ship": "SHIP=1 rollup -c && node tools/build/copy-demo-artifacts.mjs",
+		"prepublishOnly": "SHIP=1 rollup -c",
 		"watch": "rollup -cw",
 		"pretest": "npm run build",
 		"test": "node test/run.js && node test/run-schema.js",
@@ -41,41 +50,31 @@
 	"browser": {
 		"express": false,
 		"fs": false,
-		"https": false,
-		"image-size": false,
 		"node:fs": false,
 		"node:https": false,
 		"os": false,
 		"path": false
 	},
 	"dependencies": {
-		"@types/node": "^22.19.20",
-		"https": "^1.0.0",
-		"image-size": "^2.0.2",
 		"jszip": "^3.10.1"
 	},
 	"devDependencies": {
-		"@eslint/js": "^9.39.4",
+		"@eslint/js": "^10.0.1",
 		"@rollup/plugin-commonjs": "^29.0.3",
 		"@rollup/plugin-node-resolve": "^16.0.3",
+		"@rollup/plugin-terser": "^1.0.0",
 		"@stylistic/eslint-plugin": "^5.10.0",
+		"@types/node": "^25.9.2",
 		"@typescript-eslint/eslint-plugin": "^8.60.1",
 		"@typescript-eslint/parser": "^8.60.1",
-		"eslint": "^9.39.4",
+		"eslint": "^10.4.1",
 		"express": "^5.2.1",
-		"gulp": "^5.0.1",
-		"gulp-concat": "^2.6.1",
-		"gulp-delete-lines": "0.0.7",
-		"gulp-ignore": "^3.0.0",
-		"gulp-insert": "^0.5.0",
-		"gulp-sourcemaps": "^3.0.0",
-		"gulp-uglify": "^3.0.2",
+		"playwright": "^1.60.0",
 		"rollup": "^4.61.1",
 		"rollup-plugin-typescript2": "^0.37.0",
-		"tslib": "^2.8.0",
-		"typescript": "^5.9.3",
-		"typescript-eslint": "^8.60.1",
-		"playwright": "^1.60.0"
+		"tslib": "^2.8.1",
+		"typescript": "^6.0.3",
+		"typescript-eslint": "^8.60.1"
 	},
 	"repository": {
 		"type": "git",

package/types/index.d.ts

@@ -124,6 +124,14 @@ declare class PptxGenJS {
 	 * @deprecated use `addSlide(IAddSlideOptions)`
 	 */
 	addSlide(masterName?: string): PptxGenJS.Slide
+	/**
+	 * Compute evenly-spaced grid cell positions within a bounding area.
+	 * - Pure layout helper: returns one `{ x, y, w, h }` (inches) per item; emits no slide content.
+	 * @param {LayoutGridProps} props grid options
+	 * @returns {LayoutGridResult} array of `{ x, y, w, h }` cells (inches), one per item
+	 * @example const grid = pptx.layoutGrid({ items: 6, columns: 3, area: { x: 0.5, y: 2, w: 12, h: 4 }, gap: 0.2 })
+	 */
+	layoutGrid(props: PptxGenJS.LayoutGridProps): PptxGenJS.LayoutGridResult
 	/**
 	 * Create a custom Slide Layout in any size
 	 * @param {PresLayout} layout an object with user-defined w/h
@@ -845,6 +853,39 @@ declare namespace PptxGenJS {
 	 * @example '75%' // coordinate as percentage of slide size
 	 */
 	export type Coord = number | `${number}%`
+	export interface LayoutGridArea {
+		x: number
+		y: number
+		w: number
+		h: number
+	}
+	export interface LayoutGridProps {
+		/** Number of items (cells) to position */
+		items: number
+		/** Items per row (rows are auto-calculated) */
+		columns: number
+		/** Bounding box (inches) to lay the grid out within */
+		area: LayoutGridArea
+		/** Gap between cells (inches) - used for both axes unless overridden @default 0.2 */
+		gap?: number
+		/** Horizontal gap override (inches) */
+		gapX?: number
+		/** Vertical gap override (inches) */
+		gapY?: number
+		/** Inner padding per cell (inches) - insets each returned cell box @default 0 */
+		padding?: number
+		/** Horizontal alignment of a partial last row @default 'start' */
+		align?: 'start' | 'center' | 'stretch'
+		/** Vertical alignment (reserved) @default 'start' */
+		valign?: 'start' | 'center' | 'stretch'
+	}
+	export interface LayoutGridCell {
+		x: number
+		y: number
+		w: number
+		h: number
+	}
+	export type LayoutGridResult = LayoutGridCell[]
 	export interface PositionProps {
 		/**
 		 * Horizontal position

package/types/utils.d.ts

@@ -0,0 +1,40 @@
+// Type definitions for @jsamuel1/pptxgenjs/utils
+// Optional, format-agnostic helpers (not part of the main PptxGenJS class).
+
+/** A resolved theme palette. All colours are 6-digit hex strings (no leading `#`). */
+export interface ThemePalette {
+	/** Background colour. */
+	bg: string
+	/** Card/surface (secondary background) colour. */
+	bgSecondary: string
+	/** Primary accent colour. */
+	accent: string
+	/** Lighter accent colour. */
+	accentSoft: string
+	/** Primary text colour. */
+	text: string
+	/** Muted/secondary text colour. */
+	textSecondary: string
+	/** Font family. */
+	font: string
+	/** Extended palette — informational/utility colours. */
+	sky: string
+	green: string
+	orange: string
+	red: string
+	[key: string]: string
+}
+
+/** Options for `extractThemeFromCSS`. */
+export interface ExtractThemeOptions {
+	/** Named fallback presets; merged over the built-ins (`dark`, `light`). */
+	presets?: Record<string, Partial<ThemePalette>>
+	/** Which preset to use as the base/fallback. @default 'dark' */
+	defaultPreset?: string
+}
+
+/**
+ * Parse CSS `:root` custom properties into a theme palette, falling back to a preset for any
+ * slot not present in the CSS.
+ */
+export function extractThemeFromCSS(css: string, options?: ExtractThemeOptions): ThemePalette