@abreen/tada 1.8.1 → 1.10.1

package/README.md

@@ -9,6 +9,7 @@ A static site generator. The successor to Presto.
 
 - Modern design (light & dark following system, floating header, styled lists)
 - Fast client-side navigation
+- Detects a new version of the current page and allows the user to reload
 - Clickable/linkable landmarks (headings, deflists, alert boxes)
 - Dynamic table of contents
   * Floats on the side of the screen when window is large enough
@@ -21,8 +22,11 @@ A static site generator. The successor to Presto.
   * Dynamic table of contents for each method/function
   * Converts new Markdown comment syntax ([added in Java 23][jep467]) to HTML
   * Indexed by Pagefind (classes, interfaces, methods, and fields)
+- Interactive execution traces via `renderTrace()`
+  * Supports Java and Python source files
+  * Renders step-by-step source highlighting, output, and memory diagrams
 - PDF files are copied into `dist/`
-  - Text of each PDF page is extracted using [mutool][mutool] and indexed
+  - Text of each PDF page is extracted using `mutool` (if present) and indexed
 - External link handling (special visual treatment for external links)
 - Internal link validation at build time (broken links fail the build)
 - Internal links automatically prefixed with base path, if specified
@@ -38,16 +42,31 @@ A static site generator. The successor to Presto.
 - Automatically generated favicon
   * Text, color, font and font weight taken from config file
 
