@bendyline/squisq-formats 2.3.1 → 2.3.3

package/README.md

@@ -136,6 +136,7 @@ Chapters split at H1/H2 boundaries. Providing `audio` + `audioSegments` generate
 
 ```ts
 import {
+  docToPptx,
   markdownDocToPptx,
   pptxToMarkdownDoc,
   pptxToContainer,
@@ -145,6 +146,10 @@ import {
 // slideBreak: 'h1' | 'h2' (default — H1 and H2 both break) | 'heading'
 const pptxBytes = await markdownDocToPptx(markdownDoc, { slideBreak: 'h2', images });
 
+// Export: player-ready Doc -> 16:9 PPTX using the slideshow's canonical
+// block expansion and materialized visual layers (managed cover included by default)
+const visualDeck = await docToPptx(slideshowDoc, { images });
+
 // Import: PPTX → MarkdownDocument (add { extractImages: true } to reference slide images)
 const imported = await pptxToMarkdownDoc(pptxBuffer);
 
@@ -152,7 +157,7 @@ const imported = await pptxToMarkdownDoc(pptxBuffer);
 const container = await pptxToContainer(pptxBuffer);
 ```
 
-**Fidelity:** export preserves inline formatting as DrawingML runs and embeds images when provided via `options.images`. Import reads slide order from `ppt/presentation.xml` and converts each slide's title (→ H2), body text (→ bullet list), and tables. **Slide-image extraction (v1.5):** import can now extract slide-level `<p:pic>` bitmaps into `images/` — `pptxToContainer` returns a container with those files and forces `extractImages: true`, while `pptxToMarkdownDoc` leaves it off by default. Honest limit: only slide-level `<p:pic>` bitmaps are extracted — layout/master images, charts, SmartArt, and picture-fills are **not**.
+**Fidelity:** `markdownDocToPptx` preserves inline formatting as DrawingML runs. `docToPptx` treats a template-backed/player-ready `Doc` as a visual deck: it uses the same renderable-block flattening, timing expansion, managed-cover policy, theme, transitions, and materialized layer stack as slideshow view, so the PPTX has the same slide count and a matching 16:9 canvas. Text, shapes, tables, paths, and supplied images become editable native PowerPoint objects; browser-only map/video/Mermaid layers degrade to a static image when supplied or a labeled text fallback. Import reads slide order from `ppt/presentation.xml` and converts each slide's title (→ H2), body text (→ bullet list), and tables. **Slide-image extraction (v1.5):** import can now extract slide-level `<p:pic>` bitmaps into `images/` — `pptxToContainer` returns a container with those files and forces `extractImages: true`, while `pptxToMarkdownDoc` leaves it off by default. Honest limit: only slide-level `<p:pic>` bitmaps are extracted — layout/master images, charts, SmartArt, and picture-fills are **not**.
 
 ### CSV
 

package/dist/{chunk-IPN56VLW.js → chunk-C22NYDN2.js}

@@ -54,12 +54,22 @@ import {
 } from "./chunk-AONELFLA.js";
 
 // src/pptx/export.ts
-import { resolveFontFamily } from "@bendyline/squisq/schemas";
-import { docToMarkdown, resolveThemeForDoc } from "@bendyline/squisq/doc";
+import { resolveFontFamily, VIEWPORT_PRESETS } from "@bendyline/squisq/schemas";
+import {
+  createTemplateContext,
+  docToMarkdown,
+  expandCoverBlock,
+  expandDocBlocks,
+  flattenRenderableBlocks,
+  isTemplateBlock,
+  resolvePersistentLayers,
+  resolveThemeForDoc
+} from "@bendyline/squisq/doc";
+import { stripIconMarkers } from "@bendyline/squisq/icon-marker";
 import { readFrontmatterThemeId } from "@bendyline/squisq/markdown";
 
 // src/pptx/styles.ts
-var SLIDE_WIDTH = 9144e3;
+var SLIDE_WIDTH = 12192e3;
 var SLIDE_HEIGHT = 6858e3;
 var TITLE_LEFT = 457200;
 var TITLE_TOP = 274638;
