starlight-cannoli-plugins 2.12.1 → 2.13.1

package/README.md

@@ -121,7 +121,6 @@ Automatically compiles fenced `tex compile` and `latex compile` code blocks to S
 - Compiles LaTeX/TikZ code blocks to SVG automatically
 - Caches compiled SVGs by content hash (no recompilation if unchanged)
 - Comprehensive error reporting with line numbers and formatted LaTeX source
-- Supports custom preamble via `% ===` separator in code blocks
 - Works with Starlight and plain Astro projects
 - Requires `svgOutputDir` configuration (no defaults)
 
@@ -178,46 +177,22 @@ Use either ` ```tex compile ` or ` ```latex compile ` — both work identically:
 
 ````markdown
 ```tex compile
+\documentclass[border=5pt]{standalone}
+\usepackage{tikz}
+\begin{document}
+\Large
 \begin{tikzpicture}
   \node (A) at (0,0) {A};
   \node (B) at (2,0) {B};
   \draw (A) -- (B);
 \end{tikzpicture}
-```
-````
-
-**Minimal approach:**
-
-Use `% ===` to separate an optional custom preamble from your diagram content. The plugin wraps everything in the following document structure:
-
-```latex
-\documentclass[border=5pt]{standalone}
-{your preamble}
-\begin{document}
-\Large
-{your content}
 \end{document}
 ```
-
-Example **minimal** tex code block:
-
-````markdown
-```tex compile
-\usepackage{tikz-3dplot}
-
-% ===
-
-\begin{tikzpicture}
-  % diagram code here
-\end{tikzpicture}
-```
 ````
 
-If no `% ===` separator is present, the entire block is treated as content and wrapped in the same default document structure (with an empty preamble).
+**Document structure:**
 
-**Complete Document Control:**
-
-If your code block contains both `\documentclass` and `\begin{document}`, the plugin treats it as a complete, self-contained LaTeX document and uses it as-is without checking for a `% ===` separator for a preamble:
+Each code block must be a complete, self-contained LaTeX document:
 
 ````markdown
 ```tex compile
@@ -244,9 +219,14 @@ The following attributes can be added to the opening fence:
 
 ````markdown
 ```tex compile class="bg-white rounded-1" alt="A commutative diagram"
+\documentclass[border=5pt]{standalone}
+\usepackage{tikz}
+\begin{document}
+\Large
 \begin{tikzpicture}
   \node {Custom styled diagram};
 \end{tikzpicture}
+\end{document}
 ```
 ````
 
@@ -425,6 +405,50 @@ export default defineConfig({
 });
 ```
 
+### Expressive Code Emphasis
+
+An Expressive Code plugin that highlights specific terms inside code blocks using the `emph` meta attribute. Matched terms are wrapped in a `<span class="fw-supreme">` for custom styling.
+
+**Features:**
+
+- Comma-separated list of terms to emphasize per code block
+- Exact-word matching: terms surrounded by word boundaries or whitespace/string edges are matched; partial substrings are not
+- Supports non-word characters (e.g. `(`, `]`, `;`) as well as identifiers
+
+**Usage:**
+
+Register the plugin with Expressive Code:
+
+```ts
+// astro.config.mjs
+import { defineConfig } from "astro/config";
+import starlight from "@astrojs/starlight";
+import { expressiveCodeEmphasis } from "starlight-cannoli-plugins";
+
+export default defineConfig({
+  integrations: [
+    starlight({
+      title: "My Docs",
+      expressiveCode: {
+        plugins: [expressiveCodeEmphasis()],
+      },
+    }),
+  ],
+});
+```
+
+Then use the `emph` meta attribute on any code block:
+
+````markdown
+```js emph="foo,bar,()"
+function foo() {
+  return bar() || ();
+}
+```
+````
+
+Multiple terms are separated by commas. Each term is matched as a whole unit — it must be surrounded by whitespace, start/end of line, or (for terms that start/end with word characters) word boundaries.
+
 ## CLI Utilities
 
 ### cannoli-latex-cleanup

package/dist/{chunk-OLF3SRCP.js → chunk-57RXO5LG.js}

@@ -1,6 +1,11 @@
+import {
+  parseFrontmatter
+} from "./chunk-C2VXRQOK.js";
+
 // src/plugins/astro-latex-compile/index.ts
+import { readFileSync as readFileSync2 } from "fs";
 import { rm } from "fs/promises";
