rewrite, add tons of output options

Author: Tsche

.github/workflows/checks.yaml

@@ -0,0 +1,31 @@
+name: Checks
+
+on:
+  push:
+    branches: [main, master]
+  pull_request:
+    branches: [main, master]
+
+permissions:
+  contents: read
+
+jobs:
+  checks:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: pnpm/action-setup@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: "22"
+          cache: pnpm
+      - run: pnpm install --frozen-lockfile --ignore-scripts
+      - name: Type and formatting checks
+        run: pnpm lint
+      - name: Unit tests
+        run: pnpm test
+      - name: Build
+        env:
+          GH_TOKEN: ${{ github.token }}
+          RELEASE_REPOSITORY: ${{ github.repository }}
+        run: pnpm prepare

.prettierignore

@@ -0,0 +1,7 @@
+dist
+dist-hosted
+node_modules
+packages
+public/wasm
+pnpm-lock.yaml
+THIRD_PARTY_NOTICES.md

README.md

@@ -1,6 +1,6 @@
 # clangd in the browser
 
-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.
+This package turns ordinary `<codeblock>` tags into editable, runnable examples. It starts with an immediate syntax-highlighted simple editor, upgrades to Monaco when the block approaches the viewport, and runs a WebAssembly build of clangd for C++ code help. Multiple blocks share one VS Code runtime, worker, clangd process, and download.
 
 This project started as a fork of the excellent https://github.com/guyutongxue/clangd-in-browser/.
 
@@ -12,7 +12,7 @@ Copy the complete contents of `dist/` to one public directory, then include one
 <link rel="stylesheet" href="./codeblocks.css" />
 <script src="./codeblocks.js"></script>
 
-<codeblock compiler="gsnapshot" args="-std=c++26 -freflection">
+<codeblock compiler="gsnapshot" compiler-args="-std=c++26 -freflection">
   #include &lt;print&gt; int main() { std::println("foo {} bar", 42); }
 </codeblock>
 ```
@@ -24,25 +24,50 @@ Add as many `<codeblock>` elements as needed. Tags inserted later are upgraded a
 A block can also contain multiple tabbed sources:
 
 ```html
-<codeblock compiler="clang2110" args="-std=c++23" height="360px">
+<codeblock compiler="clang2110" compiler-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>
 ```
 
-Each tab keeps its own source. Run compiles the active tab. Use separate `<codeblock>` elements when examples need different compiler settings.
+Tabs are independent examples by default. Add `multi-file` to send the inactive
+tabs to Compiler Explorer as extra files. A hidden supporting tab implies
+multi-file mode. Use `build-system="cmake"` and a hidden `CMakeLists.txt` tab
+for a CMake request. Switching independent or grouped tabs always clears stale
+output.
 
 Supported attributes are:
 
-- `compiler`: Compiler Explorer compiler ID, defaulting to `clang2110`.
-- `args`: arguments sent unchanged to Compiler Explorer.
+- `language`: editor/simple-mode and Compiler Explorer language, defaulting to `c++`.
+- `compiler`: Compiler Explorer compiler ID. C++ defaults to `clang2110`; languages without an explicit default require this attribute.
+- `compiler-args` (JavaScript: `compiler_args`): arguments sent to the compiler. The old `args` name remains a deprecated alias.
+- `run-args` (JavaScript: `run_args`): arguments passed to the compiled program.
+- `stdin`: standard input passed to the compiled program.
+- `output-views`: comma-separated `execution`, `compiler`, `assembly`, or `tool:TOOL_ID` views. Requesting `execution` controls whether the compiled program runs; assembly is returned by the same compile request.
+- `output-position`: `below`, `side`, or `custom`. Custom suppresses built-in output rendering.
+- `live`: enable live output with a 500 ms debounce, or set the debounce as milliseconds.
+- `readonly`: prevent reader edits. It has no reader-facing toggle.
+- `inline`: transparent, automatically sized, read-only presentation with Monaco/clangd support. The shorter `<cb>code</cb>` tag is equivalent to an inline, read-only `<codeblock>`.
+- `simple`: keep the simple editor/highlighter and never initialize Monaco or clangd. It works on both `<codeblock>` and `<cb>`.
+- `src`: load source from a same-origin or CORS-enabled URL.
+- `range="START[:COLUMN]-END[:COLUMN]"`: show only a source window while compiling the complete file. Columns follow C++ source-range semantics: the start is included and the end is excluded. The equivalent `start-line`, `end-line`, `start-column`, and `end-column` attributes are also available. Ranged views are read-only.
+- `highlight-lines="2-4,7"`: persistently highlight source lines. Line numbers refer to the complete source file and are translated into a visible `range` automatically.
+- `fit`, `fit="height"`, or `fit="width"`: fit the editor to its content in both dimensions or one dimension.
+- `multi-file`: compile the active tab with the remaining tabs as extra files. `build-system="cmake"` uses the CMake API and treats `CMakeLists.txt` as the project source.
+- `editable-options`: show the reader-editable compiler and execution settings, or name a comma-separated subset. Result views are selected by the output tabs; the legacy `output` field is only shown when named explicitly.
+- `hide-toolbar`, `hide-tabs`, `hide-run`, `hide-compiler-explorer`, `hide-info`, and `hide-output`: author-only UI visibility controls. Corresponding `show-*` attributes override configured defaults.
+- `compiler-explorer-link`: replace the generated Compiler Explorer destination with an author-provided URL. JavaScript consumers use `compilerExplorerLinkUrl`.
+- `info-name`, `info-description`, and `source-url`: customize the information popover.
+- `editor-options` and `styles`: JSON objects matching the JavaScript options.
+- `no-render-output`: send results only to the JavaScript callback/API.
 - `ce-url`: Compiler Explorer base URL, defaulting to `https://godbolt.org/`.
 - `ce-language`: language stored in the Compiler Explorer client state, defaulting to `c++`.
 - `ce-compiler`: legacy fallback for the compiler when `compiler` is absent.
