tosijs-ui 1.16.7 → 1.16.9

package/CHANGELOG.md

@@ -1,5 +1,134 @@
 # Changelog
 
+## 1.16.9
+
+Two sets of asks from tjs-lang for *The TJS Programming Language*, a book that teaches
+programming in the page. Single-sourcing for books (#217): one corpus, several outputs,
+nothing kept in sync by hand. And live examples that open with their code showing and a
+console that speaks the example's language (#216). Additive, with one behaviour change to
+know about: in a `tjs` or `ts` example, or one in a registered dialect, a line typed at the
+console is now evaluated in that language and not as JavaScript. `dist/iife.js` grows by
+0.7 kB gzip.
+
+### The book opens on the project, not on "Adopting the doc system"
+
+Both pages are pinned to the top, and the adopting page had an `order` where the README had
+none, so it sorted first: the ePub's opening chapter, and the first entry in the site nav, was
+a page about adopting the doc system. The README now leads both.
+
+### One source, several outputs (#217)
+
+- **Per-volume placement.** A page can sit in a different place in each book:
+  `{"placement": {"language": {"parent": "for-programmers", "order": 20}}}` in its metadata.
+  Each entry may set `parent`, `order`, `pin` and `title`, and naming a volume also binds the
+  page into it. The site nav is unaffected.
+- **Text insets.** `<!--{ "inset": "install.md#with-bun" }-->` includes another document, or
+  one heading's section of it, in the page. A fragment (a markdown file whose name starts
+  with `_`, in a directory the docs are extracted from) can be inset without being a page, and is the only kind of
+  file an inset reads. Resolved at extraction, so the site, the ePubs, `llms.txt` and the markdown copies
+  all get the assembled text, and an inset passage's live examples and tests run where it is
+  inset.
+- **Conditional text.** `<!--{ "only": "book" | "site" }--> … <!--{ "end": "only" }-->`
+  conditional text, for wording that belongs to one output, such as "next chapter" against
+  "next page". Books read `bookText`, everything else reads `text`; both are in the published
+  `docs.json`, so this chooses wording and does not hide anything.
+- **Each is guarded.** An inset that resolves nowhere, an include cycle, a missing heading, a
+  file that is not a fragment, an unbalanced `only`, a directive inside a list, quote or
+  paragraph, and a placement under a parent that is not in the volume all fail the build.
+- **Print is not a volume.** The in-app Print output takes the book wording but stays the
+  whole site in site order; `placement` arranges ePub volumes.
+- New from `tosijs-ui/site`, for a consumer that builds its corpus some other way:
+  `assembleCorpus`, `resolveInsets`, `splitConditions`, `SingleSourceError`, `placeInBook`,
+  `bookTextOf`, and the `BookPlacement` type.
+- Saving an edited live example back to source is refused on a page whose source uses an
+  inset or conditional text, where the example's position on the page no longer identifies a
+  block in that file. No existing page is affected: it applies only to a page that uses one
+  of the new directives.
+
+### Examples that open with their code showing, and a console in their language (#216)
+
+- **A fence picks the view an example opens in.** `{"view": "code"}` in the source block's
+  fence options opens the editor beside the preview, in the page and not full-screen;
+  `{"view": "console"}` puts the console where the preview would be, beside the code, for
+  examples whose point is a value. The editor is built as the example nears the viewport. In
+  a narrow column the panes stack. `example.showInline('code' | 'console')` does the same
+  from code.
+- **The console evaluates in the example's dialect.** A line goes through the same transform
+  as the example's code, with the same fence options, so `x == '5'` in a `tjs` example is
+  TJS's `==`. A line the dialect rejects shows the dialect's error and is not retried as
+  JavaScript. Plain `js` examples and `run` dialects are unchanged. A registered dialect's
+  `transform` now also receives console lines, marked with `options.repl === true`.
+- **Known limit of the above with tjs.** tjs puts setup statements in front of the line it
+  translates, so an expression shows its value, but a line that is only a declaration shows a
+  leftover value where a browser console shows `undefined`, and a line needing both that
+  setup and `await` shows `undefined`. Fixing it needs the setup to be separable, which is
+  asked of tjs-lang.
+- The generated JavaScript tjs-lang asked to see already exists as the read-only **JS** tab of
+  a `tjs` or `ts` example, and the inline views make it reachable in the page. Showing the
+  JavaScript for a single console line is not in this release: a transform's output for one
+  line is mostly its runtime prelude, and there is no general way to separate the two.
+
+## 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

package/README.md

@@ -1,6 +1,6 @@
 # tosijs-ui
 
