@openpresentation/opf 0.6.0 → 0.8.0

package/dist/{chunk-C7GKRLI6.js → chunk-NEQAPMS2.js}

@@ -1,8 +1,45 @@
+// src/table.ts
+var record = (value) => value && typeof value === "object" && !Array.isArray(value) ? value : {};
+function tableGrid(value, path = "table") {
+  const table = record(value), hasHeaders = Array.isArray(table.columns) && table.columns.length > 0;
+  const values = [...hasHeaders ? [table.columns] : [], ...Array.isArray(table.rows) ? table.rows : []];
+  const columnCount = values.reduce((count, row) => Math.max(count, Array.isArray(row) ? row.length : 0), 1), rowCount = values.length;
+  const owners = Array.from({ length: rowCount }, () => Array(columnCount));
+  const rows2 = Array.from({ length: rowCount }, () => []), issues = [];
+  const location = (r, c) => `${path}.${hasHeaders && r === 0 ? "columns" : `rows.${r - Number(hasHeaders)}`}.${c}`;
+  for (let r = 0; r < rowCount; r++) for (let c = 0; c < columnCount; c++) {
+    const input = values[r]?.[c], cellPath = location(r, c), existing = owners[r][c];
+    if (existing) {
+      if (input !== null) issues.push({ path: cellPath, message: "A position covered by a spanning cell must explicitly contain null; content cannot be hidden." });
+      continue;
+    }
+    const object = record(input), styled = Object.hasOwn(object, "value");
+    const rowSpan = styled ? object.rowSpan ?? 1 : 1, colSpan = styled ? object.colSpan ?? 1 : 1;
+    if (!Number.isSafeInteger(rowSpan) || !Number.isSafeInteger(colSpan) || rowSpan < 1 || colSpan < 1 || r + rowSpan > rowCount || c + colSpan > columnCount || hasHeaders && r === 0 && rowSpan > 1) {
+      issues.push({ path: cellPath, message: "Cell spans must be positive integers within the table grid and cannot cross from headers into body rows." });
+      continue;
+    }
+    const cell = { input, value: styled ? object.value : input, style: styled ? record(object.style) : {}, row: r, column: c, rowSpan, colSpan, header: hasHeaders && r === 0, path: cellPath, valuePath: styled ? cellPath + ".value" : cellPath };
+    rows2[r].push(cell);
+    for (let y = r; y < r + rowSpan; y++) for (let x = c; x < c + colSpan; x++) {
+      if (owners[y][x]) issues.push({ path: cellPath, message: "Cell spans cannot overlap another spanning cell." });
+      else owners[y][x] = cell;
+    }
+  }
+  return { rows: rows2, columnCount, rowCount, hasHeaders, owners, issues };
+}
+function tableRowBoundaries(value) {
+  const grid = tableGrid(value), offset = Number(grid.hasHeaders), count = grid.rowCount - offset;
+  const allowed = new Set(Array.from({ length: count + 1 }, (_, i) => i));
+  for (const row of grid.rows) for (const cell of row) if (!cell.header) for (let r = 1; r < cell.rowSpan; r++) allowed.delete(cell.row - offset + r);
+  return [...allowed];
+}
+
 // src/composition.ts
 var MAX_COMPOSITION_DEPTH = 32;
 function resolveFontFamilies(input) {
-  const scheme = record(input);
-  const family = (value) => typeof value === "string" ? value : record(value).family;
+  const scheme = record2(input);
+  const family = (value) => typeof value === "string" ? value : record2(value).family;
   return {
     heading: family(scheme.heading) ?? scheme.major ?? scheme.minor ?? "Roboto",
     body: family(scheme.body) ?? scheme.minor ?? scheme.major ?? "Roboto",
@@ -21,19 +58,21 @@ 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"]);
 var rows = ["top", "middle", "bottom"];
 var columns = ["left", "center", "right"];
-var record = (value) => value && typeof value === "object" && !Array.isArray(value) ? value : {};
+var record2 = (value) => value && typeof value === "object" && !Array.isArray(value) ? value : {};
 var kind = (field) => field === "items" || field === "bullets" ? "list" : field;
 var round = (value) => Math.round(value * 1e6) / 1e6 || value;
 var textSegments = new Intl.Segmenter("und", { granularity: "grapheme" });
@@ -83,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);
@@ -236,53 +379,61 @@ function fitList(input, box, requestedSize = 25, minFontSize = 16, options = { s
 function contentText(field, value) {
   if (field === "text" || headings.has(field)) return flatten(value);
   if (field === "items" || field === "bullets") return (Array.isArray(value) ? value : [value]).map((item) => {
-    const entry = record(item);
+    const entry = record2(item);
     return `\u2022 ${flatten(item)}${entry.description ? `
 ${flatten(entry.description)}` : ""}`;
   }).join("\n");
-  if (field === "code") return flatten(record(value).source ?? value);
-  if (field === "quote") return flatten(record(value).text ?? value);
+  if (field === "code") return flatten(record2(value).source ?? value);
+  if (field === "quote") return flatten(record2(value).text ?? value);
   return void 0;
 }
 function layoutTable(value, box, options = {}) {
   const scale = options.scale ?? 1, requested = 15 * scale, 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("Table dimensions, scale and font sizes must be finite and positive.");
-  const table = record(value), headers = Array.isArray(table.columns) && table.columns.length > 0;
-  const values = [...headers ? [table.columns] : [], ...Array.isArray(table.rows) ? table.rows : []];
-  const columnCount = Math.max(1, ...values.map((row) => row.length)), cellWidth = box.width / columnCount;
-  const width = Math.max(scale, cellWidth - 20 * scale), padding = 12 * scale;
+  const grid = tableGrid(value, options.path ?? "table");
+  if (grid.issues.length) throw new RangeError(`${grid.issues[0].path}: ${grid.issues[0].message}`);
+  const columnCount = grid.columnCount, cellWidth = box.width / columnCount;
+  const cells = grid.rows.flat().map((cell) => {
+    const padding = { top: 8, right: 10, bottom: 4, left: 10, ...cell.style.padding };
+    const width = cellWidth * cell.colSpan - (padding.left + padding.right) * scale;
+    const style = { fontFamily: options.fontFamily ?? "sans-serif", fontWeight: cell.header ? 700 : 400, italic: false, path: cell.valuePath };
+    return { ...cell, padding, width, textStyle: style };
+  });
   const fitCell = (cell, height, min) => {
-    const textBox = { width, height: Math.max(scale, height) };
-    return Array.isArray(cell.value) ? fitRichText(cell.value, textBox, requested, min, { style: cell.style, textMeasurement: options.textMeasurement, uniformLineHeight: true }) : fitText(flatten(cell.value), textBox, requested, min, textWidthMeasurer(resolveTextStyle(cell.style, options.textMeasurement), options.textMeasurement));
+    const textBox = { width: Math.max(scale, cell.width), height: Math.max(scale, height) };
+    return Array.isArray(cell.value) ? fitRichText(cell.value, textBox, requested, min, { style: cell.textStyle, textMeasurement: options.textMeasurement, uniformLineHeight: true }) : fitText(flatten(cell.value), textBox, requested, min, textWidthMeasurer(resolveTextStyle(cell.textStyle, options.textMeasurement), options.textMeasurement));
   };
   const textHeight = (fit) => "height" in fit ? fit.height : fit.lines.length * fit.lineHeight;
-  const measured = values.map((row, index) => {
-    const header = headers && index === 0;
-    const cells = Array.from({ length: columnCount }, (_, column) => {
-      const path = `${options.path ?? "table"}.${header ? "columns" : `rows.${index - Number(headers)}`}.${column}`;
-      return { value: row[column], path, header, style: { fontFamily: options.fontFamily ?? "sans-serif", fontWeight: header ? 700 : 400, italic: false, path } };
-    });
-    const natural2 = Math.max(...cells.map((cell) => textHeight(fitCell(cell, scale, requested)) + padding));
-    const preferred2 = Math.max(54 * scale, natural2);
-    const needed2 = Math.min(preferred2, Math.max(...cells.map((cell) => textHeight(fitCell(cell, scale, minimum)) + padding)));
-    return { cells, preferred: preferred2, natural: natural2, needed: needed2 };
-  });
-  const preferred = measured.reduce((sum, row) => sum + row.preferred, 0), natural = measured.reduce((sum, row) => sum + row.natural, 0), needed = measured.reduce((sum, row) => sum + row.needed, 0);
-  let y = box.y, overflow = cellWidth <= 20 * scale;
-  const rows2 = measured.map((row) => {
-    const height = preferred <= box.height ? row.preferred : natural <= box.height ? row.natural + (row.preferred - row.natural) * (box.height - natural) / Math.max(Number.EPSILON, preferred - natural) : needed <= box.height ? row.needed + (row.natural - row.needed) * (box.height - needed) / Math.max(Number.EPSILON, natural - needed) : row.needed * box.height / needed;
-    const rowBox = { x: box.x, y, width: box.width, height };
-    const cells = row.cells.map((cell, column) => {
-      const cellBox = { x: box.x + column * cellWidth, y, width: cellWidth, height };
-      const textBox = { x: cellBox.x + 10 * scale, y: y + 8 * scale, width, height: Math.max(scale, height - padding) };
-      const fit = fitCell(cell, textBox.height, minimum);
-      overflow ||= height <= padding || fit.overflow;
-      return { value: cell.value, path: cell.path, header: cell.header, rich: Array.isArray(cell.value), box: cellBox, textBox, textStyle: resolveTextStyle(cell.style, options.textMeasurement), fit };
-    });
-    y += height;
-    return { box: rowBox, cells };
-  });
-  return { rows: rows2, columnCount, height: y - box.y, overflow };
+  const required = (cell, size) => textHeight(fitCell(cell, scale, size)) + (cell.padding.top + cell.padding.bottom) * scale;
+  const natural = Array(grid.rowCount).fill(0), needed = Array(grid.rowCount).fill(0);
+  for (const cell of cells) if (cell.rowSpan === 1) {
+    natural[cell.row] = Math.max(natural[cell.row], required(cell, requested));
+    needed[cell.row] = Math.max(needed[cell.row], required(cell, minimum));
+  }
+  for (const cell of cells) if (cell.rowSpan > 1) for (const [heights2, size] of [[natural, requested], [needed, minimum]]) {
+    const current = heights2.slice(cell.row, cell.row + cell.rowSpan).reduce((a, b) => a + b, 0);
+    const extra = Math.max(0, required(cell, size) - current) / cell.rowSpan;
+    for (let r = cell.row; r < cell.row + cell.rowSpan; r++) heights2[r] += extra;
+  }
+  const preferred = natural.map((height) => Math.max(54 * scale, height));
+  for (let r = 0; r < needed.length; r++) needed[r] = Math.min(preferred[r], needed[r]);
+  const sum = (values) => values.reduce((a, b) => a + b, 0);
+  const preferredTotal = sum(preferred), naturalTotal = sum(natural), neededTotal = sum(needed);
+  const heights = preferred.map((height, r) => preferredTotal <= box.height ? height : naturalTotal <= box.height ? natural[r] + (height - natural[r]) * (box.height - naturalTotal) / Math.max(Number.EPSILON, preferredTotal - naturalTotal) : neededTotal <= box.height ? needed[r] + (natural[r] - needed[r]) * (box.height - neededTotal) / Math.max(Number.EPSILON, naturalTotal - neededTotal) : needed[r] * box.height / neededTotal);
+  const ys = [box.y];
+  for (const height of heights) ys.push(ys.at(-1) + height);
+  let overflow = false;
+  const rows2 = heights.map((height, r) => ({ box: { x: box.x, y: ys[r], width: box.width, height }, cells: [] }));
+  for (const cell of cells) {
+    const cellBox = { x: box.x + cell.column * cellWidth, y: ys[cell.row], width: cell.colSpan * cellWidth, height: ys[cell.row + cell.rowSpan] - ys[cell.row] };
+    const available = cellBox.height - (cell.padding.top + cell.padding.bottom) * scale;
+    const fit = fitCell(cell, available, minimum), height = textHeight(fit);
+    const offset = cell.style.verticalAlign === "bottom" ? Math.max(0, available - height) : cell.style.verticalAlign === "middle" ? Math.max(0, (available - height) / 2) : 0;
+    const textBox = { x: cellBox.x + cell.padding.left * scale, y: cellBox.y + cell.padding.top * scale + offset, width: Math.max(scale, cell.width), height: Math.max(scale, available - offset) };
+    overflow ||= cell.width <= 0 || available <= 0 || fit.overflow;
+    rows2[cell.row].cells.push({ value: cell.value, input: cell.input, path: cell.valuePath, sourcePath: cell.path, style: cell.style, row: cell.row, column: cell.column, rowSpan: cell.rowSpan, colSpan: cell.colSpan, header: cell.header, rich: Array.isArray(cell.value), box: cellBox, textBox, textStyle: resolveTextStyle(cell.textStyle, options.textMeasurement), fit });
+  }
+  return { rows: rows2, columnCount, height: sum(heights), overflow };
 }
 function tableOverflows(value, box, scale, settings, options, path) {
   return box.width <= 0 || box.height <= 0 || layoutTable(value, box, { scale, minFontSize: settings.minFontSize, fontFamily: options.fonts?.body, textMeasurement: options.textMeasurement, path }).overflow;
@@ -291,7 +442,7 @@ function flatten(value) {
   if (value == null) return "";
   if (typeof value !== "object") return String(value);
   if (Array.isArray(value)) return value.map(flatten).join("");
-  const item = record(value);
+  const item = record2(value);
   return flatten(item.text ?? item.value ?? item.source ?? JSON.stringify(value));
 }
 function regionParts(key) {
@@ -347,11 +498,11 @@ function assertComposition(value) {
   if (value.overflow !== void 0 && !["warn", "error"].includes(value.overflow)) throw new RangeError("Invalid composition.overflow.");
 }
 function composeSlide(input, options = {}) {
-  const slide = record(input), layout = record(options.layout);
+  const slide = record2(input), layout = record2(options.layout);
   const width = options.width ?? 1280, height = options.height ?? 720;
   if (![width, height].every((value) => Number.isFinite(value) && value > 0)) throw new RangeError("Canvas dimensions must be finite and positive.");
   const scale = Math.min(width, height) / 720;
-  const composition = { ...record(layout.composition), ...record(slide.composition) };
+  const composition = { ...record2(layout.composition), ...record2(slide.composition) };
   assertComposition(composition);
   const padding = (composition.padding ?? 0.08) * Math.min(width, height);
   const gap = (composition.gap ?? 1 / 30) * Math.min(width, height);
@@ -381,7 +532,7 @@ function composeSlide(input, options = {}) {
   const collect = (host, basePath, depth = 0, ancestors = []) => {
     if (Array.isArray(host.blocks)) {
       if (depth >= MAX_COMPOSITION_DEPTH || ancestors.includes(host)) throw new RangeError(`Content groups must be acyclic and nest at most ${MAX_COMPOSITION_DEPTH} levels.`);
-      const settings = record(host.composition);
+      const settings = record2(host.composition);
       assertComposition(settings);
       return [{
         field: "blocks",
@@ -390,14 +541,15 @@ function composeSlide(input, options = {}) {
         path: basePath,
         payload: host,
         composition: settings,
-        children: host.blocks.flatMap((block, index) => collect(record(block), `${basePath}.blocks.${index}`, depth + 1, [...ancestors, host]))
+        children: host.blocks.flatMap((block, index) => collect(record2(block), `${basePath}.blocks.${index}`, depth + 1, [...ancestors, host]))
       }];
     }
     return fields.filter((field) => host[field] !== void 0).map((field) => ({ field, type: host.type ?? kind(field), value: host[field], path: `${basePath}.${field}`, payload: { type: host.type ?? kind(field), [field]: host[field] } }));
   };
   const regions = Object.keys(slide).filter((key) => regionParts(key)).sort();
-  const pending = regions.length ? regions.flatMap((key) => collect(record(slide[key]), `${path}.${key}`).map((item) => ({ ...item, region: regionParts(key) }))) : Array.isArray(slide.blocks) ? slide.blocks.flatMap((block, index) => collect(record(block), `${path}.blocks.${index}`)) : collect(slide, path);
+  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,
@@ -407,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";
@@ -423,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);
@@ -436,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 });
@@ -458,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." });
       }
     });
@@ -470,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 = {
@@ -488,7 +708,7 @@ function resolveCanvasDimensions(input) {
     letter: [11, 8.5],
     a4: [11.69, 8.27]
   };
-  const value = record(input);
+  const value = record2(input);
   const preset = presets[typeof input === "string" ? input : value.preset] ?? presets.widescreen;
   const width = (value.widthInches ?? preset[0]) * 96;
   const height = (value.heightInches ?? preset[1]) * 96;
@@ -496,4 +716,4 @@ function resolveCanvasDimensions(input) {
   return { width, height };
 }
 
-export { MAX_COMPOSITION_DEPTH, OPFCompositionError, composeSlide, fitList, fitRichText, fitText, layoutTable, measureText, resolveCanvasDimensions, resolveFontFamilies, resolveTextStyle, textWidthMeasurer, wrapText };
+export { MAX_COMPOSITION_DEPTH, OPFCompositionError, composeSlide, fitList, fitRichText, fitText, layoutQuote, layoutTable, measureText, resolveCanvasDimensions, resolveFontFamilies, resolveTextStyle, tableGrid, tableRowBoundaries, textWidthMeasurer, wrapText };

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

@@ -1,5 +1,5 @@
-import { assertValidPresentation } from './chunk-23MXJL2K.js';
-import { resolveFontFamilies, resolveCanvasDimensions, composeSlide } from './chunk-C7GKRLI6.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
@@ -52,7 +52,7 @@ function leafFor(path, field, value) {
     const values = Array.isArray(value) ? value : value[key];
     if (Array.isArray(values)) {
       leaf.unit = "items";
-      leaf.boundaries = Array.from({ length: values.length + 1 }, (_, i) => i);
+      leaf.boundaries = field === "table" ? tableRowBoundaries(value) : Array.from({ length: values.length + 1 }, (_, i) => i);
       leaf.slice = (a, b) => Array.isArray(value) ? value.slice(a, b) : { ...value, [key]: values.slice(a, b) };
     }
   }
@@ -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);