tosijs-ui 1.7.0-beta.1 → 1.7.0-beta.5

package/CHANGELOG.md

@@ -1,43 +1,154 @@
 # Changelog
 
-## 1.7.0-beta.1
+## 1.7.0-beta.3
+
+**Self-contained examples, and CodeMirror + the tjs transpiler are now edit-time only.** A
+reader loading a doc page — directly or via client-side navigation — runs every example with
+**neither the tjs transpiler nor CodeMirror on first paint**. Both load only when you open a
+code panel to edit.
+
+Still a beta under the `beta` tag (`latest` stays 1.6.x): `npm i tosijs-ui@beta`.
+
+### Examples run without the transpiler
+
+Each `tjs` example is transpiled at build time and its JavaScript is baked into the page as a
+hidden, non-executing `<script type="application/tosi-transpiled">`; the example runs from that
+bake. Plain `js` examples need no transpiler at all (`loadTransform('js')` is now identity). The
+bakes also ship per-doc in `docs.json`, so client-side navigation gets them too — at **zero
+added bytes for prose/book sites** (only docs with code examples carry bakes). Editing an
+example drops the stale bake and transpiles on demand; a saved local edit keeps its own
+transpiled code so it reloads without the transpiler.
+
+### CodeMirror panels build lazily
+
+`<tosi-example>` no longer constructs its `<tosi-code>` panels up front (this delivers the
+beta.2 "Remaining" note above): the panel — and the CodeMirror chunk — is built on first
+`showCode`. A page with examples now ships zero CodeMirror until a reader opens a panel.
+
+### tjs-lang 0.9.1 → 0.10.1
+
+Bumped the transpiler, **skipping 0.10.0** (it triggered a memory storm rooted in a bun bug;
+0.10.1 carries the fix). 0.10.x closed four upstream issues, letting this release **delete ~272
+lines** of hand-rolled scope-scanning and a hand-declared autocomplete-config type in favor of
+tjs-lang's own exports. The inline-WASM guard was updated for 0.10.x's renamed compiled export.
+
+- `tjs-lang` peer: `^0.9.1` → `^0.10.1` (and the `TJS_VERSION` CDN-fallback pin, in lockstep).
+
+## 1.7.0-beta.2
+
+The code editor moved from **ACE to [CodeMirror 6](https://codemirror.net/)**, `tjs`
+became a first-class editing mode with runtime-value autocomplete, the doc-site builder
+gained the hooks that unblock the tosijs 2.0 TJS port — and generated doc pages are now
+**readable before any JavaScript runs**.
 
 **A beta, published under npm's `beta` tag** — `latest` stays on 1.6.x. A prerelease is not
 matched by `^1.6.x` (or by `^1.7.0`), so nobody is auto-upgraded into the editor swap; you get
 this only by asking for it:
 
 ```
-npm i tosijs-ui@beta        # or tosijs-ui@1.7.0-beta.1
+npm i tosijs-ui@beta        # or tosijs-ui@1.7.0-beta.2
 ```
 
-The code editor moved from **ACE to [CodeMirror 6](https://codemirror.net/)**, `tjs`
-became a first-class editing mode with runtime-value autocomplete, and the doc-site
-builder gained the hooks that unblock the tosijs 2.0 TJS port.
-
-**Known cost, deliberate for now.** `dist/iife.js` carries CodeMirror (bun's IIFE format cannot
-code-split), and generated doc pages hide the body until hydration — so on a cheap phone the
-blank-screen window is ~4.5s vs ~3.7s without the editor. The fix is to pre-render the page
-chrome so hydration is additive and the gate can go (then the bundle gates *editing*, not
-*reading*); that's the next doc-system release, not this one. Measurements in `TODO.md`.
+### Doc pages no longer wait for the bundle
+
+Generated pages used to hide the body (`opacity: 0`, with a 4s safety-net timeout) until
+hydration, because hydration injected the whole page chrome and the reflow would have been
+ugly. **That gate is gone.** The chrome is pre-rendered, so the page is styled, readable and
+navigable — real `<a>` links, real headings — before a byte of JS executes, and hydration is
+purely additive: nothing moves.
+
+Measured on the built site, gzipped, CPU-throttled — blank-screen duration:
+
+| device                     | before                           | after      |
+| -------------------------- | -------------------------------- | ---------- |
+| cheap phone / Pi4, slow 4G | 4532ms                           | **1635ms** |
+| cheap phone / Pi4, 3G      | 4837ms — _hit the 4s safety net_ | **1635ms** |
+
+The bundle now gates **editing**, not **reading** — which was the point.
+
+Two regressions against that promise were caught in review and fixed here: the nav was styled
+by two hand-copied rule sets that had drifted (so it reflowed ~4px per row on hydration), and
+the page `<title>` was derived twice (so the home page flipped from its real title to
+`tosijs-ui — tosijs-ui`, [#6](https://github.com/tonioloewald/tosijs-ui/issues/6)). Both are
+now single, shared rules, and `tests/hydration.pw.ts` asserts that a no-JS page and a hydrated
+page agree — geometry, styling and title.
+
+### Doc pages no longer ship CodeMirror to readers who don't open an editor
+
+`dist/iife.js` can't code-split (bun's IIFE format), so `<tosi-code>`'s lazy `import()` is
+flattened in — CodeMirror + lezer + acorn on every page whether or not it has an editor
+(121KB → 388KB gzip). The generated **doc pages now load an ESM `--splitting` hydration bundle**
+(`<script type="module">`) instead: the always-loaded entry is **~123KB gzip** and CodeMirror
+rides a lazy chunk pulled only when an editor mounts. The tjs CM extension stays bundled, and
+splitting preserves the shared single `@codemirror/state`. **`dist/iife.js` is unchanged and
+still shipped for the CDN `<script>` path.** So a **pure-docs / book site with no code
+examples now ships zero CodeMirror** — the case that was hurt worst.
+
+Remaining (tracked in `TODO.md`): a page that DOES have live examples still eager-loads the
+editor chunk, because `<tosi-example>` builds its code panels up front even while hidden. The
+next step defers that construction until the reader opens a panel; the example still runs (the
+preview and inline tests don't need the editors) — only the code view waits. **(Delivered in
+1.7.0-beta.3 — see below.)**
+
+### Dev-server safety (also in 1.6.23)
+
+A leaking dev server took a machine down twice. The guards, all in `tosijs-ui/site`:
+
+- **Machine-health preflight** before every build and dev-server launch: refuses to add load to
+  a machine that is already dying, and names the offending PIDs, sizes, ages and project dirs.
+  `preflight: 'fail' | 'warn' | false` in the site config; `DEV_SKIP_PREFLIGHT=1` to skip. Warns
+  rather than refuses in CI.
+- **`idleTimeoutHours` (default 8)** — ⚠️ **a behavior change**: your dev server now exits after
+  8 idle hours (no request, no rebuild). A forgotten dev server is not inert — it is a days-old
+  process still running the code it loaded at launch. Set `idleTimeoutHours: 0` to disable.
+- **RSS ceiling** (`memoryLimitMb`, default 4096) sampled every 60s, not just after a rebuild.
+- **Rebuild-loop detector** — a build that writes a file it also watches now stops, and names
+  the file, instead of spawning a bundler forever.
+- The example check, the ePub build, and the bundle gzip all moved into **child processes**;
+  `Bun.build()` strands ~30MB of native arena per call ([oven-sh/bun#34053](https://github.com/oven-sh/bun/issues/34053), still open).
+- **`killStrayServer` no longer `kill -9`s every process _connected to_ the dev port** — it used
+  `lsof -ti:PORT`, which matches clients as well as the listener, so it could kill your browser.
+- haltija is spawned as a **pinned range** (`haltija@^1.4.0`, override with `HALTIJA_VERSION`),
+  not a floating `@latest`, and its teardown kills only its own process tree. The 1.4.0 floor
+  is deliberate: it is the first haltija that routes `hj` by working directory, never overwrites
+  a newer machine-wide `hj`, and exits non-zero on a failed command — so a project's dev server
+  drives its own browser and can't silently downgrade another project's CLI.
 
 ### Breaking
 
 `<tosi-code>` (ACE → CodeMirror 6). Each removed member now **warns once and no-ops**
 rather than failing silently, but they are gone:
 
-| removed | replacement |
-| --- | --- |
-| `theme` attribute | style the editor with `--code-bg` / `--text-color` |
-| `options` property (ACE-shaped) | configure via `editor` (a CodeMirror `EditorView`) |
-| `ace` getter | there is no ACE global; use `editor` |
-| `editor.session.getUndoManager()` | `undo()` / `redo()` / `canUndo()` / `canRedo()` |
+| removed                           | replacement                                        |
+| --------------------------------- | -------------------------------------------------- |
+| `theme` attribute                 | style the editor with `--code-bg` / `--text-color` |
+| `options` property (ACE-shaped)   | configure via `editor` (a CodeMirror `EditorView`) |
+| `ace` getter                      | there is no ACE global; use `editor`               |
+| `editor.session.getUndoManager()` | `undo()` / `redo()` / `canUndo()` / `canRedo()`    |
 
 **`editor` changed type in place** — it was an ACE `Editor`, it is now a CodeMirror
-[`EditorView`](https://codemirror.net/docs/ref/#view.EditorView). A grep for the
-removed names will not catch this; any code reaching into `editor` needs revisiting.
+[`EditorView`](https://codemirror.net/docs/ref/#view.EditorView). A grep for the removed
+names will not catch this, and the warn-once shims above **cannot** catch it either: the
+property still exists and still returns an object; it is simply a different object. So
+**`editor` now warns once on first access**, naming what moved — one line in the console
+beats a `TypeError` from inside a library you have never opened. TypeScript users get a
+compile error instead (1.6 typed it `any`; 1.7 types it `EditorView | undefined`).
+
+**`change` now means the _user_ changed it.** The event is new in 1.7, and it fires only
+on user edits — a programmatic `el.value = doc` (loading a document) does not fire it, and
+neither does writing into a `disabled` editor. Without that, every app that populates an
+editor would record a spurious save/dirty-flag on open. Programmatic sets are also not
+undoable: loading a document is not an edit to Ctrl+Z back out of.
 
 Unchanged: `value`, `original` / `showDiff()`, `mode`, `disabled`.
 
+**tosijs floor is now `^1.6.9`.** 1.6.9 fixes the `parts` proxy so a pre-hydration access no
+longer poisons it, and adds public `hydrated` / `whenHydrated` seams
+([tosijs#13](https://github.com/tonioloewald/tosijs/issues/13)). Two internal hand-rolled
+hydration guards (`<tosi-code>`, `<tosi-example>`) were deleted in favor of the official
+`this.hydrated` — so any component that reaches into `parts` from a getter is safe against the
+old "read it once and it's bricked forever" trap.
+
 **Semver stance (deliberate, not an oversight).** This library breaks in minors before 2.0 —
 **`2.0` is reserved for the tjs-native rewrite**, not for this. So `^1.6.x` resolves `1.7.0` and
 existing consumers pick this up on their next install.
@@ -46,6 +157,21 @@ existing consumers pick this up on their next install.
 is untouched, so a consumer of (say) `<tosi-rating>` can take 1.7 without changes — but note it
 now installs 12 `@codemirror/*` runtime dependencies where the library previously had none.
 
+## 1.6.23
+
+**Dev-server safety.** Everything under "Dev-server safety" above, backported — this is the
+release every `tosijs-ui/site` consumer wants, and it needs no code changes.
+
+The one to know about: **`killStrayServer` was `kill -9`ing every process _connected to_ the
+dev port, not just the listener.** `lsof -i:PORT` matches sockets whose local _or remote_ port
+is `PORT`, so `bun start` could SIGKILL the browser reading your page, Playwright's browsers,
+or an editor's language server. Now it signals only the listening process, only if it is a JS
+runtime, SIGTERM first.
+
+⚠️ **Behavior change:** the dev server now exits after **8 idle hours** (`idleTimeoutHours: 0`
+to disable), and refuses to start on a machine that is already out of memory
+(`DEV_SKIP_PREFLIGHT=1`, or `preflight: 'warn' | false`).
+
 The trap to know about: **`editor` changed type in place** and no shim can catch it. The removed
 `theme` / `options` / `ace` members warn once and no-op, but `el.editor` still exists — it is
 simply a CodeMirror `EditorView` now, so `el.editor.session.*` is a runtime `TypeError`. A grep
@@ -56,7 +182,7 @@ for the removed names will not find it.
 - `<tosi-code>` gained a `change` event (`event.detail.value`), `undo()` / `redo()` /
   `canUndo()` / `canRedo()`, and `tjs` / `ajs` modes.
 - **Runtime-value autocomplete** in `tjs` mode: set `tjsAutocomplete` and completion
-  suggests the *real members of live values* — including tosijs proxy members that no
+  suggests the _real members of live values_ — including tosijs proxy members that no
   static analysis can see. Live examples wire their own executed scope into it, so
   `const { app } = tosi(…)` gives real `app.` / `app.items.` completions.
 - Inline **WebAssembly** live examples (tjs `wasm {}` blocks).
@@ -120,7 +246,7 @@ for the removed names will not find it.
 
 ### Fixed
 
-- Doc-system nav-toggle in `routing: 'memory'` mode drove the *outer* doc-browser
+- Doc-system nav-toggle in `routing: 'memory'` mode drove the _outer_ doc-browser
   instance instead of its own (now scoped per-instance).
 
 ### Added
@@ -159,7 +285,7 @@ Doc-system tooling; no component API changes.
 - **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
+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
@@ -173,7 +299,7 @@ Doc-system tooling; no component API changes.
 ### 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
+  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.
 
@@ -374,6 +500,7 @@ below.
 
 - **Subpath exports**, so an app can import only what it needs without the barrel
   dragging in dev tools:
+
   - curated: `tosijs-ui/icons`, `tosijs-ui/code-editor`, `tosijs-ui/live-example`,
     `tosijs-ui/doc-browser`, `tosijs-ui/diff`, `tosijs-ui/theme`
   - per-component wildcard: `import { tosiRating } from 'tosijs-ui/rating'`

package/README.md

@@ -1,6 +1,6 @@
 # tosijs-ui
 
-<!--{ "pin": "top", "headTitle": "tosijs-ui — robust, dependency-free web components", "description": "A small, fast library of standards-based web components (data tables, dialogs, forms, rich text, carousels, and more) built on tosijs — smaller and faster than a React app, with no virtual DOM.", "keywords": "web components, custom elements, tosijs, data table, dialog, form, rich text, no virtual dom" }-->
+<!--{ "pin": "top", "headTitle": "tosijs-ui — robust, standards-based web components", "description": "A small, fast library of standards-based web components (data tables, dialogs, forms, rich text, carousels, and more) built on tosijs — smaller and faster than a React app, with no virtual DOM.", "keywords": "web components, custom elements, tosijs, data table, dialog, form, rich text, no virtual dom" }-->
 
 [ui.tosijs.net live demo](https://ui.tosijs.net) | [tosijs](https://tosijs.net) | [discord](https://discord.gg/ramJ9rgky5) | [github](https://github.com/tonioloewald/tosijs-ui#readme) | [npm](https://www.npmjs.com/package/tosijs-ui)
 
@@ -74,9 +74,15 @@ document.body.append(tosiTable())
 
 ### Using the iife via cdn
 
-The `tosijs-ui` iife build bundles `tosijs`, `tosijs-ui`, and `marked` into
-a single minified javascript source file. You can access `xinjs` and `xinjsui`
-as globals which contain all the things exported by `tosijs` and `tosijs-ui`.
+The `tosijs-ui` iife build bundles `tosijs`, `tosijs-ui`, `marked` and — as of 1.7 —
+**CodeMirror** into a single minified javascript source file. You can access `xinjs` and
+`xinjsui` as globals which contain all the things exported by `tosijs` and `tosijs-ui`.
+
+> **Size (1.7):** ~385KB gzip, up from ~120KB in 1.6. `bun build --format iife` cannot
+> code-split, so `<tosi-code>`'s lazy CodeMirror import is flattened into this bundle
+> whether or not the page uses an editor. **If you don't need `<tosi-code>`, use the ESM
+> build** (`import 'tosijs-ui'` via a bundler), where CodeMirror stays a separate lazy
+> chunk and a page with no editor never downloads it.
 
 ```
 <script src="https://ui.tosijs.net/iife.js"></script>

package/bin/make-icon-data.js

@@ -212,9 +212,13 @@ function findIcons(dirs, ignore = []) {
       } else if (path.extname(file) === '.svg') {
         const content = fs.readFileSync(filePath, 'utf8')
         const rawName = file.split('.')[0]
-        const names = rawName.split(',').map((n) =>
-          n.trim().replace(/-([a-z0-9])/g, (_, char) => char.toLocaleUpperCase())
-        )
+        const names = rawName
+          .split(',')
+          .map((n) =>
+            n
+              .trim()
+              .replace(/-([a-z0-9])/g, (_, char) => char.toLocaleUpperCase())
+          )
         const name = names[0]
         let svgSource = content
           .replace(/(<\?xml.*?>|<!DOCTYPE.*?>)\s?/g, '')

package/dist/babylon-3d.js

@@ -345,7 +345,9 @@ export class B3d extends WebComponent {
             this.BABYLON = BABYLON;
             // A `transparent` (alpha < 1) clear-color needs an alpha WebGL context so
             // the canvas composites over the page.
-            const clearColor = this.clearColor ? toColor4(BABYLON, this.clearColor) : null;
+            const clearColor = this.clearColor
+                ? toColor4(BABYLON, this.clearColor)
+                : null;
             this.engine = new BABYLON.Engine(canvas, true, clearColor && clearColor.a < 1
                 ? { alpha: true, premultipliedAlpha: false }
                 : undefined);

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

@@ -2,13 +2,14 @@ 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>;
-}
+/**
+ * Runtime-introspection hooks for tjs autocomplete (all optional). tjs-lang 0.10.0+
+ * ships this type (tjs-lang#12 — we used to hand-declare it); aliased so the public
+ * `TjsAutocompleteConfig` name stays stable. `import type` is erased at build, so this
+ * adds nothing to the bundle.
+ */
+import type { AutocompleteConfig } from 'tjs-lang/editors/codemirror';
+export type TjsAutocompleteConfig = AutocompleteConfig;
 /**
  * Lazy-load tjs-lang's CodeMirror language + completion bundle. Returns a single
  * CodeMirror `Extension` (tjs language, forbidden-keyword highlighting, theme, and

package/dist/code-editor-cm.js

@@ -11,7 +11,7 @@ tjs (highlighting + runtime-value autocomplete via tjs-lang's editors/codemirror
 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 { EditorState, Compartment, Annotation, Transaction, } 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';
@@ -29,6 +29,21 @@ import { oneDarkHighlightStyle } from '@codemirror/theme-one-dark';
 const isDarkMode = () => typeof document !== 'undefined' &&
     !!document.body &&
     document.body.classList.contains('darkmode');
+/**
+ * Marks a transaction as OURS — a programmatic `value` set, not a user edit.
+ *
+ * `change` is documented as "fires when the text changes", and consumers write
+ * `code.addEventListener('change', e => save(e.detail.value))`. Without this, `el.value
+ * = doc` — merely LOADING a document — dispatches a CM transaction, `docChanged` is
+ * true, and the app records a spurious save/dirty-flag every time it populates the
+ * editor. A `disabled` (read-only) editor fired it too: `EditorState.readOnly` gates
+ * user input, not `view.dispatch`. The library itself does this in five places,
+ * including writing results into a read-only *output* editor after every example run.
+ *
+ * The event is new in 1.7 (the ACE build dispatched nothing), so there is no prior
+ * semantic to preserve — and tightening it after 1.7 is on `latest` would be breaking.
+ */
+const programmatic = Annotation.define();
 const highlightFor = (dark) => dark
     ? syntaxHighlighting(oneDarkHighlightStyle)
     : syntaxHighlighting(defaultHighlightStyle, { fallback: true });
@@ -189,8 +204,12 @@ export function createCmEditor(parent, opts = {}) {
                 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());
+                    if (!u.docChanged || !opts.onChange)
+                        return;
+                    // A programmatic `value` set is not a change the USER made. See `programmatic`.
+                    if (u.transactions.some((t) => t.annotation(programmatic)))
+                        return;
+                    opts.onChange(u.state.doc.toString());
                 }),
             ],
         }),
@@ -213,6 +232,12 @@ export function createCmEditor(parent, opts = {}) {
                 return;
             view.dispatch({
                 changes: { from: 0, to: view.state.doc.length, insert: text },
+                annotations: [
+                    programmatic.of(true),
+                    // Loading a document is not an edit to undo back out of. (The ACE wrapper
+                    // called `getUndoManager().reset()` at this point, for the same reason.)
+                    Transaction.addToHistory.of(false),
+                ],
             });
         },
         setMode(mode) {

package/dist/code-editor.d.ts

@@ -28,9 +28,7 @@ export declare class CodeEditor extends WebComponent<CodeEditorParts> {
     get original(): string;
     set original(text: string);
     private diffOverlay;
-    private _partsHydrated;
     private _pendingDiff;
-    private get partsReady();
     get showingDiff(): boolean;
     showDiff(on: boolean): void;
     static initAttributes: {
@@ -38,7 +36,22 @@ export declare class CodeEditor extends WebComponent<CodeEditorParts> {
         disabled: boolean;
     };
     role: string;
-    /** The underlying CodeMirror EditorView (undefined until loaded). */
+    /**
+     * The underlying CodeMirror `EditorView` (undefined until loaded).
+     *
+     * **Changed in 1.7 (ACE → CodeMirror 6).** In 1.6 this was an ACE editor, and
+     * `editor.session.getUndoManager()` was documented public API. `^1.6.x` resolves
+     * 1.7.0, so an app that never changed a line auto-upgrades into a `TypeError` on the
+     * next install — and this is the ONE break the warn-once shims below cannot catch,
+     * because the property still exists and still returns an object; it is simply a
+     * different object. TS consumers get a compile error (1.6 typed this `any`); vanilla
+     * 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.
+     */
     get editor(): CmHandle['view'] | undefined;
     /** @deprecated Removed in 1.7 — CodeMirror themes via `--code-bg`/`--text-color`. */
     get theme(): string;
@@ -88,6 +101,9 @@ export declare class CodeEditor extends WebComponent<CodeEditorParts> {
      * installed, or if the mode/handle changed before the async load resolved.
      */
     private applyTjsExtension;
+    /** True once tjs-lang's CM language+autocomplete is actually live (test seam). */
+    get tjsExtensionApplied(): boolean;
+    private _tjsExtensionApplied;
     render(): void;
 }
 export declare const codeEditor: ElementCreator<CodeEditor>;

package/dist/code-editor.js

@@ -76,6 +76,9 @@ const warnRemoved = (member, advice) => {
     warned.add(member);
     console.warn(`<tosi-code>.${member} was removed in tosijs-ui 1.7 (the editor is now CodeMirror 6, not ACE) — ${advice}. See CHANGELOG 1.7.0.`);
 };
+// One warning per page, not per element — see the `editor` getter.
+let warnedEditor = false;
+let warnedTjs = false;
 export class CodeEditor extends WebComponent {
     static preferredTagName = 'tosi-code';
     source = '';
@@ -135,28 +138,24 @@ export class CodeEditor extends WebComponent {
     // it. (Re-adding a slot is NOT the fix — it would also project the element's
     // textContent, i.e. the initial code, and double-render it under the editor.)
     diffOverlay;
-    // Set once hydration has actually happened (end of connectedCallback).
-    //
-    // This CANNOT be a `try { this.parts.x } catch` probe, which is what it used to be.
-    // tosijs's `parts` proxy caches its query root on FIRST access — so touching it before
-    // hydration permanently roots the proxy at the light-DOM element, and every later
-    // `this.parts.*` throws, including the `this.parts.host` that mounts CodeMirror. The
-    // editor then never mounts at all. Merely reading `el.showingDiff` on a constructed,
-    // not-yet-inserted element was enough to brick it — silently, and unrecoverably.
-    _partsHydrated = false;
-    // A showDiff() call made before hydration, replayed once we're ready (rather than
-    // silently dropped, which is what used to happen).
+    // Hydration state comes from the base class (`this.hydrated`), as of tosijs 1.6.9.
+    // This used to be a hand-rolled `_partsHydrated` flag — because before 1.6.9 the
+    // `parts` proxy poisoned itself on any pre-hydration read (touching it once rooted
+    // the proxy at the light-DOM element forever, so the editor never mounted), and
+    // there was no public way to ask "am I hydrated yet?" without triggering exactly
+    // that. 1.6.9 fixed both — it invalidates the cached proxy at hydrate AND exposes
+    // `hydrated`/`whenHydrated` — so the flag is gone. (tonioloewald/tosijs#13.)
+    // A showDiff() call made before hydration, replayed once we're ready. Still needed:
+    // `parts` genuinely doesn't exist before hydration (content is injected at connect),
+    // so work that touches it is legitimately deferred — that is not the poisoning bug.
     _pendingDiff;
-    get partsReady() {
-        return this._partsHydrated;
-    }
     get showingDiff() {
-        if (!this.partsReady)
+        if (!this.hydrated)
             return this._pendingDiff ?? false;
         return !this.parts.diffHost.hidden;
     }
     showDiff(on) {
-        if (!this.partsReady) {
+        if (!this.hydrated) {
             this._pendingDiff = on;
             return;
         }
@@ -176,8 +175,30 @@ export class CodeEditor extends WebComponent {
         disabled: false,
     };
     role = 'code editor';
-    /** The underlying CodeMirror EditorView (undefined until loaded). */
+    /**
+     * The underlying CodeMirror `EditorView` (undefined until loaded).
+     *
+     * **Changed in 1.7 (ACE → CodeMirror 6).** In 1.6 this was an ACE editor, and
+     * `editor.session.getUndoManager()` was documented public API. `^1.6.x` resolves
+     * 1.7.0, so an app that never changed a line auto-upgrades into a `TypeError` on the
+     * next install — and this is the ONE break the warn-once shims below cannot catch,
+     * because the property still exists and still returns an object; it is simply a
+     * different object. TS consumers get a compile error (1.6 typed this `any`); vanilla
+     * 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.
+     */
     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.');
+        }
         return this._handle?.view;
     }
     // ── Removed in 1.7 (ACE → CodeMirror 6) ────────────────────────────────────
@@ -251,8 +272,8 @@ export class CodeEditor extends WebComponent {
     }
     connectedCallback() {
         super.connectedCallback();
-        // super.connectedCallback() hydrates, so `this.parts` is safe from here on.
-        this._partsHydrated = true;
+        // super.connectedCallback() hydrated us, so `this.hydrated` is now true and
+        // `this.parts` is safe from here on.
         if (this.source === '') {
             this.value = this.textContent !== null ? this.textContent.trim() : '';
         }
@@ -330,9 +351,35 @@ export class CodeEditor extends WebComponent {
             .then((ext) => {
             if (ext && this._handle === handle && this.isTjsMode()) {
                 handle.setLanguageExtension(ext);
+                this._tjsExtensionApplied = true;
+                return;
+            }
+            // Degrade LOUDLY. `loadTjsExtension` swallows everything and returns null by
+            // design, and the guard is `typeof mod.tjsEditorExtension === 'function'` — so
+            // an upstream export rename returns null without even throwing, and every tjs
+            // editor on the page silently falls back to plain TypeScript highlighting with
+            // no autocomplete. Nothing goes red; the feature just quietly isn't there.
+            if (!ext && this._handle === handle && this.isTjsMode() && !warnedTjs) {
+                warnedTjs = true;
+                console.warn(`<tosi-code mode="${this.mode}">: tjs-lang's CodeMirror extension did not load — ` +
+                    `falling back to TypeScript highlighting (no tjs autocomplete). Install the ` +
+                    `optional peer \`tjs-lang\`, or check that tjs-lang/editors/codemirror still ` +
+                    `exports \`tjsEditorExtension\`.`);
+            }
+        })
+            .catch((e) => {
+            // The chain had no .catch(), so any throw here was an unhandled rejection.
+            if (!warnedTjs) {
+                warnedTjs = true;
+                console.warn(`<tosi-code>: failed to apply the tjs extension —`, e);
             }
         });
     }
+    /** True once tjs-lang's CM language+autocomplete is actually live (test seam). */
+    get tjsExtensionApplied() {
+        return this._tjsExtensionApplied;
+    }
+    _tjsExtensionApplied = false;
     render() {
         super.render();
         if (this._handle) {

package/dist/doc-browser.d.ts

@@ -23,6 +23,10 @@ export interface Doc {
     pin?: string;
     hidden?: boolean;
     testStatus?: 'passed' | 'failed' | 'pending';
+    bakes?: Array<[string, {
+        dialect: string;
+        js: string;
+    }]>;
 }
 export interface ProjectLinks {
     github?: string;