tosijs-ui 1.16.6 → 1.16.8

package/CHANGELOG.md

@@ -1,5 +1,149 @@
 # Changelog
 
+## 1.16.8
+
+A patch for honest results. The doc-test lane can no longer pass over pages that never
+reported, three more of tjs-lang's findings are fixed, and an example that only logs now
+shows what it logged. Two things to know on upgrade: `ts` examples lose tjs's runtime
+parameter guards (below), and one thing may newly go red: a doc-test
+run that was silently losing pages will now fail and name them. `dist/iife.js` grows by
+1.0 kB gzip (484.0 → 485.0 kB).
+
+### Three more from tjs-lang's sweep of its own site (#210)
+
+- **Inline tjs tests ran with plain-JavaScript semantics**, so passing tests were shown
+  failing: `"hello world".capitalize is not a function` for a local `extend`, `Expected false
+  but got true` for a boxed boolean. This release prepares the fix and tjs-lang delivers it:
+  an example's inline tests now use the runner `tjs()` itself returns, and from the tjs-lang
+  release after 0.14.0-rc.2 that runner is built from the rewritten test bodies. On 0.13.13,
+  which this release still pins, nothing changes.
+- **The `ts` dialect overrode converted TypeScript's semantics.** It passed `dialect: 'tjs'`
+  to `tjs()`, which outranks the annotation `fromTS` writes, so a TS example's
+  `new Calculator(…)` was refused as native TJS. It now passes no dialect. **This changes
+  what every `ts` example does at run time:** converted TypeScript now has JavaScript's
+  semantics, so the runtime parameter guards are gone too. `add('a', 2)` with
+  `(a: number, b: number)` returned a type error before and returns `'a2'` now, as it would
+  in TypeScript. `tjs` examples are unaffected.
+- **An example whose output is only `console.log` was an empty box.** When a run finishes with
+  nothing rendered into its preview, the lines it logged (and its inline-test summary, when
+  one was run) are shown where the preview would be. It steps aside when the example renders
+  anything, never writes into `preview`, and follows the existing console switches. Inline
+  examples only: an `:iframe` example's output stays in its Console tab.
+
+Not in this release: examples written as modules (`export const x = …`) still fail. Stripping
+`export` safely needs a JavaScript parser, which tosijs-ui does not ship; tjs-lang already
+bundles one, so the ask is with them to export their stripper.
+
+### The doc-test lane can no longer pass over pages that reported nothing (#2874)
+
+The background test runner counted a page as tested when it finished or timed out, whether or
+not any results arrived, and the lane passed on "0 failed". A run once passed with results for
+7 of 19 pages.
+
+- A page with test blocks that reports no tests, or does not finish within 45 seconds, is now
+  recorded as a failed test naming the page and the reason. A page that timed out after some
+  of its examples had reported was still recorded as a pass in the first cut of this fix; a
+  timeout now fails the page whatever had reported.
+- The parent waited 30 seconds per page, the same as the frame's own stall timeout, so a
+  stall report could arrive just after the parent moved on. The page budget is now 45s.
+- Which pages have tests is decided by parsing the markdown the way the page is rendered. A
+  ` ```test ` line shown inside a longer or `:static` block no longer makes a page count as
+  one with tests.
+- `bun run test-browser` now exits non-zero unless every page with tests has recorded results,
+  and prints how many pages its count covers.
+- The page a run starts on is tested in place, by its own code path. That path replaced the
+  page's results each time one example finished, so the last example was the whole page and
+  a failing earlier one could vanish; and it marked the page tested on a timer. It now adds
+  its examples up and waits for all of them, by the same rule the iframes use. A deployed
+  (non-localhost) page with tests enabled follows the same rule.
+- The runner accepted `tosi-test-results` messages from any window on the page; it now
+  requires its own test frame as the source.
+- `testReportVerdict` is exported from `tosijs-ui/site` for adopters' own gates. A gate that
+  checks only `failed === 0` should also require results for every page with tests.
+
+## 1.16.7
+
+A patch for readers that are not browsers, and for builds that were too polite. Every doc page
+now also ships as markdown, for LLM fetchers that fail on ordinary HTML. Two misconfigurations
+tjs-lang found the hard way now say so, and `strict: true` turns the build's warnings into
+failures. Nothing to change on upgrade: `markdownPages` is on by default and adds files only;
+`strict` is off by default. `dist/iife.js` grows by 0.3 kB gzip (483.7 → 484.0 kB).
+
+### Every doc page also ships as markdown
+
+The site build now writes each page's markdown source beside its HTML, at
+`/{slug}/index.md`, links it from the page with
+`<link rel="alternate" type="text/markdown" href="index.md">`, and says so in `llms.txt`.
+It is for readers that want the text and not the page: an LLM's URL fetcher, a script, `curl`.
+Prompted by one such fetcher reporting "no `<body>`" for a page whose whole article was in the
+static HTML.
+
+- On by default; `markdownPages: false` in the site config ships HTML only. It adds one file
+  per page: on this repo's site, 70 files and 0.5 MB, about 3% of the output.
+- The file is the page's source as written, so HTML comments and metadata blocks in a doc
+  are served as text. If a page's source holds something its rendered page does not show,
+  mark it `noindex` or turn this off.
+- A `noindex` page gets neither the file nor the link.
+- The build now writes `.nojekyll` whenever markdown pages are on, not only under
+  `host: 'github-pages'`. Without it, GitHub Pages' Jekyll would render `index.md` over the
+  real page. The file is empty and harmless on other hosts.
+
+### Misconfigurations the build and the page used to accept in silence (#210)
+
+Two reported by tjs-lang, whose site ran every example against the wrong tjs-lang for weeks
+without being told.
+
+- **The same-origin tjs-lang copy was skipped without a word.** When `tjs-lang/browser`
+  cannot be resolved, nothing is written to `/tjs/`, and `tjs`/`ts` examples load tjs-lang
+  from a CDN at the version tosijs-ui pins. The build now warns when the corpus has live
+  `tjs` or `ts` examples and that happens. A corpus with none stays quiet.
+- **A custom `bundleEntry` silently dropped what examples import.** It replaces the bundle
+  that set the `xinjs`/`xinjsui` globals, so `import { elements } from 'tosijs'` in an example
+  failed with "Cannot destructure property 'elements' of 'tosijs'". Examples now get `tosijs`
+  from the doc system's own copy. `tosijs-ui` still has to be supplied by the entry (importing
+  it here would put every component in every doc site's bundle), and an example that imports
+  it without one now fails with a message naming the module and the two lines that fix it,
+  whether it is met in the example or its tests. The cost of the
+  `tosijs` fallback is 0.3 kB gzip on this site's own bundle.
+
+### `strict: true` makes the build fail on what it otherwise warns about
+
+A new site-config option, default `false`. With it, `buildSite` throws
+`SiteMisconfiguredError` when `bundleEntry` does not register `<tosi-doc-system>`, when the
+corpus has executable fences and `bundleEntry` does not register `<tosi-example>`, or when
+the tjs-lang copy above is skipped on a corpus that needs it. Warning stays the default
+because each is a legitimate thing to do on purpose; this is for a project that never does.
+Asked for by tosijs-product, whose inert-bundle blocker reached a release candidate under a
+green build. `SiteMisconfiguredError` is exported from `tosijs-ui/site`, so a caller can tell a
+refused misconfiguration from a crash.
+
+Whether a corpus "has executable fences" is now decided by the same rule the page uses, under
+the site's `liveExamples` policy. The build's warning used a narrower pattern of its own: it
+counted a bare `js` fence on an opt-in site, and missed `js:iframe`, `html`, `css`, `~~~`
+fences and registered dialects. `llms.txt`'s note about live examples follows the same rule.
+
+### Found by the pre-tag review, fixed before release
+
+None of these ever shipped; they are listed so the notes account for every fix in the release.
+
+- `liveFenceLanguages` found no fences in a CRLF corpus and disagreed with the renderer on
+  blockquoted, indented and commented-out fences, because it scanned lines. It now reads
+  marked's tokens through `collectCodeTokens`, shared with check-examples.
+- The missing-module error covered the example only; tests and inline tjs tests still got the
+  destructuring error. They now go through `rewriteContextImports`, and the check matches a
+  real import statement, not a commented-out one.
+- The Console REPL keeps plain `rewriteImports`: the checking variant threw outside the `try`
+  that prints REPL errors, so a line importing an unsupplied module printed nothing.
+- A failed copy of the tjs-lang bundles shared a `catch` with resolution and would have been
+  reported as "could not be resolved"; only resolution is caught now.
+
+### `<meta charset>` is back in the first 1024 bytes of every page
+
+Two explanatory HTML comments at the top of each generated page's `<head>` had pushed the
+charset declaration to about byte 1550; the HTML spec wants it within the first 1024. The
+comments now live in the generator's source, and charset and viewport lead the head. Every
+page is about 1.4 kB smaller.
+
 ## 1.16.6
 
 A one-fix patch: a link to the page you are already on no longer adds a history entry that Back

package/dist/doc-browser.d.ts

@@ -1,5 +1,6 @@
 import { TestResults } from './live-example/test-harness.js';
-export declare const hasTestBlock: (text: string | undefined) => boolean;
+import { type ExamplePolicy } from './doc-system/example-policy.js';
+export declare const hasTestBlock: (text: string | undefined, policy?: ExamplePolicy) => boolean;
 export interface PageTestResults {
     passed: boolean;
     tests: TestResults['tests'];

package/dist/doc-browser.js

@@ -156,10 +156,12 @@ import { buildSlugMap, pathForSlug, filenameForPath, } from './doc-system/routin
 import { buildNavTree } from './doc-system/nav-tree.js';
 import { renderDocMarkdown } from './doc-system/render.js';
 import { pageTitle } from './doc-system/doc-title.js';
-import { unsettledExamples } from './doc-system/test-completion.js';
+import { unsettledExamples, tallyExamples, closePage, } from './doc-system/test-completion.js';
 import { LiveExample, testManager, pageTestCount, enableTests, disableTests, } from './live-example.js';
 import { highlightBlocks } from './doc-system/highlight.js';
 import { examplePolicy } from './live-example/insert-examples.js';
+import { collectCodeTokens } from './doc-system/code-fences.js';
+import { isLiveFence } from './doc-system/example-policy.js';
 import { tosiSidenav, TosiSidenav } from './side-nav.js';
 import { icons } from './icons.js';
 import { tosiLocalized } from './localize.js';
@@ -183,8 +185,17 @@ standalone run reporting "62 passed" against a build the full suite failed on.
 A fence is only a fence at the start of a line, which is the rule the doc extractor already
 applies to `/*#`. `[ \t]*` allows the indented fences that appear inside list items.
 */
