use <codeblock>, refactor

Author: Tsche

README.md

@@ -1,164 +1,145 @@
-# clangd browser runtime
+# clangd in the browser
 
-This project packages Monaco and the WebAssembly build of clangd as a reusable browser component. It creates an editor only inside the element supplied by the host page; it does not use an iframe, register a service worker, replace page-level DOM, or own Run/output UI.
+This package turns ordinary `<codeblock>` tags into editable, runnable C++ examples. It starts with a small textarea editor, upgrades to Monaco when the main bundle is ready, and runs a WebAssembly build of clangd for code help. Multiple blocks on one page share the same runtime, worker, and clangd download.
 
-## Use the hosted runtime
+## Add a code block
 
-The preferred deployment uses separate origins:
+Copy the complete contents of `dist/` to one public directory, then include one stylesheet and one classic script:
 
-```text
-https://www.example.com/       host page
-https://clangd.example.com/    contents of dist/
+```html
+<link rel="stylesheet" href="./codeblocks.css" />
+<script src="./codeblocks.js"></script>
+
+<codeblock compiler="gsnapshot" args="-std=c++26 -freflection">
+#include &lt;print&gt;
+int main() {
+    std::println("foo {} bar", 42);
+}
+</codeblock>
 ```
 
-The host can be ordinary HTML and JavaScript:
+Angle brackets in source code must use normal HTML escaping, such as `&lt;print&gt;`, because the code is embedded in an HTML document.
 
-```html
-<div class="editor-shell">
-  <textarea id="fallback">int main() { return 0; }</textarea>
-  <div id="monaco-host"></div>
-</div>
-
-<script type="module">
-  const fallback = document.querySelector("#fallback");
-  const host = document.querySelector("#monaco-host");
-  const { createCppEditor } =
-    await import("https://clangd.example.com/editor.js");
-
-  const editor = await createCppEditor({
-    element: host,
-    value: fallback.value,
-    theme: "dark",
-    onStatus(status) {
-      console.log(status);
-    },
-  });
+Add as many `<codeblock>` elements as needed. Tags inserted later are upgraded automatically. Monaco, clangd, and the WebAssembly file are initialized once per page.
 
-  // Capture edits made while Monaco loaded, then swap only the editor nodes.
-  editor.setValue(fallback.value);
-  host.style.visibility = "visible";
-  editor.layout();
-  fallback.remove();
+A block can also contain multiple tabbed sources:
 
-  await editor.clangdReady;
-</script>
+```html
+<codeblock compiler="clang2110" args="-std=c++23" height="360px">
+  <codeblock-tab name="first.cpp">
+int main() { return 1; }
+  </codeblock-tab>
+  <codeblock-tab name="second.cpp">
+int main() { return 2; }
+  </codeblock-tab>
+</codeblock>
 ```
 
-`createCppEditor()` resolves as soon as Monaco is usable. clangd downloads and starts independently; `editor.clangdReady` resolves after the language client connects and rejects if clangd is unavailable. A missing cross-origin-isolation policy affects clangd only; Monaco remains usable.
-
-The returned component API is:
+Each tab keeps its own source. Run compiles the active tab. Use separate `<codeblock>` elements when examples need different compiler settings.
 
-```js
-editor.getValue();
-editor.setValue(source);
-editor.focus();
-editor.layout();
-editor.dispose();
-const unsubscribe = editor.onDidChange((source) => {});
-await editor.clangdReady;
-```
+Supported attributes are:
 
-### Lightweight fallback
+- `compiler`: Compiler Explorer compiler ID, defaulting to `clang2110`.
+- `args`: arguments sent unchanged to Compiler Explorer.
+- `theme`: `auto`, `light`, or `dark`.
+- `debug`: show the basic/full editor and light/dark switches. These are hidden by default.
+- `status`: show the optional user-facing code-help status.
+- `width`: any valid CSS width for the complete block.
+- `height`: any valid CSS height for the editor area, such as `280px`, `40vh`, or `clamp(240px, 50vh, 600px)`.
+- `min-height`: any valid CSS minimum height for the editor area.
 
-The fallback editor is a separate, small public module and does not load Monaco:
+## JavaScript API
 
-```js
-const { createCppFallbackEditor } =
-  await import("https://clangd.example.com/fallback.js");
+`codeblocks.js` creates `globalThis.CodeBlocks` immediately. Its `ready` promise resolves after the module API has loaded:
 
-const fallback = createCppFallbackEditor({
-  element: document.querySelector(".fallback-host"),
-  value: "int main() { return 0; }",
-});
+```html
+<script>
+  CodeBlocks.configure({
+    theme: "dark",
+    editorOptions: {
+      fontSize: 15,
+      wordWrap: "on",
+    },
+    styles: {
+      "editor-height": "360px",
+      "accent": "#7c3aed",
+    },
+  });
 