-import { join as join2, resolve as resolve2 } from "path";
+import { join as join2, relative as relative2, resolve as resolve2 } from "path";
 import { visit, SKIP } from "unist-util-visit";
 import { MetaOptions } from "@expressive-code/core";
 
@@ -9,11 +14,13 @@ import { createHash } from "crypto";
 import {
   existsSync,
   mkdirSync,
+  readdirSync,
+  readFileSync,
   writeFileSync,
   rmSync,
   mkdtempSync
 } from "fs";
-import { basename, dirname, join, resolve } from "path";
+import { basename, dirname, join, relative, resolve } from "path";
 import { tmpdir } from "os";
 import sharp from "sharp";
 
@@ -187,6 +194,61 @@ function execProcess(command, args, options) {
   });
 }
 
+// src/plugins/utils/html-builder.ts
+import { JSDOM } from "jsdom";
+var { document } = new JSDOM("").window;
+var HtmlSanitizer = {
+  tempElement: document.createElement("div"),
+  sanitize(htmlString) {
+    this.tempElement.textContent = htmlString;
+    return this.tempElement.innerHTML;
+  }
+};
+var HtmlString = class extends String {
+  element = null;
+  constructor(value) {
+    super(value);
+  }
+  asElement() {
+    if (this.element !== null) {
+      return this.element;
+    }
+    const temp = document.createElement("div");
+    temp.innerHTML = this.valueOf();
+    if (temp.childElementCount > 1) {
+      throw new Error("html template does not accept more than 1 element");
+    }
+    const child = temp.firstElementChild;
+    if (child === null) {
+      throw new Error("html template produced no elements");
+    }
+    this.element = child;
+    return this.element;
+  }
+};
+function html(literalValues, ...interpolatedValues) {
+  let result = "";
+  interpolatedValues.forEach((currentInterpolatedVal, idx) => {
+    const literalVal = literalValues[idx];
+    let interpolatedVal = "";
+    if (Array.isArray(currentInterpolatedVal)) {
+      interpolatedVal = currentInterpolatedVal.join("\n");
+    } else if (typeof currentInterpolatedVal !== "boolean") {
+      interpolatedVal = currentInterpolatedVal.toString();
+    }
+    const isSanitize = !literalVal.endsWith("$");
+    if (isSanitize) {
+      result += literalVal;
+      result += HtmlSanitizer.sanitize(interpolatedVal);
+    } else {
+      result += literalVal.slice(0, -1);
+      result += interpolatedVal;
+    }
+  });
+  result += literalValues.slice(-1);
+  return new HtmlString(result);
+}
+
 // src/plugins/astro-latex-compile/utils.ts
 var CONTENT_ROOT = "src/content/docs/";
 function computeJpgPath(tempOutputDir, filePath, blockId) {
@@ -201,7 +263,7 @@ function computeJpgPath(tempOutputDir, filePath, blockId) {
 }
 async function writeJpgFromSvg(svgPath, jpgPath) {
   mkdirSync(dirname(jpgPath), { recursive: true });
-  await sharp(svgPath).flatten({ background: { r: 255, g: 255, b: 255 } }).jpeg({ quality: 90 }).toFile(jpgPath);
+  await sharp(svgPath, { density: 300 }).flatten({ background: { r: 255, g: 255, b: 255 } }).jpeg({ quality: 90 }).toFile(jpgPath);
 }
 function stripAnsi(text) {
   return text.replace(/\x1b\[[0-9;]*m/g, "");
@@ -254,33 +316,107 @@ async function writeJpgError(jpgPath, header, errorText) {
   mkdirSync(dirname(jpgPath), { recursive: true });
   await sharp(Buffer.from(svg)).flatten({ background: { r: 255, g: 255, b: 255 } }).jpeg({ quality: 90 }).toFile(jpgPath);
 }
-function hashLatexCode(code) {
+function computeLineOffset(_latexCode) {
+  return 0;
+}
+function buildErrorHtml(header, errorMsg, latexCode) {
+  const clean = stripAnsi(errorMsg);
+  const sourceIdx = clean.indexOf("LaTeX source:");
+  const summary = (sourceIdx !== -1 ? clean.slice(0, sourceIdx) : clean).trimEnd();
+  const compiledLineNums = [];
+  const linePattern = /Error \(line (\d+)\)/g;
+  let m;
+  while ((m = linePattern.exec(summary)) !== null) {
+    compiledLineNums.push(parseInt(m[1], 10));
+  }
+  const offset = computeLineOffset(latexCode);
+  const errorLineSet = new Set(
+    compiledLineNums.map((n) => n - offset).filter((n) => n > 0)
+  );
+  const codeLines = latexCode.split("\n");
+  const lineWidth = String(codeLines.length).length;
+  const summaryLines = summary.split("\n").map((line) => line.trim()).filter(Boolean).map((line) => html`<div>${line}</div>`);
+  const codeBlock = new HtmlString(
+    codeLines.map((line, i) => {
+      const lineNum = i + 1;
+      const isError = errorLineSet.has(lineNum);
+      const gutter = String(lineNum).padStart(lineWidth);
+      const bg = isError ? "background:var(--cannoli-error-low);" : "";
+      return html`<span style="${bg}display:block;padding:0 14px"
+          ><span style="color:var(--sl-color-gray-3);user-select:none"
+            >${gutter} │ </span
+          >${line}</span
+        >`.toString();
+    }).join("")
+  );
+  return html`<div
+    class="not-content"
+    style="border:1px solid var(--cannoli-error-low);border-radius:6px;overflow:hidden;margin:1.5em 0;font-family:ui-monospace,SFMono-Regular,Menlo,monospace;font-size:13px;line-height:1.5;display:flex;flex-direction:column"
+  >
+    <div
+      style="background:var(--cannoli-error);color:var(--sl-color-black);padding:8px 14px;font-weight:700"
+    >
+      &#9888;&nbsp;LaTeX Compilation Error &mdash; ${header}
+    </div>
+    <div
+      style="background:var(--cannoli-error-low);color:var(--cannoli-error-high);padding:10px 14px;border-bottom:1px solid var(--cannoli-error)"
+    >
+      $${summaryLines}
+    </div>
+    <pre
+      style="margin:0;background:var(--sl-color-gray-6);color:var(--sl-color-text);overflow-x:auto"
+    ><code style="display:block;padding:8px 0;font-size:12px">$${codeBlock}</code></pre>
+  </div>`.toString();
+}
+function collectTexInputFiles(dir, recursive) {
+  const files = [];
+  try {
+    for (const entry of readdirSync(dir, { withFileTypes: true })) {
+      const full = join(dir, entry.name);
+      if (entry.isDirectory() && recursive) {
+        files.push(...collectTexInputFiles(full, recursive));
+      } else if (entry.isFile()) {
+        files.push(full);
+      }
+    }
+  } catch {
+  }
+  return files.sort();
+}
+function computeTexInputDirsSalt(texInputDirs) {
+  if (texInputDirs.length === 0) return "";
+  const hash = createHash("md5");
+  let hasAnyFile = false;
+  for (const dir of texInputDirs) {
+    const recursive = dir.endsWith("//");
+    const resolved = resolve(dir.endsWith("/") ? dir.slice(0, -1) : dir);
+    for (const filePath of collectTexInputFiles(resolved, recursive)) {
+      try {
+        hash.update(relative(process.cwd(), filePath));
+        hash.update(readFileSync(filePath));
+        hasAnyFile = true;
+      } catch {
+      }
+    }
+  }
+  return hasAnyFile ? hash.digest("hex").slice(0, 16) : "";
+}
+function hashLatexCode(code, salt = "") {
   const normalized = code.split("\n").map((line) => line.trim()).filter((line) => !line.startsWith("%")).filter(Boolean).join("\n").trim();
-  return createHash("md5").update(normalized).digest("hex").slice(0, 16);
+  const h = createHash("md5").update(normalized);
+  if (salt) h.update(salt);
+  return h.digest("hex").slice(0, 16);
 }
 function buildLatexSource(latexCode) {
   if (latexCode.includes("\\documentclass") && latexCode.includes("\\begin{document}")) {
     return latexCode.trim();
   }
-  const separatorRegex = /%[ \t]*===/;
-  const parts = latexCode.split(separatorRegex);
-  let preamble = "";
-  let content = latexCode.trim();
-  if (parts.length === 2) {
-    preamble = parts[0].trim();
-    content = parts[1].trim();
-  }
-  return [
-    "\\documentclass[border=5pt]{standalone}",
-    preamble,
-    "\\begin{document}",
-    "\\Large",
-    content,
-    "\\end{document}"
-  ].join("\n");
+  throw new Error(
+    `[remark-latex-compile] Code block is not a complete LaTeX document. Blocks must contain both \\documentclass and \\begin{document}.`
+  );
 }
-async function compileLatexToSvg(latexCode, svgOutputDir, texInputDirs = []) {
-  const hash = hashLatexCode(latexCode);
+async function compileLatexToSvg(latexCode, svgOutputDir, texInputDirs = [], inputsSalt = "") {
+  const hash = hashLatexCode(latexCode, inputsSalt);
   const svgPath = join(svgOutputDir, `${hash}.svg`);
   if (existsSync(svgPath)) {
     return { hash, svgPath, wasCompiled: false };
@@ -351,6 +487,16 @@ Error: ${errorOutput}`
 }
 
 // src/plugins/astro-latex-compile/index.ts
+function getFrontmatterOffset(absoluteFilePath) {
+  try {
+    const original = readFileSync2(absoluteFilePath, "utf-8");
+    const { rawFrontmatter } = parseFrontmatter(original);
+    if (!rawFrontmatter) return 0;
+    return rawFrontmatter.split("\n").length - 1 + 2;
+  } catch {
+    return 0;
+  }
+}
 function remarkLatexCompile(options) {
   const svgOutputDir = resolve2(options.svgOutputDir);
   return async function transformer(tree, file) {
@@ -363,27 +509,31 @@ function remarkLatexCompile(options) {
     });
     if (nodes.length === 0) return;
     const filePath = file.path || "unknown";
+    const relFilePath = filePath !== "unknown" ? relative2(process.cwd(), filePath) : "unknown";
+    const frontmatterOffset = filePath !== "unknown" ? getFrontmatterOffset(filePath) : 0;
+    const inputsSalt = computeTexInputDirsSalt(options.texInputDirs ?? []);
     const results = await Promise.all(
       nodes.map(async ({ node, index, parent }) => {
-        const lineNumberStr = node.position?.start.line ?? "?";
+        const lineNumberStr = node.position?.start.line !== void 0 ? String(node.position.start.line + frontmatterOffset) : "?";
         const blockId = new MetaOptions(node.meta ?? "").getInteger("blockid");
         const jpgPath = options.tempOutputDir && blockId !== void 0 ? computeJpgPath(options.tempOutputDir, filePath, blockId) : null;
         try {
           const result = await compileLatexToSvg(
             node.value,
             svgOutputDir,
-            options.texInputDirs ?? []
+            options.texInputDirs ?? [],
+            inputsSalt
           );
           if (result.wasCompiled) {
             console.log(
-              `[remark-latex-compile] ${filePath}:${lineNumberStr}: compiled ${result.hash}.svg`
+              `[remark-latex-compile] ${relFilePath}:${lineNumberStr}: compiled ${result.hash}.svg`
             );
           }
           options._referencedHashes?.add(result.hash);
           if (jpgPath) {
             await writeJpgFromSvg(result.svgPath, jpgPath);
             console.log(
-              `[remark-latex-compile] ${filePath}:${lineNumberStr}: wrote ${jpgPath}`
+              `[remark-latex-compile] ${relFilePath}:${lineNumberStr}: wrote ${jpgPath}`
             );
           }
           return {
@@ -399,13 +549,13 @@ function remarkLatexCompile(options) {
           const match = errorMsg.match(/\n\n([\s\S]+)/);
           const details = match ? match[1] : errorMsg;
           console.error(
-            `[remark-latex-compile] ${filePath}:${lineNumberStr}
+            `[remark-latex-compile] ${relFilePath}:${lineNumberStr}
 ${details}`
           );
           if (jpgPath) {
             await writeJpgError(
               jpgPath,
-              `${filePath}:${lineNumberStr}`,
+              `${relFilePath}:${lineNumberStr}`,
               errorMsg
             );
           }
@@ -453,9 +603,22 @@ ${details}`
       options._fileJpgPathMap.set(filePath, newJpgPaths);
     }
     for (let i = results.length - 1; i >= 0; i--) {
-      const { index, parent, result } = results[i];
+      const { index, parent, result, error } = results[i];
       const { node } = nodes[i];
-      if (!result) continue;
+      if (!result) {
+        const lineNumberStr = node.position?.start.line !== void 0 ? String(node.position.start.line + frontmatterOffset) : "?";
+        const errorMsg = error instanceof Error ? error.message : String(error);
+        const errorNode = {
+          type: "html",
+          value: buildErrorHtml(
+            `${relFilePath}:${lineNumberStr}`,
+            errorMsg,
+            node.value
+          )
+        };
+        parent.children.splice(index, 1, errorNode);
+        continue;
+      }
       const metaOptions = new MetaOptions(node.meta ?? "");
       const customClasses = metaOptions.getString("class")?.split(/\s+/).filter(Boolean) ?? [];
       const altText = metaOptions.getString("alt") ?? "LaTeX diagram";