@abreen/tada 1.4.1 → 1.5.0

package/src/trace/index.ts

@@ -0,0 +1,250 @@
+import type { TraceManifest, TraceChunkEntry } from './types';
+
+interface WidgetState {
+  manifest: TraceManifest;
+  chunks: Map<number, TraceChunkEntry[]>;
+  currentStep: number;
+}
+
+interface WidgetElements {
+  root: HTMLElement;
+  source: HTMLElement;
+  controls: HTMLElement;
+  output: HTMLElement;
+  diagram: HTMLElement;
+}
+
+function getStep(state: WidgetState): TraceChunkEntry {
+  const chunkIndex = Math.floor(state.currentStep / state.manifest.chunkSize);
+  const offset = state.currentStep % state.manifest.chunkSize;
+  return state.chunks.get(chunkIndex)![offset];
+}
+
+function chunkUrlFromManifest(manifestUrl: string, chunkIndex: number): string {
+  return manifestUrl.replace('manifest.json', `chunk-${chunkIndex}.json`);
+}
+
+async function loadChunk(
+  state: WidgetState,
+  manifestUrl: string,
+  chunkIndex: number,
+): Promise<void> {
+  if (state.chunks.has(chunkIndex)) {
+    return;
+  }
+  const url = chunkUrlFromManifest(manifestUrl, chunkIndex);
+  const res = await fetch(url);
+  const chunk: TraceChunkEntry[] = await res.json();
+  state.chunks.set(chunkIndex, chunk);
+}
+
+async function goToStep(
+  state: WidgetState,
+  elements: WidgetElements,
+  manifestUrl: string,
+  stepIndex: number,
+  doc: Document,
+): Promise<void> {
+  stepIndex = Math.max(0, Math.min(stepIndex, state.manifest.totalSteps - 1));
+  const lastChunk = Math.floor(stepIndex / state.manifest.chunkSize);
+  const loads: Promise<void>[] = [];
+  for (let i = 0; i <= lastChunk; i++) {
+    loads.push(loadChunk(state, manifestUrl, i));
+  }
+  await Promise.all(loads);
+  state.currentStep = stepIndex;
+  renderWidgetState(state, elements, doc);
+}
+
+function updateSourceHighlight(panel: HTMLElement, currentLine: number): void {
+  panel.querySelectorAll('.line-number').forEach(ln => {
+    ln.classList.remove('trace-line-active');
+  });
+  const el = panel.querySelector(`.line-number[data-line="${currentLine}"]`);
+  if (el) {
+    el.classList.add('trace-line-active');
+    const elRect = el.getBoundingClientRect();
+    const panelRect = panel.getBoundingClientRect();
+    panel.scrollTop += elRect.top - panelRect.top - panel.clientHeight / 2;
+  }
+}
+
+function updateStepControls(
+  container: HTMLElement,
+  currentStep: number,
+  totalSteps: number,
+  doc: Document,
+): void {
+  const counter = container.querySelector(
+    '.trace-step-counter',
+  ) as HTMLElement | null;
+  if (counter) {
+    counter.textContent = `${currentStep + 1}/${totalSteps}`;
+    const digits = String(totalSteps).length;
+    counter.style.minWidth = `${digits * 2 + 1}ch`;
+  }
+  const first = container.querySelector('.trace-first') as HTMLButtonElement;
+  const prev = container.querySelector('.trace-prev') as HTMLButtonElement;
+  const next = container.querySelector('.trace-next') as HTMLButtonElement;
+  const last = container.querySelector('.trace-last') as HTMLButtonElement;
+  const btns = [first, prev, next, last];
+
+  const focused = doc.activeElement;
+
+  if (first) {
+    first.disabled = currentStep === 0;
+  }
+  if (prev) {
+    prev.disabled = currentStep === 0;
+  }
+  if (next) {
+    next.disabled = currentStep >= totalSteps - 1;
+  }
+  if (last) {
+    last.disabled = currentStep >= totalSteps - 1;
+  }
+
+  // When a clicked button becomes disabled, the browser removes focus.
+  // Move focus to a sensible sibling so the outline stays visible.
+  if (
+    focused &&
+    'disabled' in focused &&
+    (focused as HTMLButtonElement).disabled
+  ) {
+    if (focused === first || focused === prev) {
+      next?.focus();
+    } else if (focused === next || focused === last) {
+      prev?.focus();
+    }
+  }
+
+  // Roving tabindex: the focused button is the Tab stop.
+  const currentFocus = doc.activeElement;
+  const enabled = btns.filter(b => b && !b.disabled);
+  const focusedBtn = enabled.find(b => b === currentFocus);
+  for (const b of enabled) {
+    b.tabIndex = b === focusedBtn ? 0 : -1;
+  }
+  if (!focusedBtn && enabled.length > 0) {
+    enabled[0].tabIndex = 0;
+  }
+  for (const b of btns) {
+    if (b && b.disabled) {
+      b.tabIndex = -1;
+    }
+  }
+}
+
+function renderWidgetState(
+  state: WidgetState,
+  elements: WidgetElements,
+  doc: Document,
+): void {
+  const entry = getStep(state);
+  updateSourceHighlight(elements.source, entry.line);
+  updateStepControls(
+    elements.controls,
+    state.currentStep,
+    state.manifest.totalSteps,
+    doc,
+  );
+  let output = '';
+  for (let i = 0; i <= state.currentStep; i++) {
+    const ci = Math.floor(i / state.manifest.chunkSize);
+    const off = i % state.manifest.chunkSize;
+    const s = state.chunks.get(ci)![off];
+    if (s.stdout) {
+      output += s.stdout;
+    }
+  }
+  elements.output.textContent = output;
+
+  const prevHeight = elements.diagram.scrollHeight;
+  elements.diagram.innerHTML = entry.svg;
+
+  // If the diagram grew past the visible area, scroll to show the new content
+  if (elements.diagram.scrollHeight > prevHeight) {
+    elements.diagram.scrollTop =
+      elements.diagram.scrollHeight - elements.diagram.clientHeight;
+  }
+}
+
+async function initWidget(root: HTMLElement, doc: Document): Promise<void> {
+  const manifestUrl = root.dataset.traceManifest;
+  if (!manifestUrl) {
+    return;
+  }
+
+  const res = await fetch(manifestUrl);
+  const manifest: TraceManifest = await res.json();
+
+  const state: WidgetState = { manifest, chunks: new Map(), currentStep: 0 };
+
+  await loadChunk(state, manifestUrl, 0);
+
+  const entry = getStep(state);
+
+  const source = root.querySelector('.trace-source') as HTMLElement;
+  const diagram = root.querySelector('.trace-diagram') as HTMLElement;
+  const output = root.querySelector('.trace-output') as HTMLPreElement;
+  output.textContent = entry.stdout || '';
+
+  const controls = root.querySelector('.trace-controls') as HTMLElement;
+  const firstBtn = controls.querySelector('.trace-first') as HTMLButtonElement;
+  const prevBtn = controls.querySelector('.trace-prev') as HTMLButtonElement;
+  const nextBtn = controls.querySelector('.trace-next') as HTMLButtonElement;
+  const lastBtn = controls.querySelector('.trace-last') as HTMLButtonElement;
+  firstBtn.addEventListener('click', () =>
+    goToStep(state, elements, manifestUrl, 0, doc),
+  );
+  prevBtn.addEventListener('click', () =>
+    goToStep(state, elements, manifestUrl, state.currentStep - 1, doc),
+  );
+  nextBtn.addEventListener('click', () =>
+    goToStep(state, elements, manifestUrl, state.currentStep + 1, doc),
+  );
+  lastBtn.addEventListener('click', () =>
+    goToStep(state, elements, manifestUrl, manifest.totalSteps - 1, doc),
+  );
+
+  const btns = [firstBtn, prevBtn, nextBtn, lastBtn];
+  controls.addEventListener('keydown', (e: KeyboardEvent) => {
+    if (e.key !== 'ArrowLeft' && e.key !== 'ArrowRight') {
+      return;
+    }
+    const enabled = btns.filter(b => !b.disabled);
+    const idx = enabled.indexOf(doc.activeElement as HTMLButtonElement);
+    if (idx < 0) {
+      return;
+    }
+    e.preventDefault();
+    const next =
+      e.key === 'ArrowRight'
+        ? enabled[(idx + 1) % enabled.length]
+        : enabled[(idx - 1 + enabled.length) % enabled.length];
+    for (const b of enabled) {
+      b.tabIndex = -1;
+    }
+    next.tabIndex = 0;
+    next.focus();
+  });
+
+  const elements: WidgetElements = { root, source, controls, output, diagram };
+
+  updateStepControls(controls, state.currentStep, manifest.totalSteps, doc);
+
+  diagram.innerHTML = entry.svg;
+  updateSourceHighlight(source, entry.line);
+}
+
+export default function mountTrace(window: Window): void {
+  const widgets = window.document.querySelectorAll('.trace-widget');
+
+  if (widgets.length === 0) {
+    return;
+  }
+
+  for (const widget of widgets) {
+    initWidget(widget as HTMLElement, window.document);
+  }
+}