-- `ce-options`: legacy fallback for arguments when `args` is absent.
+- `ce-options`: legacy fallback for arguments when `compiler-args` is absent.
+- `ce-libs`, `ce-special-outputs`, `ce-tools`, and `ce-overrides`: JSON values forwarded to Compiler Explorer.
 - `ce-filters`: JSON object overriding Compiler Explorer output filters, such as `'{"intel":false,"demangle":true}'`.
 - `theme`: `auto`, `light`, or `dark`.
-- `debug`: show the basic/full editor and light/dark switches. These are hidden by default.
+- `debug`: log editor and clangd lifecycle details to the console.
 - `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.
@@ -74,24 +99,28 @@ Supported attributes are:
 ```
 
 Call `CodeBlocks.configure(options)` before a block is upgraded to set defaults
-for later blocks. The available options are `theme`, `showDebugControls`,
-`compiler`, `args`, `compilerExplorer`, `editorOptions`, `styles`,
+for later blocks. Configuration includes `theme`, `showDebugControls`,
+`language`, `compiler`, `compiler_args`, `run_args`, `stdin`, `readOnly`,
+`inline`, `simple`, `fit`, `outputViews`, `outputPosition`, `live`, `ui`,
+`editableOptions`, `info`, `compilerExplorer`, `compilerExplorerLinkUrl`, `editorOptions`, `styles`,
 `renderOutput`, `onResult`, and `onStatus`.
 
 The Compiler Explorer link contains the active source, filename, compiler,
 arguments, execution view, and output filters in its `/clientstate/` URL. No
 upload or short-link request is needed. Additional client-state fields can be
 configured globally or when creating an individual block. The nested
 `compiler` and `options` values are fallbacks; the code box's top-level
-`compiler` and `args` always win so Run and the link cannot diverge:
+`compiler` and `compiler_args` always win so the action and link cannot diverge:
 
 ```js
 CodeBlocks.configure({
+  language: "c++",
+  compiler: "gsnapshot",
+  compiler_args: "-std=c++26 -O2",
+  run_args: "--verbose",
+  stdin: "example input\n",
   compilerExplorer: {
     baseUrl: "https://godbolt.org/",
-    language: "c++",
-    compiler: "gsnapshot",
-    options: "-std=c++26 -O2",
     filters: {
       intel: false,
       demangle: true,
@@ -105,26 +134,57 @@ CodeBlocks.configure({
 });
 ```
 
