@abreen/tada 1.18.5 → 1.19.1

package/README.md

@@ -5,37 +5,62 @@
 
 A static site generator. The successor to Presto.
 
+<figure>
+  <a href="https://abreen.io/Tada/markdown.html" target="_blank">
+    <img src=".github/screenshot.png" alt="Four screenshots of the Tada example site">
+  </a>
+  <figcaption>
+    A screenshot of the Tada example site in:
+    <ul>
+      <li>light mode</li>
+      <li>dark mode, high contrast</li>
+      <li>light mode, high contrast, & serif fonts</li>
+      <li>dark mode, standard contrast</li>
+    </ul>
+    </figcaption>
+</figure>
+
+[Visit the example site ↗](https://abreen.io/Tada/index.html)
+
+
 ## Features
 
-- 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
-  * Renders headings, alert boxes, and `<hr>` elements
-  * Highlights the heading currently being viewed
+- Modern design
+  * Light & dark mode following system, customizable tint
+  * Standard & high contrast picker
+  * Sans-serif & serif font picker
+  * Plus, provide your own web fonts (with many tuning options)
+
+- LaTeX math support
+  * Provided by [KaTeX][katex]
+  * Rendered completely at build time (zero load time on the client)
+
+- Automatically generated favicon
+  * Text, color, font and font weight taken from config file
+  * Or, provide your own favicon file
+
+- High quality output and ergonomic authoring
+  * Exhaustive internal link validation (broken links fail the build)
+  * External link handling (special visual treatment for external links,
+    no need to type `target="_blank"`)
+  * Internal links automatically prefixed with base path, if specified (no
+    need to keep writing the same URL prefix everywhere)
+
 - Built-in search powered by [Pagefind][pagefind]
   * Only pages in `content/` reachable from `/index.html` are indexed
+  * If `mutool` is installed, text inside PDFs in `content/` is indexed
+
 - Generated HTML pages for source code
   * Automatic code highlighting, clickable line numbers
   * 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
-- Slides mode: separate content by `---` and present sections as full-screen slides
-  * Click icon near slide titles to start presenting at that slide
-  * Right-click in presentation mode to annotate
-  * Hold Shift while annotating to erase
-- PDF files are copied into `dist/`
-  * 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
-- Time zone chooser (automatically adjusts `<datetime>` elements)
-- LaTeX math rendered at build time via [KaTeX][katex]
+
+- Dynamic table of contents
+  * Floats on the side of the screen when window is large enough
+  * Renders headings, alert boxes, and `<hr>` elements
+  * Highlights the heading currently being viewed
+
 - Extended Markdown syntax
   * `<<< details ... <<<` renders a collapsible box
   * `::: section ... :::` renders a special section with a fancy background
@@ -45,9 +70,28 @@ A static site generator. The successor to Presto.
   * `+++ ... +++ ... +++` renders a two-column layout
   * Special heading subtitles with `## Heading # A subtitle here`
   * `{{{ _partial.md }}}` syntax for including partials
-- Custom header logo from an image in `public/`
-- Automatically generated favicon or custom ICO from `public/`
-  * Text, color, font and font weight taken from config file
+
+- Extremely efficient client-side navigation
+  * A miniature SPA that uses internal links tagged at build time
+  * Get the benefits of DOM tree replacement without an entire bloated framework
+  * Thoroughly covered by browser tests across multiple engines
+  * Clear loading indicators for slow requests
+  * Also detects a new version of the current page and supplies a reload button
+
+### Experimental features
+
+- Interactive execution traces via `renderTrace()`
+  * Supports Java and Python source files
+  * Renders step-by-step source highlighting, output, and memory diagrams
+
+- Slides mode: separate content by `---` and present sections as full-screen slides
+  * Click icon near slide titles to start presenting at that slide
+  * Right-click in presentation mode to annotate
+  * Hold Shift while annotating to erase
+
+
+
+- Time zone chooser (automatically adjusts `<datetime>` elements)
 
 ## Prerequisites
 
@@ -107,9 +151,11 @@ Visit [http://localhost:8080/index.html](http://localhost:8080/index.html).
 
 Create a new Tada site in a new directory. Prompts for:
 - **Site title**: displayed in the header and `<title>` tag
-- **Symbol**: short text (1-5 uppercase characters) shown in the logo and favicon
-- **Theme color**: HSL color, e.g. `hsl(195 70% 40%)`
-- **Background tint hue**: hue (0-360) for background/foreground tinting (defaults to `33`)
+- **Symbol**: short text (1-5 uppercase characters) shown in the logo and favicon,
+  or a single emoji shown in the logo (defaults to 🎉; emoji symbols turn off
+  generated favicons)
+- **Theme color**: CSS color, e.g. `hsl(195 70% 40%)` (defaults to `darkturquoise`)
+- **Background tint hue**: hue (0-360) for background/foreground tinting (defaults to `190`)
 - **Background tint amount**: percentage (0-100) of tint to apply (defaults to `100`)
 - **Default time zone**: for `<time>` elements (defaults to your system zone)
 - **Production base URL**: e.g. `https://example.edu`
@@ -268,16 +314,16 @@ vars:
 | `title` | Title for the whole site (also used to derive `titlePostfix`) |
 | `titlePostfix` | *Optional*, the string to append to each page's `title` |
 | `banner` | *Optional*, Markdown rendered in a bordered box above every page |
-| `symbol` | Text (1-5 chars) displayed in header when `logo` is absent; also used for generated favicons |
+| `symbol` | Text (1-5 chars) or a single emoji displayed in header when `logo` is absent; also used for generated favicons |
 | `logo` | *Optional*, image path relative to `public/`, replacing the header symbol |
 | `favicon` | *Optional*, `.ico` path relative to `public/`, replacing generated favicons and the web app manifest |
 | `themeColor` | Theme color for the site (e.g., `"tomato"`, `"#c04040"`, `"hsl(195 70% 40%)"`) |
-| `tintHue` | *Optional*, hue (0-360) for background and foreground tinting (default `33`) |
+| `tintHue` | *Optional*, hue (0-360) for background and foreground tinting (default `190`) |
 | `tintAmount` | *Optional*, percentage (0-100) of tint to apply to the neutral palette (default `100`); link saturation stays fixed |
 | `defaultFont` | *Optional*, initial font pairing: `sans` or `serif` (default `sans`) |
 | `defaultContrast` | *Optional*, initial neutral-palette contrast: `standard` or `high` (default `standard`) |
 | `fontOverrides` | *Optional*, custom serif and serif-monospace WOFF2 faces from `public/`; each configured family requires `regular` and may include styled faces, OpenType `features`, and font-specific `tuning` |
-| `faviconSymbol` | *Optional*, the text to use instead of `symbol` in generated favicons |
+| `faviconSymbol` | *Optional*, the text to use instead of `symbol` in generated favicons; required when `symbol` is an emoji and favicons are generated |
 | `features.search` | Enable search UI and Pagefind index generation |
 | `features.favicon` | Enable favicon links and generation (default `true`); `false` also omits custom favicon links |
 | `features.footer` | Show the Tada footer at the bottom of every page |

package/bin/tada.ts

@@ -27,6 +27,7 @@ import {
   resolveSiteConfigFile,
   type SiteEnv,
 } from '../build/config-files';
+import { isEmojiSymbol } from '../build/utils/symbol';
 
 const { version } = packageJson;
 
@@ -49,7 +50,7 @@ function parsePortArg(name: string): number | undefined {
   const idx = process.argv.indexOf(name);
   if (idx !== -1 && process.argv[idx + 1]) {
     const val = parseInt(process.argv[idx + 1], 10);
-    if (val > 0 && val < 65536) {
+    if (val >= 0 && val < 65536) {
       return val;
     }
   }
@@ -75,22 +76,22 @@ interface InitQuestion {
 const INIT_QUESTIONS: Record<string, InitQuestion> = {
   title: {
     prompt: 'Site title',
-    defaultValue: 'Introduction to Computer Science',
+    defaultValue: 'Tada',
     validate: (v: string) => (v ? null : 'Title is required'),
   },
   symbol: {
-    prompt: 'Logo symbol (1-5 uppercase chars)',
-    defaultValue: 'CS 0',
+    prompt: 'Logo symbol (1-5 uppercase chars or one emoji)',
+    defaultValue: '🎉',
     validate: validateSymbol,
   },
   themeColor: {
     prompt: 'Theme color',
-    defaultValue: 'hsl(195 70% 40%)',
+    defaultValue: 'darkturquoise',
     validate: validateColor,
   },
   tintHue: {
     prompt: 'Background tint hue (0-360)',
-    defaultValue: '33',
+    defaultValue: '190',
     validate: validateHue,
   },
   tintAmount: {
@@ -338,6 +339,14 @@ async function initCommand(args: string[]): Promise<void> {
   // Create project directory
   fs.mkdirSync(projectDir);
 
+  // Generated favicons are text-only, so an emoji symbol starts without them
+  const features = {
+    search: true,
+    favicon: !isEmojiSymbol(symbol),
+    footer: true,
+    pickers: true,
+  };
+
   // Generate site configs
   const devConfig = createSiteConfig({
     title,
@@ -349,7 +358,7 @@ async function initCommand(args: string[]): Promise<void> {
     base: 'http://localhost:8080',
     basePath: '/',
     internalDomains: ['localhost'],
-    features: { search: true, favicon: false, footer: true, pickers: true },
+    features,
     extensionToShikiLanguage: bare ? {} : { java: 'java', py: 'python' },
     shikiLanguages: bare ? [] : ['java', 'python', 'html'],
   });
@@ -364,7 +373,7 @@ async function initCommand(args: string[]): Promise<void> {
     base: prodBase,
     basePath: prodBasePath,
     internalDomains: [prodDomain],
-    features: { search: true, favicon: true, footer: true, pickers: true },
+    features,
     extensionToShikiLanguage: bare ? {} : { java: 'java', py: 'python' },
     shikiLanguages: bare ? [] : ['java', 'python', 'html'],
   });

package/bin/validators.ts

@@ -1,5 +1,6 @@
 import timezones from '../src/timezone/timezones.json' with { type: 'json' };
 import type { SiteConfigInput, SiteVariables } from '../build/types';
+import { isValidSymbol } from '../build/utils/symbol';
 
 const SUPPORTED_TIME_ZONES: readonly string[] = timezones.map(tz => tz.value);
 const FALLBACK_TIME_ZONE = 'UTC';
@@ -8,13 +9,13 @@ export function validateSymbol(value: string): string | null {
   if (!value) {
     return 'Symbol is required';
   }
-  if (value.length > 5) {
-    return 'Symbol must be 5 characters or fewer';
+  if (isValidSymbol(value)) {
+    return null;
   }
-  if (!/^[A-Z0-9\- ]{1,5}$/.test(value)) {
-    return 'Symbol must contain only uppercase letters, digits, hyphens, and spaces';
+  if (value.length > 5) {
+    return 'Symbol must be 5 characters or fewer, or a single emoji';
   }
-  return null;
+  return 'Symbol must contain only uppercase letters, digits, hyphens, and spaces, or be a single emoji';
 }
 
 export function validateColor(value: string): string | null {

package/build/bundle.ts

@@ -51,7 +51,7 @@ function renderThemeScss(siteVariables: SiteVariables): string {
   const templatePath = path.join(getPackageDir(), 'templates/_theme.scss');
   const template = fs.readFileSync(templatePath, 'utf-8');
   const theme = deriveTheme(siteVariables.themeColor);
-  const tintHue = siteVariables.tintHue ?? 33;
+  const tintHue = siteVariables.tintHue ?? 190;
   const tintAmount = siteVariables.tintAmount ?? 100;
 
   const linkHue = formatCssNumber(deriveLinkHue(tintHue));

package/build/config-loader.ts

@@ -29,6 +29,14 @@ export function parseConfigText(text: string, fileName: string): unknown {
   try {
     return Bun.YAML.parse(text);
   } catch (error) {
+    // YAML rejects JSON surrogate pair escapes such as emoji in `\ud83c\udf89` form
+    if (fileName.endsWith('.json')) {
+      try {
+        return JSON.parse(text);
+      } catch {
+        // Report the YAML error, as for any other config
+      }
+    }
     const message = error instanceof Error ? error.message : String(error);
     throw new Error(`${fileName}: ${message}`, { cause: error });
   }

package/build/reachability.ts

@@ -2,59 +2,24 @@ import path from 'path';
 import { normalizeOutputPath } from './util';
 import type { HtmlOutputAnalysis } from './types';
 
-function normalizeInternalTarget(target: string): string {
-  return normalizeOutputPath(target);
-}
-
+/** HTML candidates for an already normalized target without a non-HTML extension. */
 function toCandidateHtmlAssetPaths(target: string): string[] {
-  const normalizedTarget = normalizeInternalTarget(target);
-
-  if (normalizedTarget === '/') {
+  if (target === '/') {
     return ['index.html'];
   }
 
-  if (normalizedTarget.endsWith('.html')) {
-    return [normalizedTarget.slice(1)];
-  }
-
-  if (path.posix.extname(normalizedTarget)) {
-    return [];
+  if (target.endsWith('.html')) {
+    return [target.slice(1)];
   }
 
-  const withoutLeadingSlash = normalizedTarget.slice(1);
-  if (normalizedTarget.endsWith('/')) {
+  const withoutLeadingSlash = target.slice(1);
+  if (target.endsWith('/')) {
     return [`${withoutLeadingSlash}index.html`];
   }
 
   return [`${withoutLeadingSlash}/index.html`, `${withoutLeadingSlash}.html`];
 }
 
-function resolveTargetToAssetTarget(target: string): string | null {
-  const normalizedTarget = normalizeInternalTarget(target);
-  if (normalizedTarget === '/' || normalizedTarget.endsWith('.html')) {
-    return null;
-  }
-  return path.posix.extname(normalizedTarget) ? normalizedTarget : null;
-}
-
-function collectOutgoingHtmlAssetPaths(
-  analysis: HtmlOutputAnalysis,
-  knownHtmlAssetPaths: Set<string>,
-): string[] {
-  const htmlAssetPaths = new Set<string>();
-
-  for (const target of analysis.outgoingTargets) {
-    for (const candidate of toCandidateHtmlAssetPaths(target)) {
-      if (knownHtmlAssetPaths.has(candidate)) {
-        htmlAssetPaths.add(candidate);
-        break;
-      }
-    }
-  }
-
-  return [...htmlAssetPaths].sort();
-}
-
 interface CollectReachableOptions {
   htmlAnalysisByPath: Map<string, HtmlOutputAnalysis>;
   knownAssetTargets?: Set<string>;
@@ -75,7 +40,6 @@ export function collectReachableSiteAssets({
     throw new Error(`Pagefind reachability root not found: ${rootPath}`);
   }
 
-  const knownHtmlAssetPaths = new Set(htmlAnalysisByPath.keys());
   const reachableHtmlPaths = new Set<string>();
   const reachableAssetTargets = new Set<string>();
   const pending: string[] = [rootPath];
@@ -89,19 +53,19 @@ export function collectReachableSiteAssets({
 
     const analysis = htmlAnalysisByPath.get(currentPath)!;
 
-    for (const targetPath of collectOutgoingHtmlAssetPaths(
-      analysis,
-      knownHtmlAssetPaths,
-    )) {
-      if (!reachableHtmlPaths.has(targetPath)) {
-        pending.push(targetPath);
+    for (const outgoingTarget of analysis.outgoingTargets) {
+      const target = normalizeOutputPath(outgoingTarget);
+      if (!target.endsWith('.html') && path.posix.extname(target)) {
+        if (knownAssetTargets.has(target)) {
+          reachableAssetTargets.add(target);
+        }
+        continue;
       }
-    }
-
-    for (const target of analysis.outgoingTargets) {
-      const assetTarget = resolveTargetToAssetTarget(target);
-      if (assetTarget && knownAssetTargets.has(assetTarget)) {
-        reachableAssetTargets.add(assetTarget);
+      const targetPath = toCandidateHtmlAssetPaths(target).find(candidate =>
+        htmlAnalysisByPath.has(candidate),
+      );
+      if (targetPath && !reachableHtmlPaths.has(targetPath)) {
+        pending.push(targetPath);
       }
     }
   }

package/build/site-variables.ts

@@ -4,6 +4,7 @@ import type { SiteEnv } from './config-files';
 import { loadSiteConfig } from './config-loader';
 import { compile as compileJsonSchema, doValidation } from './json-schema';
 import { getProjectDir } from './utils/paths';
+import { isEmojiSymbol } from './utils/symbol';
 import type { PlainTextLanguage, SiteVariables } from './types';
 import siteSchema from '../schema/site.schema.json' with { type: 'json' };
 import timezones from '../src/timezone/timezones.json' with { type: 'json' };
@@ -131,10 +132,7 @@ function getSiteVariables(env: SiteEnv): SiteVariables {
     },
   } as SiteVariables;
 
-  // Derive faviconSymbol from symbol if not explicitly set
-  if (variables.symbol && !variables.faviconSymbol) {
-    variables.faviconSymbol = variables.symbol;
-  }
+  resolveFaviconSymbol(variables, fileName);
 
   // Derive faviconColor from themeColor if not explicitly set
   if (!variables.faviconColor) {
@@ -157,6 +155,28 @@ function getSiteVariables(env: SiteEnv): SiteVariables {
   return variables;
 }
 
+/**
+ * Derive faviconSymbol from a text symbol. Generated favicons are drawn with a
+ * text font that has no emoji, so an emoji symbol needs a text faviconSymbol.
+ */
+export function resolveFaviconSymbol(
+  variables: SiteVariables,
+  fileName: string,
+): void {
+  if (!variables.symbol || variables.faviconSymbol) {
+    return;
+  }
+  if (!isEmojiSymbol(variables.symbol)) {
+    variables.faviconSymbol = variables.symbol;
+    return;
+  }
+  if (variables.features.favicon !== false && !variables.favicon) {
+    throw new Error(
+      `${fileName}: faviconSymbol is required when symbol is an emoji and favicons are generated; set faviconSymbol to 1 to 5 uppercase characters, digits, hyphens, or spaces`,
+    );
+  }
+}
+
 export function getDevSiteVariables(): SiteVariables {
   return getSiteVariables('dev');
 }

package/build/template-globals.ts

@@ -1,4 +1,5 @@
 import { encodePublicAssetPath } from './custom-fonts';
+import { isEmojiSymbol } from './utils/symbol';
 import timezones from '../src/timezone/timezones.json' with { type: 'json' };
 import type { SiteVariables } from './types';
 
@@ -26,6 +27,7 @@ interface TemplateGlobals {
   cx: (obj: Record<string, unknown>) => string;
   encodeAuthoredUrl: (value: string) => string;
   encodePublicAssetPath: (value: string) => string;
+  isEmojiSymbol: (value: string | null | undefined) => boolean;
   renderTimeZoneChooser: () => string;
 }
 
@@ -56,6 +58,7 @@ export default function createTemplateGlobals(
     cx: classNames,
     encodeAuthoredUrl,
     encodePublicAssetPath,
+    isEmojiSymbol,
     renderTimeZoneChooser,
   };
 }

package/build/utils/render.ts

@@ -426,7 +426,7 @@ export function renderCopiedContentAsset({
   const rawSource = fs.readFileSync(filePath, 'utf-8');
   const templated = applySourceTemplate(rawSource, siteVariables, filePath);
 
-  if (filePath.endsWith('.java')) {
+  if (path.extname(filePath).toLowerCase() === '.java') {
     const pageDirPath = toPosix(
       path.relative(contentDir, path.dirname(filePath)),
     );
@@ -568,7 +568,7 @@ function renderPlainTextContent(
 } {
   const applyBasePath = createApplyBasePath(siteVariables);
 
-  const ext = path.extname(filePath);
+  const ext = path.extname(filePath).toLowerCase();
   const raw = fs.readFileSync(filePath, 'utf-8');
   const { pageVariables: rawPageVariables, content } =
     parseFrontMatterAndContent(raw, ext);

package/build/utils/symbol.ts

@@ -0,0 +1,21 @@
+// One emoji: a flag, keycap, subdivision flag, or pictograph with optional
+// skin tone and ZWJ joins. Written for the `u` flag so the site schema (Ajv)
+// can share it; `\p{RGI_Emoji}` needs the `v` flag.
+const EMOJI = String.raw`\p{RI}\p{RI}|[#*0-9]\uFE0F\u20E3|\u{1F3F4}[\u{E0061}-\u{E007A}]+\u{E007F}|(?!\p{RI})(?:\p{Emoji_Presentation}|\p{Extended_Pictographic}\uFE0F)\p{Emoji_Modifier}?(?:\u200D(?:\p{Emoji_Presentation}|\p{Extended_Pictographic}\uFE0F?)\p{Emoji_Modifier}?)*`;
+
+/** Must match `faviconSymbol` in `schema/site.schema.json` */
+export const TEXT_SYMBOL_PATTERN = '^[A-Z0-9\\- ]{1,5}$';
+
+/** Must match `symbol` in `schema/site.schema.json` */
+export const SYMBOL_PATTERN = `^(?:[A-Z0-9\\- ]{1,5}|${EMOJI})$`;
+
+const SYMBOL_RE = new RegExp(SYMBOL_PATTERN, 'u');
+const EMOJI_RE = new RegExp(`^(?:${EMOJI})$`, 'u');
+
+export function isValidSymbol(value: string): boolean {
+  return SYMBOL_RE.test(value);
+}
+
+export function isEmojiSymbol(value: string | null | undefined): boolean {
+  return value != null && EMOJI_RE.test(value);
+}

package/build/utils/trace-layout.ts

@@ -34,18 +34,13 @@ const MIN_ARRAY_CELL_WIDTH = 48;
 
 /** Information collected about a heap object across all trace steps. */
 interface ObjectInfo {
-  id: string;
   type: string;
   firstStep: number;
   lastStep: number;
-  /** Set of object IDs this object ever references (across all steps). */
-  references: Set<string>;
   /** Step indices where this object is actually present. */
   activeSteps: Set<number>;
   /** Per-field reference targets (field name -> set of referenced object IDs). */
   fieldRefs: Map<string, Set<string>>;
-  /** Max number of fields seen on this object (for field objects). */
-  maxFields: number;
   /** Max number of elements seen on this object (for arrays). */
   maxElements: number;
   /** Scalar value (for heap objects represented by a single value). */
@@ -70,7 +65,7 @@ interface TreeNode {
 
 /**
  * Walk every step, collect every heap object's type, lifetime (first/last step),
- * all references it ever makes, max fields seen, whether it's an array or string.
+ * reference targets by field, display widths, and whether it's an array or string.
  */
 export function scanSteps(steps: TraceStep[]): Map<string, ObjectInfo> {
   const objects = new Map<string, ObjectInfo>();
@@ -81,14 +76,11 @@ export function scanSteps(steps: TraceStep[]): Map<string, ObjectInfo> {
       let info = objects.get(id);
       if (!info) {
         info = {
-          id,
           type: obj.type,
           firstStep: stepIndex,
           lastStep: stepIndex,
-          references: new Set(),
           activeSteps: new Set(),
           fieldRefs: new Map(),
-          maxFields: 0,
           maxElements: 0,
           value: null,
           hasValue: false,
@@ -115,18 +107,14 @@ export function scanSteps(steps: TraceStep[]): Map<string, ObjectInfo> {
 
         for (const elem of obj.elements) {
           if (elem.type === 'ref') {
-            info.references.add(elem.id);
             elemRefs.add(elem.id);
           }
         }
       } else if ('fields' in obj) {
-        const fieldEntries = Object.entries(obj.fields);
-        info.maxFields = Math.max(info.maxFields, fieldEntries.length);
-        for (const [fieldName, val] of fieldEntries) {
+        for (const [fieldName, val] of Object.entries(obj.fields)) {
           info.fieldNames.add(fieldName);
 
           if (val.type === 'ref') {
-            info.references.add(val.id);
             if (!info.fieldRefs.has(fieldName)) {
               info.fieldRefs.set(fieldName, new Set());
             }

package/package.json

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

package/schema/site.schema.json

@@ -31,14 +31,17 @@
     },
     "title": { "type": "string" },
     "banner": { "type": "string" },
-    "symbol": { "type": "string", "pattern": "^[A-Z0-9\\- ]{1,5}$" },
+    "symbol": {
+      "type": "string",
+      "pattern": "^(?:[A-Z0-9\\- ]{1,5}|\\p{RI}\\p{RI}|[#*0-9]\\uFE0F\\u20E3|\\u{1F3F4}[\\u{E0061}-\\u{E007A}]+\\u{E007F}|(?!\\p{RI})(?:\\p{Emoji_Presentation}|\\p{Extended_Pictographic}\\uFE0F)\\p{Emoji_Modifier}?(?:\\u200D(?:\\p{Emoji_Presentation}|\\p{Extended_Pictographic}\\uFE0F?)\\p{Emoji_Modifier}?)*)$"
+    },
     "titlePostfix": { "type": "string" },
     "themeColor": { "type": "string" },
     "tintHue": {
       "type": "integer",
       "minimum": 0,
       "maximum": 360,
-      "default": 33
+      "default": 190
     },
     "tintAmount": {
       "type": "integer",

package/src/_content.scss

@@ -184,7 +184,7 @@ button.icon-button:focus {
 
 ol.styled-list,
 ul.styled-list {
-  font-weight: 700;
+  font-weight: 600;
   color: var(--theme-color-text);
 }
 

package/src/_icons.scss

@@ -65,7 +65,7 @@
   @include define-icon(
     'heading-present',
     24,
-    "<rect x='3.25' y='5.25' width='17.5' height='13.5' rx='2.25'/><path d='M10.25 9.25v5.5L14.75 12z' fill='black'/>"
+    "<rect x='4' y='5' width='16' height='11' rx='1'/><path d='M12 16v4M9 20h6'/>"
   );
   @include define-icon(
     'check',

package/src/_layout.scss

@@ -220,6 +220,7 @@ body.literate main table {
 footer {
   @include user-select(none);
 
+  font-size: var(--font-size-smaller);
   color: var(--fg2-color);
   text-align: center;
 

package/src/header/_index.scss

@@ -184,6 +184,17 @@ header summary .logo {
   background: var(--theme-color);
 }
 
+// A single emoji is the logo itself: no badge, sized like an image logo
+header summary .logo-emoji {
+  padding: 0;
+  font-family:
+    'Apple Color Emoji', 'Segoe UI Emoji', 'Noto Color Emoji', sans-serif;
+  font-size: 22px;
+  font-weight: normal;
+  line-height: 24px;
+  background: none;
+}
+
 header summary .logo-image {
   flex: 0 0 auto;
   width: auto;

package/src/index.ts

@@ -25,6 +25,8 @@ const PERSISTENT_COMPONENTS: Record<
 let startTime = -1;
 
 document.addEventListener('DOMContentLoaded', async () => {
+  const initialHref = window.location.href;
+  const initialHash = window.location.hash;
   startTime = window.performance.now();
 
   const failed: Record<string, string> = {};
@@ -54,8 +56,8 @@ document.addEventListener('DOMContentLoaded', async () => {
   // fragment scroll. Do it ourselves once per-page components have
   // finished mutating the DOM. On a fresh cold load the browser already
   // scrolled, so this is a harmless re-align.
-  if (window.location.hash) {
-    getHashTarget(window.document, window.location.hash)?.scrollIntoView();
+  if (initialHash && window.location.href === initialHref) {
+    getHashTarget(window.document, initialHash)?.scrollIntoView();
   }
 
   for (const [name, reason] of Object.entries(failed)) {

package/src/navigate/_index.scss

@@ -7,6 +7,11 @@ $movement-easing: cubic-bezier(0.2, 0, 0, 1);
   --page-transition-movement-easing: #{$movement-easing};
 }
 
+html.navigation-loading,
+html.navigation-loading * {
+  cursor: progress !important;
+}
+
 @keyframes page-fade-out {
   to {
     opacity: 0;

package/src/navigate/runtime.ts

@@ -9,6 +9,8 @@ import { swapHeaderTitle } from '../header';
 
 export const NAVIGATION_EVENT = 'tada:navigation';
 
+const LOADING_CURSOR_DELAY = 400;
+
 let currentAbortController: AbortController | null = null;
 let historyIndex = 0;
 let currentPath = '';
@@ -235,15 +237,28 @@ export async function navigateToUrl(
 
   const header = document.querySelector('header');
   header?.classList.add('loading');
+  const loadingCursorTimeout = window.setTimeout(() => {
+    if (isActiveNavigation(controller)) {
+      document.documentElement.classList.add('navigation-loading');
+    }
+  }, LOADING_CURSOR_DELAY);
+  const stopLoading = (): void => {
+    window.clearTimeout(loadingCursorTimeout);
+    if (!isActiveNavigation(controller)) {
+      return;
+    }
+    header?.classList.remove('loading');
+    document.documentElement.classList.remove('navigation-loading');
+  };
 
   let response: Response;
   try {
     response = await globals.fetch(url, { signal: controller.signal });
   } catch (err: unknown) {
+    stopLoading();
     if (!isActiveNavigation(controller)) {
       return;
     }
-    header?.classList.remove('loading');
     if (isAbortError(err)) {
       return;
     }
@@ -252,11 +267,12 @@ export async function navigateToUrl(
   }
 
   if (!isActiveNavigation(controller)) {
+    stopLoading();
     return;
   }
 
   if (!response.ok) {
-    header?.classList.remove('loading');
+    stopLoading();
     globals.setLocationHref(window, url);
     return;
   }
@@ -265,10 +281,10 @@ export async function navigateToUrl(
   try {
     html = await response.text();
   } catch (err: unknown) {
+    stopLoading();
     if (!isActiveNavigation(controller)) {
       return;
     }
-    header?.classList.remove('loading');
     if (isAbortError(err)) {
       return;
     }
@@ -277,10 +293,11 @@ export async function navigateToUrl(
   }
 
   if (!isActiveNavigation(controller)) {
+    stopLoading();
     return;
   }
 
-  header?.classList.remove('loading');
+  stopLoading();
 
   const DOMParserCtor = (window as unknown as { DOMParser: typeof DOMParser })
     .DOMParser;

package/src/question/_index.scss

@@ -21,7 +21,7 @@
 .question-a-label {
   flex: 0 0 var(--question-label-width);
   margin: 0;
-  font-weight: 700;
+  font-weight: 600;
   color: var(--theme-color-text);
 
   @include user-select(none);

package/src/question/index.ts

@@ -62,12 +62,19 @@ export default (window: Window) => {
   const bodies =
     window.document.querySelectorAll<HTMLElement>('.question-a-body');
   bodies.forEach(el => {
+    const content = el.querySelector<HTMLElement>('.question-a-content');
+    if (content) {
+      content.inert = !el.hasAttribute('data-revealed');
+    }
     el.setAttribute('role', 'button');
     el.setAttribute('tabindex', '0');
     el.setAttribute('aria-label', 'Click to reveal answer');
 
     const reveal = () => {
       el.setAttribute('data-revealed', '');
+      if (content) {
+        content.inert = false;
+      }
       el.removeAttribute('role');
       el.removeAttribute('tabindex');
       el.removeAttribute('aria-label');

package/src/search/index.ts

@@ -94,25 +94,7 @@ async function doSearch(query: string, window: Window): Promise<SearchState> {
   return { totalResults: grouped.length, results: grouped };
 }
 
-function applyHighlight(
-  resultsContainer: HTMLElement,
-  focusedEl: HTMLElement | null,
-) {
-  const options = Array.from(
-    resultsContainer.querySelectorAll('[role="option"]'),
-  ) as HTMLElement[];
-  options.forEach(opt => {
-    const selected = focusedEl !== null && opt.contains(focusedEl);
-    opt.setAttribute('aria-selected', selected ? 'true' : 'false');
-  });
-}
-
-function render(
-  input: HTMLInputElement,
-  resultsContainer: HTMLElement,
-  state: State,
-  loading = false,
-) {
+function render(resultsContainer: HTMLElement, state: State, loading = false) {
   const doc = resultsContainer.ownerDocument;
 
   if (state.showResults) {
@@ -129,16 +111,10 @@ function render(
   }
 
   const ol = doc.createElement('ol');
-  ol.id = `${input.name}-results`;
-  ol.role = 'listbox';
-  ol.tabIndex = -1;
   ol.setAttribute('aria-label', 'Search results');
 
-  const totalVisible = state.results.length;
-
-  state.results.forEach((result, i) => {
+  state.results.forEach(result => {
     const a = doc.createElement('a');
-    a.id = `result-${i}`;
     a.className = 'result';
     a.href = result.url;
     const isGeneratedPage = Boolean(result.template);
@@ -148,7 +124,6 @@ function render(
     a.tabIndex = 0;
 
     const titleEl = doc.createElement('div');
-    titleEl.id = `title-${i}`;
     titleEl.className = 'title';
     if (result.template === 'code') {
       titleEl.classList.add('code-page');
@@ -166,12 +141,6 @@ function render(
     a.appendChild(excerpt);
 
     const li = doc.createElement('li');
-    li.id = `option-${i}`;
-    li.setAttribute('role', 'option');
-    li.setAttribute('aria-selected', 'false');
-    li.setAttribute('aria-setsize', String(totalVisible));
-    li.setAttribute('aria-posinset', String(i + 1));
-    li.setAttribute('aria-labelledby', `title-${i}`);
     li.appendChild(a);
 
     const subsToShow = result.subResults;
@@ -265,9 +234,6 @@ function render(
     resultsContainer.setAttribute('aria-hidden', 'true');
     resultsContainer.setAttribute('inert', '');
   }
-
-  input.setAttribute('aria-expanded', String(state.showResults));
-  input.setAttribute('aria-controls', ol.id);
 }
 
 export default (window: Window) => {
@@ -335,7 +301,7 @@ export default (window: Window) => {
         pagefindLoadGeneration += 1;
         console.log(`failed to load Pagefind: ${err}`);
         if (state.showResults) {
-          render(input!, resultsContainer, state, false);
+          render(resultsContainer, state, false);
         }
       }
       return false;
@@ -362,7 +328,7 @@ export default (window: Window) => {
 
   async function update(updateId: number) {
     if (state.showResults) {
-      render(input!, resultsContainer, state, true);
+      render(resultsContainer, state, true);
     }
     const query = state.value;
     if (!(await loadPagefind()) || updateId !== latestUpdateId) {
@@ -380,7 +346,7 @@ export default (window: Window) => {
     if (!state.showResults) {
       return;
     }
-    render(input!, resultsContainer, state, false);
+    render(resultsContainer, state, false);
   }
 
   function queueUpdate() {
@@ -402,7 +368,7 @@ export default (window: Window) => {
       .catch(err => {
         console.log(`failed to load Pagefind: ${err}`);
         if (state.showResults) {
-          render(input!, resultsContainer, state, false);
+          render(resultsContainer, state, false);
         }
       });
   }
@@ -418,7 +384,7 @@ export default (window: Window) => {
     const stalePagefind = pagefind;
     invalidatePagefind();
     if (state.showResults) {
-      render(input!, resultsContainer, state, true);
+      render(resultsContainer, state, true);
     }
     if (stalePagefind) {
       try {
@@ -434,7 +400,7 @@ export default (window: Window) => {
     reloadPagefindAfterPageUpdateRefresh().catch(err => {
       console.log(`failed to reload Pagefind: ${err}`);
       if (state.showResults) {
-        render(input!, resultsContainer, state, false);
+        render(resultsContainer, state, false);
       }
     });
   }
@@ -446,7 +412,7 @@ export default (window: Window) => {
       return;
     }
     state.showResults = false;
-    render(input!, resultsContainer, state);
+    render(resultsContainer, state);
   }
 
   function handleInput(e: Event) {
@@ -573,23 +539,11 @@ export default (window: Window) => {
       }
     } else if (e.key === 'Escape') {
       e.preventDefault();
-      hide();
       input!.focus();
+      hide();
     }
   }
 
-  function handleResultsFocusIn(e: FocusEvent) {
-    applyHighlight(resultsContainer, e.target as HTMLElement);
-  }
-
-  function handleResultsFocusOut(e: FocusEvent) {
-    const related = e.relatedTarget as HTMLElement | null;
-    if (related && (resultsContainer.contains(related) || related === input)) {
-      return;
-    }
-    applyHighlight(resultsContainer, null);
-  }
-
   function handleWindowPointerDown(e: PointerEvent) {
     const target = e.target as Node;
     if (!input!.contains(target) && !resultsContainer.contains(target)) {
@@ -616,8 +570,6 @@ export default (window: Window) => {
   resultsContainer.addEventListener('pointerdown', handlePointerDown);
   resultsContainer.addEventListener('click', handleResultClick);
   resultsContainer.addEventListener('keydown', handleResultsKeyDown);
-  resultsContainer.addEventListener('focusin', handleResultsFocusIn);
-  resultsContainer.addEventListener('focusout', handleResultsFocusOut);
   window.addEventListener('pointerup', handleWindowPointerUp);
   window.addEventListener('pointerdown', handleWindowPointerDown);
   window.addEventListener('pointermove', handleWindowPointerMove);
@@ -637,8 +589,6 @@ export default (window: Window) => {
     window.removeEventListener('pointermove', handleWindowPointerMove);
     window.removeEventListener('pointerdown', handleWindowPointerDown);
     window.removeEventListener('pointerup', handleWindowPointerUp);
-    resultsContainer.removeEventListener('focusout', handleResultsFocusOut);
-    resultsContainer.removeEventListener('focusin', handleResultsFocusIn);
     resultsContainer.removeEventListener('keydown', handleResultsKeyDown);
     resultsContainer.removeEventListener('click', handleResultClick);
     resultsContainer.removeEventListener('pointerdown', handlePointerDown);

package/src/top/README.md

@@ -1,4 +1,9 @@
 # The `top` component
 
-Show a floating "back to top" button once the page is scrolled more than 250px,
-and keep it visible until the page is back near the top.
+Show a floating "back to top" button on long pages once the reader has scrolled
+well down the page, and keep it visible until they are back above that point.
+
+- The page must be at least 3 viewports tall; shorter pages never show it.
+- It shows once the scroll position passes 1.5 viewports or 25% of the
+  scrollable distance, whichever is farther.
+- Visibility is recalculated on scroll and on resize.

package/src/top/index.ts

@@ -1,8 +1,14 @@
 import { debounce, removeClass } from '../util';
 import { globals } from '../globals';
 
-/** Show the "Back to top" button once the user is past this scroll position */
-const SHOW_THRESHOLD_PX = 250;
+/** Only show the "Back to top" button on pages at least this many viewports tall */
+const MIN_PAGE_SCREENS = 3;
+
+/** Show the button once the user is this many viewports down the page... */
+const SHOW_AFTER_SCREENS = 1.5;
+
+/** ...or this fraction of the scrollable distance, whichever is farther */
+const SHOW_AFTER_FRACTION = 0.25;
 
 /** Debounce time (maximum amount of time to wait before updates) */
 const LATENCY_MS = 50;
@@ -60,8 +66,22 @@ export default (window: Window) => {
     isShowing = false;
   }
 
+  function shouldShow(): boolean {
+    const viewportHeight = window.innerHeight;
+    const maxScroll =
+      window.document.documentElement.scrollHeight - viewportHeight;
+    if (maxScroll < (MIN_PAGE_SCREENS - 1) * viewportHeight) {
+      return false;
+    }
+    const threshold = Math.max(
+      SHOW_AFTER_SCREENS * viewportHeight,
+      SHOW_AFTER_FRACTION * maxScroll,
+    );
+    return window.scrollY > threshold;
+  }
+
   function updateVisibility() {
-    if (window.scrollY > SHOW_THRESHOLD_PX) {
+    if (shouldShow()) {
       show(link);
     } else {
       hide(link);
@@ -70,9 +90,11 @@ export default (window: Window) => {
 
   const debounced = debounce(window, updateVisibility, LATENCY_MS);
   window.addEventListener('scroll', debounced, { passive: true });
+  window.addEventListener('resize', debounced, { passive: true });
   updateVisibility();
 
   return () => {
     window.removeEventListener('scroll', debounced);
+    window.removeEventListener('resize', debounced);
   };
 };

package/templates/_top.html

@@ -23,7 +23,7 @@
     <link rel="apple-touch-icon" sizes="512x512" href="/favicon-512.png" />
     <link rel="apple-touch-icon" sizes="256x256" href="/favicon-256.png" />
     <link rel="manifest" href="/manifest.json" />
-    <meta name="apple-mobile-web-app-title" content="<%- site.symbol %>">
+    <meta name="apple-mobile-web-app-title" content="<%- site.title %>">
     <meta name="mobile-web-app-capable" content="yes">
     <% } %>
     <% } %>
@@ -192,20 +192,17 @@
       <div class="header-controls">
         <div id="to-top-container" class="to-top-container"></div>
         <% if (site.features.search) { %>
-        <div class="search-controls">
+        <div class="search-controls" role="search">
           <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-label="Search"
                  aria-controls="quick-search-results"
                  disabled />
         </div>
         <% } %>
       </div>
-      <div class="results-container" role="region"
+      <div id="quick-search-results" class="results-container" role="region"
            aria-label="Search results"
            aria-live="polite" aria-hidden="true" inert>
         <div class="results" style="display:none"></div>
@@ -219,7 +216,7 @@
             <path class="menu-icon-line menu-icon-line-middle" d="M3 12h18" />
             <path class="menu-icon-line menu-icon-line-bottom" d="M3 18h18" />
           </svg>
-          <% if (site.logo) { %><img class="logo-image" src="/<%- encodePublicAssetPath(site.logo) %>" alt="" aria-hidden="true" /><% } else if (site.symbol) { %><span class="logo" aria-hidden="true"><%- site.symbol %></span><% } %>
+          <% if (site.logo) { %><img class="logo-image" src="/<%- encodePublicAssetPath(site.logo) %>" alt="" aria-hidden="true" /><% } else if (site.symbol) { %><span class="<%- isEmojiSymbol(site.symbol) ? 'logo logo-emoji' : 'logo' %>" aria-hidden="true"><%- site.symbol %></span><% } %>
           <span class="header-title" aria-hidden="true">
             <span class="header-title-reel">
               <span class="site-title"><%- site.title %></span>