@brianmsm/quarto-bento 0.0.0-stage → 0.1.0

package/distribution/runtime/src/integration/quarto.ts

@@ -0,0 +1,457 @@
+import { readSourceInline } from "../render/source-inline.ts";
+import {
+  assertCompatibleProducerFilters,
+  attachProducerCapture,
+  prepareProducerCapture,
+  type ProducerManifest,
+} from "../render/producer-capture.ts";
+import {
+  assertDesignRegistryUnchanged,
+  loadDesignRegistry,
+} from "../render/registry.ts";
+import { basename, dirname, resolve } from "node:path";
+import { extractDocument } from "../render/html.ts";
+import { hashSource, scanSource } from "../source/mod.ts";
+import { assertCompatibleComponentSource } from "../render/components.ts";
+import { assertOutputUnchanged, sha256, StateError } from "../state/mod.ts";
+import {
+  assertSourceThemeReferences,
+  projectPaths,
+  renderProjectFromAst,
+  withProject,
+} from "../core/project.ts";
+
+import { assertSafeQuartoInvocation, processStartTime } from "./invocation.ts";
+
+interface QuartoRun {
+  version: 1;
+  token: string;
+  source: string;
+  sourceHash: string;
+  designHash?: string | null;
+  producerHash?: string;
+  imageAssets?: Record<string, string>;
+  revision: number | null;
+  backupHash: string | null;
+  process: { pid: number; startTime: string };
+}
+const receiptName = "quarto-run.json";
+const stageName = "quarto-stage";
+const producerManifestName = "producer-manifest.json";
+const producerOutputName = "producer-output.jsonl";
+async function assertPrivateStageFile(path: string): Promise<void> {
+  if (!(await fileExists(path))) return;
+  const info = await Deno.lstat(path);
+  if (
+    !info.isFile || info.isSymlink || (info.nlink !== null && info.nlink > 1)
+  ) {
+    throw new Error(
+      "UNSAFE_STAGE_PATH: producer receipts must be ordinary unlinked files",
+    );
+  }
+}
+async function clearProducerStage(stateDir: string): Promise<void> {
+  const stage = resolve(stateDir, stageName);
+  if (!(await fileExists(stage))) return;
+  await realDirectory(stage);
+  for (const name of [producerManifestName, producerOutputName]) {
+    const path = resolve(stateDir, stageName, name);
+    if (await fileExists(path)) await Deno.remove(path);
+  }
+}
+function backupPath(stateDir: string, run: QuartoRun): string {
+  return resolve(stateDir, "history", `quarto-baseline-${run.token}.html`);
+}
+async function fileExists(path: string): Promise<boolean> {
+  try {
+    await Deno.lstat(path);
+    return true;
+  } catch (e) {
+    if (e instanceof Deno.errors.NotFound) return false;
+    throw e;
+  }
+}
+async function checkOutput(
+  state: Parameters<typeof assertOutputUnchanged>[0],
+  output: string,
+) {
+  try {
+    await assertOutputUnchanged(state, output);
+  } catch (e) {
+    if (e instanceof StateError) throw new Error(`${e.code}: ${e.message}`);
+    throw e;
+  }
+}
+/** inspect includes YAML inheritance; unlike rendering, it does not execute chunks. */
+async function inspectOutput(source: string): Promise<void> {
+  const inspected = await new Deno.Command("quarto", {
+    args: ["inspect", source],
+    cwd: dirname(source),
+    stdout: "piped",
+    stderr: "piped",
+  }).output();
+  if (!inspected.success) {
+    throw new Error(
+      `QUARTO_INSPECT_FAILED: ${new TextDecoder().decode(inspected.stderr)}`,
+    );
+  }
+  const formats =
+    JSON.parse(new TextDecoder().decode(inspected.stdout)).formats;
+  if (
+    !formats || Object.keys(formats).length !== 1 || !formats["qbento-html"]
+  ) {
+    throw new Error(
+      "QBENTO_FORMAT_REQUIRED: select only qbento-html in QMD/project YAML; remove format: html (source remains unchanged)",
+    );
+  }
+  const expected = basename(source).replace(/\.qmd$/, ".qbento-stage.html");
+  if (
+    formats["qbento-html"].pandoc?.["output-file"] !== expected ||
+    formats["qbento-html"].render?.["output-ext"] !== "qbento-stage.html"
+  ) {
+    throw new Error(
+      "UNSAFE_QUARTO_OUTPUT: remove output-file/output-ext overrides; Quarto must write its disposable stage",
+    );
+  }
+  const stageOutput = resolve(dirname(source), expected);
+  if (await fileExists(stageOutput)) {
+    const info = await Deno.lstat(stageOutput);
+    if (
+      !info.isFile || info.isSymlink || (info.nlink !== null && info.nlink > 1)
+    ) {
+      throw new Error(
+        "UNSAFE_STAGE_PATH: disposable stage must be an ordinary unlinked file, never an alias to the final deck",
+      );
+    }
+  }
+  const outputDir = Deno.env.get("QUARTO_PROJECT_OUTPUT_DIR");
+  if (outputDir && resolve(outputDir) !== dirname(source)) {
+    throw new Error(
+      "UNSUPPORTED_QUARTO_OUTPUT_DIR: keep the default project output directory for qbento",
+    );
+  }
+}
+async function fileList(name: "INPUT" | "OUTPUT"): Promise<string[]> {
+  const file = Deno.env.get(`QUARTO_USE_FILE_FOR_PROJECT_${name}_FILES`);
+  const value = file
+    ? await Deno.readTextFile(file)
+    : Deno.env.get(`QUARTO_PROJECT_${name}_FILES`) ?? "";
+  return value.split(/\r?\n/).filter(Boolean);
+}
+async function realDirectory(path: string) {
+  await Deno.mkdir(path, { recursive: true });
+  const info = await Deno.lstat(path);
+  if (!info.isDirectory || info.isSymlink) {
+    throw new Error(`UNSAFE_STAGE_PATH: ${path} must be a real directory`);
+  }
+}
+async function readReceipt(path: string): Promise<QuartoRun> {
+  const value = JSON.parse(await Deno.readTextFile(path));
+  if (
+    value.version !== 1 || typeof value.token !== "string" ||
+    !/^[a-f0-9-]{36}$/.test(value.token) ||
+    typeof value.source !== "string" || typeof value.sourceHash !== "string" ||
+    !(value.designHash === undefined || value.designHash === null ||
+      typeof value.designHash === "string" &&
+        /^[a-f0-9]{64}$/.test(value.designHash)) ||
+    !(value.producerHash === undefined ||
+      typeof value.producerHash === "string" &&
+        /^[a-f0-9]{64}$/.test(value.producerHash)) ||
+    !(value.imageAssets === undefined ||
+      value.imageAssets && typeof value.imageAssets === "object" &&
+        !Array.isArray(value.imageAssets) &&
+        Object.entries(value.imageAssets).every(([id, digest]) =>
+          id && typeof digest === "string" && /^[a-f0-9]{64}$/.test(digest)
+        )) ||
+    !(value.revision === null || Number.isInteger(value.revision)) ||
+    !(value.backupHash === null || typeof value.backupHash === "string") ||
+    !Number.isInteger(value.process?.pid) ||
+    typeof value.process?.startTime !== "string"
+  ) {
+    throw new Error("INVALID_QUARTO_RECEIPT: inspect .qbento/quarto-run.json");
+  }
+  return value;
+}
+
+/** A durable receipt prevents overlapping external renders. */
+export async function beforeQuartoRender(): Promise<void> {
+  if (Deno.env.get("QBENTO_INTERNAL_RENDER") === "1") return;
+  const inputs = await fileList("INPUT");
+  if (inputs.length !== 1 || !inputs[0].endsWith(".qmd")) {
+    throw new Error(
+      "SINGLE_QMD_REQUIRED: qbento project renders exactly one QMD",
+    );
+  }
+  const source = resolve(inputs[0]);
+  if (dirname(source) !== Deno.cwd()) {
+    throw new Error(
+      "SOURCE_AT_PROJECT_ROOT: place the single QMD beside _quarto.yml",
+    );
+  }
+  const process = await assertSafeQuartoInvocation(source);
+  await assertCompatibleProducerFilters(source, "qbento-html");
+  const original = scanSource(await Deno.readTextFile(source));
+  assertCompatibleComponentSource(original);
+  if (
+    original.blocks.some((block) =>
+      block.kind === "image" && block.origin === "computed"
+    )
+  ) {
+    throw new Error(
+      "UNSUPPORTED_AUTHORED_IMAGE: computed image captions/paths require a verified producer adapter",
+    );
+  }
+  const imageProofs = original.blocks.some((block) => block.kind === "image")
+    ? await readSourceInline(original, dirname(source))
+    : new Map();
+  const imageAssets = Object.fromEntries(
+    [...imageProofs].filter(([, proof]) => proof.kind === "image").map((
+      [id, proof],
+    ) => [id, hashSource(proof.image!.data!)]),
+  );
+  const registry = await loadDesignRegistry(dirname(source));
+  await inspectOutput(source);
+  await withProject(source, async (paths, store) => {
+    const state = await store.load();
+    if (state) assertSourceThemeReferences(state.emitted, state.ownership);
+    await checkOutput(state, paths.output);
+    const receipt = resolve(paths.stateDir, receiptName);
+    const run: QuartoRun = {
+      version: 1,
+      token: crypto.randomUUID(),
+      source,
+      sourceHash: hashSource(await Deno.readTextFile(source)),
+      designHash: registry.hash,
+      imageAssets,
+      revision: state?.revision ?? null,
+      backupHash: null,
+      process,
+    };
+    if (run.sourceHash !== original.hash) {
+      throw new Error(
+        "SOURCE_CHANGED: QMD changed during image/source preflight; execution refused",
+      );
+    }
+    try {
+      await Deno.writeTextFile(receipt, JSON.stringify(run, null, 2) + "\n", {
+        createNew: true,
+      });
+    } catch (e) {
+      if (e instanceof Deno.errors.AlreadyExists) {
+        throw new Error(
+          "QUARTO_RENDER_PENDING: another render or failed execution has a receipt; run the explicit Quarto recovery operation after the render stops (final HTML and project edits remain intact)",
+        );
+      }
+      throw e;
+    }
+    // Independent copy: a hardlink would also be truncated by Pandoc --output.
+    if (await fileExists(paths.output)) {
+      const bytes = await Deno.readFile(paths.output);
+      if (await sha256(bytes) !== state?.output?.sha256) {
+        throw new Error(
+          "UNCAPTURED_HTML_EDITS: output changed during preflight; execution refused",
+        );
+      }
+      await realDirectory(resolve(paths.stateDir, "history"));
+      await Deno.writeFile(backupPath(paths.stateDir, run), bytes, {
+        createNew: true,
+      });
+      run.backupHash = await sha256(bytes);
+      await Deno.writeTextFile(receipt, JSON.stringify(run, null, 2) + "\n");
+    }
+    const stage = resolve(paths.stateDir, stageName);
+    await realDirectory(stage);
+    const capture = await prepareProducerCapture(source, {
+      environment: false,
+    });
+    try {
+      if (capture.manifest.sourceHash !== run.sourceHash) {
+        throw new Error(
+          "QUARTO_SOURCE_MISMATCH: source changed while producer receipts were prepared",
+        );
+      }
+      const manifestPath = resolve(stage, producerManifestName);
+      const outputReceiptPath = resolve(stage, producerOutputName);
+      await assertPrivateStageFile(manifestPath);
+      await assertPrivateStageFile(outputReceiptPath);
+      capture.manifest.outputReceiptPath = outputReceiptPath;
+      const bytes = new TextEncoder().encode(
+        JSON.stringify(capture.manifest) + "\n",
+      );
+      await Deno.writeTextFile(outputReceiptPath, "");
+      await Deno.writeFile(manifestPath, bytes);
+      run.producerHash = await sha256(bytes);
+      await Deno.writeTextFile(receipt, JSON.stringify(run, null, 2) + "\n");
+    } finally {
+      await capture.cleanup();
+    }
+    try {
+      await Deno.remove(resolve(stage, "executed.json"));
+    } catch (e) {
+      if (!(e instanceof Deno.errors.NotFound)) throw e;
+    }
+  });
+}
+
+/** Consume the actual executed AST once; never execute Quarto again here. */
+export async function afterQuartoRender(): Promise<void> {
+  if (Deno.env.get("QBENTO_INTERNAL_RENDER") === "1") return;
+  const outputs = await fileList("OUTPUT");
+  const staged = outputs.filter((path) => path.endsWith(".qbento-stage.html"));
+  if (staged.length !== 1 || outputs.length !== 1) {
+    throw new Error(
+      "QBENTO_FORMAT_REQUIRED: render the single qbento-html format",
+    );
+  }
+  const stateDir = resolve(Deno.cwd(), ".qbento");
+  const receipt = resolve(stateDir, receiptName);
+  const run = await readReceipt(receipt);
+  const paths = projectPaths(run.source);
+  if (
+    paths.stateDir !== stateDir ||
+    basename(staged[0]) !==
+      basename(run.source).replace(/\.qmd$/, ".qbento-stage.html")
+  ) {
+    throw new Error(
+      "QUARTO_SOURCE_MISMATCH: stage and receipt must belong to this project",
+    );
+  }
+  const captured = JSON.parse(
+    await Deno.readTextFile(resolve(stateDir, stageName, "executed.json")),
+  );
+  if (captured.token !== run.token || !Array.isArray(captured.ast?.blocks)) {
+    throw new Error(
+      "STALE_QUARTO_AST: stage was not produced by this execution",
+    );
+  }
+  await realDirectory(resolve(stateDir, stageName));
+  const manifestPath = resolve(stateDir, stageName, producerManifestName);
+  const outputReceiptPath = resolve(stateDir, stageName, producerOutputName);
+  await assertPrivateStageFile(manifestPath);
+  await assertPrivateStageFile(outputReceiptPath);
+  const manifestBytes = await Deno.readFile(manifestPath);
+  if (!run.producerHash || await sha256(manifestBytes) !== run.producerHash) {
+    throw new Error(
+      "INVALID_PRODUCER_RECEIPT: producer manifest differs from the guarded Quarto run",
+    );
+  }
+  const manifest: ProducerManifest = JSON.parse(
+    new TextDecoder().decode(manifestBytes),
+  );
+  if (
+    manifest.sourceHash !== run.sourceHash ||
+    manifest.outputReceiptPath !== outputReceiptPath ||
+    manifest.input !== run.source.replace(/\.qmd$/, ".rmarkdown")
+  ) {
+    throw new Error(
+      "INVALID_PRODUCER_RECEIPT: producer manifest belongs to another source or stage",
+    );
+  }
+  const tokens: string[] = (await Deno.readTextFile(outputReceiptPath)).split(
+    "\n",
+  ).filter(Boolean).map((line) => {
+    const value = JSON.parse(line);
+    if (typeof value !== "string") {
+      throw new Error("INVALID_PRODUCER_RECEIPT: malformed execution ledger");
+    }
+    return value;
+  });
+  captured.ast = attachProducerCapture(captured.ast, manifest, tokens);
+  if (run.designHash !== undefined) {
+    await assertDesignRegistryUnchanged(paths.directory, run.designHash);
+  }
+  const result = await renderProjectFromAst(run.source, {
+    ast: captured.ast,
+    sourceHash: run.sourceHash,
+    assetDirectories: [dirname(resolve(staged[0])), paths.directory],
+    expectedImageAssets: run.imageAssets ?? {},
+    expectedRevision: run.revision,
+    designHash: run.designHash,
+  });
+  await clearProducerStage(stateDir);
+  await Deno.remove(receipt);
+  console.log(`Bento output created: ${result.output}`);
+  for (const diagnostic of result.diagnostics) {
+    console.warn(`${diagnostic.code}: ${diagnostic.message}`);
+  }
+}
+
+/** Explicit recovery after a failed external Quarto run. Retains both outputs. */
+export async function recoverQuartoRender(
+  source: string,
+): Promise<{ restored: boolean; retainedOutput: string | null }> {
+  return await withProject(source, async (paths, store) => {
+    const receipt = resolve(paths.stateDir, receiptName);
+    const run = await readReceipt(receipt);
+    if (Deno.build.os !== "linux") {
+      throw new Error(
+        "QUARTO_RECOVERY_PLATFORM: verify interrupted render manually on this platform",
+      );
+    }
+    if (await processStartTime(run.process.pid) === run.process.startTime) {
+      throw new Error(
+        "QUARTO_RENDER_ACTIVE: the original render process is still running",
+      );
+    }
+    if (run.source !== paths.source) {
+      throw new Error(
+        "QUARTO_SOURCE_MISMATCH: recovery source differs from receipt",
+      );
+    }
+    const state = await store.load();
+    if ((state?.revision ?? null) !== run.revision) {
+      throw new Error(
+        "STALE_REVISION: project changed since this Quarto render; inspect receipt and history manually",
+      );
+    }
+    // Recovery may rename an interrupted publication into history and write a
+    // restored baseline through stage. Verify both children before reading the
+    // backup or mutating either path; an imported .qbento subtree is untrusted.
+    await realDirectory(resolve(paths.stateDir, "history"));
+    await realDirectory(resolve(paths.stateDir, stageName));
+    let retainedOutput: string | null = null;
+    if (run.backupHash) {
+      const bytes = await Deno.readFile(backupPath(paths.stateDir, run));
+      if (await sha256(bytes) !== run.backupHash) {
+        throw new Error("INVALID_QUARTO_BACKUP: baseline checksum mismatch");
+      }
+      if (await fileExists(paths.output)) {
+        if (
+          await sha256(await Deno.readFile(paths.output)) !== run.backupHash
+        ) {
+          // Valid native edits remain in place for explicit capture after recovery.
+          let nativeEdit = false;
+          try {
+            nativeEdit =
+              extractDocument(await Deno.readTextFile(paths.output)).docId ===
+                state?.docId;
+          } catch { /* Truncated outputs are retained separately below. */ }
+          if (nativeEdit) {
+            await clearProducerStage(paths.stateDir);
+            await Deno.remove(receipt);
+            return { restored: false, retainedOutput: paths.output };
+          }
+          retainedOutput = resolve(
+            paths.stateDir,
+            "history",
+            `quarto-interrupted-${crypto.randomUUID()}.html`,
+          );
+          await Deno.rename(paths.output, retainedOutput);
+        }
+      }
+      if (!(await fileExists(paths.output))) {
+        const staging = resolve(
+          paths.stateDir,
+          stageName,
+          `recovered-${crypto.randomUUID()}.html`,
+        );
+        await Deno.writeFile(staging, bytes, { createNew: true });
+        await Deno.link(staging, paths.output);
+        await Deno.remove(staging);
+      }
+    }
+    await clearProducerStage(paths.stateDir);
+    await Deno.remove(receipt);
+    return { restored: run.backupHash !== null, retainedOutput };
+  });
+}

