tosijs-ui 1.14.0 → 1.14.2

package/CHANGELOG.md

@@ -1,5 +1,191 @@
 # Changelog
 
+## 1.14.2
+
+A single-fix patch, cut from `v1.14.1` rather than from `main`, so it carries none of the
+in-progress 1.15.0 work.
+
+### `import 'tosijs-ui/doc-browser'` now actually defines `<tosi-doc-system>` (#158, #159)
+
+**If you are building a doc site with `tosijs-ui/site`, upgrade.** The one import every
+adoption doc tells you to write did not register the doc system.
+
+`doc-browser.ts` is a library module — types, helpers, `createDocBrowser()` — while the element
+lives in `doc-system/doc-system.ts`, which imports *from* doc-browser. The dependency arrow ran
+the wrong way, so that import could never have reached the registrar however it was written.
+
+What let it survive several releases is that it was a **partial** success. The leaf components
+(`tosi-sidenav`, `tosi-example`, …) registered fine, so your bundle looked healthy, your own
+elements worked, pages served 200 — and `<tosi-doc-system>` sat in the markup inert. The
+expensive half was quieter: no doc system means no `window.__docTestResults`, so an entire
+inline doc-test corpus **silently stopped existing**. Not a red suite; a suite reporting
+nothing. Two projects hit this independently, one of them reaching a release candidate first.
+
+`tosijs-ui/doc-browser` now resolves to an entry that imports the registrar and re-exports the
+whole documented API. **No code changes** — the line you already wrote starts working.
+
+A more precise spelling, a named `tosijs-ui/doc-system` export, is coming in a later release.
+**This one keeps working**; it is an addition, not a deprecation.
+
+Two sentences were separately false and are corrected: `import 'tosijs-ui'` does **not** also
+register the doc system. The root barrel deliberately excludes that cluster (#133 — it was 77%
+of the barrel's weight, landing on every app that imported a button), so the root import gives
+you buttons and an undefined doc system. That text shipped in the emitted `.d.ts`, the adoption
+page and the adopter reference.
+
+A test now imports the built entry in a subprocess and fails if the element is undefined.
+Verified by mutation: strip the side-effect import and it goes red.
+
+## 1.14.1
+
+### The doc-test gate can tell a dropped page from a passing one
+
+`__docTestResults` reported `{ passed, failed, pages }`, so a consumer gate could assert that
+tests ran and that none failed — but not that **all** of them ran. A runner that silently lost
+half the corpus satisfied every check.
+
+That is not hypothetical. The false green fixed in 1.14.0 was a page-**selection** defect: a
+substring match counted 17 pages where 16 had tests, and ran a prose page's examples in a
+background iframe. Fixing the selection did not add a guard against the next one.
+
+The resolved object now carries `pagesWithTests` and `pagesTested`, and
+`tests/doc-tests.pw.ts` asserts three things where it previously asserted one: the corpus
+contains test pages at all, every such page reported, and some assertions executed. A corpus
+with genuinely no tests resolves with honest zeros, so "no tests exist" stays distinguishable
+from "tests exist and ran".
+
+Framed by tosijs-platform in #142, from a suite that reported **140 pass, 0 fail while twelve
+cases had never executed** — skip-guarded behind emulators that were not running, asserting
+`expect(true).toBe(true)`. When the emulators were finally started it found three production
+bugs in ten minutes. The tests were fine; the reporting was a lie, and a comfortable one, which
+is why it survived. **"We didn't look" and "we looked and it's fine" must not produce the same
+output** — a reported total is that same lie one level up.
+
+### New page: "Adopting the doc system"
+
+Three of the four onboarding defects this release fixes (#144, #145, #146) would have been
+prevented by a page that did not exist — a narrow path to read *before* the first build, as
+opposed to a configuration reference nobody reads until something is already wrong.
+
+It is organised around the thing that makes this system hard to adopt: **its failure mode is a
+site that serves perfectly and shows nothing.** Not a crash, not a 404 — pages return 200, the
+markup is in the HTML, the adopter's own elements register, and the page is inert. So the page
+leads with a "how to tell it actually worked" checklist (is `tosi-doc-system` defined, is the
+chrome there, read one emitted `<head>`, do the examples run) and then explains the four silent
+failures behind those checks.
+
+Includes the complete `bundleEntry` file rather than naming it, since "your entry should import
+what your pages need" was the sentence that cost #145's reporter the most — it reads as *your*
+content, not as the doc system that renders the entire site.
+
+### `<tosi-table>` filters and sorts the whole table, not the first `maxVisibleRows` (#147)
+
+The window was applied **first**, so both the filter and the sort saw only the first N rows.
+Two consequences, both reported from production at 300k rows:
+
+- **A matching row past the cap could never be found.** A newly-created company appended to a
+  12,000-row list, with the cap at 10,000, did not exist as far as search was concerned.
+- **Sorting did not sort the table.** You got the first N rows in *data* order, arranged
+  nicely — not the top N by the sort.
+
+This was known and the answer had been a warning: the comment in the render path read *"every
+count, filter and sort then ran on the truncated set, so the numbers were self-consistent and
+wrong"* (#82). A warning does not help someone whose search returns nothing, and it named row
+counts rather than the consequence — so "showing 10,000 of 12,000 rows" gave no clue why a
+search failed.
+
+The order is now **filter → force → sort → cluster → window**. `maxVisibleRows` is a *layout*
+ceiling — the browser's maximum element height — so it belongs at the end, against what will be
+drawn, rather than at the start against the data.
+
+**Cost, measured on 300k rows**, since this moves the sort from "at most `maxVisibleRows`" to
+"every match": the common case (no sort set) is **0.9ms, down from 2.9ms**; a filter narrowing
+to ~1% is 2.0ms; a broad sort over all 300k is **108ms**. That last one is the price of sorting
+the real table, and it is paid when you click a column header — but `pinColumns()`, a schema
+change and a column resize all trigger a render without changing row order, so the pipeline is
+memoized against the identities that determine it (array, filter, sort, groupId, forced ids).
+A render that changes none of them reuses the result.
+
+The truncation warning now counts against the **filtered** set — "10,000 of 300,000" is
+alarming and wrong once a filter has narrowed things to 40 — and says that the rows shown are
+the right ones, there are simply more than the browser can lay out.
+
+### `menuClass` — theme one component's menus without restyling the page (#148)
+
+Menu metrics are all theme variables, and setting them on your component **did not work**.
+The popup is built per-invocation and mounted in a body-level `<tosi-float>`, so it is not a
+descendant of whatever opened it, and custom properties have nothing to inherit from. The only
+selector that reached it was `:root` — which restyles every menu on the page, including the doc
+system's own when your component is documented on a `tosijs-ui/site` site. The reporter had not
+shipped their denser menubar for exactly that reason: a component reaching out to re-theme the
+page around it is the wrong direction.
+
+```
+popMenu({ target, menuItems, menuClass: 'my-editor-menu' })
+<tosi-menu menu-class="my-editor-menu">
+<tosi-select menu-class="my-listbox">      // its listbox mounts the same way
+```
+
+The class lands beside `xin-menu tosi-menu`, takes a space-separated list, and **propagates to
+submenus** — which are separate popups, so without that the theming would apply at the top
+level and silently revert one level down. `menuWidth` was already a per-menu attribute, so
+per-menu styling is not new here; this is the same idea for the rest of the knobs.
+
+Chosen over the two alternatives in the report: copying the trigger's computed variables onto
+the popup needs no change from adopters but is considerably more magic, and stamping a
+`data-menu-owner` back-reference solves selection without solving theming.
+
+### Adoption blockers found by tosijs-editor onboarding (#144, #145, #146)
+
+Three defects and a credential, all found by one project adopting `tosijs-ui/site` for the
+first time. Every one of them failed silently.
+
+**A Mapbox token in `dist/` blocked adopters' pushes (#145).** Two `<tosi-map>` doc examples
+carried a literal `pk.` token, which compiled into `dist/mapbox.js`, inlined into `iife.js`,
+and landed in every adopter's sourcemap. It matches Mapbox's published secret pattern, so
+**GitHub push protection blocked adopters the first time they committed their built site** — a
+wall with someone else's name on it.
+
+To be clear about what this is and is not: Mapbox `pk.` tokens are **public by design** —
+Mapbox's own docs tell you to put them in client-side JavaScript — so the scanner match is a
+false positive and there was never a secret here. The demos still use the token; it is now
+assigned programmatically and base64'd, which is **not** a security measure and would be a
+poor one. It exists solely so the literal string stops matching a regex. `atob()` protects
+nothing from anyone, which is precisely why it suits a value that needs no protection.
+
+`src/no-secrets.test.ts` fails the build on any credential-shaped string in `src/`, and says
+plainly what it cannot see: an encoded value, deliberately. It catches accident, not intent.
+
+**`bundleEntry` REPLACES the default bundle rather than extending it (#145).** An entry that
+imports only your own library produces a site where every page renders its prerendered markup
+and nothing else — no header, no nav, no menu, no live examples — with no console error, no
+build warning and no 404. `<tosi-doc-system>` sits in the HTML, inert, because nothing defined
+it, while your own elements register fine and make the bundle look healthy. The jsdoc now says
+this in the imperative with the two-line fix, and the build **scans the emitted bundle and
+warns** when `tosi-doc-system` is absent (and `tosi-example`, when the corpus has executable
+fences). Grepping is sound here for once: `customElements.define` needs the literal tag, so
+minification cannot erase it.
+
+**`baseUrl` meant two different things (#144).** `generate-site` treated it as the origin and
+added `basePath` on top; `make-llms-txt` treated it as origin-plus-path and ignored `basePath`
+entirely. On a GitHub project page no configuration satisfied both — matching the canonical
+URLs doubled the prefix in `llms.txt`, matching `llms.txt` dropped it from every canonical and
+sitemap entry. Underneath were **two copies of `withBase`** (`generate-site`, and `epub`, whose
+comment read "mirrors generate-site's withBase") plus this third consumer with none: one rule,
+three implementations, one of them empty. `withBase` now lives once in `routing.ts`, `llms.txt`
+applies it, `baseUrl` is documented as origin-only, and the build warns on the combination that
+is always wrong.
+
+**Which fence languages execute was undocumented (#146).** Six run — `js`, `ts`, `tjs`,
+`html`, `css`, `test` — and the only place the distinction appeared named a subset, so the
+mental model everyone formed was "js/ts/tjs/test run, everything else is display". A ` ```css `
+fence showing how to style the component in your app is injected as a page-wide `<style>`; a
+lone ` ```html ` fence showing the markup something compiles to renders as a broken-looking
+example. Neither fails the build. Now documented as a table with display-only alternatives
+(`xml` for markup), along with the grouping rule — adjacent fences form one example, prose
+between them starts a new one — which is why moving a `test` block under its own heading
+silently detaches it from the demo it was written against.
+
 ## 1.14.0
 
 ### Quote style no longer decides whether a live example runs (#141)

package/dist/data-table.d.ts

@@ -238,6 +238,8 @@ export declare class TosiTable extends WebComponent {
     private _sort?;
     private _rowGroupId;
     private _visibleGroupedRowIds;
+    private _visibleMemo;
+    private computeVisibleRows;
     private _nonRepeatingGroupedRowCells;
     private _pinnedTopRows?;
     private _pinnedBottomRows?;

package/dist/data-table.js

@@ -1453,6 +1453,76 @@ export class TosiTable extends WebComponent {
     _sort;
     _rowGroupId = null;
     _visibleGroupedRowIds = null;
+    /*
+    Memo for the filter → force → sort → cluster pipeline (#147).
+  
+    Correcting the order moved the sort from "at most `maxVisibleRows` rows" to "every matching
+    row", which is the price of sorting the actual table. Measured on 300k rows: a broad sort is
+    **108ms**, against 2.9ms for the old (wrong) window-first order. Paying that once when the
+    user clicks a column header is fine. Paying it on `pinColumns()`, a schema change or a
+    column resize — all of which call `queueRender` and none of which change the row order — is
+    not, and would read as the O(1)-in-rows claim quietly breaking.
+  
+    So the result is cached against the identities that actually determine it. Everything else
+    that triggers a render reuses it. With no sort set (the common case) the whole pipeline is
+    0.9ms and this never earns its keep — it exists for the case where the fix would otherwise
+    regress a real table.
+    */
+    _visibleMemo = null;
+    computeVisibleRows(baseData, groupId, sort) {
+        const memo = this._visibleMemo;
+        if (memo &&
+            memo.array === this._array &&
+            memo.filter === this._filter &&
+            memo.sort === sort &&
+            memo.groupId === groupId &&
+            memo.forcedIds === this._visibleGroupedRowIds) {
+            return memo.result;
+        }
+        let rows = this.filter(baseData);
+        /*
+        Forcing runs BEFORE the sort, so a row re-admitted by `visibleGroupedRowIds` is ordered
+        like any other row rather than being tacked on the end. It re-admits from the full
+        pre-filter set, which is what `baseData` now is.
+        */
+        if (groupId) {
+            rows = withForcedGroups(rows, baseData, groupId, this._visibleGroupedRowIds);
+        }
+        /*
+        `filter` defaults to `passThru`, which returns the SAME array — sorting it in place would
+        reorder the caller's data. Copy only when we are about to mutate.
+        */
+        if (sort)
+            rows = rows.slice().sort(sort);
+        // Clustering LAST — the spec is "grouped, then sorted within the grouping", so any other
+        // sort is applied first and survives inside each group.
+        if (groupId)
+            rows = clusterByGroup(rows, groupId);
+        // The window, last: it is a layout ceiling on what gets DRAWN.
+        const limit = this.maxVisibleRows;
+        if (rows.length > limit) {
+            if (!this._warnedTruncation) {
+                this._warnedTruncation = true;
+                console.warn(`<tosi-table> is showing ${limit.toLocaleString()} of ${rows.length.toLocaleString()} matching rows.\n` +
+                    `  maxVisibleRows is ${limit.toLocaleString()}${this._maxVisibleRows === undefined
+                        ? ` — derived from this browser's maximum element height (${probeMaxElementHeight().toLocaleString() || 'unknown'}px) at rowHeight ${this.rowHeight}.`
+                        : ' — set explicitly on this element.'}\n` +
+                    `  Filtering and sorting run over the FULL set, so the rows shown are the right\n` +
+                    `  ones — there are simply more of them than the browser can lay out. Raise it\n` +
+                    `  with \`table.maxVisibleRows = n\`, or narrow the filter.`);
+            }
+            rows = rows.slice(0, limit);
+        }
+        this._visibleMemo = {
+            array: this._array,
+            filter: this._filter,
+            sort,
+            groupId,
+            forcedIds: this._visibleGroupedRowIds,
+            result: rows,
+        };
+        return rows;
+    }
     _nonRepeatingGroupedRowCells = null;
     // Optional explicit arrays of pinned items. When set, they are managed
     // separately from `array` and override the `pinnedTop` / `pinnedBottom`
@@ -3073,25 +3143,13 @@ export class TosiTable extends WebComponent {
         const pinnedTopData = this.effectivePinnedTopData;
         const pinnedBottomData = this.effectivePinnedBottomData;
         const baseData = this.effectiveBaseData;
-        const limit = this.maxVisibleRows;
-        const cap = Math.min(baseData.length, limit);
         /*
-        Say so when rows are dropped. Truncating in silence meant the table disagreed with the
-        data and nothing anywhere said why — every count, filter and sort then ran on the
-        truncated set, so the numbers were self-consistent and wrong (#82).
-    
-        Once per table, and only when it actually bites: a notice on every render of every table
-        is how a warning becomes something people filter.
+        The truncation warning moved into `computeVisibleRows`, where the window is now applied
+        (#147). It has to be counted against the FILTERED set: "showing 10,000 of 300,000 rows"
+        is alarming and wrong once the filter has already narrowed things to 40. Kept as a
+        once-per-table notice — one on every render of every table is how a warning becomes
+        something people filter (#82).
         */
-        if (cap < baseData.length && !this._warnedTruncation) {
-            this._warnedTruncation = true;
-            console.warn(`<tosi-table> is showing ${cap.toLocaleString()} of ${baseData.length.toLocaleString()} rows.\n` +
-                `  maxVisibleRows is ${limit.toLocaleString()}${this._maxVisibleRows === undefined
-                    ? ` — derived from this browser's maximum element height (${probeMaxElementHeight().toLocaleString() || 'unknown'}px) at rowHeight ${this.rowHeight}.`
-                    : ' — set explicitly on this element.'}\n` +
-                `  Raise it with \`table.maxVisibleRows = n\`. Beyond the layout ceiling the\n` +
-                `  spacer stops growing, so the far end simply cannot be scrolled to.`);
-        }
         /*
         A big table with no `rowHeight` is a misconfiguration, not a use case (#84).
     
@@ -3120,29 +3178,35 @@ export class TosiTable extends WebComponent {
                 `  depending on row count at all — virtual tables are O(1) in rows.\n` +
                 `  rowHeight 0 is for SMALL tables and for variable row heights.`);
         }
-        const scope = baseData.slice(0, cap);
         // Fresh per render — see `_groupIdMemo`. Must happen before `groupIdFn` is read.
         this._groupIdMemo = new WeakMap();
         const groupId = this.groupIdFn;
-        let visibleData = this.filter(scope);
+        const { sort } = this;
         /*
-        Forcing runs BEFORE the sort, so a row re-admitted by `visibleGroupedRowIds` is ordered
-        like any other row rather than being tacked on the end.
+        ORDER: filter → force → sort → cluster → WINDOW (#147).
+    
+        `maxVisibleRows` used to be applied FIRST, so both the filter and the sort saw only the
+        first N rows. Two consequences a user would call bugs, and both were reported from
+        production at 300k rows:
+    
+          - a matching row past the cap could never be found. Search for a company appended to
+            the end of a 12,000-row list, with the cap at 10,000, and it does not exist.
+          - sorting did not sort the table. You got the first N rows in DATA order, arranged
+            nicely — not the top N by the sort.
+    
+        The comment on the truncation warning above already said this ("every count, filter and
+        sort then ran on the truncated set, so the numbers were self-consistent and wrong"), and
+        #82's answer was to warn. A warning does not help someone whose search returns nothing.
+    
+        The window is a LAYOUT ceiling — the browser's maximum element height — so it belongs at
+        the end, against what will actually be shown, not at the start against the data.
         */
+        const visibleData = this.computeVisibleRows(baseData, groupId, sort);
         if (groupId) {
-            visibleData = withForcedGroups(visibleData, scope, groupId, this._visibleGroupedRowIds);
-        }
-        const { sort } = this;
-        if (sort)
-            visibleData.sort(sort);
-        // Clustering LAST — the spec is "grouped, then sorted within the grouping", so any
-        // other sort is applied first and survives inside each group.
-        if (groupId) {
-            visibleData = clusterByGroup(visibleData, groupId);
             this._grouping = groupRenderMeta(visibleData, groupId);
-            // Counted from `scope` (pre-filter) against the final rendered set, and assigned
-            // BEFORE the rows below are stamped, so a cell renderer can read it as it renders.
-            this._rowGroupCounts = groupCounts(scope, visibleData, groupId);
+            // Counted from the full PRE-FILTER set against the rendered set, and assigned BEFORE
+            // the rows below are stamped, so a cell renderer can read it as it renders.
+            this._rowGroupCounts = groupCounts(baseData, visibleData, groupId);
         }
         else {
             this._grouping = null;

package/dist/doc-browser-entry.d.ts

@@ -0,0 +1,2 @@
+import './doc-system/doc-system.js';
+export * from './doc-browser.js';

package/dist/doc-browser-entry.js

@@ -0,0 +1,28 @@
+/*
+The entry behind `tosijs-ui/doc-browser`.
+
+This exists because that import — the one EVERY adoption doc tells you to write, and the one
+the build's own remediation warning prints when it detects a missing doc system — did not
+define `<tosi-doc-system>`.
+
+`doc-browser.ts` is a library module: types, helpers, and the `createDocBrowser()` factory. The
+custom element lives in `doc-system/doc-system.ts`, which imports FROM `doc-browser.ts`. The
+dependency arrow runs the wrong way, so the documented import could never reach the registrar
+however it was written.
+
+The result was precisely the failure mode the adoption page warns about, and it is disguised by
+being a PARTIAL success: `tosi-sidenav`, `tosi-example` and the other leaf components do
+register, so the bundle looks healthy, pages serve 200, and `<tosi-doc-system>` sits in the
+markup inert. The expensive half is quieter — no doc system means no `window.__docTestResults`,
+so an adopter's entire inline doc-test corpus silently stops existing. The suite does not fail;
+it reports nothing. Two projects hit this independently (#158, #159), one of them reaching a
+release candidate before anyone noticed.
+
+A SEPARATE FILE, not a side-effect import inside `doc-browser.ts`: that would be a genuine
+import cycle (doc-system → doc-browser → doc-system). It would probably work, because
+`doc-system.ts` uses `createDocBrowser` only inside methods — but "probably works, depending on
+evaluation order after your bundler reorders it" is not a thing to put under the one import
+every adopter is told to write. Nothing here depends on evaluation order.
+*/
+import './doc-system/doc-system.js';
+export * from './doc-browser.js';

package/dist/doc-browser.d.ts

@@ -10,6 +10,20 @@ export interface DocTestResults {
     passed: number;
     failed: number;
     pages: Record<string, PageTestResults>;
+    /**
+     * How many pages the runner INTENDED to run, and how many reported back.
+     *
+     * `passed + failed > 0` only proves the runner started. It cannot tell a full corpus from
+     * a corpus that silently lost half its pages — and a page-selection defect that ran 16 of
+     * 17 pages is exactly the false green fixed in 1.14.0, so this is a live failure mode
+     * rather than a hypothetical one. A consumer gate should assert
+     * `pagesTested === pagesWithTests && pagesWithTests > 0`.
+     *
+     * Framed by tosijs-platform in #142: "we didn't look" and "we looked and it's fine" must
+     * not produce the same output. Reporting a total is how a skipped run stays comfortable.
+     */
+    pagesWithTests: number;
+    pagesTested: number;
 }
 declare global {
     interface Window {

package/dist/doc-browser.js

@@ -488,6 +488,8 @@ export function createDocBrowser(options) {
                 passed: 0,
                 failed: 0,
                 pages: pageTestResults,
+                pagesWithTests,
+                pagesTested,
             };
             for (const pageResults of Object.values(pageTestResults)) {
                 allResults.passed += pageResults.totalPassed;
@@ -1723,7 +1725,13 @@ export function createDocBrowser(options) {
         }
         if (pagesWithTests === 0) {
             if (testResultsResolve) {
-                testResultsResolve({ passed: 0, failed: 0, pages: {} });
+                testResultsResolve({
+                    passed: 0,
+                    failed: 0,
+                    pages: {},
+                    pagesWithTests: 0,
+                    pagesTested: 0,
+                });
                 testResultsResolve = undefined;
             }
             return;
@@ -1826,7 +1834,13 @@ export function createDocBrowser(options) {
                 setTimeout(() => markPageTested(currentDoc.filename), 2000);
             }
             else if (testResultsResolve) {
-                testResultsResolve({ passed: 0, failed: 0, pages: {} });
+                testResultsResolve({
+                    passed: 0,
+                    failed: 0,
+                    pages: {},
+                    pagesWithTests: 0,
+                    pagesTested: 0,
+                });
                 testResultsResolve = undefined;
             }
         }

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

@@ -48,3 +48,19 @@ export declare function resolveParent(parentValue: string, docs: Array<{
     filename: string;
     title?: string;
 }>, slugMap: Record<string, string>): string;
+/**
+ * Prefix a root-relative path with the site's `basePath`.
+ *
+ * THE ONE COPY. There were two identical implementations (`generate-site.ts`, `epub.ts` —
+ * the latter's comment said "mirrors generate-site's withBase") and a third consumer,
+ * `make-llms-txt.ts`, that had none at all. So `baseUrl` meant the ORIGIN to the page
+ * generator and ORIGIN-PLUS-PATH to llms.txt, and on a GitHub project page no configuration
+ * satisfied both: matching the canonical URLs doubled the prefix in llms.txt, and matching
+ * llms.txt dropped it from every canonical and sitemap entry (tosijs-ui#144).
+ *
+ * Nothing failed — `basePath` affects metadata only, so the site works and you find it by
+ * reading the emitted `<head>`. The reporter's shipped to Pages before they noticed.
+ *
+ * `baseUrl` is the ORIGIN ONLY. Absolute URLs and an empty/`/` basePath pass through.
+ */
+export declare function withBase(basePath: string | undefined, p: string): string;

package/dist/doc-system/routing.js

@@ -128,3 +128,23 @@ export function resolveParent(parentValue, docs, slugMap) {
             return d.filename;
     return '';
 }
+/**
+ * Prefix a root-relative path with the site's `basePath`.
+ *
+ * THE ONE COPY. There were two identical implementations (`generate-site.ts`, `epub.ts` —
+ * the latter's comment said "mirrors generate-site's withBase") and a third consumer,
+ * `make-llms-txt.ts`, that had none at all. So `baseUrl` meant the ORIGIN to the page
+ * generator and ORIGIN-PLUS-PATH to llms.txt, and on a GitHub project page no configuration
+ * satisfied both: matching the canonical URLs doubled the prefix in llms.txt, and matching
+ * llms.txt dropped it from every canonical and sitemap entry (tosijs-ui#144).
+ *
+ * Nothing failed — `basePath` affects metadata only, so the site works and you find it by
+ * reading the emitted `<head>`. The reporter's shipped to Pages before they noticed.
+ *
+ * `baseUrl` is the ORIGIN ONLY. Absolute URLs and an empty/`/` basePath pass through.
+ */
+export function withBase(basePath, p) {
+    if (!p || !basePath || basePath === '/' || /^(https?:)?\/\//.test(p))
+        return p;
+    return basePath.replace(/\/$/, '') + (p.startsWith('/') ? p : '/' + p);
+}

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

@@ -17,7 +17,7 @@ Build-time only (Bun APIs + the `zip` CLI); never import from browser code.
 import * as fs from 'fs';
 import * as path from 'path';
 import { renderDocMarkdown } from '../render.js';
-import { buildSlugMap, pathForSlug, slugForPath } from '../routing.js';
+import { buildSlugMap, pathForSlug, slugForPath, withBase } from '../routing.js';
 import { buildNavTree } from '../nav-tree.js';
 import { partitionByBook, DEFAULT_BOOK } from '../book-target.js';
 import { epubVolumeIdentity } from './epub-volumes.js';
@@ -159,12 +159,6 @@ function collectExamplePres(el, out) {
         }
     }
 }
-/** Prefix a root-relative path with basePath (mirrors generate-site's withBase). */
-function withBase(basePath, p) {
-    if (!p || !basePath || basePath === '/' || /^(https?:)?\/\//.test(p))
-        return p;
-    return basePath.replace(/\/$/, '') + (p.startsWith('/') ? p : '/' + p);
-}
 /**
  * Rewrite in-book cross-links so they resolve INSIDE the EPUB (#15). renderDocMarkdown
  * emits site paths — `/slug/` (wikilinks + the auto-generated section TOCs) and legacy

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

@@ -74,6 +74,14 @@ export interface GenerateSiteConfig {
     /** extra lines injected into every <head> (favicon, analytics, etc.) */
     headExtra?: string;
 }
+/**
+ * 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`.
+ */
 /**
  * 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/`

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

@@ -11,7 +11,7 @@ Build-time only (uses Bun.write). Shares slug + markdown rendering with the runt
 component (src/doc-system/*) so static and hydrated output agree.
 */
 import { pageTitle } from '../doc-title.js';
-import { buildSlugMap, pathForSlug, rewriteDocLinks } from '../routing.js';
+import { buildSlugMap, pathForSlug, rewriteDocLinks, withBase, } from '../routing.js';
 import { buildNavTree, navOpenPath } from '../nav-tree.js';
 import { renderDocMarkdown, docDescription, } from '../render.js';
 const escapeAttr = (s) => s
@@ -83,11 +83,7 @@ function absUrl(baseUrl, pathOrUrl) {
  * 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);
-}
+// `withBase` now lives in ../routing.ts — see the note there (#144).
 /**
  * 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/`

package/dist/doc-system/site/host-preset.d.ts

@@ -11,3 +11,43 @@ export interface HostConfigMismatch {
  * multi-site config that serves the built directory from any of its targets is fine.
  */
 export declare function firebasePublicMismatch(firebaseJson: string, outputDir: string): HostConfigMismatch | null;
+/**
+ * `baseUrl` is the ORIGIN; `basePath` is the mount path. Supplying the path in BOTH is
+ * always wrong and always silent: `generate-site` emits `baseUrl + withBase(basePath, …)`,
+ * so every canonical URL, `og:url` and sitemap entry carries the prefix twice.
+ *
+ * Nothing fails — `basePath` affects metadata only (#25), so the site builds, serves and
+ * navigates correctly with assets resolving relative. You find it by reading the emitted
+ * `<head>`, or from Search Console. The reporter's shipped to GitHub Pages first (#144).
+ *
+ * Warns rather than throws: the emitted site is usable, and refusing to build over a
+ * metadata defect would be disproportionate. But it names the exact fix, because "these two
+ * fields overlap" is not something a reader can act on.
+ */
+export declare function basePathDoubling(config: {
+    baseUrl?: string;
+    basePath?: string;
+}): string | undefined;
+/**
+ * Does a custom `bundleEntry` bundle actually contain the doc system?
+ *
+ * `bundleEntry` REPLACES tosijs-ui's bundle rather than extending it, so an entry that
+ * imports only the adopter's own library produces a site where every page renders its
+ * prerendered markup and nothing else: no header, no nav, no menu, no live examples. Nothing
+ * fails — `docs.json`, `hydrate.js` and the HTML all serve 200, `<tosi-doc-system>` is
+ * present in the markup, and the adopter's own `customElements.get('their-element')` returns
+ * true, so the bundle looks healthy. It is inert because nothing defined `tosi-doc-system`
+ * (tosijs-ui#145; cost the reporter more than any other onboarding problem).
+ *
+ * Checked by looking for the tag names in the built output, which survives minification
+ * because `customElements.define` needs the literal string. This is the one case where
+ * grepping a bundle is sound — we are looking for a STRING the runtime must contain, not for
+ * a package path that minification erases.
+ *
+ * `liveExample` is reported separately: a corpus with no executable fences legitimately does
+ * not need it, so the caller decides whether its absence is worth mentioning.
+ */
+export declare function bundleRegistrations(bundleSource: string): {
+    docSystem: boolean;
+    liveExample: boolean;
+};