@openpresentation/opf 0.7.0 → 0.9.0

package/dist/{chunk-IQ727X3E.js → chunk-3GPZMY2W.js}

@@ -1,5 +1,5 @@
-import { assertValidPresentation } from './chunk-H7UXKXEJ.js';
-import { resolveFontFamilies, resolveCanvasDimensions, composeSlide, tableRowBoundaries } from './chunk-OVPWNQIJ.js';
+import { assertValidPresentation } from './chunk-ZGV6I23P.js';
+import { resolveFontFamilies, resolveCanvasDimensions, composeSlide, tableRowBoundaries } from './chunk-JA5W5TVA.js';
 import { catalogs } from './chunk-TWMRZ43O.js';
 
 // src/pagination.ts
@@ -60,27 +60,32 @@ function leafFor(path, field, value) {
 }
 function paginateSlide(input, options = {}) {
   assertValidPresentation({ slides: [input] });
-  const source = clone(input);
+  let source = clone(input);
   const maxSlides = options.maxSlides ?? 100;
   if (!Number.isInteger(maxSlides) || maxSlides < 1 || maxSlides > 1e4) throw new RangeError("maxSlides must be an integer between 1 and 10000.");
   const minFontSize = options.minFontSize ?? 24;
   if (!Number.isFinite(minFontSize) || minFontSize < 8 || minFontSize > 32) throw new RangeError("Pagination minFontSize must be between 8 and 32.");
   const sourceIndex = options.slideIndex ?? 0, sourceBase = `slides.${sourceIndex}`;
-  const warnOnly = (slide) => {
+  const withReadability = (slide, warn = false) => {
     const result = clone(slide);
-    const visit = (node) => {
-      if (node.composition) node.composition = { ...node.composition, overflow: "warn", minFontSize: Math.max(minFontSize, node.composition.minFontSize ?? 16) };
-      if (Array.isArray(node.blocks)) node.blocks.forEach(visit);
+    const rootMinimum = Math.max(minFontSize, result.composition?.minFontSize ?? options.layout?.composition?.minFontSize ?? 16);
+    result.composition = { ...result.composition, minFontSize: rootMinimum };
+    const visit = (node, inheritedMinimum) => {
+      const minimum = Math.max(minFontSize, node.composition?.minFontSize ?? inheritedMinimum);
+      if (node.composition) node.composition = { ...node.composition, minFontSize: minimum, ...warn ? { overflow: "warn" } : {} };
+      if (Array.isArray(node.blocks)) node.blocks.forEach((child) => {
+        visit(child, minimum);
+      });
     };
-    visit(result);
-    for (const [key, value] of Object.entries(result)) if (isRecord(value) && /^(top|middle|bottom|left|center|right)([+:]|$)/.test(key)) visit(value);
-    result.composition = { ...result.composition, overflow: "warn", minFontSize: Math.max(minFontSize, result.composition?.minFontSize ?? options.layout?.composition?.minFontSize ?? 16) };
+    visit(result, rootMinimum);
+    for (const [key, value] of Object.entries(result)) if (isRecord(value) && /^(top|middle|bottom|left|center|right)([+:]|$)/.test(key)) visit(value, rootMinimum);
     return result;
   };
+  source = withReadability(source);
   let evaluations = 0;
   const geometry = (slide) => {
     if (++evaluations > 2e4) throw new OPFPaginationError("Pagination exceeded its layout evaluation limit. Split the input into smaller sections.");
-    return composeSlide(warnOnly(slide), options);
+    return composeSlide(withReadability(slide, true), options);
   };
   const initial = geometry(source);
   if (!initial.diagnostics.length) return { slides: [source], pages: [{ slideIndex: sourceIndex, mappings: initial.items.map((item) => ({ sourcePath: item.path, outputPath: item.path })) }] };
@@ -150,7 +155,7 @@ function paginateSlide(input, options = {}) {
     const boundaries = leaf.boundaries ?? [0, 1];
     const end = boundaries.at(-1);
     let start = 0;
-    do {
+    while (true) {
       const make = (limit) => ({ leaf, start, end: limit, value: leaf.slice ? leaf.slice(start, limit) : leaf.value });
       let candidate = new Map(selected).set(leaf.path, make(end));
       let issues = diagnosticsFor(candidate);
@@ -187,7 +192,7 @@ function paginateSlide(input, options = {}) {
         start = best;
       } else if (selected.size) finish();
       else throw new OPFPaginationError(`Content at ${leaf.path} cannot fit on an otherwise empty slide. Change its layout or split an atomic item.`, issues);
-    } while (start < end);
+    }
   }
   finish();
   if (!slides.length) throw new OPFPaginationError("No body content can be paginated.", initial.diagnostics);

package/dist/{chunk-OVPWNQIJ.js → chunk-JA5W5TVA.js}

@@ -58,13 +58,15 @@ function textWidthMeasurer(style, measurement) {
   };
 }
 var OPFCompositionError = class extends Error {
-  constructor(diagnostics) {
+  constructor(diagnostics, explanation) {
     super("Slide content does not fit its composition.");
     this.diagnostics = diagnostics;
     this.name = "OPFCompositionError";
+    if (explanation) this.explanation = explanation;
   }
   diagnostics;
   code = "layout-overflow";
+  explanation;
 };
 var fields = ["text", "items", "bullets", "image", "video", "chart", "table", "code", "metric", "quote", "timeline"];
 var headings = /* @__PURE__ */ new Set(["title", "subtitle", "tag"]);
@@ -120,6 +122,258 @@ function fitText(text, box, requestedSize = 25, minFontSize = 16, measure = meas
   }
   return { lines, fontSize, lineHeight: fontSize * 1.22, overflow: lines.length * fontSize * 1.22 > box.height + 0.01 || lines.some((line) => measure(line, fontSize) > box.width + 0.01) };
 }
+function layoutQuote(value, box, options = {}) {
+  const shorthand = typeof value === "string";
+  const quote = shorthand ? { text: value } : value;
+  if (!quote || Array.isArray(quote) || typeof quote.text !== "string" || [quote.attribution, quote.source].some((field) => field !== void 0 && typeof field !== "string")) {
+    throw new TypeError("Quote content must be a string or a text object with optional string attribution/source.");
+  }
+  const scale = options.scale ?? 1, minimum = (options.minFontSize ?? 16) * scale;
+  if (![box.x, box.y, box.width, box.height, scale, minimum].every(Number.isFinite) || box.width <= 0 || box.height <= 0 || scale <= 0 || minimum <= 0) {
+    throw new RangeError("Quote dimensions, scale and minimum font size must be finite and positive.");
+  }
+  if (options.overflow !== void 0 && !["warn", "error"].includes(options.overflow)) throw new RangeError("Invalid quote overflow policy.");
+  const path = options.path ?? "quote";
+  const diagnostics = [], parts = [];
+  const report = (reason, diagnosticPath, roles, message) => diagnostics.push({ code: "text-overflow", reason, path: diagnosticPath, parts: roles, message });
+  const source = (sourcePath, text, outputStart) => ({ path: sourcePath, start: 0, end: text.length, outputStart, outputEnd: outputStart + text.length });
+  const add = (role, text, sources, area, fontSize, fontFamily, fontWeight, partPath) => {
+    const requestedStyle = { fontFamily, fontWeight, italic: false, path: partPath };
+    const style = resolveTextStyle({ ...requestedStyle }, options.textMeasurement);
+    const requestedFontSize = Math.max(fontSize * scale, minimum);
+    const part = { role, path: partPath, text, sources, box: area, requestedFontSize, minFontSize: minimum, requestedStyle, style };
+    parts.push(part);
+    return part;
+  };
+  let footer = "";
+  const footerSources = [];
+  for (const field of ["attribution", "source"]) {
+    const text = quote[field];
+    if (!text) continue;
+    if (footer) footer += " - ";
+    footerSources.push(source(`${path}.${field}`, text, footer.length));
+    footer += text;
+  }
+  const bodyPath = shorthand ? path : `${path}.text`;
+  const body = add(
+    "body",
+    `"${quote.text}"`,
+    [source(bodyPath, quote.text, 1)],
+    { x: box.x + 18, y: box.y + 18, width: box.width - 36, height: box.height - (footer ? 94 : 36) },
+    28,
+    options.fonts?.heading ?? "sans-serif",
+    600,
+    bodyPath
+  );
+  const attribution = footer ? add(
+    "footer",
+    footer,
+    footerSources,
+    { x: box.x + 18, y: box.y + box.height - 58, width: box.width - 36, height: 40 },
+    17,
+    options.fonts?.body ?? "sans-serif",
+    500,
+    path
+  ) : void 0;
+  const usable = (area) => [area.x, area.y, area.width, area.height].every(Number.isFinite) && area.width > 0 && area.height > 0;
+  const fit = (part, area, size = part.requestedFontSize, floor = minimum) => usable(area) ? fitText(part.text, area, size, floor, textWidthMeasurer(part.style, options.textMeasurement)) : void 0;
+  const inner = { x: box.x + 18, y: box.y + 18, width: box.width - 36, height: box.height - 36 };
+  if (!attribution) body.fit = fit(body, body.box);
+  else if (usable(inner) && inner.height > 18) {
+    const available = inner.height - 18;
+    const preferredBody = fit(body, inner, body.requestedFontSize, body.requestedFontSize);
+    const minimumBody = body.requestedFontSize === minimum ? preferredBody : fit(body, inner, minimum, minimum);
+    const preferredBodyHeight = preferredBody.lines.length * preferredBody.lineHeight;
+    const minimumBodyHeight = minimumBody.lines.length * minimumBody.lineHeight;
+    let selected;
+    for (const size of /* @__PURE__ */ new Set([attribution.requestedFontSize, minimum])) {
+      const natural = fit(attribution, inner, size, size);
+      const naturalHeight = natural.lines.length * natural.lineHeight;
+      const preferredHeight = Math.max(40, naturalHeight);
+      const bodyReservation = Math.min(minimumBodyHeight, Math.max(minimumBody.lineHeight, available - natural.lineHeight));
+      const footerHeight = preferredBodyHeight + preferredHeight <= available + 0.01 ? preferredHeight : Math.min(naturalHeight, Math.max(0, available - bodyReservation));
+      const bodyBox = { ...inner, height: available - footerHeight };
+      const footerBox = { ...inner, y: inner.y + inner.height - footerHeight, height: footerHeight };
+      const bodyFit = fit(body, bodyBox);
+      const footerFit = usable(footerBox) ? { ...natural, overflow: natural.overflow || naturalHeight > footerHeight + 0.01 } : void 0;
+      const overflow = !bodyFit || !footerFit || bodyFit.overflow || footerFit.overflow;
+      const score = (body.requestedFontSize - (bodyFit?.fontSize ?? minimum) + attribution.requestedFontSize - size) / scale;
+      if (!selected || !overflow && (selected.overflow || score < selected.score) || overflow && selected.overflow) {
+        selected = { bodyBox, footerBox, bodyFit, footerFit, score, overflow };
+      }
+    }
+    if (selected) {
+      body.box = selected.bodyBox;
+      body.fit = selected.bodyFit;
+      attribution.box = selected.footerBox;
+      attribution.fit = selected.footerFit;
+    }
+  }
+  for (const part of parts) {
+    const area = part.box;
+    if (!part.fit) {
+      report("invalid-part-box", part.path, [part.role], `Quote ${part.role} has no usable space after its insets; increase the cell size or change the arrangement.`);
+    } else if (part.fit.overflow) {
+      report("text-fit", part.path, [part.role], `Quote ${part.role} exceeds its available space at the readability floor; increase its space or change the arrangement.`);
+    }
+    if (usable(area) && (area.x < box.x || area.y < box.y || area.x + area.width > box.x + box.width + 0.01 || area.y + area.height > box.y + box.height + 0.01)) {
+      report("part-outside-cell", part.path, [part.role], `Quote ${part.role} extends outside its cell; increase the cell size or change the arrangement.`);
+    }
+  }
+  if (body?.fit && attribution?.fit && body.box.y + body.fit.lines.length * body.fit.lineHeight > attribution.box.y + 0.01 && attribution.box.y + attribution.fit.lines.length * attribution.fit.lineHeight > body.box.y + 0.01) {
+    report("part-overlap", path, ["body", "footer"], "Quote body and footer line boxes overlap; do not accept this layout without more space.");
+  }
+  if (diagnostics.length && options.overflow === "error") throw new OPFCompositionError(diagnostics);
+  return { algorithm: "quote-flow-v1", textMeasurement: options.textMeasurement ? "provided" : "estimated", parts, diagnostics, overflow: diagnostics.length > 0 };
+}
+function fitCodeText(text, box, size, minimum, step, measure) {
+  const layout = (fontSize) => {
+    const tabWidth = measure(" ", fontSize) * 4;
+    if (!Number.isFinite(tabWidth) || text.includes("	") && tabWidth <= 0) throw new RangeError("Code tabs require a positive finite measured space advance.");
+    const measureLine = (start2, end2, record3 = false) => {
+      let x = 0, offset = start2;
+      const segments = [];
+      for (const [index, segment] of text.slice(start2, end2).split("	").entries()) {
+        if (index) {
+          const next = (Math.floor(x / tabWidth + 1e-9) + 1) * tabWidth;
+          if (record3) segments.push({ kind: "tab", start: offset, end: offset + 1, x, width: next - x });
+          x = next;
+          offset++;
+        }
+        if (segment) {
+          const advance = measure(segment, fontSize);
+          if (record3) segments.push({ kind: "text", start: offset, end: offset + segment.length, x, width: advance });
+          x += advance;
+          offset += segment.length;
+        }
+      }
+      return { width: x, segments };
+    };
+    const width = (start2, end2) => measureLine(start2, end2).width;
+    const sourceLines = [];
+    let start = 0, end = 0;
+    const push = (last, nextStart, boundary) => {
+      sourceLines.push({ start, end: last, nextStart, boundary, ...measureLine(start, last, true) });
+      start = nextStart;
+      end = nextStart;
+    };
+    for (const token of text.matchAll(/\r\n|\r|\n|[^\S\r\n]+|[^\s]+/gu)) {
+      if (token.index === void 0) throw new Error("Missing code token source offset.");
+      const a = token.index, b = a + token[0].length;
+      if (/^[\r\n]/.test(token[0])) {
+        push(a, b, "hard");
+        continue;
+      }
+      if (width(start, b) <= box.width + 0.01) {
+        end = b;
+        continue;
+      }
+      if (end > start && /\S/u.test(text.slice(start, end))) push(a, a, "soft");
+      if (width(start, b) <= box.width + 0.01) {
+        end = b;
+        continue;
+      }
+      for (const segment of textSegments.segment(token[0])) {
+        const next = a + segment.index + segment.segment.length;
+        if (end > start && width(start, next) > box.width + 0.01) push(a + segment.index, a + segment.index, "soft");
+        end = next;
+      }
+    }
+    push(end, end, "end");
+    const lineHeight = fontSize * 1.22;
+    return {
+      lines: sourceLines.map((line) => text.slice(line.start, line.end)),
+      sourceLines,
+      fontSize,
+      lineHeight,
+      tabSize: 4,
+      tabWidth,
+      overflow: sourceLines.length * lineHeight > box.height + 0.01 || sourceLines.some((line) => line.width > box.width + 0.01)
+    };
+  };
+  let result = layout(size);
+  while (result.overflow && size > minimum) {
+    size = Math.max(minimum, size - step);
+    result = layout(size);
+  }
+  return result;
+}
+function layoutCode(value, box, options = {}) {
+  const shorthand = typeof value === "string", code = shorthand ? { source: value } : value;
+  if (!code || Array.isArray(code) || typeof code.source !== "string" || [code.language, code.filename].some((field) => field !== void 0 && typeof field !== "string")) {
+    throw new TypeError("Code content must be a string or source object with optional string language/filename.");
+  }
+  const scale = options.scale ?? 1, minimum = (options.minFontSize ?? 16) * scale;
+  if (![box.x, box.y, box.width, box.height, box.x + box.width, box.y + box.height, scale, minimum, Math.max(18 * scale, minimum) * 1.22].every(Number.isFinite) || box.width <= 0 || box.height <= 0 || scale <= 0 || minimum <= 0) {
+    throw new RangeError("Code dimensions, scale and minimum font size must be finite and positive.");
+  }
+  if (options.overflow !== void 0 && !["warn", "error"].includes(options.overflow)) throw new RangeError("Invalid code overflow policy.");
+  const path = options.path ?? "code", inner = { x: box.x + 18, y: box.y + 18, width: box.width - 36, height: box.height - 36 };
+  const parts = [], diagnostics = [];
+  const add = (role, text, partPath, generated = false) => {
+    const requestedStyle = { fontFamily: options.fonts?.code ?? "monospace", fontWeight: role === "body" ? 400 : 700, italic: false, path: partPath };
+    const part = {
+      role,
+      path: partPath,
+      text,
+      sources: generated ? [] : [{ path: partPath, start: 0, end: text.length }],
+      generated,
+      box: { ...inner },
+      requestedFontSize: Math.max((role === "body" ? 18 : 14) * scale, minimum),
+      minFontSize: minimum,
+      requestedStyle,
+      style: resolveTextStyle({ ...requestedStyle }, options.textMeasurement)
+    };
+    parts.push(part);
+    return part;
+  };
+  if (code.filename) add("filename", code.filename, `${path}.filename`);
+  if (code.language) add("language", code.language, `${path}.language`);
+  if (!parts.length) add("language", "code", path, true);
+  const body = add("body", code.source, shorthand ? path : `${path}.source`), headers = parts.filter((part) => part !== body);
+  const usable = (area) => [area.x, area.y, area.width, area.height].every(Number.isFinite) && area.width > 0 && area.height > 0;
+  const fit = (part, area, size = part.requestedFontSize, floor = minimum) => usable(area) ? fitCodeText(part.text, area, size, floor, scale, textWidthMeasurer(part.style, options.textMeasurement)) : void 0;
+  if (usable(inner)) {
+    const combinations = headers.reduce((choices, part) => choices.flatMap((choice) => [.../* @__PURE__ */ new Set([part.requestedFontSize, minimum])].map((size) => [...choice, { part, size }])), [[]]);
+    let selected;
+    for (const combination of combinations) {
+      let y = inner.y;
+      const allocations = [];
+      for (const [index, { part, size }] of combination.entries()) {
+        const measured = fitCodeText(part.text, inner, size, size, scale, textWidthMeasurer(part.style, options.textMeasurement));
+        const area2 = { ...inner, y, height: measured.lines.length * measured.lineHeight };
+        allocations.push({ part, box: area2, fit: usable(area2) ? { ...measured, overflow: measured.sourceLines.some((line) => line.width > area2.width + 0.01) } : void 0 });
+        y += area2.height + (index < headers.length - 1 ? 8 : 12);
+      }
+      const area = { ...inner, y, height: inner.y + inner.height - y };
+      allocations.push({ part: body, box: area, fit: fit(body, area) });
+      const overflow = allocations.some(({ box: box2, fit: fit2 }) => !fit2 || fit2.overflow || !usable(box2) || box2.y + box2.height > inner.y + inner.height + 0.01);
+      const score = allocations.reduce((sum, { part, fit: fit2 }) => sum + (part.requestedFontSize - (fit2?.fontSize ?? minimum)) / scale, 0);
+      if (!selected || !overflow && (selected.overflow || score < selected.score) || overflow && selected.overflow) selected = { allocations, score, overflow };
+    }
+    if (selected) for (const { part, box: box2, fit: fit2 } of selected.allocations) {
+      part.box = box2;
+      part.fit = fit2;
+    }
+  }
+  const report = (reason, part, roles, message) => diagnostics.push({ code: "text-overflow", reason, path: part.path, parts: roles, message });
+  for (const part of parts) {
+    if (!part.fit) report("invalid-part-box", part, [part.role], `Code ${part.role} has no usable space after metadata and insets; increase the cell or change the arrangement.`);
+    else if (part.fit.overflow) report("text-fit", part, [part.role], `Code ${part.role} exceeds its space at the readability floor; increase its space or change the arrangement.`);
+    const area = part.box;
+    if (usable(area) && (area.x < box.x || area.y < box.y || area.x + area.width > box.x + box.width + 0.01 || area.y + area.height > box.y + box.height + 0.01)) {
+      report("part-outside-cell", part, [part.role], `Code ${part.role} extends outside its cell; increase the cell or change the arrangement.`);
+    }
+  }
+  for (const [index, first] of parts.entries()) {
+    const second = parts[index + 1];
+    if (first.fit && second?.fit && first.box.y + first.fit.lines.length * first.fit.lineHeight > second.box.y + 0.01) {
+      report("part-overlap", first, [first.role, second.role], "Code part line boxes overlap; do not accept this layout without more space.");
+    }
+  }
+  if (diagnostics.length && options.overflow === "error") throw new OPFCompositionError(diagnostics);
+  return { algorithm: "code-flow-v1", textMeasurement: options.textMeasurement ? "provided" : "estimated", parts, diagnostics, overflow: diagnostics.length > 0 };
+}
 function fitRichText(input, box, requestedSize = 25, minFontSize = 16, options = { style: { fontFamily: "sans-serif", fontWeight: 400 } }) {
   if (![box.width, box.height, requestedSize, minFontSize].every((value) => Number.isFinite(value) && value > 0)) throw new RangeError("Rich text dimensions and font sizes must be finite and positive.");
   const layout = richTextLayouter(input, box, requestedSize, options), minimum = Math.min(requestedSize, minFontSize);
@@ -443,6 +697,7 @@ function composeSlide(input, options = {}) {
   const regions = Object.keys(slide).filter((key) => regionParts(key)).sort();
   const pending = regions.length ? regions.flatMap((key) => collect(record2(slide[key]), `${path}.${key}`).map((item) => ({ ...item, region: regionParts(key) }))) : Array.isArray(slide.blocks) ? slide.blocks.flatMap((block, index) => collect(record2(block), `${path}.blocks.${index}`)) : collect(slide, path);
   const groups = [], flows = [];
+  const decisions = options.explain ? [] : void 0;
   const inheritedSettings = (parent, own = {}) => ({
     minFontSize: parent.minFontSize,
     ...own,
@@ -452,15 +707,50 @@ function composeSlide(input, options = {}) {
     const amount = (settings.padding ?? 0) * Math.min(box.width, box.height);
     return { x: box.x + amount, y: box.y + amount, width: box.width - amount * 2, height: box.height - amount * 2 };
   };
-  const leafScore = (node, box, settings) => {
+  const acceptedBox = (box) => ({ x: round(box.x), y: round(box.y), width: round(box.width), height: round(box.height) });
+  const measureQuote = (node, box, settings) => layoutQuote(node.value, acceptedBox(box), {
+    fonts: options.fonts,
+    textMeasurement: options.textMeasurement,
+    scale,
+    minFontSize: settings.minFontSize,
+    path: node.path
+  });
+  const measureCode = (node, box, settings) => layoutCode(node.value, acceptedBox(box), {
+    fonts: options.fonts,
+    textMeasurement: options.textMeasurement,
+    scale,
+    minFontSize: settings.minFontSize,
+    path: node.path
+  });
+  const leafScore = (node, box, settings, penalties) => {
     const text = contentText(node.field, node.value);
     let score = Math.abs(Math.log(box.width / box.height / 1.6));
-    if (text) {
+    if (penalties) penalties.cellProportions += score;
+    if (node.field === "quote" || node.field === "code") {
+      const internal = node.field === "quote" ? measureQuote(node, box, settings) : measureCode(node, box, settings);
+      const reduction = internal.parts.reduce((sum, part) => sum + (part.fit ? (part.requestedFontSize - part.fit.fontSize) / scale : 0), 0);
+      score += reduction + (internal.overflow ? 1e3 : 0);
+      if (penalties) {
+        penalties.fontReduction += reduction;
+        penalties.textOverflow += internal.overflow ? 1e3 : 0;
+      }
+    } else if (text) {
       const fit = fitContent(node.field, node.value, text, box, 25 * scale, (settings.minFontSize ?? 16) * scale, node.path);
-      score += (25 * scale - fit.fontSize) / scale + (fit.overflow ? 1e3 : 0);
+      const reduction = (25 * scale - fit.fontSize) / scale;
+      score += reduction + (fit.overflow ? 1e3 : 0);
+      if (penalties) {
+        penalties.fontReduction += reduction;
+        penalties.textOverflow += fit.overflow ? 1e3 : 0;
+      }
+    }
+    if (node.field === "table" && tableOverflows(node.value, box, scale, settings, options, node.path)) {
+      score += 1e3;
+      if (penalties) penalties.tableOverflow += 1e3;
+    }
+    if (box.width < 100 * scale || box.height < 60 * scale) {
+      score += 100;
+      if (penalties) penalties.smallCells += 100;
     }
-    if (node.field === "table" && tableOverflows(node.value, box, scale, settings, options, node.path)) score += 1e3;
-    if (box.width < 100 * scale || box.height < 60 * scale) score += 100;
     return score;
   };
   const modeFor = (settings) => settings.mode ?? "auto";
@@ -468,12 +758,12 @@ function composeSlide(input, options = {}) {
     const mode = modeFor(settings);
     return mode === "column" ? 1 : mode === "row" ? Math.max(1, count) : settings.columns ?? Math.max(1, Math.min(count, Math.ceil(Math.sqrt(count * area.width / area.height / 1.6))));
   };
-  const scoreNode = (node, box, settings) => {
-    if (!node.children) return leafScore(node, box, settings);
+  const scoreNode = (node, box, settings, penalties) => {
+    if (!node.children) return leafScore(node, box, settings, penalties);
     const own = inheritedSettings(settings, node.composition), area = inset(box, own);
     const cols = defaultColumns(node.children.length, area, own);
     const boxes = gridBoxes(node.children.length, area, cols, (own.gap ?? 1 / 30) * Math.min(box.width, box.height), own.weights ?? [], modeFor(own) === "column");
-    return node.children.reduce((score, child, index) => score + scoreNode(child, boxes[index], own), 0);
+    return node.children.reduce((score, child, index) => score + scoreNode(child, boxes[index], own, penalties), 0);
   };
   const arrange = (nodes, area, settings, reserved = 0, gapOverride, containerPath = path) => {
     const count = Math.max(nodes.length, reserved);
@@ -481,17 +771,29 @@ function composeSlide(input, options = {}) {
     const mode = modeFor(settings), localGap = (settings.gap ?? 1 / 30) * Math.min(area.width, area.height);
     const actualGap = gapOverride ?? (settings === rootSettings ? gap : localGap);
     let cols = defaultColumns(count, area, settings);
-    if (mode === "auto" && !nodes.some((node) => node.region)) {
+    const hasRegions = nodes.some((node) => node.region);
+    const candidates = decisions ? [] : void 0;
+    if (mode === "auto" && !hasRegions) {
       let best = Infinity;
       for (let candidate = 1; candidate <= Math.min(count, settings.columns ?? 6); candidate++) {
         const boxes2 = gridBoxes(count, area, candidate, actualGap, settings.weights ?? [], false);
-        const score = nodes.reduce((sum, node, i) => sum + scoreNode(node, boxes2[i], settings), 0) + (Math.ceil(count / candidate) * candidate - count) * 2;
+        const emptySlots = (Math.ceil(count / candidate) * candidate - count) * 2;
+        const penalties = candidates ? { cellProportions: 0, fontReduction: 0, textOverflow: 0, tableOverflow: 0, smallCells: 0, emptySlots } : void 0;
+        const score = nodes.reduce((sum, node, i) => sum + scoreNode(node, boxes2[i], settings, penalties), 0) + emptySlots;
+        if (penalties && candidates) candidates.push({ columns: candidate, rows: Math.ceil(count / candidate), score, penalties });
         if (score < best) {
           best = score;
           cols = candidate;
         }
       }
     }
+    decisions?.push({
+      path: containerPath,
+      mode: hasRegions ? "regions" : mode,
+      reason: hasRegions ? "promoted-regions" : mode === "auto" ? "lowest-score" : "configured-mode",
+      ...hasRegions ? {} : { selectedColumns: cols },
+      candidates: candidates ?? []
+    });
     const grid = gridGeometry(count, area, cols, actualGap, settings.weights ?? [], mode === "column");
     const boxes = grid.boxes;
     if (!nodes.some((node) => node.region)) flows.push({ path: containerPath, box: { ...area }, composition: { ...settings }, columns: grid.columns, rows: grid.rows, gap: grid.gap, itemCount: nodes.length, slotCount: count });
@@ -503,8 +805,23 @@ function composeSlide(input, options = {}) {
         arrange(node.children, inner, own, 0, (own.gap ?? 1 / 30) * Math.min(box.width, box.height), node.path);
       } else {
         const textValue = contentText(node.field, node.value);
-        const text = textValue !== void 0 ? fitContent(node.field, node.value, textValue, box, 25 * scale, (settings.minFontSize ?? 16) * scale, node.path) : void 0;
-        items.push({ path: node.path, field: node.field, type: node.type, value: node.value, payload: node.payload, box, text, textStyle: styleFor(node.field, node.path), composition: settings });
+        const quoteLayout = node.field === "quote" ? measureQuote(node, box, settings) : void 0;
+        const codeLayout = node.field === "code" ? measureCode(node, box, settings) : void 0;
+        const internal = quoteLayout ?? codeLayout, body = internal?.parts.find((part) => part.role === "body");
+        const text = internal ? body?.fit : textValue !== void 0 ? fitContent(node.field, node.value, textValue, box, 25 * scale, (settings.minFontSize ?? 16) * scale, node.path) : void 0;
+        items.push({
+          path: node.path,
+          field: node.field,
+          type: node.type,
+          value: node.value,
+          payload: node.payload,
+          box: internal ? acceptedBox(box) : box,
+          text,
+          textStyle: body?.style ?? styleFor(node.field, node.path),
+          composition: settings,
+          ...quoteLayout ? { quoteLayout } : {},
+          ...codeLayout ? { codeLayout } : {}
+        });
         if (box.width < 100 * scale || box.height < 60 * scale) diagnostics.push({ code: "small-cell", path: node.path, message: "Content cell is too small for comfortable reading; use fewer blocks or a different composition." });
       }
     });
@@ -515,13 +832,30 @@ function composeSlide(input, options = {}) {
   for (const item of items) {
     for (const key of ["x", "y", "width", "height"]) item.box[key] = round(item.box[key]);
     if (item.field === "table" && tableOverflows(item.value, item.box, scale, item.composition, options, item.path)) diagnostics.push({ code: "text-overflow", path: item.path, message: "Table cells do not fit; use fewer rows, fewer columns, or split the table across slides." });
-    if (item.text?.overflow) diagnostics.push({ code: "text-overflow", path: item.path, message: "Text exceeds its cell at the minimum font size; shorten it, increase its space, or split the slide." });
+    if (item.quoteLayout) diagnostics.push(...item.quoteLayout.diagnostics);
+    else if (item.codeLayout) diagnostics.push(...item.codeLayout.diagnostics);
+    else if (item.text?.overflow) diagnostics.push({ code: "text-overflow", path: item.path, message: "Text exceeds its cell at the minimum font size; shorten it, increase its space, or split the slide." });
   }
   for (const group of groups) for (const box of [group.box, group.contentBox]) for (const key of ["x", "y", "width", "height"]) box[key] = round(box[key]);
   const strictPaths = new Set(items.filter((item) => item.composition.overflow === "error").map((item) => item.path));
-  const failures = diagnostics.filter((diagnostic) => strictPaths.has(diagnostic.path));
-  if (failures.length) throw new OPFCompositionError(failures);
-  return { width, height, contentBox, items, groups, flows, diagnostics, composition };
+  const failures = diagnostics.filter((diagnostic) => {
+    let path2 = diagnostic.path;
+    while (path2) {
+      if (strictPaths.has(path2)) return true;
+      const boundary = path2.lastIndexOf(".");
+      if (boundary < 0) break;
+      path2 = path2.slice(0, boundary);
+    }
+    return false;
+  });
+  const explanation = decisions ? {
+    algorithm: "grid-score-v3",
+    textMeasurement: options.textMeasurement ? "provided" : "estimated",
+    decisions,
+    unmeasuredPayloads: items.filter((item) => !headings.has(item.field) && !item.quoteLayout && !item.codeLayout && !["text", "items", "bullets", "table"].includes(item.field)).map((item) => item.path)
+  } : void 0;
+  if (failures.length) throw new OPFCompositionError(failures, explanation);
+  return { width, height, contentBox, items, groups, flows, diagnostics, composition, ...explanation ? { explanation } : {} };
 }
 function resolveCanvasDimensions(input) {
   const presets = {
@@ -541,4 +875,4 @@ function resolveCanvasDimensions(input) {
   return { width, height };
 }
 
-export { MAX_COMPOSITION_DEPTH, OPFCompositionError, composeSlide, fitList, fitRichText, fitText, layoutTable, measureText, resolveCanvasDimensions, resolveFontFamilies, resolveTextStyle, tableGrid, tableRowBoundaries, textWidthMeasurer, wrapText };
+export { MAX_COMPOSITION_DEPTH, OPFCompositionError, composeSlide, fitList, fitRichText, fitText, layoutCode, layoutQuote, layoutTable, measureText, resolveCanvasDimensions, resolveFontFamilies, resolveTextStyle, tableGrid, tableRowBoundaries, textWidthMeasurer, wrapText };

package/dist/{chunk-H7UXKXEJ.js → chunk-ZGV6I23P.js}

@@ -1,4 +1,4 @@
-import { MAX_COMPOSITION_DEPTH, tableGrid } from './chunk-OVPWNQIJ.js';
+import { MAX_COMPOSITION_DEPTH, tableGrid } from './chunk-JA5W5TVA.js';
 import { schemas } from './chunk-GQSK3T7X.js';
 import { catalogSchemaNames } from './chunk-TWMRZ43O.js';
 import Ajv2020 from 'ajv/dist/2020.js';