ptxiagram 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 hiio420official
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,45 @@
+# ptxiagram
+
+**Generate architecture and workflow diagrams as native, editable PowerPoint shapes — not an embedded image.**
+
+ptxiagram is an agent skill for Claude (and a standalone CLI/library) that turns a plain-English description of a system or process into a `.pptx` slide built from real PowerPoint shapes: rectangles, cylinders, clouds, connectors, text boxes. Anyone can open the result in PowerPoint — or Hancom 한쇼 — and click a box to change its color, text, or position, because it *is* a box, not a picture of one.
+
+- **Native shapes, not a picture** — every box and arrow is a real PPTX shape, editable after generation
+- **Two diagram types today** — `workflow` (swimlanes, happy-path flows) and `architecture` (free-placed components, trust boundaries, hub-and-spoke)
+- **A validator that catches real layout bugs before rendering** — node overlap, labels wider than their shape, and connectors that cut through an unrelated node all fail loudly with a specific fix, instead of shipping a broken-looking slide
+- **Ships a Hancom Office compatibility fix** — every generated file is post-processed to strip a documented PptxGenJS defect that PowerPoint silently repairs but Hancom's 한쇼 flags as a corrupted document (see below)
+- **Route presets instead of hand-computed coordinates** — `straight`, `drop`, `elbow-right`, `arc-over-top` cover swimlane transitions, hub-and-spoke fan-out, and routing around a boundary box
+
+## Install
+
+As a Claude Skill:
+
+```bash
+npx skills add hiio420official/ptxiagram -g
+```
+
+As a CLI / library:
+
+```bash
+npm install -g ptxiagram
+ptxiagram doctor
+```
+
+## Quick start
+
+```bash
+ptxiagram render workflow examples/onboarding.workflow.json out.pptx
+ptxiagram check out.pptx
+```
+
+`render` validates the input (schema + layout) before writing anything, and always repairs the output for Hancom Office compatibility. `check` confirms the repair took, dumps every embedded text run for a spelling/content spot-check, and — if LibreOffice is installed — writes a PNG preview for a quick visual check.
+
+See [`ptxiagram/SKILL.md`](ptxiagram/SKILL.md) for the full JSON shape of both diagram types, the node-type → shape/color mapping, and the route presets.
+
+## Why every file gets repaired
+
+PptxGenJS ships a notes-slide scaffold (6 placeholder shapes) on every file it generates, whether or not notes are used. PowerPoint silently repairs this on open. Hancom Office's 한쇼 does not — it shows a "damaged document" dialog instead, on every file, every time. `lib/repair-pptx.mjs` strips the notes infrastructure and the always-empty `charts`/`embeddings` scaffolding before the file is written. Source: [gitbrent/PptxGenJS#1449](https://github.com/gitbrent/PptxGenJS/issues/1449).
+
+## License
+
+MIT

package/SKILL.md

