tosijs-ui 1.15.2 → 1.15.4

package/CHANGELOG.md

@@ -1,5 +1,128 @@
 # Changelog
 
+## 1.15.4
+
+### `libraryBundle`: a library build Node can actually load (#169)
+
+`emitLibrary` and `libraryTsconfig` run a bare `tsc`, which copies each import specifier through
+unchanged. Written in the usual bundler style (`export * from './model'`), that produces a
+`dist/` **Node refuses** (`ERR_MODULE_NOT_FOUND`), though Bun and bundlers resolve it, so it
+tends to ship unnoticed. Three projects had each written their own guard for it.
+
+The new `libraryBundle` option is the paved road:
+
+```ts
+libraryBundle: { entries: ['src/index.ts', 'src/core.ts'] }
+```
+
+`bun build` bundles the entries with code-splitting (every declared dependency and peer stays an
+import), `tsc` emits declarations only, and the build **fails** if `dist/` still has a relative
+import without a file extension. Options: `externals` (default: all declared dependencies and
+peers), `tsconfig` for the declaration pass, `target` (default `browser`). It needs `typescript`
+installed, as any TypeScript library has.
+
+`emitLibrary` and `libraryTsconfig` keep working, and now **warn** when their output has that
+problem.
+
+### Tag colours on chips and in the pick menu (#173)
+
+A Tag in `<tosi-tag-list>`'s `availableTags` can carry `background` and `color`. Chips now use
+them (they were ignored), and the pick menu shows each coloured tag's caption as a lozenge in
+those colours, with the checkmark beside it. Without a `color`, the text is black or white,
+whichever contrasts more.
+
+### Tag list fixes (#189)
+
+- A Tag object without a `caption` (the obvious way to colour chips: `{ value, color, background }`)
+  showed as a **blank row** in the pick menu; on a phone, a tall empty column. It now shows its
+  value.
+- A selected tag that was also in `availableTags` as an object appeared in the menu **twice**:
+  string tags were compared against Tag objects with `includes`. It now compares by value.
+- `<tosi-tag-list>`'s `value` is documented as `string | string[]`, but an array threw
+  `split is not a function` on render.
+
+### `emitLibrary` no longer ships `tsconfig.tsbuildinfo`
+
+Libraries built with `emitLibrary` shipped TypeScript's incremental-build cache in `dist/`: no
+use to consumers, and different on every rebuild. It is gone; rebuild and republish to drop it
+from your package.
+
+## 1.15.3
+
+### `<tosi-md sanitize="on">`, and a heads-up: it becomes the default in 1.16 (#179)
+
+`<tosi-md>` assigns rendered markdown to the page, and markdown can carry raw HTML. For text you
+did not write (issue bodies, comments, anything from a user or an API), that is a **stored
+XSS**: tosijs-virta's pre-release review demonstrated reading a token out of `localStorage`
+through an issue body with `<img onerror>`.
+
+`sanitize="on"` strips executable content (scripts, event-handler attributes, unsafe URL
+schemes) with [kilpi](https://www.npmjs.com/package/tosijs-kilpi), and drops any link that is
+not safe to navigate to. It **removes some elements together with everything inside them**:
+`script`, `style`, `iframe`, `object`, `embed`, `form`, `link`, `meta`, `base`, `noscript`,
+`template` and SVG animation elements. So markdown that embeds a `<form>` needs `sanitize="off"`.
+Markdown, ordinary links (relative, `#anchor`, `mailto:`), inputs and custom elements survive. A
+bare `<tosi-md sanitize>` also means on.
+
+**If you leave `sanitize` unset, nothing changes in this release** except one console warning
+per page. **In 1.16 the default becomes `on`.** Set `sanitize="on"` or `sanitize="off"` now and
+the upgrade will not affect you; `off` keeps raw HTML and is silent.
+
+`tosijs-kilpi` is a new runtime dependency: +865 bytes gzip on `dist/iife.js`.
+
+### Escape closes a `<tosi-dialog>` properly — `confirm`/`alert`/`prompt` no longer hang (#183)
+
+Escape let the browser close the native `<dialog>` directly, bypassing `close()`. So
+`await TosiDialog.confirm(...)` (and `alert`, `prompt`) **never settled**, the `showModal()`
+promise never resolved, and a `removeOnClose` dialog stayed in the DOM, one leaked element per
+Escape. Escape now closes with `'cancel'` through the same path as the Cancel button. So does
+the browser closing the element on its own (a `<form method="dialog">`, or Chrome refusing a
+repeated Escape), so nothing waits forever.
+
+**New: `dialogWillClose` can refuse a close.** Return `false`, or a Promise of `false`, and the
+dialog stays open, e.g. while an async save is in flight. `close()` now returns whether it
+closed. Reported by snowfox-app, which carried a workaround at nine sites.
+
+The default `dialogWillClose` no longer `console.log`s on every close, and the docs now say that
+the built-in **OK** button sits beside footer buttons rather than being replaced by them.
+
+### Icon types: `IconElement` is importable, and `icons.x()` needs no `!` (#176, #181)
+
+- `IconElement`, `IconName` and `SVGIconMap` are exported from `tosijs-ui/icons`:
+  `import { icons, type IconElement } from 'tosijs-ui/icons'`. 1.15 widened the icon return
+  type from `SVGElement` to `SVGElement | HTMLSpanElement` (a composite icon is a span), and
+  there was no importable name for the new union.
+- Under `noUncheckedIndexedAccess`, every `icons.user()` read as possibly undefined, forcing
+  `icons.user!()` everywhere. Built-in icon names are now explicit keys of the type, so the `!`
+  can go, and a misspelled `IconName` is a type error. Composites and `defineIcons()` names
+  still go through the index signature.
+- `tosijs-make-icons` now generates `satisfies IconData` rather than `as IconData`, which keeps
+  icon names in the type system. **It needs TypeScript 4.9 or later** in the project that runs
+  it.
+
+### `tagList.popSelectMenu` can be replaced after the element is on the page (#172)
+
+The documented "replace this method" hook only worked if you replaced it before the element
+connected, which `tosiTagList({...})` never allows: the button captured the original function.
+It now looks the method up on every click.
+
+### Doc-site sourcemaps no longer expose the build machine's paths
+
+A doc site built with `bundleEntry` published sourcemaps whose sources climbed to the
+filesystem root and into the builder's home directory (`../../../../../../Users/<name>/…`),
+because the hydration bundle was built in the OS temp directory. The deployed site revealed
+the build machine's directory layout, and two machines could not produce the same site. The
+bundle is now built under your project's `node_modules/.cache`, and its maps are rewritten to
+point at the sources from where they are served, so devtools find them and every machine
+builds identical output. Rebuild your site to replace the old maps.
+
+### `/version.json`: what `commit` means (#180)
+
+Documentation only. Since #122, a content-identical rebuild keeps the previous stamp, so `commit`
+is the last commit whose build *changed the site*, and can be older than `HEAD`. To check that
+committed output matches `HEAD`, rebuild and confirm the tree is clean. `doc-site-system.md` now
+says so and shows `contentHash`.
+
 ## 1.15.2
 
 ### The `tjs-lang` peer admits 0.14.x (#182)

package/bin/make-icon-data.js

@@ -414,7 +414,10 @@ let source =
   (typeDeclaration ? typeDeclaration + '\n\n' : '') +
   'export default ' +
   emitObject(iconData) +
-  (isTypescript ? ' as IconData\n' : '\n')
+  // `satisfies`, not `as`: `as IconData` widened the keys to `string`, so the icon NAMES were
+  // lost to the type system and `icons.user` read as possibly-undefined under
+  // noUncheckedIndexedAccess (#181). `satisfies` checks the shape and keeps the names.
+  (isTypescript ? ' satisfies IconData\n' : '\n')
 
 /*
 If prettier is resolvable, let it have the last word — it picks up the CONSUMER's own

package/dist/dialog.d.ts

@@ -51,10 +51,22 @@ export declare class TosiDialog extends Component<DialogParts> {
     removeOnClose: boolean;
     closeOnBackgroundClick: boolean;
     constructor();
-    dialogWillClose: (reason?: string) => void;
+    /**
+    Called before the dialog closes, with the reason (`'confirm'`, `'cancel'`, or whatever was
+    passed to `close()`). Return `false` — or a Promise resolving to `false` — to refuse the
+    close, e.g. while an async save is in flight: a dialog that cannot be cancelled must not
+    look as though it was.
+    */
+    dialogWillClose: (_reason?: string) => void | boolean | Promise<void | boolean>;
     initialFocus(): void;
     showModal: () => Promise<string | null>;
-    close: (reason?: string) => void;
+    /**
+    Close the dialog unless `dialogWillClose` vetoes it. Returns whether it closed — a Promise
+    of that when `dialogWillClose` is async.
+    */
+    close: (reason?: string) => boolean | Promise<boolean>;
+    onCancel: (event: Event) => void;
+    onNativeClose: () => void;
     ok: () => void;
     content: () => HTMLDialogElement;
 }

