tosijs-ui 1.6.21 → 1.7.0-beta.1

package/dist/doc-system/site/bundle-guard.d.ts

@@ -0,0 +1,50 @@
+declare global {
+    var Bun: any;
+}
+/** The specifier that must NOT survive in the bundle when tjs-lang is installed. */
+export declare const TJS_EDITOR_SPECIFIER = "tjs-lang/editors/codemirror";
+/**
+ * Externalize the tjs CodeMirror extension ONLY when tjs-lang isn't installed.
+ *
+ * When it IS installed we bundle it in, so it shares the editor's single CodeMirror
+ * instance. When it's absent, bundling would fail to resolve, so we externalize it and
+ * the runtime import degrades to plain TS highlighting.
+ *
+ * Returns [] (i.e. "bundle it") when tjs-lang resolves, else [TJS_EDITOR_SPECIFIER].
+ */
+export declare function tjsEditorExternal(root: string): string[];
+/**
+ * Did the tjs CodeMirror extension get externalized out of the bundle?
+ *
+ * If it was bundled, its specifier is gone (the module's code is inlined). If it was
+ * externalized, the bundler leaves the specifier behind in an `import("…")`. So the
+ * presence of the specifier in the emitted JS means the invariant is broken.
+ *
+ * Checking the identifier (`tjsCompletionSource`) instead would be useless: the import
+ * SITE names it either way, so that grep passes in exactly the broken case.
+ */
+export declare function tjsEditorLeakedAsExternal(bundleJs: string): boolean;
+/**
+ * Compile (without running) the bundle as a classic script body, and return the syntax
+ * error if it isn't valid. `import.meta` is a SyntaxError outside a module, so this
+ * catches the real failure.
+ *
+ * The naive `bundleJs.includes('import.meta')` this replaces false-positived on EVERY
+ * build that bundled a JS parser: acorn's own error-message string literals contain
+ * "import.meta", so the guard fired while the bundle was perfectly fine — and its advice
+ * ("mark that dep external") would have undone the deliberate decision to bundle the tjs
+ * CodeMirror extension. A guard that cries wolf on every build trains everyone to ignore
+ * the real hit.
+ */
+export declare function classicScriptSyntaxError(bundleJs: string): string | null;
+/**
+ * The same check, run in a CHILD process — this is what the build calls.
+ *
+ * Compiling the bundle strands memory in the parent: JSC caches the compiled code, so
+ * `new Function()` over a 1.2MB bundle retains ~378KB *per call* even after a forced
+ * GC. The build runs on every dev rebuild in a process that lives for days, so that is
+ * exactly the shape of leak this release just fixed elsewhere — parsing to guard
+ * against a leak while leaking would be a poor joke. The child hands it all back on
+ * exit. (Cost: one ~30ms process. See oven-sh/bun#34053 for the family.)
+ */
+export declare function classicScriptSyntaxErrorInChild(bundlePath: string): Promise<string | null>;

package/dist/doc-system/site/bundle-guard.js

