tosijs-ui 1.7.0 → 1.7.2

package/CHANGELOG.md

@@ -1,5 +1,85 @@
 # Changelog
 
+## 1.7.2
+
+- **Fix: doc sites are now mount-point-agnostic** (issue #25). The build baked `basePath` into
+  every functional URL (nav/content links, `scriptUrl`, `stylesUrl`, favicon, `docsUrl`), so a
+  build was locked to one mount — adding a custom domain to a GitHub project page flipped the
+  live site to the root while `docs/` still pointed at `/repo`, 404ing every asset into a bare,
+  unstyled shell with no warning. Functional URLs are now emitted **relative to each page**, so
+  one build works at `/repo`, a custom-domain root, or a moved mount with no rebuild. *Metadata*
+  URLs (`canonical`, `og:url`, `og:image`, `sitemap.xml`) stay absolute via `baseUrl`+`basePath`
+  — so `basePath` now only affects metadata, never the page's assets. (The hydrated SPA's own
+  nav/`pushState` and `__TJS_LOCAL_BASE` remain root-relative — tracked in #16.)
+- **Fix: the haltija dev channel loaded once per background-test iframe.** The doc-browser's
+  background test runner loads every page-with-tests in a hidden iframe, each served the injected
+  dev-channel loader — so `dev.js` was imported N times into throwaway frames. The loader is now
+  gated to the top window (`self===top`).
+- **Live examples get a rounded, padded card.** `.preview` gains `padding` (breathing room around
+  rendered content) and its first child's top margin is dropped; the inset border moves to the
+  example's `:host` with a `border-radius`, so the whole example (preview + editors) reads as one
+  bordered card. CodeMirror tooltips render fixed-positioned so autocomplete isn't clipped by the
+  card's `overflow: hidden`.
+- **Removed the "blueprint loading" doc page.** It documented tosijs's own
+  `<xin-loader>`/`<xin-blueprint>` elements (no tosijs-ui component), so it belongs in tosijs's
+  docs. The generic `blueprint` icon stays.
+
+## 1.7.1
+
+- **Fix: components looked wrong in the doc site's dark mode** (e.g. `<tosi-table>` stayed
+  white). The doc-system theme drives the legacy `--background`/`--text-color` family and never
+  set the `--tosi-*` component palette, so components fell back to their baked-in light defaults
+  (`var(--tosi-bg, #fff)`). The doc-system now bridges `--tosi-accent`/`--tosi-bg`/`--tosi-text`/
+  `--tosi-bg-inset` onto its own colors **as references**, so every `--tosi-*` component follows
+  the site theme automatically — including dark mode (the referenced vars flip via
+  `invertLuminance`). The data-table pinned-row example now uses `var(--tosi-table-bg)` instead of
+  a hardwired `#eee`.
+- **Data-table `type` example** demonstrating the new column types (currency, number, percent,
+  fixed, bytes, boolean) added to the docs.
+
+- **Fix: "edit page source" showed HTML instead of source in a dev server without
+  `editableSources`.** The `/__docstore/source` endpoint was only routed when
+  `editableSources` was on; otherwise the request fell through to the SPA `index.html`
+  fallback and returned the rendered page at status 200 — so the client loaded HTML *as* the
+  source (and save read HTML). The endpoint is now handled unconditionally and answers a clean
+  `501` when editing is disabled, so `loadSource` falls back to the GitHub raw source (read-only
+  editing, matching the deployed site). Belt-and-suspenders: the client also rejects any
+  `text/html` response from that endpoint (guards SPA-rewrite hosts too). Documented the option
+  more fully in `doc-site-system.md`.
+- **Local example save now gives feedback.** "Save changes (local)" writes a per-browser
+  scratchpad (not the file) — it used to do so silently, reading as a no-op. It now posts a
+  toast (`postNotification`): *"Saved to this browser only — use 'Save to source' to write the
+  file."*
+
+- **`valueRenderer(type)` + declarative `<tosi-table>` column `type`.** A new exported helper
+  turns a compact type string into a reusable, locale-aware renderer with a sensible default
+  alignment: `number`, `currency`/`currency(USD)`, `fixed`/`fixed(n)` (default 2),
+  `percent`/`percent(n)` (of a fraction; default 0), `sci`, `eng`, `bytes`/`bytes(iec)` (SI ÷1000
+  or IEC ÷1024 units, right-aligned), and `boolean`/`boolean(t)`/`boolean(t,f)` (icons via the
+  `icons` proxy, centered; default `checkSquare`/`square`). Numeric cells also get a
+  `-negative` / `-zero` **state class** by value sign, so you get red negatives (etc.) from one
+  CSS rule — no custom cell renderer. Data-table columns take a `type`
+  (`ValueRendererType`) and format + align automatically — no hand-rolled `dataCell`; an explicit
+  `align`/`dataCell` still wins. Formatting follows `setLocale()`. Verified end-to-end (unit +
+  browser).
+
+- **Deprecation cleanup: `on<Event>` component callbacks → `handle<Event>`.** tosijs reserves the
+  `on<Event>` prefix for elements-factory event-handler sugar and now warns when a component
+  *defines* such a property. Renamed the internal ones: `onResize` → `handleResize` (`size-break`,
+  `side-nav`, `code-editor`, `babylon-3d`, `tab-selector`) and `onScrollEnd` → `handleScrollEnd`
+  (`data-table`). Verified: those pages now load with zero `on<Event>` deprecation warnings.
+  (`<tosi-tabs>`'s public `onCloseTab` still uses the old name — a breaking rename deferred to a
+  deprecation-alias pass; and the `tosiValue()`/`tosiPath()` accessor deprecation is a separate,
+  larger cleanup — both tracked.)
+
+- **CSS canary** — an inline doc-test on the `live-theme` page that smoke-tests the whole
+  styling chain in a real browser (`StyleSheet()` → the `vars` proxy → scaled-var `calc()` →
+  `createTheme`/`applyTheme` → cascade → `getComputedStyle`), plus a theme color-change
+  propagating to computed style, dark-mode luminance inversion, and `Color.inverseLuminance`.
+  Each link is silent when it breaks (happy-dom can't resolve `var()`/the cascade), so a red
+  now means a system-level CSS break, not a component quirk. Runs in the `doc-tests.pw.ts` CI
+  gate.
+
 ## 1.7.0
 
 > ### ⚠️ BREAKING CHANGE — `<tosi-code>` moved from ACE to CodeMirror 6

package/dist/babylon-3d.d.ts

@@ -51,7 +51,7 @@ export declare class B3d extends WebComponent {
     sceneCreated: B3dCallback;
     update: B3dCallback;
     private _update;
-    onResize(): void;
+    handleResize(): void;
     loadScene: (path: string, file: string, processCallback?: MeshProcessCallback) => Promise<void>;
     loadUI: (options: B3dUIOptions) => Promise<any>;
     connectedCallback(): void;

package/dist/babylon-3d.js

@@ -299,7 +299,7 @@ export class B3d extends WebComponent {
             }
         }
     };