-const TEST_FENCE = /^[ \t]*```test[ \t]*$/m;
-export const hasTestBlock = (text) => typeof text === 'string' && TEST_FENCE.test(text);
+/*
+…and a line-anchored regex was not the rule either (#2874). A ` ```test ` line SHOWN inside a
+longer or `:static` block matched it, so a page that documents the test tier was counted as a
+page with tests, ran in a background iframe, reported nothing, and was counted as tested. The
+lane said "19 of 19 pages" over results for 18. Code blocks now come from marked, the parser
+the page is rendered with, and liveness from `isLiveFence`, under the site's policy.
+*/
+export const hasTestBlock = (text, policy = 'auto') => typeof text === 'string' &&
+    // Cheap reject first: lexing every doc in a large corpus is not free.
+    text.includes('test') &&
+    collectCodeTokens(text).some((t) => t.lang === 'test' && isLiveFence('test', t.mode, policy));
 const { div, span, a, header, button, template, input, h2, img, details, summary, ul, li, } = elements;
 /*
 Test colors, and the text color that goes ON each — because contrast is a PAIR.
@@ -498,10 +509,15 @@ export function createDocBrowser(options) {
     let refreshNav = () => { };
     // Test result tracking
     const pageTestResults = {};
+    // The per-example results behind the entry for the page the reader is on.
+    let liveResults = new Map();
+    let liveResultsFile = '';
     let testResultsResolve;
     let backgroundTestsStarted = false;
     let pagesWithTests = 0;
     let pagesTested = 0;
+    // Per-page budget for the background runner; see the wait loop for why it exceeds 30s.
+    const PAGE_DEADLINE_MS = 45_000;
     // Set up global promise for scriptable browser integration. A memory-routed
     // (embedded) browser must not clobber the host page's global.
     if (!memoryRouting) {
@@ -554,15 +570,93 @@ export function createDocBrowser(options) {
     const handleTestComplete = (event) => {
         const { results } = event.detail;
         const filename = String(app.currentDoc.filename);
-        // Reset page results each time (don't accumulate across reloads)
-        pageTestResults[filename] = {
-            passed: results.failed === 0,
-            tests: [...results.tests],
-            totalPassed: results.passed,
-            totalFailed: results.failed,
-        };
+        /*
+        One entry per EXAMPLE, added up — `testcomplete` fires once for each. This used to
+        replace the page's entry on every event, so the last example to finish was the whole
+        page: a failing first example followed by a passing second one reported green.
+    
+        Keyed by element, so an example that re-runs (an edit, a refresh) replaces its own
+        result and nothing else's. A different page starts a fresh tally, and elements no longer
+        in the document are dropped first.
+        */
+        if (liveResultsFile !== filename) {
+            liveResultsFile = filename;
+            liveResults = new Map();
+        }
+        // Navigating away and back re-creates the page's examples; the old elements are gone
+        // from the document and their results must go with them, or the page counts double.
+        for (const element of liveResults.keys()) {
+            if (!element.isConnected)
+                liveResults.delete(element);
+        }
+        liveResults.set(event.detail.element, results);
+        pageTestResults[filename] = tallyExamples(liveResults.values());
         updateDocTestStatus(filename);
     };
