log more, refactor

Author: Tsche

README.md

@@ -43,7 +43,6 @@ Supported attributes are:
 - `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.
@@ -74,7 +73,7 @@ Supported attributes are:
 </script>
 ```
 
-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`.
+Call `CodeBlocks.configure(options)` before a block is upgraded to set defaults for later blocks. The available options are `theme`, `showDebugControls`, `compiler`, `args`, `compilerExplorerUrl`, `editorOptions`, `styles`, and `onStatus`.
 
 `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.
 
@@ -93,6 +92,16 @@ codeblock {
 
 The editor observes its container and relayouts whenever its width or height changes, including flexbox, grid, responsive, and script-driven resizing.
 
+Debug mode also writes lifecycle messages to the browser console, including Monaco loading/loaded, clangd download progress, clangd starting/loaded/activated, and complete clangd error messages. Add `data-debug` to the loader script to include loader, HTTPS, service-worker, and isolation messages:
+
+```html
+<script
+  src="./codeblocks.js"
+  data-coi-serviceworker="./coi-serviceworker.js"
+  data-debug
+></script>
+```
+
 The lower-level ES module entries remain available as `editor.js`, `fallback.js`, and `ansi.js`.
 
 ## Cross-origin isolation
@@ -115,6 +124,8 @@ The reusable loader does not register a service worker by default. Hosts such as
 
 That opt-in registers a host-owned service worker and reloads once. Do not use the attribute when the server already sends the headers.
 
+WebAssembly threads, service workers, and cross-origin isolation require a secure context. Enable "Enforce HTTPS" for a GitHub Pages custom domain. When the isolation helper is enabled, the loader also redirects non-local HTTP pages to the same HTTPS URL as a fallback. The included `clangd.cpp.social` example redirects before loading its external CSS or JavaScript.
+
 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 test

clangd-browser-runtime.tar.gz

@@ -3,6 +3,24 @@
 
   var script = document.currentScript;
   if (!script || !script.src) throw new Error("codeblocks.js requires a script URL");
+  var debug = script.hasAttribute("data-debug");
+  var serviceWorker = script.getAttribute("data-coi-serviceworker");
+  var localHost = /^(localhost|127(?:\.\d+){3}|\[::1\])$/.test(location.hostname);
+  function log(message) {
+    if (debug) console.info("[CodeBlocks] " + message);
+  }
+  function fail(message, error) {
+    console.error("[CodeBlocks] " + message, error || "");
+  }
+
+  log("Loader started at " + location.href);
+  if (serviceWorker !== null && location.protocol === "http:" && !localHost) {
+    var secureUrl = new URL(location.href);
+    secureUrl.protocol = "https:";
+    log("HTTPS is required for clangd; redirecting to " + secureUrl.href);
+    location.replace(secureUrl.href);
+    return;
+  }
   var queuedConfigurations = [];
   var loadedModule;
   var api = {
@@ -14,26 +32,38 @@
   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 () {});
+    try {
+      if (serviceWorker !== null && !globalThis.crossOriginIsolated) {
+        if (!("serviceWorker" in navigator)) {
+          fail("Service workers are unavailable; clangd cannot enable cross-origin isolation");
+        } else {
+          var workerUrl = new URL(serviceWorker || "./coi-serviceworker.js", script.src);
+          log("Registering isolation service worker at " + workerUrl.href);
+          await navigator.serviceWorker.register(workerUrl, { scope: "./" });
+          await navigator.serviceWorker.ready;
+          log("Isolation service worker activated");
+          if (!globalThis.crossOriginIsolated) {
+            log("Reloading once to enable cross-origin isolation");
+            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;
+      log("Cross-origin isolation: " + globalThis.crossOriginIsolated);
+      loadedModule = await import(new URL("./codeblocks-module.js", script.src).href);
+      log("Code block module loaded");
+      queuedConfigurations.forEach(loadedModule.configureCodeBlocks);
+      api.configure = loadedModule.configureCodeBlocks;
+      api.create = loadedModule.createCodeBlock;
+      api.get = loadedModule.getCodeBlock;
+      api.start = loadedModule.startCodeBlocks;
+      loadedModule.startCodeBlocks();
+      log("Code block scan started");
+      return api;
+    } catch (error) {
+      fail("Loader failed: " + (error instanceof Error ? error.message : String(error)), error);
+      throw error;
+    }
   })();
 })();

public/codeblocks.js

@@ -5,7 +5,11 @@
     <meta name="viewport" content="width=device-width, initial-scale=1.0" />
     <title>C++ code block example</title>
     <link rel="stylesheet" href="./codeblocks.css" />