+## Prerequisites
+
+- [Bun](https://bun.com/)
+- [MuPDF](https://mupdf.com/) (optional)
+  - macOS (using [Homebrew][homebrew]): `brew install mupdf-tools`
+  - Fedora Linux: `sudo dnf install mupdf`
+  - Ubuntu Linux: `sudo apt-get install mupdf-tools`
+  - Windows: `winget install mutool`
+
+> [!NOTE]
+> You may skip MuPDF if you don't need search results to include links to PDF
+> pages. You can also turn off `features.search` in the config to disable
+> search entirely.
+
+If you plan to use `renderTrace()` to generate traces of Java or Python code,
+the appropriate compiler/interpreter must be installed.
 
 ## Installation
 
-Install [Bun](https://bun.sh/), then install Tada globally:
+Install Tada globally:
 
 ```
-bun add -g @abreen/tada
+bun install --global @abreen/tada
 ```
 
-
 ## Quick start
 
 Create a new site:
@@ -69,7 +88,6 @@ tada serve
 
 Visit [http://localhost:8080/index.html](http://localhost:8080/index.html).
 
-
 ## CLI commands
 
 ### `tada init <dirname>`
@@ -92,30 +110,25 @@ You can also override specific defaults with flags:
 Available flags: `--title`, `--symbol`, `--theme-color`, `--tint-hue`,
 `--tint-amount`, `--default-time-zone`, `--prod-base`, `--prod-base-path`.
 
-
 ### `tada dev`
 
 Build the site for local development (using `site.dev.json`)
 into the `dist/` directory.
 
-
 ### `tada serve`
 
 Start a development web server at `http://localhost:8080` which serves the
 files in the `dist/` directory.
 
-
 ### `tada watch`
 
 Start a development web server, watch for changes and rebuild automatically.
 
-
 ### `tada clean`
 
 Remove the `dist/` directory. Pass `--prod` to also prune old production
 builds (keeps the latest two versions).
 
-
 ### `tada prod`
 
 Build the site for production (uses `site.prod.json`). Each prod build is
@@ -123,7 +136,6 @@ saved to a versioned directory under `dist-prod/` (e.g., `dist-prod/v1/`,
 `dist-prod/v2/`) with a manifest file that records the SHA-256 hash of every
 output file.
 
-
 ### `tada diff`
 
 Compare two production builds and list added, changed, and removed files.
@@ -139,7 +151,6 @@ Use `--copy <dir>` to copy only the changed and added files to a directory:
 
 The output directory will also include a `manifest.json` for the newer build.
 
-
 ## Development vs. production builds
 
 `tada dev` and `tada watch` build to the `dist/` directory using
@@ -151,7 +162,6 @@ for previewing a `tada dev` build. Dev builds overwrite `dist/` each time.
 it runs. Previous production builds are preserved, so you can compare any
 two versions with `tada diff`.
 
-
 ## Deploying to S3
 
 If you host your site in an S3 bucket, `tada diff --copy` lets you upload
@@ -176,20 +186,6 @@ tada diff --copy upload/
 If `tada diff` reports removed files, delete those from your S3 bucket
 manually.
 
-
-## Prerequisites
-
-- [Bun](https://bun.sh/)
-- [MuPDF](https://mupdf.com/) (optional, for PDF text extraction in search)
-  - On macOS: `brew install mupdf-tools`
-  - On Fedora: `dnf install mupdf`
-  - On Ubuntu: `apt-get install mupdf-tools`
-
-> You may skip MuPDF if you don't need search results to include links to PDF
-> pages. You can also turn off `features.search` in the config to disable
-> search entirely.
-
-
 ## Configuration
 
 Build-time site config lives in:
@@ -241,7 +237,6 @@ Example site configuration JSON file:
 | `faviconFontWeight` | *Optional*, font weight used for favicon text (default `700`) |
 | `vars` | Arbitrary key/value variables exposed to templates/content as `vars.*` (e.g., `<%= vars.staffEmail %>`) |
 
-
 #### `nav.json`
 
 Defines the site navigation structure. The file contains an array of section
@@ -275,7 +270,6 @@ but three or more sections are supported.
 ]
 ```
 
-
 #### `authors.json`
 
 Maps author handles (used in front matter `author` fields) to display names
@@ -293,7 +287,6 @@ with `name`, `avatar`, and optionally `url`.
 }
 ```
 
-
 ## Content
 
 Site content lives in the `content/` directory. Markdown is converted to HTML.
@@ -304,7 +297,6 @@ Any other kinds of files are copied into `dist/` in the same locations.
 All files in `public/` are copied directly into `dist/` with zero processing.
 Files in `public/` are **not** included in the search index.
 
-
 ### Front matter fields
 
 Each file in `content/` should start with "front matter" (a YAML-formatted
@@ -323,7 +315,6 @@ list of variables parsed using the [`front-matter`][front-matter] library).
 You may also add arbitrary fields in a page's front matter, and access them
 using Lodash syntax (see below).
 
-
 ### Variable substitution
 
 Plain text content (e.g., HTML and Markdown) are processed using [Lodash
@@ -335,11 +326,10 @@ templates][lodash].
   under `vars` (e.g., `<%= vars.staffEmail %>`)
 
 
-
 [inter]: https://fonts.google.com/specimen/Inter
 [lodash]: https://lodash.info/doc/template
 [front-matter]: https://www.npmjs.com/package/front-matter
 [pagefind]: https://pagefind.app/
-[mutool]: https://mupdf.readthedocs.io/en/latest/tools/mutool.html
 [jep467]: https://openjdk.org/jeps/467
 [katex]: https://katex.org/
+[homebrew]: https://brew.sh/

package/bin/tada.ts

@@ -621,7 +621,7 @@ try {
     case 'watch': {
       requireSiteConfig('dev');
       const { runWatch } = await import(
-        path.join(packageDir, 'build/watch.ts')
+        path.join(packageDir, 'build/watch/index.ts')
       );
       await runWatch({
         httpPort: parsePortArg('--port'),

package/bin/validators.ts

@@ -80,6 +80,6 @@ export function createSiteConfig({
     themeColor,
     tintHue: Number(tintHue),
     tintAmount: Number(tintAmount),
-    vars: {},
+    vars: { foobar: 123 },
   };
 }

package/build/apply-base-path-plugin.ts

@@ -1,6 +1,7 @@
 import path from 'path';
 import type MarkdownIt from 'markdown-it';
 import type Token from 'markdown-it/lib/token.mjs';
+import { JSDOM } from 'jsdom';
 import { createApplyBasePath } from './utils/paths';
 import { isFeatureEnabled } from './features';
 import { isInternalLink } from './utils/link';
@@ -9,6 +10,47 @@ import type { SiteVariables } from './types';
 
 const log = makeLogger(import.meta.url);
 
+function serializeStartTag(element: Element): string {
+  const attrs = Array.from(element.attributes).map(attr =>
+    attr.value === '' ? attr.name : `${attr.name}="${attr.value}"`,
+  );
+  return `<${element.tagName.toLowerCase()}${attrs.length > 0 ? ` ${attrs.join(' ')}` : ''}>`;
+}
+
+function isStandaloneOpeningAnchorTag(html: string): boolean {
+  if (!/^<a\b/i.test(html)) {
+    return false;
+  }
+
+  let i = 2;
+  let quote: '"' | "'" | null = null;
+
+  while (i < html.length) {
+    const char = html[i];
+    if (quote) {
+      if (char === quote) {
+        quote = null;
+      }
+      i += 1;
+      continue;
+    }
+
+    if (char === '"' || char === "'") {
+      quote = char;
+      i += 1;
+      continue;
+    }
+
+    if (char === '>') {
+      return html.slice(i + 1).trim() === '';
+    }
+
+    i += 1;
+  }
+
+  return false;
+}
+
 interface ApplyBasePathOptions {
   literateJavaOutputPaths?: Set<string>;
   sourceUrlPath?: string;
@@ -91,25 +133,45 @@ export default function applyBasePathPlugin(
         token.attrSet('src', afterApply);
       }
     } else if (token.type === 'html_block' || token.type === 'html_inline') {
-      token.content = token.content
-        .replace(
-          /(<a\b[^>]*\bhref=")(\/)([^"]*")/g,
-          (match, prefix, slash, rest) => {
-            const href = slash + rest.slice(0, -1);
+      if (isStandaloneOpeningAnchorTag(token.content)) {
+        const dom = new JSDOM(`<body>${token.content}__tada__</a></body>`);
+        const anchor = dom.window.document.body.querySelector('a[href]');
+        const href = anchor?.getAttribute('href');
+        if (anchor && href && href.startsWith('/')) {
+          const afterApply = applyBasePath(href);
+          log.debug`Applying base path to raw HTML anchor: ${href} -> ${afterApply}`;
+          anchor.setAttribute('href', afterApply);
+          token.content = serializeStartTag(anchor);
+        }
+      } else {
+        const dom = new JSDOM(`<body>${token.content}</body>`);
+        const { document } = dom.window;
+        let changed = false;
+
+        for (const anchor of document.body.querySelectorAll('a[href]')) {
+          const href = anchor.getAttribute('href');
+          if (href && href.startsWith('/')) {
             const afterApply = applyBasePath(href);
-            log.debug`Applying base path to a tag href: ${href} -> ${afterApply}`;
-            return prefix + afterApply + '"';
-          },
-        )
-        .replace(
-          /(<img\b[^>]*\bsrc=")(\/)([^"]*")/g,
-          (match, prefix, slash, rest) => {
-            const src = slash + rest.slice(0, -1);
+            log.debug`Applying base path to raw HTML anchor: ${href} -> ${afterApply}`;
+            anchor.setAttribute('href', afterApply);
+            changed = true;
+          }
+        }
+
+        for (const image of document.body.querySelectorAll('img[src]')) {
+          const src = image.getAttribute('src');
+          if (src && src.startsWith('/')) {
             const afterApply = applyBasePath(src);
-            log.debug`Applying base path to img tag src: ${src} -> ${afterApply}`;
-            return prefix + afterApply + '"';
-          },
-        );
+            log.debug`Applying base path to raw HTML image: ${src} -> ${afterApply}`;
+            image.setAttribute('src', afterApply);
+            changed = true;
+          }
+        }
+
+        if (changed) {
+          token.content = document.body.innerHTML;
+        }
+      }
     }
 
     token.children?.forEach(checkAndApplyBasePath);

package/build/bundle.ts

@@ -14,6 +14,14 @@ import type { PluginBuilder } from 'bun';
 import type { SiteVariables } from './types';
 import timezones from '../src/timezone/timezones.json' with { type: 'json' };
 
+function formatCssNumber(value: number, precision = 4): string {
+  if (Number.isInteger(value)) {
+    return String(value);
+  }
+
+  return value.toFixed(precision).replace(/\.?0+$/, '');
+}
+
 function renderThemeScss(siteVariables: SiteVariables): string {
   const templatePath = path.join(getPackageDir(), 'templates/_theme.scss');
   const template = fs.readFileSync(templatePath, 'utf-8');
@@ -27,7 +35,7 @@ function renderThemeScss(siteVariables: SiteVariables): string {
   const iconColorHoverDark = `hsl(${tintHue}deg ${(6 * tintAmount) / 100}% 60%)`;
   const iconColorTranslucentDark = `hsl(${tintHue}deg ${(85 * tintAmount) / 100}% 90%)`;
 
-  const linkHue = deriveLinkHue(tintHue);
+  const linkHue = formatCssNumber(deriveLinkHue(tintHue));
   const linkColor = `hsl(${linkHue}deg 44.4% 49.4%)`;
   const linkColorHover = `hsl(${linkHue}deg 34% 60%)`;
   const linkColorDark = `hsl(${linkHue}deg 50% 72%)`;

package/build/content-watch.ts

@@ -85,10 +85,10 @@ export class ContentChangeDetector {
       }
     }
 
-    const changedJavaFiles = [...changedContentFiles].filter(f =>
-      f.endsWith('.java'),
+    const changedTraceFiles = [...changedContentFiles].filter(
+      f => f.endsWith('.java') || f.endsWith('.py'),
     );
-    for (const filePath of changedJavaFiles) {
+    for (const filePath of changedTraceFiles) {
       log.event`${B`${path.basename(filePath)}`} changed, re-running traces`;
     }
 

package/build/copy.ts

@@ -102,6 +102,36 @@ function copySingleFile(
   log.info`Copying ${sourceLabel} file ${B`${rel}`}`;
 }
 
+export function deleteOutputPath(distDir: string, relPath: string): void {
+  const root = path.resolve(distDir);
+  const target = path.resolve(distDir, relPath);
+  const relative = path.relative(root, target);
+  if (
+    relative.startsWith('..') ||
+    path.isAbsolute(relative) ||
+    relative.length === 0
+  ) {
+    throw new Error(`refusing to delete path outside dist/: ${relPath}`);
+  }
+
+  fs.rmSync(target, { force: true });
+  log.info`Removing output ${B`${toPosix(relPath)}`}`;
+
+  let currentDir = path.dirname(target);
+  while (currentDir !== root) {
+    try {
+      fs.rmdirSync(currentDir);
+    } catch (err) {
+      const code = (err as NodeJS.ErrnoException).code;
+      if (code === 'ENOTEMPTY' || code === 'ENOENT') {
+        break;
+      }
+      throw err;
+    }
+    currentDir = path.dirname(currentDir);
+  }
+}
+
 export function copyPublicFile(
   publicDir: string,
   distDir: string,

package/build/generate-content-assets.ts

@@ -15,13 +15,14 @@ import {
   renderPlainTextPageAsset,
 } from './util';
 import { isLiterateJava } from './utils/file-types';
-import { checkJavac } from './utils/literate-java';
+import { checkTraceToolAvailability, isTraceSourceFile } from './utils/trace';
 import { toPosix } from './utils/paths';
 import type {
   SiteVariables,
   Asset,
   ContentRenderOptions,
   ContentRenderResult,
+  TraceToolAvailability,
   WatchState,
 } from './types';
 
@@ -33,6 +34,7 @@ export class ContentRenderer {
   private sourceFileCache: Map<string, Asset[]>;
   private lastBuildFiles: Set<string>;
   private javacAvailable: boolean | undefined;
+  private traceToolAvailability: TraceToolAvailability | undefined;
   private traceCache: Map<
     string,
     {
@@ -78,12 +80,10 @@ export class ContentRenderer {
       return new Set(buildContentFiles);
     }
 
-    // If any .java file changed, the trace cache will be stale, so rebuild
+    // If any trace source changed, the trace cache will be stale, so rebuild
     // all content pages to pick up the new trace output.
-    const javaFileChanged = [...changedContentFiles].some(f =>
-      f.endsWith('.java'),
-    );
-    if (javaFileChanged) {
+    const traceFileChanged = [...changedContentFiles].some(isTraceSourceFile);
+    if (traceFileChanged) {
       return new Set(buildContentFiles);
     }
 
@@ -103,28 +103,6 @@ export class ContentRenderer {
     return Object.prototype.hasOwnProperty.call(codeExtensions, ext.slice(1));
   }
 
-  getDirtyCopiedSourceFiles(
-    buildContentFiles: string[],
-    { changedContentFiles }: WatchState = {},
-  ): string[] {
-    if (this.lastBuildFiles.size === 0 || !changedContentFiles) {
-      return buildContentFiles.filter(filePath =>
-        this.isCopiedAssetSource(filePath),
-      );
-    }
-
-    const buildFileSet = new Set(buildContentFiles);
-    const dirtyCopiedSourceFiles: string[] = [];
-    for (const filePath of changedContentFiles) {
-      if (!buildFileSet.has(filePath) || !this.isCopiedAssetSource(filePath)) {
-        continue;
-      }
-      dirtyCopiedSourceFiles.push(filePath);
-    }
-
-    return dirtyCopiedSourceFiles;
-  }
-
   renderSourceAssets(
     filePath: string,
     contentDir: string,
@@ -163,7 +141,7 @@ export class ContentRenderer {
           assetFiles,
           literateJavaOutputPaths,
           traceCache: this.traceCache,
-          javacAvailable: this.javacAvailable,
+          traceToolAvailability: this.traceToolAvailability,
         }),
       );
       return assets;
@@ -190,27 +168,23 @@ export class ContentRenderer {
     return assets;
   }
 
-  writeUncachedAssets(
-    distDir: string,
-    copiedSourceFiles: string[],
-    contentDir: string,
-  ): void {
-    for (const filePath of copiedSourceFiles) {
-      for (const asset of renderCopiedContentAsset({
-        filePath,
-        contentDir,
-        siteVariables: this.siteVariables,
-      })) {
-        const outPath = path.join(distDir, asset.assetPath);
-        fs.mkdirSync(path.dirname(outPath), { recursive: true });
-        fs.writeFileSync(outPath, asset.content);
-      }
+  renderCopiedSourceAssets(filePath: string, contentDir: string): Asset[] {
+    if (!this.isCopiedAssetSource(filePath)) {
+      return [];
     }
+
+    return renderCopiedContentAsset({
+      filePath,
+      contentDir,
+      siteVariables: this.siteVariables,
+    });
   }
 
   updateSourceCache(
     filePath: string,
     assets: Asset[],
+    changedOutputRelPaths: Set<string>,
+    removedOutputRelPaths: Set<string>,
     changedHtmlAssetPaths: Set<string>,
     removedHtmlAssetPaths: Set<string>,
   ): void {
@@ -221,12 +195,14 @@ export class ContentRenderer {
       if (nextAssetPaths.has(asset.assetPath)) {
         continue;
       }
+      removedOutputRelPaths.add(asset.assetPath);
       if (asset.assetPath.endsWith('.html')) {
         removedHtmlAssetPaths.add(asset.assetPath);
       }
     }
 
     for (const asset of assets) {
+      changedOutputRelPaths.add(asset.assetPath);
       if (asset.assetPath.endsWith('.html')) {
         changedHtmlAssetPaths.add(asset.assetPath);
       }
@@ -248,6 +224,7 @@ export class ContentRenderer {
 
   pruneRemovedSources(
     buildFileSet: Set<string>,
+    removedOutputRelPaths: Set<string>,
     removedHtmlAssetPaths: Set<string>,
   ): void {
     for (const filePath of [...this.lastBuildFiles]) {
@@ -257,6 +234,7 @@ export class ContentRenderer {
 
       const previousAssets = this.getCachedAssets(filePath);
       for (const asset of previousAssets) {
+        removedOutputRelPaths.add(asset.assetPath);
         if (asset.assetPath.endsWith('.html')) {
           removedHtmlAssetPaths.add(asset.assetPath);
         }
@@ -280,10 +258,8 @@ export class ContentRenderer {
       buildContentFiles,
       watchState,
     );
-    const dirtyCopiedSourceFiles = this.getDirtyCopiedSourceFiles(
-      buildContentFiles,
-      watchState,
-    );
+    const changedOutputRelPaths = new Set<string>();
+    const removedOutputRelPaths = new Set<string>();
     const changedHtmlAssetPaths = new Set<string>();
     const removedHtmlAssetPaths = new Set<string>();
     const validInternalTargets = getValidInternalTargets(
@@ -312,7 +288,11 @@ export class ContentRenderer {
       errors.push(new Error(msg));
     }
 
-    this.pruneRemovedSources(buildFileSet, removedHtmlAssetPaths);
+    this.pruneRemovedSources(
+      buildFileSet,
+      removedOutputRelPaths,
+      removedHtmlAssetPaths,
+    );
 
     if (dirtySourceFiles.size > 0) {
       const noun = dirtySourceFiles.size === 1 ? 'file' : 'files';
@@ -320,7 +300,8 @@ export class ContentRenderer {
     }
 
     if (this.javacAvailable === undefined && dirtySourceFiles.size > 0) {
-      this.javacAvailable = checkJavac();
+      this.traceToolAvailability = checkTraceToolAvailability();
+      this.javacAvailable = this.traceToolAvailability.java;
       if (!this.javacAvailable) {
         log.warn`javac was not found; literate Java pages will not include execution output`;
       }
@@ -329,14 +310,17 @@ export class ContentRenderer {
     for (const filePath of dirtySourceFiles) {
       let assets: Asset[];
       try {
-        assets = this.renderSourceAssets(
-          filePath,
-          contentDir,
-          distDir,
-          validInternalTargets,
-          assetFiles,
-          literateJavaOutputPaths,
-        );
+        assets = [
+          ...this.renderSourceAssets(
+            filePath,
+            contentDir,
+            distDir,
+            validInternalTargets,
+            assetFiles,
+            literateJavaOutputPaths,
+          ),
+          ...this.renderCopiedSourceAssets(filePath, contentDir),
+        ];
       } catch (err) {
         errors.push(err as Error);
         continue;
@@ -344,13 +328,14 @@ export class ContentRenderer {
       this.updateSourceCache(
         filePath,
         assets,
+        changedOutputRelPaths,
+        removedOutputRelPaths,
         changedHtmlAssetPaths,
         removedHtmlAssetPaths,
       );
     }
 
     this.writeCachedAssets(distDir, buildContentFiles);
-    this.writeUncachedAssets(distDir, dirtyCopiedSourceFiles, contentDir);
     this.lastBuildFiles = buildFileSet;
 
     // Collect HTML asset content for Pagefind
@@ -368,6 +353,7 @@ export class ContentRenderer {
       errors,
       changedHtmlAssetPaths,
       removedHtmlAssetPaths,
+      removedOutputRelPaths,
       htmlAssetsByPath,
       buildContentFiles,
     };

package/build/pagefind.ts

@@ -245,13 +245,6 @@ export async function runPagefind({
     pdfSourceByOutputPath,
   });
 
-  try {
-    const pagefind = await getPagefind();
-    await pagefind.close();
-  } catch {
-    // Best-effort cleanup
-  }
-
   const finishedAt = Date.now();
   log.debug`Search index built in ${finishedAt - snapshotReadyAt}ms (${finishedAt - start}ms total)`;
 }

package/build/serve.ts

@@ -62,6 +62,10 @@ export function startServer(options: StartServerOptions): void {
       return new Response(null, { status: 304, headers });
     }
 
+    if (req.method === 'HEAD') {
+      return new Response(null, { headers });
+    }
+
     return new Response(Bun.file(result.filePath), { headers });
   }
 

package/build/templates.ts

@@ -122,8 +122,6 @@ export function compileTemplates(
       _.template(fs.readFileSync(filePath, 'utf-8'))({
         vars: siteVariables.vars || {},
         site: siteVariables,
-        base: siteVariables.base,
-        basePath: siteVariables.basePath,
       }),
     );