ptxiagram 0.1.0

package/lib/routes.mjs

@@ -0,0 +1,112 @@
+import { FONT } from "./shapes.mjs";
+
+export function centerTop(n) { return { x: n.x + n.w / 2, y: n.y }; }
+export function centerBottom(n) { return { x: n.x + n.w / 2, y: n.y + n.h }; }
+export function centerLeft(n) { return { x: n.x, y: n.y + n.h / 2 }; }
+export function centerRight(n) { return { x: n.x + n.w, y: n.y + n.h / 2 }; }
+
+// Normalizes a point-to-point line into a {x,y,w,h} box (pptxgenjs "line"
+// shapes are a bounding box + direction, so a purely vertical or horizontal
+// segment always has w=0 or h=0 here).
+function boxFromPoints(p1, p2) {
+  return { x: p1.x, y: p1.y, w: p2.x - p1.x, h: p2.y - p1.y };
+}
+
+/**
+ * Pure geometry: returns the ordered line segments (each an arrow-less
+ * {x,y,w,h,arrow} box, `arrow: true` only on the final one) and the label
+ * anchor a connector between `from` and `to` would use, without touching a
+ * slide. The renderer draws these; the validator walks them to check for
+ * crossings against unrelated nodes. See routes' JSDoc in `connector()`
+ * below for what each route means.
+ */
+export function computeSegments(from, to, opts = {}) {
+  const { route = "straight", bias = 0.5, clearY, label } = opts;
+
+  if (route === "straight") {
+    const a = centerRight(from), b = centerLeft(to);
+    return {
+      segments: [{ ...boxFromPoints(a, b), arrow: true }],
+      labelAnchor: label ? { x: a.x, y: a.y, w: b.x - a.x } : null,
+    };
+  }
+
+  if (route === "drop") {
+    const a = centerBottom(from), b = centerTop(to);
+    if (Math.abs(a.x - b.x) < 0.05) {
+      return {
+        segments: [{ ...boxFromPoints(a, { x: a.x, y: b.y }), arrow: true }],
+        labelAnchor: label ? { x: a.x - 0.6, y: (a.y + b.y) / 2, w: 1.2 } : null,
+      };
+    }
+    const midY = a.y + (b.y - a.y) * bias;
+    return {
+      segments: [
+        { ...boxFromPoints(a, { x: a.x, y: midY }), arrow: false },
+        { ...boxFromPoints({ x: Math.min(a.x, b.x), y: midY }, { x: Math.max(a.x, b.x), y: midY }), arrow: false },
+        { ...boxFromPoints({ x: b.x, y: midY }, b), arrow: true },
+      ],
+      labelAnchor: label ? { x: Math.min(a.x, b.x) - 0.6, y: midY, w: Math.abs(b.x - a.x) + 1.2 } : null,
+    };
+  }
+
+  if (route === "elbow-right") {
+    const a = centerRight(from), b = centerLeft(to);
+    if (Math.abs(a.y - b.y) < 0.05) {
+      return {
+        segments: [{ ...boxFromPoints(a, { x: b.x, y: a.y }), arrow: true }],
+        labelAnchor: label ? { x: a.x, y: a.y, w: b.x - a.x } : null,
+      };
+    }
+    const midX = a.x + (b.x - a.x) * bias;
+    return {
+      segments: [
+        { ...boxFromPoints(a, { x: midX, y: a.y }), arrow: false },
+        { ...boxFromPoints({ x: midX, y: Math.min(a.y, b.y) }, { x: midX, y: Math.max(a.y, b.y) }), arrow: false },
+        { ...boxFromPoints({ x: midX, y: b.y }, b), arrow: true },
+      ],
+      labelAnchor: label ? { x: midX - 0.6, y: b.y, w: 1.2 } : null,
+    };
+  }
+
+  if (route === "arc-over-top") {
+    if (clearY === undefined) throw new Error("route 'arc-over-top' requires opts.clearY");
+    const a = centerTop(from), b = centerTop(to);
+    return {
+      segments: [
+        { ...boxFromPoints(a, { x: a.x, y: clearY }), arrow: false },
+        { ...boxFromPoints({ x: Math.min(a.x, b.x), y: clearY }, { x: Math.max(a.x, b.x), y: clearY }), arrow: false },
+        { ...boxFromPoints({ x: b.x, y: clearY }, b), arrow: true },
+      ],
+      labelAnchor: label ? { x: Math.min(a.x, b.x), y: clearY, w: Math.abs(b.x - a.x) } : null,
+    };
+  }
+
+  throw new Error(`Unknown route: ${route}`);
+}
+
+/** Draws a connector between two node boxes {x,y,w,h}. See computeSegments
+ * for what each `route` means; this is the thin drawing layer over it.
+ * opts: { color, dashed, label, route, bias, clearY } */
+export function connector(slide, from, to, opts = {}) {
+  const { color = "94A3B8", dashed = false, label } = opts;
+  const { segments, labelAnchor } = computeSegments(from, to, opts);
+
+  for (const s of segments) {
+    slide.addShape("line", {
+      x: s.x, y: s.y, w: s.w, h: s.h,
+      line: {
+        color, width: 2,
+        dashType: dashed ? "dash" : "solid",
+        ...(s.arrow ? { endArrowType: "triangle" } : {}),
+      },
+    });
+  }
+
+  if (label && labelAnchor) {
+    slide.addText(label, {
+      x: labelAnchor.x, y: labelAnchor.y - 0.32, w: labelAnchor.w, h: 0.28,
+      align: "center", fontFace: FONT, fontSize: 8.5, color: "475569",
+    });
+  }
+}

