tosijs-ui 1.6.19 → 1.6.21

package/CHANGELOG.md

@@ -1,5 +1,23 @@
 # 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.

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

@@ -0,0 +1,48 @@
+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;
+/** Runtime-introspection hooks for tjs autocomplete (all optional). */
+export interface TjsAutocompleteConfig {
+    getMetadata?: () => Record<string, unknown> | undefined;
+    getImports?: () => Record<string, Record<string, unknown>> | undefined;
+    getLiveBindings?: () => Record<string, unknown> | undefined;
+    getMembers?: (path: string) => Promise<unknown[] | undefined>;
+}
+/**
+ * Lazy-load tjs-lang's CodeMirror language + completion bundle. Returns a single
+ * CodeMirror `Extension` (tjs language, forbidden-keyword highlighting, theme, and
+ * `tjsCompletionSource`-driven autocomplete) suitable for `setLanguageExtension()`,
+ * or `null` when tjs-lang (an optional peer) isn't installed or its editor build
+ * lacks `tjsEditorExtension`. The dynamic import keeps it out of the bundle until a
+ * tjs editor actually mounts.
+ */
+export declare function loadTjsExtension(autocomplete?: TjsAutocompleteConfig): Promise<Extension | null>;
+export interface CmHandle {
+    view: EditorView;
+    getValue(): string;
+    setValue(text: string): void;
+    setMode(mode: string): void;
+    /** Swap the language compartment wholesale (e.g. an async-loaded tjs bundle). */
+    setLanguageExtension(ext: Extension): 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,219 @@
+/*
+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';
+import { oneDarkHighlightStyle } from '@codemirror/theme-one-dark';
+// The doc-system flips dark mode with a `darkmode` class on <body> (which inverts
+// the luminance of --code-bg / --text-color, so the editor SURFACE adapts for
+// free). Only CM's syntax-token colors need swapping: the light defaultHighlightStyle
+// washes out on a dark surface, so use oneDark's brighter palette in dark mode.
+const isDarkMode = () => typeof document !== 'undefined' &&
+    !!document.body &&
+    document.body.classList.contains('darkmode');
+const highlightFor = (dark) => dark
+    ? syntaxHighlighting(oneDarkHighlightStyle)
+    : syntaxHighlighting(defaultHighlightStyle, { fallback: true });
+const isTjsMode = (mode) => mode === 'tjs' || mode === 'ajs';
+/** 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 as TypeScript here (the sync default). First-class tjs — the
+        // tjs-lang language + autocomplete — is layered on asynchronously via
+        // `loadTjsExtension()` + `setLanguageExtension()`, since it lazy-loads the
+        // (optional) tjs-lang editor build; this keeps `mode="tjs"` readable meanwhile.
+        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();
+    }
+}
+// The language compartment carries the language AND its completion source, so
+// exactly ONE `autocompletion()` is ever active: standard modes use CM's built-in
+// (language-provided) completions here, while the tjs bundle brings its own
+// `autocompletion({ override: [tjsCompletionSource] })`. (This is why the base
+// extension set below does NOT include `autocompletion()`.)
+function standardLanguageBundle(mode) {
+    return [languageForMode(mode), autocompletion()];
+}
+/**
+ * Lazy-load tjs-lang's CodeMirror language + completion bundle. Returns a single
+ * CodeMirror `Extension` (tjs language, forbidden-keyword highlighting, theme, and
+ * `tjsCompletionSource`-driven autocomplete) suitable for `setLanguageExtension()`,
+ * or `null` when tjs-lang (an optional peer) isn't installed or its editor build
+ * lacks `tjsEditorExtension`. The dynamic import keeps it out of the bundle until a
+ * tjs editor actually mounts.
+ */
+export async function loadTjsExtension(autocomplete = {}) {
+    try {
+        const mod = (await import('tjs-lang/editors/codemirror'));
+        if (typeof mod.tjsEditorExtension === 'function') {
+            return mod.tjsEditorExtension({ typescript: true, autocomplete });
+        }
+    }
+    catch {
+        // tjs-lang absent or editor build unavailable — caller keeps TS highlighting.
+    }
+    return null;
+}
+// A minimal theme so the editor has a real surface instead of showing whatever is
+// behind it. It's applied as a CodeMirror theme (not shadow-DOM CSS) so it beats
+// CM's injected base styles. Colors come from the doc-system theme vars
+// (`--code-bg` / `--text-color`, which pierce the shadow root and adapt to dark
+// mode) with sensible standalone fallbacks.
+const editorTheme = EditorView.theme({
+    '&': {
+        height: '100%',
+        backgroundColor: 'var(--code-bg, var(--input-bg, #fdfdfd))',
+        color: 'var(--text-color, #222)',
+    },
+    '.cm-scroller': {
+        fontFamily: "Menlo, Monaco, Consolas, 'Courier New', monospace",
+    },
+    '.cm-gutters': {
+        backgroundColor: 'var(--code-bg, var(--input-bg, #fdfdfd))',
+        color: 'var(--text-color, #888)',
+        border: 'none',
+    },
+    '.cm-activeLine': { backgroundColor: 'transparent' },
+    '.cm-activeLineGutter': { backgroundColor: 'transparent' },
+});
+// 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 [
+        editorTheme,
+        lineNumbers(),
+        highlightActiveLineGutter(),
+        highlightSpecialChars(),
+        history(),
+        foldGutter(),
+        drawSelection(),
+        dropCursor(),
+        EditorState.allowMultipleSelections.of(true),
+        indentOnInput(),
+        indentUnit.of('  '),
+        EditorState.tabSize.of(2),
+        // syntax highlighting is applied per-instance via a compartment (dark-mode aware)
+        bracketMatching(),
+        closeBrackets(),
+        // NB: autocompletion() lives in the language compartment (see
+        // standardLanguageBundle) so tjs's own completion source never doubles up.
+        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 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)
+                        opts.onChange(u.state.doc.toString());
+                }),
+            ],
+        }),
+    });
+    // Re-apply the right highlight palette when the doc-system toggles dark mode
+    // (it flips the `darkmode` class on <body>).
+    let dark = isDarkMode();
+    const darkObserver = typeof MutationObserver !== 'undefined' && typeof document !== 'undefined'
+        ? new MutationObserver(() => {
+            const nowDark = isDarkMode();
+            if (nowDark !== dark) {
+                dark = nowDark;
+                view.dispatch({ effects: highlight.reconfigure(highlightFor(dark)) });
+            }
+        })
+        : null;
+    darkObserver?.observe(document.body, { attributes: true, attributeFilter: ['class'] });
+    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(standardLanguageBundle(mode)) });
+        },
+        setLanguageExtension(ext) {
+            view.dispatch({ effects: language.reconfigure(ext) });
+        },
+        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: () => {
+            darkObserver?.disconnect();
+            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,27 @@ 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;
+    private isTjsMode;
+    /**
+     * When in tjs mode, lazily upgrade the editor to tjs-lang's CodeMirror language +
+     * autocomplete. No-op (keeps TS highlighting) if not tjs, if tjs-lang isn't
+     * installed, or if the mode/handle changed before the async load resolved.
+     */
+    private applyTjsExtension;
     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,71 @@ 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;
+                this.applyTjsExtension();
+                return handle;
             });
         }
     }