package/src/trace/style.scss

@@ -0,0 +1,210 @@
+.trace-body {
+  display: flex;
+  flex-direction: column;
+  height: calc(100dvh - var(--header-collapsed-height) - 3 * var(--gap));
+  overflow: hidden;
+  gap: var(--gap);
+}
+
+.trace-content {
+  display: flex;
+  flex-direction: column;
+  flex: 1;
+  min-height: 0;
+  gap: var(--gap);
+}
+
+.trace-content > .trace-diagram {
+  flex: 1 1 100%;
+  min-height: 8rem;
+  border: 1px solid var(--fg2-color);
+  border-radius: var(--border-radius);
+  overflow: auto;
+}
+
+.trace-source-wrapper {
+  min-height: calc(
+    3 * var(--font-size-smaller) * var(--mono-line-height) + 1em
+  );
+  max-height: calc(
+    5 * var(--font-size-smaller) * var(--mono-line-height) + 1em
+  );
+  position: relative;
+
+  &:has(:focus-visible)::after {
+    content: '';
+    position: absolute;
+    inset: 0;
+    border: 2px solid var(--theme-color);
+    border-radius: var(--mono-border-radius);
+    pointer-events: none;
+    z-index: 1;
+  }
+
+  & > .trace-source {
+    height: 100%;
+  }
+}
+
+.trace-toolbar {
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  flex-shrink: 0;
+  padding: 3px;
+}
+
+.trace-controls {
+  display: flex;
+  align-items: center;
+  gap: 0.5rem;
+  padding: 6px;
+  border-radius: calc(var(--border-radius) + 4px);
+  background: var(--bg2-color);
+
+  &:focus-within {
+    outline: 2px solid var(--fg-color);
+    outline-offset: 1px;
+  }
+
+  width: 100%;
+  max-width: 386px;
+
+  @media (max-width: 410px) {
+    max-width: none;
+  }
+}
+
+.trace-btn {
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  flex: 1;
+  min-width: 2.5em;
+  padding: 0.5em 0.75em;
+}
+
+.trace-step-counter {
+  text-align: center;
+  font-variant-numeric: tabular-nums;
+  font-size: var(--font-size-smaller);
+}
+
+.trace-source {
+  --code-gutter-width: 4rem;
+  overflow: auto;
+  clip-path: inset(0 round var(--mono-border-radius));
+  scroll-behavior: smooth;
+
+  &:focus-visible {
+    outline: none;
+  }
+
+  & > pre {
+    margin: 0;
+    padding: 0;
+    overflow: visible;
+    width: max-content;
+    min-width: 100%;
+
+    code {
+      padding-right: var(--gap);
+    }
+  }
+
+  .line-number.trace-line-active {
+    font-weight: bold;
+    color: var(--fg-color);
+
+    &::before {
+      content: '\25B6';
+      position: absolute;
+      margin-right: 0.25em;
+      left: 0;
+      line-height: 1.3;
+    }
+  }
+}
+
+.trace-output {
+  flex-shrink: 0;
+  min-height: calc(var(--font-size-smaller) * var(--mono-line-height) + 1em);
+  margin: 0;
+}
+
+.trace-output::before {
+  content: 'Output';
+  display: block;
+  font-size: var(--font-size-small);
+  font-style: italic;
+  color: var(--fg2-color);
+}
+
+.trace-memory {
+  font-family: var(--mono-font, monospace);
+  font-size: var(--font-size-smaller, 15px);
+  max-width: 100%;
+  height: auto;
+
+  .trace-separator {
+    stroke: var(--fg2-color);
+    stroke-width: 1;
+  }
+
+  .trace-frame-title {
+    font-weight: bold;
+    fill: var(--fg-color);
+  }
+
+  .trace-var-name,
+  .trace-field-name {
+    fill: var(--fg-color);
+  }
+
+  .trace-var-box {
+    fill: none;
+    stroke: var(--fg2-color);
+    stroke-width: 1;
+  }
+
+  .trace-obj-border {
+    fill: none;
+    stroke: var(--fg2-color);
+    stroke-width: 1;
+  }
+
+  .trace-val {
+    fill: var(--fg-color);
+  }
+
+  .trace-null {
+    fill: var(--fg2-color);
+  }
+
+  .trace-arrow {
+    fill: none;
+    stroke: var(--fg-color);
+    stroke-width: 1.5;
+  }
+
+  .trace-arrow-dim {
+    fill: none;
+    stroke: var(--fg2-color);
+    stroke-width: 1.5;
+  }
+
+  .trace-arrow-heap {
+    fill: none;
+    stroke: var(--fg2-color);
+    stroke-width: 1.5;
+    stroke-dasharray: 4 3;
+  }
+
+  .trace-arrowhead {
+    fill: var(--fg-color);
+  }
+
+  .trace-arrowhead-dim {
+    fill: var(--fg2-color);
+  }
+}

