@openpresentation/opf 0.7.0 → 0.8.0

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

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

package/dist/{chunk-OVPWNQIJ.js → chunk-NEQAPMS2.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,110 @@ 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 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 +549,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 +559,43 @@ 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 quoteBox = (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, quoteBox(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") {
+      const quote = measureQuote(node, box, settings);
+      const reduction = quote.parts.reduce((sum, part) => sum + (part.fit ? (part.requestedFontSize - part.fit.fontSize) / scale : 0), 0);
+      score += reduction + (quote.overflow ? 1e3 : 0);
+      if (penalties) {
+        penalties.fontReduction += reduction;
+        penalties.textOverflow += quote.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 +603,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 +616,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 +650,20 @@ 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 text = quoteLayout ? quoteLayout.parts[0]?.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: quoteLayout ? quoteBox(box) : box,
+          text,
+          textStyle: quoteLayout?.parts[0]?.style ?? styleFor(node.field, node.path),
+          composition: settings,
+          ...quoteLayout ? { quoteLayout } : {}
+        });
         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 +674,29 @@ 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.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-v2",
+    textMeasurement: options.textMeasurement ? "provided" : "estimated",
+    decisions,
+    unmeasuredPayloads: items.filter((item) => !headings.has(item.field) && !item.quoteLayout && !["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 +716,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, layoutQuote, layoutTable, measureText, resolveCanvasDimensions, resolveFontFamilies, resolveTextStyle, tableGrid, tableRowBoundaries, textWidthMeasurer, wrapText };

package/dist/{chunk-IQ727X3E.js → chunk-X22DFHMW.js}

@@ -1,5 +1,5 @@
-import { assertValidPresentation } from './chunk-H7UXKXEJ.js';
-import { resolveFontFamilies, resolveCanvasDimensions, composeSlide, tableRowBoundaries } from './chunk-OVPWNQIJ.js';
+import { assertValidPresentation } from './chunk-HIY26FJV.js';
+import { resolveFontFamilies, resolveCanvasDimensions, composeSlide, tableRowBoundaries } from './chunk-NEQAPMS2.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/composition.d.ts

@@ -97,6 +97,8 @@ interface ComposedItem {
     box: LayoutBox;
     text?: TextFit | RichTextFit | ListFit;
     textStyle?: TextStyle;
+    /** Complete accepted quote internals; consumers must reuse these fits and styles. */
+    quoteLayout?: QuoteLayout;
     /** Effective container settings, including inherited readability constraints. */
     composition: Composition;
 }
@@ -121,6 +123,37 @@ interface ComposedFlow {
     itemCount: number;
     slotCount: number;
 }
+/** Additive penalties in grid-score-v2; lower is preferred. These are not quality percentages. */
+interface CompositionPenalties {
+    cellProportions: number;
+    fontReduction: number;
+    textOverflow: number;
+    tableOverflow: number;
+    smallCells: number;
+    emptySlots: number;
+}
+interface CompositionCandidate {
+    columns: number;
+    rows: number;
+    score: number;
+    penalties: CompositionPenalties;
+}
+interface CompositionDecision {
+    path: string;
+    mode: NonNullable<Composition['mode']> | 'regions';
+    reason: 'lowest-score' | 'configured-mode' | 'promoted-regions';
+    selectedColumns?: number;
+    /** Only candidates actually evaluated by automatic selection, in tie-break order. */
+    candidates: CompositionCandidate[];
+}
+interface CompositionExplanation {
+    algorithm: 'grid-score-v2';
+    /** Provided widths do not establish shaping, glyph coverage or native fidelity. */
+    textMeasurement: 'estimated' | 'provided';
+    decisions: CompositionDecision[];
+    /** Payloads whose complete internal fit is not covered by this scoring model. */
+    unmeasuredPayloads: string[];
+}
 interface SlideComposition {
     width: number;
     height: number;
@@ -130,6 +163,7 @@ interface SlideComposition {
     flows: ComposedFlow[];
     diagnostics: LayoutDiagnostic[];
     composition: Composition;
+    explanation?: CompositionExplanation;
 }
 interface ComposeSlideOptions {
     fonts?: Partial<FontFamilies>;
@@ -138,16 +172,72 @@ interface ComposeSlideOptions {
     height?: number;
     slideIndex?: number;
     layout?: Record<string, unknown>;
+    /** Return candidate scores and coverage without changing the selected geometry. */
+    explain?: boolean;
 }
 declare class OPFCompositionError extends Error {
     readonly diagnostics: LayoutDiagnostic[];
     readonly code = "layout-overflow";
-    constructor(diagnostics: LayoutDiagnostic[]);
+    readonly explanation?: CompositionExplanation;
+    constructor(diagnostics: LayoutDiagnostic[], explanation?: CompositionExplanation);
 }
 /** Deterministic estimate, not a font shaping engine. Preserves explicit line breaks. */
 declare function measureText(text: string, fontSize: number): number;
 declare function wrapText(text: string, width: number, fontSize: number, measure?: MeasureTextWidth): string[];
 declare function fitText(text: string, box: LayoutBox, requestedSize?: number, minFontSize?: number, measure?: MeasureTextWidth): TextFit;
+interface QuoteContent {
+    text: string;
+    attribution?: string;
+    source?: string;
+}
+/** Source and displayed-text ranges are half-open UTF-16 offsets. Added punctuation has no source range. */
+interface QuoteTextSource {
+    path: string;
+    start: number;
+    end: number;
+    outputStart: number;
+    outputEnd: number;
+}
+interface QuoteTextPart {
+    role: 'body' | 'footer';
+    path: string;
+    text: string;
+    sources: QuoteTextSource[];
+    /** Available space, before fitting. Invalid dimensions remain visible in failed results. */
+    box: LayoutBox;
+    requestedFontSize: number;
+    minFontSize: number;
+    requestedStyle: TextStyle;
+    style: TextStyle;
+    /** Absent when the available box is invalid; never fit against an invented one-pixel box. */
+    fit?: TextFit;
+}
+interface QuoteLayoutDiagnostic extends LayoutDiagnostic {
+    reason: 'invalid-part-box' | 'part-outside-cell' | 'text-fit' | 'part-overlap';
+    parts: QuoteTextPart['role'][];
+}
+interface QuoteLayout {
+    algorithm: 'quote-flow-v1';
+    textMeasurement: 'estimated' | 'provided';
+    parts: QuoteTextPart[];
+    diagnostics: QuoteLayoutDiagnostic[];
+    overflow: boolean;
+}
+interface QuoteLayoutOptions {
+    /** Canvas short edge divided by 720. Insets retain the current 18 reference-pixel contract. */
+    scale?: number;
+    fonts?: Partial<FontFamilies>;
+    /** Readability floor in reference pixels, before canvas scaling. */
+    minFontSize?: number;
+    overflow?: Composition['overflow'];
+    path?: string;
+    textMeasurement?: TextMeasurement;
+}
+/**
+ * Allocate and measure quote body/footer space for composition, rendering and export. Callers must
+ * check overflow before accepting the parts. Line boxes are not shaped glyph or native raster bounds.
+ */
+declare function layoutQuote(value: string | QuoteContent, box: LayoutBox, options?: QuoteLayoutOptions): QuoteLayout;
 interface RichTextRun {
     text: string;
     bold?: boolean;
@@ -272,4 +362,4 @@ declare function resolveCanvasDimensions(input: unknown): {
     height: number;
 };
 
-export { type ComposeSlideOptions, type ComposedFlow, type ComposedGroup, type ComposedItem, type Composition, type CompositionTrack, type FontFamilies, type LayoutBox, type LayoutDiagnostic, type ListEntryLayout, type ListFit, type ListText, type ListValue, MAX_COMPOSITION_DEPTH, type MeasureTextWidth, OPFCompositionError, type RichTextFit, type RichTextFragment, type RichTextLine, type RichTextOptions, type RichTextRun, type SlideComposition, type TableBorder, type TableCellLayout, type TableCellStyle, type TableGrid, type TableGridCell, type TableGridIssue, type TableLayout, type TableLayoutOptions, type TableRowLayout, type TextFit, type TextMeasurement, type TextStyle, composeSlide, fitList, fitRichText, fitText, layoutTable, measureText, resolveCanvasDimensions, resolveFontFamilies, resolveTextStyle, tableGrid, tableRowBoundaries, textWidthMeasurer, wrapText };
+export { type ComposeSlideOptions, type ComposedFlow, type ComposedGroup, type ComposedItem, type Composition, type CompositionCandidate, type CompositionDecision, type CompositionExplanation, type CompositionPenalties, type CompositionTrack, type FontFamilies, type LayoutBox, type LayoutDiagnostic, type ListEntryLayout, type ListFit, type ListText, type ListValue, MAX_COMPOSITION_DEPTH, type MeasureTextWidth, OPFCompositionError, type QuoteContent, type QuoteLayout, type QuoteLayoutDiagnostic, type QuoteLayoutOptions, type QuoteTextPart, type QuoteTextSource, type RichTextFit, type RichTextFragment, type RichTextLine, type RichTextOptions, type RichTextRun, type SlideComposition, type TableBorder, type TableCellLayout, type TableCellStyle, type TableGrid, type TableGridCell, type TableGridIssue, type TableLayout, type TableLayoutOptions, type TableRowLayout, type TextFit, type TextMeasurement, type TextStyle, composeSlide, fitList, fitRichText, fitText, layoutQuote, layoutTable, measureText, resolveCanvasDimensions, resolveFontFamilies, resolveTextStyle, tableGrid, tableRowBoundaries, textWidthMeasurer, wrapText };

package/dist/composition.js

@@ -1 +1 @@
-export { MAX_COMPOSITION_DEPTH, OPFCompositionError, composeSlide, fitList, fitRichText, fitText, layoutTable, measureText, resolveCanvasDimensions, resolveFontFamilies, resolveTextStyle, tableGrid, tableRowBoundaries, textWidthMeasurer, wrapText } from './chunk-OVPWNQIJ.js';
+export { MAX_COMPOSITION_DEPTH, OPFCompositionError, composeSlide, fitList, fitRichText, fitText, layoutQuote, layoutTable, measureText, resolveCanvasDimensions, resolveFontFamilies, resolveTextStyle, tableGrid, tableRowBoundaries, textWidthMeasurer, wrapText } from './chunk-NEQAPMS2.js';