speced · marcoscaceres · Apr 23, 2026 · Apr 17, 2026 · Apr 17, 2026 · Apr 17, 2026
diff --git a/examples/basic.built.html b/examples/basic.built.html
@@ -1,4 +1,4 @@
-<!DOCTYPE html>
+<!doctype html>
 <html>
   <head>
     <meta charset="utf-8" />
@@ -70,6 +70,53 @@ <h2>Start your spec!</h2>
         <li>A |variable:DOMString| can be declared like this.</li>
       </ol>
     </section>
+    <section>
+      <h2>WebDriver BiDi Extension for Foo</h2>
+      <p>
+        This section defines the WebDriver BiDi [[WEBDRIVER-BIDI]] protocol
+        commands for the {{Foo}} interface.
+      </p>
+      <section>
+        <h3>The <code>foo.doTheFoo</code> Command</h3>
+        <p>
+          The <dfn cddl-type>FooDoTheFooCommand</dfn> invokes {{Foo/doTheFoo()}}
+          on the remote end. The {^FooDoTheFooParameters/bar^} parameter maps to
+          the {{Foo}}'s {{Foo/bar}} attribute.
+        </p>
+        <pre class="cddl">
+          FooDoTheFooCommand = {
+            method: "foo.doTheFoo",
+            params: FooDoTheFooParameters,
+          }
+
+          FooDoTheFooParameters = {
+            bar: tstr,
+            ? timeout: uint,
+            ? level: FooLevel,
+          }
+
+          FooLevel = "low" / "medium" / "high"
+        </pre>
+        <p>
+          The {^FooDoTheFooParameters/bar^} parameter is required. The
+          {^FooDoTheFooParameters/timeout^} parameter is optional and defaults
+          to 30 seconds. The {^FooLevel^} can be {^FooLevel/"low"^},
+          {^FooLevel/"medium"^}, or {^FooLevel/"high"^}.
+        </p>
+      </section>
+      <section>
+        <h3>The <code>foo.doTheFoo</code> Result</h3>
+        <p>On success, the remote end returns a {^FooDoTheFooResult^}.</p>
+        <pre class="cddl">
+          FooDoTheFooResult = {
+            success: bool,
+            ? message: tstr,
+            ? data: bstr,
+          }
+        </pre>
+      </section>
+    </section>
+    <section id="cddl-index"></section>
     <section id="conformance">
       <p>
         This is required for specifications that contain normative material.

diff --git a/examples/basic.html b/examples/basic.html
@@ -1,4 +1,4 @@
-<!DOCTYPE html>
+<!doctype html>
 <html>
   <head>
     <meta charset="utf-8" />
@@ -70,6 +70,53 @@ <h2>Start your spec!</h2>
         <li>A |variable:DOMString| can be declared like this.</li>
       </ol>
     </section>
+    <section>
+      <h2>WebDriver BiDi Extension for Foo</h2>
+      <p>
+        This section defines the WebDriver BiDi [[WEBDRIVER-BIDI]] protocol
+        commands for the {{Foo}} interface.
+      </p>
+      <section>
+        <h3>The <code>foo.doTheFoo</code> Command</h3>
+        <p>
+          The <dfn cddl-type>FooDoTheFooCommand</dfn> invokes {{Foo/doTheFoo()}}
+          on the remote end. The {^FooDoTheFooParameters/bar^} parameter maps to
+          the {{Foo}}'s {{Foo/bar}} attribute.
+        </p>
+        <pre class="cddl">
+          FooDoTheFooCommand = {
+            method: "foo.doTheFoo",
+            params: FooDoTheFooParameters,
+          }
+
+          FooDoTheFooParameters = {
+            bar: tstr,
+            ? timeout: uint,
+            ? level: FooLevel,
+          }
+
+          FooLevel = "low" / "medium" / "high"
+        </pre>
+        <p>
+          The {^FooDoTheFooParameters/bar^} parameter is required. The
+          {^FooDoTheFooParameters/timeout^} parameter is optional and defaults
+          to 30 seconds. The {^FooLevel^} can be {^FooLevel/"low"^},
+          {^FooLevel/"medium"^}, or {^FooLevel/"high"^}.
+        </p>
+      </section>
+      <section>
+        <h3>The <code>foo.doTheFoo</code> Result</h3>
+        <p>On success, the remote end returns a {^FooDoTheFooResult^}.</p>
+        <pre class="cddl">
+          FooDoTheFooResult = {
+            success: bool,
+            ? message: tstr,
+            ? data: bstr,
+          }
+        </pre>
+      </section>
+    </section>
+    <section id="cddl-index"></section>
     <section id="conformance">
       <p>
         This is required for specifications that contain normative material.

diff --git a/package.json b/package.json
@@ -30,6 +30,7 @@
     "@rollup/plugin-terser": "^1.0.0",
     "@types/pluralize": "0.0.33",
     "boxen": "^8.0.1",
+    "cddlparser": "^0.6.0",
     "chokidar": "^5.0.0",
     "clean-css": "^5.3.3",
     "epipebomb": "^1.0.0",

diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
diff --git a/profiles/w3c.js b/profiles/w3c.js
@@ -29,6 +29,7 @@ const modules = [
   import("../src/core/figures.js"),
   import("../src/core/tables.js"),
   import("../src/core/webidl.js"),
+  import("../src/core/cddl.js"),
   import("../src/core/biblio.js"),
   import("../src/core/link-to-dfn.js"),
   import("../src/core/xref.js"),
@@ -39,6 +40,7 @@ const modules = [
   import("../src/core/sections.js"),
   import("../src/core/fix-headers.js"),
   import("../src/core/webidl-index.js"),
+  import("../src/core/cddl-index.js"),
   import("../src/core/structure.js"),
   import("../src/core/informative.js"),
   import("../src/core/id-headers.js"),

diff --git a/src/core/cddl-index.js b/src/core/cddl-index.js
@@ -0,0 +1,131 @@
+// @ts-check
+/**
+ * Module: core/cddl-index
+ * Constructs a summary of CDDL in the document by
+ * cloning all the generated CDDL nodes and
+ * appending them to a pre element.
+ *
+ * Usage:
+ * Add a <section id="cddl-index"> to the document.
+ * It also supports title elements to generate a header.
+ * Or if a header element is an immediate child, then
+ * that is preferred.
+ */
+export const name = "core/cddl-index";
+import { nonNormativeSelector, renameElement } from "./utils.js";
+
+export function run() {
+  /** @type {HTMLElement | null} */
+  const cddlIndexSec = document.querySelector("section#cddl-index");
+  if (!cddlIndexSec) {
+    return;
+  }
+
+  if (
+    !cddlIndexSec.querySelector(":scope > :is(h2, h3, h4, h5, h6):first-child")
+  ) {
+    const heading = document.createElement("h2");
+    if (cddlIndexSec.title) {
+      heading.textContent = cddlIndexSec.title;
+      cddlIndexSec.removeAttribute("title");
+    } else {
+      heading.textContent = "CDDL Index";
+    }
+    cddlIndexSec.prepend(heading);
+  }
+
+  // Filter out CDDL marked with class="exclude" and in non-normative sections
+  const cddlBlocks = /** @type {HTMLElement[]} */ (
+    Array.from(
+      document.querySelectorAll("pre.cddl:not(.exclude) > code")
+    ).filter(cddl => !cddl.closest(nonNormativeSelector))
+  );
+
+  if (cddlBlocks.length === 0) {
+    const text = "This specification doesn't normatively declare any CDDL.";
+    cddlIndexSec.append(text);
+    return;
+  }
+
+  // Group by module if data-cddl-module is used
+  /** @type {Map<string, HTMLElement[]>} */
+  const modules = new Map();
+  for (const cddlCode of cddlBlocks) {
+    const pre = cddlCode.closest("pre");
+    const moduleName =
+      /** @type {HTMLElement} */ (pre)?.dataset.cddlModule || "";
+    let moduleBlocks = modules.get(moduleName);
+    if (!moduleBlocks) {
+      moduleBlocks = [];
+      modules.set(moduleName, moduleBlocks);
+    }
+    moduleBlocks.push(/** @type {HTMLElement} */ (cddlCode));
+  }
+
+  // Check if we have multiple modules
+  const hasModules =
+    modules.size > 1 || (modules.size === 1 && !modules.has(""));
+
+  if (hasModules) {
+    modules.forEach((blocks, moduleName) => {
+      const section = document.createElement("section");
+      const heading = document.createElement("h3");
+      const displayName = moduleName || "Default";
+      heading.textContent = `Module: ${displayName}`;
+      if (moduleName) {
+        heading.id = `cddl-index-module-${moduleName.toLowerCase().replace(/[^a-z0-9]+/g, "-")}`;
+      }
+      section.append(heading);
+      section.append(createConsolidatedPre(blocks));
+      cddlIndexSec.append(section);
+    });
+  } else {
+    // Single consolidated pre
+    cddlIndexSec.append(createConsolidatedPre(cddlBlocks, "actual-cddl-index"));
+  }
+}
+
+/**
+ * Create a consolidated <pre class="cddl"> from multiple code blocks.
+ * @param {HTMLElement[]} cddlCodes - array of <code> elements inside <pre class="cddl">
+ * @param {string} [id] - optional id (used for the single consolidated index pre)
+ * @returns {HTMLPreElement}
+ */
+function createConsolidatedPre(cddlCodes, id) {
+  const pre = document.createElement("pre");
+  pre.classList.add("cddl", "def", "highlight");
+  if (id) {
+    pre.id = id;
+  }
+
+  const code = document.createElement("code");
+  cddlCodes
+    .map(elem => {
+      const fragment = document.createDocumentFragment();
+      elem.childNodes.forEach(child =>
+        fragment.appendChild(child.cloneNode(true))
+      );
+      return fragment;
+    })
+    .forEach(fragment => {
+      if (code.lastChild) {
+        code.append("\n\n");
+      }
+      code.appendChild(fragment);
+    });
+
+  // Remove duplicate IDs
+  code.querySelectorAll("*[id]").forEach(elem => elem.removeAttribute("id"));
+
+  // Replace dfns with spans so the index doesn't create duplicate definitions
+  code.querySelectorAll("dfn").forEach(dfn => {
+    const span = renameElement(dfn, "span");
+    span.removeAttribute("data-export");
+    for (const attr of [...span.attributes]) {
+      if (attr.name.startsWith("data-dfn")) span.removeAttribute(attr.name);
+    }
+  });
+
+  pre.append(code);
+  return pre;
+}