package/distribution/runtime/src/render/assets.ts

@@ -0,0 +1,66 @@
+import { isAbsolute, relative, resolve } from "node:path";
+export async function assetData(
+  src: string,
+  assetRoots: string[],
+): Promise<string> {
+  // UNC and device paths must refuse before realPath can contact a share on Windows.
+  if (/^[a-z][a-z0-9+.-]*:/i.test(src) || /^[/\\]{2}/.test(src)) {
+    throw new Error("EXTERNAL_ASSET: local bundled image required");
+  }
+  try {
+    src = decodeURIComponent(src);
+  } catch {
+    throw new Error("INVALID_ASSET_PATH: malformed escaped local image path");
+  }
+  if (
+    /^[a-z][a-z0-9+.-]*:/i.test(src) || /^[/\\]{2}/.test(src) ||
+    src.includes("\0")
+  ) throw new Error("EXTERNAL_ASSET: local bundled image required");
+  for (const root of assetRoots) {
+    try {
+      const candidate = resolve(root, src);
+      const lexical = relative(resolve(root), candidate);
+      if (
+        lexical === ".." || lexical.startsWith("../") ||
+        lexical.startsWith("..\\") || isAbsolute(lexical)
+      ) continue;
+      const actual = await Deno.realPath(candidate);
+      const rel = relative(await Deno.realPath(root), actual);
+      if (
+        rel === ".." || rel.startsWith("../") || rel.startsWith("..\\") ||
+        isAbsolute(rel)
+      ) continue;
+      const bytes = await Deno.readFile(actual);
+      const extension = actual.split(".").pop()?.toLowerCase();
+      const mime = ({
+        svg: "image/svg+xml",
+        png: "image/png",
+        jpg: "image/jpeg",
+        jpeg: "image/jpeg",
+        webp: "image/webp",
+      } as Record<string, string>)[extension || ""];
+      if (!mime) {
+        throw new Error("UNSUPPORTED_ASSET: image format is not supported");
+      }
+      if (extension === "svg") {
+        const text = new TextDecoder().decode(bytes);
+        if (
+          /<(?:script|foreignObject)\b|\bon\w+\s*=|(?:href|src)\s*=\s*["']\s*(?:https?:|\/\/|javascript:)|<!ENTITY/i
+            .test(text)
+        ) {
+          throw new Error(
+            "UNSAFE_SVG: scripts, external references and entities are not supported",
+          );
+        }
+      }
+      let binary = "";
+      for (const byte of bytes) binary += String.fromCharCode(byte);
+      return `data:${mime};base64,${btoa(binary)}`;
+    } catch (error) {
+      if (!(error instanceof Deno.errors.NotFound)) throw error;
+    }
+  }
+  throw new Error(
+    `MISSING_ASSET: ${src} is not within the source/build directory`,
+  );
+}

package/distribution/runtime/src/render/capture.lua

@@ -0,0 +1,8 @@
+-- Runs after Quarto's HTML transforms, so figures have concrete output assets.
+function Pandoc(doc)
+  local path = os.getenv('QBENTO_AST')
+  if not path then error('QBENTO_AST is required') end
+  local out = assert(io.open(path, 'w'))
+  out:write(pandoc.write(pandoc.Pandoc(doc.blocks, { title = doc.meta.title }), 'json'))
+  out:close()
+end

package/distribution/runtime/src/render/chart.ts

@@ -0,0 +1,165 @@
+/** Bounded chart contract for the actual pinned charts-lite renderer. */
+import { type PlainTable, plainTable } from "./table.ts";
+import type { Element, Json, Node } from "./types.ts";
+import type { Frame } from "./design.ts";
+export type ChartKind = "bar" | "line";
+function fail(message: string): never {
+  throw new Error(`UNSUPPORTED_CHART: ${message}`);
+}
+/** Never use native tableChartColumns: its parseFloat/missing->zero loses data. */
+export function chartNumber(text: string): number {
+  if (!/^-?(?:0|[1-9]\d*)(?:\.\d{1,2})?$/.test(text)) {
+    fail(
+      "Values must be plain decimal numbers with at most two decimal places; missing values, percentages, exponents and locale separators need another adapter.",
+    );
+  }
+  const value = Number(text);
+  if (
+    !Number.isFinite(value) || Math.abs(value) > 1e6 || Object.is(value, -0)
+  ) {
+    fail(
+      "Values must be finite, within -1000000..1000000, and not negative zero.",
+    );
+  }
+  return value;
+}
+export function chartOption(
+  table: PlainTable,
+  kind: ChartKind,
+  frame: Pick<Frame, "w" | "h"> = { w: 1120, h: 460 },
+): Record<string, Json> {
+  if (kind !== "bar" && kind !== "line") fail("Choose bar or line explicitly.");
+  if (!table.header || table.columns.length < 2 || table.columns.length > 5) {
+    fail(
+      "Use a header row, one category column and one to four numeric series.",
+    );
+  }
+  const header = table.rows[0], body = table.rows.slice(1);
+  if (header[0].text !== "") {
+    fail(
+      "The first column header must be empty: pinned Bento does not render a category-axis title, so a meaningful title cannot be silently dropped.",
+    );
+  }
+  if (body.length < (kind === "line" ? 2 : 1) || body.length > 8) {
+    fail("Use one to eight categories for bars, or two to eight for lines.");
+  }
+  const names = header.slice(1).map((cell) => cell.text);
+  const labels = body.map((row) => row[0].text);
+  for (const values of [names, labels]) {
+    if (
+      values.some((value) => !value.trim() || /[\r\n\t\p{Cc}]/u.test(value)) ||
+      new Set(values).size !== values.length
+    ) {
+      fail(
+        "Category labels and series names must be nonempty, unique plain text.",
+      );
+    }
+  }
+  const width = frame.w, fontSize = 14, plotWidth = width - 112 - 24;
+  // Pinned charts-lite drops category labels below a 56px band. Six value-axis
+  // ticks also need actual vertical space: never resize only an outer box.
+  if (
+    !Number.isFinite(width) || !Number.isFinite(frame.h) ||
+    plotWidth < labels.length * 56 || frame.h < 242
+  ) {
+    fail(
+      "The final chart frame needs at least 56px per category and 242px height for readable axes and legend.",
+    );
+  }
+  if (
+    labels.some((s) =>
+      Array.from(s).length * fontSize * 2 > plotWidth / labels.length
+    )
+  ) {
+    fail(
+      "Category labels exceed the conservative single-line space; shorten the labels or use fewer categories.",
+    );
+  }
+  if (
+    names.reduce((n, s) => n + Array.from(s).length * fontSize * 2 + 40, 0) >
+      width - 32
+  ) {
+    fail("Series names exceed the conservative single-line legend space.");
+  }
+  const series = names.map((name, index) => ({
+    type: kind,
+    name,
+    data: body.map((row) => chartNumber(row[index + 1].text)),
+    ...(kind === "line" ? { smooth: false } : {}),
+  }));
+  const values = series.flatMap((s) => s.data);
+  const min = Math.min(0, Math.floor(Math.min(...values)));
+  let max = Math.max(0, Math.ceil(Math.max(...values)));
+  if (max === min) max = min + 1;
+  // Integer bounds yield six ticks at fifths, accurately shown by native fmt(2dp).
+  return {
+    textStyle: { fontFamily: "Arial, sans-serif" },
+    tooltip: { trigger: "axis" },
+    legend: { bottom: 0, textStyle: { fontSize } },
+    grid: { left: 112, right: 24, top: 24, bottom: 78 },
+    xAxis: { type: "category", data: labels, axisLabel: { fontSize } },
+    yAxis: { type: "value", min, max, axisLabel: { fontSize } },
+    series,
+  };
+}
+export function projectChart(
+  table: PlainTable,
+  kind: ChartKind,
+  id: string,
+  y = 166,
+  contentFrame?: Frame,
+): Element {
+  const frame = contentFrame ?? { x: 80, y, w: 1120, h: 460 };
+  if (
+    frame.x < 0 || frame.x + frame.w > 1280 || frame.y < 0 ||
+    frame.y + frame.h > 720
+  ) {
+    fail(
+      "The chart does not fit in the remaining slide area; place it on a separate slide.",
+    );
+  }
+  return {
+    id,
+    type: "chart",
+    preset: kind,
+    option: chartOption(table, kind, frame),
+    ...frame,
+    rotation: 0,
+    opacity: 1,
+  };
+}
+/** Execute no guessing/fallback: a single table under only Quarto cell wrappers. */
+export function executedChartTable(
+  nodes: Node[],
+): { table: PlainTable; computed: boolean } {
+  let found: { table: PlainTable; computed: boolean } | undefined;
+  function walk(nodes: Node[], computed: boolean) {
+    for (const node of nodes) {
+      if (node.t === "Table") {
+        if (found) fail("Use exactly one table per chart producer.");
+        found = { table: plainTable(node), computed };
+      } else if (node.t === "Div") {
+        const [attr, children] = node.c as [
+          [string, string[], [string, string][]],
+          Node[],
+        ];
+        if (
+          attr[2].length || !attr[1].length ||
+          attr[1].some((c) => !["cell", "cell-output-display"].includes(c))
+        ) {
+          fail(
+            "Only plain Quarto cell/output wrappers may surround the chart data table; captions and floats need another adapter.",
+          );
+        }
+        walk(children, computed || attr[1].includes("cell"));
+      } else {fail(
+          `Chart data must be exactly one plain table; ${node.t} cannot be dropped.`,
+        );}
+    }
+  }
+  walk(nodes, false);
+  return found ??
+    fail(
+      "Chart data must contain one table; images cannot be inferred as native data.",
+    );
+}