-    onResize() {
+    handleResize() {
         if (this.engine) {
             this.engine.resize();
         }

package/dist/code-editor-cm.js

@@ -10,7 +10,7 @@ Languages here are the always-available set (js/ts/css/html/markdown). First-cla
 tjs (highlighting + runtime-value autocomplete via tjs-lang's editors/codemirror) is
 layered in separately and only when tjs-lang is installed.
 */
-import { EditorView, keymap, lineNumbers, highlightActiveLineGutter, highlightSpecialChars, drawSelection, dropCursor, rectangularSelection, crosshairCursor, highlightActiveLine, } from '@codemirror/view';
+import { EditorView, keymap, lineNumbers, highlightActiveLineGutter, highlightSpecialChars, drawSelection, dropCursor, rectangularSelection, crosshairCursor, highlightActiveLine, tooltips, } from '@codemirror/view';
 import { EditorState, Compartment, Annotation, Transaction, } from '@codemirror/state';
 import { indentWithTab, history, defaultKeymap, historyKeymap, undo, redo, undoDepth, redoDepth, } from '@codemirror/commands';
 import { indentUnit, foldGutter, foldKeymap, indentOnInput, syntaxHighlighting, defaultHighlightStyle, bracketMatching, } from '@codemirror/language';
@@ -129,6 +129,10 @@ const editorTheme = EditorView.theme({
 function baseExtensions() {
     return [
         editorTheme,
+        // Render autocomplete / hover tooltips in a fixed layer so they escape the
+        // live-example's `:host { overflow: hidden }` (the rounded card clip) instead
+        // of being cut off at the editor's bottom edge in a short example.
+        tooltips({ position: 'fixed' }),
         lineNumbers(),
         highlightActiveLineGutter(),
         highlightSpecialChars(),

package/dist/code-editor.d.ts

@@ -92,7 +92,7 @@ export declare class CodeEditor extends WebComponent<CodeEditorParts> {
             fontFamily: string;
         };
     };
-    onResize(): void;
+    handleResize(): void;
     connectedCallback(): void;
     disconnectedCallback(): void;
     private isTjsMode;

package/dist/code-editor.js

@@ -267,7 +267,7 @@ export class CodeEditor extends WebComponent {
             fontFamily: "Menlo, Monaco, Consolas, 'Courier New', monospace",
         },
     };
-    onResize() {
+    handleResize() {
         this._handle?.refresh();
     }
     connectedCallback() {

package/dist/data-table.d.ts

@@ -1,11 +1,13 @@
 import { Component as WebComponent, ElementCreator } from 'tosijs';
 import { SortCallback } from './make-sorter';
+import { ValueRendererType } from './value-renderer';
 export interface ColumnOptions {
     name?: string;
     prop: string;
     width: number;
     visible?: boolean;
     align?: string;
+    type?: ValueRendererType;
     pinned?: 'left' | 'right';
     sort?: false | 'ascending' | 'descending';
     headerCell?: (options: ColumnOptions) => HTMLElement;
@@ -201,7 +203,7 @@ export declare class TosiTable extends WebComponent {
     private updateSelection;
     private findCell;
     private _pendingFocus;
-    private onScrollEnd;
+    private handleScrollEnd;
     private focusCell;
     private handleKeyNav;
     connectedCallback(): void;

package/dist/data-table.js

@@ -194,6 +194,7 @@ export interface ColumnOptions {
   width: number
   visible?: boolean
   align?: string
+  type?: string // valueRenderer type: 'currency(USD)', 'fixed(2)', 'bytes', 'boolean(check,x)', …
   pinned?: 'left' | 'right'
   sort?: false | 'ascending' | 'descending'
   headerCell?: (options: ColumnOptions) => HTMLElement
@@ -201,6 +202,59 @@ export interface ColumnOptions {
 }
 ```
 
+## Column value types
+
+Give a column a `type` and it's formatted (and aligned) automatically — no hand-rolled
+`dataCell`. The `type` is a [`valueRenderer`](value-renderer) string:
+
+```
+[
+  { prop: 'name',    width: 160 },
+  { prop: 'price',   width: 100, type: 'currency(USD)' }, // localized $, right-aligned
+  { prop: 'weight',  width: 100, type: 'fixed(3)' },      // 3 decimals, right-aligned
+  { prop: 'size',    width: 100, type: 'bytes' },         // 1.5 MB, right-aligned
+  { prop: 'active',  width: 60,  type: 'boolean' },       // checkSquare / square, centered
+]
+```
+
+Numeric types (`number`, `currency`, `fixed`, `percent`, `sci`, `eng`, `bytes`) right-align
+by default; `boolean` centers and renders icons. An explicit `align` — or a `dataCell` —
+always wins. Formatting follows the app locale (`setLocale()`). Numeric cells also get a
+`-negative` or `-zero` state class by value sign, so the red "Change" values above come from
+one CSS rule (`.-negative { color: #e44 }`), no cell renderer.
+
+```js
+import { tosiTable } from 'tosijs-ui'
+
+const rows = [
+  { item: 'Alpha Widget', price: 12.5, qty: 1240, change: 3.25, rate: 0.075, mass: 1.23456, size: 1_536_000, active: true, flagged: false },
+  { item: 'Beta Gadget', price: 4.99, qty: 42, change: -1.5, rate: 0.2, mass: 0.5, size: 512, active: false, flagged: true },
+  { item: 'Gamma Sprocket', price: 199, qty: 8, change: 0, rate: 1.5, mass: 12.005, size: 2_500_000_000, active: true, flagged: true },
+  { item: 'Delta Cog', price: 0.75, qty: 99999, change: -0.12, rate: 0.004, mass: 0.001, size: 48_200, active: false, flagged: false },
+]
+
+const table = tosiTable({ style: { display: 'block', height: '240px' } })
+table.value = {
+  array: rows,
+  columns: [
+    { prop: 'item', name: 'Item', width: 150 },
+    { prop: 'price', name: 'Price', width: 110, type: 'currency(USD)' },
+    { prop: 'change', name: 'Change', width: 100, type: 'currency(USD)' }, // red negatives via CSS
+    { prop: 'qty', name: 'Qty', width: 90, type: 'number' },
+    { prop: 'rate', name: 'Rate', width: 80, type: 'percent(1)' },
+    { prop: 'mass', name: 'Mass', width: 90, type: 'fixed(2)' },
+    { prop: 'size', name: 'Size', width: 100, type: 'bytes' },
+    { prop: 'active', name: 'Active', width: 80, type: 'boolean' },
+    { prop: 'flagged', name: 'Flag', width: 80, type: 'boolean(check, x)' },
+  ],
+}
+preview.append(table)
+```
+```css
+.preview .-negative { color: #e44; }
+.preview .-zero { opacity: 0.45; }
+```
+
 ## Pinned Columns and Rows
 
 Set `pinned: 'left'` or `pinned: 'right'` on individual columns to pin
@@ -314,11 +368,11 @@ preview.append(table)
   width: 100%;
 }
 .preview tosi-table .pinned-bottom {
-  background: #eee;
+  background: var(--tosi-table-bg, var(--tosi-bg, #fff));
   font-weight: bold;
 }
 .preview .row-pinned .td {
-  background: #eee;
+  background: var(--tosi-table-bg, var(--tosi-bg, #fff));
 }
 .preview .num-cell {
   font-variant-numeric: tabular-nums;
@@ -513,6 +567,7 @@ As well as any column names you want localized.
 import { Component as WebComponent, elements, vars, varDefault, tosiValue, getListItem, getListBinding, tosi, } from 'tosijs';
 import { trackDrag } from './track-drag';
 import { icons } from './icons';
+import { valueRenderer } from './value-renderer';
 import { popMenu } from './menu';
 import * as dragAndDrop from './drag-and-drop';
 import { tosiLocalized, localize } from './localize';
@@ -545,6 +600,20 @@ function defaultWidth(array, prop, charWidth) {
 }
 const { div, span, button } = elements;
 const passThru = (array) => array;
+// One ValueRenderer per typed column, cached: `Intl.*Format` construction is the
+// expensive part and a column's renderer is stable for its lifetime. Returns null
+// when the column has no `type` or supplies its own `dataCell` (which always wins).
+const columnRenderers = new WeakMap();
+function columnRenderer(col) {
+    if (!col.type || col.dataCell)
+        return null;
+    let renderer = columnRenderers.get(col);
+    if (!renderer) {
+        renderer = valueRenderer(col.type);
+        columnRenderers.set(col, renderer);
+    }
+    return renderer;
+}
 export class TosiTable extends WebComponent {
     static preferredTagName = 'tosi-table';
     // Layout: a single .scroll-area inside :host is the only scroll container
@@ -968,7 +1037,9 @@ export class TosiTable extends WebComponent {
         // position: sticky lives in `.col-pinned` (added by cellClasses), so only
         // the per-cell offsets need to be set inline here.
         const style = {
-            justifyContent: col.align || 'left',
+            // Explicit align wins; else the column type's default (numerics right,
+            // booleans center); else left.
+            justifyContent: col.align || columnRenderer(col)?.align || 'left',
             ...extra,
         };
         if (si.left != null)
@@ -993,6 +1064,27 @@ export class TosiTable extends WebComponent {
             this.applyGridCellAttrs(cell, colIndex, si, style);
             return cell;
         }
+        // A `type` column formats through its cached ValueRenderer. The binding's toDOM
+        // runs per stamped row, so it stays locale-reactive and works for icon cells
+        // (which replace children) as well as text.
+        const renderer = columnRenderer(col);
+        if (renderer) {
+            return span({
+                class: this.cellClasses('td', si),
+                role: 'gridcell',
+                tabindex: -1,
+                ariaColindex: String(colIndex + 1),
+                style,
+                bind: {
+                    value: item[col.prop],
+                    binding: {
+                        toDOM(el, val) {
+                            renderer.toDOM(el, val);
+                        },
+                    },
+                },
+            });
+        }
         return span({
             class: this.cellClasses('td', si),
             role: 'gridcell',
@@ -1287,7 +1379,7 @@ export class TosiTable extends WebComponent {
         return cells?.[colIndex] ?? null;
     }
     _pendingFocus = null;
-    onScrollEnd = () => {
+    handleScrollEnd = () => {
         if (!this._pendingFocus)
             return;
         const { row, col } = this._pendingFocus;
@@ -1659,7 +1751,7 @@ export class TosiTable extends WebComponent {
             ...visibleBinding,
             this._tbodyBottom,
         ].filter(Boolean));
-        this._scrollArea.addEventListener('scrollend', this.onScrollEnd);
+        this._scrollArea.addEventListener('scrollend', this.handleScrollEnd);
         this.append(this._scrollArea);
         this.observePinnedRowMutations();
         this.tagPinnedRows();

package/dist/doc-browser.js

@@ -726,7 +726,12 @@ export function createDocBrowser(options) {
     const loadSource = async (p) => {
         try {
             const r = await fetch(`/__docstore/source?file=${encodeURIComponent(p)}`);
-            if (r.ok)
+            // Accept only a genuine source response. A misconfigured dev server (no
+            // editableSources) or a SPA-rewrite host answers an unknown path with
+            // index.html at status 200 — taking that would load the PAGE as the source.
+            // Reject HTML and fall through to the GitHub raw source instead.
+            const contentType = r.headers.get('content-type') || '';
+            if (r.ok && !/text\/html/i.test(contentType))
                 return await r.text();
         }
         catch {

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

@@ -62,6 +62,17 @@ export function docSystemStyleSpec(theme = {}) {
             _fontSize: '16px',
             _codeFontSize: '14px',
             ...colors,
+            // Bridge the tosijs component palette (`--tosi-*`) onto the doc-system's color
+            // family. Defined as REFERENCES, so a component reading `var(--tosi-bg)` follows
+            // the site theme automatically — including dark mode, where `invertLuminance()`
+            // flips the referenced `--background`/`--text-color`/… in `.darkmode`. Without
+            // this the doc-system never set `--tosi-*`, so components fell back to their
+            // baked-in light defaults (e.g. `var(--tosi-bg, #fff)` → white <tosi-table> in
+            // dark mode). Colors only — component metrics keep their own defaults.
+            _tosiAccent: vars.brandColor,
+            _tosiBg: vars.background,
+            _tosiText: vars.textColor,
+            _tosiBgInset: vars.insetBg,
             _spacing: '10px',
             _lineHeight: 'calc(var(--font-size) * 1.6)',
             _h1Scale: '2',

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

@@ -28,6 +28,17 @@ export declare function resolveIdleMs(configHours: number | undefined, envHours:
  * off. Only an explicit non-positive number disables the ceiling.
  */
 export declare function resolveLimitMb(configMb: number | undefined, envMb: string | undefined): number;
+/**
+ * The localhost-gated haltija dev-channel loader injected into served HTML at
+ * serve time (never bundled, never in the built output).
+ *
+ * `self===top` keeps it in the TOP window only. The doc-browser's background test
+ * runner loads every page-with-tests in a hidden iframe (`?_testMode=1`), each
+ * served this same HTML — without the guard, haltija's `dev.js` gets imported
+ * once per test page (N redundant loads in throwaway frames). An agent only ever
+ * drives the top page, so nested frames never need the channel.
+ */
+export declare function haltijaLoaderSnippet(httpsPort: number): string;
 export declare function devServer(config: SiteConfig, opts?: {
     test?: boolean;
     build?: () => unknown | Promise<unknown>;

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

@@ -78,6 +78,20 @@ export function resolveLimitMb(configMb, envMb) {
     const mb = Number.isFinite(raw) ? raw : DEFAULT_LIMIT_MB;
     return mb > 0 ? mb : 0;
 }
+/**
+ * The localhost-gated haltija dev-channel loader injected into served HTML at
+ * serve time (never bundled, never in the built output).
+ *
+ * `self===top` keeps it in the TOP window only. The doc-browser's background test
+ * runner loads every page-with-tests in a hidden iframe (`?_testMode=1`), each
+ * served this same HTML — without the guard, haltija's `dev.js` gets imported
+ * once per test page (N redundant loads in throwaway frames). An agent only ever
+ * drives the top page, so nested frames never need the channel.
+ */
+export function haltijaLoaderSnippet(httpsPort) {
+    return (`<script>self===top&&/^localhost$|^127\\./.test(location.hostname)` +
+        `&&import('https://localhost:${httpsPort}/dev.js')</script>`);
+}
 /**
  * Reclaim the port we are about to bind, from the process LISTENING on it.
  *
@@ -259,8 +273,7 @@ export async function devServer(config, opts = {}) {
         (config.haltijaDev === true ||
             process.env.HALTIJA_DEV === '1' ||
             process.env.HALTIJA_DEV === 'true');
-    const HALTIJA_SNIPPET = `<script>/^localhost$|^127\\./.test(location.hostname)` +
-        `&&import('https://localhost:${HALTIJA_HTTPS_PORT}/dev.js')</script>`;
+    const HALTIJA_SNIPPET = haltijaLoaderSnippet(HALTIJA_HTTPS_PORT);
     let testReportResolve;
     // Source read/write for in-browser "edit page source" (config.editableSources).
     // Local dev only — your machine, your files — so the lone guard is correctness:
@@ -581,11 +594,21 @@ export async function devServer(config, opts = {}) {
             // Source read/write for in-browser "edit page source" (opt-in, dev only).
             // A write lands in the repo file; the chokidar watcher then rebuilds and
             // the page refreshes — the build itself is the preview.
-            if (config.editableSources && reqPath === '/__docstore/source') {
+            if (reqPath === '/__docstore/source') {
+                // Handle this endpoint UNCONDITIONALLY so it never falls through to the SPA
+                // index.html fallback below. A 200-with-HTML there is silently corrupting:
+                // the client loads the PAGE as the "source" (edit-page-source shows HTML;
+                // save-to-source reads HTML). When editing isn't enabled, answer with a clean
+                // status so `loadSource` falls back to the GitHub raw source (read-only), which
+                // is what the deployed static site already does.
+                if (!config.editableSources) {
+                    return new Response('editableSources is not enabled in this doc-site config (set editableSources: true to edit/save source in dev)', { status: 501, headers: { 'Content-Type': 'text/plain; charset=utf-8' } });
+                }
                 if (request.method === 'GET')
                     return handleReadSource(request);
                 if (request.method === 'POST')
                     return handleWriteSource(request);
+                return new Response('method not allowed', { status: 405 });
             }
             if (reqPath === '/')
                 reqPath = '/index.html';

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

@@ -56,4 +56,22 @@ export interface GenerateSiteConfig {
     /** extra lines injected into every <head> (favicon, analytics, etc.) */
     headExtra?: string;
 }
+/**
+ * Depth of a page below the site root: 0 for the root index (served at the mount
+ * root), 1 for every `/slug/` page. The generator only ever emits a flat `/slug/`
+ * tree (see `pathForSlug`), so a non-root page is always exactly one directory deep.
+ */
+export declare function pageDepth(slug: string): number;
+/**
+ * Rewrite a root-relative *functional* URL (asset ref, nav / content link) to be
+ * relative to a page at `depth`, so ONE build works at ANY mount point — a GitHub
+ * project page under `/repo`, a custom-domain root, or a moved mount — with no
+ * `basePath` rebuild. Relative URLs resolve against wherever the page is actually
+ * served, so `basePath` is deliberately NOT applied here: a page at `/repo/x/`
+ * gets `../styles.css` → `/repo/styles.css`, the same page at `/x/` gets it at
+ * `/styles.css`. External (`https://…`, `//…`) and already-relative refs pass
+ * through untouched. (Metadata URLs still use `withBase` — they need the absolute
+ * origin.) See issue #25; the runtime/SPA-navigation half is issue #16.
+ */
+export declare function relativeUrl(depth: number, p: string): string;
 export declare function generateSite(config: GenerateSiteConfig): Promise<number>;

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

@@ -27,11 +27,11 @@ const escapeText = (s) => s.replace(/&/g, '&amp;').replace(/</g, '&lt;').replace
  * <details> on the path to `currentFilename` opened. `currentFilename` gets
  * aria-current. Crawlable + no-JS: every node is a real <a>.
  */
-function navHtml(docs, slugMap, currentFilename, basePath) {
+function navHtml(docs, slugMap, currentFilename, depth) {
     const roots = buildNavTree(docs, slugMap);
     const open = navOpenPath(roots, currentFilename);
     const renderNode = (node, indent) => {
-        const href = withBase(basePath, pathForSlug(node.slug));
+        const href = relativeUrl(depth, pathForSlug(node.slug));
         const current = node.doc.filename === currentFilename;
         // `doc-link` is what the HYDRATED nav emits, and the shared nav CSS is written
         // against it. Emitting a bare <a> here forced a second, hand-copied rule set under
@@ -78,16 +78,48 @@ function absUrl(baseUrl, pathOrUrl) {
 /**
  * Prefix a root-relative path with basePath. No-op for '/', empty, protocol-
  * relative (`//…`), or absolute (`https://…`) URLs.
+ *
+ * Used ONLY for *metadata* URLs now (canonical, og:url, og:image, sitemap) — they
+ * legitimately need the real absolute origin+path. *Functional* URLs go through
+ * `relativeUrl` instead, so the artifact is mount-agnostic. See `relativeUrl`.
  */
 function withBase(basePath, p) {
     if (!p || !basePath || basePath === '/' || /^(https?:)?\/\//.test(p))
         return p;
     return basePath.replace(/\/$/, '') + (p.startsWith('/') ? p : '/' + p);
 }
+/**
+ * Depth of a page below the site root: 0 for the root index (served at the mount
+ * root), 1 for every `/slug/` page. The generator only ever emits a flat `/slug/`
+ * tree (see `pathForSlug`), so a non-root page is always exactly one directory deep.
+ */
+export function pageDepth(slug) {
+    return slug === '' ? 0 : 1;
+}
+/**
+ * Rewrite a root-relative *functional* URL (asset ref, nav / content link) to be
+ * relative to a page at `depth`, so ONE build works at ANY mount point — a GitHub
+ * project page under `/repo`, a custom-domain root, or a moved mount — with no
+ * `basePath` rebuild. Relative URLs resolve against wherever the page is actually
+ * served, so `basePath` is deliberately NOT applied here: a page at `/repo/x/`
+ * gets `../styles.css` → `/repo/styles.css`, the same page at `/x/` gets it at
+ * `/styles.css`. External (`https://…`, `//…`) and already-relative refs pass
+ * through untouched. (Metadata URLs still use `withBase` — they need the absolute
+ * origin.) See issue #25; the runtime/SPA-navigation half is issue #16.
+ */
+export function relativeUrl(depth, p) {
+    if (!p || /^(https?:)?\/\//.test(p) || !p.startsWith('/'))
+        return p;
+    const rel = '../'.repeat(depth) + p.slice(1);
+    return rel === '' ? './' : rel;
+}
 function pageHtml(doc, config, slugMap, configAttr) {
     const { projectName = '', baseUrl = '', lang = 'en', favicon = '/favicon.svg', docsUrl = '/docs.json', scriptUrl = '/iife.js', hydrateUrl, stylesUrl = '/doc-system.css', 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 localizedAttr = config.localizedStrings
-        ? ` localized="${escapeAttr(withBase(basePath, localizedUrl))}"`
+        ? ` localized="${escapeAttr(relativeUrl(depth, localizedUrl))}"`
         : '';
     // ONE rule, shared with the doc-browser's hydration path — see doc-title.ts. Writing
     // it twice is what made the title change on hydration (issue #6).
@@ -103,9 +135,9 @@ function pageHtml(doc, config, slugMap, configAttr) {
     // static HTML is correct for no-JS readers and crawlers (the doc-browser also
     // does this client-side after hydration).
     const body = rewriteDocLinks(renderDocMarkdown(doc.text, { bakes: bakes?.get(doc.filename) }), (filename) => slugMap[filename] !== undefined
-        ? withBase(basePath, pathForSlug(slugMap[filename]))
+        ? relativeUrl(depth, pathForSlug(slugMap[filename]))
         : null);
-    const nav = navHtml(config.docs, slugMap, doc.filename, basePath);
+    const nav = navHtml(config.docs, slugMap, doc.filename, depth);
     const navbar = linkListHtml('doc-navbar', config.navbarLinks);
     const jsonLd = baseUrl
         ? jsonLdScript({
@@ -126,7 +158,7 @@ function pageHtml(doc, config, slugMap, configAttr) {
         '  <link rel="preconnect" href="https://fonts.googleapis.com" />',
         '  <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin />',
         // Burned-in theme: styles the page with no JS and with zero flash on hydration.
-        `  <link rel="stylesheet" href="${escapeAttr(withBase(basePath, stylesUrl))}" data-tosi-doc-system />`,
+        `  <link rel="stylesheet" href="${escapeAttr(relativeUrl(depth, stylesUrl))}" data-tosi-doc-system />`,
         `  <title>${escapeText(title)}</title>`,
         description
             ? `  <meta name="description" content="${escapeAttr(description)}" />`
@@ -155,7 +187,7 @@ function pageHtml(doc, config, slugMap, configAttr) {
             ? `  <meta name="twitter:image" content="${escapeAttr(imageAbs)}" />`
             : '',
         jsonLd,
-        `  <link rel="icon" href="${escapeAttr(withBase(basePath, favicon))}" />`,
+        `  <link rel="icon" href="${escapeAttr(relativeUrl(depth, favicon))}" />`,
         headExtra,
     ]
         .filter(Boolean)
@@ -189,7 +221,7 @@ function pageHtml(doc, config, slugMap, configAttr) {
 ${head}
 </head>
 <body>
-  <tosi-doc-system docs="${escapeAttr(withBase(basePath, docsUrl))}" config="${configAttr}"${localizedAttr}>
+  <tosi-doc-system docs="${escapeAttr(relativeUrl(depth, docsUrl))}" config="${configAttr}"${localizedAttr}>
   <article class="doc-content">
 ${body}
   </article>
@@ -197,8 +229,8 @@ ${nav}
 ${navbar}
   </tosi-doc-system>
   ${hydrateUrl
-        ? `<script type="module" src="${escapeAttr(withBase(basePath, hydrateUrl))}"></script>`
-        : `<script src="${escapeAttr(withBase(basePath, scriptUrl))}"></script>`}
+        ? `<script type="module" src="${escapeAttr(relativeUrl(depth, hydrateUrl))}"></script>`
+        : `<script src="${escapeAttr(relativeUrl(depth, scriptUrl))}"></script>`}
 </body>
 </html>
 `;

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

@@ -88,9 +88,16 @@ export interface SiteConfig {
     domain?: string;
     /**
      * URL prefix the site is served under, default '/'. Set to '/<repo>' for a
-     * GitHub project page without a custom domain; every absolute URL the
-     * generator emits (links, canonical, sitemap, scriptUrl, stylesUrl) is
-     * rewritten under it.
+     * GitHub project page without a custom domain.
+     *
+     * As of the mount-agnostic build (issue #25), `basePath` only affects
+     * *metadata* URLs — `canonical`, `og:url`, `og:image`, and `sitemap.xml` —
+     * which need the real absolute served path for SEO. *Functional* URLs (nav /
+     * content links, `scriptUrl`, `stylesUrl`, favicon, `docsUrl`) are emitted
+     * **relative to each page**, so one build works at `/repo`, at a custom-domain
+     * root, or a moved mount with no rebuild. You still want `basePath` correct so
+     * search engines see canonical URLs at the real path; getting it wrong now only
+     * mis-states metadata, it no longer 404s the page's assets.
      */
     basePath?: string;
     /**