@@ -82,7 +92,7 @@ function buildPresentationXml(slideCount, slideRelIds, slideMasterRelId, _themeR
   for (let i = 0; i < slideCount; i++) {
     sldIdList.push(`<p:sldId id="${256 + i}" r:id="${slideRelIds[i]}"/>`);
   }
-  return xmlDeclaration() + `<p:presentation xmlns:a="${NS_DRAWINGML}" xmlns:r="${NS_R}" xmlns:p="${NS_PML}" saveSubsetFonts="1"><p:sldMasterIdLst><p:sldMasterId id="2147483648" r:id="${slideMasterRelId}"/></p:sldMasterIdLst><p:sldIdLst>${sldIdList.join("")}</p:sldIdLst><p:sldSz cx="${SLIDE_WIDTH}" cy="${SLIDE_HEIGHT}" type="screen4x3"/><p:notesSz cx="${SLIDE_HEIGHT}" cy="${SLIDE_WIDTH}"/></p:presentation>`;
+  return xmlDeclaration() + `<p:presentation xmlns:a="${NS_DRAWINGML}" xmlns:r="${NS_R}" xmlns:p="${NS_PML}" saveSubsetFonts="1"><p:sldMasterIdLst><p:sldMasterId id="2147483648" r:id="${slideMasterRelId}"/></p:sldMasterIdLst><p:sldIdLst>${sldIdList.join("")}</p:sldIdLst><p:sldSz cx="${SLIDE_WIDTH}" cy="${SLIDE_HEIGHT}" type="screen16x9"/><p:notesSz cx="${SLIDE_HEIGHT}" cy="${SLIDE_WIDTH}"/></p:presentation>`;
 }
 function buildSlideMasterXml(layoutRelId) {
   return xmlDeclaration() + `<p:sldMaster xmlns:a="${NS_DRAWINGML}" xmlns:r="${NS_R}" xmlns:p="${NS_PML}"><p:cSld><p:bg><p:bgRef idx="1001"><a:schemeClr val="bg1"/></p:bgRef></p:bg><p:spTree><p:nvGrpSpPr><p:cNvPr id="1" name=""/><p:cNvGrpSpPr/><p:nvPr/></p:nvGrpSpPr><p:grpSpPr/></p:spTree></p:cSld><p:clrMap bg1="lt1" tx1="dk1" bg2="lt2" tx2="dk2" accent1="accent1" accent2="accent2" accent3="accent3" accent4="accent4" accent5="accent5" accent6="accent6" hlink="hlink" folHlink="folHlink"/><p:sldLayoutIdLst><p:sldLayoutId id="2147483649" r:id="${layoutRelId}"/></p:sldLayoutIdLst></p:sldMaster>`;
@@ -121,11 +131,69 @@ async function markdownDocToPptx(doc, options = {}) {
   return buildPptxPackage(slideXmls, slideContexts, options);
 }
 async function docToPptx(doc, options = {}) {
-  const markdownDoc = docToMarkdown(doc);
-  if (!options.themeId && doc.themeId) {
-    options = { ...options, themeId: doc.themeId };
+  options.signal?.throwIfAborted();
+  const effectiveOptions = !options.themeId && doc.themeId ? { ...options, themeId: doc.themeId } : options;
+  const flatBlocks = flattenRenderableBlocks(doc.blocks);
+  if (!flatBlocks.some(isTemplateBlock)) {
+    return markdownDocToPptx(docToMarkdown(doc), effectiveOptions);
+  }
+  const theme = resolveThemeForDoc(doc, effectiveOptions.themeId, effectiveOptions.themeRegistry);
+  const style = slideStyleFromTheme(theme, effectiveOptions);
+  const audioSegments = doc.audio?.segments?.map((segment) => ({
+    startTime: segment.startTime,
+    duration: segment.duration
+  }));
+  const persistentLayers = resolvePersistentLayers(
+    { persistentLayers: doc.persistentLayers },
+    theme
+  );
+  const expanded = expandDocBlocks(flatBlocks, {
+    audioSegments,
+    viewport: VIEWPORT_PRESETS.landscape,
+    persistentLayers,
+    theme,
+    customTemplates: doc.customTemplates
+  });
+  const slideBlocks = [];
+  if (shouldIncludeCoverSlide(doc, effectiveOptions) && doc.startBlock) {
+    const coverContext = createTemplateContext(
+      theme,
+      0,
+      Math.max(1, expanded.length + 1),
+      VIEWPORT_PRESETS.landscape
+    );
+    slideBlocks.push({
+      id: "cover-block",
+      startTime: -1,
+      duration: 0,
+      audioSegment: -1,
+      layers: expandCoverBlock(doc.startBlock, coverContext)
+    });
+  }
+  slideBlocks.push(...expanded);
+  if (slideBlocks.length === 0) {
+    slideBlocks.push({ id: "empty-slide", startTime: 0, duration: 0, audioSegment: 0, layers: [] });
   }
-  return markdownDocToPptx(markdownDoc, options);
+  const slideXmls = [];
+  const slideContexts = [];
+  for (let index = 0; index < slideBlocks.length; index++) {
+    if ((index & 31) === 0) effectiveOptions.signal?.throwIfAborted();
+    const ctx = new SlideContext(
+      style,
+      effectiveOptions.images,
+      index,
+      effectiveOptions.allowRelativeHyperlinks ?? false,
+      effectiveOptions.signal
+    );
+    slideXmls.push(buildLayerSlideXml(slideBlocks[index], ctx));
+    slideContexts.push(ctx);
+  }
+  return buildPptxPackage(slideXmls, slideContexts, effectiveOptions);
+}
+function officeTypeface(family, fallback) {
+  const resolved = resolveFontFamily(family, fallback);
+  const first = resolved.split(",")[0]?.trim().replace(/^['"]|['"]$/g, "");
+  return first || fallback;
 }
 function resolveSlideStyle(themeId, options, doc) {
   if (!themeId) {
@@ -142,19 +210,37 @@ function resolveSlideStyle(themeId, options, doc) {
     };
   }
   const theme = resolveThemeForDoc(doc, themeId, options.themeRegistry);
+  return slideStyleFromTheme(theme, options);
+}
+function slideStyleFromTheme(theme, options) {
   const c = theme.colors;
   return {
     background: toOoxmlHex(c.background, "FFFFFF"),
     text: toOoxmlHex(c.text, "333333"),
     titleColor: toOoxmlHex(c.highlight || c.secondary || c.text, "333333"),
     mutedColor: toOoxmlHex(c.textMuted || c.text, "666666"),
-    titleFont: resolveFontFamily(theme.typography?.titleFont, DEFAULT_TITLE_FONT),
-    bodyFont: resolveFontFamily(theme.typography?.bodyFont, options.defaultFont || DEFAULT_FONT),
-    codeFont: resolveFontFamily(theme.typography?.monoFont, DEFAULT_CODE_FONT),
+    titleFont: officeTypeface(theme.typography?.titleFont, DEFAULT_TITLE_FONT),
+    bodyFont: officeTypeface(theme.typography?.bodyFont, options.defaultFont || DEFAULT_FONT),
+    codeFont: officeTypeface(theme.typography?.monoFont, DEFAULT_CODE_FONT),
     codeColor: toOoxmlHex(c.textMuted || c.text, "333333"),
     hasTheme: true
   };
 }
+function shouldIncludeCoverSlide(doc, options) {
+  if (options.includeCoverSlide !== void 0) return options.includeCoverSlide;
+  const frontmatterValue = doc.frontmatter?.["squisq-cover-slide"] ?? doc.frontmatter?.["cover-slide"];
+  if (typeof frontmatterValue === "boolean") return frontmatterValue;
+  if (typeof frontmatterValue === "string") {
+    const normalized = frontmatterValue.trim().toLowerCase();
+    if (normalized === "false" || normalized === "no" || normalized === "off" || normalized === "0") {
+      return false;
+    }
+    if (normalized === "true" || normalized === "yes" || normalized === "on" || normalized === "1") {
+      return true;
+    }
+  }
+  return true;
+}
 function segmentIntoSlides(children, slideBreak) {
   const maxDepth = slideBreak === "h1" ? 1 : slideBreak === "h2" ? 2 : 6;
   const slides = [];
@@ -301,6 +387,438 @@ function buildSlideXml(slide, ctx) {
   const extensionAttrs = transitionXml.includes("p14:") ? ` xmlns:mc="${NS_MC}" xmlns:p14="${NS_PML_2010}" mc:Ignorable="p14"` : "";
   return xmlDeclaration() + `<p:sld xmlns:a="${NS_DRAWINGML}" xmlns:r="${NS_R}" xmlns:p="${NS_PML}"${extensionAttrs}><p:cSld>` + bgXml + `<p:spTree>` + shapes.join("") + `</p:spTree></p:cSld>` + transitionXml + `</p:sld>`;
 }
+function buildLayerSlideXml(block, ctx) {
+  const shapes = [
+    `<p:nvGrpSpPr><p:cNvPr id="1" name=""/><p:cNvGrpSpPr/><p:nvPr/></p:nvGrpSpPr><p:grpSpPr/>`
+  ];
+  const textLayerY = (block.layers ?? []).filter((layer) => layer.type === "text").map((layer) => resolvePositionValue(layer.position.y, 1080));
+  for (let index = 0; index < (block.layers?.length ?? 0); index++) {
+    if ((index & 31) === 0) ctx.signal?.throwIfAborted();
+    const layer = block.layers[index];
+    const currentY = layer.type === "text" ? resolvePositionValue(layer.position.y, 1080) : void 0;
+    const nextTextY = currentY === void 0 ? void 0 : textLayerY.filter((candidate) => candidate > currentY + 1).sort((a, b) => a - b)[0];
+    shapes.push(
+      ...convertLayerToShapes(
+        layer,
+        ctx,
+        nextTextY === void 0 || currentY === void 0 ? void 0 : Math.max(currentY + 1, nextTextY - 8)
+      )
+    );
+  }
+  const bgXml = ctx.style.hasTheme ? `<p:bg><p:bgPr><a:solidFill><a:srgbClr val="${ctx.style.background}"/></a:solidFill><a:effectLst/></p:bgPr></p:bg>` : "";
+  const transitionXml = buildTransitionXml(block.transition);
+  const extensionAttrs = transitionXml.includes("p14:") ? ` xmlns:mc="${NS_MC}" xmlns:p14="${NS_PML_2010}" mc:Ignorable="p14"` : "";
+  return xmlDeclaration() + `<p:sld xmlns:a="${NS_DRAWINGML}" xmlns:r="${NS_R}" xmlns:p="${NS_PML}"${extensionAttrs}><p:cSld>${bgXml}<p:spTree>${shapes.join("")}</p:spTree></p:cSld>` + transitionXml + `</p:sld>`;
+}
+function convertLayerToShapes(layer, ctx, textBottom) {
+  switch (layer.type) {
+    case "text":
+      return [buildLayerTextShape(layer, ctx.allocShapeId(), textBottom)];
+    case "shape":
+      return [buildLayerShape(layer, ctx.allocShapeId())];
+    case "image": {
+      const data = ctx.images?.get(layer.content.src);
+      if (data) {
+        const image = ctx.addImage(layer.content.src, data, layer.content.alt);
+        const rect = toEmuRect(resolveLayerRect(layer.position, 1920, 1080));
+        const embedded = ctx.embeddedImages.find((candidate) => candidate.relId === image);
+        return [
+          buildImageShape(embedded, ctx.allocShapeId(), rect.x, rect.y, rect.width, rect.height)
+        ];
+      }
+      return [
+        buildLayerTextShape(
+          textLayerForPlaceholder(
+            layer.position,
+            `[Image: ${layer.content.alt || layer.content.src}]`,
+            ctx
+          ),
+          ctx.allocShapeId()
+        )
+      ];
+    }
+    case "table":
+      return buildTableLayerShapes(layer, ctx);
+    case "tree":
+      return [
+        buildLayerTextShape(
+          {
+            ...layer,
+            type: "text",
+            content: {
+              text: treeItemsToText(layer.content.items),
+              style: {
+                fontSize: layer.content.style.fontSize,
+                fontFamily: layer.content.style.fontFamily,
+                color: layer.content.style.rowColor,
+                lineHeight: 1.35
+              }
+            }
+          },
+          ctx.allocShapeId()
+        )
+      ];
+    case "path":
+      return buildPathLayerShapes(layer, ctx);
+    case "map": {
+      const staticSrc = layer.content.staticSrc;
+      const data = staticSrc ? ctx.images?.get(staticSrc) : void 0;
+      if (staticSrc && data) {
+        const relId = ctx.addImage(staticSrc, data, "Map");
+        const embedded = ctx.embeddedImages.find((candidate) => candidate.relId === relId);
+        const rect = toEmuRect(resolveLayerRect(layer.position, 1920, 1080));
+        return [
+          buildImageShape(embedded, ctx.allocShapeId(), rect.x, rect.y, rect.width, rect.height)
+        ];
+      }
+      return [
+        buildLayerTextShape(
+          textLayerForPlaceholder(
+            layer.position,
+            `Map: ${layer.content.center.lat.toFixed(4)}, ${layer.content.center.lng.toFixed(4)}`,
+            ctx
+          ),
+          ctx.allocShapeId()
+        )
+      ];
+    }
+    case "video": {
+      const poster = layer.content.posterSrc;
+      const data = poster ? ctx.images?.get(poster) : void 0;
+      if (poster && data) {
+        const relId = ctx.addImage(poster, data, layer.content.alt);
+        const embedded = ctx.embeddedImages.find((candidate) => candidate.relId === relId);
+        const rect = toEmuRect(resolveLayerRect(layer.position, 1920, 1080));
+        return [
+          buildImageShape(embedded, ctx.allocShapeId(), rect.x, rect.y, rect.width, rect.height)
+        ];
+      }
+      return [
+        buildLayerTextShape(
+          textLayerForPlaceholder(
+            layer.position,
+            `[Video: ${layer.content.alt || layer.content.src}]`,
+            ctx
+          ),
+          ctx.allocShapeId()
+        )
+      ];
+    }
+    case "mermaid":
+      return [
+        buildLayerTextShape(
+          textLayerForPlaceholder(layer.position, layer.content.source, ctx),
+          ctx.allocShapeId()
+        )
+      ];
+  }
+}
+function resolvePositionValue(value, dimension) {
+  if (typeof value === "number") return value;
+  if (typeof value === "string") {
+    const trimmed = value.trim();
+    if (trimmed.endsWith("%")) {
+      const percent = Number.parseFloat(trimmed);
+      if (Number.isFinite(percent)) return percent / 100 * dimension;
+    }
+    const numeric = Number.parseFloat(trimmed);
+    if (Number.isFinite(numeric)) return numeric;
+  }
+  return 0;
+}
+function resolveLayerRect(position, defaultWidth, defaultHeight) {
+  const width = Math.max(
+    1,
+    position.width != null ? resolvePositionValue(position.width, 1920) : defaultWidth
+  );
+  const height = Math.max(
+    1,
+    position.height != null ? resolvePositionValue(position.height, 1080) : defaultHeight
+  );
+  let x = resolvePositionValue(position.x, 1920);
+  let y = resolvePositionValue(position.y, 1080);
+  const anchor = position.anchor ?? "top-left";
+  if (anchor === "center") {
+    x -= width / 2;
+    y -= height / 2;
+  } else {
+    if (anchor.endsWith("right")) x -= width;
+    if (anchor.startsWith("bottom")) y -= height;
+  }
+  const clippedX = Math.min(1919, Math.max(0, x));
+  const clippedY = Math.min(1079, Math.max(0, y));
+  const clippedWidth = Math.max(1, Math.min(width - (clippedX - x), 1920 - clippedX));
+  const clippedHeight = Math.max(1, Math.min(height - (clippedY - y), 1080 - clippedY));
+  return { x: clippedX, y: clippedY, width: clippedWidth, height: clippedHeight };
+}
+function toEmuRect(rect) {
+  return {
+    x: Math.round(rect.x / 1920 * SLIDE_WIDTH),
+    y: Math.round(rect.y / 1080 * SLIDE_HEIGHT),
+    width: Math.max(1, Math.round(rect.width / 1920 * SLIDE_WIDTH)),
+    height: Math.max(1, Math.round(rect.height / 1080 * SLIDE_HEIGHT))
+  };
+}
+function buildLayerTextShape(layer, shapeId, maxBottom) {
+  const text = stripIconMarkers(layer.content.text ?? "");
+  const style = layer.content.style;
+  const padding = style.padding ?? 0;
+  const rawLines = text.split("\n");
+  const estimatedWidth = Math.min(
+    1920,
+    Math.max(1, Math.max(...rawLines.map((line) => line.length), 1) * style.fontSize * 0.55)
+  );
+  const boxWidth = layer.position.width != null ? resolvePositionValue(layer.position.width, 1920) : estimatedWidth;
+  const fittedFontSize = rawLines.length === 1 && style.fontSize >= 80 && text.length > 0 ? Math.min(style.fontSize, boxWidth / (text.length * 0.78)) : style.fontSize;
+  const charsPerLine = Math.max(1, Math.floor(boxWidth / Math.max(1, fittedFontSize * 0.58)));
+  const wrappedLineCount = Math.max(
+    1,
+    rawLines.reduce((count, line) => count + Math.max(1, Math.ceil(line.length / charsPerLine)), 0)
+  );
+  const officeFontMetricSlack = fittedFontSize * 0.8;
+  const estimatedHeight = Math.max(
+    fittedFontSize * (style.lineHeight ?? 1.4) * wrappedLineCount + officeFontMetricSlack + padding * 2,
+    fittedFontSize + officeFontMetricSlack + padding * 2
+  );
+  const resolvedRect = resolveLayerRect(layer.position, boxWidth, estimatedHeight);
+  const safeBottom = Math.min(1060, maxBottom ?? 1060);
+  const virtualRect = {
+    ...resolvedRect,
+    y: Math.min(resolvedRect.y, safeBottom - 1),
+    height: Math.max(1, Math.min(resolvedRect.height, safeBottom - resolvedRect.y))
+  };
+  const heightScale = Math.min(1, virtualRect.height / estimatedHeight);
+  const renderedFontSize = Math.max(1, fittedFontSize * heightScale * (heightScale < 1 ? 0.9 : 1));
+  const renderedStyle = renderedFontSize === style.fontSize ? style : { ...style, fontSize: renderedFontSize };
+  const rect = toEmuRect(virtualRect);
+  const align = style.textAlign === "center" ? "ctr" : style.textAlign === "right" ? "r" : "l";
+  const vertical = style.verticalAlign === "bottom" ? "b" : style.verticalAlign === "middle" ? "ctr" : "t";
+  const inset = Math.max(0, Math.round(padding / 1920 * SLIDE_WIDTH));
+  const bodyPr = `<a:bodyPr wrap="square" anchor="${vertical}" vertOverflow="clip" horzOverflow="clip" lIns="${inset}" rIns="${inset}" tIns="${inset}" bIns="${inset}"><a:noAutofit/></a:bodyPr>`;
+  const paragraphs = text.split("\n").map((line) => buildLayerTextParagraph(line, renderedStyle, align)).join("");
+  return `<p:sp><p:nvSpPr><p:cNvPr id="${shapeId}" name="${escapeXml(layer.id)}"/><p:cNvSpPr txBox="1"/><p:nvPr/></p:nvSpPr><p:spPr><a:xfrm><a:off x="${rect.x}" y="${rect.y}"/><a:ext cx="${rect.width}" cy="${rect.height}"/></a:xfrm><a:prstGeom prst="rect"><a:avLst/></a:prstGeom>` + fillXml(style.background, style.backgroundOpacity, style.backgroundGradient) + lineXml(style.borderColor, style.borderWidth, style.borderStyle) + `</p:spPr><p:txBody>${bodyPr}<a:lstStyle/>${paragraphs}</p:txBody></p:sp>`;
+}
+function buildLayerTextParagraph(text, style, align) {
+  const size = Math.max(100, Math.round(style.fontSize * 75));
+  const color = parseCssColor(style.color, "000000");
+  const typeface = officeTypeface(style.fontFamily, DEFAULT_FONT);
+  const runProperties = [
+    `lang="en-US"`,
+    `dirty="0"`,
+    `sz="${size}"`,
+    ...style.fontWeight === "bold" ? ['b="1"'] : [],
+    ...style.fontStyle === "italic" ? ['i="1"'] : []
+  ].join(" ");
+  const lineSpacing = Math.max(1e4, Math.round((style.lineHeight ?? 1.4) * 1e5));
+  return `<a:p><a:pPr algn="${align}"><a:lnSpc><a:spcPct val="${lineSpacing}"/></a:lnSpc></a:pPr><a:r><a:rPr ${runProperties}>${solidColorXml(color)}<a:latin typeface="${escapeXml(typeface)}"/></a:rPr><a:t>${escapeXml(text || " ")}</a:t></a:r></a:p>`;
+}
+function buildLayerShape(layer, shapeId) {
+  const rect = toEmuRect(resolveLayerRect(layer.position, 100, 100));
+  const geometry = layer.content.shape === "circle" ? "ellipse" : layer.content.shape === "line" ? "line" : layer.content.borderRadius ? "roundRect" : "rect";
+  const fill = layer.content.shape === "line" ? "<a:noFill/>" : fillXml(layer.content.fill, layer.content.fillOpacity, layer.content.gradient);
+  const stroke = lineXml(
+    layer.content.stroke ?? (layer.content.shape === "line" ? "#ffffff" : void 0),
+    layer.content.strokeWidth ?? (layer.content.shape === "line" ? 2 : void 0),
+    layer.content.borderStyle
+  );
+  return `<p:sp><p:nvSpPr><p:cNvPr id="${shapeId}" name="${escapeXml(layer.id)}"/><p:cNvSpPr/><p:nvPr/></p:nvSpPr><p:spPr><a:xfrm><a:off x="${rect.x}" y="${rect.y}"/><a:ext cx="${rect.width}" cy="${rect.height}"/></a:xfrm><a:prstGeom prst="${geometry}"><a:avLst/></a:prstGeom>` + fill + stroke + `</p:spPr></p:sp>`;
+}
+function buildTableLayerShapes(layer, ctx) {
+  const rows = [layer.content.headers, ...layer.content.rows];
+  const columnCount = Math.max(1, ...rows.map((row) => row.length));
+  const rowCount = Math.max(1, rows.length);
+  const rect = resolveLayerRect(layer.position, 1920, 1080);
+  const cellWidth = rect.width / columnCount;
+  const cellHeight = rect.height / rowCount;
+  const shapes = [];
+  for (let rowIndex = 0; rowIndex < rows.length; rowIndex++) {
+    for (let columnIndex = 0; columnIndex < columnCount; columnIndex++) {
+      const isHeader = rowIndex === 0;
+      const text = rows[rowIndex]?.[columnIndex] ?? "";
+      shapes.push(
+        buildLayerTextShape(
+          {
+            id: `${layer.id}-${rowIndex}-${columnIndex}`,
+            type: "text",
+            position: {
+              x: rect.x + columnIndex * cellWidth,
+              y: rect.y + rowIndex * cellHeight,
+              width: cellWidth,
+              height: cellHeight
+            },
+            content: {
+              text,
+              style: {
+                fontSize: layer.content.style.fontSize,
+                fontFamily: isHeader ? layer.content.style.headerFontFamily ?? layer.content.style.fontFamily : layer.content.style.fontFamily,
+                fontWeight: isHeader ? "bold" : "normal",
+                color: isHeader ? layer.content.style.headerColor : layer.content.style.cellColor,
+                background: isHeader ? layer.content.style.headerBackground : layer.content.style.cellBackground,
+                borderColor: layer.content.style.borderColor,
+                borderWidth: 1,
+                padding: Math.max(4, layer.content.style.fontSize * 0.25),
+                verticalAlign: "middle",
+                textAlign: layer.content.align?.[columnIndex] ?? "left",
+                lineHeight: 1.2
+              }
+            }
+          },
+          ctx.allocShapeId()
+        )
+      );
+    }
+  }
+  return shapes;
+}
+function treeItemsToText(items, depth = 0) {
+  const lines = [];
+  for (const item of items) {
+    lines.push(
+      `${"  ".repeat(depth)}${item.isDir ? "\u25BE " : "\u2022 "}${item.label}${item.comment ? ` \u2014 ${item.comment}` : ""}`
+    );
+    if (item.children.length > 0) lines.push(treeItemsToText(item.children, depth + 1));
+  }
+  return lines.filter(Boolean).join("\n");
+}
+function buildPathLayerShapes(layer, ctx) {
+  if (layer.content.shapeKind) {
+    const shape = {
+      id: layer.id,
+      type: "shape",
+      position: layer.position,
+      content: {
+        shape: layer.content.shapeKind === "circle" ? "circle" : "rect",
+        fill: layer.content.fill,
+        fillOpacity: layer.content.fillOpacity,
+        gradient: layer.content.gradient,
+        stroke: layer.content.stroke,
+        strokeWidth: layer.content.strokeWidth,
+        borderStyle: layer.content.borderStyle
+      }
+    };
+    return [buildLayerShape(shape, ctx.allocShapeId())];
+  }
+  const numbers = layer.content.d.match(/-?\d+(?:\.\d+)?/g)?.map(Number);
+  if (!numbers || numbers.length < 4) return [];
+  const x1 = numbers[0];
+  const y1 = numbers[1];
+  const x2 = numbers[numbers.length - 2];
+  const y2 = numbers[numbers.length - 1];
+  const rect = toEmuRect({
+    x: Math.min(x1, x2),
+    y: Math.min(y1, y2),
+    width: Math.max(1, Math.abs(x2 - x1)),
+    height: Math.max(1, Math.abs(y2 - y1))
+  });
+  const flipH = x2 < x1 ? ' flipH="1"' : "";
+  const flipV = y2 < y1 ? ' flipV="1"' : "";
+  const stroke = parseCssColor(layer.content.stroke, "FFFFFF");
+  const width = Math.max(1, Math.round((layer.content.strokeWidth ?? 2) * 9525));
+  const head = markerXml("headEnd", layer.content.startMarker);
+  const tail = markerXml("tailEnd", layer.content.endMarker);
+  const dash = dashXml(layer.content.borderStyle, layer.content.dasharray);
+  const shapeId = ctx.allocShapeId();
+  return [
+    `<p:sp><p:nvSpPr><p:cNvPr id="${shapeId}" name="${escapeXml(layer.id)}"/><p:cNvSpPr/><p:nvPr/></p:nvSpPr><p:spPr><a:xfrm${flipH}${flipV}><a:off x="${rect.x}" y="${rect.y}"/><a:ext cx="${rect.width}" cy="${rect.height}"/></a:xfrm><a:prstGeom prst="line"><a:avLst/></a:prstGeom><a:noFill/><a:ln w="${width}">${solidColorXml(stroke)}${dash}${head}${tail}</a:ln></p:spPr></p:sp>`
+  ];
+}
+function textLayerForPlaceholder(position, text, ctx) {
+  return {
+    id: `placeholder-${ctx.allocShapeId()}`,
+    type: "text",
+    position,
+    content: {
+      text,
+      style: {
+        fontSize: 28,
+        fontFamily: ctx.style.bodyFont,
+        fontStyle: "italic",
+        color: `#${ctx.style.mutedColor}`,
+        textAlign: "center",
+        verticalAlign: "middle",
+        padding: 12
+      }
+    }
+  };
+}
+function parseCssColor(color, fallback) {
+  if (!color) return { hex: toOoxmlHex(fallback), alpha: 1e5 };
+  const trimmed = color.trim();
+  if (trimmed === "transparent" || trimmed === "none") return { hex: "000000", alpha: 0 };
+  const hexMatch = /^#?([0-9a-f]{3}|[0-9a-f]{6}|[0-9a-f]{8})$/i.exec(trimmed);
+  if (hexMatch) {
+    const raw = hexMatch[1];
+    const expanded = raw.length === 3 ? raw.split("").map((char) => char + char).join("") : raw;
+    const alpha = expanded.length === 8 ? Math.round(Number.parseInt(expanded.slice(6, 8), 16) / 255 * 1e5) : 1e5;
+    return { hex: expanded.slice(0, 6).toUpperCase(), alpha };
+  }
+  const rgbMatch = /^rgba?\(\s*([\d.]+)\s*,\s*([\d.]+)\s*,\s*([\d.]+)(?:\s*,\s*([\d.]+))?\s*\)$/i.exec(trimmed);
+  if (rgbMatch) {
+    const channel = (value) => Math.max(0, Math.min(255, Math.round(Number(value)))).toString(16).padStart(2, "0");
+    const alpha = rgbMatch[4] ? Math.round(Math.max(0, Math.min(1, Number(rgbMatch[4]))) * 1e5) : 1e5;
+    return {
+      hex: `${channel(rgbMatch[1])}${channel(rgbMatch[2])}${channel(rgbMatch[3])}`.toUpperCase(),
+      alpha
+    };
+  }
+  const named = {
+    black: "000000",
+    white: "FFFFFF",
+    red: "FF0000",
+    blue: "0000FF",
+    green: "008000",
+    gray: "808080",
+    grey: "808080"
+  };
+  return { hex: named[trimmed.toLowerCase()] ?? toOoxmlHex(fallback), alpha: 1e5 };
+}
+function solidColorXml(color) {
+  const alpha = color.alpha < 1e5 ? `<a:alpha val="${color.alpha}"/>` : "";
+  return `<a:solidFill><a:srgbClr val="${color.hex}">${alpha}</a:srgbClr></a:solidFill>`;
+}
+function fillXml(fill, opacity, gradient) {
+  if (gradient) return gradientFillXml(gradient.from, gradient.to, gradient.angle ?? 0, opacity);
+  if (!fill || fill === "none" || fill === "transparent") return "<a:noFill/>";
+  if (fill.includes("gradient(")) {
+    const colors = fill.match(/#[0-9a-f]{3,8}|rgba?\([^)]*\)/gi) ?? [];
+    if (colors.length >= 2) {
+      const angle = Number.parseFloat(
+        /(?:linear-gradient\()\s*([\d.-]+)deg/i.exec(fill)?.[1] ?? "0"
+      );
+      return gradientFillXml(colors[0], colors[colors.length - 1], angle, opacity);
+    }
+  }
+  const color = parseCssColor(fill, "000000");
+  if (opacity !== void 0)
+    color.alpha = Math.round(color.alpha * Math.max(0, Math.min(1, opacity)));
+  return solidColorXml(color);
+}
+function gradientFillXml(from, to, angle, opacity) {
+  const first = parseCssColor(from, "000000");
+  const second = parseCssColor(to, first.hex);
+  if (opacity !== void 0) {
+    const factor = Math.max(0, Math.min(1, opacity));
+    first.alpha = Math.round(first.alpha * factor);
+    second.alpha = Math.round(second.alpha * factor);
+  }
+  const ooxmlAngle = Math.round(((90 - angle) % 360 + 360) % 360 * 6e4);
+  return `<a:gradFill rotWithShape="1"><a:gsLst><a:gs pos="0"><a:srgbClr val="${first.hex}">${first.alpha < 1e5 ? `<a:alpha val="${first.alpha}"/>` : ""}</a:srgbClr></a:gs><a:gs pos="100000"><a:srgbClr val="${second.hex}">${second.alpha < 1e5 ? `<a:alpha val="${second.alpha}"/>` : ""}</a:srgbClr></a:gs></a:gsLst><a:lin ang="${ooxmlAngle}" scaled="1"/></a:gradFill>`;
+}
+function lineXml(color, widthPx, borderStyle) {
+  if (!color || !widthPx || widthPx <= 0) return "<a:ln><a:noFill/></a:ln>";
+  const width = Math.max(1, Math.round(widthPx * 9525));
+  return `<a:ln w="${width}">${solidColorXml(parseCssColor(color, "000000"))}${dashXml(borderStyle)}</a:ln>`;
+}
+function dashXml(style, dasharray) {
+  if (style === "dashed" || dasharray && dasharray !== "none") return '<a:prstDash val="dash"/>';
+  if (style === "dotted") return '<a:prstDash val="dot"/>';
+  return "";
+}
+function markerXml(tag, marker) {
+  if (!marker || marker === "none") return "";
+  const type = marker === "arrow" ? "triangle" : marker === "open" ? "arrow" : marker === "diamond" ? "diamond" : marker === "circle" ? "oval" : "square";
+  return `<a:${tag} type="${type}" w="med" len="med"/>`;
+}
 function buildTransitionXml(transition) {
   if (!transition || transition.type === "cut") return "";
   const child = buildTransitionChildXml(transition);

package/dist/{chunk-LBHZSY7N.js → chunk-YLDQWCHS.js}

@@ -295,6 +295,7 @@ function pptxImportOptionsFrom(options) {
 function defaultFormats() {
   const md = {
     id: "md",
+    templateAnnotationHandling: "preserved",
     label: "Markdown",
     mimeType: MIME.md,
     extensions: [".md", ".markdown"],
@@ -320,6 +321,7 @@ function defaultFormats() {
   };
   const docx = {
     id: "docx",
+    templateAnnotationHandling: "ignored",
     label: "Word (DOCX)",
     mimeType: MIME.docx,
     extensions: [".docx"],
@@ -349,6 +351,7 @@ function defaultFormats() {
   };
   const pdf = {
     id: "pdf",
+    templateAnnotationHandling: "ignored",
     label: "PDF",
     mimeType: MIME.pdf,
     extensions: [".pdf"],
@@ -380,6 +383,7 @@ function defaultFormats() {
   };
   const pptx = {
     id: "pptx",
+    templateAnnotationHandling: "rendered",
     label: "PowerPoint (PPTX)",
     mimeType: MIME.pptx,
     extensions: [".pptx"],
@@ -409,6 +413,7 @@ function defaultFormats() {
   };
   const xlsx = {
     id: "xlsx",
+    templateAnnotationHandling: "ignored",
     label: "Excel (XLSX)",
     mimeType: MIME.xlsx,
     extensions: [".xlsx"],
@@ -432,6 +437,7 @@ function defaultFormats() {
   };
   const csv = {
     id: "csv",
+    templateAnnotationHandling: "ignored",
     label: "CSV",
     mimeType: MIME.csv,
     extensions: [".csv"],
@@ -456,6 +462,7 @@ function defaultFormats() {
   };
   const html = {
     id: "html",
+    templateAnnotationHandling: "rendered",
     label: "HTML (single file)",
     mimeType: MIME.html,
     extensions: [".html", ".htm"],
@@ -485,6 +492,7 @@ function defaultFormats() {
   };
   const htmlzip = {
     id: "htmlzip",
+    templateAnnotationHandling: "rendered",
     label: "HTML (ZIP archive)",
     mimeType: MIME.zip,
     extensions: [".html.zip"],
@@ -508,6 +516,7 @@ function defaultFormats() {
   };
   const epub = {
     id: "epub",
+    templateAnnotationHandling: "ignored",
     label: "EPUB",
     mimeType: MIME.epub,
     extensions: [".epub"],
@@ -529,6 +538,7 @@ function defaultFormats() {
   };
   const dbk = {
     id: "dbk",
+    templateAnnotationHandling: "preserved",
     label: "Squisq container (DBK)",
     mimeType: MIME.zip,
     extensions: [".dbk", ".zip"],

package/dist/{import-C3htUTss.d.ts → import-BhBGQqnz.d.ts}

@@ -71,6 +71,12 @@ interface PptxExportOptions {
     images?: Map<string, ArrayBuffer>;
     /** Permit carefully validated relative hyperlink targets. Default: false. */
     allowRelativeHyperlinks?: boolean;
+    /**
+     * Include the Doc's managed cover (`startBlock`) as slide 1. Defaults to
+     * the document's `squisq-cover-slide` / `cover-slide` setting, then true.
+     * MarkdownDocument export is unaffected because it has no managed cover.
+     */
+    includeCoverSlide?: boolean;
 }
 /**
  * Convert a MarkdownDocument to a .pptx ArrayBuffer.
@@ -79,7 +85,10 @@ declare function markdownDocToPptx(doc: MarkdownDocument, options?: PptxExportOp
 /**
  * Convert a squisq Doc to a .pptx ArrayBuffer.
  *
- * Convenience wrapper: Doc -> MarkdownDocument -> PPTX.
+ * Template-backed Docs are exported through the same canonical slideshow
+ * expansion as the player, then their materialized visual layers are mapped
+ * to native DrawingML shapes. Plain, non-template Docs retain the semantic
+ * Markdown export path for backward compatibility.
  */
 declare function docToPptx(doc: Doc, options?: PptxExportOptions): Promise<ArrayBuffer>;
 

package/dist/index.d.ts

@@ -9,7 +9,7 @@ export { ExtractedFileTheme, InferSourceFormat, InferThemeOptions, InferredFileT
 export { BUILTIN_FORMAT_IDS, BuiltinFormatOptions, ConversionError, ConversionErrorCode, ConversionErrorOptions, ConversionLimits, ConversionResult, ConvertOptions, ConvertSource, DEFAULT_CONVERSION_LIMITS, DbkFormatOptions, FormatDefinition, FormatId, FormatRegistry, MarkdownFormatOptions, NormalizedInput, PreparedConversion, PreparedExportOptions, convert, createRegistry, defaultFormats, defaultRegistry, prepareConversion, resolveConversionLimits } from './registry/index.js';
 export { Z as ZipSafetyError, a as ZipSafetyErrorCode, b as ZipSafetyErrorOptions, c as ZipSafetyLimits } from './zipLimits-BOKCB7qk.js';
 export { H as HtmlExportOptions, a as HtmlImportOptions, c as collectImagePaths, h as htmlToMarkdown, b as htmlToMarkdownDoc, d as htmlToMarkdownDocSync } from './import-C8whCC7_.js';
-export { P as PptxExportOptions, a as PptxImportOptions, d as docToPptx, m as markdownDocToPptx, p as pptxToMarkdownDoc } from './import-C3htUTss.js';
+export { P as PptxExportOptions, a as PptxImportOptions, d as docToPptx, m as markdownDocToPptx, p as pptxToMarkdownDoc } from './import-BhBGQqnz.js';
 export { X as XlsxExportOptions, a as XlsxImportOptions, d as docToXlsx, m as markdownDocToXlsx, x as xlsxToMarkdownDoc } from './export-D9msROJS.js';
 import '@bendyline/squisq/schemas';
 import '@bendyline/squisq/markdown';

package/dist/index.js

@@ -11,7 +11,7 @@ import {
   defaultRegistry,
   prepareConversion,
   resolveConversionLimits
-} from "./chunk-LBHZSY7N.js";
+} from "./chunk-YLDQWCHS.js";
 import {
   inferThemeFromFile
 } from "./chunk-6S6GU3ZG.js";
@@ -33,7 +33,7 @@ import {
   markdownDocToPptx,
   pptxToDoc,
   pptxToMarkdownDoc
-} from "./chunk-IPN56VLW.js";
+} from "./chunk-C22NYDN2.js";
 import "./chunk-TAAENIRB.js";
 import "./chunk-GX7RAUME.js";
 import {

package/dist/pptx/index.d.ts

@@ -1,5 +1,5 @@
-import { a as PptxImportOptions } from '../import-C3htUTss.js';
-export { P as PptxExportOptions, d as docToPptx, m as markdownDocToPptx, b as pptxToContainer, p as pptxToMarkdownDoc } from '../import-C3htUTss.js';
+import { a as PptxImportOptions } from '../import-BhBGQqnz.js';
+export { P as PptxExportOptions, d as docToPptx, m as markdownDocToPptx, b as pptxToContainer, p as pptxToMarkdownDoc } from '../import-BhBGQqnz.js';
 import { Doc } from '@bendyline/squisq/schemas';
 export { A as AnalyzePptxLayoutsOptions, a as AnalyzedLayout, E as ExtractedPlaceholder, b as ExtractedSlideLayout, I as InspectPptxLayoutsOptions, L as LayoutVerdict, P as PptxColorHints, c as PptxLayoutInference, d as PptxLayoutSummary, e as analyzePptxLayouts, i as inspectPptxLayouts } from '../layouts-CTdPlB-u.js';
 import '@bendyline/squisq/markdown';

package/dist/pptx/index.js

@@ -4,7 +4,7 @@ import {
   pptxToContainer,
   pptxToDoc,
   pptxToMarkdownDoc
-} from "../chunk-IPN56VLW.js";
+} from "../chunk-C22NYDN2.js";
 import {
   analyzePptxLayouts,
   inspectPptxLayouts

package/dist/registry/index.d.ts

@@ -3,7 +3,7 @@ import { TransformStyleInput, TransformStyleRegistry } from '@bendyline/squisq/t
 import { ParseOptions, StringifyOptions, MarkdownDocument } from '@bendyline/squisq/markdown';
 import { ContentContainer } from '@bendyline/squisq/storage';
 import { DocxImportOptions, DocxExportOptions } from '../docx/index.js';
-import { a as PptxImportOptions, P as PptxExportOptions } from '../import-C3htUTss.js';
+import { a as PptxImportOptions, P as PptxExportOptions } from '../import-BhBGQqnz.js';
 import { a as XlsxImportOptions, X as XlsxExportOptions } from '../export-D9msROJS.js';
 import { CsvImportOptions, CsvExportOptions } from '../csv/index.js';
 import { PdfImportOptions, PdfExportOptions } from '../pdf/index.js';
@@ -123,12 +123,21 @@ type PreparedExportOptions = Pick<ConvertOptions, 'signal' | 'title' | 'resolveP
 interface PreparedConversion {
     convert(to: FormatId, options?: PreparedExportOptions): Promise<ConversionResult>;
 }
+/**
+ * How a format's exporter treats Squisq template annotations: `rendered`
+ * materializes template visuals into the output, `preserved` keeps annotations
+ * intact for round-tripping, and `ignored` flattens blocks to semantic content
+ * so annotations have no effect on the exported result.
+ */
+type TemplateAnnotationHandling = 'rendered' | 'preserved' | 'ignored';
 /** Describes how a single format imports to / exports from the squisq model. */
 interface FormatDefinition {
     id: FormatId;
     label: string;
     mimeType: string;
     extensions: readonly string[];
+    /** Exporter treatment of template annotations. Absent means unspecified. */
+    templateAnnotationHandling?: TemplateAnnotationHandling;
     /** Import raw bytes to a MarkdownDocument. */
     importDoc?(data: ArrayBuffer, options: ConvertOptions): Promise<MarkdownDocument>;
     /** Import raw bytes to a ContentContainer (markdown + extracted media). */

package/dist/registry/index.js

@@ -7,7 +7,7 @@ import {
   defaultRegistry,
   prepareConversion,
   resolveConversionLimits
-} from "../chunk-LBHZSY7N.js";
+} from "../chunk-YLDQWCHS.js";
 import {
   ConversionError
 } from "../chunk-KXOZMWBS.js";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bendyline/squisq-formats",
-  "version": "2.3.1",
+  "version": "2.3.3",
   "description": "Document format converters — DOCX, PDF, OOXML import/export",
   "license": "MIT",
   "author": "Bendyline",
@@ -107,7 +107,7 @@
   "dependencies": {
     "@pdf-lib/upng": "1.0.1",
     "@xmldom/xmldom": "0.9.10",
-    "@bendyline/squisq": "2.3.1",
+    "@bendyline/squisq": "2.3.3",
     "jszip": "3.10.1",
     "pdf-lib": "1.17.1",
     "pdfjs-dist": "4.10.38"