package/src/trace/types.d.ts

@@ -0,0 +1,47 @@
+export interface TraceManifest {
+  totalSteps: number;
+  chunkSize: number;
+  sourceFile: string;
+  source: string;
+  lineToSteps: Record<number, number[]>;
+}
+
+export interface TraceStep {
+  line: number;
+  file: string;
+  stack: TraceStackFrame[];
+  heap: Record<string, TraceHeapObject>;
+  stdout: string;
+}
+
+export interface TraceStackFrame {
+  method: string;
+  class: string;
+  line: number;
+  locals: Record<string, TraceValue>;
+}
+
+export type TraceValue =
+  | {
+      type: 'int' | 'long' | 'short' | 'byte' | 'float' | 'double';
+      value: number;
+    }
+  | { type: 'boolean'; value: boolean }
+  | { type: 'char' | 'String'; value: string }
+  | { type: 'null' }
+  | { type: 'ref'; id: string }
+  | { type: 'unknown' }
+  | { type: 'uninitialized' }
+  | { type: 'truncated'; remaining: number };
+
+export type TraceHeapObject =
+  | { type: string; elements: TraceValue[] }
+  | { type: string; fields: Record<string, TraceValue> }
+  | { type: string; value: string };
+
+/** A single entry in a chunk file (new format with precomputed SVG). */
+export interface TraceChunkEntry {
+  line: number;
+  stdout: string;
+  svg: string;
+}

