tosijs-ui 1.16.35 → 1.16.37

package/CHANGELOG.md

@@ -1,5 +1,41 @@
 # Changelog
 
+## 1.16.37
+
+Doc-site test running, as a developer meets it. On a deployed site, tests still start off; the
+only difference there is how a passing run looks to a reader who turns them on.
+
+- **Safari no longer stalls the background test run.** The runner loads each page with tests in
+  a hidden frame, and parked that frame off-screen; WebKit gives an off-screen frame no
+  animation frames, tosijs renders on them, so every page waited out its 45-second deadline and
+  the header read "Running 0" for the whole run. The frame now sits inside the viewport, clipped
+  so nothing paints. The doc-test gate runs in WebKit for the first time, and passes.
+- **Over the tunnel, tests run as they do on localhost.** They started off there, and turned on
+  ran only the page on screen; the dev server now marks the pages it serves, so any page it
+  served starts with tests on and runs the whole site in the background. That is every visitor
+  to a dev server, on the LAN or through a tunnel link, with or without an edit session: a
+  preview link opened on a phone runs every page's tests in hidden frames. Turning tests off
+  from the header menu is remembered per browser. A deployed site has no mark and still
+  defaults to off.
+- **A pass no longer blanks the header's test widget.** It faded to nothing and left an empty
+  rectangle in the bar. It now turns grey and then translucent, all as a CSS filter over the
+  pass colour, and stays readable and clickable. Floating over a page with no header it still
+  fades out.
+
+## 1.16.36
+
+One additive site option. Nothing changes for a site that does not set it.
+
+- **A page can be served at a second path (#3513).** `aliases: { readme: '' }` in the site
+  config also writes the root page to `/readme/`, with its stylesheet, bundle and `docs.json`
+  references worked out for that depth, and the browser opens it as the README. Before this a
+  host rewrite was the only way, and it served the page one level down with every relative
+  reference 404ing, so the page rendered but never hydrated. An alias page's canonical link
+  names the page's own path, aliases stay out of the sitemap and the nav, and relative images
+  and links in the page are rewritten to reach the same files. An alias is one lowercase path
+  segment with no dot; the build fails on one that is not, that takes a page's own path or a
+  static folder's, or that names no page.
+
 ## 1.16.35
 
 Board follow-ups from 1.16.32 and 1.16.33, plus one tunnel feature. Nothing to change in an

package/dist/doc-browser.d.ts

@@ -102,6 +102,11 @@ export interface DocBrowserOptions {
      * doc). Lets a host mount the browser already pointed at a specific doc.
      */
     initialRoute?: string;
+    /**
+     * Path routing only: extra paths a doc is served at, `{ alias: slug }` (`''` is the root
+     * page). The site build passes its `aliases` here, so `/readme/` opens the README.
+     */
+    aliases?: Record<string, string>;
     /**
      * Memory routing only: called with the current doc's slug whenever in-app
      * navigation happens, so a host can reflect it (e.g. to an attribute).

package/dist/doc-browser.js

@@ -119,6 +119,7 @@ import { popMenu } from './menu.js';
 import { codeEditor } from './code-editor.js';
 import { tosiDiff } from './diff.js';
 import { LAN_REFUSAL_ADVICE } from './live-example/source-access.js';
+import { servedForDevelopment } from './live-example/dev-served.js';
 /*
 Does this doc contain a REAL ` ```test ` block, as opposed to mentioning one?
 
@@ -186,6 +187,18 @@ const testIndicatorStyleSpec = {
         '70%': { opacity: '1', transform: 'scale(1.1)' },
         '100%': { opacity: '0', transform: 'scale(0.9)', pointerEvents: 'none' },
     },
+    /*
+    A pass in the header settles into a muted, monochrome badge rather than fading out. Faded,
+    it left an empty rectangle in the bar (the widget keeps its box), and the result was gone
+    for anyone who looked a moment late. Muted, it reads as "nothing to see" and stays a button.
+    All of it is a filter over the pass colour, never a new colour. Grey first, then faded: fading
+    while still green put a washed-out green on the header's colour.
+    */
+    '@keyframes test-settle': {
+        '0%, 40%': { filter: 'grayscale(0) opacity(1)' },
+        '55%': { filter: 'grayscale(1) opacity(1)' },
+        '100%': { filter: 'grayscale(1) opacity(0.55)' },
+    },
     // Hide when tests disabled
     'body:not(.tests-enabled) .doc-link::after, body:not(.tests-enabled) .test-widget': {
         display: 'none !important',
@@ -240,8 +253,19 @@ const testIndicatorStyleSpec = {
     '.test-widget.-passed': {
         _testBg: testColor.pass,
         _testFg: testTextColor.pass,
+        animation: 'test-settle 3s ease-out forwards',
+    },
+    // Floating over the page (no header), it still gets out of the way: there is no gap to leave.
+    '.test-widget.-floating.-passed': {
         animation: 'test-fade 3s ease-out forwards',
     },
+    '@media (prefers-reduced-motion: reduce)': {
+        '.test-widget.-passed': {
+            animation: 'none',
+            filter: 'grayscale(1) opacity(0.55)',
+        },
+        '.test-widget.-floating.-passed': { opacity: '0', pointerEvents: 'none' },
+    },
     '.test-widget.-failed': {
         _testBg: testColor.fail,
         _testFg: testTextColor.fail,
@@ -354,7 +378,7 @@ const logoMarkStyleSpec = {
 // tosi() registry key (see stateKey below) and two browsers can't share state.
 let docBrowserSeq = 0;
 export function createDocBrowser(options) {
-    const { docs, context = {}, projectName = '', projectLinks = {}, logo, navSize = 200, minSize = 600, routing = 'query', initialRoute, onRouteChange, searchShortcut = 'mod+k', navbarLinks, contentElement, } = options;
+    const { docs, context = {}, projectName = '', projectLinks = {}, logo, navSize = 200, minSize = 600, routing = 'query', initialRoute, aliases = {}, onRouteChange, searchShortcut = 'mod+k', navbarLinks, contentElement, } = options;
     // Memory routing is fully self-contained: it never reads or writes
     // window.history/location, so an embedded or nested browser can't hijack the
     // host page's URL (or recurse into it).
@@ -381,7 +405,7 @@ export function createDocBrowser(options) {
         if (memoryRouting)
             return initialRoute ? filenameForSlug(initialRoute) : '';
         return routing === 'path'
-            ? filenameForPath(document.location.pathname, slugMap)
+            ? filenameForPath(document.location.pathname, slugMap, aliases)
             : document.location.search !== ''
                 ? document.location.search.substring(1).split('&')[0]
                 : '';
@@ -414,7 +438,7 @@ export function createDocBrowser(options) {
         }
         // Clean `/slug/` path form (only meaningful when slugs are in play).
         if (!memoryRouting && routing !== 'query') {
-            const filename = known(filenameForPath(url.pathname, slugMap));
+            const filename = known(filenameForPath(url.pathname, slugMap, aliases));
             if (filename)
                 return filename;
         }
@@ -1762,7 +1786,7 @@ export function createDocBrowser(options) {
             else {
                 testWidget.classList.add('-passed');
                 testWidget.classList.remove('-failed');
-                testWidget.hidden = false; // Show briefly before fade
+                testWidget.hidden = false; // settles into a muted badge (see `.test-widget.-passed`)
             }
         }
         updateTestWidgetDisplay();
@@ -1938,9 +1962,15 @@ export function createDocBrowser(options) {
         const currentFilename = String(app.currentDoc.filename);
         /*
         Create a hidden iframe that loads the full page. Keep a real layout size — layout-dependent
-        example tests need one — but park it off-screen rather than rely on opacity:0 over the
-        visible page: Chromium (and haltija on top of it) still composites a 0-opacity layer at 0,0,
-        which flashes as the frame navigates page to page.
+        example tests need one — and hide it with a clip that leaves nothing to paint, not opacity:
+        Chromium (and haltija on top of it) still composites a 0-opacity layer at 0,0, which flashes
+        as the frame navigates page to page.
+    
+        INSIDE the viewport, though. It used to be parked at left:-10000px, and WebKit throttles a
+        frame outside the viewport: its animation frames never came, tosijs renders on animation
+        frames, so every page sat until its 45s deadline and Safari showed "Running 0" for the whole
+        run. That was the "WebKit's iframe runner never signals" of the e2e lane, and it reached
+        readers once the tunnel ran tests in the background.
     
         THE SIZE IS OVERRIDABLE, because 800x600 was the only width the inline tier had ever run at.
         A doc-system layout regression at phone width shipped in 1.12.3 and was found by a reader,
@@ -1959,7 +1989,7 @@ export function createDocBrowser(options) {
         const vpWidth = Number(vp?.width) > 0 ? Number(vp?.width) : 800;
         const vpHeight = Number(vp?.height) > 0 ? Number(vp?.height) : 600;
         const testFrame = document.createElement('iframe');
-        testFrame.style.cssText = `position: fixed; left: -10000px; top: 0; width: ${vpWidth}px; height: ${vpHeight}px; opacity: 0; pointer-events: none;`;
+        testFrame.style.cssText = `position: fixed; left: 0; top: 0; z-index: -1; clip-path: inset(100%); width: ${vpWidth}px; height: ${vpHeight}px; opacity: 0; pointer-events: none;`;
         document.body.appendChild(testFrame);
         // Listen for test results posted from the iframe
         const messageHandler = (event) => {
@@ -2032,11 +2062,12 @@ export function createDocBrowser(options) {
             void settleCurrentPage(currentFilename);
         }
     };
-    // Run background tests when enabled (initially or when toggled on)
+    // Run background tests when enabled (initially or when toggled on). Every page where a
+    // developer is looking, the tunnel included; elsewhere only the page on screen.
     const startBackgroundTests = () => {
         if (!testManager.enabled.value)
             return;
-        if (isLocalhost) {
+        if (servedForDevelopment()) {
             setTimeout(runBackgroundTests, 1000);
         }
         else {

package/dist/doc-system/doc-system.d.ts

@@ -48,6 +48,8 @@ export declare class TosiDocSystem extends TosiDocSystem_base {
     private initPrefs;
     private initLocale;
     private settingsButton;
+    /** The site's `aliases`, which the build writes into the config attribute (board #3513). */
+    private configAliases;
     private parseLinks;
     connectedCallback(): void;
     render(): void;

package/dist/doc-system/doc-system.js

@@ -485,6 +485,16 @@ export class TosiDocSystem extends withAttributes({
     // ---- Lifecycle -----------------------------------------------------------
     // Parse a declarative <ul class="..."> of <li><a href data-icon?>label</a> into
     // LinkItem[]. Returns [] when the list is absent.
+    /** The site's `aliases`, which the build writes into the config attribute (board #3513). */
+    configAliases() {
+        try {
+            const { aliases } = JSON.parse(this.config || '{}');
+            return aliases && typeof aliases === 'object' ? aliases : undefined;
+        }
+        catch {
+            return undefined;
+        }
+    }
     parseLinks(selector) {
         const list = this.querySelector(selector);
         if (!list)
@@ -570,6 +580,7 @@ export class TosiDocSystem extends withAttributes({
         this.browser = createDocBrowser({
             docs: this.corpus,
             routing: memory ? 'memory' : 'path',
+            aliases: memory ? undefined : this.configAliases(),
             initialRoute: memory ? this.route || undefined : undefined,
             onRouteChange: memory
                 ? (slug) => {

package/dist/doc-system/routing.d.ts

@@ -55,8 +55,21 @@ export declare function slugForPath(pathname: string): string;
 /**
  * Resolve a browser location.pathname to a doc filename, using a slug map.
  * Returns '' if nothing matches (caller falls back to the first/README doc).
+ *
+ * `aliases` ({ alias path -> slug }, the site config's `aliases`) are a doc's extra paths: a
+ * page's own slug wins, so an alias never takes a path from a page.
+ */
+export declare function filenameForPath(pathname: string, slugMap: Record<string, string>, aliases?: Record<string, string>): string;
+/**
+ * Check a site's `aliases` against its slug map, and return the problems in words (empty when
+ * there are none). An alias is one lowercase path segment with no dot, takes no page's own
+ * path, and names a page.
+ *
+ * Lowercase because on a case-insensitive filesystem (macOS, Windows) writing `Guide/` replaces
+ * `guide/`, and a crawler at `/guide/` then got another page. No dot because every file the
+ * build writes at the root has one (`docs.json`, `sitemap.xml`, `llms.txt`).
  */
-export declare function filenameForPath(pathname: string, slugMap: Record<string, string>): string;
+export declare function aliasProblems(aliases: Record<string, string>, slugMap: Record<string, string>): string[];
 /** Turn a human name/title into a slug: 'Form Components' -> 'form-components'. */
 export declare function slugify(s: string): string;
 /**

package/dist/doc-system/routing.js

@@ -133,14 +133,47 @@ export function slugForPath(pathname) {
 /**
  * Resolve a browser location.pathname to a doc filename, using a slug map.
  * Returns '' if nothing matches (caller falls back to the first/README doc).
+ *
+ * `aliases` ({ alias path -> slug }, the site config's `aliases`) are a doc's extra paths: a
+ * page's own slug wins, so an alias never takes a path from a page.
  */
-export function filenameForPath(pathname, slugMap) {
+export function filenameForPath(pathname, slugMap, aliases = {}) {
     const slug = slugForPath(pathname);
-    for (const [filename, docSlug] of Object.entries(slugMap)) {
-        if (docSlug === slug)
-            return filename;
+    const find = (wanted) => {
+        for (const [filename, docSlug] of Object.entries(slugMap)) {
+            if (docSlug === wanted)
+                return filename;
+        }
+        return '';
+    };
+    const own = find(slug);
+    return own || (Object.hasOwn(aliases, slug) ? find(aliases[slug]) : '');
+}
+/**
+ * Check a site's `aliases` against its slug map, and return the problems in words (empty when
+ * there are none). An alias is one lowercase path segment with no dot, takes no page's own
+ * path, and names a page.
+ *
+ * Lowercase because on a case-insensitive filesystem (macOS, Windows) writing `Guide/` replaces
+ * `guide/`, and a crawler at `/guide/` then got another page. No dot because every file the
+ * build writes at the root has one (`docs.json`, `sitemap.xml`, `llms.txt`).
+ */
+export function aliasProblems(aliases, slugMap) {
+    const slugs = new Set(Object.values(slugMap));
+    const folded = new Set([...slugs].map((s) => s.toLowerCase()));
+    const problems = [];
+    for (const [alias, target] of Object.entries(aliases)) {
+        if (!/^[a-z0-9][a-z0-9_-]*$/.test(alias)) {
+            problems.push(`"${alias}" is not one lowercase path segment (a-z, 0-9, "_", "-")`);
+        }
+        else if (folded.has(alias)) {
+            problems.push(`"${alias}" is already a page's own path`);
+        }
+        if (!slugs.has(target)) {
+            problems.push(`"${alias}" names "${target}", which is no page's slug ('' is the root page)`);
+        }
     }
-    return '';
+    return problems;
 }
 /** Turn a human name/title into a slug: 'Form Components' -> 'form-components'. */
 export function slugify(s) {

package/dist/doc-system/site/dev-server.d.ts

@@ -31,6 +31,11 @@ import { isLoopbackAddressForAuth as isLoopbackAddress } from './dev-auth.js';
  *
  * `root + sep` rather than a bare `startsWith`, or `/srv/docs-evil` counts as inside `/srv/docs`.
  */
+/**
+ * Put `snippet` before every script in `html`: just inside `<head>`, or else just after the
+ * doctype. Never before the doctype, which would put the page in quirks mode.
+ */
+export declare function injectFirst(html: string, snippet: string): string;
 export declare function isUnderRoot(root: string, candidate: string): boolean;
 export declare function resolveWatchPaths(config: {
     docPaths?: string[];

package/dist/doc-system/site/dev-server.js

@@ -28,6 +28,7 @@ import { assertSecretNotServed, ensureSessionSecret, readSessionSecret, sessionS
 import { revocationList, startRevocationSweep } from './device-revocation.js';
 import { resolveDataStore, resolveDataFile, dataContentProblem, listDataFiles, saveDataFile, dataHistory, readDataAt, isGitWorkTree, } from './data-store.js';
 import { SOURCE_ACCESS_HEADER, SOURCE_ENDPOINT_SNIPPET, } from '../../live-example/source-access.js';
+import { DEV_SERVER_SNIPPET } from '../../live-example/dev-served.js';
 /**
  * Every path the dev server watches for changes.
  *
@@ -59,6 +60,20 @@ import { SOURCE_ACCESS_HEADER, SOURCE_ENDPOINT_SNIPPET, } from '../../live-examp
  *
  * `root + sep` rather than a bare `startsWith`, or `/srv/docs-evil` counts as inside `/srv/docs`.
  */
+/**
+ * Put `snippet` before every script in `html`: just inside `<head>`, or else just after the
+ * doctype. Never before the doctype, which would put the page in quirks mode.
+ */
+export function injectFirst(html, snippet) {
+    const head = /<head(\s[^>]*)?>/i.exec(html);
+    if (head) {
+        const at = head.index + head[0].length;
+        return html.slice(0, at) + snippet + html.slice(at);
+    }
+    const doctype = /^\s*<!doctype[^>]*>/i.exec(html);
+    const at = doctype ? doctype[0].length : 0;
+    return html.slice(0, at) + snippet + html.slice(at);
+}
 export function isUnderRoot(root, candidate) {
     const base = path.resolve(root);
     const target = path.resolve(candidate);
@@ -1373,12 +1388,19 @@ export async function devServer(config, opts = {}) {
             // deployed static site, which has none, is never asked.
             (config.editableSources ? SOURCE_ENDPOINT_SNIPPET : '');
         const encoding = negotiateEncoding(request?.headers.get('accept-encoding') ?? null);
-        if ((extras || asRoot) && filePath.endsWith('.html')) {
+        if (filePath.endsWith('.html')) {
             const read = await Bun.file(filePath).text();
             const html = asRoot ? rootRelativeUrls(read) : read;
-            const injected = html.includes('</body>')
+            const withExtras = html.includes('</body>')
                 ? html.replace('</body>', `${extras}</body>`)
                 : html + extras;
+            /*
+            Tests on by default, every page, for whoever is looking through the dev server (the tunnel
+            included); see dev-served.ts. FIRST in <head>, unlike the extras: it is read when the
+            bundle evaluates, and on the iife path that is a classic script, which runs as it is
+            parsed, before anything at the end of <body> exists.
+            */
+            const injected = injectFirst(withExtras, DEV_SERVER_SNIPPET);
             // Injected HTML is built per request, so it is compressed but never cached — the
             // cache key would have to include the injected extras, and HTML is small anyway.
             const body = encoding

package/dist/doc-system/site/generate-site.d.ts

@@ -6,6 +6,8 @@ declare global {
 }
 export interface GenerateSiteConfig {
     docs: Doc[];
+    /** `SiteConfig.aliases`: { alias path -> slug } (board #3513) */
+    aliases?: Record<string, string>;
     /**
      * Mirrors `SiteConfig.liveExamples`. The static highlighter needs it so it skips the
      * fences that will become live examples — a highlighted block hands the example markup
@@ -130,4 +132,10 @@ export declare function pageDepth(slug: string): number;
  */
 export declare function relativeUrl(depth: number, p: string): string;
 export declare function withStamp(url: string, stamp?: string): string;
+/**
+ * Rewrite the relative `href`/`src` references in rendered page HTML, written for a page at
+ * `fromPath` ('/' or '/slug/'), so they reach the same files from a page at `depth`. Rooted
+ * (`/x`), external, `#`, `?` and `data:`-style references are left alone.
+ */
+export declare function rebaseRelativeRefs(html: string, fromPath: string, depth: number): string;
 export declare function generateSite(config: GenerateSiteConfig): Promise<number>;

package/dist/doc-system/site/generate-site.js

@@ -12,10 +12,11 @@ component (src/doc-system/*) so static and hydrated output agree.
 */
 import { pageTitle } from '../doc-title.js';
 import { highlightHtml } from '../highlight.js';
-import { buildSlugMap, pathForSlug, rewriteDocLinks, withBase, wikilinkTargets, } from '../routing.js';
+import { aliasProblems, buildSlugMap, pathForSlug, rewriteDocLinks, withBase, wikilinkTargets, } from '../routing.js';
 import { buildNavTree, navOpenPath } from '../nav-tree.js';
 import { renderDocMarkdown, docDescription, } from '../render.js';
 import { bareNameLinks, deadInPageAnchors, missingWikilinks, misconfigured, } from './build-warnings.js';
+import { existsSync } from 'fs';
 const escapeAttr = (s) => s
     .replace(/&/g, '&')
     .replace(/</g, '&lt;')
@@ -111,11 +112,14 @@ export function relativeUrl(depth, p) {
     const rel = '../'.repeat(depth) + p.slice(1);
     return rel === '' ? './' : rel;
 }
-async function pageHtml(doc, config, slugMap, configAttr, wikilinks) {
+async function pageHtml(doc, config, slugMap, configAttr, wikilinks, 
+/** the slug this copy is written at: the doc's own, or an alias of it */
+at = slugMap[doc.filename] ?? '') {
     const { projectName = '', baseUrl = '', lang = 'en', favicon = '/favicon.svg', docsUrl = '/docs.json', scriptUrl = '/iife.js', hydrateUrl, stylesUrl = '/doc-system.css', assetStamp, docsStamp, localizedUrl = '/localized-strings.txt', basePath, headExtra = '', bakes, } = config;
     // Functional URLs are emitted relative to THIS page's depth so the build is
     // mount-agnostic (issue #25); metadata URLs below stay absolute via withBase.
-    const depth = pageDepth(slugMap[doc.filename] ?? '');
+    const depth = pageDepth(at);
+    const own = slugMap[doc.filename] ?? '';
     const localizedAttr = config.localizedStrings
         ? ` localized="${escapeAttr(relativeUrl(depth, localizedUrl))}"`
         : '';
@@ -142,7 +146,7 @@ async function pageHtml(doc, config, slugMap, configAttr, wikilinks) {
     // Rewrite legacy `?filename` content links to clean `/slug/` paths so the
     // static HTML is correct for no-JS readers and crawlers (the doc-browser also
     // does this client-side after hydration).
-    const body = rewriteDocLinks(await highlightHtml(renderDocMarkdown(doc.text, {
+    const rendered = rewriteDocLinks(await highlightHtml(renderDocMarkdown(doc.text, {
         bakes: bakes?.get(doc.filename),
         wikilinks,
     }), 
@@ -151,6 +155,11 @@ async function pageHtml(doc, config, slugMap, configAttr, wikilinks) {
     config.liveExamples ?? 'auto'), (filename) => slugMap[filename] !== undefined
         ? relativeUrl(depth, pathForSlug(slugMap[filename]))
         : null);
+    // A copy at an alias: what the author wrote relative to the page's own path must still reach
+    // the same file (a README's `img/logo.png` is /img/logo.png, not /readme/img/logo.png).
+    const body = at === own
+        ? rendered
+        : rebaseRelativeRefs(rendered, pathForSlug(own), depth);
     const nav = navHtml(config.docs, slugMap, doc.filename, depth);
     const navbar = linkListHtml('doc-navbar', config.navbarLinks);
     const jsonLd = baseUrl
@@ -289,6 +298,19 @@ export function withStamp(url, stamp) {
         return url;
     return `${url}?v=${encodeURIComponent(stamp)}`;
 }
+/**
+ * Rewrite the relative `href`/`src` references in rendered page HTML, written for a page at
+ * `fromPath` ('/' or '/slug/'), so they reach the same files from a page at `depth`. Rooted
+ * (`/x`), external, `#`, `?` and `data:`-style references are left alone.
+ */
+export function rebaseRelativeRefs(html, fromPath, depth) {
+    return html.replace(/(\s(?:href|src|poster)=")([^"]*)"/g, (match, attr, ref) => {
+        if (!ref || /^(?:[a-z][a-z0-9+.-]*:|\/|#|\?)/i.test(ref))
+            return match;
+        const rooted = new URL(ref, `https://x${fromPath}`);
+        return `${attr}${relativeUrl(depth, rooted.pathname + rooted.search + rooted.hash)}"`;
+    });
+}
 export async function generateSite(config) {
     const { docs, outputDir } = config;
     const slugMap = buildSlugMap(docs);
@@ -303,8 +325,19 @@ export async function generateSite(config) {
         }
         seen.set(slug, doc.filename);
     }
+    // A wrong alias fails the build like a `home` that names no page: it is a typo or a
+    // renamed page, and a site with a dead path is not one to ship quietly.
+    const aliases = config.aliases ?? {};
+    const problems = aliasProblems(aliases, slugMap);
+    if (problems.length) {
+        throw new Error(`generate-site: aliases are wrong:\n${problems
+            .map((p) => `    ${p}`)
+            .join('\n')}`);
+    }
     const configAttr = escapeAttr(JSON.stringify({
         projectName: config.projectName,
+        // The browser needs them too, or an alias page hydrates as whichever doc comes first.
+        ...(Object.keys(aliases).length ? { aliases } : {}),
         projectLinks: config.projectLinks,
         logo: config.logo,
         bookVolumes: config.bookVolumes,
@@ -341,6 +374,26 @@ export async function generateSite(config) {
         }
         count += 1;
     }
+    /*
+    Each alias is the page again, written where the alias is served, so its relative references
+    (stylesheet, bundle, docs.json, nav links) resolve from there. A host rewrite to the original
+    page cannot do that: it serves the same bytes at a different depth and the page never
+    hydrates (board #3513). The canonical link stays the page's own path.
+    */
+    for (const [alias, target] of Object.entries(aliases)) {
+        const doc = docs.find((d) => slugMap[d.filename] === target);
+        const dir = `${outputDir}/${alias}`;
+        // The output folder starts empty, so anything already here is a static file or folder, or
+        // one the build wrote (`tjs/`, `_chunks/`): an alias must not write into it.
+        if (existsSync(dir)) {
+            throw new Error(`generate-site: the alias "${alias}" names /${alias}/, which the site already has ` +
+                `(a static file or folder, or one the build writes); choose another name`);
+        }
+        await Bun.write(`${dir}/index.html`, await pageHtml(doc, config, slugMap, configAttr, wikilinks, alias));
+        if (hasMarkdownPage(doc, config)) {
+            await Bun.write(`${dir}/index.md`, doc.text.trimEnd() + '\n');
+        }
+    }
     if (danglingWikilinks.length) {
         misconfigured(config.strict, `\n⚠️  Wikilinks that reach no doc page. A target matches a page's slug (its file name)\n` +
             `    or its title; write [[slug|label]] to link one by file name, and an ordinary\n` +

package/dist/doc-system/site/orchestrator.js

@@ -1491,6 +1491,7 @@ export async function buildSite(config, opts = {}) {
             const pageCount = await generateSite({
                 liveExamples: config.liveExamples,
                 docs,
+                aliases: config.aliases,
                 outputDir: PUBLIC,
                 projectName: config.name,
                 bookVolumes: printCoverManifestUrl(config),

package/dist/doc-system/site/site-config.d.ts

@@ -61,6 +61,16 @@ export interface SiteConfig {
      * names no page. A doc can also claim the root itself with `{"home": true}`.
      */
     home?: string;
+    /**
+     * Extra paths a page is served at, as `{ alias: slug }`; `''` is the root page. With
+     * `aliases: { readme: '' }` the README (the root page) is also written to `/readme/`, with its
+     * stylesheet, bundle and `docs.json` references computed for that depth, and the browser
+     * opens it as the README. Each alias page's canonical link names the page's own path, and
+     * aliases stay out of the sitemap and the nav; relative references in the page are rewritten
+     * to reach the same files. An alias is one lowercase path segment with no dot; the build fails
+     * on one that is not, that takes a page's own path or a static folder's, or that names no page.
+     */
+    aliases?: Record<string, string>;
     /**
      * Directories to skip while scanning `docPaths` — by basename (skipped wherever it
      * appears) or by path (skipped only at that location). Added to the built-in