+    /*
+    When has the page now rendered in THIS document finished its tests? Resolves with the
+    examples that never settled (empty when all did).
+  
+    One definition, used by a test iframe to signal its parent, by the page the reader is on,
+    and by a deployed page — the latter two used to be a flat timer, which marked a page tested
+    whether or not anything had reported.
+  
+    The census is only as good as the DOM it reads. Examples are inserted into the page as it
+    renders, so a census taken while insertion is still in progress sees FEWER examples than the
+    page has — and an example that appears afterwards was never waited on, never reported, and
+    never missed. So the count must be observed to STOP GROWING before "done" means anything:
+    two consecutive equal censuses, and a third example arriving later restarts the requirement.
+    */
+    const whenPageSettled = (deadlineMs) => new Promise((resolve) => {
+        const startedAt = Date.now();
+        let previousCount = -1;
+        let stableCensuses = 0;
+        const census = () => {
+            const examples = [...container.querySelectorAll('tosi-example')];
+            if (examples.length === previousCount)
+                stableCensuses++;
+            else
+                stableCensuses = 0;
+            previousCount = examples.length;
+            const stalled = unsettledExamples(examples.map((ex) => ({
+                element: ex,
+                test: ex.test,
+                hasTests: ex.classList.contains('-has-tests'),
+                testRunning: ex.classList.contains('-test-running'),
+            })));
+            const settling = stalled.length > 0 || stableCensuses < 2;
+            if (settling && Date.now() - startedAt < deadlineMs) {
+                setTimeout(census, 100);
+                return;
+            }
+            resolve(stalled.map(({ element }) => element));
+        };
+        // Give the page a moment to insert its examples before the first census.
+        setTimeout(census, 500);
+    });
+    /*
+    The page the reader is on runs its tests in place. Wait for them the way a test iframe is
+    waited for, then close the entry by the same rule (`closePage`): examples that never
+    settled, or no results at all, are failures with a name.
+    */
+    const settleCurrentPage = async (filename) => {
+        const stalled = await whenPageSettled(PAGE_DEADLINE_MS);
+        /*
+        If the reader navigated away, the census was of ANOTHER page and says nothing about this
+        one. Whatever this page had reported stands, and if it reported nothing no failure is
+        invented for it: the report then has one page fewer than it should, which is the honest
+        statement ("we did not look") and is what `testReportVerdict` fails on.
+        */
+        if (String(app.currentDoc.filename) === filename) {
+            pageTestResults[filename] = closePage(pageTestResults[filename], {
+                timedOut: false,
+                deadlineMs: PAGE_DEADLINE_MS,
+                stalled: stalled.length,
+            });
+            updateDocTestStatus(filename);
+        }
+        markPageTested(filename);
+    };
     // Track when a page finishes loading all its tests
     const markPageTested = (_filename) => {
         pagesTested++;
@@ -1769,36 +1863,7 @@ export function createDocBrowser(options) {
     if (isTestFrame && testFrameFilename) {
         // Generous: this bounds a hung example, it does not pace a slow one.
         const STALL_TIMEOUT_MS = 30000;
-        const startedAt = Date.now();
-        /*
-        The census is only as good as the DOM it reads. Examples are inserted into the page as
-        it renders, so a census taken while insertion is still in progress sees FEWER examples
-        than the page has — and an example that appears afterwards was never waited on, never
-        reported, and never missed. That is the same silent-loss failure as the bug above, one
-        step earlier, so the count must be observed to STOP GROWING before "done" means
-        anything. Two consecutive equal censuses is enough; a third example arriving later
-        restarts the requirement.
-        */
-        let previousCount = -1;
-        let stableCensuses = 0;
-        const signalDone = () => {
-            const examples = [...container.querySelectorAll('tosi-example')];
-            if (examples.length === previousCount)
-                stableCensuses++;
-            else
-                stableCensuses = 0;
-            previousCount = examples.length;
-            const stalled = unsettledExamples(examples.map((ex) => ({
-                element: ex,
-                test: ex.test,
-                hasTests: ex.classList.contains('-has-tests'),
-                testRunning: ex.classList.contains('-test-running'),
-            })));
-            const settling = stalled.length > 0 || stableCensuses < 2;
-            if (settling && Date.now() - startedAt < STALL_TIMEOUT_MS) {
-                setTimeout(signalDone, 100);
-                return;
-            }
+        void whenPageSettled(STALL_TIMEOUT_MS).then((stalled) => {
             /*
             Past the deadline with examples still unsettled: report them as failures rather than
             signalling a done that omits them. An example that never finishes is a real defect —
@@ -1812,7 +1877,7 @@ export function createDocBrowser(options) {
                     results: {
                         passed: 0,
                         failed: stalled.length,
-                        tests: stalled.map(({ element }) => ({
+                        tests: stalled.map((element) => ({
                             name: `example never finished running (${STALL_TIMEOUT_MS}ms)`,
                             passed: false,
                             error: `The example's code did not complete, so its test block never ran. Its source begins: ${String(element.js ?? '').slice(0, 120)}`,
@@ -1821,9 +1886,7 @@ export function createDocBrowser(options) {
                 }, '*');
             }
             window.parent.postMessage({ type: 'tosi-tests-done', filename: testFrameFilename }, '*');
-        };
-        // Give the page a moment to insert its examples before taking the census.
-        setTimeout(signalDone, 500);
+        });
     }
     // Background test runner for all doc pages
     const runBackgroundTests = async () => {
@@ -1847,7 +1910,7 @@ export function createDocBrowser(options) {
         exits 0. So a runtime error in an example on a page with no ` ```test ` block is caught by
         nothing. Tracked as its own issue rather than papered over by making this predicate loose.
         */
-        const docsWithTests = docs.filter((doc) => hasTestBlock(doc.text));
+        const docsWithTests = docs.filter((doc) => hasTestBlock(doc.text, examplePolicy()));
         pagesWithTests = docsWithTests.length;
         if (pagesWithTests > 0) {
             setTestWidgetRunning();
@@ -1895,6 +1958,9 @@ export function createDocBrowser(options) {
         const messageHandler = (event) => {
             if (event.data?.type !== 'tosi-test-results')
                 return;
+            // Only from OUR test frame: any other window on the page could otherwise post results.
+            if (event.source !== testFrame.contentWindow)
+                return;
             const { filename, results } = event.data;
             if (!pageTestResults[filename]) {
                 pageTestResults[filename] = {
@@ -1922,11 +1988,15 @@ export function createDocBrowser(options) {
                 routing === 'path'
                     ? `${window.location.origin}${hrefFor(doc.filename)}?_testMode=1`
                     : `${window.location.origin}${window.location.pathname}?${doc.filename}&_testMode=1`;
-            // Wait for the iframe to signal it's done (max 30s per page)
+            // Wait for the iframe to signal it's done. LONGER than the frame's own 30s stall
+            // timeout, so a frame that gives up on a hung example gets to say so: at the same 30s
+            // the two raced, and the parent could move on a moment before the stall report landed.
+            let timedOut = false;
             await new Promise((resolve) => {
-                const deadline = Date.now() + 30_000;
+                const deadline = Date.now() + PAGE_DEADLINE_MS;
                 const onDone = (event) => {
-                    if (event.data?.type === 'tosi-tests-done' &&
+                    if (event.source === testFrame.contentWindow &&
+                        event.data?.type === 'tosi-tests-done' &&
                         event.data.filename === doc.filename) {
                         window.removeEventListener('message', onDone);
                         resolve();
@@ -1935,17 +2005,24 @@ export function createDocBrowser(options) {
                 window.addEventListener('message', onDone);
                 setTimeout(() => {
                     window.removeEventListener('message', onDone);
+                    timedOut = true;
                     resolve();
                 }, deadline - Date.now());
             });
+            // A page that timed out fails even if some of its examples had reported (closePage).
+            pageTestResults[doc.filename] = closePage(pageTestResults[doc.filename], {
+                timedOut,
+                deadlineMs: PAGE_DEADLINE_MS,
+            });
+            updateDocTestStatus(doc.filename);
             markPageTested(doc.filename);
         }
         // Clean up
         window.removeEventListener('message', messageHandler);
         testFrame.remove();
-        // Mark current page as tested if it has tests
+        // The page the reader is on ran its tests in place; wait for them and close its entry.
         if (docsWithTests.some((d) => d.filename === currentFilename)) {
-            setTimeout(() => markPageTested(currentFilename), 1000);
+            void settleCurrentPage(currentFilename);
         }
     };
     // Run background tests when enabled (initially or when toggled on)
@@ -1956,11 +2033,20 @@ export function createDocBrowser(options) {
             setTimeout(runBackgroundTests, 1000);
         }
         else {
-            const currentHasTests = currentDoc.text.includes('```test');
+            /*
+            The page showing NOW, not the one this browser was constructed on. Tests are toggled
+            from the menu, often after navigating, and the construction-time doc then named a page
+            that is no longer on screen: it was judged by a census of some other page and recorded
+            as "reported no tests" without ever having run (1.16.8 re-review, F1).
+            */
+            const showing = String(app.currentDoc.filename);
+            const showingDoc = docs.find((d) => d.filename === showing);
+            const currentHasTests = hasTestBlock(showingDoc?.text, examplePolicy());
             if (currentHasTests) {
                 pagesWithTests = 1;
                 setTestWidgetRunning();
-                setTimeout(() => markPageTested(currentDoc.filename), 2000);
+                // Not a flat timer: the same settle-and-close rule as on localhost.
+                void settleCurrentPage(showing);
             }
             else if (testResultsResolve) {
                 testResultsResolve({

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

@@ -0,0 +1,5 @@
+export declare function collectCodeTokens(text: string): Array<{
+    lang: string;
+    text: string;
+    mode?: string;
+}>;

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

@@ -0,0 +1,41 @@
+/*
+THE way to enumerate the code blocks in a doc, build and client alike: marked's own lexer.
+
+`check-examples` had this function; `build-warnings` then grew a hand-written line scanner for
+the same job, and the 1.16.7 re-review found the scanner disagreeing with marked on CRLF files,
+blockquoted fences and fences inside HTML blocks. A scanner can only ever approximate the
+parser the pages are rendered with, so nothing here scans: every caller asks marked. The
+doc-browser's test runner asks here too (`hasTestBlock`), for the same reason.
+*/
+import { marked } from 'marked';
+import { parseFenceInfo } from './example-policy.js';
+/*
+Fence info is parsed by `parseFenceInfo`, the one copy of that grammar. This file had its own
+`dialectOf`/`modeOf` pair; once fences could carry JSON options (#184) `modeOf` would have read
+`{"debug":true}` as the mode `true`.
+*/
+export function collectCodeTokens(text) {
+    const out = [];
+    const walk = (tokens) => {
+        for (const t of tokens) {
+            /*
+            Keep the MODE. `dialectOf` reduced `js:static` to `js`, so the checker could not tell a
+            block that will never run from one that will — and hard-failed a build over the syntax
+            of illustrative code, advising the author to retag it as `typescript`, which is exactly
+            the mislabelling this release exists to abolish (review major M2).
+            */
+            if (t.type === 'code')
+                out.push({
+                    lang: parseFenceInfo(t.lang ?? '').lang,
+                    text: t.text,
+                    mode: parseFenceInfo(t.lang ?? '').mode,
+                });
+            if (Array.isArray(t.tokens))
+                walk(t.tokens);
+            if (Array.isArray(t.items))
+                walk(t.items); // list items
+        }
+    };
+    walk(marked.lexer(text));
+    return out;
+}

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

@@ -1,9 +1,10 @@
 import { ElementCreator } from 'tosijs';
+import * as tosijsModule from 'tosijs';
 import { Doc } from '../doc-browser.js';
 import './css-var-editor.js';
 export declare const CORPUS_ATTEMPTS = 3;
 export declare function fetchCorpus(url: string): Promise<Doc[]>;
-declare const TosiDocSystem_base: import("tosijs").WithAttributes<{
+declare const TosiDocSystem_base: tosijsModule.WithAttributes<{
     docs: string;
     config: string;
     localized: string;

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

@@ -57,6 +57,7 @@ A self-contained, controllable embed (e.g. docs in a floating panel):
 */
 /*{ "parent": "Appendices" }*/
 import { StyleSheet, elements, tosi, vars, withAttributes, } from 'tosijs';
+import * as tosijsModule from 'tosijs';
 import { createDocBrowser, } from '../doc-browser.js';
 import { buildSlugMap, legacyQueryPath } from './routing.js';
 import { buildBookHtml, slugify } from './book-html.js';
@@ -527,8 +528,19 @@ export class TosiDocSystem extends withAttributes({
                     this.route = slug;
                 }
                 : undefined,
+            /*
+            The iife sets `xinjs` / `xinjsui`; a site with its own `bundleEntry` has neither, and
+            examples there used to get `undefined` for both with no word said (#210 item 4).
+      
+            `tosijs` falls back to the copy this module already imports — the same instance the
+            page's components use, which is the one an example should share state with.
+            `tosijs-ui` has no such fallback on purpose: importing the barrel here would put every
+            component in every doc site's bundle (#133). A site that wants it in examples supplies
+            it, and an example that imports it without one now fails with a sentence saying so
+            (`assertContextProvided`).
+            */
             context: this.context || {
-                tosijs: globalThis.xinjs,
+                tosijs: globalThis.xinjs ?? tosijsModule,
                 'tosijs-ui': globalThis.xinjsui,
             },
             projectName: config.projectName,

package/dist/doc-system/site/build-warnings.d.ts

@@ -0,0 +1,23 @@
+import { type ExamplePolicy } from '../example-policy.js';
+/** Thrown by `misconfigured` under `strict`, so a caller can tell it from a crash. */
+export declare class SiteMisconfiguredError extends Error {
+    name: string;
+}
+/**
+ * Report a misconfiguration: a warning by default, a thrown `SiteMisconfiguredError` (which
+ * fails `buildSite`) when the site config sets `strict: true`.
+ */
+export declare function misconfigured(strict: boolean | undefined, message: string): void;
+/**
+ * The languages of the corpus's LIVE fences, under the site's example policy.
+ *
+ * Code blocks come from marked (`collectCodeTokens`), the parser the pages are rendered with,
+ * and liveness from `isLiveFence`, THE predicate. Neither is re-derived here: a second copy of
+ * the liveness rule is what disagreed when `:static` shipped, a regex of its own in the bundle
+ * guard is what the 1.16.7 review caught deciding a `strict` build, and the line scanner that
+ * first replaced it missed CRLF files and blockquoted fences. Every build-side "does this
+ * corpus have live examples?" asks here.
+ */
+export declare function liveFenceLanguages(docs: Array<{
+    text?: string;
+}>, policy?: ExamplePolicy): Set<string>;

package/dist/doc-system/site/build-warnings.js

@@ -0,0 +1,45 @@
+/*
+Things a site build can see are wrong and used to mention quietly, or not at all.
+
+A build that exits 0 with a warning in scrollback is how tosijs-product's 0.8.0 blocker reached
+a release candidate (#145, board #2543), and how tjs.tosijs.net ran every example against the
+wrong tjs-lang for weeks without anyone being told (#210). Warning stays the default, because
+each of these is a legitimate thing to do on purpose. `strict: true` in the site config is how a
+project that never does them on purpose says so, and then the build fails.
+*/
+import { isLiveFence } from '../example-policy.js';
+import { collectCodeTokens } from '../code-fences.js';
+/** Thrown by `misconfigured` under `strict`, so a caller can tell it from a crash. */
+export class SiteMisconfiguredError extends Error {
+    name = 'SiteMisconfiguredError';
+}
+/**
+ * Report a misconfiguration: a warning by default, a thrown `SiteMisconfiguredError` (which
+ * fails `buildSite`) when the site config sets `strict: true`.
+ */
+export function misconfigured(strict, message) {
+    if (strict) {
+        throw new SiteMisconfiguredError(`${message}\n    This fails the build because the site config sets \`strict: true\`.\n`);
+    }
+    console.warn(message);
+}
+/**
+ * The languages of the corpus's LIVE fences, under the site's example policy.
+ *
+ * Code blocks come from marked (`collectCodeTokens`), the parser the pages are rendered with,
+ * and liveness from `isLiveFence`, THE predicate. Neither is re-derived here: a second copy of
+ * the liveness rule is what disagreed when `:static` shipped, a regex of its own in the bundle
+ * guard is what the 1.16.7 review caught deciding a `strict` build, and the line scanner that
+ * first replaced it missed CRLF files and blockquoted fences. Every build-side "does this
+ * corpus have live examples?" asks here.
+ */
+export function liveFenceLanguages(docs, policy = 'auto') {
+    const langs = new Set();
+    for (const doc of docs) {
+        for (const { lang, mode } of collectCodeTokens(doc.text ?? '')) {
+            if (lang && isLiveFence(lang, mode, policy))
+                langs.add(lang);
+        }
+    }
+    return langs;
+}