+The module also exports `listCompilerExplorerLanguages`,
+`listCompilerExplorerCompilers`, `listCompilerExplorerLibraries`, and
+`listCompilerExplorerTools`. Compiler fields use the language-specific endpoint
+to offer current compiler IDs while still accepting custom/private-service IDs.
+`compilerExplorer` and `editorOptions` are passed through as the consumer-facing
+escape hatches for Compiler Explorer filters/tools/libraries and Monaco options.
+
 The legacy `compilerExplorerUrl` JavaScript option remains available as an alias for `compilerExplorer.baseUrl`.
 
 `CodeBlocks.get(element)` returns the upgraded block instance. It exposes
 `getValue`, `setValue`, `getTabs`, `selectTab`, `getCompilerExplorerUrl`,
-`focus`, `compile`, `run`, `setTheme`, `dispose`, `onDidChange`, `editorReady`,
-`monacoReady`, and `clangdReady`. `getValue` and `setValue` act on the active
+`focus`, `compile`, `run`, `setOutputView`, `setEditorMode`, `setTheme`, `dispose`, `onDidChange`, `editorReady`,
+`monacoReady`, `clangdReady`, and `sourceReady`. `getValue` and `setValue` act on the active
 tab. `monacoReady` resolves to the underlying Monaco standalone editor for
 integrations that need the native editor API.
 
+`CodeBlocks.setEditorMode("full" | "simple", root?)` and
+`CodeBlocks.setTheme("auto" | "light" | "dark", root?)` update every existing
+block under a page or container. The Pages examples use these for global
+controls instead of placing editor/theme switches inside every block.
+
 `compile()` is the presentation-independent path: it returns the structured
 Compiler Explorer JSON result, including execution output and assembly. Set
 `renderOutput: false` to suppress the built-in drawer, and use `onResult` to
 observe results produced by either `compile()` or the Run button. The exported
 `compileWithCompilerExplorer(request)` function is available for consumers that
 do not need a code-block UI at all.
 
-Run and the generated Compiler Explorer link resolve one shared compiler,
-language, and argument set. The link enables execution and includes both the
-assembly compiler and an execution/output view using that same compiler ID and
-options.
+The requested output determines the work: an `execution` view runs the program,
+while assembly, diagnostics, and tools use compilation only. Side output is
+height-constrained to the editor and scrolls independently. Compiler diagnostics
+are hidden when a successful compile produced none, and execution output reports
+the process exit code. `outputPosition: "custom"` or `renderOutput: false`
+leaves presentation to `onResult` or the returned `CompilationResult`.
+
+The first source line may be a runline such as
+`// clang2110 -std=c++23 -O2`. The compiler and remaining text become defaults
+unless attributes or JavaScript options override them; the runline is removed
+from the editor, compile request, and Compiler Explorer link.
+
+Source-bearing custom elements in formatted HTML should have a
+`<!-- prettier-ignore -->` comment immediately before the `<codeblock>` node.
+The bundled examples do this so Prettier formats the surrounding page without
+rewriting code text nodes. Runtime extraction also removes the common host-HTML
+indent while retaining indentation inside the source itself.
+
+Blocks outside an 800px viewport margin keep the simple editor until
+they approach the viewport. Set `deferMonaco: false` or add `eager` when an
+off-screen integration must initialize immediately. Simultaneously visible
+blocks need separate Monaco renderers, but they still share the expensive VS
+Code services and clangd process.
 
 Styling uses CSS custom properties. Common properties include:
 
@@ -151,11 +211,10 @@ Debug mode also writes lifecycle messages to the browser console, including Mona
 ></script>
 ```
 
-The lower-level ES module entries remain available as `editor.js`, `fallback.js`,
-and `ansi.js`. The fallback editor is language-agnostic internally; its current
-C++ adapter uses [Microlighter](https://github.com/davatron5000/microlighter),
-which applies an on-demand TextMate grammar through the CSS Custom Highlight
-API while keeping the code DOM as plain text.
+The lower-level ES module entries remain available as `editor.js`, `simple.js`,
+and `ansi.js`. The simple-editor implementation and its language adapter live
+together under `editor/simple/`. [Microlighter](https://github.com/davatron5000/microlighter)
+loads the selected TextMate grammar on demand and keeps the code DOM as plain text.
 
 ## Cross-origin isolation
 
@@ -189,30 +248,45 @@ do not rebuild LLVM or clangd.
 
 ```bash
 pnpm install
