tosijs-ui 1.6.18 → 1.6.20

package/CHANGELOG.md

@@ -1,5 +1,50 @@
 # Changelog
 
+## 1.6.20
+
+### Fixed
+
+- **`import 'tosijs-ui'` no longer resolves to the IIFE under browser bundlers.**
+  The `"."` export had a `"browser"` condition pointing at `dist/iife.js` — the
+  self-contained CDN/doc-site bundle that inlines tosijs + marked. Browser-targeted
+  bundlers (Vite, webpack, esbuild) picked it, so consumers **double-bundled tosijs**
+  instead of externalizing the peer, and named imports broke (the IIFE isn't an ESM
+  module). Removed the condition: every `import` now resolves to `dist/index.js`
+  (ESM, peers externalized). The IIFE stays for CDN `<script>` use and the naive
+  doc site — referenced by file path, never via `import 'tosijs-ui'`.
+
+### Changed
+
+- **tosijs peer + dev dependency bumped to `^1.6.6`** — picks up a subtle
+  component-lifecycle fix.
+
+## 1.6.19
+
+Doc-system tooling; no component API changes.
+
+### Added
+
+- **Build-time example transpile check.** Every executable live-example block
+  (`js` / `tjs` / `ts` / `test`) across the whole corpus is run through the front
+  half of the runtime pipeline — `rewriteImports` → transform → `new
+  AsyncFunction` — at build time, **without executing it**, so a block that can't
+  build (a syntax/import error, or illustrative code mistakenly tagged with an
+  executable language instead of the display-only `typescript`) **fails the build**
+  with the offending doc/block named, on every page — including fences hidden in
+  blockquotes and lists. TypeScript is transpiled with bun's own transpiler
+  (network-free). Opt out with `checkExamples: false`.
+- **"One Source, Every Artifact"** doc page — how one corpus of doc-comments +
+  markdown projects into a static SEO site, a self-testing live playground with
+  in-browser TypeScript, an ePub/PDF, and an agent-debuggable page. Embeds a live
+  `<tosi-doc-system>` (the whole system running inside its own page).
+
+### Fixed
+
+- **A live example's build/exec failure is now a test failure whether or not it
+  defines `test` blocks.** So on any page the browser test runner loads, *all* of
+  its examples are checked for explosions — a no-test example that throws is
+  reported as a failed test — not just blocks with explicit assertions.
+
 ## 1.6.18
 
 Doc-site tooling; no component API changes.

package/dist/code-editor-cm.d.ts

@@ -0,0 +1,30 @@
+import { EditorView } from '@codemirror/view';
+import { Extension } from '@codemirror/state';
+/** Map a `<tosi-code mode>` value to a CodeMirror language extension. */
+export declare function languageForMode(mode: string): Extension;
+export interface CmHandle {
+    view: EditorView;
+    getValue(): string;
+    setValue(text: string): void;
+    setMode(mode: string): void;
+    setReadOnly(readOnly: boolean): void;
+    undo(): void;
+    redo(): void;
+    canUndo(): boolean;
+    canRedo(): boolean;
+    focus(): void;
+    refresh(): void;
+    destroy(): void;
+}
+export interface CmOptions {
+    value?: string;
+    mode?: string;
+    readOnly?: boolean;
+    /** additional language-adjacent extensions (e.g. a tjs language + autocomplete) */
+    languageExtension?: Extension;
+    onChange?: (value: string) => void;
+    /** style-injection root — pass the host's ShadowRoot when mounted in shadow DOM */
+    root?: Document | ShadowRoot;
+}
+/** Create a CodeMirror editor mounted in `parent`, returning an editor-agnostic handle. */
+export declare function createCmEditor(parent: HTMLElement, opts?: CmOptions): CmHandle;

package/dist/code-editor-cm.js

