@brianmsm/quarto-bento 0.0.0-stage → 0.1.1

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

@@ -0,0 +1,82 @@
+import type { BentoDoc } from "./types.ts";
+export const DOCUMENT_BLOCK =
+  /(<script\b[^>]*\bid\s*=\s*["']bento-doc["'][^>]*>)([\s\S]*?)(<\/script\s*>)/gi;
+export function extractDocument(html: string): BentoDoc {
+  const matches = [...html.matchAll(DOCUMENT_BLOCK)];
+  if (matches.length !== 1) {
+    throw new Error("INVALID_HTML: expected exactly one bento-doc block");
+  }
+  const doc = JSON.parse(matches[0][2]);
+  if (
+    doc.format !== "bento/slides" || doc.version !== 1 || !doc.docId ||
+    !Array.isArray(doc.slides)
+  ) {
+    throw new Error(
+      "INVALID_DOCUMENT: incompatible or encrypted Bento document",
+    );
+  }
+  if (
+    doc.collab &&
+    !(Object.keys(doc.collab).sort().join(",") === "key,on,room" &&
+      doc.collab.room === "" && doc.collab.key === "" &&
+      doc.collab.on === false)
+  ) {
+    throw new Error(
+      "COLLABORATION_DISABLED: remove collaboration via an explicit independent copy",
+    );
+  }
+  const slides = new Set();
+  for (const slide of doc.slides) {
+    if (!slide.id || slides.has(slide.id) || !Array.isArray(slide.elements)) {
+      throw new Error("DUPLICATE_ID: invalid slide identity");
+    }
+    slides.add(slide.id);
+    const ids = new Set();
+    for (const el of slide.elements) {
+      if (!el.id || ids.has(el.id)) {
+        throw new Error("DUPLICATE_ID: invalid element identity");
+      }
+      ids.add(el.id);
+    }
+  }
+  return doc;
+}
+export function spliceDocument(
+  shell: string,
+  doc: BentoDoc,
+  preboot = "",
+  csp = "",
+): string {
+  if ([...shell.matchAll(DOCUMENT_BLOCK)].length !== 1) {
+    throw new Error("INVALID_SHELL: bento-doc missing or duplicated");
+  }
+  const json = JSON.stringify(doc).replaceAll("<", "\\u003c");
+  let html = shell.replace(
+    DOCUMENT_BLOCK,
+    (_whole, start, _old, end) => start + json + end,
+  );
+  if (preboot) {
+    if (/<\/script/i.test(preboot)) {
+      throw new Error("INVALID_BOOTSTRAP: closing script token");
+    }
+    html = html.replace(
+      /<head([^>]*)>/i,
+      `<head$1><script>${preboot}</script>`,
+    );
+  }
+  if (csp) {
+    html = html.replace(
+      /<head([^>]*)>/i,
+      `<head$1><meta http-equiv="Content-Security-Policy" content="${
+        escapeHtml(csp)
+      }">`,
+    );
+  }
+  return html;
+}
+export function escapeHtml(value: string): string {
+  return value.replaceAll("&", "&amp;").replaceAll("<", "&lt;").replaceAll(
+    ">",
+    "&gt;",
+  ).replaceAll('"', "&quot;");
+}

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

@@ -0,0 +1,268 @@
+import { assetData } from "./assets.ts";
+import { isAbsolute } from "node:path";
+import { renderInline } from "./inline.ts";
+import type { Node } from "./types.ts";
+export type ImageAttr = [string, string[], [string, string][]];
+export interface AuthoredImageShape {
+  target: string;
+  captionHtml: string;
+  captioned: boolean;
+}
+function fail(): never {
+  throw new Error(
+    "UNSUPPORTED_AUTHORED_IMAGE: use one local standalone Markdown image with a bounded caption; image titles, numbered/cross-reference figures, extra HTML and transformed image structures need an explicit faithful adapter",
+  );
+}
+const plain = (attr: ImageAttr) =>
+  !attr[0] && !attr[1].length && !attr[2].length;
+function image(
+  node: Node,
+  executed: boolean,
+): { target: string; captionHtml: string } {
+  if (node.t !== "Image" || !Array.isArray(node.c) || node.c.length !== 3) {
+    return fail();
+  }
+  const [attr, alt, target] = node.c as [ImageAttr, Node[], [string, string]];
+  if (
+    !Array.isArray(attr) || !Array.isArray(alt) || !Array.isArray(target) ||
+    target.length !== 2 || typeof target[0] !== "string" || target[1] !== ""
+  ) return fail();
+  if (
+    executed
+      ? attr[0] || attr[2].length ||
+        JSON.stringify(attr[1]) !== JSON.stringify(["img-fluid"]) &&
+          !plain(attr)
+      : !plain(attr)
+  ) return fail();
+  return { target: target[0], captionHtml: renderInline(alt) };
+}
+function singleImage(blocks: Node[], executed: boolean) {
+  if (blocks.length !== 1 || !["Plain", "Para"].includes(blocks[0].t)) {
+    return fail();
+  }
+  const content = blocks[0].c as Node[];
+  if (!Array.isArray(content) || content.length !== 1) return fail();
+  return image(content[0], executed);
+}
+/** Original Pandoc Figure is checked independently from Quarto's generated HTML. */
+export function originalImageShape(node: Node): AuthoredImageShape {
+  if (node.t === "Para" || node.t === "Plain") {
+    const value = singleImage([node], false);
+    if (value.captionHtml) return fail();
+    return { ...value, captioned: false };
+  }
+  if (node.t !== "Figure" || !Array.isArray(node.c) || node.c.length !== 3) {
+    return fail();
+  }
+  const [attr, caption, blocks] = node.c as [ImageAttr, [null, Node[]], Node[]];
+  if (
+    !plain(attr) || !Array.isArray(caption) || caption.length !== 2 ||
+    caption[0] !== null || caption[1].length !== 1 ||
+    !["Plain", "Para"].includes(caption[1][0].t)
+  ) return fail();
+  const value = singleImage(blocks, false);
+  const captionHtml = renderInline(caption[1][0].c as Node[]);
+  if (!captionHtml || captionHtml !== value.captionHtml) return fail();
+  return { ...value, captioned: true };
+}
+const raw = (node: Node, kind: "RawBlock" | "RawInline", expected: string) =>
+  node.t === kind &&
+  JSON.stringify(node.c) === JSON.stringify(["html", expected]);
+/** Accept only the known Quarto image wrapper, never general raw HTML. */
+export function executedImageShape(node: Node): AuthoredImageShape {
+  if (node.t === "Figure") return originalImageShape(node);
+  if (node.t === "Para" || node.t === "Plain") {
+    const value = singleImage([node], true);
+    if (value.captionHtml) return fail();
+    return { ...value, captioned: false };
+  }
+  if (node.t !== "Div" || !Array.isArray(node.c) || node.c.length !== 2) {
+    return fail();
+  }
+  const [attr, children] = node.c as [ImageAttr, Node[]];
+  if (
+    attr[0] || attr[2].length ||
+    JSON.stringify([...attr[1]].sort()) !==
+      JSON.stringify(["quarto-figure", "quarto-figure-center"])
+  ) return fail();
+  if (
+    children.length !== 4 || !raw(children[0], "RawBlock", "<figure>") ||
+    !raw(children[3], "RawBlock", "</figure>") || children[2].t !== "Plain"
+  ) return fail();
+  const value = singleImage([children[1]], true);
+  if (value.captionHtml) return fail();
+  const caption = children[2].c as Node[];
+  if (
+    !Array.isArray(caption) || caption.length < 3 ||
+    !raw(caption[0], "RawInline", "<figcaption>") ||
+    !raw(caption.at(-1)!, "RawInline", "</figcaption>")
+  ) return fail();
+  const captionHtml = renderInline(caption.slice(1, -1));
+  if (!captionHtml) return fail();
+  return { target: value.target, captionHtml, captioned: true };
+}
+export function assertImageShape(
+  original: AuthoredImageShape,
+  executed: AuthoredImageShape,
+) {
+  if (JSON.stringify(original) !== JSON.stringify(executed)) {
+    throw new Error(
+      "UNMAPPED_AUTHORED_IMAGE: executed image path or caption differs from the exact original source",
+    );
+  }
+}
+export function assertAuthoredSvgData(src: string) {
+  if (!src.startsWith("data:image/svg+xml;base64,")) return;
+  const svg = new TextDecoder().decode(
+    Uint8Array.from(atob(src.split(",")[1]), (c) => c.charCodeAt(0)),
+  );
+  if (/<!DOCTYPE|<!ENTITY|<(?:script|foreignObject)\b|\bon\w+\s*=/i.test(svg)) {
+    throw new Error(
+      "UNSAFE_SVG: authored images must be self-contained and script-free",
+    );
+  }
+  const css = [...svg.matchAll(/<style\b[^>]*>([\s\S]*?)<\/style>/gi)].map((
+    match,
+  ) => match[1]);
+  css.push(
+    ...[...svg.matchAll(/\bstyle\s*=\s*(?:"([^"]*)"|'([^']*)')/gi)].map((
+      match,
+    ) => match[1] ?? match[2]),
+  );
+  for (const value of css) {
+    const decoded = value.replace(
+      /&#(?:x([0-9a-f]+)|([0-9]+));/gi,
+      (_whole, hex: string, decimal: string) => {
+        const point = parseInt(hex ?? decimal, hex ? 16 : 10);
+        if (
+          point > 0x10ffff || point === 0 || point >= 0xd800 && point <= 0xdfff
+        ) {
+          throw new Error(
+            "UNSAFE_SVG: invalid XML character reference in style",
+          );
+        }
+        return String.fromCodePoint(point);
+      },
+    ).replace(/\/\*[\s\S]*?\*\//g, "");
+    if (/@|\\/.test(decoded)) {
+      throw new Error(
+        "UNSAFE_SVG: authored image styles cannot use at-rules or escaped dependency syntax",
+      );
+    }
+    for (const match of decoded.matchAll(/url\(([^)]*)\)/gi)) {
+      if (!/^\s*["']?#[^\s"']+["']?\s*$/.test(match[1])) {
+        throw new Error(
+          "UNSAFE_SVG: authored image styles must use only internal fragment references",
+        );
+      }
+    }
+  }
+  for (const match of svg.matchAll(/\b(?:href|src)\s*=\s*["']([^"']*)["']/gi)) {
+    if (
+      !/^#[^\s]*$/.test(match[1]) &&
+      !/^data:image\/(?:png|jpeg|webp);base64,[A-Za-z0-9+/=]+$/.test(match[1])
+    ) {
+      throw new Error(
+        "UNSAFE_SVG: authored images cannot reference external or local companion resources",
+      );
+    }
+  }
+  for (const match of svg.matchAll(/url\(([^)]*)\)/gi)) {
+    if (!/^\s*["']?#[^\s"']+["']?\s*$/.test(match[1])) {
+      throw new Error(
+        "UNSAFE_SVG: authored image styles must use only internal fragment references",
+      );
+    }
+  }
+}
+
+/** Read only the source file, not a generated build file sharing its name. */
+export async function authoredImageData(
+  shape: AuthoredImageShape,
+  sourceRoot: string,
+) {
+  if (/[?#]/.test(shape.target)) {
+    throw new Error(
+      "UNSUPPORTED_AUTHORED_IMAGE: image fragments/query semantics need a dedicated adapter",
+    );
+  }
+  let file: string;
+  try {
+    file = decodeURIComponent(shape.target);
+  } catch {
+    throw new Error("INVALID_IMAGE_PATH: malformed escaped local path");
+  }
+  if (
+    !file || isAbsolute(file) || /^[a-z][a-z0-9+.-]*:/i.test(file) ||
+    /^[/\\]{2}/.test(file) || file.includes("\0")
+  ) {
+    throw new Error(
+      "EXTERNAL_ASSET: authored image must use a relative local source asset",
+    );
+  }
+  const data = await assetData(shape.target, [sourceRoot]);
+  assertAuthoredSvgData(data);
+  return data;
+}
+
+import type { SourceBlock, SourceDocument } from "../source/mod.ts";
+import {
+  originalAttributeTokens,
+  originalPandocAttributes,
+} from "../source/attributes.ts";
+import { isNativeIdentity } from "../source/identity-id.ts";
+export function imageNativeIdentities(
+  source: SourceDocument,
+  block: SourceBlock,
+) {
+  const parent = block.parentId
+    ? source.blocks.find((candidate) => candidate.id === block.parentId)
+    : undefined;
+  const attributes = parent
+    ? originalPandocAttributes(
+      parent.raw.split(/\r?\n/)[0].replace(/^\s*:{3,}\s*\{/, "").replace(
+        /\}\s*$/,
+        "",
+      ),
+      originalAttributeTokens(
+        parent.raw.split(/\r?\n/)[0].replace(/^\s*:{3,}\s*\{/, "").replace(
+          /\}\s*$/,
+          "",
+        ),
+      ),
+    )
+    : undefined;
+  const caption = attributes?.[2].find(([name]) => name === "bento-element-id")
+    ?.[1];
+  const image = attributes?.[2].find(([name]) => name === "bento-image-id")
+    ?.[1];
+  if (caption !== undefined || image !== undefined) {
+    if (
+      !caption || !image || !isNativeIdentity(caption) ||
+      !isNativeIdentity(image) || caption === image
+    ) {
+      throw new Error(
+        "INVALID_IMAGE_BINDING: source image pair needs distinct exact caption and image IDs",
+      );
+    }
+    return {
+      imageId: image,
+      captionId: caption,
+      groupId: `${image}-figure`,
+      attributes,
+    };
+  }
+  const imageId = block.stable || parent?.stable
+    ? block.id
+    : `qb-image-${
+      source.blocks.filter((candidate) => candidate.kind === "image").findIndex(
+        (candidate) => candidate.id === block.id,
+      ) + 1
+    }`;
+  return {
+    imageId,
+    captionId: `${imageId}-caption`,
+    groupId: `${imageId}-figure`,
+    attributes,
+  };
+}

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

@@ -0,0 +1,259 @@
+/** Faithful bounded rich-text vocabulary shared by projection and explicit sync. */
+import { StateError } from "../state/mod.ts";
+import { escapeHtml } from "./html.ts";
+import type { Node } from "./types.ts";
+export const INLINE_CODEC_VERSION = 1;
+type Attr = [string, string[], [string, string][]];
+function fail(message: string): never {
+  throw new StateError("UNSUPPORTED_HTML", message);
+}
+function decodeEntities(value: string): string {
+  return value.replace(/&([^;\s]+);/g, (_whole, name: string) => {
+    const named: Record<string, string> = {
+      amp: "&",
+      lt: "<",
+      gt: ">",
+      quot: '"',
+      apos: "'",
+      nbsp: "\u00a0",
+    };
+    if (Object.hasOwn(named, name)) return named[name];
+    if (/^#(?:[0-9]+|x[0-9a-f]+)$/i.test(name)) {
+      const point = name[1].toLowerCase() === "x"
+        ? parseInt(name.slice(2), 16)
+        : parseInt(name.slice(1), 10);
+      if (
+        point > 0 && point <= 0x10ffff && !(point >= 0xd800 && point <= 0xdfff)
+      ) {
+        return String.fromCodePoint(point);
+      }
+    }
+    return fail(`Unsupported or invalid HTML entity &${name};.`);
+  });
+}
+function webLink(href: string): string {
+  if (
+    !/^https?:\/\//i.test(href) || /[\s<>"'\\]/u.test(href) ||
+    Array.from(href).some((c) =>
+      c.charCodeAt(0) < 32 || c.charCodeAt(0) === 127
+    )
+  ) {
+    fail(
+      "Only explicit http/https links without control characters are supported by native Bento.",
+    );
+  }
+  try {
+    if (!new URL(href).hostname) fail("Link has no hostname.");
+  } catch {
+    fail("Link is not a valid web URL.");
+  }
+  return href;
+}
+function plainAttributes(attr: Attr): boolean {
+  return !attr[0] && !attr[1].length && !attr[2].length;
+}
+export function renderInline(nodes: Node[]): string {
+  return nodes.map((node) => {
+    switch (node.t) {
+      case "Str":
+        return escapeHtml(String(node.c));
+      case "Space":
+      case "SoftBreak":
+        return " ";
+      case "LineBreak":
+        return "<br>";
+      case "Strong":
+        return `<b>${renderInline(node.c as Node[])}</b>`;
+      case "Emph":
+        return `<i>${renderInline(node.c as Node[])}</i>`;
+      case "Underline":
+        return `<u>${renderInline(node.c as Node[])}</u>`;
+      case "Strikeout":
+        return `<s>${renderInline(node.c as Node[])}</s>`;
+      case "Code": {
+        const [attr, code] = node.c as [Attr, string];
+        if (!plainAttributes(attr)) {
+          fail("Inline code attributes need an explicit supported projection.");
+        }
+        return `<code>${escapeHtml(code)}</code>`;
+      }
+      case "Span": {
+        const [attr, content] = node.c as [Attr, Node[]];
+        if (!plainAttributes(attr)) {
+          fail(
+            "Inline span identities, classes and styles need an explicit supported projection.",
+          );
+        }
+        return renderInline(content);
+      }
+      case "Link": {
+        const [attr, content, [href, title]] = node.c as [
+          Attr,
+          Node[],
+          [string, string],
+        ];
+        if (!plainAttributes(attr) || title) {
+          fail(
+            "Native Bento cannot retain link titles or extra link attributes; edit the source explicitly.",
+          );
+        }
+        return `<a href="${escapeHtml(webLink(href))}">${
+          renderInline(content)
+        }</a>`;
+      }
+      default:
+        throw new Error(
+          `UNSUPPORTED_INLINE: ${node.t}; no faithful projection implemented`,
+        );
+    }
+  }).join("");
+}
+const escapeMarkdown = (text: string) =>
+  text.replace(/[\\`*_[\]{}<>!#$|~^@]/g, "\\$&");
+function codeSpan(text: string): string {
+  if (!text || /[\r\n\t]|^\s|\s$| {2,}/.test(text)) {
+    fail(
+      "Inline code with empty text or significant whitespace needs explicit source review; Pandoc normalizes those spaces.",
+    );
+  }
+  const longest = Math.max(
+    0,
+    ...(text.match(/`+/g) ?? []).map((s) => s.length),
+  );
+  const delimiter = "`".repeat(longest + 1);
+  const pad = /^`|`$/.test(text) ? " " : "";
+  return delimiter + pad + text + pad + delimiter;
+}
+interface OpenTag {
+  tag: string;
+  kind: "b" | "i" | "s" | "code" | "a" | "span";
+  text: string;
+  href?: string;
+}
+/** Parse only the reviewed subset. Unsupported markup never disappears silently. */
+function convertInline(
+  html: string,
+  allowEmpty = false,
+): { markdown: string; html: string } {
+  if (html.length > 1_000_000 || html.includes("\u0000")) {
+    fail("Invalid or excessive text fragment.");
+  }
+  let input = html.trim();
+  const wrapper = input.match(/^<(p|div)>([\s\S]*)<\/\1>$/i);
+  if (wrapper && !new RegExp(`<\\/?${wrapper[1]}\\b`, "i").test(wrapper[2])) {
+    input = wrapper[2];
+  }
+  const tokens = input.match(/<[^>]*>|[^<]+|</g) ?? [];
+  let open: OpenTag | undefined, markdown = "", canonical = "";
+  for (const token of tokens) {
+    if (!token.startsWith("<")) {
+      const raw = decodeEntities(token);
+      const text = open?.kind === "code"
+        ? raw
+        : raw.replace(/[\r\n\t ]+/g, " ");
+      if (open) open.text += text;
+      else {
+        markdown += escapeMarkdown(text);
+        canonical += escapeHtml(text);
+      }
+      continue;
+    }
+    if (/^<br\s*\/?\s*>$/i.test(token)) {
+      if (open) {
+        fail("Line breaks inside formatted spans need explicit source review.");
+      }
+      markdown += "  \n";
+      canonical += "<br>";
+      continue;
+    }
+    const end = token.match(/^<\/([a-z]+)\s*>$/i);
+    if (end) {
+      if (!open || open.tag !== end[1].toLowerCase()) {
+        fail("HTML tags are unbalanced.");
+      }
+      if (!open.text || (open.kind !== "code" && /^\s|\s$/.test(open.text))) {
+        fail(
+          "Empty formatting or boundary whitespace needs explicit source review.",
+        );
+      }
+      if (open.kind === "span") markdown += escapeMarkdown(open.text);
+      else if (open.kind === "code") markdown += codeSpan(open.text);
+      else if (open.kind === "a") {
+        markdown += `[${escapeMarkdown(open.text)}](<${open.href}>)`;
+      } else {
+        const mark = ({ b: "**", i: "*", s: "~~" })[open.kind];
+        markdown += mark + escapeMarkdown(open.text) + mark;
+      }
+      canonical += open.kind === "span"
+        ? escapeHtml(open.text)
+        : `<${open.kind}${
+          open.kind === "a" ? ` href="${escapeHtml(open.href!)}"` : ""
+        }>${escapeHtml(open.text)}</${open.kind}>`;
+      open = undefined;
+      continue;
+    }
+    if (open) fail("Nested formatting needs explicit source review.");
+    const transparentSpan = /^<span\s*>$/i.test(token);
+    const style = token.match(/^<(b|strong|i|em|s|code)\s*>$/i);
+    const legacyStrike =
+      /^<span\s+style=(?:"text-decoration:\s*line-through;?"|'text-decoration:\s*line-through;?')\s*>$/i
+        .test(token);
+    const link = token.match(/^<a\s+href=(?:"([^"]*)"|'([^']*)')\s*>$/i);
+    if (!style && !legacyStrike && !link && !transparentSpan) {
+      fail(
+        "Supported text sync: plain text, attribute-free span, b/strong, i/em, s, code, web links and br. Review other formatting in QMD.",
+      );
+    }
+    const tag = link
+      ? "a"
+      : legacyStrike || transparentSpan
+      ? "span"
+      : style![1].toLowerCase();
+    const kind = transparentSpan
+      ? "span"
+      : link
+      ? "a"
+      : legacyStrike || tag === "s"
+      ? "s"
+      : tag === "code"
+      ? "code"
+      : ["b", "strong"].includes(tag)
+      ? "b"
+      : "i";
+    if (["b", "i", "s"].includes(kind) && /(?:\*\*|\*|~~)$/.test(markdown)) {
+      fail("Adjacent emphasis needs explicit source review.");
+    }
+    if (kind === "code" && /`$/.test(markdown)) {
+      fail("Adjacent code spans need explicit source review.");
+    }
+    open = {
+      tag,
+      kind,
+      text: "",
+      ...(link ? { href: webLink(decodeEntities(link[1] ?? link[2])) } : {}),
+    };
+  }
+  if (open) fail("HTML tags are unclosed.");
+  markdown = markdown.trim().replace(/(^|\n)([-+] )/g, "$1\\$2").replace(
+    /(^|\n)(\d+)([.)]) /g,
+    "$1$2\\$3 ",
+  );
+  if (!markdown) {
+    if (allowEmpty && !canonical.replace(/<br>/g, "").trim()) {
+      return { markdown: "", html: "" };
+    }
+    fail("An empty text field requires explicit deletion, not text sync.");
+  }
+  return { markdown, html: canonical.trim() };
+}
+export function inlineHtmlToMarkdown(html: string): string {
+  return convertInline(html).markdown;
+}
+export function canonicalInlineHtml(html: string): string {
+  return convertInline(html).html;
+}
+
+/** An image may retain its source asset while its caption is explicitly cleared. */
+export function imageCaptionHtmlToSource(html: string) {
+  return convertInline(html, true);
+}