@@ -0,0 +1,175 @@
+---
+name: ptxiagram
+description: Create architecture and workflow diagrams as native, editable PowerPoint shapes (real rectangles, connectors, and text boxes a user can click and restyle in PowerPoint or Hancom 한쇼) instead of an embedded image. Accepts a plain-language description, turns it into a small JSON file, and renders it with pptxgenjs. Use when the user asks for a diagram, architecture drawing, or process flow that needs to end up inside a .pptx deck or a Korean-office-suite-compatible presentation - not when they just want a standalone image or an HTML/web diagram (use an SVG-based diagram tool for that instead).
+license: MIT
+metadata:
+  version: "0.1.0"
+  status: prototype
+  based_on: "gitbrent/PptxGenJS (MIT)"
+---
+
+# ptxiagram
+
+Turns a plain-language description of a system or process into a single
+`.pptx` slide built from **native PowerPoint shapes** — real rectangles,
+cylinders, connectors, and text boxes — not a picture pasted into a slide.
+Anyone can then click a box in PowerPoint (or Hancom 한쇼) and change its
+color, text, or position directly.
+
+This is the thing to reach for when the deliverable is a slide deck. If the
+deliverable is a standalone image, an HTML page, or a README diagram, an
+SVG/HTML-based diagram tool is the better fit — this skill's whole reason to
+exist is that the output has to remain editable inside PowerPoint.
+
+## Install
+
+```bash
+npx skills add hiio420official/ptxiagram -g
+```
+
+or as an npm package (CLI + library):
+
+```bash
+npm install -g ptxiagram
+ptxiagram doctor
+```
+
+## Setup
+
+```bash
+node bin/cli.mjs doctor
+```
+
+Confirms pptxgenjs, jszip, and ajv are present, and reports whether
+LibreOffice is installed (optional — enables the `check` command's PNG
+preview for visual QA; without it you still get full schema/layout
+validation and the embedded-text dump, just no rendered preview image).
+
+## Choosing a diagram type
+
+| Type | Use for | Schema |
+|------|---------|--------|
+| `workflow` | Cross-team processes, approval chains, anything with swimlanes and a happy path | `schemas/workflow.schema.json` |
+| `architecture` | System components, services, datastores, trust boundaries, hub-and-spoke integrations | `schemas/architecture.schema.json` |
+
+## The loop
+
+1. **Read the matching example** before writing JSON by hand — copy its
+   shape, don't guess the field names:
+   - `examples/onboarding.workflow.json`
+   - `examples/order-processing.architecture.json`
+2. Write `<name>.<type>.json`.
+3. Render:
+   ```bash
+   node bin/cli.mjs render workflow <input>.json <output>.pptx
+   ```
+   This validates the JSON (schema + layout) and **always** repairs the
+   output for Hancom Office compatibility before writing the final file —
+   see "Why every file gets repaired" below. If layout validation fails, the
+   error names exactly what's wrong (which nodes overlap, which label is
+   wider than its shape, which edge cuts through an unrelated node) — fix
+   the JSON and re-run; don't hand-edit the generated pptx.
+4. Spot-check before handing it over:
+   ```bash
+   node bin/cli.mjs check <output>.pptx
+   ```
+   Confirms the Hancom repair actually took (no leftover notes/chart
+   scaffolding), dumps every embedded text run so you can read the real
+   strings back (LibreOffice's PNG rendering has shown font-substitution
+   artifacts that don't reflect the actual file — trust this text dump over
+   the preview image for spelling/content, and trust the PNG for layout).
+   If LibreOffice is installed, this also writes a PNG preview next to the
+   file so you can visually confirm layout before delivering it.
+
+## Workflow JSON shape
+
+```json
+{
+  "schema_version": 1,
+  "diagram_type": "workflow",
+  "meta": { "title": "...", "subtitle": "...", "output": "out.pptx" },
+  "lanes": [{ "id": "hr", "label": "HR팀" }],
+  "nodes": [
+    { "id": "apply", "lane": "hr", "col": 0, "type": "neutral", "label": "...", "sublabel": "..." }
+  ],
+  "edges": [
+    { "from": "apply", "to": "request", "variant": "default", "route": "straight" }
+  ],
+  "cards": []
+}
+```
+
+**Layout budget**: lanes stack vertically and are auto-positioned (default
+height 1.75in). Each lane has 6 column slots (`col` 0–5, each 2.0in wide);
+a node claims exactly one slot, so default-width nodes can never overlap —
+omit `col` and the renderer assigns the next free slot in that lane in JSON
+order. Default node size is 1.8×0.95in.
+
+## Architecture JSON shape
+
+```json
+{
+  "schema_version": 1,
+  "diagram_type": "architecture",
+  "meta": { "title": "...", "output": "out.pptx" },
+  "components": [
+    { "id": "api", "type": "backend", "label": "API 서버", "pos": [5.9, 3.1], "size": [1.85, 1.1] }
+  ],
+  "boundaries": [{ "label": "사내 인프라 (VPC)", "wraps": ["api", "db"] }],
+  "connections": [
+    { "from": "api", "to": "db", "variant": "default", "route": "elbow-right", "label": "주문 저장" }
+  ],
+  "cards": []
+}
+```
+
+**Layout budget**: free placement in inches on a 13.33×7.5in (16:9) slide.
+`boundaries[].wraps` takes component ids, not coordinates — the renderer
+computes a padded frame around them, so never hand-compute a boundary box.
+
+## Node types
+
+`client` `frontend` `neutral` `backend` `database` `cache` `queue`
+`external` `security` `decision` — each maps to a shape preset (ellipse,
+rect, roundRect, can/cylinder, hexagon, cube, cloud, diamond) and a color
+pair. Pick by role, not by desired color.
+
+## Route presets
+
+Connectors never need hand-computed coordinates — pick the preset that
+matches the story:
+
+- `straight` — adjacent nodes, same row. One segment.
+- `drop` — top-to-bottom flow (cross-lane, or stacked components). Straight
+  if the two nodes share an x-center, otherwise a vertical→horizontal→vertical
+  jog through the midpoint (`bias` picks where, default 0.5).
+- `elbow-right` — hub-and-spoke fan-out where targets sit at different row
+  heights. Straight if the two nodes share a y-center, otherwise a
+  horizontal→vertical→horizontal jog.
+- `arc-over-top` — routes above a shared clearance line (`clearY`, required)
+  instead of cutting through whatever sits between two nodes. Use this for
+  a connection that has to reach past a boundary box or a row of components
+  a straight/elbow line would otherwise cross.
+
+`node overlaps`, `label wider than its shape`, and `edge crosses an
+unrelated node` are exactly the failure modes `render`/`validate` catch
+before a file is written — if you hit one, change the route or `bias`
+rather than fighting raw coordinates.
+
+## Why every file gets repaired
+
+pptxgenjs ships a notes-slide scaffold (6 placeholder shapes) on every
+file it generates, regardless of whether notes are used. PowerPoint
+silently repairs this on open; Hancom Office's 한쇼 does not — it shows a
+"damaged document" dialog instead. `lib/repair-pptx.mjs` strips the notes
+infrastructure and the always-empty `charts`/`embeddings` scaffolding
+after generation and before the file is written. Every `render` call does
+this automatically; `check` verifies it actually happened. Source:
+[gitbrent/PptxGenJS#1449](https://github.com/gitbrent/PptxGenJS/issues/1449).
+
+## What's not built yet
+
+- `sequence`, `dataflow`, `lifecycle` diagram types (only `workflow` and
+  `architecture` exist so far)
+- No CJK exact-metrics font measurement — the label-width check is a
+  conservative estimate, not real glyph widths

package/bin/cli.mjs

@@ -0,0 +1,159 @@
+#!/usr/bin/env node
+import fs from "node:fs/promises";
+import { existsSync } from "node:fs";
+import path from "node:path";
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+import JSZip from "jszip";
+import { renderWorkflow } from "../renderers/workflow/render-workflow.mjs";
+import { renderArchitecture } from "../renderers/architecture/render-architecture.mjs";
+import { validateAll } from "../lib/validate.mjs";
+
+const execFileAsync = promisify(execFile);
+
+const RENDERERS = { workflow: renderWorkflow, architecture: renderArchitecture };
+
+function usage() {
+  console.log(`Usage:
+  cli render <type> <input.json> [output.pptx]
+  cli validate <type> <input.json> [--json]
+  cli check <output.pptx>
+  cli doctor
+
+Types: workflow, architecture`);
+}
+
+async function cmdRender(type, inputPath, outputPath) {
+  const renderFn = RENDERERS[type];
+  if (!renderFn) throw new Error(`Unknown type "${type}". Expected one of: ${Object.keys(RENDERERS).join(", ")}`);
+  const outFile = await renderFn(inputPath, outputPath);
+  console.log(outFile);
+}
+
+async function cmdValidate(type, inputPath, asJson) {
+  const raw = JSON.parse(await fs.readFile(inputPath, "utf8"));
+  try {
+    const problems = await validateAll(type, raw);
+    const result = { ok: problems.length === 0, type, input: inputPath, problems };
+    if (asJson) {
+      console.log(JSON.stringify(result, null, 2));
+    } else if (problems.length === 0) {
+      console.log("OK: schema and layout are clean.");
+    } else {
+      console.log(`Layout problems (${problems.length}):`);
+      for (const p of problems) console.log(`- ${p}`);
+    }
+    if (problems.length) process.exitCode = 1;
+  } catch (err) {
+    if (asJson) {
+      console.log(JSON.stringify({ ok: false, type, input: inputPath, error: err.message }, null, 2));
+    } else {
+      console.error(err.message);
+    }
+    process.exitCode = 1;
+  }
+}
+
+function findSoffice() {
+  const candidates = [
+    "C:/Program Files/LibreOffice/program/soffice.exe",
+    "/usr/bin/soffice",
+    "/opt/libreoffice/program/soffice",
+  ];
+  return candidates.find((p) => existsSync(p));
+}
+
+async function cmdCheck(pptxPath) {
+  const buf = await fs.readFile(pptxPath);
+  const zip = await JSZip.loadAsync(buf);
+  const problems = [];
+
+  const hasNotes = Object.keys(zip.files).some(
+    (n) => n.startsWith("ppt/notesMasters/") || n.startsWith("ppt/notesSlides/")
+  );
+  if (hasNotes) problems.push("notesMaster/notesSlide parts present — repairPptx() was not applied (Hancom Office will flag this as corrupted).");
+
+  const hasEmptyScaffold = Object.keys(zip.files).some(
+    (n) => n.startsWith("ppt/charts/") || n.startsWith("ppt/embeddings/")
+  );
+  if (hasEmptyScaffold) problems.push("empty ppt/charts/ or ppt/embeddings/ scaffolding present.");
+
+  const slideFiles = Object.keys(zip.files).filter((n) => /^ppt\/slides\/slide\d+\.xml$/.test(n));
+  const texts = [];
+  for (const name of slideFiles) {
+    const content = await zip.file(name).async("string");
+    const matches = [...content.matchAll(/<a:t>([^<]*)<\/a:t>/g)].map((m) => m[1]);
+    texts.push(...matches);
+  }
+
+  console.log(JSON.stringify({ ok: problems.length === 0, file: pptxPath, problems, embeddedText: texts }, null, 2));
+
+  const soffice = findSoffice();
+  if (soffice) {
+    const outDir = path.join(path.dirname(pptxPath), "render");
+    await fs.mkdir(outDir, { recursive: true });
+    await execFileAsync(soffice, ["--headless", "--convert-to", "png", "--outdir", outDir, pptxPath]);
+    const pngName = path.basename(pptxPath).replace(/\.pptx$/, ".png");
+    console.log(`PNG preview: ${path.join(outDir, pngName)}`);
+  } else {
+    console.log("LibreOffice not found — skipping PNG preview. Install it for visual QA (soffice --headless --convert-to png).");
+  }
+
+  if (problems.length) process.exitCode = 1;
+}
+
+async function cmdDoctor() {
+  const checks = [];
+  try {
+    await import("pptxgenjs");
+    checks.push(["pptxgenjs", true]);
+  } catch {
+    checks.push(["pptxgenjs", false]);
+  }
+  try {
+    await import("jszip");
+    checks.push(["jszip", true]);
+  } catch {
+    checks.push(["jszip", false]);
+  }
+  try {
+    await import("ajv/dist/2020.js");
+    checks.push(["ajv", true]);
+  } catch {
+    checks.push(["ajv", false]);
+  }
+  const soffice = findSoffice();
+  checks.push(["LibreOffice (optional, enables `check` PNG preview + visual QA)", Boolean(soffice)]);
+
+  for (const [name, ok] of checks) {
+    console.log(`[${ok ? "ok" : "MISSING"}] ${name}`);
+  }
+  if (checks.some(([, ok]) => !ok)) process.exitCode = 1;
+}
+
+const [, , cmd, ...rest] = process.argv;
+
+try {
+  if (cmd === "render") {
+    const [type, input, output] = rest;
+    if (!type || !input) { usage(); process.exit(1); }
+    await cmdRender(type, input, output);
+  } else if (cmd === "validate") {
+    const asJson = rest.includes("--json");
+    const [type, input] = rest.filter((a) => a !== "--json");
+    if (!type || !input) { usage(); process.exit(1); }
+    await cmdValidate(type, input, asJson);
+  } else if (cmd === "check") {
+    const [pptxPath] = rest;
+    if (!pptxPath) { usage(); process.exit(1); }
+    await cmdCheck(pptxPath);
+  } else if (cmd === "doctor") {
+    await cmdDoctor();
+  } else {
+    usage();
+    process.exit(cmd ? 1 : 0);
+  }
+} catch (err) {
+  console.error(err.message);
+  process.exit(1);
+}

package/examples/onboarding.workflow.json

@@ -0,0 +1,29 @@
+{
+  "schema_version": 1,
+  "diagram_type": "workflow",
+  "meta": {
+    "title": "신규 직원 온보딩 프로세스",
+    "subtitle": "HR팀 → IT팀 → 팀장",
+    "output": "test/output/onboarding.schema-driven.pptx"
+  },
+  "lanes": [
+    { "id": "hr", "label": "HR팀" },
+    { "id": "it", "label": "IT팀" },
+    { "id": "lead", "label": "팀장" }
+  ],
+  "nodes": [
+    { "id": "apply", "lane": "hr", "col": 0, "type": "neutral", "label": "입사 서류 접수", "sublabel": "인사팀 접수 확인" },
+    { "id": "request", "lane": "hr", "col": 1, "type": "neutral", "label": "계정 발급 요청", "sublabel": "IT팀에 요청 전달" },
+    { "id": "account", "lane": "it", "col": 1, "type": "backend", "label": "계정 생성", "sublabel": "사내 계정 · 이메일" },
+    { "id": "equipment", "lane": "it", "col": 2, "type": "backend", "label": "장비 지급", "sublabel": "노트북 · 출입카드" },
+    { "id": "kickoff", "lane": "lead", "col": 3, "type": "database", "label": "킥오프 미팅", "sublabel": "팀 소개 · 업무 안내" },
+    { "id": "done", "lane": "lead", "col": 4, "type": "database", "label": "온보딩 완료", "sublabel": "1주차 체크인 예약" }
+  ],
+  "edges": [
+    { "from": "apply", "to": "request", "variant": "default", "route": "straight" },
+    { "from": "request", "to": "account", "variant": "emphasis", "route": "drop", "label": "요청 전달" },
+    { "from": "account", "to": "equipment", "variant": "emphasis", "route": "straight" },
+    { "from": "equipment", "to": "kickoff", "variant": "default", "route": "drop", "label": "장비 수령 후" },
+    { "from": "kickoff", "to": "done", "variant": "default", "route": "straight" }
+  ]
+}

package/examples/order-processing.architecture.json

@@ -0,0 +1,29 @@
+{
+  "schema_version": 1,
+  "diagram_type": "architecture",
+  "meta": {
+    "title": "온라인 쇼핑몰 주문처리 아키텍처",
+    "subtitle": "클라이언트 → API 서버 → 내부 인프라 / 외부 결제 PG",
+    "output": "test/output/order-processing.schema-driven.pptx"
+  },
+  "components": [
+    { "id": "client", "type": "client", "label": "사용자", "sublabel": "브라우저", "pos": [0.4, 3.1], "size": [1.5, 1.1] },
+    { "id": "web", "type": "frontend", "label": "웹 / 앱", "sublabel": "React", "pos": [2.35, 3.1], "size": [1.7, 1.1] },
+    { "id": "api", "type": "backend", "label": "API 서버", "sublabel": "주문 처리", "pos": [5.9, 3.1], "size": [1.85, 1.1] },
+    { "id": "db", "type": "database", "label": "주문 DB", "pos": [8.4, 1.55], "size": [1.0, 1.2] },
+    { "id": "cache", "type": "cache", "label": "캐시", "sublabel": "Redis", "pos": [8.3, 3.1], "size": [1.15, 1.1] },
+    { "id": "queue", "type": "queue", "label": "알림 큐", "pos": [8.3, 4.55], "size": [1.15, 1.05] },
+    { "id": "pg", "type": "external", "label": "결제 PG사", "sublabel": "외부 서비스", "pos": [10.4, 3.0], "size": [2.1, 1.3] }
+  ],
+  "boundaries": [
+    { "label": "사내 인프라 (VPC)", "wraps": ["api", "db", "cache", "queue"], "color": "F59E0B" }
+  ],
+  "connections": [
+    { "from": "client", "to": "web", "variant": "default", "route": "straight" },
+    { "from": "web", "to": "api", "variant": "emphasis", "route": "straight" },
+    { "from": "api", "to": "db", "variant": "default", "route": "elbow-right", "label": "주문 저장" },
+    { "from": "api", "to": "cache", "variant": "default", "route": "elbow-right" },
+    { "from": "api", "to": "queue", "variant": "default", "route": "elbow-right", "label": "발송 알림" },
+    { "from": "api", "to": "pg", "variant": "dashed", "route": "arc-over-top", "clearY": 1.0, "label": "결제 요청 (async)" }
+  ]
+}

package/index.mjs

@@ -0,0 +1,4 @@
+export { renderWorkflow } from "./renderers/workflow/render-workflow.mjs";
+export { renderArchitecture } from "./renderers/architecture/render-architecture.mjs";
+export { validateAll, validateSchema, validateWorkflowLayout, validateArchitectureLayout } from "./lib/validate.mjs";
+export { repairPptx } from "./lib/repair-pptx.mjs";

package/lib/layout.mjs

@@ -0,0 +1,73 @@
+// Pure layout math shared by the renderers (which draw the boxes this
+// computes) and the validator (which checks them before anything is drawn).
+// Keeping this in one place means the renderer and the validator can never
+// silently drift apart.
+
+export const SLIDE_W = 13.33, SLIDE_H = 7.5;
+
+export const WORKFLOW_LAYOUT = {
+  LANE_X: 0.4, LANE_W: 12.5,
+  LANE_START_Y: 1.15, LANE_GAP: 0.15, DEFAULT_LANE_H: 1.75,
+  COL_X0: 0.6, COL_WIDTH: 2.0,
+  NODE_W: 1.8, NODE_H: 0.95, NODE_Y_OFFSET: 0.35,
+};
+
+export function computeWorkflowLayout(raw) {
+  const L = WORKFLOW_LAYOUT;
+  let y = L.LANE_START_Y;
+  const laneBoxes = {};
+  for (const lane of raw.lanes) {
+    const h = lane.height || L.DEFAULT_LANE_H;
+    laneBoxes[lane.id] = { x: L.LANE_X, y, w: L.LANE_W, h };
+    y += h + L.LANE_GAP;
+  }
+  const cardsY = y + 0.1;
+
+  const usedCols = {};
+  for (const n of raw.nodes) {
+    if (n.col !== undefined) (usedCols[n.lane] ||= new Set()).add(n.col);
+  }
+  const nodeBoxes = {};
+  const nodeMeta = {};
+  for (const n of raw.nodes) {
+    const laneBox = laneBoxes[n.lane];
+    if (!laneBox) throw new Error(`Node "${n.id}" references unknown lane "${n.lane}"`);
+    let col = n.col;
+    if (col === undefined) {
+      const used = (usedCols[n.lane] ||= new Set());
+      col = 0;
+      while (used.has(col)) col++;
+      used.add(col);
+    }
+    const w = n.width || L.NODE_W;
+    const h = n.height || L.NODE_H;
+    nodeBoxes[n.id] = { x: L.COL_X0 + col * L.COL_WIDTH, y: laneBox.y + L.NODE_Y_OFFSET, w, h };
+    nodeMeta[n.id] = { lane: n.lane, col };
+  }
+  return { laneBoxes, nodeBoxes, nodeMeta, cardsY };
+}
+
+const BOUNDARY_PAD = 0.3;
+
+export function computeArchitectureLayout(raw) {
+  const boxes = {};
+  for (const c of raw.components) {
+    const [x, y] = c.pos;
+    const [w, h] = c.size || [1.8, 0.95];
+    boxes[c.id] = { x, y, w, h };
+  }
+
+  const boundaryBoxes = (raw.boundaries || []).map((b) => {
+    const wrapped = b.wraps.map((id) => {
+      if (!boxes[id]) throw new Error(`Boundary "${b.label}" wraps unknown component "${id}"`);
+      return boxes[id];
+    });
+    const minX = Math.min(...wrapped.map((n) => n.x)) - BOUNDARY_PAD;
+    const minY = Math.min(...wrapped.map((n) => n.y)) - BOUNDARY_PAD;
+    const maxX = Math.max(...wrapped.map((n) => n.x + n.w)) + BOUNDARY_PAD;
+    const maxY = Math.max(...wrapped.map((n) => n.y + n.h)) + BOUNDARY_PAD;
+    return { label: b.label, color: b.color, box: { x: minX, y: minY, w: maxX - minX, h: maxY - minY } };
+  });
+
+  return { boxes, boundaryBoxes };
+}

package/lib/repair-pptx.mjs

@@ -0,0 +1,73 @@
+import fs from "node:fs/promises";
+import JSZip from "jszip";
+
+/**
+ * Fixes known PptxGenJS OOXML defects that PowerPoint and Hancom Office's
+ * 한쇼 flag as a corrupted/damaged document (LibreOffice is lenient and
+ * renders the unfixed output fine, which is why the defects go unnoticed
+ * until a stricter parser opens the file).
+ *
+ * Source: https://github.com/gitbrent/PptxGenJS/issues/1449
+ *   - Defect 5: notesMaster1.xml always ships 6 placeholder shapes
+ *     (hdr/dt/sldImg/body/ftr/sldNum) that PowerPoint-family parsers
+ *     consider malformed. PptxGenJS emits this notes scaffold on every
+ *     file regardless of whether notes are used, so every generated
+ *     pptx carries it.
+ *   - Defect 6: empty ppt/charts/ and ppt/embeddings/ directories are
+ *     always created even when no chart/embedding exists.
+ *
+ * Strategy: since our diagrams never use PPT speaker notes or embedded
+ * charts, the simplest fix is to strip the notes infrastructure and the
+ * empty scaffold directories entirely rather than trying to make them
+ * spec-conformant.
+ */
+export async function repairPptx(filePath) {
+  const buf = await fs.readFile(filePath);
+  const zip = await JSZip.loadAsync(buf);
+
+  // Defect 5: drop notes parts
+  for (const name of Object.keys(zip.files)) {
+    if (name.startsWith("ppt/notesMasters/") || name.startsWith("ppt/notesSlides/")) {
+      zip.remove(name);
+    }
+  }
+
+  // Defect 6: drop empty chart/embedding scaffolding
+  for (const name of Object.keys(zip.files)) {
+    if (name.startsWith("ppt/charts/") || name.startsWith("ppt/embeddings/")) {
+      zip.remove(name);
+    }
+  }
+
+  // [Content_Types].xml: remove notesMaster/notesSlide Overrides
+  const ctPath = "[Content_Types].xml";
+  let ct = await zip.file(ctPath).async("string");
+  ct = ct.replace(/<Override[^>]*PartName="\/ppt\/notesMasters\/[^"]*"[^>]*\/>/g, "");
+  ct = ct.replace(/<Override[^>]*PartName="\/ppt\/notesSlides\/[^"]*"[^>]*\/>/g, "");
+  zip.file(ctPath, ct);
+
+  // presentation.xml: remove <p:notesMasterIdLst>
+  const presPath = "ppt/presentation.xml";
+  let pres = await zip.file(presPath).async("string");
+  pres = pres.replace(/<p:notesMasterIdLst>[\s\S]*?<\/p:notesMasterIdLst>/g, "");
+  zip.file(presPath, pres);
+
+  // presentation.xml.rels: remove notesMaster relationship
+  const presRelsPath = "ppt/_rels/presentation.xml.rels";
+  let presRels = await zip.file(presRelsPath).async("string");
+  presRels = presRels.replace(/<Relationship[^>]*Type="[^"]*\/notesMaster"[^>]*\/>/g, "");
+  zip.file(presRelsPath, presRels);
+
+  // each slide's .rels: remove notesSlide relationship
+  const slideRelsPattern = /^ppt\/slides\/_rels\/slide\d+\.xml\.rels$/;
+  for (const name of Object.keys(zip.files)) {
+    if (slideRelsPattern.test(name)) {
+      let content = await zip.file(name).async("string");
+      const cleaned = content.replace(/<Relationship[^>]*Type="[^"]*\/notesSlide"[^>]*\/>/g, "");
+      if (cleaned !== content) zip.file(name, cleaned);
+    }
+  }
+
+  const out = await zip.generateAsync({ type: "nodebuffer", compression: "DEFLATE" });
+  await fs.writeFile(filePath, out);
+}