canva-pptx 1.0.0

package/README.md

@@ -0,0 +1,1147 @@
+# canva-pptx
+
+**Professional Programmable PowerPoint Generator for Node.js**
+
+`canva-pptx` is a high-level, component-based engine built on top of `pptxgenjs`. It transforms PowerPoint generation from a manual coordinate-pushing task into a modular design process. It provides a robust abstraction layer, allowing developers to build complex, branded presentations using reusable components, automated layouts, and theme-driven styling.
+
+## Table of Contents
+
+1. [Installation](#installation)
+2. [Getting Started](#getting-started)
+3. [Core & Theme System](#core--theme-system)
+4. [Layout Engines](#layout-engines)
+5. [Base Components](#base-components)
+6. [Utility Components](#utility-components)
+7. [Advanced Components (Standard)](#advanced-components-standard)
+8. [Advanced Components (Enterprise)](#advanced-components-enterprise)
+9. [Visual Decorations](#visual-decorations)
+10. [System Engines & Tools](#system-engines--tools)
+
+---
+
+<a name="installation"></a>
+## Installation
+
+Install the package via NPM. This will also install the necessary peer dependencies required for PowerPoint generation.
+
+```bash
+npm install canva-pptx
+```
+
+---
+
+<a name="getting-started"></a>
+## Getting Started
+
+This example initializes the manager, creates a slide, and saves the file. It demonstrates the basic workflow: Instance -> Slide -> Component -> Output.
+
+```javascript
+const { PPTManager, addSlide, addText } = require("canva-pptx");
+
+async function main() {
+  // Initialize the core manager
+  const manager = new PPTManager();
+  const pptx = manager.getPptx();
+
+  // Create a new slide instance
+  const slide = addSlide(pptx);
+
+  // Add a simple text component with absolute positioning
+  addText(slide, "Hello World", { 
+    x: 1, y: 1, w: 8, h: 1, 
+    fontSize: 24, 
+    color: "333333",
+    align: "center",
+    bold: true
+  });
+
+  // Export the generated file to the local file system
+  await manager.save("Presentation.pptx");
+}
+
+main();
+```
+
+---
+
+<a name="core--theme-system"></a>
+## Core & Theme System
+
+The Theme System allows you to define a design token set (colors, fonts, sizes) once and apply it globally, ensuring brand consistency across hundreds of slides.
+
+### PPTManager
+
+The main wrapper class that handles the PptxGenJS instance, file saving, and global configurations.
+
+* **Usage**: `new PPTManager()`
+* **Methods**:
+  * `getPptx()`: Returns the underlying PptxGenJS instance for direct manipulation if needed.
+  * `save(filename)`: Finalizes the presentation and writes the `.pptx` file.
+  * `setAuthor(name)`: Sets the metadata for the presentation author.
+
+### registerTheme
+
+Registers a new theme configuration globally. You can define multiple themes (e.g., "dark", "corporate") and switch between them at runtime.
+
+```javascript
+registerTheme("corporate", {
+  primary: "0078D7",
+  secondary: "2B2B2B",
+  accent: "FFB900",
+  background: "FFFFFF",
+  heading: { fontFace: "Arial", bold: true, color: "0078D7", fontSize: 32 },
+  body: { fontFace: "Arial", color: "333333", fontSize: 14 },
+  spacing: 0.25 // Global padding/margin token
+});
+```
+
+### getTheme
+
+Retrieves a registered theme object. Useful for passing theme values into components dynamically to ensure they match the brand palette.
+
+```javascript
+const theme = getTheme("corporate");
+console.log(theme.primary); // Outputs: 0078D7
+// Example: Use theme color for a custom shape
+addShape(slide, "rect", { x: 1, y: 1, fill: theme.accent });
+```
+
+### applyTheme
+
+Applies the theme's background settings and default text styles to a specific slide. This automates the repetitive task of setting background colors or master slides.
+
+```javascript
+applyTheme(slide, theme); // Sets slide background color and default font families
+```
+
+---
+
+<a name="layout-engines"></a>
+## Layout Engines
+
+Layout engines calculate the X, Y, Width, and Height for elements automatically. Instead of manual math, you describe the *intent* (e.g., "split screen") and the engine does the geometry.
+
+### getHeroLayout
+
+Calculates centered coordinates for a title slide (Title and Subtitle). Perfect for opening slides or section headers.
+
+* **Options**: `align` ("center" | "left").
+
+```javascript
+const layout = getHeroLayout({ align: "center", margin: 1 });
+addText(slide, "Title", layout.title);
+addText(slide, "Subtitle", { ...layout.subtitle, color: "666666" });
+```
+
+### getSplitScreen
+
+Divides the slide into two vertical or horizontal zones. Great for comparing "Current State" vs "Future State".
+
+* **Options**: `type` ("vertical" | "horizontal"), `ratio` (0.0 - 1.0).
+
+```javascript
+const split = getSplitScreen({ type: "vertical", ratio: 0.5 });
+// Left side: Text content
+addText(slide, "Left Side Description", { ...split.left, valign: "middle" });
+// Right side: Supporting visual
+addImage(slide, "img.png", { ...split.right, sizing: { type: "contain" } });
+```
+
+### getBentoLayout
+
+Generates a modern grid of varying box sizes (bento box style). Inspired by Apple-style marketing slides.
+
+* **Options**: `feature-left`, `feature-right`, `quadrant`.
+
+```javascript
+const boxes = getBentoLayout("feature-left", { x: 0.5, y: 1, w: 9, h: 4 });
+addText(slide, "Big Box (Main Feature)", boxes[0]); // Large box on left
+addText(slide, "Small Box 1", boxes[1]); // Top-right small box
+addText(slide, "Small Box 2", boxes[2]); // Bottom-right small box
+```
+
+### getRadialLayout
+
+Arranges items in a circle around a central point. Ideal for showing ecosystem cycles or central concepts.
+
+* **Parameters**: Count (number), Options (`x`, `y`, `radius`, `itemSize`).
+
+```javascript
+const points = getRadialLayout(5, { x: 5, y: 3, radius: 2, itemSize: 1 });
+points.forEach((pos, index) => {
+  addShape(slide, "oval", { ...pos, fill: "0078D7" });
+  addText(slide, `Node ${index + 1}`, pos);
+});
+```
+
+### getMagazineLayout
+
+Creates a layout with one large focus area and a sidebar list of smaller items, resembling a magazine feature page.
+
+* **Options**: `focusPosition` ("left" | "right").
+
+```javascript
+const mag = getMagazineLayout(3, { focusPosition: "left", margin: 0.5 });
+// mag.focus: The primary content area
+addText(slide, "Feature Article", mag.focus);
+// mag.side: Array of coordinates for smaller supporting items
+mag.side.forEach((pos, i) => addText(slide, `Bullet ${i+1}`, pos));
+```
+
+### getCheckerboardLayout
+
+Creates a zig-zag pattern ideal for alternating text and image rows for high readability.
+
+```javascript
+const rows = getCheckerboardLayout(2, { y: 1, h: 4, margin: 0.2 });
+// Row 1: Text on Left, Media on Right
+addText(slide, "Text Block 1", rows[0].text);
+addImage(slide, "img1.png", rows[0].media);
+// Row 2: Media on Left, Text on Right (Auto-swapped)
+addText(slide, "Text Block 2", rows[1].text);
+```
+
+### getFilmStripLayout
+
+Creates a horizontal row of identical frames, simulating a film strip or a process gallery.
+
+```javascript
+const strips = getFilmStripLayout(4, { x: 0.5, y: 2, w: 9, h: 2, gap: 0.1 });
+strips.forEach((pos, i) => {
+  addImage(slide, `step-${i}.png`, pos);
+  addText(slide, `Step ${i+1}`, { ...pos, y: pos.y + pos.h });
+});
+```
+
+### createGrid
+
+Generates a standard uniform grid layout with customizable rows, columns, and gutters.
+
+```javascript
+const grid = createGrid({ rows: 2, cols: 2, x: 1, y: 1, w: 8, h: 4, gap: 0.2 });
+// grid[0] is top-left, grid[1] is top-right, grid[2] is bottom-left, etc.
+grid.forEach((cell, i) => addShape(slide, "rect", { ...cell, line: { color: "CCC" } }));
+```
+
+### getZPattern
+
+Generates a layout optimized for scanning content in a 'Z' shape (Top-Left, Top-Right, Bottom-Left, Bottom-Right), which follows natural eye movement.
+
+```javascript
+const zLayout = getZPattern({ margin: 0.5, topH: 1, bottomH: 1 });
+addText(slide, "Headline", zLayout.topLeft);
+addText(slide, "Logo/Icon", zLayout.topRight);
+addText(slide, "Description", zLayout.bottomLeft);
+addText(slide, "CTA Button", zLayout.bottomRight);
+```
+
+### getSidebarLayout
+
+Creates a layout with a dedicated narrow sidebar for navigation or summary and a large main content area.
+
+```javascript
+const layout = getSidebarLayout({ width: 2.5, position: "left", gap: 0.3 });
+addText(slide, "Navigation / Metadata", { ...layout.sidebar, fill: "F1F1F1" });
+addText(slide, "Main Body Content", layout.content);
+```
+
+### getGalleryLayout
+
+Creates a layout optimized for displaying multiple images in a pleasing grid with uniform spacing.
+
+```javascript
+const frames = getGalleryLayout(6, { x: 0.5, y: 1, w: 9, h: 4, cols: 3 });
+frames.forEach((frame, i) => {
+  addImage(slide, `photo-${i}.jpg`, { ...frame, sizing: { type: "cover" } });
+});
+```
+
+---
+
+<a name="base-components"></a>
+## Base Components
+
+Base components map directly to PptxGenJS primitives but are enhanced with theme awareness and simplified APIs.
+
+### addSlide
+
+Creates and returns a new slide object within the presentation instance.
+
+```javascript
+const slide = addSlide(pptx);
+// You can also pass a master slide name
+const masterSlide = addSlide(pptx, { masterName: "TITLE_SLIDE" });
+```
+
+### addText
+
+Renders text. Supports all standard formatting options including alignment, bullets, and shadow.
+
+```javascript
+addText(slide, "Hello World", { 
+  x: 1, y: 1, w: 5, h: 1, 
+  fontSize: 18, 
+  color: "333333",
+  align: "center",
+  valign: "middle"
+});
+```
+
+### addImage
+
+Renders an image from a local path, base64 string, or URL.
+
+```javascript
+addImage(slide, "./photo.jpg", { 
+  x: 1, y: 1, w: 4, h: 3, 
+  sizing: { type: "cover", w: 4, h: 3 },
+  rounding: true // Adds rounded corners
+});
+```
+
+### addShape
+
+Renders a geometric shape (rect, oval, line, etc.). Useful for background accents and diagrams.
+
+```javascript
+addShape(slide, "rect", { 
+  x: 1, y: 1, w: 2, h: 2, 
+  fill: { color: "FF0000", transparency: 50 },
+  line: { color: "000000", width: 2 }
+});
+```
+
+### addTable
+
+Renders a data table with automatic row/column styling based on the current theme.
+
+```javascript
+addTable(slide, [
+  ["Header 1", "Header 2"], 
+  ["Row 1 Col 1", "Row 1 Col 2"]
+], { 
+  x: 1, y: 1, w: 8,
+  colW: [4, 4],
+  border: { type: "solid", color: "CCCCCC" }
+});
+```
+
+### addChart
+
+Renders a chart (bar, pie, line, scatter). Wraps the complex PptxGenJS chart API into a cleaner interface.
+
+```javascript
+addChart(slide, "bar", [
+  { name: "Projected", values: [10, 20, 30] },
+  { name: "Actual", values: [12, 18, 29] }
+], { 
+  x: 1, y: 1, w: 6, h: 3,
+  showLegend: true,
+  chartColors: ["0078D7", "FFB900"]
+});
+```
+
+### addCard
+
+Renders a content card with a Title and Body text inside a stylized container (box with shadow/border).
+
+```javascript
+addCard(slide, {
+  title: "Project Milestone",
+  body: "The project has reached 50% completion as of October.",
+  x: 1, y: 1, w: 3, h: 2,
+  theme: "light",
+  shadow: true
+});
+```
+
+### addLink
+
+Adds a hyperlink to text or shapes, allowing for interactive presentations or external references.
+
+```javascript
+addLink(slide, "Visit Documentation", "https://github.com/fairoz-539/canva-pptx", { 
+  x: 1, y: 1, 
+  fontSize: 12, 
+  color: "0000FF", 
+  underline: true 
+});
+```
+
+---
+
+<a name="utility-components"></a>
+## Utility Components
+
+### addBrowserWindow
+
+Wraps content or an image in a container that resembles a web browser frame. Perfect for software demos and UI/UX presentations.
+
+```javascript
+addBrowserWindow(slide, {
+  x: 1, y: 1, w: 8, h: 5,
+  url: "https://mysite.com/dashboard",
+  imagePath: "./screenshot.png",
+  browserColor: "E0E0E0"
+});
+```
+
+### addSocialBar
+
+Renders a row of social media icons (LinkedIn, Twitter, etc.). Useful for contact or "About Us" slides.
+
+```javascript
+addSocialBar(slide, [
+  { type: "linkedin", url: "https://linkedin.com/in/fairoz" },
+  { type: "twitter", url: "https://twitter.com/fairoz" },
+  { type: "github", url: "https://github.com/fairoz-539" }
+], { x: 1, y: 5, iconSize: 0.4 });
+```
+
+### addCodeDiff
+
+Renders a code block that highlights additions (green) and deletions (red). Essential for technical reviews and developer updates.
+
+```javascript
+const diff = `- var x = 1;\n+ const x = 2;`;
+addCodeDiff(slide, diff, { 
+  x: 1, y: 1, w: 6, h: 4, 
+  fontSize: 10,
+  title: "refactor(core): update variable declaration"
+});
+```
+
+---
+
+<a name="advanced-components-standard"></a>
+## Advanced Components (Standard)
+
+### addProgressBar
+
+Visualizes a percentage value as a horizontal bar. Useful for status reports and project tracking.
+
+```javascript
+addProgressBar(slide, 75, { 
+  x: 1, y: 1, w: 5, h: 0.3, 
+  color: "007AFF", 
+  trackColor: "E5E5EA",
+  label: "Overall Progress: 75%" 
+});
+```
+
+### addStatMetric
+
+Displays a large number with a descriptive label below it. Ideal for KPIs, financial results, and impact metrics.
+
+```javascript
+addStatMetric(slide, { 
+  value: "$10M", 
+  label: "Annual Revenue", 
+  x: 1, y: 1, w: 3, h: 2,
+  color: "28A745"
+});
+```
+
+### addBadge
+
+Renders a small pill-shaped tag with text. Used for status indicators (e.g., "New", "Stable", "In Progress").
+
+```javascript
+addBadge(slide, "BETA", { 
+  x: 1, y: 1, 
+  color: "FFFFFF", 
+  backgroundColor: "6F42C1",
+  fontSize: 10 
+});
+```
+
+### addCodeBlock
+
+Renders a standard block of code with a dark background and syntax-like coloring for readability.
+
+```javascript
+addCodeBlock(slide, "function init() {\n  console.log('App Started');\n}", { 
+  x: 1, y: 1, w: 6, h: 3,
+  language: "javascript" 
+});
+```
+
+### addTimeline
+
+Renders a linear timeline with milestones. Perfect for roadmaps and historical overviews.
+
+```javascript
+addTimeline(slide, [
+  { date: "Q1 2023", title: "Inception", desc: "Project Kickoff" }, 
+  { date: "Q3 2023", title: "Beta", desc: "First release" },
+  { date: "Q1 2024", title: "Launch", desc: "Global rollout" }
+], { x: 1, y: 2, w: 8, color: "0078D7" });
+```
+
+### addAvatarGroup
+
+Renders overlapping circles with initials or images to represent a team or group of contributors.
+
+```javascript
+addAvatarGroup(slide, [
+  { initials: "FA", color: "FF5733" }, 
+  { initials: "JD", color: "33FF57" },
+  { initials: "SK", color: "3357FF" }
+], { x: 1, y: 1, size: 0.6 });
+```
+
+### addTestimonialCard
+
+Renders a quote with author attribution, styling, and optional profile image.
+
+```javascript
+addTestimonialCard(slide, "The best automation tool we've used!", "Jane Doe, CTO", { 
+  x: 1, y: 1, w: 5, h: 2.5,
+  quoteColor: "666666"
+});
+```
+
+### addAlertBox
+
+Renders a colored box for warnings, errors, or success messages.
+
+```javascript
+addAlertBox(slide, "Session Timeout: Please log in again.", "warning", { 
+  x: 1, y: 1, w: 6,
+  showIcon: true 
+});
+```
+
+### addIconList
+
+Renders a vertical list where each item has a custom bullet icon instead of standard dots.
+
+```javascript
+addIconList(slide, ["Secure Encryption", "Cloud Sync", "Offline Mode"], { 
+  x: 1, y: 1, w: 4, 
+  icon: "check", 
+  iconColor: "28A745" 
+});
+```
+
+### addPricingColumn
+
+Renders a pricing tier card (e.g., Basic, Pro) with a price, features, and a CTA area.
+
+```javascript
+addPricingColumn(slide, { 
+  name: "Enterprise", 
+  price: "$99/mo", 
+  features: ["Unlimited Users", "24/7 Support", "Custom API"],
+  highlight: true 
+}, { x: 1, y: 1, w: 2.5, h: 4.5 });
+```
+
+### addStepProcess
+
+Visualizes a linear step-by-step process with connecting arrows or lines.
+
+```javascript
+addStepProcess(slide, ["Design", "Develop", "Test", "Deploy"], { 
+  x: 1, y: 2, w: 8, 
+  activeStep: 2 // Highlights 'Develop'
+});
+```
+
+### addComparisonTable
+
+Renders a feature comparison table (e.g., Free vs Paid) with checkmarks and cross symbols.
+
+```javascript
+addComparisonTable(slide, { 
+  headers: ["Features", "Free", "Premium"], 
+  rows: [
+    ["HD Video", false, true],
+    ["Cloud Storage", "1GB", "Unlimited"]
+  ] 
+}, { x: 1, y: 1, w: 7 });
+```
+
+### addRatingStars
+
+Renders a star rating (0-5) visually using vector shapes. Supports partial stars (e.g., 4.5).
+
+```javascript
+addRatingStars(slide, 4.7, { 
+  x: 1, y: 1, 
+  size: 0.4, 
+  color: "FFD700",
+  totalStars: 5 
+});
+```
+
+### addBreadcrumbNav
+
+Renders a navigation path (Home > Section > Page) to provide context in large presentations.
+
+```javascript
+addBreadcrumbNav(slide, ["Settings", "Security", "2FA Setup"], { 
+  x: 0.5, y: 0.5,
+  activeColor: "0078D7" 
+});
+```
+
+### addTagCloud
+
+Renders a cluster of keywords or tags with randomized or weighted sizes.
+
+```javascript
+addTagCloud(slide, ["React", "Node.js", "TypeScript", "PowerPoint", "Automation"], { 
+  x: 1, y: 1, w: 6, 
+  colors: ["333", "666", "999"] 
+});
+```
+
+### addKanbanColumn
+
+Renders a task column (like Trello/Jira) with individual cards nested inside.
+
+```javascript
+addKanbanColumn(slide, "In Progress", [
+  { title: "Fix Auth Bug", priority: "High" },
+  { title: "Update Docs", priority: "Low" }
+], { x: 1, y: 1, w: 2.8, h: 5 });
+```
+
+### addCallToAction
+
+Renders a prominent button-style link to prompt user interaction or external navigation.
+
+```javascript
+addCallToAction(slide, "Get Started Now", "https://example.com/signup", { 
+  x: 4, y: 3, w: 2.5,
+  backgroundColor: "0078D7",
+  color: "FFFFFF"
+});
+```
+
+---
+
+<a name="advanced-components-enterprise"></a>
+## Advanced Components (Enterprise)
+
+### addFeatureGrid
+
+Renders a grid of small blocks, each containing an icon, title, and description. Ideal for product feature pages.
+
+```javascript
+addFeatureGrid(slide, [
+  { title: "Real-time", desc: "Collaborate instantly.", icon: "clock" },
+  { title: "Secure", desc: "End-to-end encryption.", icon: "lock" }
+], { x: 1, y: 1, w: 8, columns: 2 });
+```
+
+### addTeamMemberProfile
+
+Renders a detailed profile card for a team member with a bio, role, and contact info.
+
+```javascript
+addTeamMemberProfile(slide, { 
+  name: "Jane Smith", 
+  role: "Lead Engineer", 
+  bio: "Expert in Node.js and cloud architecture.",
+  image: "jane.jpg"
+}, { x: 1, y: 1, w: 3 });
+```
+
+### addSWOTMatrix
+
+Renders a 2x2 grid for Strengths, Weaknesses, Opportunities, and Threats analysis.
+
+```javascript
+addSWOTMatrix(slide, { 
+  strengths: ["Strong Brand", "Patented Tech"], 
+  weaknesses: ["High Costs"], 
+  opportunities: ["Market Expansion"], 
+  threats: ["New Regulations"] 
+}, { x: 1, y: 1, w: 8, h: 4.5 });
+```
+
+### addProcessCycle
+
+Renders a circular flow of steps, useful for continuous improvement (PDCA) or lifecycle cycles.
+
+```javascript
+addProcessCycle(slide, ["Discovery", "Definition", "Design", "Delivery"], { 
+  x: 4, y: 3, 
+  radius: 2.2, 
+  arrowStyle: "curved" 
+});
+```
+
+### addFunnelDiagram
+
+Renders a sales or marketing funnel visualization with widening stages.
+
+```javascript
+addFunnelDiagram(slide, [
+  { label: "Awareness", value: "5000" }, 
+  { label: "Consideration", value: "1200" },
+  { label: "Conversion", value: "300" }
+], { x: 3, y: 1, w: 4, h: 4, fill: ["D1E9FF", "74B9FF", "0984E3"] });
+```
+
+### addPyramidHierarchy
+
+Renders a pyramid divided into levels to show organizational or conceptual hierarchy.
+
+```javascript
+addPyramidHierarchy(slide, ["Executive", "Management", "Operations"], { 
+  x: 3, y: 1, w: 4, h: 4,
+  direction: "up"
+});
+```
+
+### addDeviceMockup
+
+Renders a device frame (phone, tablet, or laptop) with a custom image inside the screen area.
+
+```javascript
+addDeviceMockup(slide, "laptop", "dashboard-preview.png", { 
+  x: 2, y: 1, h: 4,
+  frameColor: "333333" 
+});
+```
+
+### addAccordionList
+
+Renders a list that looks like an open/closed accordion menu, useful for FAQs or technical specs.
+
+```javascript
+addAccordionList(slide, [
+  { title: "How it works?", content: "It uses PptxGenJS under the hood.", open: true },
+  { title: "Is it free?", content: "Yes, licensed under MIT." }
+], { x: 1, y: 1, w: 6 });
+```
+
+### addTrafficLight
+
+Renders a Red/Yellow/Green status indicator, perfect for project health dashboards.
+
+```javascript
+addTrafficLight(slide, "yellow", { 
+  x: 1, y: 1, 
+  label: "At Risk",
+  orientation: "horizontal" 
+});
+```
+
+### addVennDiagram
+
+Renders overlapping circles (2 or 3 sets) to show relationships and commonalities.
+
+```javascript
+addVennDiagram(slide, ["Sales", "Marketing", "Product"], { 
+  x: 3, y: 2, 
+  radius: 1.5,
+  opacity: 0.6 
+});
+```
+
+### addOrgChart
+
+Renders a hierarchical tree (Parent -> Children) automatically. Handles line routing and node spacing.
+
+```javascript
+addOrgChart(slide, { 
+  name: "CEO", 
+  children: [
+    { name: "VP Sales", children: [{ name: "AE" }] },
+    { name: "VP Eng", children: [{ name: "Staff Eng" }] }
+  ] 
+}, { x: 1, y: 1, w: 8, h: 4 });
+```
+
+### addCalendarGrid
+
+Renders a monthly calendar view with highlighted events and color-coded days.
+
+```javascript
+addCalendarGrid(slide, "December 2025", [
+  { day: 25, title: "Holiday", color: "FF0000" },
+  { day: 31, title: "NYE Party", color: "00FF00" }
+], { x: 1, y: 1, w: 7, h: 5 });
+```
+
+### addGanttChart
+
+Renders a project timeline with horizontal bars indicating duration, dependencies, and progress.
+
+```javascript
+addGanttChart(slide, [
+  { name: "Phase A", start: 0, end: 0.4, progress: 100 },
+  { name: "Phase B", start: 0.4, end: 0.9, progress: 20 }
+], { x: 1, y: 1, w: 8, h: 4 });
+```
+
+### addPersonaCard
+
+Renders a UX persona profile including a photo, goals, frustrations, and personality traits.
+
+```javascript
+addPersonaCard(slide, { 
+  name: "Alex the Admin", 
+  role: "IT Manager", 
+  goals: ["Efficiency", "Security"],
+  frustrations: ["Slow legacy tools"]
+}, { x: 1, y: 1, w: 4.5, h: 5 });
+```
+
+### addMatrixGrid
+
+Renders a 2x2 consulting matrix (e.g., Eisenhower Matrix, Impact/Effort) with labeled axes.
+
+```javascript
+addMatrixGrid(slide, ["Do First", "Schedule", "Delegate", "Eliminate"], { 
+  x: 2, y: 1, w: 6, h: 4, 
+  xAxis: "Urgency", 
+  yAxis: "Importance" 
+});
+```
+
+### addMindMap
+
+Renders a central node with branching child nodes in a spider-diagram style.
+
+```javascript
+addMindMap(slide, "New Product", ["Market Research", "Design", "Pricing", "Launch"], { 
+  x: 2, y: 1, w: 6, h: 4,
+  nodeColor: "E1F5FE"
+});
+```
+
+### addInvoiceTable
+
+Renders a formal financial table with itemized lines and a calculated total/tax row.
+
+```javascript
+addInvoiceTable(slide, [
+  { desc: "Consulting", qty: 10, rate: 150 },
+  { desc: "Design", qty: 5, rate: 100 }
+], { x: 1, y: 1, w: 7, currency: "$" });
+```
+
+### addCertificateFrame
+
+Renders a decorative border, formal typography, and seal area for awards or recognition.
+
+```javascript
+addCertificateFrame(slide, "John Smith", "Outstanding Achievement in Sales 2025", {
+  date: "2026-01-01",
+  signatureName: "CEO Name"
+});
+```
+
+### addSaaSFeatureBlock
+
+Renders a side-by-side Image + Text layout block for modern feature explanations.
+
+```javascript
+addSaaSFeatureBlock(slide, "Cloud Sync", "Your data is always available.", "cloud.png", { 
+  x: 1, y: 1, 
+  imageSide: "right" 
+});
+```
+
+### addWinLossChart
+
+Renders a diverging bar chart showing positive vs negative values, ideal for quarterly performance.
+
+```javascript
+addWinLossChart(slide, [
+  { label: "Jan", value: 15 }, 
+  { label: "Feb", value: -10 },
+  { label: "Mar", value: 25 }
+], { x: 1, y: 1, w: 7, h: 3 });
+```
+
+---
+
+<a name="visual-decorations"></a>
+## Visual Decorations
+
+### addOrganicBlob
+
+Adds fluid, organic SVG-style shapes to the background to break the "square" feel of PowerPoint.
+
+```javascript
+addOrganicBlob(slide, { 
+  x: -1, y: -1, 
+  size: 4,
+  color: "E3F2FD", 
+  opacity: 0.4,
+  seed: 123 // Ensures consistent shape generation
+});
+```
+
+### addWaveDecoration
+
+Adds a wave graphic at the bottom or top of the slide for a modern web-design aesthetic.
+
+```javascript
+addWaveDecoration(slide, { 
+  position: "bottom", 
+  color: "007AFF", 
+  height: 1.5,
+  frequency: 2 
+});
+```
+
+### addDotPattern
+
+Adds a grid of subtle dots to provide background texture and professional depth.
+
+```javascript
+addDotPattern(slide, { 
+  x: 0, y: 0, w: 10, h: 5.6, 
+  color: "EEEEEE", 
+  spacing: 0.2, 
+  dotSize: 0.02 
+});
+```
+
+### addBrushStroke
+
+Adds a paint-brush effect behind text or images to highlight key sections with an "artistic" touch.
+
+```javascript
+addBrushStroke(slide, { 
+  x: 1, y: 1, w: 4, h: 1.2, 
+  color: "FFF9C4", 
+  angle: -2 
+});
+```
+
+### addGeometricConfetti
+
+Scatters small geometric shapes (triangles, circles, squares) for a celebratory or high-energy look.
+
+```javascript
+addGeometricConfetti(slide, { 
+  count: 40, 
+  colors: ["#FF5252", "#FFEB3B", "#2196F3"],
+  spread: "full" 
+});
+```
+
+### addGradientMesh
+
+Adds a blurry, multi-color gradient background (mesh gradient) for a premium, high-end feel.
+
+```javascript
+addGradientMesh(slide, { 
+  colors: ["FF8A80", "FFD180", "80D8FF"],
+  steps: 10 
+});
+```
+
+### addSquiggleLine
+
+Adds a hand-drawn wavy line separator to add personality and a human touch to the design.
+
+```javascript
+addSquiggleLine(slide, { 
+  x: 1, y: 2.5, w: 8, 
+  color: "333333", 
+  weight: 2 
+});
+```
+
+### addCornerAccent
+
+Adds a decorative geometric shape to a specific corner of the slide to frame the content.
+
+```javascript
+addCornerAccent(slide, "top-right", { 
+  color: "0078D7", 
+  size: 1.5,
+  style: "triangle" 
+});
+```
+
+---
+
+<a name="system-engines--tools"></a>
+## System Engines & Tools
+
+### renderMarkdown
+
+Parses a Markdown string and generates slides automatically. It maps `#` to new slides, `##` to headers, and `-` to bullet points.
+
+```javascript
+const md = `
+# Welcome Slide
+This is an automated presentation.
+
+# Feature List
+- Automatic Generation
+- Theme Support
+- Easy API
+`;
+renderMarkdown(manager, md, { theme: "corporate" });
+```
+
+### addTableOfContents / addToTOC
+
+Builds an agenda slide dynamically. You call `addToTOC` during the generation process, and then `addTableOfContents` generates the summary slide.
+
+```javascript
+addToTOC("Introduction", 1);
+addToTOC("Market Analysis", 5);
+// ... later
+addTableOfContents(manager, { 
+  title: "Agenda", 
+  columns: 2, 
+  showPageNumbers: true 
+});
+```
+
+### applyMaster
+
+Applies a global master overlay (footer, logo, page numbers, confidentiality watermarks) to a specific slide.
+
+```javascript
+applyMaster(slide, { 
+  footer: "© 2026 Canva-PPTX Inc.", 
+  showPageNumber: true,
+  logoPath: "./logo.png" 
+});
+```
+
+### addSmartIcon
+
+Renders an icon from integrated libraries (like FontAwesome or Lucide) by name.
+
+```javascript
+addSmartIcon(slide, "home", { 
+  x: 1, y: 1, 
+  size: 0.5, 
+  color: "333333" 
+});
+```
+
+### addSmartText
+
+Renders text with intelligent resizing logic—it automatically shrinks the font size if the text exceeds the container height.
+
+```javascript
+addSmartText(slide, "This is a very long title that might overflow the box...", { 
+  x: 1, y: 1, w: 4, h: 1, 
+  minFontSize: 10, 
+  maxFontSize: 24 
+});
+```
+
+### jsonToTableData / csvToTableData
+
+Converts raw data formats (JSON/CSV) into the specific 2D array format required by PptxGenJS tables.
+
+```javascript
+const tableData = csvToTableData("ID,Name,Status\n1,App,Active\n2,API,Pending");
+addTable(slide, tableData, { x: 1, y: 1 });
+```
+
+### jsonToChartData
+
+Converts raw JSON arrays into the complex data series format required for PptxGenJS charts.
+
+```javascript
+const raw = [{ month: "Jan", val: 10 }, { month: "Feb", val: 20 }];
+const chartData = jsonToChartData(raw, "month", "val");
+addChart(slide, "line", chartData, { x: 1, y: 1 });
+```
+
+### animate
+
+Applies entrance or exit animations (Fade, Fly In, Zoom) to slide elements for dynamic presentations.
+
+```javascript
+const text = addText(slide, "Animate Me", { x: 1, y: 1 });
+animate(slide, text, "fadeIn", { duration: 500, delay: 200 });
+```
+
+### debugSlide
+
+Draws a visible coordinate grid (inches) and borders on all elements to help you align layouts during development.
+
+```javascript
+debugSlide(slide, { 
+  showGrid: true, 
+  gridColor: "FF0000", 
+  opacity: 0.1 
+});
+```
+
+### addSpeakerNotes
+
+Adds invisible text notes to the slide that are only visible in Presenter Mode.
+
+```javascript
+addSpeakerNotes(slide, "Key talking point: Remind the audience about the 20% growth.");
+```
+
+### generateTheme
+
+Helper to generate a full color palette (light, dark, muted, secondary) from a single base brand color using HSL math.
+
+```javascript
+const palette = generateTheme("007AFF");
+// Result: { main: "007AFF", light: "E3F2FD", dark: "004A99", ... }
+```
+
+### addWatermark
+
+Stamps text across the slide background at an angle (e.g., "DRAFT", "CONFIDENTIAL", "INTERNAL ONLY").
+
+```javascript
+addWatermark(slide, "DRAFT", { 
+  color: "CCCCCC", 
+  opacity: 0.15, 
+  fontSize: 100,
+  angle: 45 
+});
+```
+
+### addSectionDivider
+
+Automatically creates a standalone slide acting as a chapter break with a large centered title and contrasting background.
+
+```javascript
+addSectionDivider(manager, "Chapter 1", "The Foundation of Our Strategy", {
+  theme: "dark"
+});
+```
+
+### checkContrast
+
+Calculates the contrast ratio between two hex colors and logs a warning to the console if the text is not readable per WCAG accessibility standards.
+
+```javascript
+checkContrast("Headline", "FFFFFF", "0078D7"); // Returns contrast ratio and pass/fail
+```
+
+---
+
+## License
+
+This project is licensed under the **MIT License**. You are free to use, modify, and distribute this software as permitted by the license terms.
+
+## Support & Contributing
+
+We welcome contributions to `canva-pptx`!
+
+* **Report Bugs**: Please use the GitHub Issues tab to report bugs or request features.
+* **Submit Pull Requests**: Fork the repository and submit a PR for review.
+* **Contact**: For enterprise support or specific feature requests, please contact the author via GitHub.
+
+## Author
+
+**Fairoz Ahmed** GitHub: [https://github.com/fairoz-539](https://github.com/fairoz-539)
+
+---
+*Built with logic, designed for business.*