package/dist/dialog.js

@@ -43,6 +43,32 @@ test('dialog has header slot content', () => {
 })
 ```
 
+The dialog always supplies its own **OK** button (`part="ok"`, which closes with
+`'confirm'`). Buttons you put in the `footer` slot appear **beside** it, not instead of it, so
+add a Cancel button there, not a second OK.
+
+## Closing
+
+Every way a dialog closes — the OK button, `close(reason)`, a background click when
+`closeOnBackgroundClick` is set, **Escape**, or a `<form method="dialog">` — goes through the
+same path: `dialogWillClose(reason)` is called, the `showModal()` promise resolves with the
+reason, and a `removeOnClose` dialog removes itself. Escape closes with `'cancel'`.
+
+`dialogWillClose` can **refuse** a close by returning `false`, or a Promise resolving to
+`false`. Use it for a dialog that must not be dismissed while it is busy, such as an async save
+in flight. `close()` returns whether the dialog closed, or a Promise of that when
+`dialogWillClose` is async.
+
+```typescript
+const editor = tosiDialog({
+  dialogWillClose: () => !saving, // Escape and Cancel do nothing mid-save
+})
+```
+
+The browser can close a `<dialog>` without asking (a `<form method="dialog">` submission, or a
+repeated Escape without fresh user interaction in Chrome). Those cannot be refused; the dialog
+still calls `dialogWillClose` and resolves, so nothing waits forever.
+
 ## Static Functions
 
 `TosiDialog` provides static async functions to replace the built-in dialogs provided by
@@ -232,8 +258,14 @@ export class TosiDialog extends Component {
             }
         });
     }
-    dialogWillClose = (reason = 'cancel') => {
-        console.log('dialog will close with', reason);
+    /**
+    Called before the dialog closes, with the reason (`'confirm'`, `'cancel'`, or whatever was
+    passed to `close()`). Return `false` — or a Promise resolving to `false` — to refuse the
+    close, e.g. while an async save is in flight: a dialog that cannot be cancelled must not
+    look as though it was.
+    */
+    dialogWillClose = (_reason = 'cancel') => {
+        /* override to observe or veto */
     };
     initialFocus() {
         this.parts.ok.focus();
@@ -241,8 +273,16 @@ export class TosiDialog extends Component {
     #modalResolution = (_outcome) => {
         /* noop */
     };
+    /*
+    True once this showing's close side effects have run — resolution, removal — so that no path
+    runs them twice. Every route to "closed" funnels into #finish, and there are three: close()
+    (buttons, background click, callers), Escape (the native `cancel`), and the browser closing
+    the element on its own (the native `close` event, below).
+    */
+    #settled = false;
     showModal = () => {
         this.style.zIndex = String(findHighestZ());
+        this.#settled = false;
         return new Promise((resolve) => {
             this.#modalResolution = resolve;
             this.parts.dialog.showModal();
@@ -251,17 +291,59 @@ export class TosiDialog extends Component {
             });
         });
     };
+    /**
+    Close the dialog unless `dialogWillClose` vetoes it. Returns whether it closed — a Promise
+    of that when `dialogWillClose` is async.
+    */
     close = (reason = 'cancel') => {
-        this.dialogWillClose(reason);
+        if (this.#settled) {
+            return true;
+        }
+        const verdict = this.dialogWillClose(reason);
+        if (verdict instanceof Promise) {
+            return verdict.then((v) => (v === false ? false : this.#finish(reason)));
+        }
+        return verdict === false ? false : this.#finish(reason);
+    };
+    #finish(reason) {
+        if (this.#settled) {
+            return true;
+        }
+        this.#settled = true;
         this.#modalResolution(reason);
-        this.parts.dialog.close();
+        if (this.parts.dialog.open) {
+            this.parts.dialog.close();
+        }
         if (this.removeOnClose) {
             this.remove();
         }
+        return true;
+    }
+    /*
+    Escape (#183). The browser would close the <dialog> itself and bypass close(), so the static
+    helpers never resolved and removeOnClose leaked the element. Take the close over instead,
+    which is also what lets dialogWillClose veto it.
+    */
+    onCancel = (event) => {
+        event.preventDefault();
+        this.close('cancel');
+    };
+    /*
+    The browser can still close the element without asking: Chrome's close-watcher makes a repeat
+    `cancel` non-cancelable without fresh user activation, and `<form method="dialog">` closes it
+    directly. Too late to veto, so tell dialogWillClose and settle, rather than hang the caller.
+    */
+    onNativeClose = () => {
+        if (this.#settled) {
+            return;
+        }
+        const reason = this.parts.dialog.returnValue || 'cancel';
+        this.dialogWillClose(reason);
+        this.#finish(reason);
     };
     ok = () => {
         this.close('confirm');
     };
-    content = () => dialog({ part: 'dialog' }, header(tosiSlot({ name: 'header' })), tosiSlot(), footer(tosiSlot({ name: 'footer' }), button({ part: 'ok', onClick: this.ok }, 'OK')));
+    content = () => dialog({ part: 'dialog', onCancel: this.onCancel, onClose: this.onNativeClose }, header(tosiSlot({ name: 'header' })), tosiSlot(), footer(tosiSlot({ name: 'footer' }), button({ part: 'ok', onClick: this.ok }, 'OK')));
 }
 export const tosiDialog = TosiDialog.elementCreator();

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

@@ -3,7 +3,12 @@ export interface BuildStamp {
     generator: string;
     /** the project's name, from site config */
     site?: string;
-    /** short commit hash the site was built from, when available */
+    /**
+     * Short hash of the last commit whose build CHANGED the site's content, when available.
+     * A content-identical rebuild keeps the previous value (see `stampToWrite`, #122), so this
+     * can be older than HEAD — to check committed output matches HEAD, rebuild and check the
+     * tree is clean instead (#180).
+     */
     commit?: string;
     /** ISO-8601 commit timestamp, when available */
     commitTime?: string;

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

@@ -8,6 +8,7 @@ export { openDevBrowser, buildOpenPlan } from './open-browser.js';
 export type { OpenPlan, OpenPlanInput } from './open-browser.js';
 export { extractDocs, saveDocsJSON } from './docs.js';
 export type { Doc } from './docs.js';
+export type { LibraryBundle } from './library-bundle.js';
 export { generateSite } from './generate-site.js';
 export type { GenerateSiteConfig } from './generate-site.js';
 export { buildEpub, DEFAULT_BOOK_CSS } from './epub.js';

package/dist/doc-system/site/library-bundle.d.ts

@@ -0,0 +1,26 @@
+export interface LibraryBundle {
+    /** Entry points relative to the project root, e.g. `['src/index.ts', 'src/core.ts']`. */
+    entries: string[];
+    /**
+     * Packages left as imports instead of bundled (each also matches its subpaths). Default:
+     * every `dependencies`, `peerDependencies` and `optionalDependencies` name in package.json.
+     */
+    externals?: string[];
+    /** tsconfig for the declaration pass (run with `--emitDeclarationOnly`). Default: the root one. */
+    tsconfig?: string;
+    /** `bun build --target`. Default `browser`. */
+    target?: 'browser' | 'node' | 'bun';
+}
+interface PackageJsonDeps {
+    dependencies?: Record<string, string>;
+    peerDependencies?: Record<string, string>;
+    optionalDependencies?: Record<string, string>;
+}
+/** The externals to use: the configured list, or every declared runtime dependency. */
+export declare function bundleExternals(bundle: LibraryBundle, pkg: PackageJsonDeps): string[];
+/** The `bun build` argv for the JavaScript half. */
+export declare function bundleBuildArgs(bundle: LibraryBundle, pkg: PackageJsonDeps, outdir: string): string[];
+/** The `tsc` argv for the declaration half. */
+export declare function bundleDeclarationArgs(bundle: LibraryBundle, outdir: string): string[];
+export declare function extensionlessImports(dir: string): string[];
+export {};

package/dist/doc-system/site/library-bundle.js

@@ -0,0 +1,100 @@
+/*
+The bundled library build (`SiteConfig.libraryBundle`, #169).
+
+`emitLibrary` / `libraryTsconfig` run a bare `tsc`, which copies each source file's import
+specifiers into the output unchanged. Written in bundler style (`export * from './model'`), that
+output is a `dist/` Node refuses: `ERR_MODULE_NOT_FOUND .../dist/model`. Bun resolves it, so
+nothing in a Bun build or test loop notices, and it ships. tosijs-3d, tosijs-3d-ensemble and
+tosijs-virta each grew their own guard for this, in three different shapes.
+
+This is the paved road instead: `bun build` bundles the entries with splitting (its output
+imports its own chunks WITH extensions, by construction), every declared dependency and peer
+stays an import rather than being bundled, and `tsc` emits declarations only. The result is
+then scanned for relative imports without an extension, and any hit fails the build — the
+guard the three repos wrote, done once.
+
+Every heavy step runs as a CHILD process (`bun build`, `tsc`): this code also runs inside the
+long-lived dev server, where Bun.build() leaks its native arena on every call.
+*/
+import { readdirSync, readFileSync, statSync } from 'fs';
+import * as path from 'path';
+/** The externals to use: the configured list, or every declared runtime dependency. */
+export function bundleExternals(bundle, pkg) {
+    const names = bundle.externals ?? [
+        ...Object.keys(pkg.dependencies ?? {}),
+        ...Object.keys(pkg.peerDependencies ?? {}),
+        ...Object.keys(pkg.optionalDependencies ?? {}),
+    ];
+    return [...new Set(names)].sort();
+}
+/** The `bun build` argv for the JavaScript half. */
+export function bundleBuildArgs(bundle, pkg, outdir) {
+    return [
+        'bun',
+        'build',
+        ...bundle.entries,
+        '--outdir',
+        outdir,
+        '--format',
+        'esm',
+        '--splitting',
+        '--target',
+        bundle.target ?? 'browser',
+        '--sourcemap=linked',
+        ...bundleExternals(bundle, pkg).flatMap((name) => [
+            '--external',
+            name,
+            '--external',
+            `${name}/*`,
+        ]),
+    ];
+}
+/** The `tsc` argv for the declaration half. */
+export function bundleDeclarationArgs(bundle, outdir) {
+    return [
+        'bun',
+        'tsc',
+        ...(bundle.tsconfig ? ['-p', bundle.tsconfig] : []),
+        '--declaration',
+        '--emitDeclarationOnly',
+        // a root tsconfig with `noEmit: true` would otherwise emit nothing at all
+        '--noEmit',
+        'false',
+        '--outDir',
+        outdir,
+    ];
+}
+const HAS_EXTENSION = /\.(?:m?js|cjs|json)$/;
+/*
+Real imports, from Bun's parser rather than a regex: a regex also matched specifiers quoted in
+COMMENTS — four false hits in tosijs-ui's own dist, one of them this file's own doc comment.
+One Transpiler for the process: each construction costs ~40KB that is never returned, and this
+runs inside the long-lived dev server (see CLAUDE.md, "Dev servers are the most dangerous thing").
+*/
+let transpiler;
+function importsOf(source) {
+    transpiler ??= new Bun.Transpiler({ loader: 'js' });
+    return transpiler
+        .scanImports(source)
+        .map((entry) => entry.path);
+}
+export function extensionlessImports(dir) {
+    const found = [];
+    const walk = (current) => {
+        for (const name of readdirSync(current)) {
+            const full = path.join(current, name);
+            if (statSync(full).isDirectory()) {
+                walk(full);
+            }
+            else if (/\.m?js$/.test(name)) {
+                for (const specifier of importsOf(readFileSync(full, 'utf8'))) {
+                    if (/^\.{1,2}\//.test(specifier) && !HAS_EXTENSION.test(specifier)) {
+                        found.push(`${path.relative(dir, full)}: ${specifier}`);
+                    }
+                }
+            }
+        }
+    };
+    walk(dir);
+    return found;
+}

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