@@ -0,0 +1,132 @@
+/*
+CodeMirror 6 editor factory — the "heavy" module.
+
+`code-editor.ts` imports this **dynamically** (on first `<tosi-code>` connect), so
+CodeMirror only enters a consumer's bundle as a separate lazy chunk when the editor
+is actually used — mirroring the way the old ACE build loaded from a CDN on first
+use. No `<tosi-code>` in the page → no CodeMirror.
+
+Languages here are the always-available set (js/ts/css/html/markdown). First-class
+tjs (highlighting + runtime-value autocomplete via tjs-lang's editors/codemirror) is
+layered in separately and only when tjs-lang is installed.
+*/
+import { EditorView, keymap, lineNumbers, highlightActiveLineGutter, highlightSpecialChars, drawSelection, dropCursor, rectangularSelection, crosshairCursor, highlightActiveLine } from '@codemirror/view';
+import { EditorState, Compartment } from '@codemirror/state';
+import { indentWithTab, history, defaultKeymap, historyKeymap, undo, redo, undoDepth, redoDepth } from '@codemirror/commands';
+import { indentUnit, foldGutter, foldKeymap, indentOnInput, syntaxHighlighting, defaultHighlightStyle, bracketMatching } from '@codemirror/language';
+import { closeBrackets, closeBracketsKeymap, autocompletion, completionKeymap } from '@codemirror/autocomplete';
+import { searchKeymap, highlightSelectionMatches } from '@codemirror/search';
+import { lintKeymap } from '@codemirror/lint';
+import { javascript } from '@codemirror/lang-javascript';
+import { css } from '@codemirror/lang-css';
+import { html } from '@codemirror/lang-html';
+import { markdown } from '@codemirror/lang-markdown';
+/** Map a `<tosi-code mode>` value to a CodeMirror language extension. */
+export function languageForMode(mode) {
+    switch (mode) {
+        case 'js':
+        case 'javascript':
+            return javascript();
+        case 'ts':
+        case 'typescript':
+        // tjs highlights fine as TypeScript until the tjs-lang language is wired
+        // (workstream B); this keeps `mode="tjs"` readable today.
+        case 'tjs':
+        case 'ajs':
+            return javascript({ typescript: true });
+        case 'css':
+            return css();
+        case 'html':
+            return html();
+        case 'md':
+        case 'markdown':
+            return markdown();
+        default:
+            return javascript();
+    }
+}
+// A basicSetup-equivalent without a hard-coded color theme, so the host page's CSS
+// (and dark mode) controls the palette. Line-wrapping mirrors the old ACE `wrap:true`.
+function baseExtensions() {
+    return [
+        lineNumbers(),
+        highlightActiveLineGutter(),
+        highlightSpecialChars(),
+        history(),
+        foldGutter(),
+        drawSelection(),
+        dropCursor(),
+        EditorState.allowMultipleSelections.of(true),
+        indentOnInput(),
+        indentUnit.of('  '),
+        EditorState.tabSize.of(2),
+        syntaxHighlighting(defaultHighlightStyle, { fallback: true }),
+        bracketMatching(),
+        closeBrackets(),
+        autocompletion(),
+        rectangularSelection(),
+        crosshairCursor(),
+        highlightActiveLine(),
+        highlightSelectionMatches(),
+        EditorView.lineWrapping,
+        keymap.of([
+            indentWithTab,
+            ...closeBracketsKeymap,
+            ...defaultKeymap,
+            ...searchKeymap,
+            ...historyKeymap,
+            ...foldKeymap,
+            ...completionKeymap,
+            ...lintKeymap,
+        ]),
+    ];
+}
+/** Create a CodeMirror editor mounted in `parent`, returning an editor-agnostic handle. */
+export function createCmEditor(parent, opts = {}) {
+    const language = new Compartment();
+    const readonly = new Compartment();
+    const langExt = opts.languageExtension ?? languageForMode(opts.mode ?? 'javascript');
+    const view = new EditorView({
+        parent,
+        root: opts.root,
+        state: EditorState.create({
+            doc: opts.value ?? '',
+            extensions: [
+                baseExtensions(),
+                language.of(langExt),
+                readonly.of(EditorState.readOnly.of(!!opts.readOnly)),
+                EditorView.updateListener.of((u) => {
+                    if (u.docChanged && opts.onChange)
+                        opts.onChange(u.state.doc.toString());
+                }),
+            ],
+        }),
+    });
+    const handle = {
+        view,
+        getValue: () => view.state.doc.toString(),
+        setValue(text) {
+            if (view.state.doc.toString() === text)
+                return;
+            view.dispatch({
+                changes: { from: 0, to: view.state.doc.length, insert: text },
+            });
+        },
+        setMode(mode) {
+            view.dispatch({ effects: language.reconfigure(languageForMode(mode)) });
+        },
+        setReadOnly(ro) {
+            view.dispatch({
+                effects: readonly.reconfigure(EditorState.readOnly.of(ro)),
+            });
+        },
+        undo: () => void undo(view),
+        redo: () => void redo(view),
+        canUndo: () => undoDepth(view.state) > 0,
+        canRedo: () => redoDepth(view.state) > 0,
+        focus: () => view.focus(),
+        refresh: () => view.requestMeasure(),
+        destroy: () => view.destroy(),
+    };
+    return handle;
+}