-<!--{ "pin": "top", "layout": "full-width", "headTitle": "tosijs-ui — robust, standards-based web components", "description": "A small, fast library of standards-based web components (data tables, dialogs, forms, rich text, carousels, and more) built on tosijs — smaller and faster than a React app, with no virtual DOM.", "keywords": "web components, custom elements, tosijs, data table, dialog, form, rich text, no virtual dom" }-->
+<!--{ "pin": "top", "order": 0, "layout": "full-width", "headTitle": "tosijs-ui — robust, standards-based web components", "description": "A small, fast library of standards-based web components (data tables, dialogs, forms, rich text, carousels, and more) built on tosijs — smaller and faster than a React app, with no virtual DOM.", "keywords": "web components, custom elements, tosijs, data table, dialog, form, rich text, no virtual dom" }-->
 
 [ui.tosijs.net live demo](https://ui.tosijs.net) | [tosijs](https://tosijs.net) | [discord](https://discord.gg/ramJ9rgky5) | [github](https://github.com/tonioloewald/tosijs-ui#readme) | [npm](https://www.npmjs.com/package/tosijs-ui)
 

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/book-html.d.ts

@@ -3,6 +3,8 @@ export interface BookDoc {
     filename: string;
     title: string;
     text: string;
+    /** the book's variant, where conditional text made it differ from the site's */
+    bookText?: string;
     parent?: string;
     hidden?: boolean;
 }

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

@@ -9,6 +9,7 @@ force-wrapped code listings, not executed.
 import { renderDocMarkdown } from './render.js';
 import { buildSlugMap } from './routing.js';
 import { buildNavTree } from './nav-tree.js';
+import { bookTextOf } from './book-target.js';
 // Clean book typography; force-wraps code so listings never overflow a page.
 export const DEFAULT_BOOK_CSS = `/* doc-system book stylesheet */
 html { font-size: 100%; }
@@ -149,7 +150,7 @@ export function buildBookHtml(docs, opts) {
     const roots = buildNavTree(visible, slugMap);
     const css = opts.css ?? `${DEFAULT_BOOK_CSS}\n${PRINT_CSS}`;
     const chapters = flatten(roots)
-        .map((node) => `<section class="chapter" id="${slugify(node.doc.filename)}">\n${renderDocMarkdown(stripDocMeta(node.doc.text))}\n</section>`)
+        .map((node) => `<section class="chapter" id="${slugify(node.doc.filename)}">\n${renderDocMarkdown(stripDocMeta(bookTextOf(node.doc)))}\n</section>`)
         .join('\n');
     return `<!DOCTYPE html>
 <html lang="${opts.lang ?? 'en'}">

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

@@ -14,6 +14,16 @@ export interface BookTargetDoc {
     /** one book, several books, or `'none'` */
     book?: string | string[];
     hidden?: boolean;
+    /** where this doc sits in a particular volume, keyed by `book` name */
+    placement?: Record<string, BookPlacement>;
+}
+export interface BookPlacement {
+    /** parent within this volume; `''` puts the doc at the top level */
+    parent?: string;
+    order?: number;
+    pin?: 'top' | 'bottom';
+    /** chapter title in this volume */
+    title?: string;
 }
 type SlugMap = Record<string, string>;
 /**
@@ -29,6 +39,15 @@ export declare function chain<T extends BookTargetDoc>(doc: T, docs: T[], slugMa
  * another, or bind into several (`["default", "appendices"]`).
  */
 export declare function resolveBooks<T extends BookTargetDoc>(doc: T, docs: T[], slugMap?: SlugMap): string[];
+/**
+ * The docs of one volume, arranged for it: each doc's `placement` for this book overlaid on
+ * its site `parent` / `order` / `pin` / `title`. Returns shallow copies; the site's
+ * arrangement is untouched.
+ */
+export declare function placeInBook<T extends BookTargetDoc & {
+    order?: number;
+    pin?: 'top' | 'bottom';
+}>(docs: T[], book: string): T[];
 /**
  * Hidden here or anywhere above.
  *
@@ -48,4 +67,9 @@ export declare function withoutHidden<T extends BookTargetDoc>(docs: T[], slugMa
 export declare function partitionByBook<T extends BookTargetDoc>(docs: T[], slugMap?: SlugMap): Map<string, T[]>;
 /** Named books only, in stable order — the extra volumes beside the default one. */
 export declare function namedBooks<T extends BookTargetDoc>(docs: T[], slugMap?: SlugMap): string[];
+export declare const bookTextOf: (doc: {
+    text: string;
+    bookText?: string;
+}) => string;
+export declare const mayHaveSingleSourceDirective: (text: string) => boolean;
 export {};

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

@@ -29,6 +29,11 @@ export const NO_BOOK = 'none';
  * `book: ["default", "field-guide"]` binds the doc into both.
  */
 export const DEFAULT_BOOK_NAME = 'default';
+const placementKey = (book) => book === DEFAULT_BOOK ? DEFAULT_BOOK_NAME : book;
+/** Volumes a doc's `placement` names, as book keys. */
+function placedBooks(doc) {
+    return Object.keys(doc.placement ?? {}).map((k) => k.trim().toLowerCase() === DEFAULT_BOOK_NAME ? DEFAULT_BOOK : k.trim());
+}
 /**
  * The doc itself, then each ancestor nearest-first. Stops at an unresolvable parent and
  * at a cycle, so a self-parented doc yields just itself rather than hanging.
@@ -86,14 +91,51 @@ function normalizeDeclaration(value) {
  * another, or bind into several (`["default", "appendices"]`).
  */
 export function resolveBooks(doc, docs, slugMap = {}) {
+    const placed = placedBooks(doc);
+    const withPlaced = (books) => [
+        ...books,
+        ...placed.filter((b) => !books.includes(b)),
+    ];
     for (const d of chain(doc, docs, slugMap)) {
         if (d.book === undefined)
             continue;
         const declared = normalizeDeclaration(d.book);
-        if (declared !== null)
-            return declared;
+        /*
+        An explicit `none` on the doc ITSELF still wins over its own placement: withholding is
+        the conservative reading of a contradiction, as it is for `["default", "none"]`. An
+        inherited `none` does not, or a chapter could never be placed into a book from a section
+        that is otherwise site-only.
+        */
+        if (declared !== null) {
+            if (!declared.length && d === doc)
+                return [];
+            return withPlaced(declared);
+        }
     }
-    return [DEFAULT_BOOK];
+    return withPlaced([DEFAULT_BOOK]);
+}
+/**
+ * The docs of one volume, arranged for it: each doc's `placement` for this book overlaid on
+ * its site `parent` / `order` / `pin` / `title`. Returns shallow copies; the site's
+ * arrangement is untouched.
+ */
+export function placeInBook(docs, book) {
+    const key = placementKey(book);
+    return docs.map((doc) => {
+        const entry = Object.entries(doc.placement ?? {}).find(([k]) => k.trim() === key ||
+            (book === DEFAULT_BOOK && k.trim().toLowerCase() === DEFAULT_BOOK_NAME));
+        if (!entry)
+            return doc;
+        // Only what a placement is documented to set: an entry is author-written JSON, and
+        // copying whatever it holds would let `"hidden": false` or `"text"` through.
+        const out = { ...doc };
+        for (const field of ['parent', 'order', 'pin', 'title']) {
+            const value = entry[1][field];
+            if (value !== undefined)
+                out[field] = value;
+        }
+        return out;
+    });
 }
 /**
  * Hidden here or anywhere above.
@@ -134,3 +176,20 @@ export function namedBooks(docs, slugMap = {}) {
         .filter((k) => k !== DEFAULT_BOOK)
         .sort();
 }
+/*
+The text a book binds for this doc.
+
+`bookText` exists only where conditional text made the book differ from the site
+(`site/single-source.ts`). Every book output asks here, so there are exactly two readers to
+get right (the ePub and print) and every other consumer keeps reading `text`.
+*/
+export const bookTextOf = (doc) => doc.bookText ?? doc.text;
+/*
+Might this source use an inset or conditional text?
+
+Deliberately loose: it also matches a directive that is only being SHOWN in a code fence.
+Its two callers want exactly that bias. The build uses it to skip docs that certainly have
+none before asking the parser, and the example editor uses it to refuse a save, where a
+false positive costs a refusal and a false negative writes an edit into the wrong block.
+*/
+export const mayHaveSingleSourceDirective = (text) => /<!--\s*\{[^\n]*"(inset|only|end)"\s*:/.test(text);

package/dist/doc-system/{site/code-fences.js → code-fences.js}

@@ -1,13 +1,14 @@
 /*
-The build's ONE way to enumerate the code blocks in a doc: marked's own lexer.
+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: both callers ask marked.
+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';
+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

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

@@ -8,7 +8,7 @@ each of these is a legitimate thing to do on purpose. `strict: true` in the site
 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';
+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';

package/dist/doc-system/site/check-examples.js

@@ -21,7 +21,7 @@ executed, so they're skipped.
 
 Build-time only (bun). Never import from browser code.
 */
-import { collectCodeTokens } from './code-fences.js';
+import { collectCodeTokens } from '../code-fences.js';
 import { rewriteImports, AsyncFunction, loadTransform, transformAvailable, UnsupportedImportError, } from '../../live-example/code-transform.js';
 import { isLiveFence } from '../example-policy.js';
 // The default live-example context (matches the IIFE globals the pages provide).