bc-atlas 0.10.0 → 0.11.0

package/CHANGELOG.md

@@ -4,6 +4,49 @@ All notable changes to BC Atlas will be documented here. The format is based on
 [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and the project
 follows [Semantic Versioning](https://semver.org/).
 
+## 0.11.0 - 2026-10-29
+
+### Changed
+
+- Dependency explorer: without an architecture, objects are colored and
+  grouped by their relation clusters (the clustering of the architecture
+  proposal) instead of one color per app. Clusters float like galaxies
+  around their app candidate and their app, clusters of one app candidate
+  share a family of colors, each cluster shows its name at its center, links
+  inside a cluster take its color, and links between groups are faint arcs.
+  Labels that would overlap a more important one are hidden. On a dark
+  background the graph glows (**Glow** turns it off); dense graphs get
+  fainter links and less glow.
+- Dependency explorer: a **Clusters** filter lists the clusters by app
+  candidate; **only** shows one cluster (or one app) and frames it, and so
+  does a click on a cluster name in the graph or in the legend, which lists
+  the largest clusters on screen. A second click or `Esc` shows all again.
+  Neighbors in other clusters stay visible in gray.
+- Dependency explorer: the glow fades when you zoom in close, so large
+  spheres no longer bloom into white discs.
+- The graph document (`bca export --view explorer --format json`) carries
+  the clusters: `clusters` with name, size, and app candidate, and `cluster`
+  on every workspace object.
+- Clustering by relations is about twice as fast (4.5 instead of 9 seconds for
+  the Base Application) with the same result, and the explorer and the
+  architecture proposal share it: after a saved file, only the apps and
+  modules whose objects or relations changed are clustered again.
+- The explorer's browser bundle (3d-force-graph with three.js and its bloom
+  pass) is built into `vendor/graph-viewer.js` (`npm run update:graph-vendor`);
+  3d-force-graph is no longer installed with the package.
+
+### Fixed
+
+- `bca docs set` and `unset` understand Microsoft's tags: `[SCENARIO 218101]`
+  and `[FEATURE] [A] [B]` are edited in place (the work item stays, one
+  feature of a list can be removed), setting `SCENARIO` again replaces the
+  line instead of adding a second one, and a value with a line break is
+  rejected instead of being written as AL code. Removing a feature that is
+  set for the whole codeunit says to change it in `OnRun`.
+- Markdown guides and test cases show the author's text as written: `<Posted>`,
+  `<b>`, `*now*`, `_done_`, and `|` are escaped instead of disappearing or
+  turning into formatting.
+
 ## 0.10.0 - 2026-10-29
 
 The npm package skips 0.9.0 so it shares its version with the VS Code

package/README.md

@@ -44,7 +44,7 @@ In VS Code, install the **BC Atlas** extension and open an AL project:
 | **Export** | `bca export` | Everything the extension shows, as files: the BC Atlas pages as one offline HTML file to share (default), the Markdown report ([example](./examples/report/README.md)), the 3D explorer, one Markdown page per object, any of ten diagram views as D2, SVG, PNG, PDF, or JSON, with `--watch`. |
 | | `bca docs` | User guides and test cases from AL UI tests (`[SCENARIO]`, `[GIVEN]`, `[WHEN]`, `[THEN]`) as Markdown, HTML, DITA 1.3, or Azure DevOps CSV, with real captions and translations, a flow diagram per scenario, and BPMN 2.0 processes per use case. [Example](./examples/docs/index.md) |
 | **Integrate** | `bca run` | One entry point for Git hooks, schedules, and pipelines; verifies, stages, or publishes generated files. Also available as a [GitHub Action](./docs/automation-and-ci.md#github-actions). |
-| | `bca update` | "BC Atlas 0.11.0 is available": release notes, one-step update, and regenerated hooks, tasks, and pipelines. Dependabot pull requests on request. |
+| | `bca update` | "BC Atlas 0.12.0 is available": release notes, one-step update, and regenerated hooks, tasks, and pipelines. Dependabot pull requests on request. |
 | | `bca mcp` | A Model Context Protocol server for AI agents; `bca help --format json` is the versioned command contract. |
 
 Run `bca` for the same overview in your terminal and `bca help <command>` for

package/THIRD_PARTY_NOTICES.md

@@ -28,8 +28,9 @@ executable for PNG and PDF output.
 authors. Both licensed under the MIT License. Sources:
 <https://github.com/vasturiano/3d-force-graph>, <https://github.com/mrdoob/three.js>
 
-The 3d-force-graph browser bundle, which includes three.js, is embedded in the
-explorer HTML files written by `bca export` and shown by the VS Code extension.
+A browser bundle of 3d-force-graph and three.js (including its bloom pass),
+`vendor/graph-viewer.js`, is embedded in the explorer HTML files written by
+`bca export` and shown by the VS Code extension.
 
 ## graphology
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "bc-atlas",
-  "version": "0.10.0",
+  "version": "0.11.0",
   "description": "BC Atlas maps Microsoft Dynamics 365 Business Central AL projects: architecture diagrams, health checks, reports, and documentation generated from source.",
   "homepage": "https://github.com/SchulzOli/BC-Atlas#readme",
   "bugs": {
@@ -37,7 +37,8 @@
     "site:dev": "vitepress dev website",
     "site:build": "vitepress build website && node ./scripts/site-assets.js",
     "site:preview": "vitepress preview website",
-    "version:set": "node ./scripts/set-version.js"
+    "version:set": "node ./scripts/set-version.js",
+    "update:graph-vendor": "node ./scripts/build-graph-vendor.js"
   },
   "keywords": [
     "al",
@@ -62,7 +63,6 @@
   "dependencies": {
     "@modelcontextprotocol/server": "^2.4.0",
     "@terrastruct/d2": "^0.1.33",
-    "3d-force-graph": "^1.80.0",
     "fflate": "^0.8.3",
     "graphology": "^0.26.0",
     "graphology-communities-louvain": "^2.0.2",
@@ -71,8 +71,11 @@
     "zod": "^4.6.7"
   },
   "devDependencies": {
+    "3d-force-graph": "^1.80.0",
     "@modelcontextprotocol/client": "^2.4.0",
     "bpmn-moddle": "^10.3.1",
+    "esbuild": "^0.28.2",
+    "three": "^0.186.1",
     "vitepress": "2.0.0-alpha.20"
   }
 }

package/src/blueprint/cluster.js

@@ -13,6 +13,7 @@
 //   4. the same relations at a coarser resolution say which components
 //      belong together in one app: each component goes to the app candidate
 //      most of its objects land in, so apps always hold whole components
+import { createHash } from "node:crypto";
 import Graph from "graphology";
 import louvain from "graphology-communities-louvain";
 import { coupling } from "../graph/coupling.js";
@@ -51,7 +52,8 @@ function seededRandom(seed) {
   };
 }
 
-function louvainOn(nodes, edges, resolution = 1, seed = 7) {
+/** The coupling graph for Louvain, merged per pair of objects, without self-loops. */
+function couplingGraph(nodes, edges) {
   const graph = new Graph({ type: "undirected", allowSelfLoops: false });
   for (const id of nodes) graph.addNode(id);
   for (const { source, target, weight } of edges) {
@@ -59,62 +61,101 @@ function louvainOn(nodes, edges, resolution = 1, seed = 7) {
     if (graph.hasEdge(source, target)) graph.updateEdgeAttribute(source, target, "weight", (value) => value + weight);
     else graph.addEdge(source, target, { weight });
   }
-  return graph.size ? louvain(graph, { getEdgeWeight: "weight", rng: seededRandom(seed), resolution }) : {};
+  return graph;
 }
 
-/** Undirected weighted adjacency without self-loops. */
+/**
+ * The same graph as compact arrays (compressed sparse rows) for refining and
+ * scoring: objects in sorted order, and per object its neighbors and weights.
+ */
 function adjacency(nodes, edges) {
-  const neighbors = new Map([...nodes].map((id) => [id, new Map()]));
+  const order = [...nodes].sort();
+  const index = new Map(order.map((id, position) => [id, position]));
+  const lists = order.map(() => new Map());
   for (const { source, target, weight } of edges) {
-    if (!neighbors.has(source) || !neighbors.has(target) || source === target || !weight) continue;
-    neighbors.get(source).set(target, (neighbors.get(source).get(target) ?? 0) + weight);
-    neighbors.get(target).set(source, (neighbors.get(target).get(source) ?? 0) + weight);
+    const from = index.get(source);
+    const to = index.get(target);
+    if (from === undefined || to === undefined || from === to || !weight) continue;
+    lists[from].set(to, (lists[from].get(to) ?? 0) + weight);
+    lists[to].set(from, (lists[to].get(from) ?? 0) + weight);
   }
-  return neighbors;
-}
-
-function modularity(neighbors, partition, resolution) {
+  const offsets = new Int32Array(order.length + 1);
+  for (let node = 0; node < order.length; node++) offsets[node + 1] = offsets[node] + lists[node].size;
+  const neighbors = new Int32Array(offsets[order.length]);
+  const weights = new Float64Array(offsets[order.length]);
+  const strength = new Float64Array(order.length);
   let total = 0;
-  const inside = new Map();
-  const degree = new Map();
-  for (const [id, links] of neighbors) {
-    const community = partition.get(id);
-    for (const [other, weight] of links) {
-      total += weight;
-      degree.set(community, (degree.get(community) ?? 0) + weight);
-      if (partition.get(other) === community) inside.set(community, (inside.get(community) ?? 0) + weight);
+  for (let node = 0; node < order.length; node++) {
+    let position = offsets[node];
+    for (const [other, weight] of lists[node]) {
+      neighbors[position] = other;
+      weights[position++] = weight;
+      strength[node] += weight;
     }
+    total += strength[node];
   }
+  return { order, index, offsets, neighbors, weights, strength, total };
+}
+
+/** Partition labels as consecutive integers, ordered like the labels themselves (ties break the same way). */
+function numbered(labels) {
+  const distinct = [...new Set(labels)].sort();
+  const number = new Map(distinct.map((label, position) => [label, position]));
+  return { partition: Int32Array.from(labels, (label) => number.get(label)), count: distinct.length };
+}
+
+function modularity({ offsets, neighbors, weights, strength, total }, partition, count, resolution) {
   if (!total) return 0;
+  const inside = new Float64Array(count);
+  const degree = new Float64Array(count);
+  for (let node = 0; node < partition.length; node++) {
+    const community = partition[node];
+    degree[community] += strength[node];
+    for (let position = offsets[node]; position < offsets[node + 1]; position++) {
+      if (partition[neighbors[position]] === community) inside[community] += weights[position];
+    }
+  }
   let score = 0;
-  for (const [community, sum] of degree) score += (inside.get(community) ?? 0) / total - resolution * (sum / total) ** 2;
+  for (let community = 0; community < count; community++) score += inside[community] / total - resolution * (degree[community] / total) ** 2;
   return score;
 }
 
 /** Moves single objects to the neighboring community that raises modularity most, until none does. */
-function refine(neighbors, start, resolution) {
-  const partition = new Map(start);
-  const strength = new Map([...neighbors].map(([id, links]) => [id, [...links.values()].reduce((sum, weight) => sum + weight, 0)]));
-  const total = [...strength.values()].reduce((sum, value) => sum + value, 0);
+function refine({ offsets, neighbors, weights, strength, total }, start, count, resolution) {
+  const partition = Int32Array.from(start);
   if (!total) return partition;
-  const sums = new Map();
-  for (const [id, community] of partition) sums.set(community, (sums.get(community) ?? 0) + strength.get(id));
-  const order = [...neighbors.keys()].sort();
+  const sums = new Float64Array(count);
+  for (let node = 0; node < partition.length; node++) sums[partition[node]] += strength[node];
+  const links = new Float64Array(count);
+  const touched = [];
   for (let pass = 0; pass < 20; pass++) {
     let moved = false;
-    for (const id of order) {
-      const own = partition.get(id);
-      const degree = strength.get(id);
+    for (let node = 0; node < partition.length; node++) {
+      const degree = strength[node];
       if (!degree) continue;
-      const links = new Map();
-      for (const [other, weight] of neighbors.get(id)) links.set(partition.get(other), (links.get(partition.get(other)) ?? 0) + weight);
-      sums.set(own, sums.get(own) - degree);
-      const gain = (community) => (links.get(community) ?? 0) - resolution * (sums.get(community) ?? 0) * degree / total;
+      const own = partition[node];
+      for (let position = offsets[node]; position < offsets[node + 1]; position++) {
+        const community = partition[neighbors[position]];
+        if (!links[community]) touched.push(community);
+        links[community] += weights[position];
+      }
+      sums[own] -= degree;
+      const gain = (community) => links[community] - resolution * sums[community] * degree / total;
       let best = own;
-      for (const community of [...links.keys()].sort()) if (gain(community) > gain(best) + 1e-9) best = community;
-      sums.set(best, (sums.get(best) ?? 0) + degree);
+      let bestGain = gain(own);
+      touched.sort((a, b) => a - b);
+      for (const community of touched) {
+        const value = gain(community);
+        if (value > bestGain + 1e-9) {
+          best = community;
+          bestGain = value;
+        }
+      }
+      sums[best] += degree;
+      for (const community of touched) links[community] = 0;
+      touched.length = 0;
       if (best !== own) {
-        partition.set(id, best);
+        partition[node] = best;
         moved = true;
       }
     }
@@ -130,18 +171,20 @@ function refine(neighbors, start, resolution) {
  * relations confirm it.
  */
 function communities(nodes, edges, { resolution = 1, candidates = [] } = {}) {
-  const neighbors = adjacency(nodes, edges);
+  const csr = adjacency(nodes, edges);
+  const graph = couplingGraph(nodes, edges);
   const starts = [];
   for (const seed of [7, 11, 13, 17, 19]) {
-    const result = louvainOn(nodes, edges, resolution, seed);
-    starts.push(new Map([...nodes].map((id) => [id, result[id] === undefined ? `s${id}` : `l${result[id]}`])));
+    const result = graph.size ? louvain(graph, { getEdgeWeight: "weight", rng: seededRandom(seed), resolution }) : {};
+    starts.push(csr.order.map((id) => result[id] === undefined ? `s${id}` : `l${result[id]}`));
   }
-  for (const read of candidates) starts.push(new Map([...nodes].map((id) => [id, read(id) === undefined ? `s${id}` : `k${read(id)}`])));
+  for (const read of candidates) starts.push(csr.order.map((id) => read(id) === undefined ? `s${id}` : `k${read(id)}`));
   let best;
   let bestScore = -Infinity;
-  for (const start of starts) {
-    const partition = refine(neighbors, start, resolution);
-    const score = modularity(neighbors, partition, resolution);
+  for (const labels of starts) {
+    const { partition: start, count } = numbered(labels);
+    const partition = refine(csr, start, count, resolution);
+    const score = modularity(csr, partition, count, resolution);
     if (score > bestScore + 1e-9) {
       best = partition;
       bestScore = score;
@@ -149,7 +192,9 @@ function communities(nodes, edges, { resolution = 1, candidates = [] } = {}) {
   }
   // Objects without coupling stay unassigned; the callers place them.
   const result = {};
-  for (const [id, community] of best ?? []) if (neighbors.get(id).size) result[id] = community;
+  if (best) csr.order.forEach((id, node) => {
+    if (csr.offsets[node + 1] > csr.offsets[node]) result[id] = best[node];
+  });
   return result;
 }
 
@@ -233,15 +278,44 @@ const APP_RESOLUTION = 0.3;
  * Clusters the objects of one app or module by coupling.
  * @returns Map of object id to { key, shared?, label, fullName, alternatives, app: { key, label, fullName } }
  */
+// The explorer and the architecture proposal cluster the same apps, and after
+// a saved file most apps and modules are unchanged: results are kept by a
+// fingerprint of everything they depend on.
+const clusterCache = new Map();
+const CLUSTER_CACHE_SIZE = 64;
+
 export function clusterByRelations(nodes, levels, weights, { prefix = "" } = {}) {
   const ids = new Set(nodes.map(({ id }) => id));
-  const byId = new Map(nodes.map((node) => [node.id, node]));
   const edges = [];
   for (const edge of levels.object.edges) {
     if (!ids.has(edge.source) || !ids.has(edge.target) || edge.source === edge.target || !shapes(edge)) continue;
     const weight = coupling(edge.kinds, weights);
     if (weight) edges.push({ source: edge.source, target: edge.target, weight });
   }
+  const fingerprint = createHash("sha1");
+  for (const { id, label, namespace, file, objectId } of nodes) fingerprint.update(`\u0000${id}\u0001${label}\u0001${namespace}\u0001${file}\u0001${objectId}`);
+  for (const { source, target, weight } of edges) fingerprint.update(`\u0002${source}\u0001${target}\u0001${weight}`);
+  const key = fingerprint.digest("hex");
+  let result = clusterCache.get(key);
+  if (result) clusterCache.delete(key);
+  else result = clusterFresh(nodes, edges);
+  clusterCache.set(key, result);
+  if (clusterCache.size > CLUSTER_CACHE_SIZE) clusterCache.delete(clusterCache.keys().next().value);
+  if (!prefix) return result;
+  // Keys are local to the call; the caller's prefix makes them unique across apps.
+  const apps = new Map();
+  const prefixed = new Map();
+  for (const [id, cluster] of result) {
+    if (!apps.has(cluster.app)) apps.set(cluster.app, { ...cluster.app, key: `${prefix}${cluster.app.key}` });
+    prefixed.set(id, { ...cluster, key: `${prefix}${cluster.key}`, app: apps.get(cluster.app) });
+  }
+  return prefixed;
+}
+
+function clusterFresh(nodes, edges) {
+  const prefix = "";
+  const ids = new Set(nodes.map(({ id }) => id));
+  const byId = new Map(nodes.map((node) => [node.id, node]));
 
   // Today's namespaces and functional folders compete with Louvain; the relations decide.
   const candidates = [

package/src/docs/al-ui-source.js

@@ -87,7 +87,7 @@ const TEST_KINDS = new Set(["UI", "UT"]);
  * One tag comment: "[SCENARIO 218101] Text" (Microsoft's work item number),
  * "[WHEN]/[THEN] Text", "[GIVEN] [SETUP] Text", "[FEATURE] [Sales] [Invoice]".
  */
-function tagLine(text) {
+export function tagLine(text) {
   const head = text.match(/^\[([A-Z][A-Z-]*)(?:\s+([^\]]*?))?\](?:\/\[([A-Z][A-Z-]*)\])?\s*(.*)$/u);
   if (!head) return undefined;
   let rest = head[4];

package/src/docs/al-ui-writer.js

@@ -1,7 +1,7 @@
 import { createHash } from "node:crypto";
 import fs from "node:fs/promises";
 import path from "node:path";
-import { parseAlUiTest } from "./al-ui-source.js";
+import { parseAlUiTest, tagLine } from "./al-ui-source.js";
 import { loadCorpus, validateCorpus } from "./model.js";
 import { canonicalTag, DOCUMENTATION_TAGS, PREREQUISITE_TYPES } from "./tags.js";
 
@@ -9,23 +9,30 @@ function hash(value) {
   return createHash("sha256").update(value).digest("hex");
 }
 
+// Tag comments are read exactly as the documentation reads them, including
+// Microsoft's "[SCENARIO 218101] Text" and "[FEATURE] [Sales] [Invoice]".
 function parsedTagLine(line) {
-  const match = line.match(
-    /^(\s*)\/\/\s*\[([A-Z-]+)\](?:\/\[([A-Z-]+)\])?(?:\s+\[([A-Z-]+)\])?\s*(.*)$/u
-  );
-  if (!match) return undefined;
+  const comment = line.match(/^(\s*)\/\/\s?(.*)$/u);
+  const tagged = comment && tagLine(comment[2].trim());
+  if (!tagged) return undefined;
+  const tag = canonicalTag(tagged.tags[0]) ?? tagged.tags[0];
+  const qualified = tag !== "FEATURE" && /^[A-Z][A-Z-]*$/u.test(tagged.groups[0] ?? "");
+  const rest = tag === "FEATURE" ? [] : tagged.groups.slice(qualified ? 1 : 0).map((group) => `[${group}]`);
   return {
-    indentation: match[1],
-    rawTag: match[2],
-    tag: canonicalTag(match[2]) ?? match[2],
-    qualifier: match[4],
-    value: match[5].trim()
+    indentation: comment[1],
+    rawTag: tagged.tags[0],
+    tag,
+    reference: tagged.reference,
+    qualifier: qualified ? tagged.groups[0] : undefined,
+    // [FEATURE] [A] [B] lists several values on one line.
+    values: tag === "FEATURE" ? [...tagged.groups, ...(tagged.text ? [tagged.text] : [])] : [[...rest, tagged.text].filter(Boolean).join(" ")],
+    groups: tag === "FEATURE" ? tagged.groups : []
   };
 }
 
-function metadataLine(indentation, tag, value, qualifier) {
+function metadataLine(indentation, tag, value, qualifier, reference) {
   const type = qualifier ? ` [${qualifier}]` : "";
-  return `${indentation}// [${tag}]${type} ${value}`;
+  return `${indentation}// [${tag}${reference ? ` ${reference}` : ""}]${type} ${value}`;
 }
 
 function insertionIndex(lines, tag) {
@@ -53,29 +60,44 @@ function editProcedure(segment, options) {
     throw new Error(`unknown prerequisite type: ${options.qualifier}`);
   }
 
-  const matches = lines
+  // A value is one comment line; a line break would turn the rest into AL code.
+  if (/[\r\n]/u.test(options.value ?? "")) throw new Error(`the value of [${canonical}] must be a single line`);
+
+  const sameTag = lines
     .map((line, index) => ({ index, parsed: parsedTagLine(line) }))
-    .filter(({ parsed }) =>
-      parsed?.tag === canonical &&
-      (!options.value || parsed.value === options.value) &&
-      (!options.qualifier || parsed.qualifier === options.qualifier)
-    );
+    .filter(({ parsed }) => parsed?.tag === canonical && (!options.qualifier || parsed.qualifier === options.qualifier));
+  const matches = sameTag.filter(({ parsed }) => !options.value || parsed.values.includes(options.value));
 
   if (options.remove) {
-    if (!matches.length) throw new Error(`[${canonical}] value was not found`);
-    for (const { index } of matches.reverse()) lines.splice(index, 1);
+    if (!matches.length) {
+      const where = options.codeunitTags?.some(({ tag, text }) => canonicalTag(tag) === canonical && (!options.value || text === options.value));
+      throw new Error(where
+        ? `[${canonical}] ${options.value ?? ""} is set for the whole codeunit in its OnRun trigger; change it there`
+        : `[${canonical}] value was not found`);
+    }
+    for (const { index, parsed } of matches.reverse()) {
+      // From a [FEATURE] [A] [B] list, only the named feature goes.
+      const others = options.value && parsed.groups.length ? parsed.groups.filter((group) => group !== options.value) : [];
+      if (others.length) lines[index] = `${parsed.indentation}// [${parsed.rawTag}] ${others.map((group) => `[${group}]`).join(" ")}`;
+      else lines.splice(index, 1);
+    }
     return lines.join(eol);
   }
 
   if (!options.value?.trim()) throw new Error(`--value is required for [${canonical}]`);
   const singleton = DOCUMENTATION_TAGS[canonical].cardinality === "one";
-  if (singleton && matches.length) {
-    const current = matches[0];
+  // A tag that exists once is replaced, whatever its value was.
+  if (singleton && sameTag.length) {
+    const [current, ...continued] = sameTag;
+    // "[SCENARIO 396854] ..." over several lines becomes the one new sentence.
+    for (const { index } of [...continued].reverse()) lines.splice(index, 1);
+    // A work item number ([SCENARIO 218101]) stays with the tag.
     lines[current.index] = metadataLine(
       current.parsed.indentation,
       canonical,
       options.value.trim(),
-      options.qualifier
+      options.qualifier,
+      current.parsed.reference
     );
     return lines.join(eol);
   }
@@ -107,7 +129,9 @@ export async function planMetadataEdit(root, documentId, options) {
   }
   const { start, end } = scenario.value.sourceRange;
   const before = original.slice(start, end);
-  const after = editProcedure(before, options);
+  // Tags the test has without having them itself come from the codeunit's OnRun trigger.
+  const codeunitTags = scenario.value.metadata.map(({ tag, value }) => ({ tag, text: value }));
+  const after = editProcedure(before, { ...options, codeunitTags });
   const content = `${original.slice(0, start)}${after}${original.slice(end)}`;
   const value = await parseAlUiTest(content, scenario.path, scenario.value.procedure);
   const replacement = { ...scenario, fileHash: hash(content), value };

package/src/docs/render/markdown.js

@@ -1,7 +1,7 @@
 import { label, phrase } from "../phrases.js";
 import { inlineStep } from "../steps.js";
 import { humanizeFeature, sameAsTitle } from "../task.js";
-import { escapeMarkdown, markdown as md } from "./format.js";
+import { escapeMarkdown, markdown } from "./format.js";
 
 const LINK_HEADINGS = { next: "heading.next", related: "heading.related", alternative: "heading.alternative" };
 
@@ -9,8 +9,18 @@ function link(target, extension = ".md") {
   return target.exists ? `[${escapeMarkdown(target.title)}](./${target.id}${extension})` : `**${escapeMarkdown(target.id)}**`;
 }
 
+// Tag text is author prose: escape it so `<Posted>`, `*now*` or `a | b` render as written.
+function md(value) {
+  return markdown(value, { escape: true });
+}
+
+// Pipes that md() or escapeMarkdown() already escaped stay as they are.
 function cell(value) {
-  return String(value ?? "").replaceAll("|", "\\|").replace(/\r?\n/gu, " ");
+  return String(value ?? "").replace(/(?<!\\)\|/gu, "\\|").replace(/\r?\n/gu, " ");
+}
+
+function textCell(value) {
+  return cell(escapeMarkdown(value));
 }
 
 function header(task) {
@@ -68,7 +78,7 @@ function flowSection(task, flowImage) {
 /** User guide in the shape of a DITA task: prerequisites, steps, result, links. */
 export function renderGuide(task, { flowImage } = {}) {
   const { language } = task;
-  const lines = [...header(task), `# ${task.title}`, "", md(task.shortdesc), "", ...flowSection(task, flowImage)];
+  const lines = [...header(task), `# ${escapeMarkdown(task.title)}`, "", md(task.shortdesc), "", ...flowSection(task, flowImage)];
   if (task.prereqs.length) {
     lines.push(`## ${label(language, "heading.prereq")}`, "",
       ...task.prereqs.map((item) => `- ${mdTokens(prereqLine(item, language))}`), "");
@@ -84,7 +94,7 @@ export function renderGuide(task, { flowImage } = {}) {
     }
     lines.push("");
   }
-  lines.push(`## ${label(language, "heading.result")}`, "", ...task.result.map((item) => `- ${item}`), "");
+  lines.push(`## ${label(language, "heading.result")}`, "", ...task.result.map((item) => `- ${escapeMarkdown(item)}`), "");
   for (const [kind, heading] of Object.entries(LINK_HEADINGS)) {
     if (task.links[kind].length) {
       lines.push(`## ${label(language, heading)}`, "", ...task.links[kind].map((target) => `- ${link(target)}`), "");
@@ -132,15 +142,15 @@ export function testCaseRows(task) {
 export function renderTestCase(task, { flowImage } = {}) {
   const { language } = task;
   const t = (key, values) => label(language, key, values);
-  const lines = [...header(task), `# ${t("testcase.title", { id: task.id })}: ${task.title}`, ""];
+  const lines = [...header(task), `# ${t("testcase.title", { id: task.id })}: ${escapeMarkdown(task.title)}`, ""];
   lines.push(
     "| | |",
     "| --- | --- |",
     `| ${t("testcase.id")} | \`${task.id}\` |`,
-    `| ${t("testcase.objective")} | ${cell(task.goal)} |`
+    `| ${t("testcase.objective")} | ${textCell(task.goal)} |`
   );
-  if (task.features.length) lines.push(`| ${t("label.use-case")} | ${cell(task.features.map(humanizeFeature).join(", "))} |`);
-  if (task.permissions.length) lines.push(`| ${t("testcase.permissions")} | ${cell(task.permissions.join(", "))} |`);
+  if (task.features.length) lines.push(`| ${t("label.use-case")} | ${textCell(task.features.map(humanizeFeature).join(", "))} |`);
+  if (task.permissions.length) lines.push(`| ${t("testcase.permissions")} | ${textCell(task.permissions.join(", "))} |`);
   lines.push(`| ${t("testcase.source")} | \`${task.source.file}#${task.source.procedure}\` |`, "");
   lines.push(...flowSection(task, flowImage));
 
@@ -159,7 +169,7 @@ export function renderTestCase(task, { flowImage } = {}) {
     "",
     `## ${t("testcase.final")}`,
     "",
-    ...task.result.map((item) => `- ${item}`),
+    ...task.result.map((item) => `- ${escapeMarkdown(item)}`),
     "",
     `## ${t("testcase.signoff")}`,
     "",
@@ -223,11 +233,11 @@ export function renderIndex(catalog, { journeyImage } = {}) {
   if (journeyImage) lines.push(`## ${t("heading.journey")}`, "", `![${t("heading.journey")}](./${journeyImage})`, "");
   if (catalog.byPage.length) {
     lines.push(`## ${t("heading.by-page")}`, "", `| ${t("column.page")} | ${t("column.scenarios")} |`, "| --- | --- |",
-      ...catalog.byPage.map(({ name, tasks }) => `| ${cell(name)} | ${tasks.map(taskLink).join(", ")} |`), "");
+      ...catalog.byPage.map(({ name, tasks }) => `| ${textCell(name)} | ${tasks.map(taskLink).join(", ")} |`), "");
   }
   if (catalog.byPermission.length) {
     lines.push(`## ${t("heading.by-permission")}`, "", `| ${t("column.permission-set")} | ${t("column.scenarios")} |`, "| --- | --- |",
-      ...catalog.byPermission.map(({ name, tasks }) => `| ${cell(name)} | ${tasks.map(taskLink).join(", ")} |`), "");
+      ...catalog.byPermission.map(({ name, tasks }) => `| ${textCell(name)} | ${tasks.map(taskLink).join(", ")} |`), "");
   }
   if (catalog.coverage) {
     const { coverage } = catalog;