package/lib/shapes.mjs

@@ -0,0 +1,107 @@
+// Semantic node types -> native PPTX shape preset + color pair.
+// Shape preset strings are raw OOXML preset geometry names (pptxgenjs
+// accepts these directly, no need to import the ShapeType enum).
+export const NODE_TYPES = {
+  client: { shape: "ellipse", fill: "F1F5F9", stroke: "94A3B8" },
+  frontend: { shape: "rect", fill: "E2E8F0", stroke: "94A3B8" },
+  neutral: { shape: "roundRect", fill: "E2E8F0", stroke: "94A3B8" },
+  backend: { shape: "roundRect", fill: "D1FAE5", stroke: "10B981" },
+  database: { shape: "can", fill: "DBEAFE", stroke: "3B82F6" },
+  cache: { shape: "hexagon", fill: "DBEAFE", stroke: "3B82F6" },
+  queue: { shape: "cube", fill: "DBEAFE", stroke: "3B82F6" },
+  external: { shape: "cloud", fill: "FEF3C7", stroke: "F59E0B" },
+  security: { shape: "roundRect", fill: "FFE4E6", stroke: "F43F5E" },
+  decision: { shape: "diamond", fill: "FFE4E6", stroke: "F43F5E" },
+};
+
+export const FONT = "맑은 고딕";
+
+// Edge/connection variant -> color + dash pair, so JSON authors pick a
+// semantic variant instead of guessing hex codes.
+export const EDGE_VARIANTS = {
+  default: { color: "94A3B8", dashed: false },
+  emphasis: { color: "10B981", dashed: false },
+  security: { color: "F43F5E", dashed: true },
+  dashed: { color: "64748B", dashed: true },
+};
+
+// Draws a labeled node and returns its box {x,y,w,h} for connector anchoring.
+export function drawNode(slide, { x, y, w = 1.8, h = 0.95, label, sublabel, type = "neutral", tag }) {
+  const style = NODE_TYPES[type] || NODE_TYPES.neutral;
+  slide.addShape(style.shape, {
+    x, y, w, h,
+    fill: { color: style.fill },
+    line: { color: style.stroke, width: 1.5 },
+    shadow: { type: "outer", color: "1E293B", opacity: 0.18, blur: 4, offset: 1, angle: 90 },
+  });
+
+  const hasSub = Boolean(sublabel);
+  slide.addText(label, {
+    x, y: y + h / 2 - (hasSub ? 0.28 : 0.14), w, h: 0.32,
+    align: "center", valign: "middle", fontFace: FONT, fontSize: 12.5, bold: true, color: "0F172A",
+  });
+  if (hasSub) {
+    slide.addText(sublabel, {
+      x, y: y + h / 2 + 0.08, w, h: 0.3,
+      align: "center", fontFace: FONT, fontSize: 9, color: "64748B",
+    });
+  }
+  if (tag) {
+    slide.addText(tag, {
+      x, y: y + h - 0.24, w, h: 0.22,
+      align: "center", fontFace: FONT, fontSize: 7.5, color: style.stroke,
+    });
+  }
+  return { x, y, w, h };
+}
+
+// Draws a dashed boundary frame (precomputed by lib/layout.mjs's
+// computeArchitectureLayout, which owns the padding math) with a label in
+// its top-left corner. Mirrors archify's `wraps` boundary concept.
+export function drawBoundary(slide, { box, label, color = "F59E0B" }) {
+  slide.addShape("rect", {
+    ...box,
+    fill: { type: "none" },
+    line: { color, width: 1.25, dashType: "dash" },
+  });
+  slide.addText(label, {
+    x: box.x + 0.15, y: box.y + 0.1, w: box.w - 0.3, h: 0.3,
+    fontFace: FONT, fontSize: 10, color, bold: true,
+  });
+}
+
+// Draws a row of summary cards (title + bullet items) spanning the slide
+// width, starting at the given y. Used for footnotes/exception details that
+// would otherwise need extra nodes and crossing arrows.
+export function drawCards(slide, cards, y) {
+  const totalW = 12.5, gap = 0.25;
+  const w = (totalW - gap * (cards.length - 1)) / cards.length;
+  cards.forEach((card, i) => {
+    const x = 0.4 + i * (w + gap);
+    const color = card.color ? `#${card.color}` : "3B82F6";
+    slide.addText(card.title, {
+      x, y, w, h: 0.3,
+      fontFace: FONT, fontSize: 11, bold: true, color: "0F172A",
+    });
+    const bulletText = card.items.map((t) => `• ${t}`).join("\n");
+    slide.addText(bulletText, {
+      x, y: y + 0.35, w, h: 1.3,
+      fontFace: FONT, fontSize: 9, color: "475569", valign: "top", lineSpacing: 14,
+    });
+    slide.addShape("rect", { x, y: y + 0.02, w: 0.05, h: 0.22, fill: { color: card.color || "3B82F6" }, line: { type: "none" } });
+  });
+}
+
+// Draws a swimlane frame with a title strip. Returns the lane's box.
+export function drawLane(slide, { x, y, w, h, label }) {
+  slide.addShape("rect", {
+    x, y, w, h,
+    fill: { color: "F8FAFC" },
+    line: { color: "CBD5E1", width: 1, dashType: "dash" },
+  });
+  slide.addText(label, {
+    x: x + 0.15, y: y + 0.05, w: 3, h: 0.3,
+    fontFace: FONT, fontSize: 11, color: "64748B", bold: true,
+  });
+  return { x, y, w, h };
+}

