tosijs-ui 1.6.17 → 1.6.19

package/CHANGELOG.md

@@ -1,5 +1,53 @@
 # Changelog
 
+## 1.6.19
+
+Doc-system tooling; no component API changes.
+
+### Added
+
+- **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
+  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
+  blockquotes and lists. TypeScript is transpiled with bun's own transpiler
+  (network-free). Opt out with `checkExamples: false`.
+- **"One Source, Every Artifact"** doc page — how one corpus of doc-comments +
+  markdown projects into a static SEO site, a self-testing live playground with
+  in-browser TypeScript, an ePub/PDF, and an agent-debuggable page. Embeds a live
+  `<tosi-doc-system>` (the whole system running inside its own page).
+
+### 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
+  its examples are checked for explosions — a no-test example that throws is
+  reported as a failed test — not just blocks with explicit assertions.
+
+## 1.6.18
+
+Doc-site tooling; no component API changes.
+
+### Added
+
+- **`haltijaDev` — give a coding agent eyes + hands on your running dev page.**
+  Set `haltijaDev: true` (or `HALTIJA_DEV=1`) and `bun start` injects a tiny
+  localhost-gated loader into served HTML — a runtime `import()` of a local
+  [haltija](https://github.com/tonioloewald/haltija) channel's `dev.js` — and
+  spins up (or reuses) a server-only channel (no Electron app) in `--both` mode:
+  HTTP 8700 for the `hj` CLI, HTTPS 8701 for the injected widget (so an HTTPS page
+  has no mixed-content). An agent can then read the live DOM, click/type, run JS,
+  and **screen-capture** the rendered page (`hj screenshot`, via `getDisplayMedia`
+  — click the 🖥 widget button once to grant the share). Because the loader is
+  pulled from the local server at runtime it is **never bundled** (zero build
+  bytes) and self-disables off-localhost, and because it's injected at serve time
+  it never touches the built output. Certs are mkcert-signed (already required for
+  the dev server's HTTPS), so no browser warning. Local dev only; off by default.
+  The channel tracks haltija's `@beta` dist-tag (where the WebRTC capture lives).
+
 ## 1.6.17
 
 ### Fixed

package/dist/doc-browser.js

@@ -1250,7 +1250,11 @@ export function createDocBrowser(options) {
         if (isTestFrame)
             return; // Don't run background tests in test iframe
         backgroundTestsStarted = true;
-        // Find all docs that have test blocks
+        // Find all docs that have test blocks. (Pages with examples but no explicit
+        // tests are covered cheaply at BUILD time by the transpile check —
+        // src/doc-system/site/check-examples.ts — without loading them in a browser,
+        // so the runner doesn't have to render every heavy page just to notice a
+        // build error.)
         const docsWithTests = docs.filter((doc) => doc.text.includes('```test'));
         pagesWithTests = docsWithTests.length;
         if (pagesWithTests > 0) {

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

@@ -0,0 +1,14 @@
+import type { Doc } from './docs';
+export interface ExampleProblem {
+    filename: string;
+    title: string;
+    lang: string;
+    error: string;
+    snippet: string;
+}
+/** Transpile-check every executable block in the corpus. Returns the problems. */
+export declare function checkExamples(docs: Doc[], opts?: {
+    contextKeys?: string[];
+}): Promise<ExampleProblem[]>;
+/** Format problems for a build log. */
+export declare function formatExampleProblems(problems: ExampleProblem[]): string;

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

@@ -0,0 +1,97 @@
+/*
+Build-time transpile check for live examples.
+
+Every executable code block in the corpus (`js` / `tjs` / `ts` / `test`) is put
+through the SAME front half of the runtime pipeline the live-example component
+uses — `rewriteImports` → the tjs-lang transform → `new AsyncFunction(...)` — so a
+block that can't build (a tjs/TS syntax error, an unsupported import, or
+illustrative config mistakenly tagged with an executable language like `ts`
+instead of the display-only `typescript`) fails the build *at authoring time*,
+on every page, instead of silently rendering an error only when someone opens
+that page. `html` / `css` and display-only languages (`typescript`, `json`, …)
+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';
+// 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.
+const DEFAULT_CONTEXT_KEYS = ['tosijs', 'tosijs-ui'];
+const EXECUTABLE = new Set(['js', 'tjs', 'ts', 'test']);
+/** The bare dialect from a fence info string ('js#my-id' → 'js'); '' if none. */
+function dialectOf(info) {
+    return (info ?? '').match(/^[a-z]+/)?.[0] ?? '';
+}
+/** Collect every fenced code block in a doc (recursing into lists/quotes). */
+function collectCodeTokens(text) {
+    const out = [];
+    const walk = (tokens) => {
+        for (const t of tokens) {
+            if (t.type === 'code')
+                out.push({ lang: dialectOf(t.lang), text: t.text });
+            if (Array.isArray(t.tokens))
+                walk(t.tokens);
+            if (Array.isArray(t.items))
+                walk(t.items); // list items
+        }
+    };
+    walk(marked.lexer(text));
+    return out;
+}
+/** Transpile-check every executable block in the corpus. Returns the problems. */
+export async function checkExamples(docs, opts = {}) {
+    const contextKeys = opts.contextKeys ?? DEFAULT_CONTEXT_KEYS;
+    const problems = [];
+    for (const doc of docs) {
+        for (const block of collectCodeTokens(doc.text)) {
+            if (!EXECUTABLE.has(block.lang))
+                continue;
+            // `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);
+                let js;
+                if (dialect === 'ts') {
+                    // Use bun's own transpiler — network-free (the runtime `ts` path
+                    // 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);
+                }
+                else if (dialect === 'tjs') {
+                    const transform = await loadTransform('tjs');
+                    js = (await transform(rewritten, { transforms: ['typescript'] })).code;
+                }
+                else {
+                    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) {
+                problems.push({
+                    filename: doc.filename,
+                    title: doc.title,
+                    lang: block.lang,
+                    error: err.message || String(err),
+                    snippet: block.text.split('\n').slice(0, 3).join('\n'),
+                });
+            }
+        }
+    }
+    return problems;
+}
+/** Format problems for a build log. */
+export function formatExampleProblems(problems) {
+    return problems
+        .map((p) => `  ✗ ${p.filename} (${p.lang}) — ${p.title}\n` +
+        `    ${p.error}\n` +
+        p.snippet
+            .split('\n')
+            .map((l) => `      | ${l}`)
+            .join('\n'))
+        .join('\n\n');
+}

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

@@ -21,6 +21,48 @@ async function killStrayServer(port) {
         // No process on port, that's fine
     }
 }
+/**
+ * Reuse-or-spawn a haltija dev-channel server (server-only, no desktop app) on
+ * `port` over HTTPS, so the loader injected into the dev pages has something to
+ * connect to. Best-effort: if the reachability check fails we still spawn, and
+ * if the spawn fails we just log — the injected loader degrades to a no-op, so
+ * dev startup is never blocked on haltija.
+ */
+async function ensureHaltijaChannel(port) {
+    const base = `https://localhost:${port}`;
+    const up = await fetch(`${base}/status`, {
+        // The 8701 cert is mkcert-signed, but don't let a TLS/availability hiccup
+        // in the probe stop us — we only care whether something is answering.
+        tls: { rejectUnauthorized: false },
+    })
+        .then((r) => r.ok)
+        .catch(() => false);
+    if (up) {
+        console.log(`Haltija dev-channel: reusing existing server at ${base}`);
+        return;
+    }
+    console.log(`Haltija dev-channel: starting server-only channel (HTTP 8700 + HTTPS ${port}) …`);
+    try {
+        // --server = channel server only (no Electron desktop app). --both = HTTP on
+        // 8700 AND HTTPS on 8701: the injected loader/widget use HTTPS 8701 (so an
+        // 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'], {
+            stdout: 'ignore',
+            stderr: 'ignore',
+        });
+        console.log(`Haltija dev-channel ready — drive this page with \`hj\` (e.g. \`hj tree\`). ` +
+            `The widget appears when the channel is active (Option+Tab to toggle).`);
+    }
+    catch (err) {
+        console.warn(`Haltija dev-channel: could not start (${String(err)}). The page loader ` +
+            `will no-op until you run \`bunx haltija --server --https\` yourself.`);
+    }
+}
 // The HTTPS dev server needs a cert in tls/. On a fresh clone/adopter there
 // isn't one, so warn with the exact command rather than serving a broken
 // server. We don't generate it automatically because it runs `mkcert -install`,
@@ -42,6 +84,18 @@ export async function devServer(config, opts = {}) {
     const PUBLIC = path.resolve('./', config.outputDir ?? 'docs');
     const isSPA = true;
     const testMode = !!opts.test;
+    // Haltija dev-channel — give a coding agent eyes on the running page. Opt-in
+    // (config.haltijaDev or HALTIJA_DEV=1), never in test mode. The loader is a
+    // 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.
+    const HALTIJA_HTTPS_PORT = 8701;
+    const haltijaDev = !testMode &&
+        (config.haltijaDev === true ||
+            process.env.HALTIJA_DEV === '1' ||
+            process.env.HALTIJA_DEV === 'true');
+    const HALTIJA_SNIPPET = `<script>/^localhost$|^127\\./.test(location.hostname)` +
+        `&&import('https://localhost:${HALTIJA_HTTPS_PORT}/dev.js')</script>`;
     let testReportResolve;
     // Source read/write for in-browser "edit page source" (config.editableSources).
     // Local dev only — your machine, your files — so the lone guard is correctness:
@@ -91,7 +145,7 @@ export async function devServer(config, opts = {}) {
         }
     }
     await killStrayServer(PORT);
-    function serveFromDir(cfg) {
+    function resolveFile(cfg) {
         const basePath = path.join(cfg.directory, cfg.path);
         const suffixes = ['', '.html', 'index.html'];
         for (const suffix of suffixes) {
@@ -99,7 +153,7 @@ export async function devServer(config, opts = {}) {
                 const pathWithSuffix = path.join(basePath, suffix);
                 const stat = statSync(pathWithSuffix);
                 if (stat && stat.isFile()) {
-                    return new Response(Bun.file(pathWithSuffix));
+                    return pathWithSuffix;
                 }
             }
             catch {
@@ -108,6 +162,21 @@ export async function devServer(config, opts = {}) {
         }
         return null;
     }
+    // Serve a resolved file, injecting the haltija dev-channel loader into HTML
+    // pages when enabled. Serve-time only — the loader never touches the built
+    // output on disk, and non-HTML assets are streamed untouched.
+    async function respondFile(filePath) {
+        if (haltijaDev && filePath.endsWith('.html')) {
+            const html = await Bun.file(filePath).text();
+            const injected = html.includes('</body>')
+                ? html.replace('</body>', `${HALTIJA_SNIPPET}</body>`)
+                : html + HALTIJA_SNIPPET;
+            return new Response(injected, {
+                headers: { 'Content-Type': 'text/html; charset=utf-8' },
+            });
+        }
+        return new Response(Bun.file(filePath));
+    }
     async function handleTestReport(request) {
         try {
             const results = await request.json();
@@ -211,22 +280,21 @@ export async function devServer(config, opts = {}) {
             }
             if (reqPath === '/')
                 reqPath = '/index.html';
-            const buildResponse = serveFromDir({ directory: PUBLIC, path: reqPath });
-            if (buildResponse)
-                return buildResponse;
+            const buildFile = resolveFile({ directory: PUBLIC, path: reqPath });
+            if (buildFile)
+                return await respondFile(buildFile);
             if (isSPA) {
-                const spaResponse = serveFromDir({
-                    directory: PUBLIC,
-                    path: '/index.html',
-                });
-                console.log(spaResponse);
-                if (spaResponse)
-                    return spaResponse;
+                const spaFile = resolveFile({ directory: PUBLIC, path: '/index.html' });
+                if (spaFile)
+                    return await respondFile(spaFile);
             }
             return new Response('File not found', { status: 404 });
         },
     });
     console.log(`Listening on https://localhost:${PORT}`);
+    if (haltijaDev) {
+        await ensureHaltijaChannel(HALTIJA_HTTPS_PORT);
+    }
     if (testMode) {
         const testTimeout = 120_000;
         const testResults = new Promise((resolve, reject) => {

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

@@ -16,6 +16,7 @@ import { existsSync, mkdirSync } from 'fs';
 import { gzipSync } from 'zlib';
 import { $ } from 'bun';
 import { extractDocs } from './docs';
+import { checkExamples, formatExampleProblems } from './check-examples';
 import { ensureSections } from './sections';
 import { generateLlmsTxt } from './make-llms-txt';
 import { generateSite } from './generate-site';
@@ -68,6 +69,21 @@ export async function buildSite(config) {
         sectionsDir: config.sectionsDir ?? 'src/docs',
         reExtract: extract,
     });
+    // Fail fast on any live example that can't build — a real syntax/import error,
+    // or illustrative code mistakenly tagged executable (`js`/`ts`/…) instead of
+    // display-only `typescript`. Runs on the whole corpus, so it catches breakage
+    // on pages the browser test never navigates to.
+    if (config.checkExamples !== false) {
+        const corpus = JSON.parse(await Bun.file(DOCS_JSON).text());
+        const problems = await checkExamples(corpus);
+        if (problems.length) {
+            throw new Error(`doc-site build: ${problems.length} live example(s) failed to build:\n\n` +
+                formatExampleProblems(problems) +
+                `\n\nFix the code, or — if a block is illustrative and not meant to run —` +
+                ` tag it with a display-only language like \`typescript\` instead of` +
+                ` \`js\`/\`ts\`. (Disable with checkExamples: false.)`);
+        }
+    }
     // Copy static-asset dirs into the web root.
     const staticDirs = config.staticDirs ?? (existsSync('demo/static') ? ['demo/static'] : ['static']);
     for (const dir of staticDirs) {

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

@@ -143,6 +143,15 @@ export interface SiteConfig {
      * `sort: 'filename'` gives a folder of chapters natural order with no metadata.
      */
     book?: BookManifest;
+    /**
+     * Fail the build when a live example can't transpile — a real syntax/import
+     * error, or illustrative code mistakenly tagged with an executable language
+     * (`js`/`ts`/`tjs`/`test`) instead of the display-only `typescript`. Catches it
+     * at build time, on every page, instead of only when someone opens that page.
+     * Default true; assumes the default `tosijs` / `tosijs-ui` example context —
+     * set false if your examples import from a custom `context` the check can't see.
+     */
+    checkExamples?: boolean;
     /** served web-root output dir, default 'docs' */
     outputDir?: string;
     /** dev-server port, default 8787 */
@@ -156,6 +165,19 @@ export interface SiteConfig {
      * are confined to the repo root as correctness hygiene. Off by default; opt in.
      */
     editableSources?: boolean;
+    /**
+     * Give a coding agent (Claude) eyes + hands on your running dev page via
+     * [haltija](https://github.com/tonioloewald/haltija). When on, the dev server
+     * injects a tiny localhost-gated loader into served HTML — a runtime
+     * `import()` of the local haltija channel's `dev.js` — and spins up (or reuses)
+     * a server-only HTTPS channel on port 8701. Because the loader is pulled from
+     * the local server at runtime, **haltija is never bundled** (zero build bytes)
+     * and self-disables off-localhost, and because injection happens at serve time
+     * it never touches the built output. Local dev only; off by default. Can also
+     * be toggled with `HALTIJA_DEV=1`. Requires mkcert (already needed for the dev
+     * server's HTTPS) so the 8701 cert is trusted with no browser warning.
+     */
+    haltijaDev?: boolean;
 }
 /** Identity helper that gives a site config module full type-checking + IDE help. */
 export declare function defineSiteConfig(config: SiteConfig): SiteConfig;