tosijs-ui 1.6.20 → 1.6.21

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

@@ -2,11 +2,29 @@ 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;

package/dist/code-editor-cm.js

@@ -21,6 +21,18 @@ 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) {
@@ -29,8 +41,10 @@ export function languageForMode(mode) {
             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.
+        // 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 });
@@ -45,10 +59,61 @@ export function languageForMode(mode) {
             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(),
@@ -60,10 +125,11 @@ function baseExtensions() {
         indentOnInput(),
         indentUnit.of('  '),
         EditorState.tabSize.of(2),
-        syntaxHighlighting(defaultHighlightStyle, { fallback: true }),
+        // syntax highlighting is applied per-instance via a compartment (dark-mode aware)
         bracketMatching(),
         closeBrackets(),
-        autocompletion(),
+        // NB: autocompletion() lives in the language compartment (see
+        // standardLanguageBundle) so tjs's own completion source never doubles up.
         rectangularSelection(),
         crosshairCursor(),
         highlightActiveLine(),
@@ -85,7 +151,8 @@ function baseExtensions() {
 export function createCmEditor(parent, opts = {}) {
     const language = new Compartment();
     const readonly = new Compartment();
-    const langExt = opts.languageExtension ?? languageForMode(opts.mode ?? 'javascript');
+    const highlight = new Compartment();
+    const langExt = opts.languageExtension ?? standardLanguageBundle(opts.mode ?? 'javascript');
     const view = new EditorView({
         parent,
         root: opts.root,
@@ -93,6 +160,7 @@ export function createCmEditor(parent, opts = {}) {
             doc: opts.value ?? '',
             extensions: [
                 baseExtensions(),
+                highlight.of(highlightFor(isDarkMode())),
                 language.of(langExt),
                 readonly.of(EditorState.readOnly.of(!!opts.readOnly)),
                 EditorView.updateListener.of((u) => {
@@ -102,6 +170,19 @@ export function createCmEditor(parent, opts = {}) {
             ],
         }),
     });
+    // 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(),
@@ -113,7 +194,10 @@ export function createCmEditor(parent, opts = {}) {
             });
         },
         setMode(mode) {
-            view.dispatch({ effects: language.reconfigure(languageForMode(mode)) });
+            view.dispatch({ effects: language.reconfigure(standardLanguageBundle(mode)) });
+        },
+        setLanguageExtension(ext) {
+            view.dispatch({ effects: language.reconfigure(ext) });
         },
         setReadOnly(ro) {
             view.dispatch({
@@ -126,7 +210,10 @@ export function createCmEditor(parent, opts = {}) {
         canRedo: () => redoDepth(view.state) > 0,
         focus: () => view.focus(),
         refresh: () => view.requestMeasure(),
-        destroy: () => view.destroy(),
+        destroy: () => {
+            darkObserver?.disconnect();
+            view.destroy();
+        },
     };
     return handle;
 }

package/dist/code-editor.d.ts

@@ -50,6 +50,13 @@ export declare class CodeEditor extends WebComponent<CodeEditorParts> {
     };
     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>;

package/dist/code-editor.js

@@ -141,10 +141,31 @@ export class CodeEditor extends WebComponent {
                 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._handle) {
@@ -155,6 +176,7 @@ export class CodeEditor extends WebComponent {
             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',
         '',
     ];

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

@@ -25,6 +25,18 @@ import { buildEpub } from './epub';
 // Module specifiers contain regex metacharacters (`/`, `.`, `@`, …), so escape
 // before interpolating into the require-shim detector below.
 const escapeRegExp = (s) => s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+// Externalize the tjs CodeMirror editor extension ONLY when tjs-lang isn't
+// installed — otherwise it's bundled in so it shares the editor's CodeMirror
+// instance (see the `external` comment in buildSite). Returns [] when present.
+function tjsEditorExternal(root) {
+    try {
+        Bun.resolveSync('tjs-lang/editors/codemirror', root);
+        return [];
+    }
+    catch {
+        return ['tjs-lang/editors/codemirror'];
+    }
+}
 export async function buildSite(config) {
     const PROJECT_ROOT = './';
     const PUBLIC = path.resolve(PROJECT_ROOT, config.outputDir ?? 'docs');
@@ -97,7 +109,17 @@ export async function buildSite(config) {
     console.time('build');
     // Optionally also build the library (ESM + type declarations) — for repos
     // whose single build publishes both an npm package and its doc site.
-    if (config.libraryTsconfig) {
+    if (config.libraryBuild) {
+        // Full override — the consumer owns emitting dist/*.js + *.d.ts for ALL
+        // sources (e.g. tsc for `.ts` + `tjs convert`/`generateDTS` for native `.tjs`
+        // that tsc can't compile). See BUILD-TJS-HOOK.md.
+        await config.libraryBuild({
+            dist: DIST,
+            root: path.resolve(PROJECT_ROOT),
+            tsconfig: config.libraryTsconfig,
+        });
+    }
+    else if (config.libraryTsconfig) {
         // Consumer-controlled library build (handles root noEmit, removeComments,
         // outDir, etc.).
         try {
@@ -127,12 +149,20 @@ export async function buildSite(config) {
             format: 'iife',
             minify: true,
             naming: scriptName,
-            // tjs-lang transpiles live examples; it's dynamically import()'d at
-            // runtime (falling back to CDN), so keep it out of the bundle.
+            // tjs-lang's TRANSPILER (browser bundles) is dynamically import()'d at
+            // runtime (same-origin `/tjs/` copy, else CDN), so keep it out of the bundle.
+            //
+            // `tjs-lang/editors/codemirror` (the CodeMirror language + autocomplete) is
+            // different: it MUST share the editor's CodeMirror instance, so it has to be
+            // bundled IN — a separately loaded copy carries its own `@codemirror/state`
+            // and silently no-ops. So we do NOT externalize it *when tjs-lang is
+            // installed*. But tjs-lang is an OPTIONAL peer; if it's absent, bundling would
+            // fail to resolve, so we externalize it in that case (the runtime import then
+            // no-ops to plain TS highlighting — graceful degradation).
             external: [
-                'tjs-lang',
                 'tjs-lang/browser',
                 'tjs-lang/browser/from-ts',
+                ...tjsEditorExternal(PROJECT_ROOT),
                 ...(config.bundleExternals ?? []),
             ],
         });
@@ -258,7 +288,13 @@ export async function buildSite(config) {
     const genCss = existsSync(genCssTs)
         ? genCssTs
         : `${import.meta.dir}/generate-css.js`;
-    await $ `bun ${genCss} ${PUBLIC}/doc-system.css ${JSON.stringify(config.theme || {})}`.text();
+    // generate-css imports the consumer's library to burn the theme; when that graph
+    // reaches non-`.ts` sources (e.g. `.tjs`), `--preload` a module that registers the
+    // Bun loader plugin so those modules evaluate. (See BUILD-TJS-HOOK.md.)
+    const themeArg = JSON.stringify(config.theme || {});
+    await (config.generateCssPreload
+        ? $ `bun --preload ${config.generateCssPreload} ${genCss} ${PUBLIC}/doc-system.css ${themeArg}`
+        : $ `bun ${genCss} ${PUBLIC}/doc-system.css ${themeArg}`).text();
     console.log(`generated ${pageCount} static pages`);
     // ── host preset files ──
     // Idempotent, and an explicit static file (copied from staticDirs) always wins.

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

@@ -3,6 +3,15 @@ import type { DocSystemTheme } from '../doc-system-styles';
 import type { Doc } from './docs';
 import type { BookManifest } from '../book-manifest';
 export type SiteHost = 'github-pages' | 'firebase' | 'static';
+/** Resolved paths handed to a `libraryBuild` override (see SiteConfig). */
+export interface LibraryBuildContext {
+    /** absolute path to the `dist` output dir the artifacts must land in */
+    dist: string;
+    /** project root the build runs from */
+    root: string;
+    /** the configured `libraryTsconfig`, if any (so the override can still run tsc) */
+    tsconfig?: string;
+}
 export interface SiteConfig {
     /** project / brand name — header, <title> suffix, og:site_name */
     name: string;
@@ -103,6 +112,25 @@ export interface SiteConfig {
      * yourself (e.g. keep doc comments in the published JS for AI readers).
      */
     libraryTsconfig?: string;
+    /**
+     * Fully override the library build (the `tsc` step that `libraryTsconfig` /
+     * `emitLibrary` run). Receives the resolved paths and is responsible for emitting
+     * `dist/*.js` + `*.d.ts` for ALL sources. Use this when some sources aren't `.ts`
+     * — e.g. native tjs-lang `.tjs` modules, which `tsc` can't compile: run `tsc` for
+     * the `.ts` graph and `tjs convert` + `generateDTS` for the `.tjs` files, into the
+     * same `dist`. Takes precedence over `libraryTsconfig` and `emitLibrary`. Pairs
+     * with `generateCssPreload` (below) for the CSS-extraction eval. See
+     * BUILD-TJS-HOOK.md.
+     */
+    libraryBuild?: (ctx: LibraryBuildContext) => void | Promise<void>;
+    /**
+     * A module to `--preload` into the CSS-extraction subprocess (`generate-css`),
+     * which imports your library to burn the theme stylesheet. Needed when that import
+     * graph reaches non-`.ts` sources (e.g. `.tjs`) that require a Bun loader plugin
+     * to evaluate — point this at a module that registers it (via `Bun.plugin({...})`
+     * at import time). Without it the subprocess throws `Cannot find module './x.tjs'`.
+     */
+    generateCssPreload?: string;
     /**
      * Emit llms.txt agent-discoverability index. Default true (uses `name` /
      * `description` / `baseUrl` / `projectLinks`). Set false to skip, or pass a