@@ -0,0 +1,111 @@
+/*
+Guards on the emitted hydration bundle.
+
+Two invariants that both fail SILENTLY at runtime, which is why they're checked at
+build time against the actual emitted bytes rather than against the config:
+
+1. `import.meta` must not survive into an IIFE — it's a SyntaxError in a classic
+   <script>, so the whole bundle fails to evaluate and the page never hydrates.
+2. tjs-lang's CodeMirror extension must be BUNDLED, not externalized — a separately
+   loaded copy carries its own `@codemirror/state` and silently no-ops (no error, no
+   warning; tjs highlighting and autocomplete just quietly stop working).
+
+Build-time only. Never import from browser code.
+*/
+/** The specifier that must NOT survive in the bundle when tjs-lang is installed. */
+export const TJS_EDITOR_SPECIFIER = 'tjs-lang/editors/codemirror';
+/**
+ * Externalize the tjs CodeMirror extension ONLY when tjs-lang isn't installed.
+ *
+ * When it IS installed we bundle it in, so it shares the editor's single CodeMirror
+ * instance. When it's absent, bundling would fail to resolve, so we externalize it and
+ * the runtime import degrades to plain TS highlighting.
+ *
+ * Returns [] (i.e. "bundle it") when tjs-lang resolves, else [TJS_EDITOR_SPECIFIER].
+ */
+export function tjsEditorExternal(root) {
+    try {
+        Bun.resolveSync(TJS_EDITOR_SPECIFIER, root);
+        return [];
+    }
+    catch {
+        return [TJS_EDITOR_SPECIFIER];
+    }
+}
+/**
+ * Did the tjs CodeMirror extension get externalized out of the bundle?
+ *
+ * If it was bundled, its specifier is gone (the module's code is inlined). If it was
+ * externalized, the bundler leaves the specifier behind in an `import("…")`. So the
+ * presence of the specifier in the emitted JS means the invariant is broken.
+ *
+ * Checking the identifier (`tjsCompletionSource`) instead would be useless: the import
+ * SITE names it either way, so that grep passes in exactly the broken case.
+ */
+export function tjsEditorLeakedAsExternal(bundleJs) {
+    return bundleJs.includes(TJS_EDITOR_SPECIFIER);
+}
+/**
+ * Compile (without running) the bundle as a classic script body, and return the syntax
+ * error if it isn't valid. `import.meta` is a SyntaxError outside a module, so this
+ * catches the real failure.
+ *
+ * The naive `bundleJs.includes('import.meta')` this replaces false-positived on EVERY
+ * build that bundled a JS parser: acorn's own error-message string literals contain
+ * "import.meta", so the guard fired while the bundle was perfectly fine — and its advice
+ * ("mark that dep external") would have undone the deliberate decision to bundle the tjs
+ * CodeMirror extension. A guard that cries wolf on every build trains everyone to ignore
+ * the real hit.
+ */
+export function classicScriptSyntaxError(bundleJs) {
+    try {
+        new Function(bundleJs);
+        return null;
+    }
+    catch (e) {
+        return e instanceof SyntaxError ? e.message : null;
+    }
+}
+/**
+ * The same check, run in a CHILD process — this is what the build calls.
+ *
+ * Compiling the bundle strands memory in the parent: JSC caches the compiled code, so
+ * `new Function()` over a 1.2MB bundle retains ~378KB *per call* even after a forced
+ * GC. The build runs on every dev rebuild in a process that lives for days, so that is
+ * exactly the shape of leak this release just fixed elsewhere — parsing to guard
+ * against a leak while leaking would be a poor joke. The child hands it all back on
+ * exit. (Cost: one ~30ms process. See oven-sh/bun#34053 for the family.)
+ */
+export async function classicScriptSyntaxErrorInChild(bundlePath) {
+    const self = `${import.meta.dir}/bundle-guard.ts`;
+    const cli = (await Bun.file(self).exists())
+        ? self
+        : `${import.meta.dir}/bundle-guard.js`;
+    const child = Bun.spawn(['bun', cli, bundlePath], {
+        stdout: 'ignore',
+        stderr: 'pipe',
+    });
+    // ALWAYS drain stderr, not just on failure: an unconsumed pipe stays open and its
+    // buffer is retained, which turns this guard into a per-rebuild leak of its own.
+    const [code, message] = await Promise.all([
+        child.exited,
+        new Response(child.stderr).text(),
+    ]);
+    if (code === 0)
+        return null;
+    return message.trim() || 'the bundle does not parse as a classic <script>';
+}
+// CLI entry (the child above): `bun bundle-guard.ts <bundle.js>` — exits 1 with the
+// syntax error on stderr, 0 if the bundle is a valid classic script.
+if (import.meta.main) {
+    const file = process.argv[2];
+    if (!file) {
+        console.error('bundle-guard: expected a bundle path');
+        process.exit(1);
+    }
+    const error = classicScriptSyntaxError(await Bun.file(file).text());
+    if (error) {
+        console.error(error);
+        process.exit(1);
+    }
+}

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