-fallback.getValue();
-fallback.setValue("int main() { return 1; }");
-fallback.focus();
-const unsubscribe = fallback.onDidChange((source) => {});
-fallback.dispose();
+  CodeBlocks.ready.then(() => {
+    const element = document.querySelector("codeblock");
+    const block = CodeBlocks.get(element);
+    block.setValue("int main() { return 0; }");
+  });
+</script>
 ```
 
-`fallback.js` contains its scoped styles, native textarea overlay, line numbers, scrolling synchronization, and lightweight C++ syntax highlighter. It can also enhance an existing textarea inside the supplied element, preserving source included in the initial HTML.
-
-### ANSI output
+Call `CodeBlocks.configure(options)` before a block is upgraded to set defaults for later blocks. The available options are `theme`, `showDebugControls`, `showStatus`, `compiler`, `args`, `compilerExplorerUrl`, `editorOptions`, `styles`, and `onStatus`.
 
-ANSI SGR rendering is available from the main entry and as a lightweight standalone module:
+`CodeBlocks.get(element)` returns the upgraded block instance. It exposes `getValue`, `setValue`, `getTabs`, `selectTab`, `focus`, `run`, `setTheme`, `dispose`, `onDidChange`, `editorReady`, `monacoReady`, and `clangdReady`. `getValue` and `setValue` act on the active tab. `monacoReady` resolves to the underlying Monaco standalone editor for integrations that need the native editor API.
 
-```js
-const { appendAnsi, ansiToFragment, stripAnsi } =
-  await import("https://clangd.example.com/ansi.js");
+Styling uses CSS custom properties. Common properties include:
 
-appendAnsi(outputElement, compilerOutput);
-appendAnsi(outputElement, stderr, { className: "stderr" });
+```css
+codeblock {
+  width: min(100%, 900px);
+  --codeblocks-editor-height: 360px;
+  --codeblocks-editor-min-height: 120px;
+  --codeblocks-editor-height-mobile: 300px;
+  --codeblocks-accent: #7c3aed;
+  --codeblocks-border: #475569;
+}
 ```
 
-The renderer creates text nodes and styled spans rather than injecting HTML. The same functions are also exported by `editor.js`.
+The editor observes its container and relayouts whenever its width or height changes, including flexbox, grid, responsive, and script-driven resizing.
 
-Status events have a `type` of `monaco-loading`, `monaco-ready`, `clangd-downloading`, `clangd-starting`, `clangd-ready`, or `clangd-error`. Download events also contain `loaded` and, when the server provides it, `total` bytes.
+The lower-level ES module entries remain available as `editor.js`, `fallback.js`, and `ansi.js`.
 
-## Headers
+## Cross-origin isolation
 
-The host document must be cross-origin isolated for clangd's SharedArrayBuffer/pthread build:
+clangd uses WebAssembly threads and therefore requires `crossOriginIsolated === true`. The preferred deployment sends these response headers for the document and same-origin runtime files:
 
-```http
+```text
 Cross-Origin-Opener-Policy: same-origin
 Cross-Origin-Embedder-Policy: require-corp
 ```
 
-The runtime asset server must make its public modules, workers, CSS, and WASM available cross-origin:
-
-```http
-Access-Control-Allow-Origin: *
-Cross-Origin-Resource-Policy: cross-origin
-```
-
-Serve `.wasm` as `application/wasm`. [public/_headers](public/_headers) is an example configuration for static hosts that support Netlify-style header files.
-
-The cross-origin worker bootstrap uses Blob module workers. A restrictive host Content Security Policy therefore needs at least:
-
-```http
-Content-Security-Policy: worker-src blob:; script-src 'self' https://clangd.example.com blob:
-```
-
-Adjust the runtime origin and the rest of the policy for the site. The runtime never registers a service worker or attempts to change the host's COOP/COEP policy. GitHub Pages users need a fronting service capable of setting these headers, or a COI service-worker solution managed by the host site itself.
-
-## Self-host the same package
+The reusable loader does not register a service worker by default. Hosts such as GitHub Pages that cannot set these headers can explicitly opt into the included helper:
 
-Extract the archive without rebuilding:
-
-```bash
-mkdir -p assets/clangd
-tar xf clangd-browser-runtime.tar.gz -C assets/clangd
+```html
+<script
+  src="./codeblocks.js"
+  data-coi-serviceworker="./coi-serviceworker.js"
+></script>
 ```
 
-Then import the exact same distribution from the host origin:
-
-```js
-const { createCppEditor } = await import("/assets/clangd/editor.js");
-```
+That opt-in registers a host-owned service worker and reloads once. Do not use the attribute when the server already sends the headers.
 
-All resource URLs are relative to emitted modules, so the distribution works at the origin root or any directory such as `/assets/clangd/`.
+If assets are hosted on another origin, that origin must allow CORS and send `Cross-Origin-Resource-Policy: cross-origin` or an equivalent policy accepted by the embedding page.
 
-## Build and package
+## Build and test
 
