tosijs-ui 1.16.14 → 1.16.16

package/CHANGELOG.md

@@ -1,5 +1,84 @@
 # Changelog
 
+## 1.16.16
+
+For tjs-lang's book (GitHub #216 item 3 and #210 item 5), plus one change to `llms.txt`.
+Both tjs-lang items are feature-detected, so nothing changes until your tjs-lang has them.
+
+- **A console line shows its own value, and the JavaScript it became.** A dialect's
+  transform may now return `prelude` and `body` beside `code`: its runtime setup, and what
+  the source itself became. When it does (tjs-lang 0.14.0-rc.5 and later), a line typed at
+  an example's console is evaluated for its own value, so a declaration shows `undefined`
+  where it used to show the setup's last assignment, and a line that needs both the setup
+  and `await` shows what it resolved to. The input also gains a small **JS** button that
+  shows the JavaScript for that line. A transform that returns only `code` behaves as
+  before, with no button.
+- **`tjs` and `ts` examples may be written as modules.** `export` is removed from `tjs` and
+  `ts` examples before they run, by tjs-lang's own parser (`stripExports`, from
+  0.14.0-rc.4), and the build's example check does the same. An example runs as a function
+  body, where `export` is a syntax error, so with an older tjs-lang it fails as it always
+  has. `js` examples are unchanged.
+- **The tjs-lang peer range admits the 0.14 release candidates** (`^0.13.1 || ^0.14.0-rc.5`).
+  It read `^0.14.0`, which excludes every prerelease, so `npm install` refused the one
+  tjs-lang that has these features. Run here with 0.14.0-rc.5 installed: the browser lane
+  on Chromium, and the new tests of both features on all three browsers.
+- **`registerDialect` documents what a transform should return.** `testRunner` has been
+  honoured since 1.16.8 but was not in the type or the docs: a dialect that returns only
+  `code` has its inline tests run from their raw text, with JavaScript's semantics. The
+  `transform` type now names `testRunner`, `prelude` and `body`.
+- **An example re-run while it was still loading could leave its page never finishing its
+  tests.** A run replaced by a newer one (tests turned on, or an edit, while the first run
+  was still awaiting a fetch) went on to run its test block against a preview no longer in
+  the page. A test that waits for something to render then waited for ever and the example
+  stayed marked as running, so the page was reported as not finished after 45 seconds. A
+  replaced run now stops before its tests, and one replaced while its tests are running
+  no longer writes its results over the newer run's. Seen on the data-table page off
+  localhost.
+- **`llms.txt` no longer carries a paragraph about the dev server.** A site with
+  `haltijaDev` set used to tell readers of its `llms.txt` to run `bun start` and drive the
+  page with the `hj` CLI. That file is for whoever consumes the library, and those readers
+  have no repo to run. If you relied on it to brief an agent working in your project, put
+  the same note in your `CLAUDE.md` or `AGENTS.md`.
+
+The tjs-lang this package pins for sites that load it from a CDN is still 0.13.13, which has
+neither feature. A site that serves its own tjs-lang (the installed peer, copied
+same-origin by the build) gets both as soon as that is 0.14.0-rc.5.
+
+`LlmsTxtMeta.haltijaDev` is still accepted and now ignored (deprecated). `dist/iife.js`
+grows by about 0.4 kB gzip.
+
+## 1.16.15
+
+For projects that build their own docs bundle, from tosijs's upgrade to 1.16.13 (board
+#3248). Two failures that left a green build over a broken site now say so.
+
+- **`restampSite(config)`, from `tosijs-ui/site`.** If your site has no `bundleEntry` and you
+  overwrite `/iife.js` after `buildSite`, call it afterwards. It checks that the file you
+  wrote registers `<tosi-doc-system>`, and `<tosi-example>` when the corpus has live
+  examples, and then re-stamps the script and stylesheet `?v=` in every page from the files
+  actually on disk (the stamp `buildSite` wrote described the bundle it replaced, so a
+  returning visitor could run a cached library against new pages). A bundle whose entry
+  imports only the root `tosijs-ui` registers neither element since 1.14.0, and until now
+  nothing noticed: pages served, no header, no nav, no examples, no doc tests. A warning by
+  default. Under `strict: true` it throws before writing anything. It also throws when
+  there is nothing to re-stamp, on a `bundleEntry` site, and when it cannot read the corpus.
+- **The build reports two copies of CodeMirror.** After an upgrade a lockfile can keep an
+  older hoisted `@codemirror/state` while the newer one nests under
+  `node_modules/tosijs-ui/`; every `<tosi-code>` is then blank and nothing fails.
+  `buildSite` now asks the module resolver whether the packages the editor is built from
+  agree, and names both copies and the command that fixes it
+  (`bun update @codemirror/state @codemirror/view`). A warning by default. **Under `strict: true` it fails
+  `buildSite` on a site with a `bundleEntry`, and fails `restampSite`**, which is new in a
+  patch: those are the two places a bundle is built from the install, and such a build was
+  already producing blank editors. Otherwise `buildSite` says it once and carries on. At runtime `<tosi-code>` logs the same explanation beside CodeMirror's own
+  "Unrecognized extension value" error. Cost: `iife.js` +176 bytes gzip.
+- **Fixed: `llms.txt` told agents to try `/carousel/index.md` on every site.** That is a
+  tosijs-ui page. The example is now a page of the site being built.
+- **The "relative imports without a file extension" warning says what it read.** It is
+  about the `.js` files tsc emitted, at the moment it emitted them. A project that replaces
+  those with bundles afterwards could not find the files it named; the warning now says so
+  and points at `"emitDeclarationOnly": true`.
+
 ## 1.16.14
 
 More reach for curated schema forms (#221): into arrays and unions, grouped into sections,

package/dist/code-editor-cm.js

@@ -197,27 +197,44 @@ export function createCmEditor(parent, opts = {}) {
     const readonly = new Compartment();
     const highlight = new Compartment();
     const langExt = opts.languageExtension ?? standardLanguageBundle(opts.mode ?? 'javascript');
-    const view = new EditorView({
-        parent,
-        root: opts.root,
-        state: EditorState.create({
-            doc: opts.value ?? '',
-            extensions: [
-                baseExtensions(),
-                highlight.of(highlightFor(isDarkMode())),
-                language.of(langExt),
-                readonly.of(EditorState.readOnly.of(!!opts.readOnly)),
-                EditorView.updateListener.of((u) => {
-                    if (!u.docChanged || !opts.onChange)
-                        return;
-                    // A programmatic `value` set is not a change the USER made. See `programmatic`.
-                    if (u.transactions.some((t) => t.annotation(programmatic)))
-                        return;
-                    opts.onChange(u.state.doc.toString());
-                }),
-            ],
-        }),
-    });
+    let view;
+    try {
+        view = new EditorView({
+            parent,
+            root: opts.root,
+            state: EditorState.create({
+                doc: opts.value ?? '',
+                extensions: [
+                    baseExtensions(),
+                    highlight.of(highlightFor(isDarkMode())),
+                    language.of(langExt),
+                    readonly.of(EditorState.readOnly.of(!!opts.readOnly)),
+                    EditorView.updateListener.of((u) => {
+                        if (!u.docChanged || !opts.onChange)
+                            return;
+                        // A programmatic `value` set is not a change the USER made. See `programmatic`.
+                        if (u.transactions.some((t) => t.annotation(programmatic)))
+                            return;
+                        opts.onChange(u.state.doc.toString());
+                    }),
+                ],
+            }),
+        });
+    }
+    catch (error) {
+        /*
+        CodeMirror recognises extensions by identity, so a second copy of `@codemirror/state`
+        in the install makes it reject its own language packages. The editor is then blank and
+        the message names an internal; say what happened and what fixes it (board #3248).
+        */
+        if (/Unrecognized extension value/.test(String(error?.message))) {
+            console.error('<tosi-code>: CodeMirror rejected an extension, which means two copies of ' +
+                '@codemirror/state (or @codemirror/view) are loaded. Every CodeMirror package ' +
+                'must share one. Run `bun update @codemirror/state @codemirror/view` (or ' +
+                '`npm dedupe`), then rebuild.');
+        }
+        throw error;
+    }
     // Re-apply the right highlight palette when the doc-system toggles dark mode
     // (it flips the `darkmode` class on <body>).
     let dark = isDarkMode();

package/dist/doc-system/site/asset-stamp.d.ts

@@ -22,6 +22,11 @@ export interface AssetStampResult {
  * keeps executing the bundle it cached hours ago — through edits, through reloads.
  */
 export declare function computeAssetStamp(paths: string[], fallback: string): Promise<AssetStampResult>;
+/**
+ * The assets the stamp covers, in hashing order. ONE list, for `buildSite` and for
+ * `restampSite`: two would let a re-stamp hash a different set and never match a build.
+ */
+export declare function assetStampInputs(publicDir: string, scriptName: string, hydrateName?: string): string[];
 /**
  * The message for a named-but-missing input. Separate so the test asserts the real string
  * rather than a paraphrase of it.

package/dist/doc-system/site/asset-stamp.js

@@ -53,6 +53,17 @@ export async function computeAssetStamp(paths, fallback) {
         usedFallback: !sawAny,
     };
 }
+/**
+ * The assets the stamp covers, in hashing order. ONE list, for `buildSite` and for
+ * `restampSite`: two would let a re-stamp hash a different set and never match a build.
+ */
+export function assetStampInputs(publicDir, scriptName, hydrateName) {
+    return [
+        hydrateName && `${publicDir}/${hydrateName}`,
+        `${publicDir}/${scriptName}`,
+        `${publicDir}/doc-system.css`,
+    ].filter(Boolean);
+}
 /**
  * The message for a named-but-missing input. Separate so the test asserts the real string
  * rather than a paraphrase of it.

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

@@ -22,7 +22,7 @@ executed, so they're skipped.
 Build-time only (bun). Never import from browser code.
 */
 import { collectCodeTokens } from '../code-fences.js';
-import { rewriteImports, AsyncFunction, loadTransform, transformAvailable, UnsupportedImportError, } from '../../live-example/code-transform.js';
+import { rewriteImports, AsyncFunction, loadTransform, transformAvailable, UnsupportedImportError, withoutExports, } from '../../live-example/code-transform.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
@@ -130,7 +130,9 @@ export async function checkExamples(docs, opts = {}) {
                     // We only need to validate that the source builds, not reproduce tjs
                     // lowering exactly.
                     tsTranspiler ??= new Bun.Transpiler({ loader: 'ts' });
-                    js = tsTranspiler.transformSync(rewritten);
+                    // The page removes `export` from a `ts` example when its tjs-lang can; so does
+                    // this, or a module-style example the page runs would fail the build.
+                    js = await withoutExports(tsTranspiler.transformSync(rewritten));
                 }
                 else if (dialect === 'tjs') {
                     const transform = await loadTransform('tjs');

package/dist/doc-system/site/codemirror-copies.d.ts

@@ -0,0 +1,13 @@
+declare global {
+    var Bun: any;
+}
+/**
+ * For each package that must be shared, the distinct copies reachable from tosijs-ui, from
+ * every `@codemirror/*` package it depends on, and from tjs-lang's editor extension. More than one path for a name is
+ * the defect. `uiDir` is where tosijs-ui itself is installed.
+ */
+export declare function codemirrorCopies(root: string, uiDir: string): Record<string, string[]>;
+/** What to say about `codemirrorCopies`' answer, or null when each package has one copy. */
+export declare function duplicateCodemirrorWarning(copies: Record<string, string[]>): string | null;
+/** tosijs-ui's own package directory, found from this module's location. */
+export declare function tosijsUiDir(moduleDir: string): string;

package/dist/doc-system/site/codemirror-copies.js

@@ -0,0 +1,115 @@
+/*
+Two copies of CodeMirror in one install (board #3248, item 2; the same failure as #131).
+
+Every CodeMirror package must share ONE `@codemirror/state` (and one `@codemirror/view`):
+extensions are recognised by identity, so a language package holding a different copy hands
+the editor values it rejects ("Unrecognized extension value in extension set"), and every
+`<tosi-code>` renders blank while the build and the tests stay green.
+
+It arrives through an ordinary upgrade. A lockfile that pinned an older hoisted
+`@codemirror/state` keeps it, the package manager nests the newer one tosijs-ui now needs
+under `node_modules/tosijs-ui/`, and the `lang-*` packages go on resolving the hoisted copy.
+
+Build-time only: it asks the module resolver, which is the thing that decides what loads.
+*/
+import * as path from 'path';
+import { existsSync, readFileSync, realpathSync } from 'fs';
+const SHARED = ['@codemirror/state', '@codemirror/view'];
+/** The package directory a resolved file belongs to (the one holding its package.json). */
+function packageDirOf(file) {
+    let dir = path.dirname(file);
+    while (dir !== path.dirname(dir)) {
+        if (existsSync(path.join(dir, 'package.json')))
+            return dir;
+        dir = path.dirname(dir);
+    }
+    return path.dirname(file);
+}
+function resolveFrom(specifier, from) {
+    try {
+        return realpathSync(Bun.resolveSync(specifier, from));
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * For each package that must be shared, the distinct copies reachable from tosijs-ui, from
+ * every `@codemirror/*` package it depends on, and from tjs-lang's editor extension. More than one path for a name is
+ * the defect. `uiDir` is where tosijs-ui itself is installed.
+ */
+export function codemirrorCopies(root, uiDir) {
+    let deps = [];
+    try {
+        const pkg = JSON.parse(readFileSync(path.join(uiDir, 'package.json'), 'utf8'));
+        deps = Object.keys(pkg.dependencies ?? {}).filter((name) => name.startsWith('@codemirror/'));
+    }
+    catch {
+        // no package.json to read: only the two direct resolutions are compared
+    }
+    // Where each CodeMirror package tosijs-ui uses actually lives: each resolves its OWN
+    // dependencies from there, which is where a second copy shows up.
+    /*
+    NOT the project root. A project may hold its own, unrelated `@codemirror/state` for an
+    editor of its own, beside a consistent set under tosijs-ui: that is two copies in the
+    install and no defect. The defect is the packages the editor is BUILT FROM disagreeing,
+    and the upgrade case shows up there, since the hoisted `lang-*` resolve the hoisted copy.
+    */
+    const origins = new Set([uiDir]);
+    for (const dep of deps) {
+        const resolved = resolveFrom(dep, uiDir);
+        if (resolved)
+            origins.add(packageDirOf(resolved));
+    }
+    // tjs-lang's CodeMirror extension is bundled into the same editor (see bundle-guard.ts).
+    const tjs = resolveFrom('tjs-lang/editors/codemirror', root);
+    if (tjs)
+        origins.add(packageDirOf(tjs));
+    const copies = {};
+    for (const name of SHARED) {
+        const found = new Set();
+        for (const origin of origins) {
+            const resolved = resolveFrom(name, origin);
+            if (resolved)
+                found.add(packageDirOf(resolved));
+        }
+        copies[name] = [...found].sort();
+    }
+    return copies;
+}
+/** What to say about `codemirrorCopies`' answer, or null when each package has one copy. */
+export function duplicateCodemirrorWarning(copies) {
+    const doubled = Object.entries(copies).filter(([, dirs]) => dirs.length > 1);
+    if (doubled.length === 0)
+        return null;
+    return (`\n⚠️  This install has more than one copy of a CodeMirror package that must be shared:\n` +
+        doubled
+            .map(([name, dirs]) => `    ${name}\n` + dirs.map((dir) => `      ${dir}\n`).join(''))
+            .join('') +
+        `    CodeMirror recognises extensions by identity, so in a bundle built from this install\n` +
+        `    every <tosi-code> renders blank ("Unrecognized extension value in extension set")\n` +
+        `    and nothing fails. It usually follows an upgrade: the lockfile kept an older hoisted\n` +
+        `    copy. Bring them back to one:\n` +
+        `        bun update ${doubled
+            .map(([name]) => name)
+            .join(' ')}    (npm: npm dedupe)\n`);
+}
+/** tosijs-ui's own package directory, found from this module's location. */
+export function tosijsUiDir(moduleDir) {
+    let dir = moduleDir;
+    while (dir !== path.dirname(dir)) {
+        const file = path.join(dir, 'package.json');
+        if (existsSync(file)) {
+            try {
+                if (JSON.parse(readFileSync(file, 'utf8')).name === 'tosijs-ui') {
+                    return dir;
+                }
+            }
+            catch {
+                // unreadable: keep walking up
+            }
+        }
+        dir = path.dirname(dir);
+    }
+    return moduleDir;
+}

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

@@ -1,6 +1,8 @@
 export { defineSiteConfig } from './site-config.js';
 export type { SiteConfig, SiteHost, LibraryBuildContext, } from './site-config.js';
 export { buildSite } from './orchestrator.js';
+export { restampSite } from './restamp.js';
+export type { RestampResult } from './restamp.js';
 export { SiteMisconfiguredError } from './build-warnings.js';
 export { testReportVerdict } from './test-report.js';
 export type { TestReportLike, TestReportVerdict } from './test-report.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';
+// For a project that replaces the hydration bundle after `buildSite`: re-stamp the pages
+// from what is served, and check it registers the doc system (board #3248).
+export { restampSite } from './restamp.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';

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

@@ -30,14 +30,9 @@ export interface LlmsTxtMeta {
     /** optional framing line(s) under the description */
     tagline?: string;
     /**
-     * Mirrors `SiteConfig.haltijaDev`. When set, `llms.txt` tells an agent it can DRIVE the
-     * running page rather than reason about it from source — which is the single most useful
-     * thing an agent can know about a project it is working on, and was previously discoverable
-     * only by reading the doc-site-system page in full.
-     *
-     * `'tunnel'` also carries that meaning — it is `true` plus a remote path — so the note is
-     * written on truthiness, not on `=== true`. Getting that wrong would silently drop the note
-     * for exactly the projects that enabled the MORE capable mode.
+     * @deprecated Ignored since 1.16.16. It used to add a paragraph about driving the dev
+     * server with the `hj` CLI; `llms.txt` is for whoever consumes the library, so that note
+     * belongs in the project's own agent instructions. Kept so existing callers still compile.
      */
     haltijaDev?: boolean | 'tunnel';
     /**
@@ -56,6 +51,13 @@ export interface LlmsTxtMeta {
  * docs and needs no `dist/` library output.
  */
 export declare function entriesFromCorpus(corpus: CorpusDoc[], meta: LlmsTxtMeta): LlmsEntry[];
+/**
+ * A real page of THIS site to show the `index.md` rule with. It was hard-coded to
+ * `/carousel/index.md`, a tosijs-ui page, so every other project's llms.txt pointed agents
+ * at a URL it does not have (board #3248). The first page that has a markdown copy and is
+ * not the site root.
+ */
+export declare function markdownExample(corpus: CorpusDoc[], meta: LlmsTxtMeta): string | undefined;
 /**
  * Write an `llms.txt` index. Pass the extracted `corpus` (the build does) to
  * index every doc by its rendered URL; omit it to fall back to the legacy

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

@@ -93,6 +93,25 @@ function entriesFromSrcScan() {
     }
     return entries.sort((a, b) => a.title.localeCompare(b.title));
 }
+/**
+ * A real page of THIS site to show the `index.md` rule with. It was hard-coded to
+ * `/carousel/index.md`, a tosijs-ui page, so every other project's llms.txt pointed agents
+ * at a URL it does not have (board #3248). The first page that has a markdown copy and is
+ * not the site root.
+ */
+export function markdownExample(corpus, meta) {
+    const slugMap = buildSlugMap(corpus);
+    for (const doc of corpus) {
+        if (!doc.title || doc.hidden || doc.noindex) {
+            continue;
+        }
+        const pagePath = pathForSlug(slugMap[doc.filename]);
+        if (pagePath === '/')
+            continue;
+        return `${withBase(meta.basePath, pagePath)}index.md`;
+    }
+    return undefined;
+}
 /**
  * Write an `llms.txt` index. Pass the extracted `corpus` (the build does) to
  * index every doc by its rendered URL; omit it to fall back to the legacy
@@ -128,28 +147,14 @@ export function generateLlmsTxt(outputPath, meta = {}, corpus) {
             '',
         ]
         : [];
-    /*
-    Only advertise browser control when the project has actually opted in. Telling an agent to
-    drive a page that has no dev channel sends it after a capability that will not answer, and
-    a wrong affordance costs more than a missing one.
-    */
-    const haltijaNote = meta.haltijaDev
-        ? [
-            'Running this project locally (`bun start`), the dev server injects a',
-            'localhost-gated dev channel, so an agent can DRIVE the live page with the `hj`',
-            'CLI — `hj navigate`, `hj eval`, `hj tree` — instead of inferring behaviour from',
-            'source. Injected at serve time only, never in the built output. Note that no',
-            'requestAnimationFrame runs under `hj eval`, and tosijs renders are rAF-driven, so',
-            'use it to inspect STATE; a painted-output check needs a real test lane.',
-            '',
-        ]
-        : [];
     // Only for a corpus-driven index: the legacy scan links to dist/ files, not pages.
+    const example = corpus ? markdownExample(corpus, meta) : undefined;
     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.',
+            'Pages below are also available as plain markdown: append `index.md` to the URL' +
+                (example ? '' : '.'),
+            ...(example ? [`(for example \`${example}\`).`] : []),
+            'Prefer that if you only need the text. A page marked noindex has no markdown copy.',
             '',
         ]
         : [];
@@ -178,7 +183,6 @@ export function generateLlmsTxt(outputPath, meta = {}, corpus) {
         '',
         ...markdownNote,
         ...liveExampleNote,
-        ...haltijaNote,
         '## Pages',
         '',
     ];

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

@@ -1,3 +1,6 @@
+export declare function registerSiteDialects(config: {
+    dialects?: readonly string[];
+}): void;
 import type { SiteConfig } from './site-config.js';
 declare global {
     var Bun: any;

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

@@ -21,7 +21,8 @@ import * as path from 'path';
  * that asks "is this fence live?" calls it first rather than depending on build order: the
  * misconfiguration checks run long before the page generator, which used to be the only caller.
  */
-function registerSiteDialects(config) {
+let codemirrorWarned = false;
+export function registerSiteDialects(config) {
     for (const name of normalizeDialectNames(config.dialects)) {
         if (!BUILT_IN_DIALECTS.has(name))
             registerLiveLanguage(name);
@@ -30,7 +31,7 @@ function registerSiteDialects(config) {
 import { namedBooks, partitionByBook, DEFAULT_BOOK } from '../book-target.js';
 import { attachCovers, listEpubVolumes, printCoverManifestUrl, VOLUME_MANIFEST, renderEpubDownloads, } from './epub-volumes.js';
 import { buildSlugMap } from '../routing.js';
-import { computeAssetStamp, missingStampInputWarning } from './asset-stamp.js';
+import { assetStampInputs, computeAssetStamp, missingStampInputWarning, } from './asset-stamp.js';
 import { existsSync, mkdirSync, readdirSync, readFileSync, unlinkSync, } from 'fs';
 import { tmpdir } from 'os';
 import { $, spawn } from 'bun';
@@ -43,10 +44,12 @@ import { generateLlmsTxt } from './make-llms-txt.js';
 import { DEFAULT_DOC_IGNORES } from './docs.js';
 import { writesOutsideOutputDir } from './host-preset.js';
 import { generateSite } from './generate-site.js';
+import { servedBundleProblem } from './restamp.js';
+import { codemirrorCopies, duplicateCodemirrorWarning, tosijsUiDir, } from './codemirror-copies.js';
 import { findOutputDirOverlap, resolveBundleDir } from './output-guard.js';
 import { acquireBuildLock, describeHolder } from './build-lock.js';
 import { sourcemapWarning } from './sourcemap-check.js';
-import { basePathDoubling, bundleRegistrations, firebasePublicMismatch, } from './host-preset.js';
+import { basePathDoubling, firebasePublicMismatch } from './host-preset.js';
 import { preflight } from './preflight.js';
 import { auditDependencies, reportAudit } from './audit-guard.js';
 import { gatherBuildStamp, hashOutput, stampToWrite, } from './build-stamp.js';
@@ -452,6 +455,28 @@ export async function buildSite(config, opts = {}) {
         const PUBLIC = path.resolve(PROJECT_ROOT, config.outputDir ?? 'docs');
         const DIST = path.resolve(PROJECT_ROOT, 'dist');
         /*
+        Two copies of CodeMirror blank every <tosi-code>, and nothing else says so (#3248). Asked
+        first, of the module resolver: it costs a couple of dozen resolutions, and a site built
+        on that install is broken however the rest of the build goes.
+        */
+        {
+            const doubled = duplicateCodemirrorWarning(codemirrorCopies(process.cwd(), tosijsUiDir(import.meta.dir)));
+            /*
+            Fatal under `strict` only where buildSite itself bundles the editor (`bundleEntry`).
+            Without one the site ships tosijs-ui's prebuilt bundle, which the install cannot
+            break, so the copies matter only to a bundle the project builds for itself, and
+            `restampSite` is where that project gets a failing build. Otherwise said once per
+            process: a watch rebuild has nothing new to add.
+            */
+            if (doubled) {
+                if (config.bundleEntry && config.strict)
+                    misconfigured(true, doubled);
+                else if (!codemirrorWarned)
+                    console.warn(doubled);
+                codemirrorWarned = true;
+            }
+        }
+        /*
       Where the hydration bundle is BUILT. Defaults to the site output, not to `dist` (#69).
     
       It used to be built into `dist` unconditionally — the same directory `emitLibrary` /
@@ -848,9 +873,15 @@ export async function buildSite(config, opts = {}) {
                 existsSync(DIST)) {
                 const bad = extensionlessImports(DIST);
                 if (bad.length) {
-                    console.warn(`⚠️  dist/ has ${bad.length} relative import(s) without a file extension — Node rejects them ` +
-                        `(ERR_MODULE_NOT_FOUND), even though Bun and bundlers resolve them. Use \`libraryBundle\` ` +
-                        `instead of ${config.libraryTsconfig ? 'libraryTsconfig' : 'emitLibrary'} (tosijs-ui#169). First: ${bad[0]}`);
+                    console.warn(`⚠️  The .js files tsc just emitted into dist/ have ${bad.length} relative import(s) without a ` +
+                        `file extension — Node rejects them (ERR_MODULE_NOT_FOUND), even though Bun and bundlers ` +
+                        `resolve them. Use \`libraryBundle\` instead of ${config.libraryTsconfig ? 'libraryTsconfig' : 'emitLibrary'} (tosijs-ui#169). First: ${bad[0]}\n` +
+                        // A project that publishes bundles it builds afterwards sees this about files
+                        // it then replaces, and went looking for them in its final dist/ (board #3248).
+                        `   If a later step replaces these files with bundles, they are not what you publish: ` +
+                        (config.libraryTsconfig
+                            ? `set "emitDeclarationOnly": true in ${config.libraryTsconfig} so tsc emits only the .d.ts files.`
+                            : `use \`libraryTsconfig\` with "emitDeclarationOnly": true so tsc emits only the .d.ts files.`));
                 }
             }
             // The hydration bundle. If bundleEntry is set we build it (IIFE), else pages
@@ -1145,23 +1176,10 @@ export async function buildSite(config, opts = {}) {
                     for (const f of await Array.fromAsync(new Bun.Glob('**/*.js').scan({ cwd: PUBLIC, absolute: true }))) {
                         bundled += await Bun.file(f).text();
                     }
-                    const reg = bundleRegistrations(bundled);
-                    if (!reg.docSystem) {
-                        misconfigured(config.strict, `\n⚠️  ${config.bundleEntry} does not register <tosi-doc-system>, so every page\n` +
-                            `    will render its prerendered markup and nothing else — no header, no nav,\n` +
-                            `    no menu, no live examples, and no error in the console.\n\n` +
-                            `    bundleEntry REPLACES tosijs-ui's bundle; it does not extend it. Add:\n` +
-                            `        import 'tosijs-ui/doc-browser'\n` +
-                            (docsHaveExamples && !reg.liveExample
-                                ? `        import 'tosijs-ui/live-example'   // this corpus has live examples\n`
-                                : '') +
-                            `    to ${config.bundleEntry}.\n`);
-                    }
-                    else if (docsHaveExamples && !reg.liveExample) {
-                        misconfigured(config.strict, `\n⚠️  This corpus has executable fences but ${config.bundleEntry} does not\n` +
-                            `    register <tosi-example>. Add \`import 'tosijs-ui/live-example'\` — the\n` +
-                            `    code blocks will render as plain text otherwise.\n`);
-                    }
+                    // ONE wording and one rule, shared with restampSite (restamp.ts).
+                    const problem = servedBundleProblem(bundled, String(config.bundleEntry), docsHaveExamples, String(config.bundleEntry));
+                    if (problem)
+                        misconfigured(config.strict, problem);
                 }
                 // Report the always-loaded weight (entry, not the lazy editor chunks) so a
                 // regression that pulls CodeMirror back into the entry is visible.
@@ -1206,7 +1224,6 @@ export async function buildSite(config, opts = {}) {
                         baseUrl: config.baseUrl,
                         basePath: config.basePath,
                         projectLinks: config.projectLinks,
-                        haltijaDev: config.haltijaDev,
                         markdownPages: config.markdownPages,
                         liveExamples: config.liveExamples,
                     }, corpus);
@@ -1425,11 +1442,7 @@ export async function buildSite(config, opts = {}) {
             written, so hashing the directory would hash the previous build. The bundle and the
             stylesheet exist by now, and they are exactly what a stale cache serves.
             */
-            const stampInputs = [
-                hydrateName && `${PUBLIC}/${hydrateName}`,
-                `${PUBLIC}/${scriptName}`,
-                `${PUBLIC}/doc-system.css`,
-            ].filter(Boolean);
+            const stampInputs = assetStampInputs(PUBLIC, scriptName, hydrateName);
             /*
             Always a CONTENT HASH — the `opts.lock ? version : hash` branch is gone (major M3).
       

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

@@ -0,0 +1,29 @@
+import type { SiteConfig } from './site-config.js';
+export interface RestampResult {
+    /** the stamp now in every page */
+    stamp: string;
+    /** the stamp `buildSite` had written */
+    previous: string;
+    /** pages that carried a stamp */
+    pages: number;
+    /** pages whose stamp changed (0 when the bundle was not actually replaced) */
+    changed: number;
+}
+/** The hydration entry `buildSite` emitted for a `bundleEntry`, if there is one. */
+export declare function hydrateEntryIn(publicDir: string): string | undefined;
+/**
+ * What is wrong with the scripts the pages hydrate from, or null. ONE wording and one rule,
+ * for `buildSite` (asked of a `bundleEntry`'s output) and `restampSite` (asked of a file the
+ * project wrote itself). `subject` names what was read; `fix` says where the import goes.
+ */
+export declare function servedBundleProblem(source: string, subject: string, docsHaveExamples: boolean, fix?: string): string | null;
+/**
+ * Re-stamp a built site from the assets actually on disk, and check the hydration bundle.
+ * Call it after replacing `/iife.js` (or whatever `scriptUrl` names) in `outputDir`.
+ *
+ * Throws when no page carries a stamp (the build did not run, or `outputDir` is wrong): a
+ * restamp that silently did nothing is the failure it exists to prevent. A bundle that does
+ * not register the doc system is a warning, and fails under `strict: true`, as in
+ * `buildSite`.
+ */
+export declare function restampSite(config: SiteConfig): Promise<RestampResult>;