package/lib/validate.mjs

@@ -0,0 +1,143 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import Ajv2020 from "ajv/dist/2020.js";
+import { computeWorkflowLayout, computeArchitectureLayout, SLIDE_W, SLIDE_H } from "./layout.mjs";
+import { computeSegments } from "./routes.mjs";
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const SCHEMAS_DIR = path.join(__dirname, "..", "schemas");
+
+let ajvInstance;
+async function getAjv() {
+  if (ajvInstance) return ajvInstance;
+  const ajv = new Ajv2020({ allErrors: true, strict: false });
+  const common = JSON.parse(await fs.readFile(path.join(SCHEMAS_DIR, "common.schema.json"), "utf8"));
+  ajv.addSchema(common, "common.schema.json");
+  ajvInstance = ajv;
+  return ajv;
+}
+
+/** Validates `data` against schemas/<type>.schema.json. Throws with a
+ * readable message (path + reason per error) if invalid. */
+export async function validateSchema(type, data) {
+  const ajv = await getAjv();
+  const schemaPath = path.join(SCHEMAS_DIR, `${type}.schema.json`);
+  const schema = JSON.parse(await fs.readFile(schemaPath, "utf8"));
+  const validateFn = ajv.getSchema(schema.$id) || ajv.compile(schema);
+  const ok = validateFn(data);
+  if (!ok) {
+    const messages = validateFn.errors.map((e) => `${e.instancePath || "/"} ${e.message}`);
+    throw new Error(`Schema validation failed:\n- ${messages.join("\n- ")}`);
+  }
+  return true;
+}
+
+function rectsOverlap(a, b) {
+  return a.x < b.x + b.w && a.x + a.w > b.x && a.y < b.y + b.h && a.y + a.h > b.y;
+}
+
+const CJK_RE = /[ㄱ-힝一-鿿]/;
+
+// Crude CJK-aware text width estimate (inches) for a given font size (pt).
+// Not exact glyph metrics -- good enough to flag labels that will visibly
+// overflow their shape, which is the failure mode this exists to catch.
+function estimateTextWidth(text, fontSizePt) {
+  const unit = (fontSizePt / 72) * 0.62;
+  let units = 0;
+  for (const ch of text) units += CJK_RE.test(ch) ? 1.0 : 0.55;
+  return units * unit;
+}
+
+// All routes in lib/routes.mjs only ever emit axis-aligned segments, so
+// treating each as a simple bounding box is exact, not an approximation.
+function segmentIntersectsRect(seg, rect, epsilon = 0.02) {
+  const x1 = Math.min(seg.x, seg.x + seg.w), x2 = Math.max(seg.x, seg.x + seg.w);
+  const y1 = Math.min(seg.y, seg.y + seg.h), y2 = Math.max(seg.y, seg.y + seg.h);
+  return (
+    x1 < rect.x + rect.w - epsilon && x2 > rect.x + epsilon &&
+    y1 < rect.y + rect.h - epsilon && y2 > rect.y + epsilon
+  );
+}
+
+function offSlide(box) {
+  return box.x < 0 || box.y < 0 || box.x + box.w > SLIDE_W || box.y + box.h > SLIDE_H;
+}
+
+function checkCommon({ problems, ids, boxes, labelOf, fontSizePt, edgesOrConns, resolveEndpoints, edgeLabel }) {
+  for (const id of ids) {
+    const box = boxes[id];
+    const label = labelOf(id);
+    const w = estimateTextWidth(label, fontSizePt);
+    if (w > box.w - 0.1) {
+      problems.push(`"${id}" label "${label}" (~${w.toFixed(2)}in) is wider than its shape (${box.w.toFixed(2)}in) — shorten the label or move detail to sublabel.`);
+    }
+    if (offSlide(box)) {
+      problems.push(`"${id}" is off-slide (slide is ${SLIDE_W}x${SLIDE_H}in).`);
+    }
+  }
+
+  for (let i = 0; i < ids.length; i++) {
+    for (let j = i + 1; j < ids.length; j++) {
+      if (rectsOverlap(boxes[ids[i]], boxes[ids[j]])) {
+        problems.push(`"${ids[i]}" and "${ids[j]}" overlap.`);
+      }
+    }
+  }
+
+  for (const e of edgesOrConns) {
+    const { from, to } = resolveEndpoints(e);
+    if (!from || !to) continue; // unknown-id errors surface from the renderer/schema instead
+    const { segments } = computeSegments(from, to, {
+      route: e.route || "straight", bias: e.bias, clearY: e.clearY, label: e.label,
+    });
+    for (const id of ids) {
+      if (id === e.from || id === e.to) continue;
+      const rect = boxes[id];
+      if (segments.some((seg) => segmentIntersectsRect(seg, rect))) {
+        problems.push(`${edgeLabel(e)} crosses "${id}" — pick a different route/bias/clearY or reposition.`);
+      }
+    }
+  }
+
+  return problems;
+}
+
+export function validateWorkflowLayout(raw) {
+  const { nodeBoxes } = computeWorkflowLayout(raw);
+  const labelOf = (id) => raw.nodes.find((n) => n.id === id).label;
+  return checkCommon({
+    problems: [],
+    ids: Object.keys(nodeBoxes),
+    boxes: nodeBoxes,
+    labelOf,
+    fontSizePt: 12.5,
+    edgesOrConns: raw.edges,
+    resolveEndpoints: (e) => ({ from: nodeBoxes[e.from], to: nodeBoxes[e.to] }),
+    edgeLabel: (e) => `Edge "${e.from}"->"${e.to}"`,
+  });
+}
+
+export function validateArchitectureLayout(raw) {
+  const { boxes } = computeArchitectureLayout(raw);
+  const labelOf = (id) => raw.components.find((c) => c.id === id).label;
+  return checkCommon({
+    problems: [],
+    ids: Object.keys(boxes),
+    boxes,
+    labelOf,
+    fontSizePt: 12.5,
+    edgesOrConns: raw.connections,
+    resolveEndpoints: (e) => ({ from: boxes[e.from], to: boxes[e.to] }),
+    edgeLabel: (e) => `Connection "${e.from}"->"${e.to}"`,
+  });
+}
+
+/** Runs schema validation, then layout collision checks. Returns the list
+ * of layout problems (empty = clean); throws if schema validation fails. */
+export async function validateAll(type, raw) {
+  await validateSchema(type, raw);
+  if (type === "workflow") return validateWorkflowLayout(raw);
+  if (type === "architecture") return validateArchitectureLayout(raw);
+  throw new Error(`Unknown diagram type: ${type}`);
+}