+    isTjsMode() {
+        return this.mode === 'tjs' || this.mode === 'ajs';
+    }
+    /**
+     * When in tjs mode, lazily upgrade the editor to tjs-lang's CodeMirror language +
+     * autocomplete. No-op (keeps TS highlighting) if not tjs, if tjs-lang isn't
+     * installed, or if the mode/handle changed before the async load resolved.
+     */
+    applyTjsExtension() {
+        const handle = this._handle;
+        if (!handle || !this.isTjsMode())
+            return;
+        import('./code-editor-cm')
+            .then(({ loadTjsExtension }) => loadTjsExtension())
+            .then((ext) => {
+            if (ext && this._handle === handle && this.isTjsMode()) {
+                handle.setLanguageExtension(ext);
+            }
+        });
+    }
     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;
+                this.applyTjsExtension();
+            }
         }
     }
 }

package/dist/doc-browser.js

@@ -472,6 +472,11 @@ export function createDocBrowser(options) {
             }
         });
     }
+    // This instance's own sidenav. Captured from its own change event (below), so the
+    // header nav toggle drives THIS doc-browser — not `document.querySelector('tosi-
+    // sidenav')`, which returns the FIRST sidenav in the document (an OUTER instance
+    // when this one is an embedded, memory-routed browser).
+    let sidenav = null;
     const headerContent = [
         button({
             class: 'iconic',
@@ -489,8 +494,8 @@ export function createDocBrowser(options) {
                 },
             },
             onClick() {
-                const nav = document.querySelector(TosiSidenav.tagName);
-                nav.contentVisible = !nav.contentVisible;
+                if (sidenav)
+                    sidenav.contentVisible = !sidenav.contentVisible;
             },
         }, icons.menu()),
         span({ style: { flex: '0 0 10px' } }),