@@ -14,7 +14,7 @@ are not executed, so they're skipped.
 Build-time only (bun). Never import from browser code.
 */
 import { marked } from 'marked';
-import { rewriteImports, AsyncFunction, loadTransform } from '../../live-example/code-transform';
+import { rewriteImports, AsyncFunction, loadTransform, } from '../../live-example/code-transform';
 // The default live-example context (matches the IIFE globals the pages provide).
 // A project that sets a custom `context` on its <tosi-doc-system> can pass its
 // own keys; these are the tosijs-ui defaults.
@@ -44,6 +44,14 @@ function collectCodeTokens(text) {
 export async function checkExamples(docs, opts = {}) {
     const contextKeys = opts.contextKeys ?? DEFAULT_CONTEXT_KEYS;
     const problems = [];
+    // ONE transpiler for the whole corpus, not one per example. It's stateless, and
+    // it's a native object that strands ~40KB of RSS per construction — invisible to
+    // the JS heap, so nothing GCs it. checkExamples runs on every dev rebuild, over
+    // every `ts` example in the corpus, in a process that lives for days: constructing
+    // it in the loop was leaking ~40KB × (ts examples) per rebuild. Reusing one drops
+    // that to ~1.6KB per call. (Same family as the Bun.build arena leak — oven-sh/bun#34053.)
+    // Lazily created so a corpus with no `ts` examples never makes one.
+    let tsTranspiler;
     for (const doc of docs) {
         for (const block of collectCodeTokens(doc.text)) {
             if (!EXECUTABLE.has(block.lang))
@@ -58,7 +66,8 @@ export async function checkExamples(docs, opts = {}) {
                     // fetches the TypeScript compiler from a CDN, which can't run here).
                     // We only need to validate that the source builds, not reproduce tjs
                     // lowering exactly.
-                    js = new Bun.Transpiler({ loader: 'ts' }).transformSync(rewritten);
+                    tsTranspiler ??= new Bun.Transpiler({ loader: 'ts' });
+                    js = tsTranspiler.transformSync(rewritten);
                 }
                 else if (dialect === 'tjs') {
                     const transform = await loadTransform('tjs');
@@ -68,7 +77,6 @@ export async function checkExamples(docs, opts = {}) {
                     js = rewritten; // `js` / `test` are already JS
                 }
                 // Syntax-validate the way the component does before running it.
-                // eslint-disable-next-line no-new
                 new AsyncFunction(js);
             }
             catch (err) {

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

@@ -80,7 +80,10 @@ async function ensureDevCerts() {
     process.exit(1);
 }
 export async function devServer(config, opts = {}) {
-    const PORT = config.port ?? 8787;
+    // PORT env wins over the config, so a test harness can bring up its own instance on
+    // its own port instead of adopting (or killing — killStrayServer takes the port)
+    // the dev server you already have running.
+    const PORT = Number(process.env.PORT ?? config.port ?? 8787);
     const PUBLIC = path.resolve('./', config.outputDir ?? 'docs');
     const isSPA = true;
     const testMode = !!opts.test;
@@ -89,8 +92,17 @@ export async function devServer(config, opts = {}) {
     // localhost-gated runtime import() of the local channel's dev.js, so haltija
     // is never bundled and self-disables off-localhost; it's injected only at
     // serve time (below), so it never lands in the built output.
+    //
+    // Explicitly OFF under `HALTIJA_DEV=0` and in CI, which both override a config
+    // `haltijaDev: true`: the E2E lane starts this server, and there is no agent on
+    // the other end of the channel there — spawning it would only download an Electron
+    // app into the runner for nobody to look at.
     const HALTIJA_HTTPS_PORT = 8701;
+    const haltijaOff = process.env.HALTIJA_DEV === '0' ||
+        process.env.HALTIJA_DEV === 'false' ||
+        process.env.CI === 'true';
     const haltijaDev = !testMode &&
+        !haltijaOff &&
         (config.haltijaDev === true ||
             process.env.HALTIJA_DEV === '1' ||
             process.env.HALTIJA_DEV === 'true');
@@ -223,6 +235,57 @@ export async function devServer(config, opts = {}) {
         // never regenerated — leaving the page's /iife.js to 404 into the SPA
         // fallback (it "loads as html"). Serialize builds and coalesce bursts.
         const runBuild = opts.build ?? (() => buildSite(config));
+        // Memory watchdog.
+        //
+        // The build hands work to native code (the bundler, the HTML parser, the SVG
+        // rasterizer) which can strand memory the JS heap never sees — so nothing
+        // here can GC it away, and `heapUsed` stays flat while RSS climbs. A watch
+        // process lives for DAYS across thousands of rebuilds, so a per-rebuild leak
+        // compounds until the machine swaps itself to death. That is not
+        // hypothetical: a 2-day session reached 136GB RSS and took the machine down
+        // (Bun.build's native arena — see orchestrator.ts and oven-sh/bun#34053).
+        // Dying loudly beats being the reason a laptop overheats: the dev server is
+        // one keystroke to restart, the machine is not.
+        const rssMb = () => Math.round(process.memoryUsage().rss / 1e6);
+        const limitMb = Number(process.env.DEV_MEMORY_LIMIT_MB ?? config.memoryLimitMb ?? 4096);
+        let baselineMb = 0;
+        let rebuilds = 0;
+        let warned = false;
+        const checkMemory = () => {
+            const mb = rssMb();
+            rebuilds += 1;
+            if (!baselineMb)
+                baselineMb = mb;
+            const growth = mb - baselineMb;
+            const each = rebuilds > 1 ? growth / (rebuilds - 1) : 0;
+            if (mb >= limitMb) {
+                // Distinguish the two ways to get here, because the advice is opposite:
+                // memory that GREW across rebuilds is a leak (report it); a build that was
+                // simply born bigger than the ceiling just needs a bigger ceiling.
+                const leaking = rebuilds > 1 && each >= 1;
+                const diagnosis = leaking
+                    ? `   ${rebuilds} rebuilds, +${growth}MB since the first ` +
+                        `(~${each.toFixed(1)}MB per rebuild).\n\n` +
+                        `   Growth per rebuild should be ~0, so this is a leak, not your project\n` +
+                        `   getting bigger. Restarting reclaims it — please report the numbers\n` +
+                        `   above. If this build genuinely needs the headroom, raise the ceiling\n` +
+                        `   with DEV_MEMORY_LIMIT_MB=<mb> or memoryLimitMb in your site config.\n`
+                    : `   ${rebuilds} rebuild${rebuilds === 1 ? '' : 's'}, ` +
+                        `+${growth}MB since the first — i.e. it is not growing.\n\n` +
+                        `   This build's baseline footprint is simply above the ceiling, which is\n` +
+                        `   not a leak. Raise it with DEV_MEMORY_LIMIT_MB=<mb> or memoryLimitMb in\n` +
+                        `   your site config.\n`;
+                console.error(`\n🛑 dev server stopping: ${mb}MB RSS, over the ${limitMb}MB limit.\n\n` +
+                    diagnosis);
+                process.exit(1);
+            }
+            if (!warned && mb > limitMb * 0.6) {
+                warned = true;
+                console.warn(`⚠️  dev server at ${mb}MB RSS after ${rebuilds} rebuilds (+${growth}MB, ` +
+                    `~${each.toFixed(1)}MB each; limit ${limitMb}MB). Growth per rebuild ` +
+                    `should be ~0 — if this keeps climbing, restart and report it.`);
+            }
+        };
         let building = false;
         let pending = false;
         const rebuild = async () => {
@@ -239,6 +302,7 @@ export async function devServer(config, opts = {}) {
             }
             finally {
                 building = false;
+                checkMemory();
                 if (pending) {
                     pending = false;
                     void rebuild();
@@ -313,9 +377,13 @@ export async function devServer(config, opts = {}) {
         }
         if (!hjAvailable) {
             console.log('Starting haltija...');
+            // stdout/stderr are NOT inherited: `bunx haltija` launches an Electron app as a
+            // grandchild, and killing the bunx wrapper does not kill it. An orphaned Electron
+            // holding our inherited stdout keeps the pipe open forever, so a CI job or an
+            // agent capturing this command's output sees it hang long after it exited (0).
             haltija = spawn(['bunx', 'haltija@latest', '-f'], {
-                stdout: 'inherit',
-                stderr: 'inherit',
+                stdout: 'ignore',
+                stderr: 'ignore',
             });
             console.log('Waiting for browser...');
             for (let i = 0; i < 20; i++) {
@@ -343,18 +411,40 @@ export async function devServer(config, opts = {}) {
         }
         console.log('Opening demo site...');
         await $ `hj navigate https://localhost:${PORT}`;
+        /**
+         * Tear down the haltija WE started — including the Electron grandchild.
+         *
+         * `haltija.kill()` only signals the `bunx` wrapper; the Electron app it launched
+         * survives. A surviving instance leaves stale windows behind, and the next
+         * `--test` run reuses any haltija reporting `windows.length > 0` — so the run
+         * after this one navigates a dead window, never POSTs /report, and fails with
+         * "Browser tests timed out" on a perfectly good codebase. Only ever kills the
+         * instance this process spawned; a haltija you were already running is left alone.
+         */
+        const stopHaltija = async () => {
+            if (!haltija)
+                return;
+            haltija.kill();
+            // NB: interpolate the pattern — a quoted literal in a `$` template is passed to
+            // pkill WITH the quotes and matches nothing.
+            const electron = 'haltija/apps/desktop';
+            try {
+                await $ `pkill -f ${electron}`.quiet();
+            }
+            catch {
+                // nothing left to kill — fine
+            }
+        };
         try {
             const results = await testResults;
             const exitCode = results.failed > 0 ? 1 : 0;
-            if (haltija)
-                haltija.kill();
+            await stopHaltija();
             server.stop();
             process.exit(exitCode);
         }
         catch (e) {
             console.error(e.message);
-            if (haltija)
-                haltija.kill();
+            await stopHaltija();
             server.stop();
             process.exit(1);
         }

package/dist/doc-system/site/epub-cli.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/doc-system/site/epub-cli.js

@@ -0,0 +1,22 @@
+/*
+Standalone ePub build — the subprocess entry point for buildEpub().
+
+buildEpub() drives happy-dom (HTML→XHTML for 50+ chapters) and @resvg/resvg-js
+(cover rasterization). Both hold native/retained memory that the JS heap can't
+see, and the ePub is rebuilt on EVERY dev-server rebuild — so in-process it
+strands memory in a watch process that lives for days. Running it in a child
+hands all of it back to the OS on exit. Same reasoning as the bundle step; see
+the Bun.build note in orchestrator.ts.
+
+  bun epub-cli.ts <payload.json>     # payload = { config, opts }
+
+Build-time only. Never import this from browser code.
+*/
+import { buildEpub } from './epub';
+const payloadPath = process.argv[2];
+if (!payloadPath) {
+    console.error('epub-cli: expected a payload file path');
+    process.exit(1);
+}
+const { config, opts } = JSON.parse(await Bun.file(payloadPath).text());
+await buildEpub(config, opts ?? {});

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

@@ -25,8 +25,20 @@ import { selectBookDocs } from '../book-manifest';
 export { DEFAULT_BOOK_CSS, stripDocMeta };
 // ── XML / XHTML helpers ─────────────────────────────────────────────────────
 const VOID_ELEMENTS = [
-    'area', 'base', 'br', 'col', 'embed', 'hr', 'img', 'input', 'link', 'meta',
-    'param', 'source', 'track', 'wbr',
+    'area',
+    'base',
+    'br',
+    'col',
+    'embed',
+    'hr',
+    'img',
+    'input',
+    'link',
+    'meta',
+    'param',
+    'source',
+    'track',
+    'wbr',
 ];
 export function escapeXml(s) {
     return s
@@ -222,7 +234,9 @@ function packageOpf(meta, chapters, cover) {
         ...chapters.map((c) => `<itemref idref="${c.id}"/>`),
     ];
     // EPUB2 cover fallback (older readers find the thumbnail via this meta).
-    const coverMeta = cover ? `\n    <meta name="cover" content="cover-image"/>` : '';
+    const coverMeta = cover
+        ? `\n    <meta name="cover" content="cover-image"/>`
+        : '';
     return `<?xml version="1.0" encoding="utf-8"?>
 <package xmlns="http://www.idpf.org/2007/opf" version="3.0" unique-identifier="book-id">
   <metadata xmlns:dc="http://purl.org/dc/elements/1.1/">
@@ -321,7 +335,9 @@ async function zipEpub(buildDir, outputAbs) {
     // 1) mimetype first, stored (-0), no extra fields (-X)
     await $ `zip -X0 ${outputAbs} mimetype`.cwd(buildDir).quiet();
     // 2) everything else, deflated (-9), recursive (-r), no extra fields, no dir entries (-D)
-    await $ `zip -Xr9D ${outputAbs} META-INF OEBPS -x mimetype`.cwd(buildDir).quiet();
+    await $ `zip -Xr9D ${outputAbs} META-INF OEBPS -x mimetype`
+        .cwd(buildDir)
+        .quiet();
 }
 /** Rasterize an SVG to a PNG buffer via @resvg/resvg-js (optional dep). */
 async function rasterizeSvg(svg, width) {
@@ -423,7 +439,11 @@ async function makeCover(config, opts, meta) {
             : ext === '.gif'
                 ? 'image/gif'
                 : 'image/png';
-        return { file: `cover${ext || '.png'}`, mediaType, data: fs.readFileSync(opts.cover) };
+        return {
+            file: `cover${ext || '.png'}`,
+            mediaType,
+            data: fs.readFileSync(opts.cover),
+        };
     }
     // Embed a glyph (svg) into the generated cover: prefer an explicit `coverIcon`,
     // else the site favicon. Preserve the source viewBox so any square-ish icon
@@ -500,15 +520,14 @@ export async function buildEpub(config, opts = {}) {
         const doc = node.doc;
         // The doc's live-site URL, matching generate-site's canonical link: README
         // maps to '/' (not '/index/'), others to '/slug/', with basePath applied.
-        const pageUrl = baseUrl + withBase(config.basePath, pathForSlug(slugMap[doc.filename] ?? ''));
+        const pageUrl = baseUrl +
+            withBase(config.basePath, pathForSlug(slugMap[doc.filename] ?? ''));
         const html = renderDocMarkdown(stripDocMeta(doc.text));
         // happy-dom occasionally throws on exotic content (e.g. an internal selector
         // bug); fall back to the regex pass for that doc rather than aborting.
         let bodyHtml;
         try {
-            const transform = win && baseUrl
-                ? (d) => injectExampleLinks(d, pageUrl)
-                : undefined;
+            const transform = win && baseUrl ? (d) => injectExampleLinks(d, pageUrl) : undefined;
             bodyHtml = win ? htmlToXhtml(html, win, transform) : toXhtml(html);
         }
         catch {
@@ -535,6 +554,12 @@ export async function buildEpub(config, opts = {}) {
     const output = path.resolve(opts.output ?? path.join(outDir, `${slugify(meta.title)}.epub`));
     await zipEpub(buildDir, output);
     fs.rmSync(buildDir, { recursive: true, force: true });
+    // Release the parser window: an unclosed happy-dom Window holds its whole
+    // document (every chapter parsed) plus its timers. Hygiene, not a proven win —
+    // buildEpub still grows ~1.5MB per call with this in place, so something here
+    // is still retained. buildEpub now runs in a child process (see orchestrator),
+    // which is what actually bounds it.
+    win?.close?.();
     console.log(`epub: ${output} (${chapters.length} chapters)`);
     return output;
 }

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

@@ -58,7 +58,7 @@ export function entriesFromCorpus(corpus, meta) {
  */
 function entriesFromSrcScan() {
     const entries = [];
-    let files = [];
+    let files;
     try {
         files = fs.readdirSync(SRC).filter((f) => f.endsWith('.ts'));
     }