@bendyline/squisq 2.10.0 → 2.11.0

package/dist/{chunk-DRFJU4MK.js → chunk-ZYCSRDSX.js}

@@ -56,7 +56,7 @@ import {
   sanitizeUrl,
   splitKeyValueToken,
   tokenizeAttrTokens
-} from "./chunk-NBKAXPSX.js";
+} from "./chunk-TMOHAFYE.js";
 import {
   extractPlainText,
   readFrontmatterThemeId,
@@ -6850,11 +6850,283 @@ function scatterChart(input, context) {
   return renderChart("scatter", input, context);
 }
 
+// src/doc/templates/transcriptBlock.ts
+function transcriptBlock(rawInput, context) {
+  const input = {
+    ...rawInput,
+    speaker: rawInput.speaker ?? rawInput.title ?? "Speaker",
+    text: rawInput.text ?? ""
+  };
+  const { theme } = context;
+  const scheme = resolveColorScheme(context, input.colorScheme);
+  const variant = input.variant ?? "speech";
+  const side = input.side ?? "left";
+  const handoff = typeof input.counterpartName === "string" && input.counterpartName.length > 0;
+  const bodyFont = getThemeFont(context, "body");
+  const monoFont = getThemeFont(context, "mono");
+  const nameFontSize = themedFontSize(26, context, false);
+  const textFontSize = themedFontSize(32, context, true);
+  const metaFontSize = themedFontSize(22, context, false);
+  const bubbleFill = variant === "thought" ? withAlpha(theme.colors.text, 0.05) : variant === "tool" ? withAlpha(scheme.accent, 0.12) : withAlpha(theme.colors.text, 0.08);
+  const textColor = variant === "thought" ? theme.colors.textMuted : theme.colors.text;
+  const layers = [createBackgroundLayer("bg", themedSurfaceGradient(context, 160))];
+  if (handoff) {
+    return [...layers, ...handoffLayers(input, context, scheme.accent, textColor, bubbleFill)];
+  }
+  const avatarX = side === "left" ? "12%" : "88%";
+  const columnX = side === "left" ? "20%" : "18%";
+  const bubbleWidthPct = 62;
+  layers.push(
+    ...avatarLayers("speaker", input.speaker, input.speakerImage, avatarX, "34%", context)
+  );
+  layers.push({
+    type: "text",
+    id: "speaker-name",
+    content: {
+      text: input.speaker + (variant === "thought" ? "  \xB7  thinking" : ""),
+      style: {
+        fontSize: nameFontSize,
+        fontFamily: bodyFont,
+        fontWeight: "bold",
+        color: theme.colors.textMuted,
+        textAlign: side === "left" ? "left" : "right",
+        shadow: shouldUseShadow(context)
+      }
+    },
+    position: { x: columnX, y: "24%", width: `${bubbleWidthPct}%`, anchor: "top-left" },
+    animation: { type: "fadeIn", duration: 0.4 }
+  });
+  const bubbleWidthPx = (bubbleWidthPct - 5) / 100 * context.viewport.width;
+  const textHeightPct = Math.min(
+    46,
+    estimateTextHeight(input.text, textFontSize, bubbleWidthPx, 1.35) / context.viewport.height * 100 + 8
+  );
+  layers.push({
+    type: "shape",
+    id: "bubble",
+    content: {
+      shape: "rect",
+      fill: bubbleFill,
+      borderRadius: 18,
+      ...variant === "tool" ? { stroke: scheme.accent, strokeWidth: 2 } : {}
+    },
+    position: {
+      x: columnX,
+      y: "29%",
+      width: `${bubbleWidthPct}%`,
+      height: `${Math.max(16, textHeightPct)}%`,
+      anchor: "top-left"
+    },
+    animation: { type: "fadeIn", duration: 0.4, delay: 0.1 }
+  });
+  if (variant === "tool" && input.toolName) {
+    layers.push({
+      type: "text",
+      id: "tool-name",
+      content: {
+        text: input.toolName,
+        style: {
+          fontSize: themedFontSize(28, context, false),
+          fontFamily: monoFont,
+          fontWeight: "bold",
+          color: scheme.accent
+        }
+      },
+      position: { x: `${parseFloat(columnX) + 2}%`, y: "32%", anchor: "top-left" },
+      animation: { type: "fadeIn", duration: 0.4, delay: 0.15 }
+    });
+  }
+  layers.push({
+    type: "text",
+    id: "message",
+    content: {
+      text: input.text,
+      style: {
+        fontSize: textFontSize,
+        fontFamily: variant === "tool" ? monoFont : bodyFont,
+        fontStyle: variant === "thought" ? "italic" : "normal",
+        color: textColor,
+        lineHeight: 1.35,
+        maxLines: 7
+      }
+    },
+    position: {
+      x: `${parseFloat(columnX) + 2}%`,
+      y: variant === "tool" && input.toolName ? "38%" : "32.5%",
+      width: `${bubbleWidthPct - 4}%`,
+      anchor: "top-left"
+    },
+    animation: { type: "typewriter", duration: Math.min(2.5, 0.4 + input.text.length / 120) }
+  });
+  if (variant === "tool" && input.resultText) {
+    layers.push({
+      type: "text",
+      id: "tool-result",
+      content: {
+        text: input.resultText,
+        style: {
+          fontSize: themedFontSize(26, context, false),
+          fontFamily: monoFont,
+          color: theme.colors.textMuted,
+          lineHeight: 1.3,
+          maxLines: 3
+        }
+      },
+      position: { x: columnX, y: "78%", width: `${bubbleWidthPct}%`, anchor: "top-left" },
+      animation: { type: "fadeIn", duration: 0.4, delay: 0.3 }
+    });
+  }
+  if (input.meta) {
+    layers.push({
+      type: "text",
+      id: "meta",
+      content: {
+        text: input.meta,
+        style: { fontSize: metaFontSize, fontFamily: bodyFont, color: theme.colors.textMuted }
+      },
+      position: { x: "96%", y: "94%", anchor: "bottom-right" }
+    });
+  }
+  return layers;
+}
+function handoffLayers(input, context, accent, textColor, bubbleFill) {
+  const { theme } = context;
+  const bodyFont = getThemeFont(context, "body");
+  const nameFontSize = themedFontSize(28, context, false);
+  const textFontSize = themedFontSize(32, context, true);
+  const layers = [
+    ...avatarLayers("speaker", input.speaker, input.speakerImage, "26%", "28%", context),
+    ...avatarLayers(
+      "counterpart",
+      input.counterpartName ?? "",
+      input.counterpartImage,
+      "74%",
+      "28%",
+      context
+    ),
+    nameLayer("speaker-name", input.speaker, "26%", nameFontSize, bodyFont, theme.colors.textMuted),
+    nameLayer(
+      "counterpart-name",
+      input.counterpartName ?? "",
+      "74%",
+      nameFontSize,
+      bodyFont,
+      theme.colors.textMuted
+    ),
+    {
+      type: "path",
+      id: "handoff-arrow",
+      content: { d: "M 0 0 L 100 0", stroke: accent, strokeWidth: 4, endMarker: "arrow" },
+      position: { x: "50%", y: "28%", width: "28%", height: "1%", anchor: "center" },
+      animation: { type: "fadeIn", duration: 0.4, delay: 0.2 }
+    }
+  ];
+  if (input.text.length > 0) {
+    layers.push(
+      {
+        type: "shape",
+        id: "bubble",
+        content: { shape: "rect", fill: bubbleFill, borderRadius: 18 },
+        position: { x: "50%", y: "66%", width: "66%", height: "32%", anchor: "center" },
+        animation: { type: "fadeIn", duration: 0.4, delay: 0.3 }
+      },
+      {
+        type: "text",
+        id: "message",
+        content: {
+          text: input.text,
+          style: {
+            fontSize: textFontSize,
+            fontFamily: bodyFont,
+            color: textColor,
+            textAlign: "center",
+            lineHeight: 1.35,
+            maxLines: 5
+          }
+        },
+        position: { x: "50%", y: "66%", width: "60%", height: "26%", anchor: "center" },
+        animation: { type: "typewriter", duration: 2, delay: 0.4 }
+      }
+    );
+  }
+  if (input.meta) {
+    layers.push({
+      type: "text",
+      id: "meta",
+      content: {
+        text: input.meta,
+        style: {
+          fontSize: themedFontSize(22, context, false),
+          fontFamily: bodyFont,
+          color: theme.colors.textMuted
+        }
+      },
+      position: { x: "96%", y: "94%", anchor: "bottom-right" }
+    });
+  }
+  return layers;
+}
+function nameLayer(id, text, x, fontSize, fontFamily, color) {
+  return {
+    type: "text",
+    id,
+    content: {
+      text,
+      style: { fontSize, fontFamily, fontWeight: "bold", color, textAlign: "center" }
+    },
+    position: { x, y: "42%", anchor: "center" }
+  };
+}
+function avatarLayers(idPrefix, name, imageSrc, x, y, context) {
+  const { theme } = context;
+  if (imageSrc) {
+    return [
+      {
+        type: "image",
+        id: `${idPrefix}-avatar`,
+        content: { src: imageSrc, alt: name, fit: "contain" },
+        position: { x, y, width: "9%", height: "16%", anchor: "center" }
+      }
+    ];
+  }
+  const initials = name.split(/\s+/).map((part) => part[0] ?? "").join("").slice(0, 2).toUpperCase();
+  return [
+    {
+      type: "shape",
+      id: `${idPrefix}-avatar-bg`,
+      content: {
+        shape: "circle",
+        fill: withAlpha(theme.colors.text, 0.1),
+        stroke: theme.colors.textMuted,
+        strokeWidth: 2
+      },
+      position: { x, y, width: "9%", height: "16%", anchor: "center" }
+    },
+    {
+      type: "text",
+      id: `${idPrefix}-avatar-initials`,
+      content: {
+        text: initials || "?",
+        style: {
+          fontSize: themedFontSize(44, context, true),
+          fontFamily: getThemeFont(context, "body"),
+          fontWeight: "bold",
+          color: theme.colors.text,
+          textAlign: "center",
+          verticalAlign: "middle"
+        }
+      },
+      position: { x, y, width: "9%", height: "16%", anchor: "center" }
+    }
+  ];
+}
+
 // src/doc/templates/registry.ts
 var templateRegistry = {
   title: titleBlock,
   sectionHeader,
   bigText,
+  transcript: transcriptBlock,
   content: contentBlock,
   statHighlight,
   quote: quoteBlock,
@@ -7031,9 +7303,47 @@ function CHART_DESCRIPTORS(extra = []) {
       coerce: "stringList"
     },
     { key: "rows", description: "Table rows (supply via a data fence)" },
+    ...DATA_SRC_DESCRIPTORS(),
+    { key: "sheet", description: "Worksheet inside the src workbook (XLSX src only)" },
+    {
+      key: "anchor",
+      description: "Top-left cell of the region inside the src workbook, e.g. 'B7'"
+    },
+    {
+      key: "headerRow",
+      description: "Whether row 1 of the source region is a header row",
+      coerce: "boolean"
+    },
     ...extra
   ];
 }