@@ -1027,9 +1032,12 @@ export function createDocBrowser(options) {
             flex: '1 1 auto',
             overflow: 'hidden',
         },
-        onChange() {
-            const nav = document.querySelector(TosiSidenav.tagName);
-            app.compact = nav.compact;
+        onChange(event) {
+            // Scope to the sidenav that fired — and capture it so the header toggle
+            // targets THIS instance, not the first sidenav in the document.
+            sidenav = event.target.closest(TosiSidenav.tagName);
+            if (sidenav)
+                app.compact = sidenav.compact;
         },
     }, searchField, navContent, div({
         style: {

package/dist/doc-system/site/dev-server.js

@@ -48,10 +48,10 @@ async function ensureHaltijaChannel(port) {
         // HTTPS dev page has no mixed-content), while the `hj` CLI drives over its
         // default HTTP 8700 — one server, both transports, shared state. HTTPS cert
         // is mkcert-trusted. Output quiet so it doesn't drown the dev log.
-        // Track the `@beta` tag: in-browser (widget-mode) WebRTC screen capture —
-        // which makes the Electron app CI-only — landed in the beta channel, ahead
-        // of the `latest` dist-tag.
-        spawn(['bunx', 'haltija@beta', '--server', '--both'], {
+        // `@latest` (1.3.2+): the widget-mode WebRTC screen capture (which makes the
+        // Electron app CI-only) is on the stable channel now, along with the fix for
+        // an accidental Electron launch. (Was pinned to `@beta` before 1.3.2.)
+        spawn(['bunx', 'haltija@latest', '--server', '--both'], {
             stdout: 'ignore',
             stderr: 'ignore',
         });

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

@@ -1,5 +1,5 @@
 export { defineSiteConfig } from './site-config';
-export type { SiteConfig, SiteHost } from './site-config';
+export type { SiteConfig, SiteHost, LibraryBuildContext } from './site-config';
 export { buildSite } from './orchestrator';
 export { devServer } from './dev-server';
 export { extractDocs, saveDocsJSON } from './docs';

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

@@ -102,6 +102,21 @@ export function generateLlmsTxt(outputPath, meta = {}, corpus) {
         console.warn('llms.txt: no readable package.json — using config values only');
     }
     const entries = corpus ? entriesFromCorpus(corpus, meta) : entriesFromSrcScan();
+    // Only orient agents about the live-example execution model when the corpus
+    // actually has live examples (a book / pure-docs site has none).
+    const exampleFence = /```(js|tjs|ts|html|css)\b/;
+    const hasLiveExamples = !!corpus && corpus.some((d) => exampleFence.test(d.text ?? ''));
+    const liveExampleNote = hasLiveExamples
+        ? [
+            'Live examples run inline on the shared page by default (not sandboxed):',
+            'each has its own `preview` element, but they share one tosijs module, so',
+            '`tosi()` state singletons are shared across every example on a page. This is',
+            'deliberate (it shows tosi isolation and lets you drive demos via the global',
+            'singleton). Namespace example state with unique top-level keys so examples',
+            "don't clobber each other; the `iframe` attribute isolates DOM/CSS, not state.",
+            '',
+        ]
+        : [];
     const name = meta.name ?? pkg.name ?? '';
     const description = meta.description ?? pkg.description ?? '';
     const links = [];
@@ -125,6 +140,7 @@ export function generateLlmsTxt(outputPath, meta = {}, corpus) {
         '',
         'Full documentation, with live code examples, is at the links below.',
         '',
+        ...liveExampleNote,
         '## Pages',
         '',
     ];