@bendyline/squisq 2.7.0 → 2.8.0

package/dist/{chunk-KOU5WRVN.js → chunk-PTK2SW2V.js}

@@ -2,28 +2,38 @@ import {
   SHAPE_NAMES,
   buildChartData,
   buildNarrationScript,
+  buildRegistry,
   coerceTemplateParams,
   deriveTemplateInputs,
+  expandPersistentLayers,
   extractBodyPlainText,
   extractRichListItems,
   flattenBlocks,
   flattenRenderableBlocks,
   getBlockBodyText,
   getPinnedBlockMeta,
+  getThemeFont,
+  hasTemplate,
   isDataFence,
   isShapeName,
   lintTemplateParams,
   markdownToDoc,
+  materializeBlockLayersWithRuntime,
   nearestName,
   normalizeShapeKind,
   parseDataFence,
   parseNarrationTimingJson,
   parseStandaloneAnnotation,
+  placeLayersInRect,
   readCustomThemesFromFrontmatter,
+  resolvePersistentLayers,
   templateRegistry,
   writeCustomTemplatesToFrontmatter,
   writeCustomThemesToFrontmatter
-} from "./chunk-GSJEGMKF.js";
+} from "./chunk-V6NV4GDE.js";
+import {
+  iconMarker
+} from "./chunk-7ZAAICW4.js";
 import {
   ASCII_TREE_VOCAB,
   ASCII_VOCAB,
@@ -49,11 +59,18 @@ import {
   FRONTMATTER_CUSTOM_TEMPLATES_KEY,
   FRONTMATTER_CUSTOM_THEMES_KEY,
   hexHueDegrees,
+  oklchDarken,
+  oklchLighten,
+  relativeLuminance,
   resolveFontFamily,
-  resolveTheme
+  resolveTheme,
+  withAlpha
 } from "./chunk-SBAX4ZPO.js";
 import {
   VIEWPORT_PRESETS,
+  calculateFontScale,
+  createTemplateContext,
+  getViewportOrientation,
   isTemplateBlock
 } from "./chunk-BAOV476U.js";
 import {
@@ -662,6 +679,332 @@ function removeTransitionParams(attrs) {
   };
 }
 
+// src/doc/buildPreviewDoc.ts
+function extractRichText(node) {
+  if (node.type === "inlineIcon") {
+    const icon = node;
+    return iconMarker(icon.family, icon.name);
+  }
+  if ("value" in node && typeof node.value === "string") {
+    return node.value;
+  }
+  const children = getChildren(node);
+  const separator = node.type === "list" || node.type === "listItem" ? "\n" : "";
+  return children.map(extractRichText).join(separator);
+}
+function extractBodyText(contents) {
+  if (!contents || contents.length === 0) return "";
+  const parts = [];
+  for (const node of contents) {
+    if (node.type === "code" && node.lang?.trim().toLowerCase() === "mermaid") continue;
+    parts.push(extractRichText(node));
+  }
+  return parts.join("\n").trim();
+}
+function parseDim(raw) {
+  if (raw === void 0) return void 0;
+  const n = parseFloat(raw);
+  return Number.isFinite(n) && n > 0 ? n : void 0;
+}
+function extractBlockImages(contents) {
+  if (!contents || contents.length === 0) return [];
+  const images = [];
+  function walkHtml(node) {
+    if (!node || typeof node !== "object") return;
+    const n = node;
+    if (n.type === "htmlElement" && n.tagName.toLowerCase() === "img") {
+      const attrs = n.attributes;
+      const src = attrs?.src;
+      if (typeof src === "string" && src) {
+        images.push({
+          src,
+          alt: typeof attrs?.alt === "string" ? attrs.alt : "",
+          width: parseDim(attrs?.width),
+          height: parseDim(attrs?.height)
+        });
+      }
+    }
+    if (Array.isArray(n.children)) {
+      for (const child of n.children) walkHtml(child);
+    }
+  }
+  function walk(node) {
+    if ("type" in node && node.type === "image" && "url" in node) {
+      const img = node;
+      if (img.url) {
+        images.push({ src: img.url, alt: img.alt ?? "" });
+      }
+    }
+    if ("type" in node && (node.type === "htmlBlock" || node.type === "htmlInline")) {
+      const html = node;
+      for (const child of html.htmlChildren ?? []) walkHtml(child);
+    }
+    for (const child of getChildren(node)) {
+      walk(child);
+    }
+  }
+  for (const node of contents) {
+    walk(node);
+  }
+  return images;
+}
+function collectAllDocImages(blocks) {
+  const seen = /* @__PURE__ */ new Set();
+  const images = [];
+  function walkBlocks(blockList) {
+    for (const block of blockList) {
+      for (const img of extractBlockImages(block.contents)) {
+        if (!seen.has(img.src)) {
+          seen.add(img.src);
+          images.push(img);
+        }
+      }
+      if (block.children) {
+        walkBlocks(block.children);
+      }
+    }
+  }
+  walkBlocks(blocks);
+  return images;
+}
+function extractListItems(contents) {
+  if (!contents) return [];
+  const items = [];
+  for (const node of contents) {
+    if (node.type === "list") {
+      for (const item of node.children) {
+        const text = extractPlainText(item).trim();
+        if (text) items.push(text);
+      }
+    }
+  }
+  return items;
+}
+function getTemplateDefaults(templateName, headingText, block) {
+  const body = extractBodyText(block.contents);
+  switch (templateName) {
+    case "statHighlight":
+      return deriveTemplateInputs(templateName, headingText, block.contents) ?? {
+        stat: headingText,
+        description: body || headingText
+      };
+    case "quote":
+      return { quote: body || headingText };
+    case "fullBleedQuote":
+    case "pullQuote":
+      return deriveTemplateInputs(templateName, headingText, block.contents) ?? {
+        text: body || headingText
+      };
+    case "factCard":
+      return { fact: headingText, explanation: body || headingText };
+    case "comparisonBar":
+      return { leftLabel: "A", leftValue: 60, rightLabel: "B", rightValue: 40 };
+    case "list": {
+      const items = extractListItems(block.contents);
+      return { items: items.length > 0 ? items : ["Item 1", "Item 2", "Item 3"] };
+    }
+    case "definitionCard":
+      return { term: headingText, definition: body || headingText };
+    case "dateEvent":
+      return { date: headingText, description: body || headingText };
+    case "leftFeature":
+    case "rightFeature": {
+      const images = extractBlockImages(block.contents);
+      const img = images[0];
+      return {
+        imageSrc: img?.src ?? "",
+        imageAlt: img?.alt || headingText,
+        imageWidth: img?.width,
+        imageHeight: img?.height,
+        title: headingText,
+        body: body || headingText
+      };
+    }
+    default:
+      return {};
+  }
+}
+function blockToSlide(block, index, knownTemplates, documentTitle) {
+  const headingText = block.sourceHeading ? extractPlainText(block.sourceHeading) : block.title || documentTitle || "";
+  const implicitSectionHeader = block.template === "sectionHeader" && block.autoTemplate !== true && !!block.sourceHeading && !block.sourceHeading.templateAnnotation?.template;
+  const requestedTemplate = implicitSectionHeader ? "content" : block.template ?? "content";
+  const isCustomTemplate = knownTemplates?.has(requestedTemplate) ?? false;
+  const recognized = hasTemplate(requestedTemplate) || isCustomTemplate;
+  const template = recognized ? requestedTemplate : "sectionHeader";
+  const defaults = getTemplateDefaults(template, headingText, block);
+  const templateOverrides = omitStringBlockMeta(block.templateOverrides);
+  const coercedTemplateOverrides = templateOverrides ? coerceTemplateParams(template, templateOverrides).input : void 0;
+  const {
+    id: _id,
+    startTime: _st,
+    duration: _d,
+    audioSegment: _as,
+    layers: _l,
+    transition: _tr,
+    template: _t,
+    title: _ti,
+    children: _c,
+    contents: _co,
+    sourceHeading: _sh,
+    templateOverrides: _to,
+    templateData: _td,
+    ...extraFields
+  } = block;
+  return {
+    id: block.id,
+    template,
+    duration: block.duration,
+    audioSegment: 0,
+    // Respect the block's authored transition (set via the toolbar / on-canvas
+    // properties palette → `{…}` block attrs). Only fall back to a default fade
+    // for blocks past the first when the author hasn't chosen one; the first
+    // block has no previous slide to transition in from.
+    transition: block.transition ?? (index > 0 ? { type: "fade", duration: 0.5 } : void 0),
+    title: headingText,
+    // Preserve body nodes on every slide. Built-in templates ignore this
+    // structural field, while the canonical materializer uses it to retain
+    // authored rich elements (Mermaid fences today; other media can follow)
+    // independently of the selected visual template.
+    ...block.contents ? { contents: block.contents } : {},
+    // Custom templates additionally consume child blocks through tokens.
+    ...isCustomTemplate && block.children ? { children: block.children } : {},
+    ...defaults,
+    ...extraFields,
+    // Structured body data (```json data fences, GFM tables for dataTable)
+    // carries typed values; `{[…]}` string overrides win last so an explicit
+    // annotation param can still pin any field.
+    //
+    // Block-meta keys (transition, startTime, duration, …) are the exception:
+    // they were already coerced to typed block fields above (e.g.
+    // `block.transition` → `{ type, duration, direction }`). Their raw string
+    // form also rides along in `templateData`/`templateOverrides` because the
+    // author wrote them inside `{[…]}`; left un-stripped, that string would
+    // spread back over the typed value here and clobber it — turning
+    // `transition=vortex` into the string `"vortex"`, which the player can't
+    // animate. Omit them from the content spreads so the typed fields win.
+    ...omitBlockMeta(block.templateData),
+    ...coercedTemplateOverrides
+  };
+}
+var BLOCK_META_KEYS = new Set(Object.keys(KNOWN_BLOCK_META_KEYS));
+function omitBlockMeta(data) {
+  if (!data) return data;
+  let hit = false;
+  const out = {};
+  for (const key of Object.keys(data)) {
+    if (BLOCK_META_KEYS.has(key)) {
+      hit = true;
+      continue;
+    }
+    out[key] = data[key];
+  }
+  return hit ? out : data;
+}
+function omitStringBlockMeta(data) {
+  if (!data) return data;
+  let hit = false;
+  const out = {};
+  for (const key of Object.keys(data)) {
+    if (BLOCK_META_KEYS.has(key)) {
+      hit = true;
+      continue;
+    }
+    out[key] = data[key];
+  }
+  return hit ? out : data;
+}
+var IMAGE_MOTIONS = [
+  "zoomIn",
+  "zoomOut",
+  "panLeft",
+  "panRight"
+];
+function documentTitleFromFileName(fileName) {
+  if (!fileName) return "";
+  const base = fileName.split(/[\\/]/).pop() ?? "";
+  return base.replace(/\.[^.]+$/, "").trim();
+}
+function resolveDocumentTitle(doc, provided) {
+  const frontmatterTitle = doc.frontmatter?.title;
+  if (typeof frontmatterTitle === "string" && frontmatterTitle.trim()) {
+    return frontmatterTitle.trim();
+  }
+  return provided?.trim() ?? "";
+}
+function buildPreviewDoc(doc, options) {
+  const flat = flattenRenderableBlocks(doc.blocks);
+  const allImages = collectAllDocImages(doc.blocks);
+  const usedImageSrcs = /* @__PURE__ */ new Set();
+  const knownTemplates = doc.customTemplates ? new Set(doc.customTemplates.map((d) => d.name)) : void 0;
+  const documentTitle = resolveDocumentTitle(doc, options?.documentTitle);
+  const slides = [];
+  let motionIndex = 0;
+  for (let i = 0; i < flat.length; i++) {
+    const block = flat[i];
+    const blockImages = extractBlockImages(block.contents);
+    const slide = blockToSlide(block, i, knownTemplates, documentTitle);
+    if (blockImages.length > 0 && slide.template === "sectionHeader") {
+      const img = blockImages[0];
+      usedImageSrcs.add(img.src);
+      slide.template = "imageWithCaption";
+      slide.imageSrc = img.src;
+      slide.imageAlt = img.alt;
+      slide.caption = slide.title;
+      slide.captionPosition = "bottom";
+      slide.ambientMotion = IMAGE_MOTIONS[motionIndex++ % IMAGE_MOTIONS.length];
+    } else if (blockImages.length > 0) {
+      const img = blockImages[0];
+      usedImageSrcs.add(img.src);
+      if (!slide.accentImage) {
+        slide.accentImage = {
+          src: img.src,
+          alt: img.alt,
+          position: "left-strip",
+          ambientMotion: IMAGE_MOTIONS[motionIndex++ % IMAGE_MOTIONS.length]
+        };
+      }
+    }
+    slides.push(slide);
+  }
+  const unusedImages = options?.interleaveImages ?? true ? allImages.filter((img) => !usedImageSrcs.has(img.src)) : [];
+  if (unusedImages.length > 0 && slides.length > 0) {
+    const interval = Math.max(2, Math.floor(slides.length / (unusedImages.length + 1)));
+    let insertOffset = 0;
+    for (let imgIdx = 0; imgIdx < unusedImages.length; imgIdx++) {
+      const insertAt = Math.min((imgIdx + 1) * interval + insertOffset, slides.length);
+      const img = unusedImages[imgIdx];
+      slides.splice(insertAt, 0, {
+        id: `img-interleave-${imgIdx}`,
+        template: "imageWithCaption",
+        duration: 5,
+        audioSegment: 0,
+        imageSrc: img.src,
+        imageAlt: img.alt,
+        ambientMotion: IMAGE_MOTIONS[motionIndex++ % IMAGE_MOTIONS.length],
+        transition: { type: "fade", duration: 0.5 }
+      });
+      insertOffset++;
+    }
+  }
+  let t = 0;
+  for (const slide of slides) {
+    slide.startTime = t;
+    t += slide.duration;
+  }
+  const audio = doc.audio?.segments?.length > 0 ? doc.audio : {
+    segments: t > 0 ? [{ src: "", name: "preview", duration: t, startTime: 0 }] : []
+  };
+  return {
+    // Preserve document-wide capabilities (custom themes, persistent layers,
+    // scheduled media, frontmatter, captions, and future schema fields).
+    // Preview preparation should replace only the slide/timing projection.
+    ...doc,
+    duration: t,
+    blocks: slides,
+    audio
+  };
+}
+
 // src/doc/resolveDocTheme.ts
 function resolveThemeForDoc(doc, explicitId, registry) {
   const id = explicitId ?? doc?.themeId ?? readFrontmatterThemeId(doc?.frontmatter);
@@ -1914,21 +2257,29 @@ var PAGE_BASE_CSS = `
 .squisq-page-items { list-style: none; margin: 0; padding: 0; counter-reset: squisq-item; max-width: 40em; }
 .squisq-page-items li {
   counter-increment: squisq-item;
-  position: relative;
-  padding: 0.9em 0 0.9em 3.4em;
+  /* Grid + baseline alignment keeps the marker locked to the first text line
+     regardless of marker size, body font, or line-height \u2014 an absolutely
+     positioned marker with a fixed top offset drifts as soon as either
+     changes. */
+  display: grid;
+  grid-template-columns: 3.4em 1fr;
+  align-items: baseline;
+  padding: 0.9em 0;
   font-size: 1.1rem;
 }
 .squisq-page-items li + li { border-top: 1px solid var(--squisq-page-divider-color); }
 .squisq-page-items li::before {
   content: counter(squisq-item, decimal-leading-zero);
-  position: absolute;
-  left: 0;
-  top: 0.85em;
   font-family: var(--squisq-page-title-font);
   font-weight: 700;
   color: var(--squisq-page-accent);
   font-size: 1.15em;
 }
+/* Item bodies are rendered markdown: neutralize UA paragraph margins (which
+   would otherwise push the first line below the marker) and space blocks. */
+.squisq-page-item-body { min-width: 0; }
+.squisq-page-item-body > * { margin: 0; }
+.squisq-page-item-body > * + * { margin-top: 0.6em; }
 .squisq-page[data-numerals='mono'] .squisq-page-items li::before { font-family: var(--squisq-page-mono-font); }
 .squisq-page-items-title { font-size: 1.9rem; }
 
@@ -2101,6 +2452,1186 @@ ${varLines}
 ${PAGE_BASE_CSS}`;
 }
 
+// src/doc/dashboard/dashboardZoom.ts
+var DASHBOARD_ZOOM_LEVELS = [1, 1.5, 2];
+function normalizeDashboardZoom(value) {
+  const raw = typeof value === "number" ? value : typeof value === "string" ? Number(value.trim().replace(/%$/, "")) : Number.NaN;
+  if (!Number.isFinite(raw)) return void 0;
+  const multiplier = raw > 3 ? raw / 100 : raw;
+  return DASHBOARD_ZOOM_LEVELS.find((level) => Math.abs(level - multiplier) < 1e-3);
+}
+var ZOOM_ELIGIBLE_TEMPLATES = /* @__PURE__ */ new Set([
+  "content",
+  "list",
+  "quote",
+  "definitionCard",
+  "factCard",
+  "dateEvent"
+]);
+var ZOOM_200_MAX_CHARS = 160;
+var ZOOM_150_MAX_CHARS = 360;
+function desiredCellZoom(candidate) {
+  if (!candidate.template || !ZOOM_ELIGIBLE_TEMPLATES.has(candidate.template)) return 1;
+  if (candidate.textLength < ZOOM_200_MAX_CHARS) return 2;
+  if (candidate.textLength < ZOOM_150_MAX_CHARS) return 1.5;
+  return 1;
+}
+function resolveDashboardZooms(candidates, mode) {
+  const levels = candidates.map((candidate) => {
+    if (candidate.explicit !== void 0) return candidate.explicit;
+    return mode === "auto" ? desiredCellZoom(candidate) : 1;
+  });
+  const boostVotes = /* @__PURE__ */ new Map();
+  candidates.forEach((candidate, index) => {
+    const level = levels[index];
+    if (level === 1) return;
+    const weight = candidate.explicit !== void 0 ? 2 : 1;
+    boostVotes.set(level, (boostVotes.get(level) ?? 0) + weight);
+  });
+  if (boostVotes.size <= 1) return levels;
+  let winner = 2;
+  let winnerVotes = -1;
+  for (const [level, votes] of boostVotes) {
+    if (votes > winnerVotes || votes === winnerVotes && level > winner) {
+      winner = level;
+      winnerVotes = votes;
+    }
+  }
+  return candidates.map((candidate, index) => {
+    if (candidate.explicit !== void 0) return candidate.explicit;
+    return levels[index] === 1 ? 1 : winner;
+  });
+}
+
+// src/doc/dashboard/DashboardLayout.ts
+var MAX_CELLS = 32;
+var MAX_BLOCK_ASSIGNMENT = 64;
+var NAME_PATTERN = /^[a-z0-9][a-z0-9-]*$/;
+function parsePercent(value) {
+  if (typeof value === "number") {
+    return Number.isFinite(value) ? value : void 0;
+  }
+  if (typeof value !== "string") return void 0;
+  const trimmed = value.trim().replace(/%$/, "");
+  if (trimmed.length === 0) return void 0;
+  const parsed = Number(trimmed);
+  return Number.isFinite(parsed) ? parsed : void 0;
+}
+function formatPercent(value) {
+  const rounded = Math.round(value * 1e3) / 1e3;
+  return `${rounded}%`;
+}
+function validateCell(input, path, errors) {
+  if (!input || typeof input !== "object") {
+    errors.push({ path, message: "cell must be an object" });
+    return void 0;
+  }
+  const cell = input;
+  const x = parsePercent(cell.x);
+  const y = parsePercent(cell.y);
+  const width = parsePercent(cell.width);
+  const height = parsePercent(cell.height);
+  if (x === void 0 || x < 0 || x > 100) {
+    errors.push({ path: `${path}.x`, message: "x must be a percent between 0 and 100" });
+    return void 0;
+  }
+  if (y === void 0 || y < 0 || y > 100) {
+    errors.push({ path: `${path}.y`, message: "y must be a percent between 0 and 100" });
+    return void 0;
+  }
+  if (width === void 0 || width <= 0 || width > 100) {
+    errors.push({ path: `${path}.width`, message: "width must be a percent greater than 0" });
+    return void 0;
+  }
+  if (height === void 0 || height <= 0 || height > 100) {
+    errors.push({ path: `${path}.height`, message: "height must be a percent greater than 0" });
+    return void 0;
+  }
+  const out = {
+    x: formatPercent(x),
+    y: formatPercent(y),
+    width: formatPercent(width),
+    height: formatPercent(height)
+  };
+  if (cell.block !== void 0) {
+    const block = typeof cell.block === "string" ? Number(cell.block) : cell.block;
+    if (typeof block !== "number" || !Number.isInteger(block) || block < 1 || block > MAX_BLOCK_ASSIGNMENT) {
+      errors.push({
+        path: `${path}.block`,
+        message: `block must be an integer between 1 and ${MAX_BLOCK_ASSIGNMENT}`
+      });
+      return void 0;
+    }
+    out.block = block;
+  }
+  if (cell.zoom !== void 0) {
+    const zoom = normalizeDashboardZoom(cell.zoom);
+    if (zoom === void 0) {
+      errors.push({
+        path: `${path}.zoom`,
+        message: "zoom must be 1, 1.5, or 2 (or 100/150/200 percent)"
+      });
+      return void 0;
+    }
+    out.zoom = zoom;
+  }
+  return out;
+}
+function validateCellArray(input, path, errors) {
+  if (!Array.isArray(input)) {
+    errors.push({ path, message: "must be an array of cells" });
+    return void 0;
+  }
+  if (input.length < 1 || input.length > MAX_CELLS) {
+    errors.push({ path, message: `must contain between 1 and ${MAX_CELLS} cells` });
+    return void 0;
+  }
+  const cells = [];
+  for (let i = 0; i < input.length; i++) {
+    const cell = validateCell(input[i], `${path}[${i}]`, errors);
+    if (!cell) return void 0;
+    cells.push(cell);
+  }
+  return cells;
+}
+function validateTitleSlot(input, errors) {
+  if (!input || typeof input !== "object") {
+    errors.push({ path: "titleSlot", message: "titleSlot must be an object" });
+    return void 0;
+  }
+  const slot = input;
+  const placement = slot.placement === "bottom" ? "bottom" : slot.placement === "top" ? "top" : void 0;
+  if (placement === void 0 && slot.placement !== void 0) {
+    errors.push({ path: "titleSlot.placement", message: "placement must be 'top' or 'bottom'" });
+    return void 0;
+  }
+  const height = parsePercent(slot.height);
+  if (height === void 0 || height <= 0 || height > 40) {
+    errors.push({ path: "titleSlot.height", message: "height must be a percent between 0 and 40" });
+    return void 0;
+  }
+  return { placement: placement ?? "top", height: formatPercent(height) };
+}
+function validateDashboardLayoutDefinition(input) {
+  const errors = [];
+  if (!input || typeof input !== "object") {
+    return { valid: false, errors: [{ path: "", message: "definition must be an object" }] };
+  }
+  const def = input;
+  const name = typeof def.name === "string" ? def.name.trim().toLowerCase() : "";
+  if (!NAME_PATTERN.test(name)) {
+    errors.push({
+      path: "name",
+      message: "name must be a slug (lowercase letters, digits, hyphens)"
+    });
+  }
+  const label = typeof def.label === "string" ? def.label.trim() : "";
+  if (label.length === 0) {
+    errors.push({ path: "label", message: "label must be a non-empty string" });
+  }
+  const cellsInput = def.cells;
+  let landscape;
+  let portrait;
+  let square;
+  if (!cellsInput || typeof cellsInput !== "object") {
+    errors.push({ path: "cells", message: "cells must be an object with a landscape array" });
+  } else {
+    landscape = validateCellArray(cellsInput.landscape, "cells.landscape", errors);
+    if (cellsInput.portrait !== void 0) {
+      portrait = validateCellArray(cellsInput.portrait, "cells.portrait", errors);
+    }
+    if (cellsInput.square !== void 0) {
+      square = validateCellArray(cellsInput.square, "cells.square", errors);
+    }
+    if (landscape) {
+      if (portrait && portrait.length !== landscape.length) {
+        errors.push({
+          path: "cells.portrait",
+          message: "portrait must define the same number of cells as landscape"
+        });
+      }
+      if (square && square.length !== landscape.length) {
+        errors.push({
+          path: "cells.square",
+          message: "square must define the same number of cells as landscape"
+        });
+      }
+    }
+  }
+  let titleSlot;
+  if (def.titleSlot !== void 0) {
+    titleSlot = validateTitleSlot(def.titleSlot, errors);
+  }
+  if (errors.length > 0 || !landscape) {
+    return { valid: false, errors };
+  }
+  const layout2 = {
+    name,
+    label,
+    cells: {
+      landscape,
+      ...portrait ? { portrait } : {},
+      ...square ? { square } : {}
+    }
+  };
+  if (typeof def.description === "string" && def.description.trim()) {
+    layout2.description = def.description.trim();
+  }
+  if (titleSlot) layout2.titleSlot = titleSlot;
+  if (def.auto === false) layout2.auto = false;
+  return { valid: true, errors, layout: layout2 };
+}
+function layoutCapacity(def) {
+  return def.cells.landscape.length;
+}
+function transposeCells(cells) {
+  return cells.map((cell) => ({
+    x: cell.y,
+    y: cell.x,
+    width: cell.height,
+    height: cell.width,
+    ...cell.block !== void 0 ? { block: cell.block } : {},
+    ...cell.zoom !== void 0 ? { zoom: cell.zoom } : {}
+  }));
+}
+function resolveLayoutCells(def, orientation, contentRect) {
+  const cells = orientation === "portrait" ? def.cells.portrait ?? transposeCells(def.cells.landscape) : orientation === "square" ? def.cells.square ?? def.cells.landscape : def.cells.landscape;
+  return cells.map((cell) => {
+    const x = parsePercent(cell.x) ?? 0;
+    const y = parsePercent(cell.y) ?? 0;
+    const width = parsePercent(cell.width) ?? 0;
+    const height = parsePercent(cell.height) ?? 0;
+    const resolved = {
+      rect: {
+        x: contentRect.x + x / 100 * contentRect.width,
+        y: contentRect.y + y / 100 * contentRect.height,
+        width: Math.max(1, width / 100 * contentRect.width),
+        height: Math.max(1, height / 100 * contentRect.height)
+      }
+    };
+    if (cell.block !== void 0) resolved.block = cell.block;
+    const zoom = normalizeDashboardZoom(cell.zoom);
+    if (zoom !== void 0) resolved.zoom = zoom;
+    return resolved;
+  });
+}
+
+// src/doc/dashboard/dashboardLayoutsFrontmatter.ts
+var FRONTMATTER_DASHBOARD_LAYOUTS_KEY = "squisq-dashboard-layouts";
+var LONG_TO_SHORT = {
+  label: "lb",
+  description: "ds",
+  cells: "ce",
+  landscape: "ls",
+  portrait: "pt",
+  square: "sq",
+  width: "wd",
+  height: "hg",
+  block: "bk",
+  zoom: "zo",
+  titleSlot: "ts",
+  placement: "pl",
+  auto: "au"
+};
+var SHORT_TO_LONG = Object.fromEntries(
+  Object.entries(LONG_TO_SHORT).map(([long, short]) => [short, long])
+);
+function renameKeys(value, map2) {
+  if (Array.isArray(value)) return value.map((v) => renameKeys(v, map2));
+  if (value && typeof value === "object") {
+    const out = {};
+    for (const [k, v] of Object.entries(value)) {
+      out[map2[k] ?? k] = renameKeys(v, map2);
+    }
+    return out;
+  }
+  return value;
+}
+function readDashboardLayoutsFromFrontmatter(frontmatter) {
+  if (!frontmatter) return void 0;
+  const candidates = normalizeCandidates(frontmatter[FRONTMATTER_DASHBOARD_LAYOUTS_KEY]);
+  if (!candidates) return void 0;
+  const out = [];
+  for (const entry of candidates) {
+    const result = validateDashboardLayoutDefinition(entry);
+    if (result.layout) out.push(result.layout);
+  }
+  return out.length > 0 ? out : void 0;
+}
+function writeDashboardLayoutsToFrontmatter(layouts, options) {
+  if (!layouts || layouts.length === 0) return void 0;
+  const map2 = {};
+  for (const def of layouts) {
+    const { name, ...rest } = def;
+    map2[name] = renameKeys(rest, LONG_TO_SHORT);
+  }
+  return JSON.stringify(map2, null, options?.pretty ? 2 : void 0);
+}
+function expandCompactMap(map2) {
+  return Object.entries(map2).map(([name, raw]) => {
+    const expanded = renameKeys(raw && typeof raw === "object" ? raw : {}, SHORT_TO_LONG);
+    return { name, ...expanded };
+  });
+}
+function fromParsed(parsed) {
+  if (Array.isArray(parsed)) return parsed;
+  if (parsed && typeof parsed === "object")
+    return expandCompactMap(parsed);
+  return null;
+}
+function tryJson(s) {
+  try {
+    return JSON.parse(s);
+  } catch {
+    return void 0;
+  }
+}
+function normalizeCandidates(raw) {
+  if (raw == null) return null;
+  if (Array.isArray(raw)) return raw;
+  if (typeof raw === "object") return expandCompactMap(raw);
+  if (typeof raw !== "string") return null;
+  const parsed = tryJson(raw.trim());
+  if (parsed !== void 0) return fromParsed(parsed);
+  return null;
+}
+
+// src/doc/dashboard/builtinDashboardLayouts.ts
+var GAP = 2;
+function pct(value) {
+  return `${Math.round(value * 1e3) / 1e3}%`;
+}
+function gridCells(cols, rows, gap = GAP) {
+  const cellW = (100 - (cols - 1) * gap) / cols;
+  const cellH = (100 - (rows - 1) * gap) / rows;
+  const cells = [];
+  for (let row = 0; row < rows; row++) {
+    for (let col = 0; col < cols; col++) {
+      cells.push({
+        x: pct(col * (cellW + gap)),
+        y: pct(row * (cellH + gap)),
+        width: pct(cellW),
+        height: pct(cellH)
+      });
+    }
+  }
+  return cells;
+}
+function heroRow(heroWidth, companions, gap = GAP) {
+  const railX = heroWidth + gap;
+  const railW = 100 - railX;
+  const cellH = (100 - (companions - 1) * gap) / companions;
+  const cells = [
+    { x: "0%", y: "0%", width: pct(heroWidth), height: "100%" }
+  ];
+  for (let i = 0; i < companions; i++) {
+    cells.push({
+      x: pct(railX),
+      y: pct(i * (cellH + gap)),
+      width: pct(railW),
+      height: pct(cellH)
+    });
+  }
+  return cells;
+}
+function heroBand(heroHeight, below, gap = GAP) {
+  const rowY = heroHeight + gap;
+  const rowH = 100 - rowY;
+  const cellW = (100 - (below - 1) * gap) / below;
+  const cells = [
+    { x: "0%", y: "0%", width: "100%", height: pct(heroHeight) }
+  ];
+  for (let i = 0; i < below; i++) {
+    cells.push({
+      x: pct(i * (cellW + gap)),
+      y: pct(rowY),
+      width: pct(cellW),
+      height: pct(rowH)
+    });
+  }
+  return cells;
+}
+function mosaicCells(heroWidth, gap = GAP) {
+  const gridX = heroWidth + gap;
+  const gridW = 100 - gridX;
+  const cellW = (gridW - gap) / 2;
+  const cellH = (100 - gap) / 2;
+  const cells = [
+    { x: "0%", y: "0%", width: pct(heroWidth), height: "100%" }
+  ];
+  for (let row = 0; row < 2; row++) {
+    for (let col = 0; col < 2; col++) {
+      cells.push({
+        x: pct(gridX + col * (cellW + gap)),
+        y: pct(row * (cellH + gap)),
+        width: pct(cellW),
+        height: pct(cellH)
+      });
+    }
+  }
+  return cells;
+}
+var BUILTIN_DASHBOARD_LAYOUTS = Object.freeze([
+  {
+    name: "focus-1",
+    label: "Focus",
+    description: "One block fills the dashboard.",
+    cells: { landscape: [{ x: "0%", y: "0%", width: "100%", height: "100%" }] }
+  },
+  {
+    name: "split-2",
+    label: "Split",
+    description: "Two blocks side by side.",
+    cells: { landscape: gridCells(2, 1) }
+  },
+  {
+    name: "hero-left",
+    label: "Hero + 2",
+    description: "A large lead block with two companions.",
+    cells: {
+      landscape: heroRow(58, 2),
+      portrait: [
+        { x: "0%", y: "0%", width: "100%", height: pct(46) },
+        { x: "0%", y: pct(48), width: "100%", height: pct(25) },
+        { x: "0%", y: pct(75), width: "100%", height: pct(25) }
+      ]
+    }
+  },
+  {
+    name: "grid-2x2",
+    label: "Grid 2\xD72",
+    description: "Four blocks in a balanced grid.",
+    cells: { landscape: gridCells(2, 2) }
+  },
+  {
+    name: "hero-top",
+    label: "Hero band",
+    description: "A wide lead band with three blocks below.",
+    cells: {
+      landscape: heroBand(46, 3),
+      portrait: [
+        { x: "0%", y: "0%", width: "100%", height: pct(40) },
+        { x: "0%", y: pct(42), width: "100%", height: pct(18) },
+        { x: "0%", y: pct(62), width: "100%", height: pct(18) },
+        { x: "0%", y: pct(82), width: "100%", height: pct(18) }
+      ]
+    },
+    auto: false
+  },
+  {
+    name: "mosaic-5",
+    label: "Mosaic",
+    description: "A hero block beside a 2\xD72 grid.",
+    cells: {
+      landscape: mosaicCells(58),
+      portrait: [
+        { x: "0%", y: "0%", width: "100%", height: pct(40) },
+        { x: "0%", y: pct(42), width: pct(49), height: pct(27) },
+        { x: pct(51), y: pct(42), width: pct(49), height: pct(27) },
+        { x: "0%", y: pct(71), width: pct(49), height: pct(29) },
+        { x: pct(51), y: pct(71), width: pct(49), height: pct(29) }
+      ]
+    }
+  },
+  {
+    name: "grid-3x2",
+    label: "Grid 3\xD72",
+    description: "Six blocks in three columns.",
+    cells: { landscape: gridCells(3, 2) }
+  },
+  {
+    name: "grid-3x3",
+    label: "Grid 3\xD73",
+    description: "Nine blocks in a square grid.",
+    cells: { landscape: gridCells(3, 3), square: gridCells(3, 3) }
+  },
+  {
+    name: "grid-4x3",
+    label: "Grid 4\xD73",
+    description: "Twelve blocks in four columns.",
+    cells: { landscape: gridCells(4, 3) }
+  },
+  {
+    name: "grid-4x4",
+    label: "Grid 4\xD74",
+    description: "Sixteen blocks \u2014 the densest wall.",
+    cells: { landscape: gridCells(4, 4) }
+  }
+]);
+function summarize(def, custom) {
+  return {
+    id: def.name,
+    label: def.label,
+    ...def.description ? { description: def.description } : {},
+    capacity: layoutCapacity(def),
+    custom
+  };
+}
+function getDashboardLayoutSummaries() {
+  return BUILTIN_DASHBOARD_LAYOUTS.map((def) => summarize(def, false));
+}
+function listDashboardLayouts(doc) {
+  const customs = readDashboardLayoutsFromFrontmatter(doc?.frontmatter) ?? [];
+  const customNames = new Set(customs.map((def) => def.name));
+  return [
+    ...customs.map((def) => summarize(def, true)),
+    ...BUILTIN_DASHBOARD_LAYOUTS.filter((def) => !customNames.has(def.name)).map(
+      (def) => summarize(def, false)
+    )
+  ];
+}
+
+// src/doc/dashboard/chooseDashboardLayout.ts
+var DASHBOARD_AUTO_LAYOUT_ID = "auto";
+function resolveDashboardLayoutDefinition(id, customLayouts) {
+  const normalized = id.trim().toLowerCase();
+  if (!normalized) return void 0;
+  return customLayouts?.find((def) => def.name === normalized) ?? BUILTIN_DASHBOARD_LAYOUTS.find((def) => def.name === normalized);
+}
+function chooseDashboardLayout(blockCount, _orientation, customLayouts) {
+  const pool = [
+    ...(customLayouts ?? []).filter((def) => def.auto !== false),
+    ...BUILTIN_DASHBOARD_LAYOUTS.filter((def) => def.auto !== false)
+  ];
+  const ladder = [...pool].sort((a, b) => layoutCapacity(a) - layoutCapacity(b));
+  const needed = Math.max(1, blockCount);
+  const fit = ladder.find((def) => layoutCapacity(def) >= needed);
+  if (fit) return fit;
+  const max = ladder.reduce((acc, def) => Math.max(acc, layoutCapacity(def)), 0);
+  return ladder.find((def) => layoutCapacity(def) === max) ?? BUILTIN_DASHBOARD_LAYOUTS[0];
+}
+
+// src/doc/dashboard/dashboardStyle.ts
+var DASHBOARD_STYLE_IDS = ["basic", "card", "panel", "accent"];
+var DEFAULT_DASHBOARD_STYLE = "basic";
+var DASHBOARD_STYLES = Object.freeze([
+  {
+    id: "basic",
+    label: "Basic",
+    description: "Blocks fill their cells edge to edge."
+  },
+  {
+    id: "card",
+    label: "Cards",
+    description: "Each block sits on a raised, rounded card."
+  },
+  {
+    id: "panel",
+    label: "Panels",
+    description: "Flat outlined panels with an accent rule."
+  },
+  {
+    id: "accent",
+    label: "Accent cards",
+    description: "Cards tinted with the theme's accent colors in rotation."
+  }
+]);
+function resolveDashboardStyleId(value) {
+  if (typeof value !== "string") return void 0;
+  const normalized = value.trim().toLowerCase();
+  if (!normalized) return void 0;
+  if (normalized === "none" || normalized === "default" || normalized === "flat") return "basic";
+  if (normalized === "cards") return "card";
+  if (normalized === "panels" || normalized === "outline") return "panel";
+  if (normalized === "accents" || normalized === "accent-cards") return "accent";
+  return DASHBOARD_STYLE_IDS.includes(normalized) ? normalized : void 0;
+}
+function clamp(value, min, max) {
+  return Math.min(max, Math.max(min, value));
+}
+function isLight(color) {
+  return relativeLuminance(color) > 0.45;
+}
+function dashboardCanvasFill(style, theme) {
+  const background = theme.colors.background;
+  if (style === "basic" || style === "panel") return background;
+  return isLight(background) ? oklchDarken(background, 0.05) : oklchLighten(background, 0.04);
+}
+function dashboardCellAccent(theme, index) {
+  const schemes = Object.values(theme.colorSchemes ?? {});
+  if (schemes.length === 0) return theme.colors.primary;
+  const scheme = schemes[(index % schemes.length + schemes.length) % schemes.length];
+  return scheme.accent || scheme.text || theme.colors.primary;
+}
+function cellMetrics(style, theme, rect) {
+  const minAxis = Math.max(1, Math.min(rect.width, rect.height));
+  const themeRadius = theme.style?.borderRadius ?? 14;
+  if (style === "panel") {
+    return {
+      edge: clamp(minAxis * 0.014, 3, 12),
+      radius: clamp(themeRadius * 0.45, 0, minAxis * 0.05)
+    };
+  }
+  return {
+    // Card styles reserve a wider ring: the elevation is painted inside the
+    // layout cell (a cell renders as its own clipped SVG), so the shadow
+    // needs room to fall without being cut flat at the cell boundary.
+    edge: clamp(minAxis * 0.03, 6, 26),
+    radius: clamp(themeRadius, 6, minAxis * 0.1)
+  };
+}
+function radiusPct(radius, box) {
+  if (radius <= 0) return void 0;
+  const x = Math.round(radius / Math.max(1, box.width) * 1e5) / 1e3;
+  const y = Math.round(radius / Math.max(1, box.height) * 1e5) / 1e3;
+  return `${x}% / ${y}%`;
+}
+function buildDashboardCellChrome(style, options) {
+  const { theme, rect, index } = options;
+  if (style === "basic") return null;
+  const { edge, radius } = cellMetrics(style, theme, rect);
+  const cardRect = {
+    x: rect.x + edge,
+    y: rect.y + edge,
+    width: Math.max(1, rect.width - edge * 2),
+    height: Math.max(1, rect.height - edge * 2)
+  };
+  const local = {
+    x: edge,
+    y: edge,
+    width: cardRect.width,
+    height: cardRect.height
+  };
+  const minAxis = Math.max(1, Math.min(rect.width, rect.height));
+  const hairline = Math.max(1, Math.round(minAxis * 4e-3));
+  const accent = dashboardCellAccent(theme, index);
+  const layers = [];
+  if (style !== "panel") {
+    const steps = [
+      { spread: 0.45, dy: 0.5, alpha: 0.05 },
+      { spread: 0.25, dy: 0.42, alpha: 0.05 },
+      { spread: 0.08, dy: 0.3, alpha: 0.06 }
+    ];
+    steps.forEach((step, stepIndex) => {
+      const spread = edge * step.spread;
+      const dy = edge * step.dy;
+      layers.push({
+        type: "shape",
+        id: `cell-shadow-${stepIndex}`,
+        content: {
+          shape: "rect",
+          fill: withAlpha(theme.colors.text, step.alpha),
+          borderRadius: radius + spread
+        },
+        position: {
+          x: local.x - spread,
+          y: local.y - spread + dy,
+          width: local.width + spread * 2,
+          height: local.height + spread * 2
+        }
+      });
+    });
+  }
+  layers.push({
+    type: "shape",
+    id: "cell-surface",
+    content: {
+      shape: "rect",
+      // The surface stays the theme background; the canvas is what moves
+      // (see `dashboardCanvasFill`), so cards read as raised paper in both
+      // light and dark themes without inventing a palette slot.
+      fill: theme.colors.background,
+      borderRadius: radius
+    },
+    position: { x: local.x, y: local.y, width: local.width, height: local.height }
+  });
+  const overlayLayers = [];
+  if (style === "accent") {
+    overlayLayers.push({
+      type: "shape",
+      id: "cell-accent-wash",
+      content: { shape: "rect", fill: withAlpha(accent, 0.1), borderRadius: radius },
+      position: { x: 0, y: 0, width: "100%", height: "100%" }
+    });
+  }
+  if (style === "accent" || style === "panel") {
+    const barHeight = Math.max(2, Math.round(minAxis * 0.014));
+    overlayLayers.push({
+      type: "shape",
+      id: "cell-accent-bar",
+      content: { shape: "rect", fill: accent },
+      position: { x: 0, y: 0, width: "100%", height: barHeight }
+    });
+  }
+  const strokeWidth = style === "panel" ? hairline : Math.max(1, hairline * 0.6);
+  overlayLayers.push({
+    type: "shape",
+    id: "cell-border",
+    content: {
+      shape: "rect",
+      fill: "none",
+      stroke: style === "panel" ? withAlpha(accent, 0.45) : withAlpha(theme.colors.text, 0.14),
+      strokeWidth,
+      borderRadius: radius
+    },
+    position: {
+      x: strokeWidth / 2,
+      y: strokeWidth / 2,
+      width: Math.max(1, local.width - strokeWidth),
+      height: Math.max(1, local.height - strokeWidth)
+    }
+  });
+  const chrome = {
+    cardRect,
+    // The block fills the card: templates bring their own padding, and a
+    // padded well inside the card reads as a box inside a box.
+    contentRect: cardRect,
+    layers,
+    overlayLayers,
+    radius
+  };
+  const contentRadius = radiusPct(radius, cardRect);
+  if (contentRadius) chrome.contentRadiusPct = contentRadius;
+  return chrome;
+}
+function stripsBlockBackdrop(style) {
+  return style !== "basic";
+}
+function stripBlockBackdropLayer(layers, theme) {
+  const first = layers[0];
+  if (!first || first.type !== "shape") return [...layers];
+  const { content: content2, position } = first;
+  const fill = typeof content2.fill === "string" ? content2.fill.trim().toLowerCase() : "";
+  const fullBleed = content2.shape === "rect" && (position.x === 0 || position.x === "0%") && (position.y === 0 || position.y === "0%") && position.width === "100%" && position.height === "100%";
+  if (!fullBleed || content2.gradient || content2.pattern) return [...layers];
+  if (fill !== theme.colors.background.trim().toLowerCase()) return [...layers];
+  return layers.slice(1);
+}
+
+// src/doc/dashboard/dashboardSettings.ts
+var DASHBOARD_FRONTMATTER_KEYS = Object.freeze({
+  layout: { canonical: "squisq-dashboard-layout", legacy: "dashboard-layout" },
+  showTitle: { canonical: "squisq-dashboard-title", legacy: "dashboard-title" },
+  zoom: { canonical: "squisq-dashboard-zoom", legacy: "dashboard-zoom" },
+  style: { canonical: "squisq-dashboard-style", legacy: "dashboard-style" }
+});
+var DEFAULT_DASHBOARD_SETTINGS = Object.freeze({
+  layout: DASHBOARD_AUTO_LAYOUT_ID,
+  showTitle: true,
+  zoom: "auto",
+  style: DEFAULT_DASHBOARD_STYLE
+});
+function readSetting2(frontmatter, keys) {
+  if (!frontmatter) return void 0;
+  return Object.prototype.hasOwnProperty.call(frontmatter, keys.canonical) ? frontmatter[keys.canonical] : frontmatter[keys.legacy];
+}
+function resolveBoolean2(value) {
+  if (typeof value === "boolean") return value;
+  if (typeof value !== "string") return void 0;
+  const normalized = value.trim().toLowerCase();
+  if (["true", "yes", "on", "show", "visible"].includes(normalized)) return true;
+  if (["false", "no", "off", "hide", "hidden"].includes(normalized)) return false;
+  return void 0;
+}
+function resolveLayoutId(value) {
+  if (typeof value !== "string") return void 0;
+  const normalized = value.trim().toLowerCase();
+  if (!normalized) return void 0;
+  if (normalized === "auto" || normalized === "default") return DASHBOARD_AUTO_LAYOUT_ID;
+  return normalized;
+}
+function resolveZoomMode(value) {
+  if (typeof value === "boolean") return value ? "auto" : "off";
+  if (typeof value !== "string") return void 0;
+  const normalized = value.trim().toLowerCase();
+  if (["auto", "on", "true", "yes"].includes(normalized)) return "auto";
+  if (["off", "false", "no", "none", "100", "100%", "1"].includes(normalized)) return "off";
+  return void 0;
+}
+function resolveDashboardSettings(frontmatter, overrides = {}) {
+  const resolved = {
+    layout: resolveLayoutId(readSetting2(frontmatter, DASHBOARD_FRONTMATTER_KEYS.layout)) ?? DEFAULT_DASHBOARD_SETTINGS.layout,
+    showTitle: resolveBoolean2(readSetting2(frontmatter, DASHBOARD_FRONTMATTER_KEYS.showTitle)) ?? DEFAULT_DASHBOARD_SETTINGS.showTitle,
+    zoom: resolveZoomMode(readSetting2(frontmatter, DASHBOARD_FRONTMATTER_KEYS.zoom)) ?? DEFAULT_DASHBOARD_SETTINGS.zoom,
+    style: resolveDashboardStyleId(readSetting2(frontmatter, DASHBOARD_FRONTMATTER_KEYS.style)) ?? DEFAULT_DASHBOARD_SETTINGS.style
+  };
+  return {
+    layout: resolveLayoutId(overrides.layout) ?? resolved.layout,
+    showTitle: overrides.showTitle ?? resolved.showTitle,
+    zoom: overrides.zoom ?? resolved.zoom,
+    style: resolveDashboardStyleId(overrides.style) ?? resolved.style
+  };
+}
+
+// src/doc/dashboard/materializeDashboard.ts
+var DEFAULT_TITLE_SLOT = { placement: "top", height: "9%" };
+var TITLE_CONTENT_GAP = 0.015;
+var CANVAS_MARGIN = 0.02;
+function percentNumber(value) {
+  const parsed = Number(value.trim().replace(/%$/, ""));
+  return Number.isFinite(parsed) ? parsed : 0;
+}
+function pctOf(value, total) {
+  return `${Math.round(value / Math.max(1, total) * 1e5) / 1e3}%`;
+}
+function rectToPct(rect, viewport) {
+  return {
+    left: pctOf(rect.x, viewport.width),
+    top: pctOf(rect.y, viewport.height),
+    width: pctOf(rect.width, viewport.width),
+    height: pctOf(rect.height, viewport.height)
+  };
+}
+function resolveDashboardTitle(doc, provided) {
+  const frontmatterTitle = doc.frontmatter?.title;
+  if (typeof frontmatterTitle === "string" && frontmatterTitle.trim()) {
+    return frontmatterTitle.trim();
+  }
+  return provided?.trim() ?? "";
+}
+function dedupeLeadingTitleBlock(candidates, titleText) {
+  if (candidates.length === 0 || !titleText) return candidates;
+  const first = candidates[0];
+  const firstTitle = typeof first.title === "string" ? first.title.trim().toLowerCase() : "";
+  if (!firstTitle || firstTitle !== titleText.trim().toLowerCase()) return candidates;
+  const template = first.template;
+  const titleShaped = template === "title" || template === "sectionHeader" || template === "cover";
+  const hasBody = Array.isArray(first.contents) && first.contents.length > 0;
+  return titleShaped || !hasBody ? candidates.slice(1) : candidates;
+}
+function buildTitleLayers(titleText, bandViewport, slot, theme, canvasViewport, margin) {
+  const context = createTemplateContext(theme, 0, 1, canvasViewport);
+  const canvasFontScale = calculateFontScale(canvasViewport);
+  const fontSize = Math.min(44 * canvasFontScale, bandViewport.height * 0.52);
+  const accentWidth = Math.max(4, Math.round(6 * canvasFontScale));
+  const textX = margin + accentWidth + Math.max(10, Math.round(accentWidth * 2.5));
+  return [
+    {
+      type: "shape",
+      id: "dashboard-title-accent",
+      content: { shape: "rect", fill: theme.colors.primary },
+      position: {
+        x: margin,
+        y: "26%",
+        width: accentWidth,
+        height: "48%"
+      }
+    },
+    {
+      type: "text",
+      id: "dashboard-title-text",
+      content: {
+        text: titleText,
+        style: {
+          fontSize,
+          fontFamily: getThemeFont(context, "title"),
+          fontWeight: "bold",
+          color: theme.colors.text,
+          textAlign: "left",
+          verticalAlign: "middle",
+          maxLines: 1
+        }
+      },
+      position: {
+        x: textX,
+        y: 0,
+        width: Math.max(1, bandViewport.width - textX - margin),
+        height: "100%"
+      }
+    },
+    {
+      // Hairline separating the band from the content area.
+      type: "shape",
+      id: "dashboard-title-rule",
+      content: { shape: "rect", fill: withAlpha(theme.colors.text, 0.14) },
+      position: {
+        x: 0,
+        y: slot.placement === "bottom" ? 0 : bandViewport.height - 2,
+        width: "100%",
+        height: 2
+      }
+    }
+  ];
+}
+function materializeDashboard(doc, options = {}) {
+  const theme = options.theme ?? DEFAULT_THEME;
+  const viewport = options.viewport ?? VIEWPORT_PRESETS.landscape;
+  const orientation = getViewportOrientation(viewport);
+  const customLayouts = options.customLayouts ?? readDashboardLayoutsFromFrontmatter(doc.frontmatter);
+  const customTemplates = options.customTemplates ?? doc.customTemplates;
+  const diagnostics = [];
+  const settings = resolveDashboardSettings(doc.frontmatter, {
+    layout: typeof options.layout === "string" ? options.layout : void 0,
+    showTitle: options.showTitle,
+    zoom: options.zoom,
+    ...options.style !== void 0 ? { style: options.style } : {}
+  });
+  const style = settings.style;
+  let layoutDef;
+  let layoutSource = "auto";
+  if (options.layout && typeof options.layout === "object") {
+    const validated = validateDashboardLayoutDefinition(options.layout);
+    if (validated.layout) {
+      layoutDef = validated.layout;
+      layoutSource = "option";
+    } else {
+      diagnostics.push({
+        type: "unknown-layout",
+        message: "Inline dashboard layout definition is invalid; falling back to auto.",
+        requestedLayout: options.layout.name
+      });
+    }
+  } else if (settings.layout !== DASHBOARD_AUTO_LAYOUT_ID) {
+    const resolved = resolveDashboardLayoutDefinition(settings.layout, customLayouts);
+    if (resolved) {
+      layoutDef = resolved;
+      layoutSource = typeof options.layout === "string" && options.layout.trim() ? "option" : "frontmatter";
+    } else {
+      diagnostics.push({
+        type: "unknown-layout",
+        message: `Unknown dashboard layout "${settings.layout}"; falling back to auto.`,
+        requestedLayout: settings.layout
+      });
+    }
+  }
+  const preview = buildPreviewDoc(doc, {
+    documentTitle: options.documentTitle,
+    interleaveImages: false
+  });
+  let candidates = preview.blocks ?? [];
+  if (candidates.length === 0) {
+    diagnostics.push({
+      type: "empty-doc",
+      message: "The document has no renderable blocks; the dashboard has no cells."
+    });
+  }
+  const titleText = settings.showTitle ? resolveDashboardTitle(doc, options.documentTitle) : "";
+  const hasTitleBand = titleText.length > 0;
+  if (hasTitleBand) {
+    candidates = dedupeLeadingTitleBlock(candidates, titleText);
+  }
+  if (!layoutDef) {
+    layoutDef = chooseDashboardLayout(candidates.length, orientation, customLayouts);
+    layoutSource = "auto";
+  }
+  const margin = CANVAS_MARGIN * Math.min(viewport.width, viewport.height);
+  let contentRect = {
+    x: margin,
+    y: margin,
+    width: Math.max(1, viewport.width - margin * 2),
+    height: Math.max(1, viewport.height - margin * 2)
+  };
+  let title2 = null;
+  if (hasTitleBand) {
+    const slot = layoutDef.titleSlot ?? DEFAULT_TITLE_SLOT;
+    const bandPct = Math.min(40, Math.max(2, percentNumber(slot.height)));
+    const bandHeight = bandPct / 100 * viewport.height;
+    const gap = TITLE_CONTENT_GAP * viewport.height;
+    const titleRect = slot.placement === "bottom" ? { x: 0, y: viewport.height - bandHeight, width: viewport.width, height: bandHeight } : { x: 0, y: 0, width: viewport.width, height: bandHeight };
+    contentRect = slot.placement === "bottom" ? {
+      x: margin,
+      y: margin,
+      width: Math.max(1, viewport.width - margin * 2),
+      height: Math.max(1, viewport.height - bandHeight - gap - margin)
+    } : {
+      x: margin,
+      y: bandHeight + gap,
+      width: Math.max(1, viewport.width - margin * 2),
+      height: Math.max(1, viewport.height - bandHeight - gap - margin)
+    };
+    const bandViewport = {
+      width: Math.max(1, Math.round(titleRect.width)),
+      height: Math.max(1, Math.round(titleRect.height)),
+      name: "Dashboard title"
+    };
+    title2 = {
+      text: titleText,
+      rect: titleRect,
+      rectPct: rectToPct(titleRect, viewport),
+      viewport: bandViewport,
+      // The band spans the canvas, but its type starts on the cell area's
+      // left edge so the title and the first column share one margin.
+      layers: buildTitleLayers(titleText, bandViewport, slot, theme, viewport, margin)
+    };
+  }
+  const resolvedCells = resolveLayoutCells(layoutDef, orientation, contentRect);
+  const assignments = [];
+  const explicitlyClaimed = /* @__PURE__ */ new Set();
+  resolvedCells.forEach((cell, cellIndex) => {
+    if (cell.block === void 0) return;
+    const candidateIndex = cell.block - 1;
+    if (candidateIndex < 0 || candidateIndex >= candidates.length) {
+      diagnostics.push({
+        type: "invalid-cell-assignment",
+        message: `Cell ${cellIndex + 1} of layout "${layoutDef.name}" requests block ${cell.block}, but the document has ${candidates.length} block(s); the cell is left empty.`
+      });
+      return;
+    }
+    explicitlyClaimed.add(candidateIndex);
+    assignments.push({ cellIndex, rect: cell.rect, candidateIndex, explicitZoom: cell.zoom });
+  });
+  const filled = /* @__PURE__ */ new Set();
+  let cursor = 0;
+  resolvedCells.forEach((cell, cellIndex) => {
+    if (cell.block !== void 0) return;
+    while (cursor < candidates.length && explicitlyClaimed.has(cursor)) cursor++;
+    if (cursor >= candidates.length) return;
+    filled.add(cursor);
+    assignments.push({
+      cellIndex,
+      rect: cell.rect,
+      candidateIndex: cursor,
+      explicitZoom: cell.zoom
+    });
+    cursor++;
+  });
+  const hidden = [];
+  for (let i = 0; i < candidates.length; i++) {
+    if (!explicitlyClaimed.has(i) && !filled.has(i)) hidden.push(i);
+  }
+  if (hidden.length > 0) {
+    diagnostics.push({
+      type: "overflow",
+      message: `${hidden.length} block(s) exceed the "${layoutDef.name}" layout's ${resolvedCells.length} cell(s) and are not rendered.`,
+      hiddenBlockIds: hidden.map((i) => String(candidates[i].id ?? i))
+    });
+  }
+  const orderedAssignments = assignments.sort((a, b) => a.cellIndex - b.cellIndex);
+  const zooms = resolveDashboardZooms(
+    orderedAssignments.map(({ candidateIndex, explicitZoom }) => {
+      const block = candidates[candidateIndex];
+      const title3 = typeof block.title === "string" ? block.title : "";
+      return {
+        template: resolveTemplateName(block.template ?? ""),
+        textLength: title3.length + getBlockBodyText(block).length,
+        ...explicitZoom !== void 0 ? { explicit: explicitZoom } : {}
+      };
+    }),
+    settings.zoom
+  );
+  const registry = customTemplates && customTemplates.length > 0 ? buildRegistry(customTemplates) : templateRegistry;
+  const cells = orderedAssignments.map(
+    ({ cellIndex, rect, candidateIndex }, orderIndex) => {
+      const block = candidates[candidateIndex];
+      const zoom = zooms[orderIndex];
+      const chrome = buildDashboardCellChrome(style, { theme, rect, index: cellIndex });
+      const contentRect2 = chrome ? chrome.contentRect : rect;
+      const cellViewport = {
+        width: Math.max(1, Math.round(contentRect2.width)),
+        height: Math.max(1, Math.round(contentRect2.height)),
+        name: `Dashboard cell ${cellIndex + 1}`
+      };
+      const cellContext = createTemplateContext(
+        theme,
+        candidateIndex,
+        candidates.length,
+        cellViewport
+      );
+      if (zoom !== 1) cellContext.fontScale *= zoom;
+      const result = materializeBlockLayersWithRuntime(
+        block,
+        {
+          theme,
+          viewport: cellViewport,
+          persistentLayers: false,
+          blockIndex: candidateIndex,
+          totalBlocks: candidates.length,
+          failureMode: options.failureMode
+        },
+        { registry, templateContext: cellContext }
+      );
+      const layers = stripsBlockBackdrop(style) ? stripBlockBackdropLayer(result.layers, theme) : result.layers;
+      let frame;
+      if (chrome) {
+        const frameViewport = {
+          width: Math.max(1, Math.round(rect.width)),
+          height: Math.max(1, Math.round(rect.height)),
+          name: `Dashboard cell ${cellIndex + 1} frame`
+        };
+        frame = {
+          rect,
+          rectPct: rectToPct(rect, viewport),
+          viewport: frameViewport,
+          layers: chrome.layers,
+          overlayLayers: chrome.overlayLayers,
+          overlayViewport: {
+            width: cellViewport.width,
+            height: cellViewport.height,
+            name: `Dashboard cell ${cellIndex + 1} overlay`
+          },
+          ...chrome.contentRadiusPct ? { contentRadiusPct: chrome.contentRadiusPct } : {}
+        };
+      }
+      return {
+        index: cellIndex,
+        block,
+        blockIndex: candidateIndex,
+        layers,
+        rect: contentRect2,
+        rectPct: rectToPct(contentRect2, viewport),
+        ...frame ? { frame } : {},
+        viewport: cellViewport,
+        zoom,
+        source: result.source,
+        ...result.diagnostic ? { diagnostic: result.diagnostic } : {}
+      };
+    }
+  );
+  const persistent = resolvePersistentLayers(doc, theme);
+  const canvasFill = dashboardCanvasFill(style, theme);
+  const backdrop = {
+    fill: canvasFill,
+    bottomLayers: [
+      {
+        type: "shape",
+        id: "dashboard-backdrop",
+        content: { shape: "rect", fill: canvasFill },
+        position: { x: 0, y: 0, width: "100%", height: "100%" }
+      },
+      ...expandPersistentLayers(persistent?.bottomLayers, theme)
+    ],
+    topLayers: expandPersistentLayers(persistent?.topLayers, theme)
+  };
+  return {
+    layout: layoutDef,
+    layoutSource,
+    style,
+    viewport,
+    cells,
+    title: title2,
+    backdrop,
+    diagnostics
+  };
+}
+function composeDashboardLayers(materialization) {
+  const layers = [...materialization.backdrop.bottomLayers];
+  for (const cell of materialization.cells) {
+    if (cell.frame) {
+      layers.push(
+        ...placeLayersInRect(
+          cell.frame.layers,
+          cell.frame.viewport,
+          cell.frame.rect,
+          `cell-${cell.index}-frame`
+        )
+      );
+    }
+    layers.push(...placeLayersInRect(cell.layers, cell.viewport, cell.rect, `cell-${cell.index}`));
+    if (cell.frame && cell.frame.overlayLayers.length > 0) {
+      layers.push(
+        ...placeLayersInRect(
+          cell.frame.overlayLayers,
+          cell.frame.overlayViewport,
+          cell.rect,
+          `cell-${cell.index}-overlay`
+        )
+      );
+    }
+  }
+  if (materialization.title) {
+    layers.push(
+      ...placeLayersInRect(
+        materialization.title.layers,
+        materialization.title.viewport,
+        materialization.title.rect,
+        "dashboard-title"
+      )
+    );
+  }
+  layers.push(...materialization.backdrop.topLayers);
+  return layers;
+}
+
 // src/doc/applyNarrationTiming.ts
 var MIN_BLOCK_SIMILARITY = 0.5;
 var MIN_V1_SCRIPT_SIMILARITY = 0.8;
@@ -3215,7 +4746,7 @@ function middleOut(from, to) {
   const mid = Math.floor((lo + hi) / 2);
   return rows.sort((a, b) => Math.abs(a - mid) - Math.abs(b - mid) || a - b);
 }
-function clamp(value, lo, hi) {
+function clamp2(value, lo, hi) {
   return Math.max(lo, Math.min(hi, value));
 }
 function drawVertical(args, s, t, exitCol, enterCol, dir) {
@@ -3232,8 +4763,8 @@ function drawVertical(args, s, t, exitCol, enterCol, dir) {
   };
   const straightOk = exitCol >= t.c0 + 1 && exitCol <= t.c1 - 1 && exitCol >= s.c0 + 1 && exitCol <= s.c1 - 1;
   if (straightOk || gap < 2) {
-    const sCol = clamp(exitCol, s.c0 + 1, s.c1 - 1);
-    const tCol = clamp(exitCol, t.c0 + 1, t.c1 - 1);
+    const sCol = clamp2(exitCol, s.c0 + 1, s.c1 - 1);
+    const tCol = clamp2(exitCol, t.c0 + 1, t.c1 - 1);
     junction(exitRow, sCol, dir === 1 ? "bottom" : "top");
     junction(enterRow, tCol, dir === 1 ? "top" : "bottom");
     if (sCol === tCol && gap >= 1) {
@@ -3265,7 +4796,7 @@ function drawVertical(args, s, t, exitCol, enterCol, dir) {
     }
     return;
   }
-  const midRow = clamp(
+  const midRow = clamp2(
     Math.floor((exitRow + enterRow) / 2) + stagger,
     Math.min(firstFree, lastFree),
     Math.max(firstFree, lastFree)
@@ -3366,8 +4897,8 @@ function drawHorizontal(args, s, t, exitRow, enterRow, dir) {
   };
   const straightOk = exitRow >= t.r0 + 1 && exitRow <= t.r1 - 1 && exitRow >= s.r0 + 1 && exitRow <= s.r1 - 1;
   if (straightOk || gap < 2) {
-    const sRow = clamp(exitRow, s.r0 + 1, s.r1 - 1);
-    const tRow = clamp(exitRow, t.r0 + 1, t.r1 - 1);
+    const sRow = clamp2(exitRow, s.r0 + 1, s.r1 - 1);
+    const tRow = clamp2(exitRow, t.r0 + 1, t.r1 - 1);
     junction(sRow, exitCol, dir === 1 ? "right" : "left");
     junction(tRow, enterCol, dir === 1 ? "left" : "right");
     if (sRow === tRow && gap >= 1) {
@@ -3400,7 +4931,7 @@ function drawHorizontal(args, s, t, exitRow, enterRow, dir) {
     }
     return;
   }
-  const midCol = clamp(
+  const midCol = clamp2(
     Math.floor((exitCol + enterCol) / 2) + args.stagger,
     Math.min(firstFree, lastFree),
     Math.max(firstFree, lastFree)
@@ -4028,6 +5559,8 @@ export {
   MAX_COVER_SLIDE_DURATION_SECONDS,
   resolveCoverSlideSettings,
   docToMarkdown,
+  documentTitleFromFileName,
+  buildPreviewDoc,
   resolveThemeForDoc,
   isTemplatedPageBlock,
   resolvePageBlock,
@@ -4039,6 +5572,37 @@ export {
   pageStyleDataAttributes,
   PAGE_BASE_CSS,
   buildPageCss,
+  DASHBOARD_ZOOM_LEVELS,
+  normalizeDashboardZoom,
+  desiredCellZoom,
+  resolveDashboardZooms,
+  validateDashboardLayoutDefinition,
+  layoutCapacity,
+  transposeCells,
+  resolveLayoutCells,
+  FRONTMATTER_DASHBOARD_LAYOUTS_KEY,
+  readDashboardLayoutsFromFrontmatter,
+  writeDashboardLayoutsToFrontmatter,
+  BUILTIN_DASHBOARD_LAYOUTS,
+  getDashboardLayoutSummaries,
+  listDashboardLayouts,
+  DASHBOARD_AUTO_LAYOUT_ID,
+  resolveDashboardLayoutDefinition,
+  chooseDashboardLayout,
+  DASHBOARD_STYLE_IDS,
+  DEFAULT_DASHBOARD_STYLE,
+  DASHBOARD_STYLES,
+  resolveDashboardStyleId,
+  dashboardCanvasFill,
+  dashboardCellAccent,
+  buildDashboardCellChrome,
+  stripsBlockBackdrop,
+  stripBlockBackdropLayer,
+  DASHBOARD_FRONTMATTER_KEYS,
+  DEFAULT_DASHBOARD_SETTINGS,
+  resolveDashboardSettings,
+  materializeDashboard,
+  composeDashboardLayers,
   applyNarrationTiming,
   scoreTextSimilarity,
   resolveAudioMapping,