@abreen/tada 1.13.9 → 1.14.1

package/build/utils/trace-svg.ts

@@ -7,6 +7,7 @@ import type {
   TraceObjectLayout,
 } from '../types';
 import { ARRAY_MAX_CELLS, DEFAULT_FONT_SIZE } from './trace-layout';
+import { formatHeapObjectValue, isInlineHeapObject } from './trace-heap';
 
 /** Gap between stack area and heap area. */
 const SECTION_GAP = 60;
@@ -17,6 +18,9 @@ const PADDING = 8;
 /** Horizontal margin when routing stack-to-heap arrows. */
 const ARROW_MARGIN = 20;
 
+/** Approximate monospace character width for arrow targeting. */
+const CHAR_WIDTH_RATIO = 0.6;
+
 // ---------------------------------------------------------------------------
 // Escape & format helpers
 // ---------------------------------------------------------------------------
@@ -58,13 +62,9 @@ export function formatValue(val: TraceValue): string {
 }
 
 // ---------------------------------------------------------------------------
-// filterStep -- remove args from main(), hide objects reachable only via args
+// filterStep -- remove args from main(), hide unreachable heap objects
 // ---------------------------------------------------------------------------
 
-function isStringObject(obj: TraceHeapObject): boolean {
-  return 'value' in obj && obj.type === 'String';
-}
-
 export function filterStep(step: TraceStep): {
   stack: TraceStackFrame[];
   heap: Record<string, TraceHeapObject>;
@@ -84,38 +84,6 @@ export function filterStep(step: TraceStep): {
     return { ...frame, locals };
   });
 
-  // Find objects reachable only through the hidden 'args' variable
-  const argsOnly = new Set<string>();
-  for (const frame of step.stack) {
-    if (frame.method === 'main') {
-      const argsVal = frame.locals.args;
-      if (argsVal?.type === 'ref') {
-        const q = [argsVal.id];
-        while (q.length > 0) {
-          const id = q.shift()!;
-          if (argsOnly.has(id) || !step.heap[id]) {
-            continue;
-          }
-          argsOnly.add(id);
-          const obj = step.heap[id];
-          if ('elements' in obj) {
-            for (const el of obj.elements) {
-              if (el.type === 'ref') {
-                q.push(el.id);
-              }
-            }
-          } else if ('fields' in obj) {
-            for (const v of Object.values(obj.fields)) {
-              if (v.type === 'ref') {
-                q.push(v.id);
-              }
-            }
-          }
-        }
-      }
-    }
-  }
-
   // Find objects reachable from visible (non-args) variables
   const reachable = new Set<string>();
   const queue: string[] = [];
@@ -126,6 +94,9 @@ export function filterStep(step: TraceStep): {
       }
     }
   }
