feat(core/inlines): support [[[SPEC#id]]] for cross-spec section links

profiles/aom.js

@@ -27,6 +27,7 @@ const modules = [
   import("../src/core/biblio.js"),
   import("../src/core/link-to-dfn.js"),
   import("../src/core/data-cite.js"),
+  import("../src/core/xref-headings.js"),
   import("../src/core/render-biblio.js"),
   import("../src/core/contrib.js"),
   import("../src/core/sections.js"),

profiles/dini.js

@@ -27,6 +27,7 @@ const modules = [
   import("../src/core/biblio.js"),
   import("../src/core/link-to-dfn.js"),
   import("../src/core/data-cite.js"),
+  import("../src/core/xref-headings.js"),
   import("../src/core/render-biblio.js"),
   import("../src/core/contrib.js"),
   import("../src/core/sections.js"),

profiles/geonovum.js

@@ -24,6 +24,7 @@ const modules = [
   import("../src/core/biblio.js"),
   import("../src/core/link-to-dfn.js"),
   import("../src/core/data-cite.js"),
+  import("../src/core/xref-headings.js"),
   import("../src/core/render-biblio.js"),
   import("../src/core/contrib.js"),
   import("../src/core/sections.js"),

profiles/w3c.js

@@ -34,6 +34,7 @@ const modules = [
   import("../src/core/link-to-dfn.js"),
   import("../src/core/xref.js"),
   import("../src/core/data-cite.js"),
+  import("../src/core/xref-headings.js"),
   import("../src/core/render-biblio.js"),
   import("../src/core/dfn-index.js"),
   import("../src/core/contrib.js"),

src/core/data-cite.js

@@ -184,11 +184,36 @@ export async function run() {
 
   await updateBiblio([...elems]);
 
+  // Precompute toCiteDetails for each element to capture originalKey for error
+  // messages before toCiteDetails mutates dataset.cite
+  const originalKeys = new Map();
+  const citeDetailsMap = new Map();
   for (const elem of elems) {
-    const originalKey = elem.dataset.cite;
+    originalKeys.set(elem, elem.dataset.cite);
     const citeDetails = toCiteDetails(elem);
+    citeDetailsMap.set(elem, citeDetails);
+  }
+
+  for (const elem of elems) {
+    const originalKey = originalKeys.get(elem);
+    const citeDetails = citeDetailsMap.get(elem);
     const linkProps = await getLinkProps(citeDetails);
     if (linkProps) {
+      // Apply alias text (data-lt) for non-section links only.
+      // [[[SPEC#id|alias]]] elements have both citeFrag and matchedText set;
+      // their alias is handled by core/xref-headings after this module runs.
+      // IDL references use data-lt as a lookup term but already have child
+      // content, so the textContent check prevents corrupting them.
+      if (
+        !(elem.dataset.citeFrag && elem.dataset.matchedText) &&
+        elem.dataset.lt &&
+        elem.dataset.lt !== "the-empty-string" &&
+        elem.textContent === ""
+      ) {
+        elem.textContent = elem.dataset.lt;
+        delete elem.dataset.lt;
+      }
+
       linkElem(elem, linkProps, citeDetails);
     } else {
       const msg = `Couldn't find a match for "${originalKey}"`;

src/core/dfn-index.js

@@ -344,9 +344,12 @@ function collectExternalTerms() {
     if (!elem.dataset.cite) {
       continue;
     }
-    const { cite, citeFrag, xrefType, linkType } = elem.dataset;
+    const { cite, citeFrag, xrefType, linkType, matchedText } = elem.dataset;
+    // [[[SPEC#id]]] section links have both citeFrag and matchedText; skip them.
+    if (citeFrag && matchedText) {
+      continue;
+    }
     if (!(xrefType || linkType || cite.includes("#") || citeFrag)) {
-      // Not a reference to a definition
       continue;
     }
     const uniqueID = elem.href;

src/core/inlines.js

@@ -69,7 +69,7 @@ const inlineCodeRegExp = /(?:`[^`]+`)(?!`)/; // `code`
 const inlineIdlReference = /(?:{{[^}]+\?*}})/; // {{ WebIDLThing }}, {{ WebIDLThing? }}
 const inlineVariable = /\B\|\w[\w\s]*(?:\s*:[\w\s&;"?<>]+\??)?\|\B/; // |var : Type?|
 const inlineCitation = /(?:\[\[(?:!|\\|\?)?[\w.-]+(?:|[^\]]+)?\]\])/; // [[citation]]
-const inlineExpansion = /(?:\[\[\[(?:!|\\|\?)?#?[\w-.]+\]\]\])/; // [[[expand]]]
+const inlineExpansion = /(?:\[\[\[[^\]]+\]\]\])/; // [[[SPEC]]], [[[SPEC#id]]], [[[#id]]], [[[...|text]]], !/?-prefixed
 const inlineAnchor = /(?:\[=[^=]+=\])/; // Inline [= For/link =]
 const inlineElement = /(?:\[\^[^^]+\^\])/; // Inline [^element^]
 const inlineCddlReference = /(?:\{\^[^}^]+\^\})/; // {^cddl-type^}, {^type/key^}
@@ -163,17 +163,65 @@ function inlineRFC2119Matches(matched) {
   return nodeElement;
 }
 
+/**
+ * Validates inline expansion/reference syntax.
+ * Valid forms: [[[#id]]], [[[SPEC]]], [[[SPEC#id]]], [[[SPEC|text]]],
+ * [[[SPEC#id|text]]], [[[#id|text]]]
+ */
+const inlineExpansionPattern =
+  /^(?:!|\\|\?)?(?:#[\w-.]+|[\w-.]+(?:#[\w-.]+)?)(?:\|[^\]]+)?$/;
+
 /**
  * @param {string} matched
- * @return {HTMLElement}
+ * @return {HTMLElement | string}
  */
 function inlineRefMatches(matched) {
   // slices "[[[" at the beginning and "]]]" at the end
-  const ref = matched.slice(3, -3).trim();
-  if (!ref.startsWith("#")) {
-    return html`<a data-cite="${ref}" data-matched-text="${matched}"></a>`;
+  const raw = matched.slice(3, -3).trim();
+  if (!inlineExpansionPattern.test(raw)) {
+    const msg = `Bad syntax: \`${matched}\` is not a valid inline expansion.`;
+    const hint =
+      "See https://github.com/speced/respec/wiki/inlines for valid syntax.";
+    showWarning(msg, name, { hint });
+    return matched;
+  }
+  const pipeIdx = raw.indexOf("|");
+  const linkText = pipeIdx !== -1 ? raw.slice(pipeIdx + 1).trim() : null;
+  const ref = pipeIdx !== -1 ? raw.slice(0, pipeIdx).trim() : raw;
+
+  // Strip !/?/\ prefix (normative/informative/escaped markers)
+  const refWithoutPrefix = ref.replace(/^[!?\\]/, "");
+
+  if (ref.startsWith("\\")) {
+    return `[[[${refWithoutPrefix}]]]`;
+  }
+
+  if (refWithoutPrefix.startsWith("#")) {
+    return linkText
+      ? html`<a href="${refWithoutPrefix}" data-matched-text="${matched}"
+          >${linkText}</a
+        >`
+      : html`<a href="${refWithoutPrefix}" data-matched-text="${matched}"></a>`;
   }
-  return html`<a href="${ref}" data-matched-text="${matched}"></a>`;
+
+  if (refWithoutPrefix.includes("#")) {
+    const [specName, sectionFrag] = refWithoutPrefix.split("#");
+    // Preserve any !/?/\ prefix from ref (e.g. "!SPEC" → "!" + specName)
+    const specPart =
+      ref.slice(0, ref.length - refWithoutPrefix.length) + specName;
+    return html`<a
+      data-cite="${specPart}"
+      data-cite-frag="${sectionFrag}"
+      data-matched-text="${matched}"
+      data-lt="${linkText || null}"
+    ></a>`;
+  }
+
+  return html`<a
+    data-cite="${ref}"
+    data-matched-text="${matched}"
+    data-lt="${linkText || null}"
+  ></a>`;
 }
 
 /**

src/core/xref-headings-db.js

@@ -0,0 +1,94 @@
+// @ts-check
+import { idb } from "./import-maps.js";
+
+/**
+ * @typedef {import("./xref-headings.js").HeadingInfo} HeadingInfo
+ * @typedef {{ query: { spec: string, id: string }, result: HeadingInfo }} HeadingEntry
+ * @typedef {import("idb").DBSchema & { headings: { key: string, value: HeadingEntry } }} HeadingsDb
+ */
+
+const STORE_NAME = "headings";
+const CACHE_MAX_AGE = 24 * 60 * 60 * 1000; // 24 hours
+
+async function getDb() {
+  /** @type {import("idb").IDBPDatabase<HeadingsDb>} */
+  const db = await idb.openDB("respec-headings", 1, {
+    upgrade(db) {
+      [...db.objectStoreNames].forEach(s => db.deleteObjectStore(s));
+      db.createObjectStore(STORE_NAME);
+    },
+  });
+  return db;
+}
+
+/** @param {{ spec: string, id: string }[]} queries */
+export async function resolveHeadingsCache(queries) {
+  /** @type {Map<string, HeadingInfo>} */
+  const cachedData = new Map();
+
+  if (shouldBustCache()) {
+    await clearHeadingsData();
+    return cachedData;
+  }
+
+  try {
+    const db = await getDb();
+    const tx = db.transaction(STORE_NAME);
+    for (const query of queries) {
+      const key = `${query.spec}#${query.id}`;
+      const entry = await tx.store.get(key);
+      if (entry) {
+        cachedData.set(key, entry.result);
+      }
+    }
+  } catch (err) {
+    console.error(err);
+  }
+  return cachedData;
+}
+
+/**
+ * @param {{ spec: string, id: string }[]} queries
+ * @param {Map<string, HeadingInfo>} results
+ */
+export async function cacheHeadingsData(queries, results) {
+  try {
+    const db = await getDb();
+    const tx = db.transaction(STORE_NAME, "readwrite");
+    for (const query of queries) {
+      const key = `${query.spec}#${query.id}`;
+      const result = results.get(key);
+      if (result) {
+        tx.objectStore(STORE_NAME).put({ query, result }, key);
+      }
+    }
+    await tx.done;
+    localStorage.setItem("HEADINGS:LAST_CACHED", Date.now().toString());
+  } catch (e) {
+    console.error(e);
+  }
+}
+
+/**
+ * Returns true when the cached headings data has exceeded CACHE_MAX_AGE and
+ * should be discarded. Returns false when no timestamp exists (cold start).
+ */
+function shouldBustCache() {
+  const lastCached = parseInt(
+    localStorage.getItem("HEADINGS:LAST_CACHED") ?? "",
+    10
+  );
+  if (isNaN(lastCached)) return false;
+  return Date.now() - lastCached > CACHE_MAX_AGE;
+}
+
+/** Clears all cached headings data and removes the last-cached timestamp. */
+export async function clearHeadingsData() {
+  try {
+    const db = await getDb();
+    await db.clear(STORE_NAME);
+    localStorage.removeItem("HEADINGS:LAST_CACHED");
+  } catch (e) {
+    console.error(e);
+  }
+}