-pnpm build
-pnpm demo:origins
+pnpm dev
 ```
 
-Open `http://localhost:4173/`. The example includes `debug`, so both visual editor and theme switches are shown.
+`pnpm dev` performs an initial production-equivalent build, watches source and
+types, and serves the same site published to Pages at `http://localhost:4173/`.
+The complete examples are at `http://localhost:4173/examples/`.
 
-Run the browser suite in another terminal:
+The default checks are fully headless and require no browser:
 
 ```bash
-pnpm exec playwright install chromium
-pnpm test:browser
+pnpm test
+pnpm lint
+pnpm build
 ```
 
+CI runs unit tests, TypeScript, Prettier verification, and the production build
+for pull requests and pushes to `main` or `master`.
+
 The heavyweight LLVM/clangd build recipe and its required source patch live in
 `scripts/clangd/`. Front-end work normally uses released artifacts. To build
 clangd itself, run `scripts/clangd/build.sh`; to install a local artifact set,
 run `scripts/clangd/install-artifacts.sh PATH`.
 
 The TypeScript source is split by responsibility: `codeblocks/` owns UI
 orchestration, `compiler-explorer/` owns the headless API and link state,
-`editor/` contains fallback and Monaco adapters, `languages/` contains small
-syntax adapters, and `clangd/` owns the WebAssembly worker transport. Files at
+`editor/` contains simple, language-highlighting, and Monaco adapters, and
+`clangd/` owns the WebAssembly worker transport. Files at
 the top of `src/` are stable public build entrypoints.
 
+Language support is deliberately layered. The simple highlighter accepts a
+language ID and loads its grammar, Monaco accepts the corresponding model
+language plus consumer options, and Compiler Explorer discovery/compilation is
+language-driven. C and C++ have maintained compiler defaults; other languages
+(including Python) require an explicit compiler or runline until a stable
+project default is chosen. New tools can be requested through `ce-tools` or the
+headless API without coupling them to clangd. Additional WASM language services
+can later be added beside `clangd/` without changing the code-block/Compiler
+Explorer model.
+
 ## npm packages
 
 The release workflow publishes two scoped packages from the same source and version:

package.json

@@ -28,7 +28,7 @@
   },
   "scripts": {
     "clean": "node scripts/build-package.mjs --clean",
-    "dev": "pnpm build",
+    "dev": "node scripts/dev.mjs",
     "watch": "tsc -w",
     "build": "node scripts/build-package.mjs",
     "build:hosted": "node scripts/build-package.mjs --outdir=dist-hosted --without-wasm",
@@ -37,16 +37,22 @@
     "package:npm:hosted": "node scripts/prepare-npm-package.mjs dist-hosted packages/codeblocks-hosted @cppsocial/codeblocks-hosted",
     "pack:runtime": "pnpm build && bash scripts/package-runtime.sh",
     "release:wasm": "bash scripts/clangd/release-wasm.sh",
-    "demo:origins": "node scripts/serve-test.mjs",
-    "test:browser": "playwright test"
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "format": "prettier --write .",
+    "format:check": "prettier --check .",
+    "lint": "tsc --noEmit && prettier --check .",
+    "check": "pnpm lint && pnpm test && pnpm build"
   },
   "devDependencies": {
-    "@playwright/test": "^1.55.0",
     "@types/emscripten": "^1.39.10",
     "@types/node": "~20.12.12",
     "@types/vscode": "~1.89.0",
+    "happy-dom": "^15.11.7",
+    "prettier": "^3.6.2",
     "typescript": "^5.4.5",
-    "vite": "^5.4.8"
+    "vite": "^5.4.8",
+    "vitest": "^2.1.9"
   },
   "dependencies": {
     "@codingame/esbuild-import-meta-url-plugin": "~1.0.2",