+function DATA_SRC_DESCRIPTORS() {
+  return [
+    {
+      key: "src",
+      description: "Container path to a sidecar data file (.csv/.tsv/.xlsx/.parquet) supplying the table"
+    },
+    {
+      key: "previewRows",
+      description: "Max data rows resolved from src for the bounded preview",
+      coerce: "number"
+    },
+    // Written by `resolveDataReferences` onto templateData (totalRows/totalCols/
+    // previewRows/truncated) — declared so resolved docs don't lint as unknown.
+    { key: "srcStats", description: "Preview stats recorded by data-reference resolution" },
+    // Non-destructive view state over the src data (see @bendyline/squisq/table
+    // for the grammar) — applied by the readers before windowing, so previews
+    // and exports show the author's curated view.
+    {
+      key: "sort",
+      description: "Sort order over src data: 'Col:desc,Other' (quote names containing , or :)"
+    },
+    {
+      key: "filter",
+      description: "Row filter over src data: 'Col=value;Other>=10' (ops = != > < >= <= ~ !~; AND only)"
+    }
+  ];
+}
 var STACKED_DESCRIPTOR = {
   key: "stacked",
   description: "Stack series instead of grouping them side by side",
@@ -7076,6 +7386,23 @@ var TEMPLATE_INPUT_DESCRIPTORS = {
     { key: "ambientMotion", description: "Slow zoom/pan effect", values: AMBIENT_MOTION_VALUES }
   ],
   content: [{ key: "title", description: "Heading shown above the complete body" }],
+  transcript: [
+    { key: "speaker", description: "Speaker display name" },
+    { key: "speakerImage", description: "Avatar image path (missing \u2192 initials medallion)" },
+    { key: "side", description: "Speaker column side", values: ["left", "right"] },
+    { key: "variant", description: "Beat kind", values: ["speech", "thought", "tool"] },
+    { key: "text", description: "The message body" },
+    { key: "toolName", description: "Tool variant: invoked tool name (mono chip)" },
+    { key: "resultText", description: "Tool variant: bounded result line" },
+    { key: "counterpartName", description: "Handoff form: receiving speaker name" },
+    { key: "counterpartImage", description: "Handoff form: receiving speaker avatar path" },
+    { key: "meta", description: "Muted corner line (timestamp, step)" },
+    {
+      key: "colorScheme",
+      description: "Accent scheme (tool chip, handoff arrow)",
+      valueHint: COLOR_SCHEME_HINT
+    }
+  ],
   statHighlight: [
     { key: "stat", description: 'The statistic (e.g. "89%", "2x")' },
     { key: "description", description: "What the stat means" },
@@ -7182,7 +7509,11 @@ var TEMPLATE_INPUT_DESCRIPTORS = {
       description: "Whether row 1 of the source region is a header row",
       coerce: "boolean"
     },
-    { key: "titleAnchor", description: "Cell this heading text was absorbed from" }
+    { key: "titleAnchor", description: "Cell this heading text was absorbed from" },
+    // Sidecar data source (see DATA_SRC_DESCRIPTORS): `src` points at a
+    // container data file; `sheet`/`anchor`/`headerRow` above double as the
+    // in-workbook address when src names an .xlsx.
+    ...DATA_SRC_DESCRIPTORS()
   ],
   barChart: CHART_DESCRIPTORS([STACKED_DESCRIPTOR]),
   columnChart: CHART_DESCRIPTORS([STACKED_DESCRIPTOR]),
@@ -7518,6 +7849,15 @@ var BLOCK_MEDIA_LAYOUT_POLICIES = {
     unconsumedMedia: "reserve-when-no-native-media",
     variants: TITLE_VARIANTS
   },
+  transcript: {
+    summary: "Speaker avatars are native media (initials medallions when absent); other media stays supplemental.",
+    noMedia: "template-without-optional-media",
+    ownership: "optional-native",
+    nativeLayout: "accent-strip-or-inset",
+    additionalMediaLayout: "overlay-inset",
+    unconsumedMedia: "reserve-when-no-native-media",
+    variants: TEXT_VARIANTS
+  },
   content: {
     summary: "Preserves the complete heading and body; supplemental media receives a companion field.",
     noMedia: "template-default",
@@ -8663,6 +9003,10 @@ var TEMPLATE_METADATA = {
     label: "Big Text",
     description: "Gigantic uppercase display text \u2014 thumbnail-style \u2014 on a theme surface or over an image with a contrast bloom."
   },
+  transcript: {
+    label: "Transcript",
+    description: "A conversational beat: speaker avatar and message bubble, with thought, tool, and two-speaker handoff variants."
+  },
   content: {
     label: "Content",
     description: "Shows a heading and the complete body in a loss-averse content-first layout."
@@ -8815,6 +9159,12 @@ var TEMPLATE_AUTHORING_METADATA = {
     safeForContentFirst: true,
     placement: "heading"
   },
+  transcript: {
+    role: "content",
+    bodyPolicy: "structured",
+    safeForContentFirst: false,
+    placement: "heading"
+  },
   statHighlight: {
     role: "highlight",
     bodyPolicy: "derived",

package/dist/doc/index.d.ts

@@ -1,11 +1,12 @@
-import { bb as TemplateBlock, bc as TemplateContext, a3 as Layer, w as CustomTemplateDefinition, be as TemplateRegistry, bh as Theme, bL as ViewportConfig, aL as PersistentLayerConfig, P as DocBlock, bM as ViewportOrientation, aK as PersistentLayer, bu as TitleBlockInput, b0 as SectionHeaderInput, j as BigTextInput, u as ContentBlockInput, b6 as StatHighlightInput, aW as QuoteBlockInput, V as FactCardInput, bB as TwoColumnInput, H as DateEventInput, a1 as ImageWithCaptionInput, a6 as LeftFeatureInput, aZ as RightFeatureInput, aa as MapBlockInput, b5 as StartBlockConfig, Y as FullBleedQuoteInput, a9 as ListBlockInput, aP as PhotoGridInput, J as DefinitionCardInput, t as ComparisonBarInput, aV as PullQuoteInput, bK as VideoWithCaptionInput, bJ as VideoPullQuoteInput, G as DataTableInput, K as DiagramBlockInput, bw as TreeBlockInput, bq as TimelineBlockInput, k as Block, S as DrawingBlockInput, ae as MarkerStyle, A as AccentImage, a0 as ImageTreatment, a as AccentPosition, c as Animation, d as AnimationType, bj as ThemeColorScheme, O as Doc, bl as ThemeRegistry, aD as PageEmphasis, bk as ThemePageStyle, Q as DocDiagnostic, N as DiagramTemplateNode, M as DiagramTemplateEdge, bt as TimelineTemplateTrack, bs as TimelineTemplateLink } from '../Doc-DTyeaFuW.js';
-export { T as FRONTMATTER_CUSTOM_TEMPLATES_KEY, U as FRONTMATTER_CUSTOM_THEMES_KEY, a5 as LayoutHints, aY as RenderStyle, bi as ThemeColorPalette, bo as ThemeStyle, bp as ThemeTypography, bC as VIEWPORT_PRESETS, bN as ViewportPreset, bS as createTemplateContext, bZ as getLayoutHints, c0 as getTwoColumnPositions, c1 as getViewport, c2 as getViewportOrientation, c5 as isTemplateBlock, c8 as scaledFontSize } from '../Doc-DTyeaFuW.js';
+import { bb as TemplateBlock, bc as TemplateContext, a3 as Layer, w as CustomTemplateDefinition, be as TemplateRegistry, bh as Theme, bM as ViewportConfig, aL as PersistentLayerConfig, P as DocBlock, bN as ViewportOrientation, aK as PersistentLayer, bu as TitleBlockInput, b0 as SectionHeaderInput, j as BigTextInput, u as ContentBlockInput, b6 as StatHighlightInput, aW as QuoteBlockInput, V as FactCardInput, bC as TwoColumnInput, H as DateEventInput, a1 as ImageWithCaptionInput, a6 as LeftFeatureInput, aZ as RightFeatureInput, aa as MapBlockInput, b5 as StartBlockConfig, Y as FullBleedQuoteInput, a9 as ListBlockInput, aP as PhotoGridInput, J as DefinitionCardInput, t as ComparisonBarInput, aV as PullQuoteInput, bL as VideoWithCaptionInput, bK as VideoPullQuoteInput, G as DataTableInput, K as DiagramBlockInput, bx as TreeBlockInput, bq as TimelineBlockInput, k as Block, S as DrawingBlockInput, ae as MarkerStyle, A as AccentImage, a0 as ImageTreatment, a as AccentPosition, c as Animation, d as AnimationType, bj as ThemeColorScheme, O as Doc, bl as ThemeRegistry, aD as PageEmphasis, bk as ThemePageStyle, Q as DocDiagnostic, N as DiagramTemplateNode, M as DiagramTemplateEdge, bt as TimelineTemplateTrack, bs as TimelineTemplateLink } from '../Doc-CRPQCkHn.js';
+export { T as FRONTMATTER_CUSTOM_TEMPLATES_KEY, U as FRONTMATTER_CUSTOM_THEMES_KEY, a5 as LayoutHints, aY as RenderStyle, bi as ThemeColorPalette, bo as ThemeStyle, bp as ThemeTypography, bD as VIEWPORT_PRESETS, bO as ViewportPreset, bT as createTemplateContext, b_ as getLayoutHints, c1 as getTwoColumnPositions, c2 as getViewport, c3 as getViewportOrientation, c6 as isTemplateBlock, c9 as scaledFontSize } from '../Doc-CRPQCkHn.js';
 import { L as MarkdownNode, a5 as TransitionType, a4 as TransitionDirection, M as MarkdownBlockNode, r as MarkdownHeading, n as MarkdownDocument, V as MarkdownTable, i as MarkdownCodeBlock, G as MarkdownList } from '../types-Be6sBUBx.js';
 import { C as CoercedBlockMeta } from '../annotationCoercion-Ckqpu33y.js';
-import { c as PageSection } from '../materializePageSection-BRNIINlU.js';
-export { M as MaterializePageSectionOptions, a as MaterializePageSectionsOptions, P as PageMedia, b as PageRichText, d as PageSectionDiagnostic, e as PageSectionItem, f as PageSectionMaterialization, g as PageSectionSource, h as PageSpatialKind, i as PageTransformHints, m as materializePageSection, j as materializePageSections, r as resolvePageStyle } from '../materializePageSection-BRNIINlU.js';
+import { c as PageSection } from '../materializePageSection-BeUPHeCl.js';
+export { M as MaterializePageSectionOptions, a as MaterializePageSectionsOptions, P as PageMedia, b as PageRichText, d as PageSectionDiagnostic, e as PageSectionItem, f as PageSectionMaterialization, g as PageSectionSource, h as PageSpatialKind, i as PageTransformHints, m as materializePageSection, j as materializePageSections, r as resolvePageStyle } from '../materializePageSection-BeUPHeCl.js';
 import { C as ContentContainer } from '../ContentContainer-B2w9sUoL.js';
-export { D as DEFAULT_THEME, g as getAvailableThemes, b as getThemeSummaries, r as resolveTheme } from '../themeLibrary-xaxN5UYu.js';
+import { V as ViewIssue } from '../viewState-lTZS-hP_.js';
+export { D as DEFAULT_THEME, g as getAvailableThemes, b as getThemeSummaries, r as resolveTheme } from '../themeLibrary-BG3jr6mT.js';
 
 /** Runtime registry composition for built-in and document-scoped templates. */
 
@@ -149,6 +150,12 @@ declare const TEMPLATE_AUTHORING_METADATA: {
         readonly safeForContentFirst: true;
         readonly placement: "heading";
     };
+    readonly transcript: {
+        readonly role: "content";
+        readonly bodyPolicy: "structured";
+        readonly safeForContentFirst: false;
+        readonly placement: "heading";
+    };
     readonly statHighlight: {
         readonly role: "highlight";
         readonly bodyPolicy: "derived";
@@ -403,6 +410,15 @@ declare const BLOCK_MEDIA_LAYOUT_POLICIES: {
         readonly unconsumedMedia: "reserve-when-no-native-media";
         readonly variants: SupplementalMediaVariantMatrix;
     };
+    readonly transcript: {
+        readonly summary: "Speaker avatars are native media (initials medallions when absent); other media stays supplemental.";
+        readonly noMedia: "template-without-optional-media";
+        readonly ownership: "optional-native";
+        readonly nativeLayout: "accent-strip-or-inset";
+        readonly additionalMediaLayout: "overlay-inset";
+        readonly unconsumedMedia: "reserve-when-no-native-media";
+        readonly variants: SupplementalMediaVariantMatrix;
+    };
     readonly content: {
         readonly summary: "Preserves the complete heading and body; supplemental media receives a companion field.";
         readonly noMedia: "template-default";
@@ -3164,6 +3180,107 @@ interface NarrationResolution {
  */
 declare function applyNarrationTiming(doc: Doc, container: ContentContainer): Promise<NarrationResolution>;
 
+/** File extensions (lowercase, no dot) recognized as sidecar data files. */
+declare const DATA_FILE_EXTENSIONS: readonly ["csv", "tsv", "xlsx", "parquet"];
+/**
+ * True when `path` is a relative container path ending in a data extension.
+ * Absolute/protocol URLs are never data sidecar references.
+ */
+declare function isDataFilePath(path: string): boolean;
+/**
+ * The sidecar directory for a document's data files:
+ * `<docbasename>_files/data/`. One helper owns the convention so importers,
+ * the editor's drop pipeline, and hosts agree on where data lives.
+ */
+declare function dataSidecarPrefix(docBasename: string): string;
+/** A bounded window of tabular data read from a sidecar file. */
+interface DataSourceTable {
+    headers: string[];
+    /** Preview window of data rows, cells stringified for display. */
+    rows: string[][];
+    align?: ('left' | 'center' | 'right' | null)[];
+    /**
+     * Full data-row count in the source AFTER any view-state filter (not just
+     * the preview window). With no filter this is the raw row count.
+     */
+    totalRows: number;
+    totalCols: number;
+    /** Raw row count before filtering, when a filter was applied. */
+    unfilteredTotalRows?: number;
+    /** Problems parsing/applying `sort`/`filter` (see `@bendyline/squisq/table`). */
+    viewIssues?: ViewIssue[];
+}
+interface DataSourceReadOptions {
+    /** Worksheet name (workbook sources only). */
+    sheet?: string;
+    /** Top-left cell of the region, e.g. `'B7'` (workbook sources only). */
+    anchor?: string;
+    /** Whether row 1 of the source is a header row. Default true. */
+    headerRow?: boolean;
+    /** Maximum data rows to return in `rows`. */
+    maxRows: number;
+    /**
+     * Raw view-state params (`{[dataTable … sort=… filter=…]}`). Readers parse
+     * them against their REAL headers and apply `applyTableViewState` on the
+     * full body BEFORE windowing to `maxRows` — the resolver cannot do it, the
+     * rows are already gone by then. Problems surface via
+     * `DataSourceTable.viewIssues`, never a throw.
+     */
+    sort?: string;
+    filter?: string;
+}
+/**
+ * Decodes one family of data files. `extensions` are lowercase without the
+ * dot (`['csv', 'tsv']`). `read` may throw — the resolver converts failures
+ * into diagnostics rather than propagating them.
+ */
+interface DataSourceReader {
+    extensions: readonly string[];
+    read(data: ArrayBuffer, opts: DataSourceReadOptions): Promise<DataSourceTable>;
+}
+interface ResolveDataReferencesOptions {
+    readers: readonly DataSourceReader[];
+    /** Preview window size when a block has no `previewRows` param. Default 50. */
+    maxPreviewRows?: number;
+    /**
+     * Caller-owned memo of reader reads, keyed by src + read options. A
+     * reader read is a FULL-body parse (view state applies before
+     * windowing), and the editor's projection path re-resolves on every
+     * debounce — for a 20 MB sidecar that cost per keystroke is not
+     * acceptable. The CALLER owns invalidation: clear or replace the map
+     * when the underlying bytes may have changed (the editor scopes its
+     * cache to the container and clears it on every mediaRevision bump).
+     */
+    tableCache?: Map<string, Promise<DataSourceTable>>;
+}
+interface ResolvedDataReferences {
+    /** The doc with previews filled in — the SAME object when nothing changed. */
+    doc: Doc;
+    diagnostics: DocDiagnostic[];
+}
+/** Stats recorded on `templateData.srcStats` alongside the preview rows. */
+interface DataSourceStats {
+    /** Data rows after any view-state filter. */
+    totalRows: number;
+    totalCols: number;
+    previewRows: number;
+    truncated: boolean;
+    /** Raw source rows before filtering, when a filter was applied. */
+    unfilteredTotalRows?: number;
+}
+/**
+ * Resolve every `src`-referenced table/chart block against the container.
+ *
+ * - Author data wins: blocks that already carry `headers`/`rows` (data fence,
+ *   `{[…]}` params) are left untouched.
+ * - Failures never throw: a missing file, unknown extension, or reader error
+ *   becomes a diagnostic and the block is left as-is — its body link still
+ *   renders in every projection.
+ * - Identity short-circuit: when no block changed, the input doc object is
+ *   returned unchanged.
+ */
+declare function resolveDataReferences(doc: Doc, container: ContentContainer, options: ResolveDataReferencesOptions): Promise<ResolvedDataReferences>;
+
 /**
  * Structured template data from markdown body content.
  *
@@ -3911,4 +4028,4 @@ declare function treeFromMarkdownList(list: MarkdownList): Tree;
 /** Find the first top-level markdown list in a block's body, if any. */
 declare function findFirstList(contents: MarkdownBlockNode[] | undefined): MarkdownList | undefined;
 
-export { ASCII_CHAR_H, ASCII_CHAR_W, ASCII_DIAGRAM_FENCE_LANGS, ASCII_TIMELINE_FENCE_LANGS, type AccentLayout, type AsciiDiagram, type AsciiDiagramDetection, type AsciiDiagramEdge, type AsciiDiagramNode, type AsciiTimeline, type AsciiTimelineDetection, type AsciiTimelineEvent, type AsciiTimelineLink, type AsciiTimelineMarker, type AsciiTimelineSide, type AsciiTimelineStats, type AsciiTimelineStyle, type AsciiTimelineTrack, type AudioSegmentTiming, BASE_INPUT_DESCRIPTORS, BLOCK_MEDIA_LAYOUT_POLICIES, BUILTIN_DASHBOARD_LAYOUTS, type BlockLayerMaterialization, type BlockMediaLayoutPolicy, type BuildPreviewDocOptions, type BuiltInTemplateName, CONTAINER_TEMPLATES, COVER_SLIDE_FRONTMATTER_KEYS, COVER_SLIDE_TEMPLATE_OPTIONS, type ClipBox, type ConnectorAnchor, type ConnectorPort, type ConnectorRouting, type ConnectorSnapPoint, type CoverBlockInput, type CoverSlidePlayback, type CoverSlideSettings, type CoverSlideTemplate, type CoverSlideTemplateOption, DASHBOARD_AUTO_LAYOUT_ID, DASHBOARD_FRONTMATTER_KEYS, DASHBOARD_STYLES, DASHBOARD_STYLE_IDS, DASHBOARD_ZOOM_LEVELS, DEFAULT_COVER_SLIDE_SETTINGS, DEFAULT_DASHBOARD_SETTINGS, DEFAULT_DASHBOARD_STYLE, DEFAULT_LAYOUT, DIAGRAM_LABEL_HORIZONTAL_PADDING, DIAGRAM_LABEL_LINE_HEIGHT, DIAGRAM_LABEL_MIN_FONT_SIZE, DIAGRAM_LABEL_VERTICAL_PADDING, type DashboardCell, type DashboardCellChrome, type DashboardCellDefinition, type DashboardCellFrame, type DashboardDiagnostic, type DashboardLayoutDefinition, type DashboardLayoutSummary, type DashboardLayoutValidationError, type DashboardLayoutValidationResult, type DashboardMaterialization, type DashboardRectPct, type DashboardSettings, type DashboardSettingsOverrides, type DashboardStyleId, type DashboardStyleSummary, type DashboardTitle, type DashboardTitleSlotDefinition, type DashboardZoomCandidate, type DashboardZoomLevel, type DashboardZoomMode, type DataFenceParseResult, type DeriveTemplateInputsOptions, type DetectAsciiTimelineOptions, type DiagramEdge, type DiagramLabelFit, type DiagramLayout, type DiagramLayoutOptions, type DiagramNodePosition, DocBlock, type DrawingConnector, type DrawingLayout, type DrawingLayoutOptions, type DrawingShape, type DrawingShapeKind, type EmbeddedVideo, type ExpandDocBlocksOptions, type ExtractedTableData, FRONTMATTER_DASHBOARD_LAYOUTS_KEY, type FirstImage, type Flashcard, type FlashcardChoice, type FlashcardDeck, type FlashcardDiagnostic, type FlashcardDiagnosticCode, type FlashcardFace, type FlashcardKind, type FlashcardSourceMode, type InputCoercion, type LayerMaterializationDiagnostic, type LayerMaterializationFailureMode, type LayerMaterializationSource, type LayoutLayerDefaults, type LayoutLayersResult, MAX_COVER_SLIDE_DURATION_SECONDS, type MarkdownToDocOptions, type MarkdownValidationResult, type MaterializeBlockLayersOptions, type MaterializeDashboardOptions, type MaterializeFlashcardsOptions, type NarrationResolution, type NativeMediaLayout, type NoMediaLayout, PAGE_BASE_CSS, PATH_SHAPE_KINDS, PageSection, type PageSectionContext, type PageSectionDraft, PersistentLayerConfig, type RenderAsciiDiagramOptions, type RenderAsciiTimelineOptions, type RenderTreeOptions, type RepairResult, type ResolvedDashboardCell, type ResolvedPageBlock, type RichListItem, type RuntimeTemplateRegistry, SHAPE_NAMES, type SectionExtractor, type SupplementalMediaLayoutVariant, type SupplementalMediaShape, type SupplementalMediaVariantMatrix, TABLE_FED_TEMPLATES, TEMPLATE_AUTHORING_METADATA, TEMPLATE_INPUT_DESCRIPTORS, TEMPLATE_METADATA, TREE_FENCE_LANGS, type TemplateAuthoringMetadata, type TemplateAuthoringRole, TemplateBlock, type TemplateBodyPolicy, TemplateContext, type TemplateInputDescriptor, type TemplateMediaOwnership, type TemplateMetadata, type TemplateParamFinding, Theme, ThemeColorScheme, type Tree, type TreeDetection, type TreeItem, type TreeNode, type UnconsumedMediaBehavior, type ValidateOptions, ViewportConfig, ViewportOrientation, adjustY, anchorPoint, applyNarrationTiming, applyRenderStyleToLayers, asciiCellToCanvas, asciiDiagramFromBlocks, asciiDiagramFromTemplateData, asciiDiagramToTemplateData, asciiTimelineToTemplateData, autoTemplatePreservesContent, bigText, buildDashboardCellChrome, buildPageCss, buildPageCssVars, buildPreviewDoc, buildRegistry, canvasToAsciiCell, chooseDashboardLayout, clipEndpoints, clipPoint, coerceTemplateParams, comparisonBar, composeDashboardLayers, computeDiagramLayout, computeDrawingLayout, computeLayoutLayers, connectorPath, contentBlock, countBlocks, coverBlock, createAccentLayers, cssFilterForTreatment, dashboardCanvasFill, dashboardCellAccent, dataTable, dateEvent, definitionCard, deriveTemplateInputs, desiredCellZoom, detectAsciiDiagram, detectAsciiTimeline, detectTree, diagramBlock, docToMarkdown, documentTitleFromFileName, drawingBlock, expandCoverBlock, expandDocBlocks, expandPersistentLayers, extractBlockquoteText, extractBodyPlainText, extractEmbeddedVideos, extractFirstEmbeddedVideo, extractFirstImage, extractImages, extractListItems, extractRichListItems, extractTableData, extractTableFromContents, factCard, fallbackBlockLayers, findFirstList, findFirstTable, fitBigTextSize, fitDiagramLabel, flattenBlocks, flattenRenderableBlocks, fullBleedQuote, getAccentLayout, getAnimationProgress, getAnimationStyle, getAvailableTemplates, getBlockBodyText, getBlockDepth, getBlockMediaLayoutPolicy, getDashboardLayoutSummaries, getDefaultAnimation, getDefaultAnimationDuration, getOverlayOpacity, getPersistentLayersFromTheme, getPinnedBlockMeta, getTemplateHint, getThemeFont, getTransitionClass, hasTemplate, imageWithCaption, isAsciiDiagramFence, isAsciiTimelineFence, isContainerTemplate, isDataFence, isEligibleAsciiFenceLang, isEligibleAsciiTimelineFenceLang, isEligibleTreeFenceLang, isExplicitDiagramLang, isExplicitTimelineLang, isExplicitTreeLang, isRepairableDiagram, isShapeName, isTemplatedPageBlock, isTreeFence, isWrappedFlowTimelineSource, layoutBlock, layoutCapacity, leftFeature, lineStyleDasharray, lintTemplateParams, listBlock, listDashboardLayouts, mapBlock, markdownBlockSeparatorLines, markdownToDoc, markerPath, materializeBlockLayers, materializeDashboard, materializeFlashcards, nearestSnapPoint, normalizeDashboardZoom, normalizeShapeKind, pageStyleDataAttributes, parseAsciiDiagram, parseAsciiTimeline, parseAsciiTimelineWithStats, parseDataFence, parseTree, parseWrappedFlowTimeline, parseYamlSubset, photoGrid, pullQuote, quoteBlock, readCustomTemplatesFromFrontmatter, readCustomThemesFromFrontmatter, readDashboardLayoutsFromFrontmatter, renderAsciiDiagram, renderAsciiTimeline, renderMarkdownBlocksHtml, renderTree, repairAsciiDiagram, replaceDataFence, resolveAudioMapping, resolveColorScheme, resolveCoverSlideSettings, resolveDashboardLayoutDefinition, resolveDashboardSettings, resolveDashboardStyleId, resolveDashboardZooms, resolveFlashcardMarker, resolveLayoutCells, resolvePageBlock, resolvePersistentLayers, resolveTemplateName, resolveThemeForDoc, rightFeature, scaleAnimationDuration, scoreTextSimilarity, sectionExtractors, sectionHeader, shapePath, shouldUseShadow, snapEndpoints, snapPoints, statHighlight, stripBlockBackdropLayer, stripsBlockBackdrop, templateRegistry, themeWantsAmbientMotion, themedEntrance, themedFontSize, themedImageTreatment, themedScrim, themedSurfaceGradient, timelineBlock, titleBlock, transposeCells, treeBlock, treeFromMarkdownList, treeFromTemplateData, treeToTemplateData, twoColumn, validateDashboardLayoutDefinition, validateMarkdownDoc, validateMarkdownSource, videoPullQuote, videoWithCaption, wrapWithPersistentLayers, writeCustomTemplatesToFrontmatter, writeCustomThemesToFrontmatter, writeDashboardLayoutsToFrontmatter };
+export { ASCII_CHAR_H, ASCII_CHAR_W, ASCII_DIAGRAM_FENCE_LANGS, ASCII_TIMELINE_FENCE_LANGS, type AccentLayout, type AsciiDiagram, type AsciiDiagramDetection, type AsciiDiagramEdge, type AsciiDiagramNode, type AsciiTimeline, type AsciiTimelineDetection, type AsciiTimelineEvent, type AsciiTimelineLink, type AsciiTimelineMarker, type AsciiTimelineSide, type AsciiTimelineStats, type AsciiTimelineStyle, type AsciiTimelineTrack, type AudioSegmentTiming, BASE_INPUT_DESCRIPTORS, BLOCK_MEDIA_LAYOUT_POLICIES, BUILTIN_DASHBOARD_LAYOUTS, type BlockLayerMaterialization, type BlockMediaLayoutPolicy, type BuildPreviewDocOptions, type BuiltInTemplateName, CONTAINER_TEMPLATES, COVER_SLIDE_FRONTMATTER_KEYS, COVER_SLIDE_TEMPLATE_OPTIONS, type ClipBox, type ConnectorAnchor, type ConnectorPort, type ConnectorRouting, type ConnectorSnapPoint, type CoverBlockInput, type CoverSlidePlayback, type CoverSlideSettings, type CoverSlideTemplate, type CoverSlideTemplateOption, DASHBOARD_AUTO_LAYOUT_ID, DASHBOARD_FRONTMATTER_KEYS, DASHBOARD_STYLES, DASHBOARD_STYLE_IDS, DASHBOARD_ZOOM_LEVELS, DATA_FILE_EXTENSIONS, DEFAULT_COVER_SLIDE_SETTINGS, DEFAULT_DASHBOARD_SETTINGS, DEFAULT_DASHBOARD_STYLE, DEFAULT_LAYOUT, DIAGRAM_LABEL_HORIZONTAL_PADDING, DIAGRAM_LABEL_LINE_HEIGHT, DIAGRAM_LABEL_MIN_FONT_SIZE, DIAGRAM_LABEL_VERTICAL_PADDING, type DashboardCell, type DashboardCellChrome, type DashboardCellDefinition, type DashboardCellFrame, type DashboardDiagnostic, type DashboardLayoutDefinition, type DashboardLayoutSummary, type DashboardLayoutValidationError, type DashboardLayoutValidationResult, type DashboardMaterialization, type DashboardRectPct, type DashboardSettings, type DashboardSettingsOverrides, type DashboardStyleId, type DashboardStyleSummary, type DashboardTitle, type DashboardTitleSlotDefinition, type DashboardZoomCandidate, type DashboardZoomLevel, type DashboardZoomMode, type DataFenceParseResult, type DataSourceReadOptions, type DataSourceReader, type DataSourceStats, type DataSourceTable, type DeriveTemplateInputsOptions, type DetectAsciiTimelineOptions, type DiagramEdge, type DiagramLabelFit, type DiagramLayout, type DiagramLayoutOptions, type DiagramNodePosition, DocBlock, type DrawingConnector, type DrawingLayout, type DrawingLayoutOptions, type DrawingShape, type DrawingShapeKind, type EmbeddedVideo, type ExpandDocBlocksOptions, type ExtractedTableData, FRONTMATTER_DASHBOARD_LAYOUTS_KEY, type FirstImage, type Flashcard, type FlashcardChoice, type FlashcardDeck, type FlashcardDiagnostic, type FlashcardDiagnosticCode, type FlashcardFace, type FlashcardKind, type FlashcardSourceMode, type InputCoercion, type LayerMaterializationDiagnostic, type LayerMaterializationFailureMode, type LayerMaterializationSource, type LayoutLayerDefaults, type LayoutLayersResult, MAX_COVER_SLIDE_DURATION_SECONDS, type MarkdownToDocOptions, type MarkdownValidationResult, type MaterializeBlockLayersOptions, type MaterializeDashboardOptions, type MaterializeFlashcardsOptions, type NarrationResolution, type NativeMediaLayout, type NoMediaLayout, PAGE_BASE_CSS, PATH_SHAPE_KINDS, PageSection, type PageSectionContext, type PageSectionDraft, PersistentLayerConfig, type RenderAsciiDiagramOptions, type RenderAsciiTimelineOptions, type RenderTreeOptions, type RepairResult, type ResolveDataReferencesOptions, type ResolvedDashboardCell, type ResolvedDataReferences, type ResolvedPageBlock, type RichListItem, type RuntimeTemplateRegistry, SHAPE_NAMES, type SectionExtractor, type SupplementalMediaLayoutVariant, type SupplementalMediaShape, type SupplementalMediaVariantMatrix, TABLE_FED_TEMPLATES, TEMPLATE_AUTHORING_METADATA, TEMPLATE_INPUT_DESCRIPTORS, TEMPLATE_METADATA, TREE_FENCE_LANGS, type TemplateAuthoringMetadata, type TemplateAuthoringRole, TemplateBlock, type TemplateBodyPolicy, TemplateContext, type TemplateInputDescriptor, type TemplateMediaOwnership, type TemplateMetadata, type TemplateParamFinding, Theme, ThemeColorScheme, type Tree, type TreeDetection, type TreeItem, type TreeNode, type UnconsumedMediaBehavior, type ValidateOptions, ViewportConfig, ViewportOrientation, adjustY, anchorPoint, applyNarrationTiming, applyRenderStyleToLayers, asciiCellToCanvas, asciiDiagramFromBlocks, asciiDiagramFromTemplateData, asciiDiagramToTemplateData, asciiTimelineToTemplateData, autoTemplatePreservesContent, bigText, buildDashboardCellChrome, buildPageCss, buildPageCssVars, buildPreviewDoc, buildRegistry, canvasToAsciiCell, chooseDashboardLayout, clipEndpoints, clipPoint, coerceTemplateParams, comparisonBar, composeDashboardLayers, computeDiagramLayout, computeDrawingLayout, computeLayoutLayers, connectorPath, contentBlock, countBlocks, coverBlock, createAccentLayers, cssFilterForTreatment, dashboardCanvasFill, dashboardCellAccent, dataSidecarPrefix, dataTable, dateEvent, definitionCard, deriveTemplateInputs, desiredCellZoom, detectAsciiDiagram, detectAsciiTimeline, detectTree, diagramBlock, docToMarkdown, documentTitleFromFileName, drawingBlock, expandCoverBlock, expandDocBlocks, expandPersistentLayers, extractBlockquoteText, extractBodyPlainText, extractEmbeddedVideos, extractFirstEmbeddedVideo, extractFirstImage, extractImages, extractListItems, extractRichListItems, extractTableData, extractTableFromContents, factCard, fallbackBlockLayers, findFirstList, findFirstTable, fitBigTextSize, fitDiagramLabel, flattenBlocks, flattenRenderableBlocks, fullBleedQuote, getAccentLayout, getAnimationProgress, getAnimationStyle, getAvailableTemplates, getBlockBodyText, getBlockDepth, getBlockMediaLayoutPolicy, getDashboardLayoutSummaries, getDefaultAnimation, getDefaultAnimationDuration, getOverlayOpacity, getPersistentLayersFromTheme, getPinnedBlockMeta, getTemplateHint, getThemeFont, getTransitionClass, hasTemplate, imageWithCaption, isAsciiDiagramFence, isAsciiTimelineFence, isContainerTemplate, isDataFence, isDataFilePath, isEligibleAsciiFenceLang, isEligibleAsciiTimelineFenceLang, isEligibleTreeFenceLang, isExplicitDiagramLang, isExplicitTimelineLang, isExplicitTreeLang, isRepairableDiagram, isShapeName, isTemplatedPageBlock, isTreeFence, isWrappedFlowTimelineSource, layoutBlock, layoutCapacity, leftFeature, lineStyleDasharray, lintTemplateParams, listBlock, listDashboardLayouts, mapBlock, markdownBlockSeparatorLines, markdownToDoc, markerPath, materializeBlockLayers, materializeDashboard, materializeFlashcards, nearestSnapPoint, normalizeDashboardZoom, normalizeShapeKind, pageStyleDataAttributes, parseAsciiDiagram, parseAsciiTimeline, parseAsciiTimelineWithStats, parseDataFence, parseTree, parseWrappedFlowTimeline, parseYamlSubset, photoGrid, pullQuote, quoteBlock, readCustomTemplatesFromFrontmatter, readCustomThemesFromFrontmatter, readDashboardLayoutsFromFrontmatter, renderAsciiDiagram, renderAsciiTimeline, renderMarkdownBlocksHtml, renderTree, repairAsciiDiagram, replaceDataFence, resolveAudioMapping, resolveColorScheme, resolveCoverSlideSettings, resolveDashboardLayoutDefinition, resolveDashboardSettings, resolveDashboardStyleId, resolveDashboardZooms, resolveDataReferences, resolveFlashcardMarker, resolveLayoutCells, resolvePageBlock, resolvePersistentLayers, resolveTemplateName, resolveThemeForDoc, rightFeature, scaleAnimationDuration, scoreTextSimilarity, sectionExtractors, sectionHeader, shapePath, shouldUseShadow, snapEndpoints, snapPoints, statHighlight, stripBlockBackdropLayer, stripsBlockBackdrop, templateRegistry, themeWantsAmbientMotion, themedEntrance, themedFontSize, themedImageTreatment, themedScrim, themedSurfaceGradient, timelineBlock, titleBlock, transposeCells, treeBlock, treeFromMarkdownList, treeFromTemplateData, treeToTemplateData, twoColumn, validateDashboardLayoutDefinition, validateMarkdownDoc, validateMarkdownSource, videoPullQuote, videoWithCaption, wrapWithPersistentLayers, writeCustomTemplatesToFrontmatter, writeCustomThemesToFrontmatter, writeDashboardLayoutsToFrontmatter };