tosijs-ui 1.7.0-beta.5 → 1.7.0

package/CHANGELOG.md

@@ -1,5 +1,83 @@
 # Changelog
 
+## 1.7.0
+
+> ### ⚠️ BREAKING CHANGE — `<tosi-code>` moved from ACE to CodeMirror 6
+>
+> This is a **breaking change shipping under a minor version**, deliberately. `<tosi-code>`
+> (and the `<tosi-code>`-backed code panels in live examples / the doc browser) is now a
+> CodeMirror 6 wrapper instead of ACE. The public contract that **survives** is unchanged:
+> `value`, `mode`, the `change` event, `disabled`, and `undo`/`redo`. What is **removed**:
+> the ACE-era **`theme`** and **`options`** props — there is no compatibility shim for them
+> (CodeMirror's theming model is different in kind, so a shim would silently no-op). If you set
+> either, migrate: dark mode is now automatic (driven by `body.darkmode`), and editor styling
+> comes from the `--code-bg` / `--text-color` CSS variables. The `editor` property now exposes
+> a CodeMirror `EditorView` rather than an ACE editor.
+>
+> **Why a minor, not 2.0.0:** the `2.0` name is reserved for the tjs-native tosijs port that
+> follows tosijs 2.0; spending it on an editor swap now would missignal that larger change.
+> The deviation from strict semver is intentional and called out here + in the README. **To
+> defer the change, pin `tosijs-ui@1.6`.** Everything else in 1.7.0 is additive.
+
+The headline: the editor became first-class for **tjs** and **WebAssembly**, and doc pages got
+dramatically lighter — a reader loads a page with **neither the tjs transpiler nor CodeMirror on
+first paint**, both arriving only when a code panel is opened to edit.
+
+### CodeMirror 6 editor (replaces ACE)
+
+`<tosi-code>` is a CodeMirror 6 wrapper. The heavy CM code (`code-editor-cm.ts`) is a **lazy
+chunk** loaded on first edit — for ESM/bundler consumers a page with no editor bundles none of
+it. (The IIFE build cannot code-split, so the CDN `<script>` path still inlines it.) Modes:
+`javascript`, `typescript`, `tjs`, `ajs`, `css`, `html`, `markdown`. New: `undo()`/`redo()`/
+`canUndo()`/`canRedo()`, `showDiff(on)` (diffs against a captured baseline via `tosi-diff`), and
+automatic dark mode via a `highlight` compartment + a `body.darkmode` observer.
+
+### First-class tjs + inline WebAssembly in live examples
+
+`tjs`/`ajs` example blocks get tjs-lang's CodeMirror language + **runtime-value autocomplete**
+(completion resolves the live values of an example's locals). Inline `wasm{}` examples run — the
+WASM kernel actually compiles, guarded in CI so a silent fall-back to JS is caught. tjs-lang
+bumped **0.9.0 → 0.12.0** across the release (memory-storm fix in 0.10.1; import-resolver in
+0.11.0; VM security-review fixes in 0.12.0).
+
+### Self-contained, transpiler-free example pages
+
+Each `tjs` example is transpiled **at build time** and its JS baked into the page as a hidden,
+non-executing `<script type="application/tosi-transpiled">`; the example runs from that bake, so
+no transpiler loads for a reader. The bakes ship per-doc in `docs.json` too, so client-side
+navigation gets them at zero extra first-paint cost. Editing an example drops the bake and loads
+the real transpiler + editor on demand; saving keeps the transpiled JS.
+
+### Live examples can import real npm packages (experimental)
+
+With `importResolver` enabled, a live example can `import` any npm package — resolved through a
+same-origin service worker (tjs-lang's import-resolver). Three execution modes are flaggable on
+the fence: `inline` (default), `iframe` (DOM/CSS isolation), `ide` (recognized; iframe path for
+now). Fence grammar is order-free: `` ```ts:ide#demo `` and `` ```ts#demo:ide `` both parse.
+
+### Doc-system & build
+
+Pre-rendered, hydrating doc pages (the chrome renders server-side and hydrates in place — no
+opacity gate on first paint). The hydration bundle ESM-splits CodeMirror off the critical path.
+Machine-safety guards for the long-lived dev server: an RSS ceiling, an 8-hour idle exit, and a
+preflight that refuses to build on an already-dying machine (Bun's `Bun.build()` native leak,
+oven-sh/bun#34053, is worked around by shelling out to the `bun build` CLI). A live
+`<tosi-css-var-editor>` on component pages. Nested `<tosi-doc-system>` instances no longer share
+state (each gets its own observable registry key).
+
+### Peers
+
+`tosijs` peer floor `^1.7.0` — the 1.7 line is a co-released, lockstep stack, and this is the
+version tosijs-ui is built, tested, and (in the iife) bundled against; we don't verify against
+older tosijs, so the declared floor matches what's actually tested. `tjs-lang` `^0.12.0` — a lazy, optional
+peer (a plain component consumer never pulls it in). `@codemirror/*` are the only hard runtime
+dependencies (a deliberate divergence from the zero-runtime-dep rule; they must share one
+`@codemirror/state` instance).
+
+---
+
+_The beta changelogs below are retained for detail; 1.7.0 consolidates betas 1–5 + rc.1. Built on tosijs 1.7.0._
+
 ## 1.7.0-beta.3
 
 **Self-contained examples, and CodeMirror + the tjs transpiler are now edit-time only.** A

package/README.md

@@ -16,6 +16,16 @@
 
 Copyright ©2023-2025 Tonio Loewald
 
+## ⚠️ Breaking change in 1.7.0 — `<tosi-code>` (ACE → CodeMirror 6)
+
+**1.7.0 is a breaking release shipping under a minor version, deliberately.** `<tosi-code>`
+moved from ACE to CodeMirror 6. `value`, `mode`, the `change` event, `disabled`, and
+`undo`/`redo` are unchanged; the ACE-era **`theme`** and **`options`** props are **removed** with
+no shim. Dark mode is now automatic (`body.darkmode`) and styling comes from `--code-bg` /
+`--text-color`. The `2.0` name is reserved for the tjs-native tosijs port, so this ships as
+1.7.0 — **pin `tosijs-ui@1.6` to defer.** Full detail and rationale in
+[CHANGELOG.md](./CHANGELOG.md).
+
 ## the tosijs-ui library
 
 A set of [web-components](https://developer.mozilla.org/en-US/docs/Web/API/Web_components)

package/dist/code-editor.d.ts

@@ -48,9 +48,10 @@ export declare class CodeEditor extends WebComponent<CodeEditorParts> {
      * JS and CDN consumers — the audience this component's own docs court — would get the
      * bare TypeError with no explanation at all.
      *
-     * So: say it once, on first access. One line in the console beats a stack trace in a
-     * library the reader has never opened. Use `undo()`/`redo()`/`canUndo()`/`canRedo()`
-     * for history — they are the supported surface and they survived the migration.
+     * So: one neutral note on first access. `editor` is NOT deprecated — it is the
+     * supported CM6 accessor — so this is `console.info` (not `warn`) and leads with that,
+     * to help a 1.6→1.7 migrator without scolding correct CM6 use. Use
+     * `undo()`/`redo()`/`canUndo()`/`canRedo()` for history — they survived the migration.
      */
     get editor(): CmHandle['view'] | undefined;
     /** @deprecated Removed in 1.7 — CodeMirror themes via `--code-bg`/`--text-color`. */

package/dist/code-editor.js

@@ -187,17 +187,17 @@ export class CodeEditor extends WebComponent {
      * JS and CDN consumers — the audience this component's own docs court — would get the
      * bare TypeError with no explanation at all.
      *
-     * So: say it once, on first access. One line in the console beats a stack trace in a
-     * library the reader has never opened. Use `undo()`/`redo()`/`canUndo()`/`canRedo()`
-     * for history — they are the supported surface and they survived the migration.
+     * So: one neutral note on first access. `editor` is NOT deprecated — it is the
+     * supported CM6 accessor — so this is `console.info` (not `warn`) and leads with that,
+     * to help a 1.6→1.7 migrator without scolding correct CM6 use. Use
+     * `undo()`/`redo()`/`canUndo()`/`canRedo()` for history — they survived the migration.
      */
     get editor() {
         if (!warnedEditor) {
             warnedEditor = true;
-            console.warn('<tosi-code>.editor is a CodeMirror EditorView as of 1.7 (it was an ACE editor ' +
-                'in 1.6) — `editor.session`, `editor.getSession()`, `editor.setOption()` and ' +
-                '`editor.session.getUndoManager()` no longer exist. Use undo()/redo()/' +
-                'canUndo()/canRedo() for history; see the CodeMirror 6 docs for the rest.');
+            console.info('<tosi-code>.editor is the CodeMirror 6 EditorView (the supported accessor; it ' +
+                'was an ACE editor in 1.6). ACE-era `editor.session` / `getSession()` / ' +
+                '`setOption()` are gone — use undo()/redo()/canUndo()/canRedo() for history.');
         }
         return this._handle?.view;
     }

package/dist/doc-browser.js

@@ -146,7 +146,7 @@ interface ProjectLinks {
 
 The `tosijs-ui` demo is a complete working example. See:
 
-- `/demo/src/index.ts` - How the doc browser is set up
+- `/tosijs-site.config.ts` - How this repo configures its doc site (`defineSiteConfig` / `tosijs-ui/site`)
 - `/src/doc-system/site/docs.ts` - The extraction tool (`extractDocs`, exported from `tosijs-ui/site`)
 - `/src/doc-browser.ts` - The createDocBrowser implementation
 */
@@ -252,6 +252,9 @@ const testIndicatorStyleSpec = {
         borderRadius: vars.roundedRadius,
     },
 };
+// Monotonic per-page counter so each createDocBrowser() call gets a distinct
+// tosi() registry key (see stateKey below) and two browsers can't share state.
+let docBrowserSeq = 0;
 export function createDocBrowser(options) {
     const { docs, context = {}, projectName = '', projectLinks = {}, navSize = 200, minSize = 600, routing = 'query', initialRoute, onRouteChange, navbarLinks, contentElement, } = options;
     // Memory routing is fully self-contained: it never reads or writes
@@ -320,13 +323,21 @@ export function createDocBrowser(options) {
     };
     const docName = filenameFromLocation() || docs[0]?.filename || 'README.md';
     const currentDoc = docs.find((doc) => doc.filename === docName) || docs[0];
-    const { app } = tosi({
-        app: {
+    // tosi() registers its top-level keys in a GLOBAL observable registry, so two
+    // doc browsers on one page (e.g. a page whose live example embeds a nested
+    // <tosi-doc-system>) would BOTH register `app` and share it — the second wins,
+    // so the outer browser's nav / currentDoc / edit-source silently read the
+    // nested one's doc. Give each instance its own key. (This is the same collision
+    // the live-example docs warn about: never register a generic `app`.)
+    const stateKey = `docBrowser${docBrowserSeq++}`;
+    const state = tosi({
+        [stateKey]: {
             docs,
             currentDoc,
             compact: false,
         },
     });
+    const app = state[stateKey];
     // Assigned by the hierarchical nav builder (path routing); re-applies current
     // highlight, test status, search visibility, and auto-open imperatively.
     // resetOpen=true collapses every section except the current doc's.
@@ -1044,7 +1055,7 @@ export function createDocBrowser(options) {
             },
         }, template(a({
             class: 'doc-link',
-            bindCurrent: 'app.currentDoc.filename',
+            bindCurrent: `${stateKey}.currentDoc.filename`,
             bindDocLink: '^.filename',
             bindTestStatus: '^.testStatus',
             onClick(event) {

package/dist/doc-system/css-var-editor.d.ts

@@ -0,0 +1,18 @@
+import { Component as WebComponent, ElementCreator } from 'tosijs';
+import { TosiForm } from '../form';
+declare class TosiCssVarEditor extends WebComponent {
+    static preferredTagName: string;
+    static initAttributes: {
+        elementSelector: string;
+        targetSelector: string;
+    };
+    content: () => (HTMLHeadingElement | TosiForm)[];
+    private retryTimer?;
+    private retries;
+    loadVars: () => void;
+    update: () => void;
+    connectedCallback(): void;
+    disconnectedCallback(): void;
+}
+export declare const tosiCssVarEditor: ElementCreator<TosiCssVarEditor>;
+export {};

package/dist/doc-system/css-var-editor.js

@@ -0,0 +1,85 @@
+/*
+`<tosi-css-var-editor>` — a doc-system affordance (NOT a general library component).
+Reads the CSS custom properties a component defines in its shadow `<style>` and builds
+a live form to tweak them, applying changes to the matching element(s) on the page. It
+is registered as a side effect of loading the doc-system (see doc-system.ts) so doc pages
+can drop `<tosi-css-var-editor element-selector="tosi-widget">` under an example; it is
+deliberately not exported from `tosijs-ui`.
+*/
+import { Component as WebComponent, elements, Color, } from 'tosijs';
+import { tosiForm, tosiField } from '../form';
+const { h2, code } = elements;
+// A value is a color if it's a hex literal or an rgb()/hsl() (with or without alpha)
+// functional notation — the forms getComputedStyle / getPropertyValue return. The old
+// regex (`[\d()a-fA-F]+`) rejected the commas and spaces in `rgb(255, 0, 0)`, so every
+// functional color fell through to a plain text field.
+const COLOR_RE = /^(#[0-9a-f]{3,8}|(?:rgb|hsl)a?\([^)]*\))$/i;
+class TosiCssVarEditor extends WebComponent {
+    static preferredTagName = 'tosi-css-var-editor';
+    static initAttributes = {
+        elementSelector: '',
+        targetSelector: '',
+    };
+    content = () => [
+        h2({ part: 'title' }, 'CSS variables'),
+        tosiForm({ part: 'variables', changeCallback: this.update }),
+    ];
+    // The example the editor targets can mount a frame or two after this element does;
+    // retry a bounded number of times (≈10s) rather than polling forever, and cancel on
+    // disconnect so a removed editor can't keep firing timers against a dead page.
+    retryTimer;
+    retries = 0;
+    loadVars = () => {
+        const { title, variables } = this.parts;
+        variables.textContent = '';
+        if (!this.elementSelector)
+            return;
+        title.textContent = `CSS variables for ${this.elementSelector}`;
+        const element = document.querySelector(this.elementSelector);
+        if (!element) {
+            if (this.retries++ < 40)
+                this.retryTimer = setTimeout(this.loadVars, 250);
+            return;
+        }
+        const styleNode = element.shadowRoot
+            ? element.shadowRoot.querySelector('style')
+            : document.querySelector(`style#${this.elementSelector}-component`);
+        if (!styleNode || !styleNode.textContent)
+            return;
+        const computedStyle = getComputedStyle(element);
+        const cssVars = [
+            ...new Set(styleNode.textContent.match(/--[\w-]+/g) ?? []),
+        ];
+        for (const cssVar of cssVars) {
+            let value = computedStyle.getPropertyValue(cssVar).trim();
+            const type = COLOR_RE.test(value) ? 'color' : 'string';
+            if (type === 'color')
+                value = Color.fromCss(value).html;
+            variables.append(tosiField(code(cssVar), { key: cssVar, value, type }));
+        }
+    };
+    update = () => {
+        const selector = this.targetSelector || this.elementSelector;
+        if (!selector)
+            return;
+        const targets = [...document.querySelectorAll(selector)];
+        const { value } = this.parts.variables;
+        for (const target of targets) {
+            for (const key of Object.keys(value)) {
+                target.style.setProperty(key, value[key]);
+            }
+        }
+    };
+    connectedCallback() {
+        super.connectedCallback();
+        this.retries = 0;
+        this.loadVars();
+        this.parts.variables.addEventListener('change', this.update);
+    }
+    disconnectedCallback() {
+        super.disconnectedCallback();
+        if (this.retryTimer)
+            clearTimeout(this.retryTimer);
+    }
+}
+export const tosiCssVarEditor = TosiCssVarEditor.elementCreator();

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

@@ -1,4 +1,5 @@
 import { Component, ElementCreator } from 'tosijs';
+import './css-var-editor';
 export declare class TosiDocSystem extends Component {
     static preferredTagName: string;
     static initAttributes: {

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

@@ -64,6 +64,9 @@ import { docSystemStyleSpec } from './doc-system-styles';
 import { icons } from '../icons';
 import { popMenu } from '../menu';
 import { i18n, setLocale, initLocalization } from '../localize';
+// Side-effect: register <tosi-css-var-editor> so doc pages can drop the live CSS-var
+// tweaker under an example. Part of the doc-system, NOT re-exported from tosijs-ui.
+import './css-var-editor';
 const { button, div } = elements;
 const PREFS_KEY = 'tosi-doc-system-prefs';
 export class TosiDocSystem extends Component {
@@ -425,3 +428,20 @@ export class TosiDocSystem extends Component {
     }
 }
 export const tosiDocSystem = TosiDocSystem.elementCreator();
+// Register the import-resolver service worker when the build opted in — the config
+// global is injected into the page head by orchestrator's importResolverHead (gated on
+// SiteConfig.importResolver). Dynamic import keeps tjs-lang/import-resolver out of the
+// bundle unless a site actually enables it, and out of a plain component consumer's
+// graph entirely. Experimental; 1.7.0 ships with the flag off. See import-resolver-plan.md.
+function initImportResolver() {
+    if (typeof document === 'undefined')
+        return;
+    const cfg = globalThis
+        .__TOSI_IMPORT_RESOLVER;
+    if (!cfg)
+        return;
+    void import('tjs-lang/import-resolver')
+        .then(({ registerImportResolver }) => registerImportResolver(cfg))
+        .catch((e) => console.warn('import-resolver: registration failed', e));
+}
+initImportResolver();

package/dist/doc-system/render.js

@@ -15,20 +15,28 @@ const docMarked = new Marked();
 docMarked.use({
     renderer: {
         code(token) {
+            // Fence info grammar: `<lang>` optionally with a `:<mode>` and/or `#<id>` in
+            // EITHER order — `js`, `css#anchor`, `js:iframe`, `ts:ide#demo`, `ts#demo:ide`.
+            // `:mode` (inline | iframe | ide) sets the live example's execution mode; `#id`
+            // gives it a stable anchor. `#id` is `[A-Za-z0-9_-]+` and `:mode` is `[a-z]+`, so
+            // the two can't overlap — parse each independently, order-free. Both are stripped
+            // so the language stays clean (`language-js`) for grouping/highlighting.
             const info = String(token.lang || '');
-            const hash = info.indexOf('#');
-            const id = hash === -1
-                ? ''
-                : (info.slice(hash + 1).match(/^[A-Za-z0-9_-]+/)?.[0] ?? '');
+            const lang = info.match(/^[a-z]+/)?.[0] ?? '';
+            const id = info.match(/#([A-Za-z0-9_-]+)/)?.[1] ?? '';
+            const mode = info.match(/:([a-z]+)/)?.[1] ?? '';
             const bake = currentBakes?.get(token.text);
-            if (!id && !bake)
+            if (!id && !mode && !bake)
                 return false; // default rendering — byte-identical
-            let html = baseRenderer.code({
-                ...token,
-                lang: hash === -1 ? info : info.slice(0, hash),
-            });
-            if (id)
-                html = html.replace(/^<pre>/, `<pre data-example-id="${id}">`);
+            let html = baseRenderer.code({ ...token, lang });
+            const attrs = [
+                id && `data-example-id="${id}"`,
+                mode && `data-example-mode="${mode}"`,
+            ]
+                .filter(Boolean)
+                .join(' ');
+            if (attrs)
+                html = html.replace(/^<pre>/, `<pre ${attrs}>`);
             if (bake) {
                 // `<` → < prevents a `</script>` inside the JS from breaking the tag;
                 // JSON.parse decodes it unchanged at hydration.

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

@@ -32,8 +32,14 @@ if (!docsJson) {
     process.exit(1);
 }
 const contextKeys = process.argv.slice(3);
+// When the site enables the import-resolver, the parent passes its prefix so
+// non-context imports validate as dynamic `<prefix><spec>` imports rather than failing.
+const importPrefix = process.env.TOSI_IMPORT_PREFIX || undefined;
 const corpus = JSON.parse(await Bun.file(docsJson).text());
-const { problems, bakes } = await checkExamples(corpus, contextKeys.length ? { contextKeys } : {});
+const { problems, bakes } = await checkExamples(corpus, {
+    ...(contextKeys.length ? { contextKeys } : {}),
+    ...(importPrefix ? { importPrefix } : {}),
+});
 // stdout is the channel — the parent parses this. Anything else this process prints
 // (warnings from the transform, say) goes to stderr so it can't corrupt the payload.
 // Maps can't JSON-roundtrip, so bakes go over as [filename, [source, {dialect,js}][]][].

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

@@ -25,6 +25,7 @@ export interface ExampleCheck {
  */
 export declare function checkExamples(docs: Doc[], opts?: {
     contextKeys?: string[];
+    importPrefix?: string;
 }): Promise<ExampleCheck>;
 /** Format problems for a build log. */
 export declare function formatExampleProblems(problems: ExampleProblem[]): string;

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

@@ -66,7 +66,7 @@ export async function checkExamples(docs, opts = {}) {
             // `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);
+                const rewritten = rewriteImports(block.text, contextKeys, opts.importPrefix);
                 let js;
                 if (dialect === 'ts') {
                     // Use bun's own transpiler — network-free (the runtime `ts` path

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

@@ -40,7 +40,7 @@ const DEFAULT_IDLE_HOURS = 8;
  *   - `hj` action commands (`navigate`, `click`, …) exit NON-ZERO on failure, so the
  *     test lane below can trust an exit code instead of racing to a timeout.
  */
-const HALTIJA_PKG = process.env.HALTIJA_VERSION ?? 'haltija@^1.4.0';
+const HALTIJA_PKG = process.env.HALTIJA_VERSION ?? 'haltija@^1.5.0';
 /**
  * Resolve the idle-exit timeout to milliseconds (0 = disabled).
  *
@@ -130,6 +130,9 @@ async function killStrayServer(port) {
         catch {
             continue; // already gone
         }
+        // Leave a receipt: reclaiming a port is destructive, so if it ever hits a server
+        // the developer actually wanted, the log says exactly which pid/comm on which port.
+        console.warn(`↻ reclaimed port ${port}: SIGTERM → pid ${pid} (${comm || 'unknown'})`);
         // Give it a moment to close the listener, then insist.
         for (let i = 0; i < 20; i++) {
             await Bun.sleep(50);
@@ -142,6 +145,7 @@ async function killStrayServer(port) {
             if (i === 19) {
                 try {
                     process.kill(pid, 'SIGKILL');
+                    console.warn(`   pid ${pid} ignored SIGTERM — sent SIGKILL`);
                 }
                 catch {
                     // gone between the check and the signal — fine