-Normal frontend builds use prebuilt artifacts and never clone or compile LLVM:
+The repository already contains the prebuilt clangd artifacts in `public/wasm`. Front-end changes do not rebuild LLVM or clangd.
 
 ```bash
 pnpm install
 pnpm build
-pnpm pack:runtime
+pnpm demo:origins
 ```
 
-The build produces stable `dist/editor.js`, `dist/fallback.js`, `dist/ansi.js`, `dist/editor.css`, internal chunks in `dist/assets/`, and the complete Emscripten artifact set in `dist/wasm/`. Packaging creates `clangd-browser-runtime.tar.gz`.
+Open `http://localhost:4173/`. The example includes `debug`, so both visual editor and theme switches are shown.
 
-Install an existing artifact directory or archive with:
+Run the browser suite in another terminal:
 
 ```bash
-./scripts/install-clangd-artifacts path/to/clangd-artifacts.tar.gz
+pnpm exec playwright install chromium
+pnpm test:browser
 ```
 
-The input must contain `clangd.js`, `clangd.wasm`, and any other `clangd*` files produced by Emscripten. `build.sh` remains a separate manual reference workflow and is not invoked by `pnpm build` or CI.
+Create a deployable archive with:
 
-## Compiler Explorer Run UI
+```bash
+pnpm pack:runtime
+```
 
-Compilation is intentionally a host concern. The demo keeps an `activeEditor.getValue()` abstraction that initially reads the textarea and later points to Monaco, then sends that source directly to the Compiler Explorer API. This makes Run independent of both Monaco and clangd readiness.
+The output is `clangd-browser-runtime.tar.gz`. It includes the main code-block files, lower-level entries, internal chunks, and prebuilt WebAssembly artifacts.

clangd-browser-runtime.tar.gz

@@ -9,6 +9,7 @@
     "watch": "tsc -w",
     "build": "pnpm run clean && tsc && vite build && node scripts/copy-runtime-assets.mjs",
     "pack:runtime": "pnpm build && bash scripts/package-runtime.sh",
+    "demo:origins": "node scripts/serve-test.mjs",
     "test:browser": "playwright test"
   },
   "devDependencies": {

package.json

@@ -0,0 +1,15 @@
+import { defineConfig } from "@playwright/test";
+
+export default defineConfig({
+  testDir: "tests",
+  timeout: 180_000,
+  expect: { timeout: 20_000 },
+  workers: 1,
+  use: { headless: true },
+  webServer: {
+    command: "pnpm demo:origins",
+    url: "http://localhost:4173",
+    reuseExistingServer: true,
+    timeout: 30_000,
+  },
+});

playwright.config.ts

@@ -0,0 +1,39 @@
+(function () {
+  "use strict";
+
+  var script = document.currentScript;
+  if (!script || !script.src) throw new Error("codeblocks.js requires a script URL");
+  var queuedConfigurations = [];
+  var loadedModule;
+  var api = {
+    configure: function (options) {
+      if (loadedModule) loadedModule.configureCodeBlocks(options);
+      else queuedConfigurations.push(options);
+    },
+  };
+  globalThis.CodeBlocks = api;
+
+  api.ready = (async function () {
+    var serviceWorker = script.getAttribute("data-coi-serviceworker");
+    if (serviceWorker !== null && !globalThis.crossOriginIsolated && "serviceWorker" in navigator) {
+      await navigator.serviceWorker.register(
+        new URL(serviceWorker || "./coi-serviceworker.js", script.src),
+        { scope: "./" },
+      );
+      await navigator.serviceWorker.ready;
+      if (!globalThis.crossOriginIsolated) {
+        location.reload();
+        await new Promise(function () {});
+      }
+    }
+
+    loadedModule = await import(new URL("./codeblocks-module.js", script.src).href);
+    queuedConfigurations.forEach(loadedModule.configureCodeBlocks);
+    api.configure = loadedModule.configureCodeBlocks;
+    api.create = loadedModule.createCodeBlock;
+    api.get = loadedModule.getCodeBlock;
+    api.start = loadedModule.startCodeBlocks;
+    loadedModule.startCodeBlocks();
+    return api;
+  })();
+})();

public/codeblocks.js

@@ -0,0 +1,21 @@
+/* Enabled only when the host opts in with data-coi-serviceworker. */
+self.addEventListener("install", () => self.skipWaiting());
+self.addEventListener("activate", (event) => {
+  event.waitUntil(self.clients.claim());
+});
+self.addEventListener("fetch", (event) => {
+  if (new URL(event.request.url).origin !== self.location.origin) return;
+  if (event.request.cache === "only-if-cached" && event.request.mode !== "same-origin") return;
+  event.respondWith((async () => {
+    const response = await fetch(event.request);
+    if (response.status === 0) return response;
+    const headers = new Headers(response.headers);
+    headers.set("Cross-Origin-Embedder-Policy", "require-corp");
+    headers.set("Cross-Origin-Opener-Policy", "same-origin");
+    return new Response(response.body, {
+      status: response.status,
+      statusText: response.statusText,
+      headers,
+    });
+  })());
+});