package/package.json

@@ -0,0 +1,48 @@
+{
+  "name": "ptxiagram",
+  "version": "0.1.0",
+  "description": "Generate native, editable PowerPoint (PPTX) architecture and workflow diagrams from a small JSON file — real shapes and connectors, not an embedded image. Ships with a Claude Skill (SKILL.md) and a CLI.",
+  "type": "module",
+  "main": "index.mjs",
+  "bin": {
+    "ptxiagram": "bin/cli.mjs"
+  },
+  "files": [
+    "bin",
+    "lib",
+    "renderers",
+    "schemas",
+    "examples",
+    "index.mjs",
+    "SKILL.md"
+  ],
+  "scripts": {
+    "doctor": "node bin/cli.mjs doctor",
+    "test": "node test/render-workflow.test.mjs && node test/render-architecture.test.mjs && node test/validate.test.mjs && node test/workflow-lib-smoke.test.mjs"
+  },
+  "keywords": [
+    "pptx",
+    "powerpoint",
+    "diagram",
+    "claude-skill",
+    "architecture-diagram",
+    "workflow-diagram",
+    "hancom",
+    "hanshow",
+    "office-automation"
+  ],
+  "author": "hiio420official",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/hiio420official/ptxiagram.git"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "dependencies": {
+    "ajv": "^8.20.0",
+    "jszip": "^3.10.1",
+    "pptxgenjs": "^4.0.1"
+  }
+}

