tosijs-ui 1.17.1 → 1.17.3

package/CHANGELOG.md

@@ -1,5 +1,79 @@
 # Changelog
 
+## 1.17.3
+
+> A doc site answers `/slug` as well as `/slug/`, and a missing page gets a real 404 page.
+> Nothing to change on upgrade. On Firebase, add `"cleanUrls": true` to `firebase.json` for
+> `/slug` to serve the page; GitHub Pages, Netlify and Cloudflare Pages need nothing.
+
+### Added
+
+- Every page (and alias) is also written as `/slug.html`, with its references written for
+  `/slug`, so a host that resolves extensionless paths (GitHub Pages, Netlify, Cloudflare
+  Pages, Firebase with `cleanUrls`) answers `/slug` with the page instead of a redirect. An
+  agent's fetch tool that does not follow redirects got a "moved" stub at
+  virta.tosijs.net/start. The canonical link stays `/slug/`; a file the site already has at
+  `/slug.html` is left alone and named in a warning.
+- The build writes `404.html` (unless the site ships its own): it names the path asked for,
+  suggests the closest page, lists every page and links `llms.txt`. Every link in it is
+  absolute, since hosts serve it at whatever URL was asked for.
+
+### Fixed
+
+- After Cmd-K, the doc site's search field sat on top of a maximized live example. Opening the
+  palette raised the whole `<tosi-palette>` (its trigger included) to the page's highest
+  z-index and never put it back, and any overlay on the page (haltija's widget on a dev
+  server, a toast in an app) made that higher than the example's. The dialog never needed it:
+  `showModal()` already puts it in the top layer.
+- The dev server served `/slug` from `slug/index.html`, whose references are written for
+  `/slug/`; it now serves `slug.html`. (Its `.html` fallback looked for `slug/.html` and never
+  matched.)
+- The live-theme page showed two theme editors: its example had an `html` block and a `js`
+  block that each made one.
+
+## 1.17.2
+
+> Components carry only the icons they draw, and `<tosi-affix>` centres a caption on its
+> content. Nothing to change on upgrade. An app that imports components one at a time ships
+> about 20 kB gzip less per component; **`dist/iife.js` grows 1.8 kB** (508.0 kB gzip),
+> because the whole set is now assembled from per-icon modules.
+
+### Added
+
+- `tosijs-ui/icons/<name>` exports one icon as a function, the same one `icons.name` gives:
+  `import { chevronDown } from 'tosijs-ui/icons/chevronDown'`. Each module registers its icon
+  once however many modules import it, and imports any icon it is drawn from (`chevronDown`
+  brings `chevronRight`), so a bundler keeps only the icons something imports. `delete` and
+  `package` export `deleteIcon` and `packageIcon`.
+- `tosijs-make-icons` gains `--modules <dir>` (one string module per icon, plus an index whose
+  default is the whole set), `--creators <dir>` (one creator module per icon) and
+  `--core <specifier>` (where creators import `iconCreator` from; default
+  `tosijs-ui/icon-core`).
+
+### Changed
+
+- Components import only the icons they draw, not all 320. Measured gzip, each imported alone:
+  `tosiTag` 4.4 kB, `tosiCarousel` 6.2 kB (was 23.8), menu 13.9 kB (was 34.2), select 13.7
+  (34.0), tabs 15.1 (35.4), month 15.9 (36.1), table 29.1 (48.9), rating 5.0 (25.5). Importing
+  `tosijs-ui` itself still brings the whole set, so nothing changes for an app that does.
+- An icon a caller names (a menu item's `icon: 'folder'`, a select option's, a rating's) still
+  draws. On a page that has not loaded the whole set it appears a moment late, like a web font,
+  while the set loads. Import the icon's module, pass the icon itself where an element is
+  accepted (`icon: folder()`), or import `tosijs-ui/icons` up front, to draw it at once.
+
+### Fixed
+
+- `<tosi-affix>`: a centred caption is centred on its content, not on the content's cell. A
+  fixture wider than fixed-width content (the doc page's own "a caption, centred below")
+  widened the content's column, and the content sat at its start; the same happened in any
+  affix wider than its content, where an `ne` or `e` fixture also stood off the content's edge.
+  The content now takes the fixture's alignment with auto margins, which leave content that
+  fills its cell untouched.
+- `tosijs-ui/icons/data/<name>` shipped stale icons: the per-icon modules were written once in
+  1.4.1 and never regenerated, so 54 of 313 differed from the icons actually drawn (including
+  1.17.0's open-path fix) and six (`fatArrowDown/Left/Right/Up`, `pin`, `shift`) had no module.
+  The build now writes them from the same data, and a test fails if they drift.
+
 ## 1.17.1
 
 > Fixes from the 1.17.0 review, plus elastic table columns that can be dragged narrower. Nothing

package/bin/make-icon-data.js

@@ -16,6 +16,15 @@ Ingests SVG files from icon directories and generates an icon-data module
 - `--input <dir1,dir2,...>` — directories to scan (default: `./icons`)
 - `--output <path>` — output file (default: `./src/icon-data.ts`)
 - `--optimize <true|false>` — round coordinates based on viewBox size (default: true)
+- `--modules <dir>` — also write one module per icon into `dir` (`export const name = '…'`),
+  plus an `index`, so code can import just the icons it draws. tosijs-ui's own build writes
+  `src/icons/data/` this way; files there that are no longer icons are removed.
+- `--creators <dir>` — with `--modules`, also write one module per icon that exports it as a
+  function, `export const chevronDown = iconCreator(…)`, registering it once when it loads.
+  A redirect's module imports the icon it redirects to. tosijs-ui's own build writes
+  `src/icons/` this way, published as `tosijs-ui/icons/<name>`.
+- `--core <specifier>` — where `--creators` modules import `iconCreator` from (default
+  `tosijs-ui/icon-core`)
 
 ### Examples
 
@@ -99,6 +108,9 @@ const defaultOptions = {
   input: './icons',
   output: './src/icon-data.ts',
   optimize: true, // Optimize coordinate precision based on viewBox size
+  modules: '', // A directory to also write one module per icon into
+  creators: '', // A directory to also write one creator module per icon into
+  core: 'tosijs-ui/icon-core', // Where creator modules import iconCreator from
 }
 const flags = Object.keys(defaultOptions)
 
@@ -128,7 +140,14 @@ for (const flag of flags) {
 }
 
 // Destructure options for easier use
-const { input: iconDirectories, output: outputFilePath, optimize } = options
+const {
+  input: iconDirectories,
+  output: outputFilePath,
+  optimize,
+  modules: modulesDir,
+  creators: creatorsDir,
+  core: coreSpecifier,
+} = options
 const isTypescript = outputFilePath.endsWith('.ts')
 const shouldOptimize = optimize === true || optimize === 'true'
 
@@ -484,4 +503,151 @@ try {
 
 fs.writeFileSync(outputFilePath, source, 'utf8')
 
+/*
+One module per icon, so a component can import the handful it draws instead of all of them
+(tosijs-ui#3885). They are written from the same data in the same run, so they cannot drift
+from the combined module: the 1.4.1 copies were written once, by hand, and by 1.17 a sixth of
+them were wrong. A redirect's module holds the redirect, not its target; whoever registers
+it registers the target too.
+
+Files in the directory that are not icons any more are removed, but only ones this generator
+writes (a module that starts `export const` or an index of `export {` lines), so a stray file
+of someone else's survives.
+*/
+if (typeof modulesDir === 'string' && modulesDir !== '') {
+  const ext = isTypescript ? '.ts' : '.js'
+  fs.mkdirSync(modulesDir, { recursive: true })
+  /*
+  The export is the icon's name, unless that is not a name a module can bind: `delete` and (in
+  a module) `package` look like identifiers and are reserved, so they export `deleteIcon` and
+  `packageIcon` from `delete` and `package`, as the 1.4.1 modules did. Ask the parser, not a
+  pattern.
+  */
+  const bindable = (name) => {
+    try {
+      new Function(`"use strict"; let ${name}`)
+      return true
+    } catch {
+      return false
+    }
+  }
+  const valid = (name) => /^[A-Za-z_$][\w$]*$/.test(name)
+  const names = Object.keys(iconData).filter(valid)
+  const exportName = (name) => (bindable(name) ? name : name + 'Icon')
+  const skipped = Object.keys(iconData).filter((name) => !valid(name))
+  if (skipped.length > 0) {
+    console.warn(
+      `make-icon-data: no module for ${skipped.join(', ')} (not an identifier)`
+    )
+  }
+  const wanted = new Set([...names.map((n) => n + ext), 'index' + ext])
+  for (const file of fs.readdirSync(modulesDir)) {
+    if (wanted.has(file) || !file.endsWith(ext)) continue
+    const full = path.join(modulesDir, file)
+    const head = fs.readFileSync(full, 'utf8').slice(0, 13)
+    if (head.startsWith('export const') || head.startsWith('export {')) {
+      fs.rmSync(full)
+    }
+  }
+  for (const name of names) {
+    const file = path.join(modulesDir, name + ext)
+    const text = `export const ${exportName(name)} = ${JSON.stringify(
+      iconData[name]
+    )}\n`
+    if (!fs.existsSync(file) || fs.readFileSync(file, 'utf8') !== text) {
+      fs.writeFileSync(file, text, 'utf8')
+    }
+  }
+  /*
+  The index re-exports every icon by name and, as its default, the whole set keyed by icon
+  name (so `delete`, not `deleteIcon`). Code that needs every icon imports the default, which
+  is built from the same modules a component imports one at a time: one copy of each string in
+  a bundle that has both, not two.
+  */
+  const key = (n) => (/^[A-Za-z_$][\w$]*$/.test(n) ? n : quote(n))
+  fs.writeFileSync(
+    path.join(modulesDir, 'index' + ext),
+    names
+      .map((n) => `import { ${exportName(n)} } from './${n}.js'\n`)
+      .join('') +
+      `\nexport {\n${names.map((n) => `  ${exportName(n)},\n`).join('')}}\n` +
+      `\nexport default {\n${names
+        .map((n) =>
+          exportName(n) === n ? `  ${n},\n` : `  ${key(n)}: ${exportName(n)},\n`
+        )
+        .join('')}}\n`,
+    'utf8'
+  )
+  if (typeof creatorsDir === 'string' && creatorsDir !== '') {
+    writeCreators(creatorsDir, names, exportName, ext)
+  }
+}
+
 console.log(`Successfully generated icon data to: ${outputFilePath}`)
+
+/*
+A redirect draws another icon (`chevronDown` is `chevronRight90r`), so its creator module
+imports that icon's, and registering one registers what it needs. The icon a redirect draws
+is the longest icon name its value starts with, per `$`-stacked layer; a value that names no
+icon (a composition rule's) imports nothing and resolves the way any unregistered name does.
+*/
+function redirectTargets(name) {
+  const spec = iconData[name]
+  if (spec.startsWith('<')) return []
+  const targets = new Set()
+  for (const layer of spec.split('$')) {
+    let best = ''
+    for (const other of Object.keys(iconData)) {
+      if (
+        other !== name &&
+        layer.startsWith(other) &&
+        other.length > best.length
+      )
+        best = other
+    }
+    if (best) targets.add(best)
+  }
+  return [...targets]
+}
+
+function writeCreators(dir, names, exportName, ext) {
+  if (typeof modulesDir !== 'string' || modulesDir === '') {
+    throw new Error('make-icon-data: --creators needs --modules')
+  }
+  fs.mkdirSync(dir, { recursive: true })
+  let dataPath = path.relative(dir, modulesDir).split(path.sep).join('/')
+  if (!dataPath.startsWith('.')) dataPath = './' + dataPath
+  const named = new Set(names)
+  for (const name of names) {
+    const exported = exportName(name)
+    const lines = [
+      '// Generated by make-icon-data. One icon, registered when this module loads.',
+      `import { iconCreator } from ${quote(coreSpecifier)}`,
+      ...redirectTargets(name)
+        .filter((t) => named.has(t))
+        .map((t) => `import './${t}.js'`),
+      `import { ${exported} as spec } from '${dataPath}/${name}.js'`,
+      '',
+      `export const ${exported} = iconCreator(${quote(name)}, spec)`,
+      '',
+    ]
+    const file = path.join(dir, name + ext)
+    const text = lines.join('\n')
+    if (!fs.existsSync(file) || fs.readFileSync(file, 'utf8') !== text) {
+      fs.writeFileSync(file, text, 'utf8')
+    }
+  }
+  const wanted = new Set(names.map((n) => n + ext))
+  for (const file of fs.readdirSync(dir)) {
+    if (wanted.has(file) || !file.endsWith(ext)) continue
+    const full = path.join(dir, file)
+    if (!fs.statSync(full).isFile()) continue
+    if (
+      fs
+        .readFileSync(full, 'utf8')
+        .startsWith('// Generated by make-icon-data.')
+    ) {
+      fs.rmSync(full)
+    }
+  }
+}

package/dist/affix.d.ts

@@ -50,6 +50,12 @@ export declare class TosiAffix extends Component<AffixParts> {
             minHeight: string;
             position: string;
         };
+        ':host > [part="content"][data-align="center"]::slotted(*)': {
+            marginInline: string;
+        };
+        ':host > [part="content"][data-align="end"]::slotted(*)': {
+            marginInlineStart: string;
+        };
         ':host > [part="fixture"]': {
             display: string;
             flexDirection: string;

package/dist/affix.js

@@ -259,6 +259,17 @@ export class TosiAffix extends Component {
             // a positioned child of the content is placed against the content, not the fixture
             position: 'relative',
         },
+        /*
+        Content narrower than its cell — a fixed width in a wider affix, or under a fixture wider
+        than it — follows the fixture, so a centred caption is centred on the content and not on
+        the cell. Auto margins do nothing to content that fills its cell.
+        */
+        ':host > [part="content"][data-align="center"]::slotted(*)': {
+            marginInline: 'auto',
+        },
+        ':host > [part="content"][data-align="end"]::slotted(*)': {
+            marginInlineStart: 'auto',
+        },
         ':host > [part="fixture"]': {
             display: 'flex',
             flexDirection: 'var(--tosi-affix-direction)',
@@ -436,6 +447,14 @@ export class TosiAffix extends Component {
             borderRadius: outerCorners(cell.edge, placement.inside, 'var(--tosi-affix-radius, var(--tosi-border-radius, 4px))'),
         });
         this.style.setProperty('--tosi-affix-direction', cell.direction);
+        // beside the content, it hugs the edge it is on; above, below or inside, it lines up with it
+        const side = cell.edge === 'e' || cell.edge === 'w';
+        this.parts.content.dataset.align =
+            side && !placement.inside
+                ? cell.edge === 'e'
+                    ? 'end'
+                    : 'start'
+                : cell.justifySelf;
     }
     render() {
         super.render();

package/dist/babylon-3d.js

@@ -223,7 +223,8 @@ be used to load `.glb` files. Setting `src` calls this for you on connect.
 /*{ "parent": "Components", "headTitle": "<tosi-3d> Babylon.js wrapper (deprecated) — tosijs-ui", "description": "Deprecated: <tosi-3d> is a thin Babylon.js wrapper kept for compatibility. New 3D work should use the tosijs-3d package." }*/
 import { elements, withAttributes } from 'tosijs';
 import { scriptTag } from './via-tag.js';
-import { icons, svg2DataUrl } from './icons.js';
+import { svg2DataUrl } from './icon-core.js';
+import { xrColor as xrColorIcon } from './icons/xrColor.js';
 const noop = () => {
     /* do not care */
 };
@@ -310,7 +311,7 @@ export class B3d extends withAttributes({
             width: 80,
             backgroundColor: 'transparent',
             filter: 'drop-shadow(0 0 4px #000c)',
-            backgroundImage: svg2DataUrl(icons.xrColor()),
+            backgroundImage: svg2DataUrl(xrColorIcon()),
             backgroundPosition: 'center',
             backgroundRepeat: 'no-repeat',
             border: 'none',

package/dist/carousel.js

@@ -72,7 +72,8 @@ This is a minimalist carousel component that supports the usual stuff.
 */
 /*{ "parent": "Components", "description": "A minimal carousel with optional arrows and dots, several items per page, looping, and auto-advance that holds still while someone is looking." }*/
 import { elements, vars, withAttributes } from 'tosijs';
-import { icons } from './icons.js';
+import { chevronLeft as chevronLeftIcon } from './icons/chevronLeft.js';
+import { chevronRight as chevronRightIcon } from './icons/chevronRight.js';
 import { prefersReducedMotion } from './reduced-motion.js';
 const { button, slot, div } = elements;
 export class TosiCarousel extends withAttributes({
@@ -382,12 +383,12 @@ export class TosiCarousel extends withAttributes({
         }
     }
     content = () => [
-        div({ part: 'pager' }, button({ title: 'previous slide', part: 'back' }, icons.chevronLeft()), div(
+        div({ part: 'pager' }, button({ title: 'previous slide', part: 'back' }, chevronLeftIcon()), div(
         /*
         Focusable, so the strip can be scrolled from the keyboard (#3573); ← and → page it,
         like the arrow buttons.
         */
-        { title: 'slides', role: 'group', part: 'scroller', tabindex: 0 }, div({ part: 'grid' }, slot())), button({ title: 'next slide', part: 'forward' }, icons.chevronRight())),
+        { title: 'slides', role: 'group', part: 'scroller', tabindex: 0 }, div({ part: 'grid' }, slot())), button({ title: 'next slide', part: 'forward' }, chevronRightIcon())),
         div({ title: 'choose slide to display', role: 'group', part: 'progress' }),
     ];
     connectedCallback() {

package/dist/data-table.js

@@ -1313,7 +1313,10 @@ import { elements, vars, varDefault, tosiValue, getListItem, getListBinding, tos
 import { trackDrag } from './track-drag.js';
 import { naturalSorter } from './natural-compare.js';
 import { resolveRowGroupId, withForcedGroups, clusterByGroup, groupRenderMeta, groupCounts, } from './row-grouping.js';
-import { icons } from './icons.js';
+import { chevronRight as chevronRightIcon } from './icons/chevronRight.js';
+import { sortAscending as sortAscendingIcon } from './icons/sortAscending.js';
+import { sortDescending as sortDescendingIcon } from './icons/sortDescending.js';
+import { moreVertical as moreVerticalIcon } from './icons/moreVertical.js';
 import { valueRenderer, } from './value-renderer.js';
 import { fieldForProperty, collectErrors, coerceToSchema, fieldEditable, } from './schema-form/fields.js';
 import { getSchemaValidator, warnNoValidator } from './schema-form/validator.js';
@@ -2827,7 +2830,7 @@ export class TosiTable extends withAttributes({
                     if (item != null)
                         this.toggleRowDetail(item);
                 },
-            }, icons.chevronRight()));
+            }, chevronRightIcon()));
             return cell;
         }
         if (this.columnEditable(col)) {
@@ -2949,12 +2952,12 @@ export class TosiTable extends withAttributes({
         let sortIcon;
         switch (col.sort) {
             case 'ascending':
-                sortIcon = icons.sortAscending();
+                sortIcon = sortAscendingIcon();
                 ariaSort = 'descending';
                 break;
             case 'descending':
                 ariaSort = 'ascending';
-                sortIcon = icons.sortDescending();
+                sortIcon = sortDescendingIcon();
                 break;
         }
         // An expander column has nothing to sort by and should not be hidden by accident.
@@ -2966,7 +2969,7 @@ export class TosiTable extends withAttributes({
                     popColumnMenu(event.target, col);
                     event.stopPropagation();
                 },
-            }, sortIcon || icons.moreVertical())
+            }, sortIcon || moreVerticalIcon())
             : {};
         const cell = col.headerCell !== undefined
             ? col.headerCell(col)

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

@@ -1228,10 +1228,15 @@ export async function devServer(config, opts = {}) {
         */
         if (!isUnderRoot(directory, basePath))
             return null;
-        const suffixes = ['', '.html', 'index.html'];
-        for (const suffix of suffixes) {
+        // `/slug` is the build's `slug.html` (written for that URL) before `slug/index.html`;
+        // `/slug/` is only ever the folder's index
+        const candidates = [
+            basePath,
+            ...(reqPath.endsWith('/') ? [] : [basePath + '.html']),
+            path.join(basePath, 'index.html'),
+        ];
+        for (const pathWithSuffix of candidates) {
             try {
-                const pathWithSuffix = path.join(basePath, suffix);
                 const stat = statSync(pathWithSuffix);
                 if (stat && stat.isFile()) {
                     return pathWithSuffix;

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

@@ -1,11 +1,14 @@
 import type { Doc } from './docs.js';
 import type { ProjectLinks, LinkItem } from '../../doc-browser.js';
+import { NavNode } from '../nav-tree.js';
 import { type AccessibilityMode, type ExampleBakes } from '../render.js';
 declare global {
     var Bun: any;
 }
 export interface GenerateSiteConfig {
     docs: Doc[];
+    /** whether the site serves `/llms.txt`, which the 404 page then points to */
+    llmsTxt?: boolean;
     /** `SiteConfig.aliases`: { alias path -> slug } (board #3513) */
     aliases?: Record<string, string>;
     /** `SiteConfig.searchPlaceholder` */
@@ -160,3 +163,4 @@ export declare function withStamp(url: string, stamp?: string): string;
  */
 export declare function rebaseRelativeRefs(html: string, fromPath: string, depth: number): string;
 export declare function generateSite(config: GenerateSiteConfig): Promise<number>;
+export declare function notFoundHtml(pages: NavNode<Doc>[], slugMap: Record<string, string>, config: Pick<GenerateSiteConfig, 'projectName' | 'basePath' | 'lang' | 'llmsTxt'>): string;

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

@@ -163,11 +163,12 @@ export function relativeUrl(depth, p) {
 }
 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] ?? '') {
+at = slugMap[doc.filename] ?? '', 
+/** the directory depth its references resolve from: 0 for the `/slug` copy (`slug.html`) */
+depth = pageDepth(at)) {
     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(at);
     const own = slugMap[doc.filename] ?? '';
     const localizedAttr = config.localizedStrings
         ? ` localized="${escapeAttr(relativeUrl(depth, localizedUrl))}"`
@@ -210,9 +211,10 @@ at = slugMap[doc.filename] ?? '') {
     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
+    // A copy anywhere but the page's own path (an alias, or `/slug` with no slash): what the
+    // author wrote relative to that 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 && depth === pageDepth(own)
         ? rendered
         : rebaseRelativeRefs(rendered, pathForSlug(own), depth);
     const nav = navHtml(config.docs, slugMap, doc.filename, depth);
@@ -562,6 +564,35 @@ export async function generateSite(config) {
             await Bun.write(`${dir}/index.md`, doc.text.trimEnd() + '\n');
         }
     }
+    /*
+    Every page again as `slug.html`, with its references written for `/slug`, so the trailing
+    slash is optional. Hosts serve `/slug` from `slug/index.html` with a redirect, and a client
+    that does not follow it (an agent's fetch tool, onboarding from a typed URL) got a "moved"
+    stub instead of the page. With `slug.html` beside it, a host that resolves extensionless
+    paths to `.html` (GitHub Pages, Netlify, Cloudflare Pages, Firebase with `cleanUrls`)
+    answers `/slug` with the page itself. The canonical link stays `/slug/`.
+    */
+    const slashless = [
+        ...docs.map((doc) => [slugMap[doc.filename], doc]),
+        ...Object.entries(aliases).map(([alias, target]) => [alias, docs.find((d) => slugMap[d.filename] === target)]),
+    ];
+    const occupied = [];
+    for (const [at, doc] of slashless) {
+        if (at === '')
+            continue;
+        const file = `${outputDir}/${at}.html`;
+        // the output folder starts empty, so a file here is one the site ships: leave it alone
+        if (existsSync(file)) {
+            occupied.push(`    /${at}.html`);
+            continue;
+        }
+        await Bun.write(file, await pageHtml(doc, config, slugMap, configAttr, wikilinks, at, 0));
+    }
+    if (occupied.length) {
+        console.warn(`\n⚠️  These pages are served only at /slug/, because the site already has a file where\n` +
+            `    the /slug copy goes (rename the file to make the trailing slash optional):\n` +
+            `${occupied.join('\n')}\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` +
@@ -631,5 +662,88 @@ export async function generateSite(config) {
             await Bun.write(robotsPath, `${base}Sitemap: ${config.baseUrl}/sitemap.xml\n`);
         }
     }
+    // A site's own 404.html (copied from its static files) wins.
+    if (!existsSync(`${outputDir}/404.html`)) {
+        await Bun.write(`${outputDir}/404.html`, notFoundHtml(flattenNav(buildNavTree(docs, slugMap)), slugMap, config));
+    }
     return count;
 }
+/*
+The page a host serves for a path the site does not have: GitHub Pages and Firebase serve
+`404.html` from the site root, at whatever URL was asked for, so nothing in it may be
+relative. It lists every page, which is what a reader without JavaScript (an agent's fetch
+tool, most often) needs to find its way, and with JavaScript it names the closest page to the
+path asked for. The script is a nicety: under a policy that blocks inline scripts, the list
+is still there.
+*/
+export function notFoundHtml(pages, slugMap, config) {
+    const { projectName = '', basePath, lang = 'en', llmsTxt } = config;
+    const href = (slug) => withBase(basePath, pathForSlug(slug));
+    const listed = pages.filter((node) => !node.doc.hidden);
+    const items = listed
+        .map((node) => `      <li><a href="${escapeAttr(href(node.slug))}">${escapeText(node.doc.title || node.slug || 'Home')}</a></li>`)
+        .join('\n');
+    const slugs = JSON.stringify(Object.values(slugMap).filter((slug) => slug !== '')).replace(/</g, '\\u003c');
+    const title = projectName
+        ? `Page not found — ${projectName}`
+        : 'Page not found';
+    return `<!DOCTYPE html>
+<html lang="${escapeAttr(lang)}">
+  <head>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+    <meta name="robots" content="noindex" />
+    <title>${escapeText(title)}</title>
+    <style>
+      body { font: 16px/1.5 system-ui, sans-serif; max-width: 40em; margin: 2em auto; padding: 0 1em; }
+      @media (prefers-color-scheme: dark) { body { background: #111; color: #eee; } a { color: #8bf; } }
+    </style>
+  </head>
+  <body>
+    <h1>Page not found</h1>
+    <p>There is no page at <code id="asked"></code> on this site.<span id="closest"></span></p>
+    <p><a href="${escapeAttr(withBase(basePath, '/'))}">Home</a>${llmsTxt
+        ? ` · <a href="${escapeAttr(withBase(basePath, '/llms.txt'))}">llms.txt</a> (every page, for agents)`
+        : ''}</p>
+    <h2>Pages</h2>
+    <ul>
+${items}
+    </ul>
+    <script>
+      ;(() => {
+        const slugs = ${slugs}
+        const base = ${JSON.stringify(withBase(basePath, '/'))}
+        const asked = decodeURIComponent(location.pathname)
+        document.getElementById('asked').textContent = asked
+        const want = asked.slice(base.length - 1).replace(/^\\/+|\\/+$/g, '').toLowerCase()
+        if (!want) return
+        const distance = (a, b) => {
+          const row = Array.from({ length: b.length + 1 }, (_, i) => i)
+          for (let i = 1; i <= a.length; i++) {
+            let prev = row[0]++
+            for (let j = 1; j <= b.length; j++) {
+              const next = Math.min(row[j] + 1, row[j - 1] + 1, prev + (a[i - 1] === b[j - 1] ? 0 : 1))
+              prev = row[j]
+              row[j] = next
+            }
+          }
+          return row[b.length]
+        }
+        let best = '', score = Infinity
+        for (const slug of slugs) {
+          const prefix = Math.min(want.length, slug.length) >= 3 && (slug.startsWith(want) || want.startsWith(slug))
+          const d = prefix ? 0.5 : distance(want, slug)
+          if (d < score) [best, score] = [slug, d]
+        }
+        if (score > Math.max(2, want.length / 3)) return
+        const link = document.createElement('a')
+        link.href = base + best + '/'
+        link.textContent = base + best + '/'
+        const closest = document.getElementById('closest')
+        closest.append(' Did you mean ', link, '?')
+      })()
+    </script>
+  </body>
+</html>
+`;
+}

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

@@ -1653,6 +1653,7 @@ export async function buildSite(config, opts = {}) {
             const pageCount = await generateSite({
                 liveExamples: config.liveExamples,
                 docs,
+                llmsTxt: config.llmsTxt !== false,
                 aliases: config.aliases,
                 searchPlaceholder: config.searchPlaceholder,
                 accessibility: config.accessibility,