package/src/util.test.ts

@@ -0,0 +1,135 @@
+import { describe, expect, test } from 'bun:test';
+import { JSDOM } from 'jsdom';
+import { formatDuration, removeClass, getElement, applyBasePath } from './util';
+
+function create(html: string) {
+  const dom = new JSDOM(`<body>${html}</body>`);
+  return dom.window;
+}
+
+describe('formatDuration', () => {
+  test('formats sub-millisecond values', () => {
+    expect(formatDuration(0.5)).toBe('0.5000ms');
+  });
+
+  test('formats small millisecond values', () => {
+    expect(formatDuration(3.14159)).toBe('3.1416ms');
+  });
+
+  test('formats tens of milliseconds', () => {
+    expect(formatDuration(42.7)).toBe('42.700ms');
+  });
+
+  test('formats hundreds of milliseconds', () => {
+    expect(formatDuration(456.12)).toBe('456.12ms');
+  });
+
+  test('formats exactly 1 second', () => {
+    expect(formatDuration(1000)).toBe('1.00000s');
+  });
+
+  test('formats seconds under 10', () => {
+    expect(formatDuration(5432)).toBe('5.43200s');
+  });
+
+  test('formats seconds 10 and above', () => {
+    expect(formatDuration(12345)).toBe('12.3450s');
+  });
+
+  test('formats exactly 1 minute', () => {
+    expect(formatDuration(60000)).toBe('1m0.000s');
+  });
+
+  test('formats minutes with seconds', () => {
+    expect(formatDuration(90000)).toBe('1m30.00s');
+  });
+
+  test('formats large durations', () => {
+    expect(formatDuration(600000)).toBe('10m0.00s');
+  });
+
+  test('formats zero', () => {
+    expect(formatDuration(0)).toBe('0.0000ms');
+  });
+
+  test('formats negative values with sign', () => {
+    expect(formatDuration(-500)).toBe('-500.00ms');
+  });
+
+  test('formats negative seconds', () => {
+    expect(formatDuration(-5000)).toBe('-5.00000s');
+  });
+});
+
+describe('removeClass', () => {
+  test('removes a class from an element', () => {
+    const win = create('<div class="foo bar">X</div>');
+    const el = win.document.querySelector('div') as HTMLElement;
+    removeClass(el, 'foo');
+    expect(el.classList.contains('foo')).toBe(false);
+    expect(el.classList.contains('bar')).toBe(true);
+  });
+
+  test('removes the class attribute when no classes remain', () => {
+    const win = create('<div class="only">X</div>');
+    const el = win.document.querySelector('div') as HTMLElement;
+    removeClass(el, 'only');
+    expect(el.hasAttribute('class')).toBe(false);
+  });
+
+  test('keeps class attribute when other classes remain', () => {
+    const win = create('<div class="a b">X</div>');
+    const el = win.document.querySelector('div') as HTMLElement;
+    removeClass(el, 'a');
+    expect(el.hasAttribute('class')).toBe(true);
+    expect(el.className).toBe('b');
+  });
+});
+
+describe('getElement', () => {
+  test('returns the matching element', () => {
+    const win = create('<div id="target">Hello</div>');
+    const el = getElement(win.document, '#target');
+    expect(el.textContent).toBe('Hello');
+  });
+
+  test('throws when no element matches', () => {
+    const win = create('<div>No match</div>');
+    expect(() => getElement(win.document, '#missing')).toThrow(
+      'no element matching "#missing"',
+    );
+  });
+
+  test('works with a parent element scope', () => {
+    const win = create(
+      '<div id="a"><span class="inner">A</span></div><div id="b"><span class="inner">B</span></div>',
+    );
+    const parent = win.document.getElementById('b')!;
+    const el = getElement(parent, '.inner');
+    expect(el.textContent).toBe('B');
+  });
+});
+
+describe('applyBasePath', () => {
+  test('prepends the base path to a subpath', () => {
+    (globalThis as Record<string, unknown>).__SITE_BASE_PATH__ = '/docs/';
+    expect(applyBasePath('/page.html')).toBe('/docs/page.html');
+  });
+
+  test('handles base path without trailing slash', () => {
+    (globalThis as Record<string, unknown>).__SITE_BASE_PATH__ = '/docs';
+    expect(applyBasePath('/page.html')).toBe('/docs/page.html');
+  });
+
+  test('handles root base path', () => {
+    (globalThis as Record<string, unknown>).__SITE_BASE_PATH__ = '/';
+    expect(applyBasePath('/page.html')).toBe('/page.html');
+  });
+
+  test('throws for subpath not starting with /', () => {
+    (globalThis as Record<string, unknown>).__SITE_BASE_PATH__ = '/docs';
+    expect(() => applyBasePath('page.html')).toThrow(
+      'invalid internal path, must start with "/"',
+    );
+  });
+});