@@ -28,6 +28,7 @@ export declare function shouldCleanDist(config: {
     emitLibrary?: boolean;
     libraryTsconfig?: string;
     libraryBuild?: unknown;
+    libraryBundle?: unknown;
 }): boolean;
 export declare function buildSite(config: SiteConfig, opts?: {
     skipAudit?: boolean;

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

@@ -16,10 +16,12 @@ import { namedBooks, partitionByBook, DEFAULT_BOOK } from '../book-target.js';
 import { listEpubVolumes, renderEpubDownloads } from './epub-volumes.js';
 import { buildSlugMap } from '../routing.js';
 import { computeAssetStamp, missingStampInputWarning } from './asset-stamp.js';
-import { existsSync, mkdirSync, unlinkSync } from 'fs';
+import { existsSync, mkdirSync, readFileSync, unlinkSync } from 'fs';
 import { tmpdir } from 'os';
 import { $, spawn } from 'bun';
 import { extractDocs } from './docs.js';
+import { relocateSourcemaps } from './sourcemap-relocate.js';
+import { bundleBuildArgs, bundleDeclarationArgs, extensionlessImports, } from './library-bundle.js';
 import { checkExamples, formatExampleProblems, } from './check-examples.js';
 import { ensureSections } from './sections.js';
 import { generateLlmsTxt } from './make-llms-txt.js';
@@ -347,7 +349,9 @@ export function shouldCleanDist(config) {
     // even alongside the other flags — the consumer's function is the authority.
     if (config.libraryBuild)
         return false;
-    return config.emitLibrary === true || Boolean(config.libraryTsconfig);
+    return (config.emitLibrary === true ||
+        Boolean(config.libraryTsconfig) ||
+        Boolean(config.libraryBundle));
 }
 /*
 Announce-once state for the "writes outside outputDir" warning.
@@ -713,8 +717,9 @@ export async function buildSite(config, opts = {}) {
                 directory and may legitimately emit a subset, which is exactly the reported case.
               - nothing configured — NOT cleaned. Nothing here owns it.
       
-            Incidental win: `emitLibrary` runs `tsc --incremental`, whose `.tsbuildinfo` lives in
-            `dist/`. Wiping it every run meant incremental compilation never once did anything.
+            `emitLibrary` used to run `tsc --incremental`, whose `.tsbuildinfo` lived in `dist/`; wiping
+            it every run meant incremental compilation never once did anything. It no longer runs
+            incrementally at all — see the tsc call below for why moving the cache is not the fix.
             */
             if (shouldCleanDist(config)) {
                 await $ `rm -rf ${DIST}`.text();
@@ -747,6 +752,36 @@ export async function buildSite(config, opts = {}) {
                     tsconfig: config.libraryTsconfig,
                 });
             }
+            else if (config.libraryBundle) {
+                // The bundled library build (#169): child processes only, never Bun.build() here.
+                const pkg = JSON.parse(readFileSync(path.resolve(PROJECT_ROOT, 'package.json'), 'utf8'));
+                for (const [what, argv] of [
+                    ['bun build', bundleBuildArgs(config.libraryBundle, pkg, DIST)],
+                    [
+                        'tsc --emitDeclarationOnly',
+                        bundleDeclarationArgs(config.libraryBundle, DIST),
+                    ],
+                ]) {
+                    const child = spawn([...argv], { stdout: 'pipe', stderr: 'pipe' });
+                    const output = await drainChild(child);
+                    if ((await child.exited) !== 0) {
+                        console.error(output);
+                        console.error(`❌ libraryBundle: ${what} FAILED — dist/ is incomplete. Build marked failed.` +
+                            (/Script not found "tsc"/.test(output)
+                                ? ' TypeScript is not installed in this project: `bun add -d typescript`.'
+                                : ''));
+                        libraryBuildFailed = true;
+                        break;
+                    }
+                }
+                if (!libraryBuildFailed) {
+                    const bad = extensionlessImports(DIST);
+                    if (bad.length) {
+                        console.error(`❌ libraryBundle: dist/ has relative imports without a file extension, which Node cannot load:\n  ${bad.join('\n  ')}`);
+                        libraryBuildFailed = true;
+                    }
+                }
+            }
             else if (config.libraryTsconfig) {
                 // Consumer-controlled library build (handles root noEmit, removeComments,
                 // outDir, etc.). tsc output is left visible so the errors are readable.
@@ -758,13 +793,38 @@ export async function buildSite(config, opts = {}) {
                 }
             }
             else if (config.emitLibrary) {
-                const r = await $ `bun tsc --declaration --incremental --outDir dist`.nothrow();
+                /*
+                NOT --incremental. Its .tsbuildinfo lived in dist/, so it shipped in every adopter's
+                tarball (and ours), and it differs between a first and a second build — which the publish
+                workflow's "shipped files reproduce" check rightly rejects. Moving the cache elsewhere is
+                WORSE: dist/ is wiped every build (above), and tsc trusts the cache, sees nothing changed,
+                and emits nothing — measured, the second build deleted 883 files from dist/. Since dist/
+                is always clean, incremental compilation could never help here anyway.
+                */
+                const r = await $ `bun tsc --declaration --outDir dist`.nothrow();
                 if (r.exitCode !== 0) {
                     console.error(`❌ tsc --declaration FAILED (exit ${r.exitCode}) — emitted dist/*.d.ts may ` +
                         `be stale or contain type errors. Build marked failed.`);
                     libraryBuildFailed = true;
                 }
             }
+            /*
+            A bare tsc copies bundler-style specifiers into dist/ unchanged, and Node cannot load the
+            result (#169). Say so loudly on those two paths. Not a failure: it would break working
+            builds for consumers who only ever bundle, on a patch upgrade. libraryBundle fails on it.
+            */
+            if (!libraryBuildFailed &&
+                !config.libraryBuild &&
+                !config.libraryBundle &&
+                (config.libraryTsconfig || config.emitLibrary) &&
+                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]}`);
+                }
+            }
             // The hydration bundle. If bundleEntry is set we build it (IIFE), else pages
             // load config.scriptUrl (default /iife.js) — a prebuilt/CDN bundle the
             // consumer supplies (e.g. via staticDirs or an absolute URL).
@@ -951,8 +1011,17 @@ export async function buildSite(config, opts = {}) {
               Build it in a temp dir instead. The only consumer is the copy into PUBLIC on the
               next line, so nothing needs it to persist — and a temp dir cannot be swept into a
               published tarball by a broad `files` entry.
+        
+              Not the OS temp dir, though. `bun build` writes each sourcemap `sources` entry relative
+              to the OUTPUT dir, so from /tmp every path climbed to `/` and back down into the builder's
+              home — `../../../../../../Users/<name>/<project>/node_modules/…`. That published the
+              build machine's layout in every chunk map, and made docs/ differ between any two
+              machines, which failed the publish workflow's rebuild check (#178). Under the project's
+              own node_modules/.cache the paths are project-relative, so identical everywhere, and it
+              is equally out of reach of a `files` entry.
               */
-                const HYDRATE_DIR = `${tmpdir()}/tosijs-hydrate-${process.pid}`;
+                const HYDRATE_DIR = path.resolve(PROJECT_ROOT, 'node_modules/.cache', `tosijs-hydrate-${process.pid}`);
+                mkdirSync(path.dirname(HYDRATE_DIR), { recursive: true });
                 await $ `rm -rf ${HYDRATE_DIR}`.text().catch(() => { });
                 const esm = spawn([
                     'bun',
@@ -998,6 +1067,8 @@ export async function buildSite(config, opts = {}) {
                 // Copy the whole ESM output (entry + hashed chunks) to the served root — the entry
                 // imports its chunks by RELATIVE path, so they must sit right beside it.
                 await $ `cp -R ${HYDRATE_DIR}/. ${PUBLIC}/`.text();
+                // The copy moved every map; re-point their sources from where they now sit (#178).
+                relocateSourcemaps(HYDRATE_DIR, PUBLIC);
                 hydrateName = 'hydrate.js';
                 /*
                 `bundleEntry` REPLACES our bundle rather than extending it, and an entry that forgets

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

@@ -1,3 +1,4 @@
+import type { LibraryBundle } from './library-bundle.js';
 import type { ProjectLinks, LinkItem } from '../../doc-browser.js';
 import type { DocSystemTheme } from '../doc-system-styles.js';
 import type { Doc } from './docs.js';
@@ -192,10 +193,23 @@ export interface SiteConfig {
      */
     prebuild?: () => void | Promise<void>;
     /**
-     * Also build the library: `tsc --declaration --incremental --outDir dist`
-     * (ESM + types). Default false. Repos whose single build publishes BOTH an
-     * npm package and its doc site (the tosijs-* libs) set this true; a pure docs
-     * site omits it. Ignored when `libraryTsconfig` is set.
+     * Build the library as a BUNDLE — the recommended library build (#169). `bun build` bundles
+     * `entries` with splitting into `dist/` (declared dependencies and peers stay imports), then
+     * `tsc` emits declarations only. The output is checked for relative imports without a file
+     * extension, which Node cannot load, and the build fails on any. Owns `dist/` (cleaned each
+     * build). Takes precedence over `libraryTsconfig` / `emitLibrary`; a `libraryBuild`
+     * function takes precedence over it.
+     *
+     * ```ts
+     * libraryBundle: { entries: ['src/index.ts', 'src/core.ts'] }
+     * ```
+     */
+    libraryBundle?: LibraryBundle;
+    /**
+     * Also build the library: `tsc --declaration --outDir dist` (ESM + types). Default false.
+     * **Prefer `libraryBundle`:** a bare tsc copies bundler-style specifiers (`from './model'`)
+     * into `dist/` unchanged, and Node cannot load that; the build warns when it happens.
+     * Ignored when `libraryTsconfig` is set.
      */
     emitLibrary?: boolean;
     /**

package/dist/doc-system/site/sourcemap-relocate.d.ts

@@ -0,0 +1,7 @@
+/** Re-express one map's sources, as if the map moved from `fromDir` to `toDir`. */
+export declare function relocateSources(sources: string[], fromDir: string, toDir: string): string[];
+/**
+ * For every `.map` under `builtDir`, write a copy at the same relative path under
+ * `servedDir` with its `sources` rewritten for that location.
+ */
+export declare function relocateSourcemaps(builtDir: string, servedDir: string): void;