package/renderers/architecture/render-architecture.mjs

@@ -0,0 +1,68 @@
+import pptxgen from "pptxgenjs";
+import fs from "node:fs/promises";
+import { drawNode, drawBoundary, drawCards, FONT, EDGE_VARIANTS } from "../../lib/shapes.mjs";
+import { connector } from "../../lib/routes.mjs";
+import { repairPptx } from "../../lib/repair-pptx.mjs";
+import { validateSchema, validateArchitectureLayout } from "../../lib/validate.mjs";
+import { computeArchitectureLayout } from "../../lib/layout.mjs";
+
+export async function renderArchitecture(inputPath, outputPath) {
+  const raw = JSON.parse(await fs.readFile(inputPath, "utf8"));
+  await validateSchema("architecture", raw);
+
+  const { boxes, boundaryBoxes } = computeArchitectureLayout(raw);
+  const problems = validateArchitectureLayout(raw);
+  if (problems.length) {
+    throw new Error(`Architecture layout validation failed:\n- ${problems.join("\n- ")}`);
+  }
+
+  const pptx = new pptxgen();
+  pptx.defineLayout({ name: "WIDE", width: 13.33, height: 7.5 });
+  pptx.layout = "WIDE";
+  const slide = pptx.addSlide();
+
+  slide.addText(raw.meta.title, {
+    x: 0.4, y: 0.2, w: 12.5, h: 0.5,
+    fontFace: FONT, fontSize: 20, bold: true, color: "0F172A",
+  });
+  if (raw.meta.subtitle) {
+    slide.addText(raw.meta.subtitle, {
+      x: 0.4, y: 0.65, w: 12.5, h: 0.3,
+      fontFace: FONT, fontSize: 11, color: "64748B",
+    });
+  }
+
+  // boundaries first so they sit visually under the components they frame
+  for (const b of boundaryBoxes) {
+    drawBoundary(slide, { box: b.box, label: b.label, ...(b.color ? { color: b.color } : {}) });
+  }
+
+  for (const c of raw.components) {
+    drawNode(slide, { ...boxes[c.id], label: c.label, sublabel: c.sublabel, type: c.type, tag: c.tag });
+  }
+
+  for (const conn of raw.connections) {
+    const variant = EDGE_VARIANTS[conn.variant || "default"];
+    const from = boxes[conn.from], to = boxes[conn.to];
+    if (!from) throw new Error(`Connection references unknown component "${conn.from}"`);
+    if (!to) throw new Error(`Connection references unknown component "${conn.to}"`);
+    connector(slide, from, to, {
+      color: variant.color, dashed: variant.dashed, label: conn.label,
+      route: conn.route, bias: conn.bias, clearY: conn.clearY,
+    });
+  }
+
+  if (raw.cards && raw.cards.length) {
+    drawCards(slide, raw.cards, 6.0);
+  }
+
+  slide.addText("Made with a Claude Skill · native PPTX shapes, editable in PowerPoint", {
+    x: 0.4, y: 7.15, w: 12.5, h: 0.3,
+    fontFace: FONT, fontSize: 8, color: "94A3B8", italic: true,
+  });
+
+  const outFile = outputPath || raw.meta.output || "output.pptx";
+  await pptx.writeFile({ fileName: outFile });
+  await repairPptx(outFile);
+  return outFile;
+}

