tosijs-ui 1.16.5 → 1.16.7

package/CHANGELOG.md

@@ -1,5 +1,108 @@
 # Changelog
 
+## 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
+has to step through (#174). No API change.
+
+### Clicking a link to the page you are on no longer costs an extra Back (#174)
+
+A doc link pointing at the document already showing pushed a duplicate history entry, so the
+next Back press left the page where it was. It now replaces the entry, as a native same-URL
+navigation does. "The same page" means the same document: `/x`, `/x/` and `/x/index.html`, or
+`?x` with extra query parameters, all count. A URL with a hash still pushes, so Back from
+`/x/` returns to `/x/#example`. The `router`'s `navigate()` had the same defect and gets the
+same rule: navigating to the current path (with no hash) replaces.
+
+The double push #174 measured on every link (ensemble on 1.14.1) does not reproduce on 1.16.4
+with the same direct import: one click, one entry, and Back and Forward both work, in Chromium
+and WebKit. The documented consumer entry point is `import 'tosijs-ui/doc-browser'`, which
+registers `<tosi-doc-system>` since 1.14.2. The deep `tosijs-ui/doc-system/doc-system.js`
+import loads the same module.
+
 ## 1.16.5
 
 A patch, mostly found by using the doc site on an iPhone: menus that stay on screen as Safari's

package/dist/doc-browser.js

@@ -1027,7 +1027,19 @@ export function createDocBrowser(options) {
         }
         else {
             const href = hrefFor(filename);
-            window.history.pushState({ href }, '', href);
+            /*
+            A link to the document already showing REPLACES the entry rather than pushing one, as a
+            native same-URL navigation does. Pushing left a duplicate the reader had to Back
+            through, and Back then visibly did nothing — the symptom #174 reported.
+      
+            "Same" is the DOCUMENT, the identity the popstate guard uses, not the raw path: `/x`,
+            `/x/` and `/x/index.html`, or `?x` and `?x&_testMode=1`, are one page. A URL carrying a
+            hash still pushes, because leaving `/x/#example` for `/x/` is a navigation the reader
+            may want to come Back from.
+            */
+            const same = filename === String(app.currentDoc.filename) &&
+                document.location.hash === '';
+            window.history[same ? 'replaceState' : 'pushState']({ href }, '', href);
         }
         navigateTo(filename);
     };

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;
+}

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

@@ -21,9 +21,9 @@ executed, so they're skipped.
 
 Build-time only (bun). Never import from browser code.
 */
-import { marked } from 'marked';
+import { collectCodeTokens } from './code-fences.js';
 import { rewriteImports, AsyncFunction, loadTransform, transformAvailable, UnsupportedImportError, } from '../../live-example/code-transform.js';
-import { isLiveFence, parseFenceInfo, } from '../example-policy.js';
+import { isLiveFence } from '../example-policy.js';
 // The default live-example context (matches the IIFE globals the pages provide).
 // A project that sets a custom `context` on its <tosi-doc-system> can pass its
 // own keys; these are the tosijs-ui defaults.
@@ -54,36 +54,6 @@ const EXECUTABLE = new Set(['js', 'tjs', 'ts', 'test']);
 // scope is the difference between "once" and "once per rebuild". Lazily created, so a
 // corpus with no `ts` examples never makes one at all.
 let tsTranspiler;
-/*
-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`.
-*/
-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;
-}
 /**
  * Transpile-check every executable block in the corpus. Returns the problems and
  * the `tjs` bakes (which it computes anyway while checking — no double transpile).

package/dist/doc-system/site/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/site/code-fences.js

@@ -0,0 +1,40 @@
+/*
+The build's ONE way to enumerate the code blocks in a doc: 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.
+*/
+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/site/generate-site.d.ts