+  for (const id of step.transientHeapRoots ?? []) {
+    queue.push(id);
+  }
   while (queue.length > 0) {
     const id = queue.shift()!;
     if (reachable.has(id) || !step.heap[id]) {
@@ -148,11 +119,10 @@ export function filterStep(step: TraceStep): {
     }
   }
 
-  // Keep heap objects that are reachable from visible variables, or that
-  // aren't exclusively reachable from the hidden 'args'
+  // Keep only heap objects reachable from visible variables.
   const heap: Record<string, TraceHeapObject> = {};
   const sortedIds = Object.keys(step.heap)
-    .filter(id => reachable.has(id) || !argsOnly.has(id))
+    .filter(id => reachable.has(id))
     .sort((a, b) => {
       const numA = parseInt(a.split('_').pop()!, 10);
       const numB = parseInt(b.split('_').pop()!, 10);
@@ -294,11 +264,12 @@ function svgHeapObject(
     `<g class="trace-obj" data-id="${escapeXml(id)}" transform="translate(${absX},${absY})">`,
   );
 
-  if ('value' in obj && isStringObject(obj)) {
-    // Strings: just quoted text, no box
+  if ('value' in obj && isInlineHeapObject(obj)) {
+    // Strings and Java boxed primitives are heap values, but render inline.
     parts.push(
-      `<text class="trace-val" x="0" y="${height / 2}" ` +
-        `dominant-baseline="central">${escapeXml(`"${obj.value}"`)}</text>`,
+      `<text class="trace-val" x="${width / 2}" y="${height / 2}" ` +
+        `text-anchor="middle" dominant-baseline="central">` +
+        `${escapeXml(formatHeapObjectValue(obj.type, obj.value))}</text>`,
     );
     parts.push('</g>');
     return parts.join('');
@@ -505,6 +476,43 @@ function rectBoundaryPoint(
   return { x: Math.round(cx + dx * scale), y: Math.round(cy + dy * scale) };
 }
 
+function heapTargetBoundaryPoint(
+  sx: number,
+  sy: number,
+  target: HeapObjInfo,
+  obj: TraceHeapObject | undefined,
+  dims: { fontSize: number },
+): { x: number; y: number } {
+  if (!obj || !('value' in obj) || !isInlineHeapObject(obj)) {
+    return rectBoundaryPoint(
+      sx,
+      sy,
+      target.absX,
+      target.absY,
+      target.width,
+      target.height,
+    );
+  }
+
+  const text = formatHeapObjectValue(obj.type, obj.value);
+  const textWidth = Math.max(
+    dims.fontSize,
+    text.length * dims.fontSize * CHAR_WIDTH_RATIO,
+  );
+  const textHeight = dims.fontSize * 1.2;
+  const textPadding = 4;
+  const rx = target.absX + (target.width - textWidth) / 2 - textPadding;
+  const ry = target.absY + (target.height - textHeight) / 2 - textPadding;
+  return rectBoundaryPoint(
+    sx,
+    sy,
+    rx,
+    ry,
+    textWidth + textPadding * 2,
+    textHeight + textPadding * 2,
+  );
+}
+
 /**
  * Get the center of the child-slot box for a given field.
  * The slot row has a small label at the top and a box below it.
@@ -547,14 +555,7 @@ function generateArrows(
     target: HeapObjInfo,
     style: 'fg' | 'dim' = 'fg',
   ): string {
-    const ep = rectBoundaryPoint(
-      sx,
-      sy,
-      target.absX,
-      target.absY,
-      target.width,
-      target.height,
-    );
+    const ep = heapTargetBoundaryPoint(sx, sy, target, heap[target.id], dims);
     const cpx = Math.round((sx + ep.x) / 2);
     const cls = style === 'fg' ? 'trace-arrow' : 'trace-arrow-dim';
     const marker = style === 'fg' ? 'trace-arrowhead' : 'trace-arrowhead-dim';
@@ -606,14 +607,7 @@ function generateArrows(
   // Non-structural heap arrow: cubic Bezier with auto-detected direction
   // (typically horizontal toward ref chains).
   function heapArrow(sx: number, sy: number, target: HeapObjInfo): string {
-    const ep = rectBoundaryPoint(
-      sx,
-      sy,
-      target.absX,
-      target.absY,
-      target.width,
-      target.height,
-    );
+    const ep = heapTargetBoundaryPoint(sx, sy, target, heap[target.id], dims);
     const dx = ep.x - sx;
     const dy = ep.y - sy;
     const dist = Math.sqrt(dx * dx + dy * dy);

package/build/utils/trace.ts

@@ -1,4 +1,5 @@
 import fs from 'fs';
+import os from 'os';
 import path from 'path';
 import { makeLogger } from '../log';
 import { B } from '../colors';
@@ -43,9 +44,9 @@ export interface TraceContext {
 export interface TraceResult {
   manifestUrl: string;
   artifactId: string;
-  highlightedSource: string;
+  highlightedSources: { file: string; highlightedSource: string }[];
   totalSteps: number;
-  mtime: number;
+  sourceMtims: Record<string, number>;
 }
 
 export function isTraceSourceFile(filePath: string): boolean {
@@ -89,31 +90,44 @@ function disabledTraceMessage(fileName: string): string {
   return `Python was not found; trace for ${B`${fileName}`} will be disabled`;
 }
 
-function sourceFileNameForTrace(fileName: string): string {
-  const { name, ext } = path.parse(fileName);
-  return `${name}${ext}`;
+interface TraceSourceFile {
+  requestedPath: string;
+  absolutePath: string;
+  file: string;
+  source: string;
 }
 
 function runTraceForFile(
-  filePath: string,
-  source: string,
+  primaryFilePath: string,
+  tracedFilePaths: string[],
+  sources: { file: string; source: string }[],
 ): { output: string; ignoreFields?: Record<string, string[]> } {
-  const ext = path.extname(filePath).toLowerCase();
+  const ext = path.extname(primaryFilePath).toLowerCase();
   if (ext === '.java') {
-    validateJavaTraceTarget(filePath, source);
+    validateJavaTraceTarget(primaryFilePath, sources[0].source);
+    const ignoreFields: Record<string, string[]> = {};
+    for (const source of sources) {
+      const sourceFields = parseIgnoreFields(source.source);
+      for (const [className, fieldNames] of Object.entries(sourceFields)) {
+        ignoreFields[className] = [
+          ...(ignoreFields[className] ?? []),
+          ...fieldNames,
+        ];
+      }
+    }
     return {
-      output: runJavaTrace(filePath, path.parse(filePath).name),
-      ignoreFields: parseIgnoreFields(source),
+      output: runJavaTrace(tracedFilePaths, path.parse(primaryFilePath).name),
+      ignoreFields,
     };
   }
   if (ext === '.py') {
-    return { output: runPythonTrace(filePath) };
+    return { output: runPythonTrace(primaryFilePath, tracedFilePaths) };
   }
-  throw new Error(`Unsupported trace source: ${filePath}`);
+  throw new Error(`Unsupported trace source: ${primaryFilePath}`);
 }
 
 export function createTraceHelpers(context: TraceContext): {
-  renderTrace: (sourceFile: string) => string;
+  renderTrace: (sourceFile: string, companionFiles?: string[]) => string;
 } {
   const {
     filePath,
@@ -127,60 +141,158 @@ export function createTraceHelpers(context: TraceContext): {
   } = context;
   const pageDir = path.dirname(filePath);
 
-  function getOrRunTrace(sourceFile: string): TraceResult {
-    const sourceFilePath = path.resolve(pageDir, sourceFile);
-    dependencyCollector?.traceFiles?.add(sourceFilePath);
-    const traceName = path.parse(sourceFile).name;
-    const relDir = toPosix(path.relative(contentDir, pageDir));
+  function resolveTraceSources(
+    sourceFile: string,
+    companionFiles?: string[],
+  ): TraceSourceFile[] {
+    if (companionFiles !== undefined && !Array.isArray(companionFiles)) {
+      throw new Error('renderTrace companionFiles must be an array');
+    }
+
+    const requestedPaths = [sourceFile, ...(companionFiles ?? [])];
+    const sources = requestedPaths.map(requestedPath => {
+      const absolutePath = path.resolve(pageDir, requestedPath);
+      if (!fs.existsSync(absolutePath)) {
+        throw new Error(`Trace target not found: ${absolutePath}`);
+      }
+      return {
+        requestedPath,
+        absolutePath,
+        file: path.basename(requestedPath),
+        source: fs.readFileSync(absolutePath, 'utf-8'),
+      };
+    });
+
+    const primaryExt = path.extname(sources[0].absolutePath).toLowerCase();
+    for (const source of sources) {
+      const ext = path.extname(source.absolutePath).toLowerCase();
+      if (ext !== primaryExt) {
+        throw new Error(
+          `Trace companion must use the same extension as ${sourceFile}: ${source.requestedPath}`,
+        );
+      }
+      traceLanguageForFile(source.absolutePath);
+    }
+
+    const seenBasenames = new Set<string>();
+    for (const source of sources) {
+      if (seenBasenames.has(source.file)) {
+        throw new Error(
+          `Trace files must have unique basenames in a flat workspace: ${source.file}`,
+        );
+      }
+      seenBasenames.add(source.file);
+    }
+
+    return sources;
+  }
 
-    const cached = cache.get(sourceFilePath);
-    if (cached) {
-      const mtime = fs.statSync(sourceFilePath, {
+  function cacheKeyForSources(sources: TraceSourceFile[]): string {
+    return JSON.stringify(sources.map(source => source.absolutePath));
+  }
+
+  function getSourceMtims(sources: TraceSourceFile[]): Record<string, number> {
+    return Object.fromEntries(
+      sources.map(source => [
+        source.absolutePath,
+        fs.statSync(source.absolutePath).mtimeMs,
+      ]),
+    );
+  }
+
+  function cacheIsFresh(
+    sources: TraceSourceFile[],
+    cached: TraceResult,
+  ): boolean {
+    return sources.every(source => {
+      const mtime = fs.statSync(source.absolutePath, {
         throwIfNoEntry: false,
       })?.mtimeMs;
-      if (mtime !== undefined && mtime === cached.mtime) {
-        const outputPaths = getTraceOutputPaths(
-          relDir,
-          traceName,
-          cached.artifactId,
-          cached.totalSteps,
-        );
-        if (
-          materializeTraceOutputs({
-            outputPaths,
-            targetDistDir: distDir,
-            sourceDistDir: cachedTraceSourceDir || distDir,
-          })
-        ) {
-          for (const outputPath of outputPaths) {
-            dependencyCollector?.generatedOutputPaths?.add(outputPath);
-          }
-          return {
-            ...cached,
-            manifestUrl: buildManifestUrl({
-              relDir,
-              traceName,
-              artifactId: cached.artifactId,
-              applyBasePath,
-            }),
-          };
-        }
+      return (
+        mtime !== undefined && cached.sourceMtims[source.absolutePath] === mtime
+      );
+    });
+  }
+
+  function createTraceWorkspace(sources: TraceSourceFile[]): string {
+    const tempDir = fs.mkdtempSync(path.join(os.tmpdir(), 'tada-trace-work-'));
+    try {
+      for (const source of sources) {
+        fs.copyFileSync(source.absolutePath, path.join(tempDir, source.file));
       }
+      return tempDir;
+    } catch (err) {
+      fs.rmSync(tempDir, { recursive: true, force: true });
+      throw err;
     }
+  }
 
-    if (!fs.existsSync(sourceFilePath)) {
-      throw new Error(`Trace target not found: ${sourceFilePath}`);
+  function getOrRunTrace(
+    sourceFile: string,
+    companionFiles?: string[],
+  ): TraceResult {
+    const sources = resolveTraceSources(sourceFile, companionFiles);
+    for (const source of sources) {
+      dependencyCollector?.traceFiles?.add(source.absolutePath);
     }
+    const sourceFilePath = sources[0].absolutePath;
+    const traceName = path.parse(sourceFile).name;
+    const relDir = toPosix(path.relative(contentDir, pageDir));
+    const cacheKey = cacheKeyForSources(sources);
 
-    const source = fs.readFileSync(sourceFilePath, 'utf-8');
+    const cached = cache.get(cacheKey);
+    if (cached && cacheIsFresh(sources, cached)) {
+      const outputPaths = getTraceOutputPaths(
+        relDir,
+        traceName,
+        cached.artifactId,
+        cached.totalSteps,
+      );
+      if (
+        materializeTraceOutputs({
+          outputPaths,
+          targetDistDir: distDir,
+          sourceDistDir: cachedTraceSourceDir || distDir,
+        })
+      ) {
+        for (const outputPath of outputPaths) {
+          dependencyCollector?.generatedOutputPaths?.add(outputPath);
+        }
+        return {
+          ...cached,
+          manifestUrl: buildManifestUrl({
+            relDir,
+            traceName,
+            artifactId: cached.artifactId,
+            applyBasePath,
+          }),
+        };
+      }
+    }
 
     log.info`Tracing ${B`${sourceFile}`}`;
 
-    const { output, ignoreFields } = runTraceForFile(sourceFilePath, source);
-    const highlightedSource = highlightTraceSource(
-      source,
-      traceLanguageForFile(sourceFilePath),
-    );
+    const workspaceDir = createTraceWorkspace(sources);
+    let output: string;
+    let ignoreFields: Record<string, string[]> | undefined;
+    try {
+      const workspacePaths = sources.map(source =>
+        path.join(workspaceDir, source.file),
+      );
+      ({ output, ignoreFields } = runTraceForFile(
+        workspacePaths[0],
+        workspacePaths,
+        sources.map(source => ({ file: source.file, source: source.source })),
+      ));
+    } finally {
+      fs.rmSync(workspaceDir, { recursive: true, force: true });
+    }
+
+    const language = traceLanguageForFile(sourceFilePath);
+    const highlightedSources = sources.map(source => ({
+      file: source.file,
+      highlightedSource: highlightTraceSource(source.source, language),
+    }));
     const traceOutputDir = path.join(distDir, relDir, '_traces', traceName);
 
     const traceOutput = chunkTraceOutput(
@@ -188,8 +300,8 @@ export function createTraceHelpers(context: TraceContext): {
       traceOutputDir,
       relDir,
       traceName,
-      sourceFileNameForTrace(sourceFile),
-      source,
+      sources[0].file,
+      sources.map(source => ({ file: source.file, source: source.source })),
       { chunkSize: DEFAULT_CHUNK_SIZE, ignoreFields },
     );
     for (const outputPath of traceOutput.outputPaths) {
@@ -204,45 +316,48 @@ export function createTraceHelpers(context: TraceContext): {
     });
 
     const totalSteps = traceOutput.manifest.totalSteps;
-    const mtime = fs.statSync(sourceFilePath).mtimeMs;
-    cache.set(sourceFilePath, {
+    const sourceMtims = getSourceMtims(sources);
+    cache.set(cacheKey, {
       manifestUrl,
       artifactId: traceOutput.artifactId,
-      highlightedSource,
+      highlightedSources,
       totalSteps,
-      mtime,
+      sourceMtims,
     });
     return {
       manifestUrl,
       artifactId: traceOutput.artifactId,
-      highlightedSource,
+      highlightedSources,
       totalSteps,
-      mtime,
+      sourceMtims,
     };
   }
 
   return {
-    renderTrace: (sourceFile: string): string => {
-      const sourceFilePath = path.resolve(pageDir, sourceFile);
+    renderTrace: (sourceFile: string, companionFiles?: string[]): string => {
+      const sources = resolveTraceSources(sourceFile, companionFiles);
+      for (const source of sources) {
+        dependencyCollector?.traceFiles?.add(source.absolutePath);
+      }
+      const sourceFilePath = sources[0].absolutePath;
       const available = availabilityForFile(sourceFilePath, toolAvailability);
       if (available === false) {
         log.warn`${disabledTraceMessage(sourceFile)}`;
-        if (!fs.existsSync(sourceFilePath)) {
-          throw new Error(`Trace target not found: ${sourceFilePath}`);
-        }
-        const source = fs.readFileSync(sourceFilePath, 'utf-8');
+        const language = traceLanguageForFile(sourceFilePath);
         return renderTraceWidgetHtml({
-          highlightedSource: highlightTraceSource(
-            source,
-            traceLanguageForFile(sourceFilePath),
-          ),
+          highlightedSources: sources.map(source => ({
+            file: source.file,
+            highlightedSource: highlightTraceSource(source.source, language),
+          })),
         });
       }
 
-      const { manifestUrl, highlightedSource, totalSteps } =
-        getOrRunTrace(sourceFile);
+      const { manifestUrl, highlightedSources, totalSteps } = getOrRunTrace(
+        sourceFile,
+        companionFiles,
+      );
       return renderTraceWidgetHtml({
-        highlightedSource,
+        highlightedSources,
         manifestUrl,
         totalSteps,
       });

package/build/watch/compiler-types.d.ts

@@ -7,9 +7,9 @@ import type {
 export interface TraceCacheEntry {
   manifestUrl: string;
   artifactId: string;
-  highlightedSource: string;
+  highlightedSources: { file: string; highlightedSource: string }[];
   totalSteps: number;
-  mtime: number;
+  sourceMtims: Record<string, number>;
 }
 
 export type TraceCache = Map<string, TraceCacheEntry>;

package/build/watch/compiler.ts

@@ -23,7 +23,11 @@ export function invalidateTraceCacheForBatch(
   for (const change of batch.changes) {
     const sourcePath = path.resolve(change.path);
     if (isTraceSourceFile(sourcePath)) {
-      traceCache.delete(sourcePath);
+      for (const [cacheKey, entry] of traceCache) {
+        if (sourcePath in entry.sourceMtims) {
+          traceCache.delete(cacheKey);
+        }
+      }
     }
   }
 }

package/init/content/lectures/02/_pr1.md

@@ -2,4 +2,4 @@
 
 Here's the `_pr1.md` partial. From this partial we can use the page-level
 front matter fields from the page that includes us. The page that called
-`include()` has a title of: <%= page.title %>
+this partial has a title of: <%= page.title %>

package/init/content/lectures/02/index.md

@@ -8,6 +8,6 @@ author: alex
 
 Here is a page constructed from multiple partials.
 
-<%= include('_pr1.md') %>
+{{{ _pr1.md }}}
 
-<%= include('subdir/_pr2.md') %>
+{{{ subdir/_pr2.md }}}

package/init/content/lectures/02/subdir/_foobar.md

@@ -0,0 +1,3 @@
+Here's a nested Markdown partial in a subdirectory.
+
+Here's the title of the page including this partial: <%= page.title %>

package/init/content/lectures/02/subdir/_pr2.md

@@ -1,6 +1,6 @@
 ## Problem 2 # The second example problem
 
-Here's the `_pr2.md` partial. If we use `include()` here, the path is resolved
-relative to this file, **not** the page or partial that included us.
+Here's the `_pr2.md` partial. If we include another partial here, the path is
+resolved relative to this file, **not** the page or partial that included us.
 
-<%= include('_foobar.html') %>
+{{{ _foobar.md }}}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@abreen/tada",
-  "version": "1.13.9",
+  "version": "1.14.1",
   "type": "module",
   "description": "A static site generator",
   "license": "MIT",

package/src/slides/index.ts

@@ -249,8 +249,8 @@ export default function mountSlides(window: Window): void | (() => void) {
     }
   }
 
-  function resetReadyTraces(): void {
-    const widgets = slidesRoot.querySelectorAll(
+  function resetReadyTraces(scope: HTMLElement = slidesRoot): void {
+    const widgets = scope.querySelectorAll(
       '.trace-widget:not(.trace-disabled)',
     );
 
@@ -341,7 +341,11 @@ export default function mountSlides(window: Window): void | (() => void) {
       hidePresentationControls();
     }
 
+    const previousIndex = activeIndex;
     setActiveSlide(activeIndex + delta);
+    if (delta === -1 && activeIndex !== previousIndex) {
+      resetReadyTraces(slides[activeIndex]);
+    }
     focusSlide(slides[activeIndex]);
   }