package/templates/_top.html

@@ -18,6 +18,7 @@
     <meta name="apple-mobile-web-app-title" content="<%= site.symbol %>">
     <meta name="mobile-web-app-capable" content="yes">
     <% } %>
+    <meta name="generator" content="Tada" />
     <meta charset="UTF-8" />
     <meta http-equiv="cache-control" content="no-cache" />
     <meta http-equiv="expires" content="0" />
@@ -53,32 +54,32 @@
 
   <body class="<%= page.template %><% if (page.tocHtml) { %> toc-is-active<% } %>">
     <header data-pagefind-ignore>
+      <div class="header-controls">
+        <div id="to-top-container" class="to-top-container"></div>
+        <% if (site.features.search) { %>
+        <div class="search-controls">
+          <input type="search" class="search quick-search"
+                 autocomplete="off" name="quick-search"
+                 placeholder="Search"
+                 role="combobox"
+                 aria-haspopup="listbox"
+                 aria-autocomplete="list"
+                 aria-expanded="false"
+                 aria-controls="quick-search-results"
+                 disabled />
+          <script>document.currentScript.previousElementSibling.disabled=false;</script>
+        </div>
+        <% } %>
+      </div>
+      <div class="results-container" role="region"
+           aria-label="Search results"
+           aria-live="polite" aria-hidden="true" inert>
+        <div class="results" style="display:none"></div>
+      </div>
       <details>
         <summary aria-label="Toggle site navigation">
           <% if (site.symbol) { %><span class="logo" aria-hidden="true"><%= site.symbol %></span><% } %>
           <span class="site-title" aria-hidden="true"><%= site.title %></span>
-          <div id="to-top-container" class="to-top-container"></div>
-          <% if (site.features.search) { %>
-          <div class="search-controls">
-            <input type="search" class="search quick-search"
-                   autocomplete="off" name="quick-search"
-                   placeholder="Search"
-                   role="combobox"
-                   aria-haspopup="listbox"
-                   aria-autocomplete="list"
-                   aria-expanded="false"
-                   aria-controls="quick-search-results"
-                   disabled />
-            <script>document.currentScript.previousElementSibling.disabled=false;</script>
-            <% if (site.features.search) { %>
-            <div class="results-container" role="region"
-                 aria-label="Search results"
-                 aria-live="polite" aria-hidden="true" inert>
-              <div class="results" style="display:none"></div>
-            </div>
-            <% } %>
-          </div>
-          <% } %>
         </summary>
         <div class="content">
           <%= render('_nav.html') %>