@@ -75,6 +75,13 @@ export interface GenerateSiteConfig {
      * self-contained-examples-plan.md.
      */
     bakes?: Map<string, ExampleBakes>;
+    /**
+     * Write each page's markdown beside its HTML (`/slug/index.md`) and point at it with
+     * `<link rel="alternate" type="text/markdown">`. Default true. For readers that want the
+     * text and not the page: an LLM's URL fetcher, a script, `curl`. `noindex` pages get
+     * neither, the same rule the sitemap applies.
+     */
+    markdownPages?: boolean;
     /** URL of the burned-in theme stylesheet (written by ./generate-css.ts) */
     stylesUrl?: string;
     /** extra lines injected into every <head> (favicon, analytics, etc.) */

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

@@ -163,8 +163,6 @@ async function pageHtml(doc, config, slugMap, configAttr) {
         })
         : '';
     const head = [
-        '  <meta charset="utf-8" />',
-        '  <meta name="viewport" content="width=device-width, initial-scale=1" />',
         // Render-blocking @import of web fonts lives in the stylesheet; warm the connection.
         '  <link rel="preconnect" href="https://fonts.googleapis.com" />',
         '  <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin />',
@@ -179,6 +177,10 @@ async function pageHtml(doc, config, slugMap, configAttr) {
             : '',
         doc.noindex ? '  <meta name="robots" content="noindex, follow" />' : '',
         baseUrl ? `  <link rel="canonical" href="${escapeAttr(canonical)}" />` : '',
+        // Relative to the page's own directory, so it holds at any mount (see relativeUrl).
+        hasMarkdownPage(doc, config)
+            ? `  <link rel="alternate" type="text/markdown" href="index.md" title="${escapeAttr(title)} (markdown)" />`
+            : '',
         '  <meta property="og:type" content="article" />',
         projectName
             ? `  <meta property="og:site_name" content="${escapeAttr(projectName)}" />`
@@ -203,23 +205,31 @@ async function pageHtml(doc, config, slugMap, configAttr) {
     ]
         .filter(Boolean)
         .join('\n');
+    /*
+    Two notes that used to ship as HTML comments at the top of every page's <head>. They are for
+    whoever edits this template, not for readers, and they pushed `<meta charset>` to byte ~1550
+    — the HTML spec wants it within the first 1024, and a byte-limited or strict fetcher may give
+    up before it gets there. So charset and viewport now lead, and the notes live here.
+  
+    1. The body is NOT hidden until hydration. It used to be (body opacity 0 + a 4s safety-net
+       timeout), because an undefined custom element is display:inline, so the pre-rendered page
+       stacked as bare text and hydration reflowed the whole thing. The cost was a blank screen
+       for as long as the bundle took — ~4.5s on a cheap phone, for content already in the HTML.
+       The tosi-doc-system:not(:defined) rules in the stylesheet now lay the static page out as
+       though the chrome were there, so hydration only ADDS the chrome and nothing moves. Paint
+       immediately; don't hide readable content.
+  
+    2. The inline script applies the theme BEFORE first paint. Now that we paint the static page
+       rather than hiding it, a dark-mode reader would otherwise get a flash of the light theme
+       until the bundle lands and sets body.darkmode. CSS alone can't do this: an explicit theme
+       choice lives in localStorage. Mirrors applyThemePrefs() (doc-system.ts) — keep the two in
+       step. Fails safe: any error leaves the light default.
+    */
     return `<!DOCTYPE html>
 <html lang="${escapeAttr(lang)}">
 <head>
-  <!-- NB: the body is NOT hidden until hydration. It used to be (body opacity 0 +
-       a 4s safety-net timeout), because an undefined custom element is
-       display:inline, so the pre-rendered page stacked as bare text and hydration
-       reflowed the whole thing. The cost was a blank screen for as long as the
-       bundle took — ~4.5s on a cheap phone, for content already in the HTML. The
-       tosi-doc-system:not(:defined) rules in the stylesheet now lay the static page
-       out as though the chrome were there, so hydration only ADDS the chrome and
-       nothing moves. Paint immediately; don't hide readable content. -->
-  <!-- Theme, applied BEFORE first paint. Now that we paint the static page rather
-       than hiding it, a dark-mode reader would otherwise get a flash of the light
-       theme until the bundle lands and sets body.darkmode. CSS alone can't do this:
-       an explicit theme choice lives in localStorage. Mirrors applyThemePrefs()
-       (doc-system.ts) — keep the two in step. Fails safe: any error leaves the
-       light default, exactly as before. -->
+  <meta charset="utf-8" />
+  <meta name="viewport" content="width=device-width, initial-scale=1" />
   <script>
     try {
       var p = JSON.parse(localStorage.getItem('tosi-doc-system-prefs') || '{}')
@@ -263,6 +273,10 @@ Only same-origin: `scriptUrl` may legitimately point at a CDN, and appending a q
 someone else's URL can miss their cache key or, worse, be rejected. A URL that already carries
 a query is left alone — the caller has said something deliberate about it.
 */
+/** A page gets a markdown copy unless the site opted out or the page is `noindex`. */
+function hasMarkdownPage(doc, config) {
+    return config.markdownPages !== false && !doc.noindex;
+}
 export function withStamp(url, stamp) {
     if (!stamp)
         return url;
@@ -297,6 +311,10 @@ export async function generateSite(config) {
         const slug = slugMap[doc.filename];
         const dir = slug === '' ? outputDir : `${outputDir}/${slug}`;
         await Bun.write(`${dir}/index.html`, await pageHtml(doc, config, slugMap, configAttr));
+        // The page's own source, for readers that want text rather than a page.
+        if (hasMarkdownPage(doc, config)) {
+            await Bun.write(`${dir}/index.md`, doc.text.trimEnd() + '\n');
+        }
         count += 1;
     }
     // The corpus the component fetches for nav + client-side rendering of other pages.

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

@@ -1,6 +1,7 @@
 export { defineSiteConfig } from './site-config.js';
 export type { SiteConfig, SiteHost, LibraryBuildContext, } from './site-config.js';
 export { buildSite } from './orchestrator.js';
+export { SiteMisconfiguredError } from './build-warnings.js';
 export { devServer } from './dev-server.js';
 export { auditDependencies, reportAudit, resolveAuditMode, } from './audit-guard.js';
 export type { AuditConfig, AuditGate, AuditResult, AuditSeverity, AuditMode, AuditAdvisory, } from './audit-guard.js';

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

@@ -5,6 +5,9 @@ browser code. See ./README is at ../doc-site-system.md and the repo docs.
 */
 export { defineSiteConfig } from './site-config.js';
 export { buildSite } from './orchestrator.js';
+// Thrown by `buildSite` under `strict: true` — exported so a caller can tell a refused
+// misconfiguration from a crash (`catch (e) { if (e instanceof SiteMisconfiguredError) … }`).
+export { SiteMisconfiguredError } from './build-warnings.js';
 export { devServer } from './dev-server.js';
 export { auditDependencies, reportAudit, resolveAuditMode, } from './audit-guard.js';
 export { openDevBrowser, buildOpenPlan } from './open-browser.js';

package/dist/doc-system/site/make-llms-txt.d.ts

@@ -1,3 +1,4 @@
+import type { ExamplePolicy } from '../example-policy.js';
 /** A doc as it appears in the extracted corpus (docs.json). */
 interface CorpusDoc {
     title?: string;
@@ -39,6 +40,14 @@ export interface LlmsTxtMeta {
      * for exactly the projects that enabled the MORE capable mode.
      */
     haltijaDev?: boolean | 'tunnel';
+    /**
+     * Mirrors `SiteConfig.markdownPages` (default true): the build writes `index.md` beside
+     * every page, so the index says so. Pass false when the site ships HTML only — pointing a
+     * reader at a file that is not there costs more than not mentioning it.
+     */
+    markdownPages?: boolean;
+    /** Mirrors `SiteConfig.liveExamples`: which fences are live decides the examples note. */
+    liveExamples?: ExamplePolicy;
 }
 /**
  * Build entries from the extracted corpus — every doc that was actually

package/dist/doc-system/site/make-llms-txt.js

@@ -1,6 +1,7 @@
 import * as fs from 'fs';
 import * as path from 'path';
 import { buildSlugMap, pathForSlug, withBase } from '../routing.js';
+import { liveFenceLanguages } from './build-warnings.js';
 const SRC = 'src';
 const DIST = 'dist';
 function extractTitle(text) {
@@ -113,8 +114,9 @@ export function generateLlmsTxt(outputPath, meta = {}, corpus) {
         : entriesFromSrcScan();
     // Only orient agents about the live-example execution model when the corpus
     // actually has live examples (a book / pure-docs site has none).
-    const exampleFence = /```(js|tjs|ts|html|css)\b/;
-    const hasLiveExamples = !!corpus && corpus.some((d) => exampleFence.test(d.text ?? ''));
+    // THE shared rule (build-warnings.ts), under the site's policy — this was a regex of its
+    // own, which told an opt-in prose site about live examples it does not have.
+    const hasLiveExamples = !!corpus && liveFenceLanguages(corpus, meta.liveExamples).size > 0;
     const liveExampleNote = hasLiveExamples
         ? [
             'Live examples run inline on the shared page by default (not sandboxed):',
@@ -142,6 +144,15 @@ export function generateLlmsTxt(outputPath, meta = {}, corpus) {
             '',
         ]
         : [];
+    // Only for a corpus-driven index: the legacy scan links to dist/ files, not pages.
+    const markdownNote = corpus && meta.markdownPages !== false
+        ? [
+            'Pages below are also available as plain markdown: append `index.md` to the URL',
+            '(for example `/carousel/index.md`). Prefer that if you only need the text. A page',
+            'marked noindex has no markdown copy.',
+            '',
+        ]
+        : [];
     const name = meta.name ?? pkg.name ?? '';
     const description = meta.description ?? pkg.description ?? '';
     const links = [];
@@ -165,6 +176,7 @@ export function generateLlmsTxt(outputPath, meta = {}, corpus) {
         '',
         'Full documentation, with live code examples, is at the links below.',
         '',
+        ...markdownNote,
         ...liveExampleNote,
         ...haltijaNote,
         '## Pages',