package/renderers/workflow/render-workflow.mjs

@@ -0,0 +1,67 @@
+import pptxgen from "pptxgenjs";
+import fs from "node:fs/promises";
+import { drawNode, drawLane, drawCards, FONT, EDGE_VARIANTS } from "../../lib/shapes.mjs";
+import { connector } from "../../lib/routes.mjs";
+import { repairPptx } from "../../lib/repair-pptx.mjs";
+import { validateSchema, validateWorkflowLayout } from "../../lib/validate.mjs";
+import { computeWorkflowLayout } from "../../lib/layout.mjs";
+
+export async function renderWorkflow(inputPath, outputPath) {
+  const raw = JSON.parse(await fs.readFile(inputPath, "utf8"));
+  await validateSchema("workflow", raw);
+
+  const { laneBoxes, nodeBoxes, cardsY } = computeWorkflowLayout(raw);
+  const problems = validateWorkflowLayout(raw);
+  if (problems.length) {
+    throw new Error(`Workflow layout validation failed:\n- ${problems.join("\n- ")}`);
+  }
+
+  const pptx = new pptxgen();
+  pptx.defineLayout({ name: "WIDE", width: 13.33, height: 7.5 });
+  pptx.layout = "WIDE";
+  const slide = pptx.addSlide();
+
+  slide.addText(raw.meta.title, {
+    x: 0.4, y: 0.2, w: 12.5, h: 0.5,
+    fontFace: FONT, fontSize: 20, bold: true, color: "0F172A",
+  });
+  if (raw.meta.subtitle) {
+    slide.addText(raw.meta.subtitle, {
+      x: 0.4, y: 0.65, w: 12.5, h: 0.3,
+      fontFace: FONT, fontSize: 11, color: "64748B",
+    });
+  }
+
+  for (const lane of raw.lanes) {
+    drawLane(slide, { ...laneBoxes[lane.id], label: lane.label });
+  }
+
+  for (const n of raw.nodes) {
+    drawNode(slide, { ...nodeBoxes[n.id], label: n.label, sublabel: n.sublabel, type: n.type, tag: n.tag });
+  }
+
+  for (const e of raw.edges) {
+    const variant = EDGE_VARIANTS[e.variant || "default"];
+    const from = nodeBoxes[e.from], to = nodeBoxes[e.to];
+    if (!from) throw new Error(`Edge references unknown node "${e.from}"`);
+    if (!to) throw new Error(`Edge references unknown node "${e.to}"`);
+    connector(slide, from, to, {
+      color: variant.color, dashed: variant.dashed,
+      label: e.label, route: e.route || "straight", bias: e.bias,
+    });
+  }
+
+  if (raw.cards && raw.cards.length) {
+    drawCards(slide, raw.cards, cardsY);
+  }
+
+  slide.addText("Made with a Claude Skill · native PPTX shapes, editable in PowerPoint", {
+    x: 0.4, y: 7.15, w: 12.5, h: 0.3,
+    fontFace: FONT, fontSize: 8, color: "94A3B8", italic: true,
+  });
+
+  const outFile = outputPath || raw.meta.output || "output.pptx";
+  await pptx.writeFile({ fileName: outFile });
+  await repairPptx(outFile);
+  return outFile;
+}