package/dist/code-editor.d.ts

@@ -1,7 +1,15 @@
-import { Component as WebComponent, ElementCreator } from 'tosijs';
-export declare class CodeEditor extends WebComponent {
+import { Component as WebComponent, ElementCreator, PartsMap } from 'tosijs';
+import type { CmHandle } from './code-editor-cm';
+interface CodeEditorParts extends PartsMap {
+    host: HTMLDivElement;
+}
+export declare class CodeEditor extends WebComponent<CodeEditorParts> {
     static preferredTagName: string;
     private source;
+    private _handle;
+    private _loadPromise;
+    private _appliedMode;
+    private _appliedDisabled;
     get value(): string;
     set value(text: string);
     private _original;
@@ -12,16 +20,16 @@ export declare class CodeEditor extends WebComponent {
     showDiff(on: boolean): void;
     static initAttributes: {
         mode: string;
-        theme: string;
         disabled: boolean;
     };
     role: string;
-    private _ace;
-    private _editor;
-    private _editorPromise;
-    options: any;
-    get ace(): any;
-    get editor(): any;
+    /** The underlying CodeMirror EditorView (undefined until loaded). */
+    get editor(): CmHandle['view'] | undefined;
+    undo(): void;
+    redo(): void;
+    canUndo(): boolean;
+    canRedo(): boolean;
+    content: () => HTMLDivElement[];
     static shadowStyleSpec: {
         ':host': {
             display: string;
@@ -29,9 +37,20 @@ export declare class CodeEditor extends WebComponent {
             width: string;
             height: string;
         };
+        '[part="host"]': {
+            height: string;
+        };
+        '.cm-editor': {
+            height: string;
+        };
+        '.cm-scroller': {
+            outline: string;
+            fontFamily: string;
+        };
     };
     onResize(): void;
     connectedCallback(): void;
     render(): void;
 }
 export declare const codeEditor: ElementCreator<CodeEditor>;
+export {};

package/dist/code-editor.js

@@ -1,12 +1,12 @@
 /*#
 # code
 
-An [ACE Editor](https://ace.c9.io/) wrapper.
+A [CodeMirror 6](https://codemirror.net/) wrapper.
 
 Sometimes, it's nice to be able to just toss a code-editor in a web-page.
 
-`<tosi-code>`'s `value` is the code it contains. Its `mode` attribute sets the language, and you can further configure
-the ACE editor instance via its `options` property.
+`<tosi-code>`'s `value` is the code it contains. Its `mode` attribute sets the
+language (`javascript`, `typescript`, `tjs`, `css`, `html`, `markdown`).
 
 ```html
 <tosi-code style="width: 100%; height: 100%" mode="css">
@@ -16,51 +16,33 @@ body {
 </tosi-code>
 ```
 
-The `<tosi-code>` element has an `editor` property that gives you its ACE editor instance,
-and an `ace` property that returns the `ace` module, giving you complete access to the
-[Ace API](https://ace.c9.io/api/index.html).
+The `<tosi-code>` element has an `editor` property that gives you its CodeMirror
+[`EditorView`](https://codemirror.net/docs/ref/#view.EditorView), and
+`undo()` / `redo()` / `canUndo()` / `canRedo()` methods for history control.
+
+CodeMirror is loaded lazily on first use — a page with no `<tosi-code>` bundles
+none of it.
 */
 /*{ "parent": "Components" }*/
-import { Component as WebComponent } from 'tosijs';
-import { scriptTag } from './via-tag';
+import { Component as WebComponent, elements } from 'tosijs';
 import { tosiDiff } from './diff';
-const ACE_BASE_URL = 'https://cdnjs.cloudflare.com/ajax/libs/ace/1.23.2/';
-const DEFAULT_THEME = 'ace/theme/tomorrow';
-const getAce = async () => {
-    const { ace } = await scriptTag(`${ACE_BASE_URL}ace.min.js`);
-    return ace;
-};
-const makeCodeEditor = async (codeElement, mode = 'html', options = {}, theme = DEFAULT_THEME) => {
-    const ace = await getAce();
-    ace.config.set('basePath', ACE_BASE_URL);
-    const editor = ace.edit(codeElement, {
-        mode: `ace/mode/${mode}`,
-        tabSize: 2,
-        useSoftTabs: true,
-        useWorker: false,
-        // Wrap wide lines instead of scrolling horizontally; indentedSoftWrap keeps
-        // wrapped continuations aligned under the line's indent.
-        wrap: true,
-        indentedSoftWrap: true,
-        ...options,
-    });
-    editor.setTheme(theme);
-    return { ace, editor };
-};
+const { div } = elements;
 export class CodeEditor extends WebComponent {
     static preferredTagName = 'tosi-code';
     source = '';
+    _handle;
+    _loadPromise;
+    _appliedMode = '';
+    _appliedDisabled;
     get value() {
-        return this.editor === undefined ? this.source : this.editor.getValue();
+        return this._handle ? this._handle.getValue() : this.source;
     }
     set value(text) {
-        if (this.editor === undefined) {
-            this.source = text;
+        if (this._handle) {
+            this._handle.setValue(text);
         }
         else {
-            this.editor.setValue(text);
-            this.editor.clearSelection();
-            this.editor.session.getUndoManager().reset();
+            this.source = text;
         }
     }
     // Baseline for `showDiff()` — the version to diff the current `value` against.
@@ -72,9 +54,9 @@ export class CodeEditor extends WebComponent {
     set original(text) {
         this._original = text;
     }
-    // Diff overlay — deliberately built only on the editor's public surface
-    // (`value` + `original`) and the tosi-diff component, never the underlying
-    // editor's API, so it survives a future Ace → CodeMirror swap untouched.
+    // Diff overlay — built only on the editor's public surface (`value` + `original`)
+    // and the tosi-diff component, never the underlying editor's API, so it is
+    // editor-agnostic (this is why it survived the Ace → CodeMirror swap untouched).
     diffOverlay;
     get showingDiff() {
         return this.diffOverlay !== undefined && !this.diffOverlay.hidden;
@@ -103,20 +85,27 @@ export class CodeEditor extends WebComponent {
     }
     static initAttributes = {
         mode: 'javascript',
-        theme: DEFAULT_THEME,
         disabled: false,
     };
     role = 'code editor';
-    _ace;
-    _editor;
-    _editorPromise;
-    options = {};
-    get ace() {
-        return this._ace;
-    }
+    /** The underlying CodeMirror EditorView (undefined until loaded). */
     get editor() {
-        return this._editor;
+        return this._handle?.view;
+    }
+    // History control — so consumers use these instead of reaching into `editor`.
+    undo() {
+        this._handle?.undo();
+    }
+    redo() {
+        this._handle?.redo();
+    }
+    canUndo() {
+        return this._handle?.canUndo() ?? false;
     }
+    canRedo() {
+        return this._handle?.canRedo() ?? false;
+    }
+    content = () => [div({ part: 'host' })];
     static shadowStyleSpec = {
         ':host': {
             display: 'block',
@@ -124,32 +113,49 @@ export class CodeEditor extends WebComponent {
             width: '100%',
             height: '100%',
         },
+        '[part="host"]': { height: '100%' },
+        '.cm-editor': { height: '100%' },
+        '.cm-scroller': {
+            outline: 'none',
+            fontFamily: "Menlo, Monaco, Consolas, 'Courier New', monospace",
+        },
     };
     onResize() {
-        if (this.editor !== undefined) {
-            this.editor.resize(true);
-        }
+        this._handle?.refresh();
     }
     connectedCallback() {
         super.connectedCallback();
         if (this.source === '') {
             this.value = this.textContent !== null ? this.textContent.trim() : '';
         }
-        if (this._editorPromise === undefined) {
-            this._editorPromise = makeCodeEditor(this, this.mode, this.options, this.theme);
-            this._editorPromise.then(({ ace, editor }) => {
-                this._ace = ace;
-                this._editor = editor;
-                editor.setValue(this.source, 1);
-                editor.clearSelection();
-                editor.session.getUndoManager().reset();
+        if (this._loadPromise === undefined) {
+            // Lazy chunk — CodeMirror only enters the bundle here, on first editor use.
+            this._loadPromise = import('./code-editor-cm').then(({ createCmEditor }) => {
+                const handle = createCmEditor(this.parts.host, {
+                    value: this.source,
+                    mode: this.mode,
+                    readOnly: this.disabled,
+                    root: this.shadowRoot ?? undefined,
+                    onChange: (value) => this.dispatchEvent(new CustomEvent('change', { detail: { value } })),
+                });
+                this._handle = handle;
+                this._appliedMode = this.mode;
+                this._appliedDisabled = this.disabled;
+                return handle;
             });
         }
     }
     render() {
         super.render();
-        if (this._editorPromise !== undefined) {
-            this._editorPromise.then(({ editor }) => editor.setReadOnly(this.disabled));
+        if (this._handle) {
+            if (this.disabled !== this._appliedDisabled) {
+                this._handle.setReadOnly(this.disabled);
+                this._appliedDisabled = this.disabled;
+            }
+            if (this.mode !== this._appliedMode) {
+                this._handle.setMode(this.mode);
+                this._appliedMode = this.mode;
+            }
         }
     }
 }

package/dist/doc-browser.js

@@ -1250,7 +1250,11 @@ export function createDocBrowser(options) {
         if (isTestFrame)
             return; // Don't run background tests in test iframe
         backgroundTestsStarted = true;
-        // Find all docs that have test blocks
+        // Find all docs that have test blocks. (Pages with examples but no explicit
+        // tests are covered cheaply at BUILD time by the transpile check —
+        // src/doc-system/site/check-examples.ts — without loading them in a browser,
+        // so the runner doesn't have to render every heavy page just to notice a
+        // build error.)
         const docsWithTests = docs.filter((doc) => doc.text.includes('```test'));
         pagesWithTests = docsWithTests.length;
         if (pagesWithTests > 0) {

package/dist/doc-system/site/check-examples.d.ts

@@ -0,0 +1,14 @@
+import type { Doc } from './docs';
+export interface ExampleProblem {
+    filename: string;
+    title: string;
+    lang: string;
+    error: string;
+    snippet: string;
+}
+/** Transpile-check every executable block in the corpus. Returns the problems. */
+export declare function checkExamples(docs: Doc[], opts?: {
+    contextKeys?: string[];
+}): Promise<ExampleProblem[]>;
+/** Format problems for a build log. */
+export declare function formatExampleProblems(problems: ExampleProblem[]): string;

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

@@ -0,0 +1,97 @@
+/*
+Build-time transpile check for live examples.
+
+Every executable code block in the corpus (`js` / `tjs` / `ts` / `test`) is put
+through the SAME front half of the runtime pipeline the live-example component
+uses — `rewriteImports` → the tjs-lang transform → `new AsyncFunction(...)` — so a
+block that can't build (a tjs/TS syntax error, an unsupported import, or
+illustrative config mistakenly tagged with an executable language like `ts`
+instead of the display-only `typescript`) fails the build *at authoring time*,
+on every page, instead of silently rendering an error only when someone opens
+that page. `html` / `css` and display-only languages (`typescript`, `json`, …)
+are not executed, so they're skipped.
+
+Build-time only (bun). Never import from browser code.
+*/
+import { marked } from 'marked';
+import { rewriteImports, AsyncFunction, loadTransform } from '../../live-example/code-transform';
+// 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.
+const DEFAULT_CONTEXT_KEYS = ['tosijs', 'tosijs-ui'];
+const EXECUTABLE = new Set(['js', 'tjs', 'ts', 'test']);
+/** The bare dialect from a fence info string ('js#my-id' → 'js'); '' if none. */
+function dialectOf(info) {
+    return (info ?? '').match(/^[a-z]+/)?.[0] ?? '';
+}
+/** Collect every fenced code block in a doc (recursing into lists/quotes). */
+function collectCodeTokens(text) {
+    const out = [];
+    const walk = (tokens) => {
+        for (const t of tokens) {
+            if (t.type === 'code')
+                out.push({ lang: dialectOf(t.lang), text: t.text });
+            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. */
+export async function checkExamples(docs, opts = {}) {
+    const contextKeys = opts.contextKeys ?? DEFAULT_CONTEXT_KEYS;
+    const problems = [];
+    for (const doc of docs) {
+        for (const block of collectCodeTokens(doc.text)) {
+            if (!EXECUTABLE.has(block.lang))
+                continue;
+            // `test` blocks are conventional JS/TS, transpiled as plain js.
+            const dialect = block.lang === 'test' ? 'js' : block.lang;
+            try {
+                const rewritten = rewriteImports(block.text, contextKeys);
+                let js;
+                if (dialect === 'ts') {
+                    // Use bun's own transpiler — network-free (the runtime `ts` path
+                    // fetches the TypeScript compiler from a CDN, which can't run here).
+                    // We only need to validate that the source builds, not reproduce tjs
+                    // lowering exactly.
+                    js = new Bun.Transpiler({ loader: 'ts' }).transformSync(rewritten);
+                }
+                else if (dialect === 'tjs') {
+                    const transform = await loadTransform('tjs');
+                    js = (await transform(rewritten, { transforms: ['typescript'] })).code;
+                }
+                else {
+                    js = rewritten; // `js` / `test` are already JS
+                }
+                // Syntax-validate the way the component does before running it.
+                // eslint-disable-next-line no-new
+                new AsyncFunction(js);
+            }
+            catch (err) {
+                problems.push({
+                    filename: doc.filename,
+                    title: doc.title,
+                    lang: block.lang,
+                    error: err.message || String(err),
+                    snippet: block.text.split('\n').slice(0, 3).join('\n'),
+                });
+            }
+        }
+    }
+    return problems;
+}
+/** Format problems for a build log. */
+export function formatExampleProblems(problems) {
+    return problems
+        .map((p) => `  ✗ ${p.filename} (${p.lang}) — ${p.title}\n` +
+        `    ${p.error}\n` +
+        p.snippet
+            .split('\n')
+            .map((l) => `      | ${l}`)
+            .join('\n'))
+        .join('\n\n');
+}

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

@@ -16,6 +16,7 @@ import { existsSync, mkdirSync } from 'fs';
 import { gzipSync } from 'zlib';
 import { $ } from 'bun';
 import { extractDocs } from './docs';
+import { checkExamples, formatExampleProblems } from './check-examples';
 import { ensureSections } from './sections';
 import { generateLlmsTxt } from './make-llms-txt';
 import { generateSite } from './generate-site';
@@ -68,6 +69,21 @@ export async function buildSite(config) {
         sectionsDir: config.sectionsDir ?? 'src/docs',
         reExtract: extract,
     });
+    // Fail fast on any live example that can't build — a real syntax/import error,
+    // or illustrative code mistakenly tagged executable (`js`/`ts`/…) instead of
+    // display-only `typescript`. Runs on the whole corpus, so it catches breakage
+    // on pages the browser test never navigates to.
+    if (config.checkExamples !== false) {
+        const corpus = JSON.parse(await Bun.file(DOCS_JSON).text());
+        const problems = await checkExamples(corpus);
+        if (problems.length) {
+            throw new Error(`doc-site build: ${problems.length} live example(s) failed to build:\n\n` +
+                formatExampleProblems(problems) +
+                `\n\nFix the code, or — if a block is illustrative and not meant to run —` +
+                ` tag it with a display-only language like \`typescript\` instead of` +
+                ` \`js\`/\`ts\`. (Disable with checkExamples: false.)`);
+        }
+    }
     // Copy static-asset dirs into the web root.
     const staticDirs = config.staticDirs ?? (existsSync('demo/static') ? ['demo/static'] : ['static']);
     for (const dir of staticDirs) {

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

@@ -143,6 +143,15 @@ export interface SiteConfig {
      * `sort: 'filename'` gives a folder of chapters natural order with no metadata.
      */
     book?: BookManifest;
+    /**
+     * Fail the build when a live example can't transpile — a real syntax/import
+     * error, or illustrative code mistakenly tagged with an executable language
+     * (`js`/`ts`/`tjs`/`test`) instead of the display-only `typescript`. Catches it
+     * at build time, on every page, instead of only when someone opens that page.
+     * Default true; assumes the default `tosijs` / `tosijs-ui` example context —
+     * set false if your examples import from a custom `context` the check can't see.
+     */
+    checkExamples?: boolean;
     /** served web-root output dir, default 'docs' */
     outputDir?: string;
     /** dev-server port, default 8787 */