-    <script src="./codeblocks.js" data-coi-serviceworker="./coi-serviceworker.js"></script>
+    <script
+      src="./codeblocks.js"
+      data-coi-serviceworker="./coi-serviceworker.js"
+      data-debug
+    ></script>
     <style>
       :root { color-scheme: light dark; background: #ffffff; color: #1f2328; font-family: system-ui, sans-serif; }
       body { margin: 0; }

public/index.html

@@ -136,13 +136,6 @@ codeblock,
 .codeblocks-root a:hover { text-decoration: underline; }
 .codeblocks-debug { display: inline-flex; gap: 8px; }
 .codeblocks-debug[hidden] { display: none; }
-.codeblocks-status {
-  margin-left: auto;
-  color: var(--codeblocks-muted);
-  font-size: 12px;
-}
-.codeblocks-status[hidden] { display: none; }
-
 .codeblocks-output {
   border-top: 1px solid var(--codeblocks-border);
   background: var(--codeblocks-output-background);
@@ -175,5 +168,4 @@ codeblock,
 
 @media (max-width: 640px) {
   .codeblocks-editor-shell { height: var(--codeblocks-editor-height-mobile); }
-  .codeblocks-status { flex-basis: 100%; margin-left: 0; }
 }

src/codeblocks.css

@@ -9,7 +9,6 @@ export type CodeBlockTheme = "auto" | "light" | "dark";
 export interface CodeBlocksConfiguration {
   theme?: CodeBlockTheme;
   showDebugControls?: boolean;
-  showStatus?: boolean;
   compiler?: string;
   args?: string;
   compilerExplorerUrl?: string;
@@ -116,12 +115,7 @@ export function createCodeBlock(options: CreateCodeBlockOptions): CodeBlock {
   compilerLink.target = "_blank";
   compilerLink.rel = "noopener";
   compilerLink.textContent = "Open in Compiler Explorer";
-  const status = document.createElement("span");
-  status.className = "codeblocks-status";
-  status.dataset.status = "";
-  status.hidden = !options.showStatus;
-  status.textContent = "Code editor ready";
-  toolbar.append(runButton, debugControls, compilerLink, status);
+  toolbar.append(runButton, debugControls, compilerLink);
 
   const outputDrawer = document.createElement("section");
   outputDrawer.className = "codeblocks-output";
@@ -160,6 +154,7 @@ export function createCodeBlock(options: CreateCodeBlockOptions): CodeBlock {
   let editor: CppEditor | undefined;
   let activeEditor: Pick<CppEditor, "getValue" | "setValue" | "focus"> = fallback;
   let disposed = false;
+  let lastLoggedDownload = -1;
   const changeListeners = new Set<(value: string) => void>();
   let unsubscribeActive = fallback.onDidChange(notifyChange);
 
@@ -185,8 +180,9 @@ export function createCodeBlock(options: CreateCodeBlockOptions): CodeBlock {
   const editorReady = upgradeEditor();
   const monacoReady = editorReady.then((created) => created.getMonacoEditor());
   void editorReady.catch((error: unknown) => {
-    status.textContent = "Basic editor ready";
-    status.title = `Code help is unavailable: ${errorMessage(error)}`;
+    if (options.showDebugControls) {
+      console.error("[CodeBlocks] Editor failed", error);
+    }
     rejectClangd(error);
   });
 
@@ -216,26 +212,25 @@ export function createCodeBlock(options: CreateCodeBlockOptions): CodeBlock {
     activeEditor = created;
     subscribeToActive(created);
     editorToggle.disabled = false;
-    status.textContent = "Code editor ready";
     created.clangdReady.then(resolveClangd, rejectClangd);
     return created;
   }
 
   function reportStatus(event: EditorStatus): void {
-    options.onStatus?.(event);
-    if (event.type === "clangd-downloading") {
-      const percent = event.total
-        ? ` ${Math.round((event.loaded / event.total) * 100)}%`
-        : "";
-      status.textContent = `Preparing code help${percent}`;
-    } else if (event.type === "clangd-starting") {
-      status.textContent = "Preparing code help";
-    } else if (event.type === "clangd-ready") {
-      status.textContent = "Code help ready";
-    } else if (event.type === "clangd-error") {
-      status.textContent = "Code editor ready";
-      status.title = `Code help is unavailable: ${event.error.message}`;
+    if (options.showDebugControls) {
+      if (event.type !== "clangd-downloading") {
+        logStatus(event);
+      } else {
+        const milestone = event.total
+          ? Math.floor((event.loaded / event.total) * 10) * 10
+          : Math.floor(event.loaded / (5 * 1024 * 1024));
+        if (milestone !== lastLoggedDownload) {
+          lastLoggedDownload = milestone;
+          logStatus(event);
+        }
+      }
     }
+    options.onStatus?.(event);
   }
 
   async function run(): Promise<void> {
@@ -400,7 +395,6 @@ function upgradeWithin(root: ParentNode): void {
       element,
       theme: attributeTheme(element) ?? configuration.theme,
       showDebugControls: element.hasAttribute("debug") || configuration.showDebugControls,
-      showStatus: element.hasAttribute("status") || configuration.showStatus,
       compiler: element.getAttribute("compiler") ?? configuration.compiler,
       args: element.getAttribute("args") ?? configuration.args,
     });
@@ -462,6 +456,27 @@ function errorMessage(error: unknown): string {
   return error instanceof Error ? error.message : String(error);
 }
 
+function logStatus(event: EditorStatus): void {
+  if (event.type === "monaco-loading") {
+    console.info("[CodeBlocks] Monaco loading");
+  } else if (event.type === "monaco-ready") {
+    console.info("[CodeBlocks] Monaco loaded");
+  } else if (event.type === "clangd-downloading") {
+    const progress = event.total
+      ? `${Math.round((event.loaded / event.total) * 100)}%`
+      : `${event.loaded} bytes`;
+    console.info(`[CodeBlocks] clangd downloading: ${progress}`);
+  } else if (event.type === "clangd-starting") {
+    console.info("[CodeBlocks] clangd starting");
+  } else if (event.type === "clangd-loaded") {
+    console.info("[CodeBlocks] clangd loaded");
+  } else if (event.type === "clangd-ready") {
+    console.info("[CodeBlocks] clangd activated");
+  } else if (event.type === "clangd-error") {
+    console.error(`[CodeBlocks] clangd error: ${event.error.message}`, event.error);
+  }
+}
+
 interface CompilerLine { text: string }
 interface CompilerResult {
   didExecute: boolean;

src/codeblocks.ts

@@ -6,6 +6,7 @@ export type EditorStatus =
   | { type: "monaco-ready" }
   | { type: "clangd-downloading"; loaded: number; total?: number }
   | { type: "clangd-starting" }
+  | { type: "clangd-loaded" }
   | { type: "clangd-ready" }
   | { type: "clangd-error"; error: Error };
 
@@ -62,6 +63,7 @@ export function startClangd(report: StatusReporter): ClangdWorkerHandle {
       case "ready":
         if (!settled) {
           settled = true;
+          report({ type: "clangd-loaded" });
           resolveReady();
         }
         break;

src/runtime/clangd.ts

@@ -8,7 +8,7 @@ test("the example uses one public script and stylesheet and shows debug controls
   await expect(page.locator(".codeblocks-debug")).toBeVisible();
   await expect(page.locator("[data-theme-toggle]")).toBeVisible();
   await expect(page.locator("[data-editor-toggle]")).toBeVisible();
-  await expect(page.locator("[data-status]")).toBeHidden();
+  await expect(page.locator("[data-status]")).toHaveCount(0);
   await expect(page.locator(".monaco-editor")).toBeVisible({ timeout: 60_000 });
   expect(await page.locator('link[rel="stylesheet"][href]').count()).toBe(1);
   expect(await page.locator('script[src]').count()).toBe(1);
@@ -150,7 +150,9 @@ test("the main API exposes Monaco options, styling, and the editor instance", as
 
 test("code help works under the opt-in isolation service worker", async ({ page }) => {
   const errors: string[] = [];
+  const messages: string[] = [];
   page.on("pageerror", (error) => errors.push(error.message));
+  page.on("console", (message) => messages.push(message.text()));
   await page.goto("http://localhost:4173/", { waitUntil: "domcontentloaded" });
   await expect(page.locator("codeblock")).toHaveClass(/codeblocks-root/);
   expect(await page.evaluate(() => crossOriginIsolated)).toBe(true);
@@ -163,6 +165,12 @@ test("code help works under the opt-in isolation service worker", async ({ page
   });
   await expect(page.locator(".squiggly-error").first()).toBeVisible({ timeout: 30_000 });
   expect(errors).toEqual([]);
+  expect(messages).toEqual(expect.arrayContaining([
+    expect.stringContaining("[CodeBlocks] Monaco loaded"),
+    expect.stringContaining("[CodeBlocks] clangd starting"),
+    expect.stringContaining("[CodeBlocks] clangd loaded"),
+    expect.stringContaining("[CodeBlocks] clangd activated"),
+  ]));
 });
 
 test("overflow widgets are not clipped by the code block", async ({ page }) => {