package/schemas/architecture.schema.json

@@ -0,0 +1,84 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://claude-skills/pptx-diagram/schemas/architecture.schema.json",
+  "title": "Native PPTX Architecture Diagram",
+  "description": "Components are freely positioned in inches on a 13.33x7.5in (16:9) slide. Boundaries wrap a set of component ids with a computed, padded dashed frame instead of hand-picked coordinates.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["schema_version", "diagram_type", "meta", "components", "connections"],
+  "properties": {
+    "schema_version": { "const": 1 },
+    "diagram_type": { "const": "architecture" },
+    "meta": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["title"],
+      "properties": {
+        "title": { "type": "string", "minLength": 1 },
+        "subtitle": { "type": "string" },
+        "output": { "type": "string" }
+      }
+    },
+    "components": {
+      "type": "array",
+      "minItems": 1,
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["id", "type", "label", "pos"],
+        "properties": {
+          "id": { "$ref": "common.schema.json#/$defs/id" },
+          "type": { "$ref": "common.schema.json#/$defs/nodeType" },
+          "label": { "type": "string", "minLength": 1 },
+          "sublabel": { "type": "string" },
+          "tag": { "type": "string" },
+          "pos": { "$ref": "common.schema.json#/$defs/point" },
+          "size": { "$ref": "common.schema.json#/$defs/point", "description": "[w,h] in inches; default [1.8, 0.95]" }
+        }
+      }
+    },
+    "boundaries": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["label", "wraps"],
+        "properties": {
+          "label": { "type": "string", "minLength": 1 },
+          "wraps": { "type": "array", "minItems": 1, "items": { "$ref": "common.schema.json#/$defs/id" } },
+          "color": { "$ref": "common.schema.json#/$defs/hexColor" }
+        }
+      }
+    },
+    "connections": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["from", "to", "route"],
+        "properties": {
+          "from": { "$ref": "common.schema.json#/$defs/id" },
+          "to": { "$ref": "common.schema.json#/$defs/id" },
+          "label": { "type": "string" },
+          "variant": { "enum": ["default", "emphasis", "security", "dashed"] },
+          "route": { "$ref": "common.schema.json#/$defs/route" },
+          "bias": { "type": "number", "minimum": 0.1, "maximum": 0.9 },
+          "clearY": { "type": "number", "minimum": 0.3, "maximum": 7.2, "description": "required when route is 'arc-over-top'" }
+        }
+      }
+    },
+    "cards": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["title", "items"],
+        "properties": {
+          "title": { "type": "string", "minLength": 1 },
+          "color": { "$ref": "common.schema.json#/$defs/hexColor" },
+          "items": { "type": "array", "items": { "type": "string" } }
+        }
+      }
+    }
+  }
+}

package/schemas/common.schema.json

@@ -0,0 +1,28 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://claude-skills/pptx-diagram/schemas/common.schema.json",
+  "title": "Shared definitions",
+  "$defs": {
+    "id": {
+      "type": "string",
+      "pattern": "^[a-zA-Z][a-zA-Z0-9_-]*$"
+    },
+    "point": {
+      "type": "array",
+      "prefixItems": [{ "type": "number" }, { "type": "number" }],
+      "items": false,
+      "minItems": 2,
+      "maxItems": 2
+    },
+    "nodeType": {
+      "enum": ["client", "frontend", "neutral", "backend", "database", "cache", "queue", "external", "security", "decision"]
+    },
+    "route": {
+      "enum": ["straight", "drop", "elbow-right", "arc-over-top"]
+    },
+    "hexColor": {
+      "type": "string",
+      "pattern": "^[0-9A-Fa-f]{6}$"
+    }
+  }
+}