npm - docrev - Versions diffs - 0.11.0 → 0.11.1 - Mend

docrev 0.11.0 → 0.11.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (35) hide show

package/CHANGELOG.md +13 -0
package/README.md +2 -0
package/dist/lib/build.d.ts +52 -0
package/dist/lib/build.d.ts.map +1 -1
package/dist/lib/build.js +126 -0
package/dist/lib/build.js.map +1 -1
package/dist/lib/commands/build.d.ts.map +1 -1
package/dist/lib/commands/build.js +34 -12
package/dist/lib/commands/build.js.map +1 -1
package/dist/lib/trackchanges.d.ts +41 -25
package/dist/lib/trackchanges.d.ts.map +1 -1
package/dist/lib/trackchanges.js +90 -151
package/dist/lib/trackchanges.js.map +1 -1
package/dist/lib/types.d.ts +0 -7
package/dist/lib/types.d.ts.map +1 -1
package/docs-src/build.py +113 -113
package/docs-src/extra.css +208 -208
package/docs-src/md-to-html.lua +6 -6
package/docs-src/template.html +116 -116
package/issues.md +180 -0
package/lib/build.ts +186 -0
package/lib/commands/build.ts +37 -12
package/lib/trackchanges.ts +102 -183
package/lib/types.ts +0 -12
package/mkdocs.yml +64 -64
package/package.json +137 -137
package/site/assets/extra.css +208 -0
package/site/commands.html +926 -0
package/site/configuration.html +469 -0
package/site/index.html +288 -0
package/site/troubleshooting.html +461 -0
package/site/workflow.html +518 -0
package/skill/REFERENCE.md +14 -3
package/skill/SKILL.md +12 -5
package/types/index.d.ts +16 -10

package/docs-src/template.html CHANGED Viewed

@@ -1,116 +1,116 @@
-<!DOCTYPE html>
-<html lang="en" data-bs-theme="light">
-<head>
-  <meta charset="utf-8">
-  <meta name="viewport" content="width=device-width, initial-scale=1">
-  <title>$if(pagetitle)$$pagetitle$ — $endif$docrev</title>
-  <meta name="description" content="CLI for writing documents in Markdown while collaborating with Word users.">
-  <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/bootswatch@5.3.3/dist/sandstone/bootstrap.min.css">
-$if(highlighting-css)$
-  <style>
-$highlighting-css$
-  </style>
-$endif$
-  <link rel="stylesheet" href="assets/extra.css">
-</head>
-<body>
-<nav class="navbar navbar-expand-lg fixed-top" aria-label="Site navigation">
-  <div class="container">
-    <a class="navbar-brand me-2" href="index.html">docrev</a>
-    <button class="navbar-toggler" type="button" data-bs-toggle="collapse" data-bs-target="#navbar-main" aria-controls="navbar-main" aria-expanded="false" aria-label="Toggle navigation">
-      <span class="navbar-toggler-icon"></span>
-    </button>
-    <div class="collapse navbar-collapse" id="navbar-main">
-      <ul class="navbar-nav me-auto">
-        <li class="nav-item">
-          <a class="nav-link$if(active-home)$ active$endif$" $if(active-home)$aria-current="page"$endif$ href="index.html">Home</a>
-        </li>
-        <li class="nav-item">
-          <a class="nav-link$if(active-workflow)$ active$endif$" $if(active-workflow)$aria-current="page"$endif$ href="workflow.html">Get Started</a>
-        </li>
-        <li class="nav-item">
-          <a class="nav-link$if(active-commands)$ active$endif$" $if(active-commands)$aria-current="page"$endif$ href="commands.html">Commands</a>
-        </li>
-        <li class="nav-item">
-          <a class="nav-link$if(active-configuration)$ active$endif$" $if(active-configuration)$aria-current="page"$endif$ href="configuration.html">Configuration</a>
-        </li>
-        <li class="nav-item">
-          <a class="nav-link$if(active-troubleshooting)$ active$endif$" $if(active-troubleshooting)$aria-current="page"$endif$ href="troubleshooting.html">Troubleshooting</a>
-        </li>
-      </ul>
-      <ul class="navbar-nav">
-        <li class="nav-item">
-          <button id="theme-toggle" class="btn btn-link nav-link border-0" aria-label="Toggle dark mode">
-            <svg id="icon-sun" xmlns="http://www.w3.org/2000/svg" width="16" height="16" fill="currentColor" viewBox="0 0 16 16">
-              <path d="M8 11a3 3 0 1 1 0-6 3 3 0 0 1 0 6m0 1a4 4 0 1 0 0-8 4 4 0 0 0 0 8M8 0a.5.5 0 0 1 .5.5v2a.5.5 0 0 1-1 0v-2A.5.5 0 0 1 8 0m0 13a.5.5 0 0 1 .5.5v2a.5.5 0 0 1-1 0v-2A.5.5 0 0 1 8 13m8-5a.5.5 0 0 1-.5.5h-2a.5.5 0 0 1 0-1h2a.5.5 0 0 1 .5.5M3 8a.5.5 0 0 1-.5.5h-2a.5.5 0 0 1 0-1h2A.5.5 0 0 1 3 8m10.657-5.657a.5.5 0 0 1 0 .707l-1.414 1.415a.5.5 0 1 1-.707-.708l1.414-1.414a.5.5 0 0 1 .707 0m-9.193 9.193a.5.5 0 0 1 0 .707L3.05 13.657a.5.5 0 0 1-.707-.707l1.414-1.414a.5.5 0 0 1 .707 0m9.193 2.121a.5.5 0 0 1-.707 0l-1.414-1.414a.5.5 0 0 1 .707-.707l1.414 1.414a.5.5 0 0 1 0 .707M4.464 4.465a.5.5 0 0 1-.707 0L2.343 3.05a.5.5 0 1 1 .707-.707l1.414 1.414a.5.5 0 0 1 0 .707"/>
-            </svg>
-            <svg id="icon-moon" xmlns="http://www.w3.org/2000/svg" width="16" height="16" fill="currentColor" viewBox="0 0 16 16" style="display:none">
-              <path d="M6 .278a.768.768 0 0 1 .08.858 7.208 7.208 0 0 0-.878 3.46c0 4.021 3.278 7.277 7.318 7.277.527 0 1.04-.055 1.533-.16a.787.787 0 0 1 .81.316.733.733 0 0 1-.031.893A8.349 8.349 0 0 1 8.344 16C3.734 16 0 12.286 0 7.71 0 4.266 2.114 1.312 5.124.06A.752.752 0 0 1 6 .278"/>
-            </svg>
-          </button>
-        </li>
-        <li class="nav-item">
-          <a class="nav-link" href="https://github.com/gcol33/docrev" aria-label="GitHub">
-            <svg xmlns="http://www.w3.org/2000/svg" width="18" height="18" fill="currentColor" viewBox="0 0 16 16">
-              <path d="M8 0C3.58 0 0 3.58 0 8c0 3.54 2.29 6.53 5.47 7.59.4.07.55-.17.55-.38 0-.19-.01-.82-.01-1.49-2.01.37-2.53-.49-2.69-.94-.09-.23-.48-.94-.82-1.13-.28-.15-.68-.52-.01-.53.63-.01 1.08.58 1.23.82.72 1.21 1.87.87 2.33.66.07-.52.28-.87.51-1.07-1.78-.2-3.64-.89-3.64-3.95 0-.87.31-1.59.82-2.15-.08-.2-.36-1.02.08-2.12 0 0 .67-.21 2.2.82.64-.18 1.32-.27 2-.27.68 0 1.36.09 2 .27 1.53-1.04 2.2-.82 2.2-.82.44 1.1.16 1.92.08 2.12.51.56.82 1.27.82 2.15 0 3.07-1.87 3.75-3.65 3.95.29.25.54.73.54 1.48 0 1.07-.01 1.93-.01 2.2 0 .21.15.46.55.38A8.012 8.012 0 0 0 16 8c0-4.42-3.58-8-8-8"/>
-            </svg>
-          </a>
-        </li>
-        <li class="nav-item">
-          <a class="nav-link" href="https://www.npmjs.com/package/docrev" aria-label="npm">
-            <svg xmlns="http://www.w3.org/2000/svg" width="20" height="20" fill="currentColor" viewBox="0 0 16 16">
-              <path d="M0 0v16h16V0zm5.333 13.333H2.667V5.333h2.666v5.334H8V5.333h2.667v8H5.333z"/>
-            </svg>
-          </a>
-        </li>
-      </ul>
-    </div>
-  </div>
-</nav>
-<div class="container template-$if(active-home)$home$else$article$endif$">
-  <div class="row">
-    <main id="main" class="$if(toc)$col-md-9$else$col-12$endif$">
-      $body$
-    </main>
-$if(toc)$
-    <aside class="col-md-3 d-none d-md-block">
-      <nav id="toc" data-toggle="toc" aria-label="On this page">
-        <h2 class="h6">On this page</h2>
-        <div class="toc">$toc$</div>
-      </nav>
-    </aside>
-$endif$
-  </div>
-</div>
-<footer class="border-top py-3 mt-auto">
-  <div class="container d-flex justify-content-between align-items-center text-muted" style="font-size:.85rem">
-    <span>docrev$if(version)$ $version$$endif$</span>
-    <span>Built with <a href="https://pandoc.org" class="text-muted">pandoc</a></span>
-  </div>
-</footer>
-<script src="https://cdn.jsdelivr.net/npm/bootstrap@5.3.3/dist/js/bootstrap.bundle.min.js"></script>
-<script>
-(function () {
-  var html  = document.documentElement;
-  var sun   = document.getElementById('icon-sun');
-  var moon  = document.getElementById('icon-moon');
-  function apply(t) {
-    html.setAttribute('data-bs-theme', t);
-    sun.style.display  = t === 'dark' ? 'none' : '';
-    moon.style.display = t === 'dark' ? ''     : 'none';
-  }
-  apply(localStorage.getItem('docrev-theme') || 'light');
-  document.getElementById('theme-toggle').addEventListener('click', function () {
-    var next = html.getAttribute('data-bs-theme') === 'dark' ? 'light' : 'dark';
-    localStorage.setItem('docrev-theme', next);
-    apply(next);
-  });
-})();
-</script>
-</body>
-</html>
+<!DOCTYPE html>
+<html lang="en" data-bs-theme="light">
+<head>
+  <meta charset="utf-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1">
+  <title>$if(pagetitle)$$pagetitle$ — $endif$docrev</title>
+  <meta name="description" content="CLI for writing documents in Markdown while collaborating with Word users.">
+  <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/bootswatch@5.3.3/dist/sandstone/bootstrap.min.css">
+$if(highlighting-css)$
+  <style>
+$highlighting-css$
+  </style>
+$endif$
+  <link rel="stylesheet" href="assets/extra.css">
+</head>
+<body>
+<nav class="navbar navbar-expand-lg fixed-top" aria-label="Site navigation">
+  <div class="container">
+    <a class="navbar-brand me-2" href="index.html">docrev</a>
+    <button class="navbar-toggler" type="button" data-bs-toggle="collapse" data-bs-target="#navbar-main" aria-controls="navbar-main" aria-expanded="false" aria-label="Toggle navigation">
+      <span class="navbar-toggler-icon"></span>
+    </button>
+    <div class="collapse navbar-collapse" id="navbar-main">
+      <ul class="navbar-nav me-auto">
+        <li class="nav-item">
+          <a class="nav-link$if(active-home)$ active$endif$" $if(active-home)$aria-current="page"$endif$ href="index.html">Home</a>
+        </li>
+        <li class="nav-item">
+          <a class="nav-link$if(active-workflow)$ active$endif$" $if(active-workflow)$aria-current="page"$endif$ href="workflow.html">Get Started</a>
+        </li>
+        <li class="nav-item">
+          <a class="nav-link$if(active-commands)$ active$endif$" $if(active-commands)$aria-current="page"$endif$ href="commands.html">Commands</a>
+        </li>
+        <li class="nav-item">
+          <a class="nav-link$if(active-configuration)$ active$endif$" $if(active-configuration)$aria-current="page"$endif$ href="configuration.html">Configuration</a>
+        </li>
+        <li class="nav-item">
+          <a class="nav-link$if(active-troubleshooting)$ active$endif$" $if(active-troubleshooting)$aria-current="page"$endif$ href="troubleshooting.html">Troubleshooting</a>
+        </li>
+      </ul>
+      <ul class="navbar-nav">
+        <li class="nav-item">
+          <button id="theme-toggle" class="btn btn-link nav-link border-0" aria-label="Toggle dark mode">
+            <svg id="icon-sun" xmlns="http://www.w3.org/2000/svg" width="16" height="16" fill="currentColor" viewBox="0 0 16 16">
+              <path d="M8 11a3 3 0 1 1 0-6 3 3 0 0 1 0 6m0 1a4 4 0 1 0 0-8 4 4 0 0 0 0 8M8 0a.5.5 0 0 1 .5.5v2a.5.5 0 0 1-1 0v-2A.5.5 0 0 1 8 0m0 13a.5.5 0 0 1 .5.5v2a.5.5 0 0 1-1 0v-2A.5.5 0 0 1 8 13m8-5a.5.5 0 0 1-.5.5h-2a.5.5 0 0 1 0-1h2a.5.5 0 0 1 .5.5M3 8a.5.5 0 0 1-.5.5h-2a.5.5 0 0 1 0-1h2A.5.5 0 0 1 3 8m10.657-5.657a.5.5 0 0 1 0 .707l-1.414 1.415a.5.5 0 1 1-.707-.708l1.414-1.414a.5.5 0 0 1 .707 0m-9.193 9.193a.5.5 0 0 1 0 .707L3.05 13.657a.5.5 0 0 1-.707-.707l1.414-1.414a.5.5 0 0 1 .707 0m9.193 2.121a.5.5 0 0 1-.707 0l-1.414-1.414a.5.5 0 0 1 .707-.707l1.414 1.414a.5.5 0 0 1 0 .707M4.464 4.465a.5.5 0 0 1-.707 0L2.343 3.05a.5.5 0 1 1 .707-.707l1.414 1.414a.5.5 0 0 1 0 .707"/>
+            </svg>
+            <svg id="icon-moon" xmlns="http://www.w3.org/2000/svg" width="16" height="16" fill="currentColor" viewBox="0 0 16 16" style="display:none">
+              <path d="M6 .278a.768.768 0 0 1 .08.858 7.208 7.208 0 0 0-.878 3.46c0 4.021 3.278 7.277 7.318 7.277.527 0 1.04-.055 1.533-.16a.787.787 0 0 1 .81.316.733.733 0 0 1-.031.893A8.349 8.349 0 0 1 8.344 16C3.734 16 0 12.286 0 7.71 0 4.266 2.114 1.312 5.124.06A.752.752 0 0 1 6 .278"/>
+            </svg>
+          </button>
+        </li>
+        <li class="nav-item">
+          <a class="nav-link" href="https://github.com/gcol33/docrev" aria-label="GitHub">
+            <svg xmlns="http://www.w3.org/2000/svg" width="18" height="18" fill="currentColor" viewBox="0 0 16 16">
+              <path d="M8 0C3.58 0 0 3.58 0 8c0 3.54 2.29 6.53 5.47 7.59.4.07.55-.17.55-.38 0-.19-.01-.82-.01-1.49-2.01.37-2.53-.49-2.69-.94-.09-.23-.48-.94-.82-1.13-.28-.15-.68-.52-.01-.53.63-.01 1.08.58 1.23.82.72 1.21 1.87.87 2.33.66.07-.52.28-.87.51-1.07-1.78-.2-3.64-.89-3.64-3.95 0-.87.31-1.59.82-2.15-.08-.2-.36-1.02.08-2.12 0 0 .67-.21 2.2.82.64-.18 1.32-.27 2-.27.68 0 1.36.09 2 .27 1.53-1.04 2.2-.82 2.2-.82.44 1.1.16 1.92.08 2.12.51.56.82 1.27.82 2.15 0 3.07-1.87 3.75-3.65 3.95.29.25.54.73.54 1.48 0 1.07-.01 1.93-.01 2.2 0 .21.15.46.55.38A8.012 8.012 0 0 0 16 8c0-4.42-3.58-8-8-8"/>
+            </svg>
+          </a>
+        </li>
+        <li class="nav-item">
+          <a class="nav-link" href="https://www.npmjs.com/package/docrev" aria-label="npm">
+            <svg xmlns="http://www.w3.org/2000/svg" width="20" height="20" fill="currentColor" viewBox="0 0 16 16">
+              <path d="M0 0v16h16V0zm5.333 13.333H2.667V5.333h2.666v5.334H8V5.333h2.667v8H5.333z"/>
+            </svg>
+          </a>
+        </li>
+      </ul>
+    </div>
+  </div>
+</nav>
+<div class="container template-$if(active-home)$home$else$article$endif$">
+  <div class="row">
+    <main id="main" class="$if(toc)$col-md-9$else$col-12$endif$">
+      $body$
+    </main>
+$if(toc)$
+    <aside class="col-md-3 d-none d-md-block">
+      <nav id="toc" data-toggle="toc" aria-label="On this page">
+        <h2 class="h6">On this page</h2>
+        <div class="toc">$toc$</div>
+      </nav>
+    </aside>
+$endif$
+  </div>
+</div>
+<footer class="border-top py-3 mt-auto">
+  <div class="container d-flex justify-content-between align-items-center text-muted" style="font-size:.85rem">
+    <span>docrev$if(version)$ $version$$endif$</span>
+    <span>Built with <a href="https://pandoc.org" class="text-muted">pandoc</a></span>
+  </div>
+</footer>
+<script src="https://cdn.jsdelivr.net/npm/bootstrap@5.3.3/dist/js/bootstrap.bundle.min.js"></script>
+<script>
+(function () {
+  var html  = document.documentElement;
+  var sun   = document.getElementById('icon-sun');
+  var moon  = document.getElementById('icon-moon');
+  function apply(t) {
+    html.setAttribute('data-bs-theme', t);
+    sun.style.display  = t === 'dark' ? 'none' : '';
+    moon.style.display = t === 'dark' ? ''     : 'none';
+  }
+  apply(localStorage.getItem('docrev-theme') || 'light');
+  document.getElementById('theme-toggle').addEventListener('click', function () {
+    var next = html.getAttribute('data-bs-theme') === 'dark' ? 'light' : 'dark';
+    localStorage.setItem('docrev-theme', next);
+    apply(next);
+  });
+})();
+</script>
+</body>
+</html>

package/issues.md ADDED Viewed

@@ -0,0 +1,180 @@
+# docrev — Open Issues
+Three issues identified during real-world use on the ADAPT proposal build. Working through one by one.
+Status legend: `[ ]` planned · `[~]` in progress · `[x]` shipped
+---
+## Issue 1 — Allow custom pandoc filters / args through `rev build`  `[x]`
+### Problem
+Source markdown with custom raw-LaTeX commands needs a pandoc filter to convert them for docx (e.g. `\tofill{X}` → bold `[X]`). `rev build docx` has no escape hatch:
+- `rev build --help` exposes no `--filter` / `--lua-filter` / `--pandoc-arg`.
+- `rev.yaml` exposes `docx.reference` and `docx.keepComments` but no generic pandoc passthrough.
+Working around it requires letting `rev build` produce `paper.md` as a side effect, then calling pandoc manually — which defeats the point of `rev build`.
+### Design (agreed)
+**rev.yaml**: top-level `pandoc-args` (applied to every format) plus per-format `<format>.pandoc-args` (concatenated *after* the top-level list so format-specific can override):
+```yaml
+pandoc-args:
+  - --lua-filter=tofill_filter.lua
+docx:
+  pandoc-args:
+    - --lua-filter=docx_only.lua
+pdf:
+  pandoc-args:
+    - --variable=papersize:a4
+```
+**CLI**: repeatable `--pandoc-arg <arg>` on `rev build`, appended *after* config args so CLI wins:
+```bash
+rev build docx --pandoc-arg=--lua-filter=tofill.lua --pandoc-arg=--shift-heading-level-by=1
+```
+**Verbose mode**: `rev build --verbose` already exists but doesn't echo the pandoc invocation. Print the full `pandoc <args>` command (one line per format) so users can copy-paste to replicate manually.
+### Touch points
+- `lib/build.ts` — `BuildConfig` + `DEFAULT_CONFIG` (add `pandocArgs: string[]`; add `pandocArgs` to each format config), `buildPandocArgs()` (append top-level then format-specific), `runPandoc()` (echo command under verbose), `loadConfig()` (read hyphenated `pandoc-args` key and map to camelCase `pandocArgs`).
+- `lib/commands/build.ts` — add `--pandoc-arg <arg>` (repeatable via custom collector), forward through `BuildOptions`, ensure CLI args are appended last.
+- `lib/schema.ts` — declare `pandoc-args` (array of strings) at top level and inside each format object.
+- `skill/SKILL.md` + `skill/REFERENCE.md` — document new field and flag with a `--lua-filter=` example.
+- `test/build.test.js` — cover (a) top-level only, (b) format-specific only, (c) both concatenated in order, (d) CLI overrides config.
+### Open questions
+None. Hyphenated YAML key + camelCase TS field is consistent with how the rest of the schema is read (we're already free-form on the JS side, just need a small key transform in `loadConfig`).
+---
+## Issue 2 — Output filename is auto-truncated mid-word and not configurable  `[x]`
+### Problem
+Default output landed at `output/adapt-alien-dark-diversity-across-plant-communitie.docx` — title slugified and hard-truncated at 50 chars (`communitie` missing the trailing `s`). No `-o` flag, no `output:` field in `rev.yaml`.
+Root cause: `lib/build.ts:1055-1056` (`runPandoc`) and `lib/commands/build.ts:591-592` (`--show-changes` path):
+```ts
+const baseName = config.title
+  ? config.title.toLowerCase().replace(/[^a-z0-9]+/g, '-').slice(0, 50)
+  : 'paper';
+```
+`.slice(0, 50)` is a blind cut.
+### Design (agreed)
+**rev.yaml**: per-format `output:` map. Extensions optional — added if missing.
+```yaml
+output:
+  docx: ADAPT_proposal_draft.docx
+  pdf: ADAPT_proposal_draft.pdf
+```
+**CLI**: `-o, --output <path>` on `rev build`. When multiple formats are built, applies as basename to all (extension swapped per format); for single-format builds, used verbatim.
+**Truncation fix**: when no `output:` is configured, slug at last `-` boundary at-or-before 50 chars instead of mid-word. Also bump the cap to 80 — 50 is conservative.
+**Doc fix**: surface the default `output/` directory in `rev build --help` and SKILL.md "Project Structure" tree (already mentioned in passing — make it explicit).
+### Touch points
+- `lib/build.ts` — `BuildConfig` (`output?: Record<string, string>`), `DEFAULT_CONFIG`, `runPandoc()` (resolve filename: `config.output[format]` → CLI `-o` → slug). Helper: `resolveOutputName(config, format, cliOverride)`.
+- `lib/commands/build.ts` — add `-o, --output <path>` flag, wire into `BuildOptions`; same fix applied to the `--show-changes` branch's `baseName` construction.
+- `lib/schema.ts` — declare `output` as object mapping format → string.
+- `skill/SKILL.md` — "Project Structure" tree explicitly notes `output/`; new `output:` example under config.
+- `test/build.test.js` — cover (a) `output:` per-format honored, (b) `-o` CLI override, (c) word-boundary truncation when title >50 chars.
+### Resolved
+- `-o` relative paths resolve under `outputDir`; absolute paths bypass it. Same rule applies to values in `output:`.
+- Cap raised from 50 → 80 chars; fallback truncates at the last `-` boundary at-or-before the cap so words stay whole (the ADAPT title now slugs cleanly without losing the trailing "s" on "communities").
+- `--show-changes` and `--dual` derived filenames (`-changes.docx`, `_comments.docx`, `_comments.pdf`) follow the chosen base name.
+- Fixed an unrelated misleading example in SKILL.md that showed `output: { docx: { reference-doc: ... } }` — the real config key is `docx.reference` (top-level), not nested under `output:`.
+---
+## Issue 3 — Raw LaTeX figure blocks silently disappear in docx builds  `[x]`
+### Problem
+Source markdown with `\begin{figure}[H]\includegraphics{...}\end{figure}` blocks renders correctly in the PDF target but produces a docx where all figures are silently missing. Pandoc strips the raw LaTeX because docx has no LaTeX rendering pipeline. No warning is emitted.
+This catches you only on careful inspection — a less careful user would ship a docx with no figures and not notice until a reviewer asks.
+### Design (agreed)
+Three layers, combined:
+**1. Warn during build (always on).** In `applyFormatTransforms()` for docx, scan for raw LaTeX figure environments (`\begin{figure}` … `\end{figure}` containing `\includegraphics`). Emit:
+```
+Warning: 3 raw LaTeX figure block(s) won't render in docx.
+  intro.md:42  \begin{figure}[H] ... \includegraphics{figures/map.pdf} ...
+  methods.md:118
+  results.md:201
+  Hint: use ![caption](path){#fig:label width=80%} for format-portable figures, or
+        pass --pandoc-arg=--lua-filter=<your.lua> to translate them yourself.
+```
+Counted by file/line so the user can jump to fix.
+**2. Auto-translate the common shape (opt-out via `docx.translateRawFigures: false`).** Convert
+```latex
+\begin{figure}[H]
+\centering
+\includegraphics[width=0.8\textwidth]{figures/map.pdf}
+\caption{Map of study sites.}
+\label{fig:map}
+\end{figure}
+```
+→
+```markdown
+![Map of study sites.](figures/map.pdf){#fig:map width=80%}
+```
+Cover the 80% case. If the block has anything more exotic (`\subfloat`, `\rotatebox`, multi-`\includegraphics`), skip auto-translate, warn loudly, and leave the block as-is.
+Width conversion: `0.8\textwidth` → `80%`; bare `8cm` → `8cm`; missing → omit.
+**3. Document.** SKILL.md "Cross-References" section currently mentions `@fig:label` and `{#fig:label}` but doesn't show how to *insert* a figure. Add:
+```markdown
+![Caption text.](figures/foo.pdf){#fig:foo width=80%}
+```
+Note this is the format-portable form. Also mention that raw `\begin{figure}` blocks are PDF-only.
+### Touch points
+- `lib/build.ts` — new helper `detectRawLatexFigures(content): {file?, line, block}[]` and `translateRawLatexFigures(content): {translated, untranslatedCount}`. Wire into `applyFormatTransforms()` for docx (after `convertDynamicRefsToDisplay`).
+- `lib/build.ts` — propagate warnings up via the existing `warnings: string[]` returned by `build()`. `rev build` already prints from there.
+- `lib/commands/build.ts` — surface warnings in normal output (not just verbose).
+- `lib/schema.ts` — declare `docx.translateRawFigures: boolean` (default true).
+- `skill/SKILL.md` — figure-insertion example under "Cross-References".
+- `test/build.test.js` — cover (a) detection counts blocks correctly, (b) auto-translate of `\includegraphics{path}`, (c) auto-translate of `\includegraphics[width=0.8\textwidth]{path}` → `width=80%`, (d) exotic block → not translated, warned, left alone, (e) opt-out via `translateRawFigures: false`.
+### Open questions
+- Should auto-translate also handle bare `\includegraphics{...}` outside a `figure` env? Lean no — keep scope to figure environments. If a user writes raw `\includegraphics` without wrapping, that's a deliberate choice we shouldn't second-guess.
+- Width unit handling: `0.8\textwidth` → `80%` is unambiguous. `\linewidth` → `100%`? Yes. Other relative units → leave raw and warn.
+---
+## Working order
+1. **Issue 1** first — unblocks immediate workflow needs and provides the manual escape hatch for issue 3 even before auto-translate ships.
+2. **Issue 2** next — small, low-risk, quality-of-life win.
+3. **Issue 3** last — biggest behavior change; benefits from the verbose pandoc echo (Issue 1) for debugging the lua-filter fallback path.

package/lib/build.ts CHANGED Viewed

@@ -14,6 +14,8 @@ import { fileURLToPath } from 'url';
 import { execSync, spawn, ChildProcess } from 'child_process';
 import YAML from 'yaml';
 import { stripAnnotations } from './annotations.js';
+import { criticToNativeTrackChanges, enableTrackRevisions, type NativeTrackChangeStats } from './trackchanges.js';
+import { prepareMarkdownWithMarkers, injectCommentsAtMarkers } from './wordcomments.js';
 import { buildRegistry, labelToDisplay, detectDynamicRefs, resolveForwardRefs, resolveSupplementaryRefs } from './crossref.js';
 import { processVariables, hasVariables } from './variables.js';
 import { processSlideMarkdown, hasSlideSyntax } from './slides.js';
@@ -970,6 +972,190 @@ export function prepareForFormat(
   return preparedPath;
 }
+// =============================================================================
+// Reviewed DOCX (track changes + threaded comments in one file)
+// =============================================================================
+export interface ReviewedDocxOptions {
+  /** Final output path for the reviewed docx. */
+  outputPath: string;
+  /** Author name attached to the tracked revisions. */
+  author?: string;
+  /**
+   * Thread `{>>...<<}` comments into the same file (parent + reply via
+   * commentsExtended.xml). When false, comments are stripped and only tracked
+   * changes are emitted.
+   */
+  includeComments?: boolean;
+  /**
+   * Optional reference docx: realign comment anchors against its text before
+   * injecting, matching the `--reference` behaviour of `--dual`. Only used
+   * when includeComments is true.
+   */
+  referencePath?: string | null;
+  /** Extra pandoc args (CLI --pandoc-arg), applied to the single pandoc pass. */
+  pandocArgs?: string[];
+  verbose?: boolean;
+}
+export interface ReviewedDocxResult {
+  success: boolean;
+  error?: string;
+  outputPath: string;
+  stats: NativeTrackChangeStats;
+  /** Number of parent comments threaded (0 when includeComments is false). */
+  commentCount: number;
+  replyCount: number;
+  /** Comments that could not be anchored (markers not found in the docx). */
+  skippedComments: number;
+  /** Realigned comment count when a reference docx was supplied. */
+  realigned?: number;
+}
+/**
+ * Build a single reviewed docx containing pandoc-native tracked changes and,
+ * optionally, threaded Word comments.
+ *
+ * One pandoc pass through the full rev filter chain (crossref, citeproc,
+ * reference-doc, macros) emits the `w:ins`/`w:del` revisions from native
+ * `.insertion`/`.deletion` spans; the same file is then post-processed to
+ * thread `{>>...<<}` comments (parent + reply). This is the `--dual
+ * --show-changes` artifact: my edits as tracked changes *and* the reviewer's
+ * comments with my replies, in the one file a supervisor opens and hands back.
+ *
+ * @param directory - Project directory
+ * @param paperPath - Combined paper.md (from combineSections)
+ * @param config - Build config
+ * @param options - Output path, author, comment handling
+ */
+export async function buildReviewedDocx(
+  directory: string,
+  paperPath: string,
+  config: BuildConfig,
+  options: ReviewedDocxOptions
+): Promise<ReviewedDocxResult> {
+  const {
+    outputPath,
+    author = 'Author',
+    includeComments = false,
+    referencePath = null,
+    pandocArgs,
+    verbose,
+  } = options;
+  const emptyStats: NativeTrackChangeStats = { insertions: 0, deletions: 0, substitutions: 0 };
+  let markdown = fs.readFileSync(paperPath, 'utf-8');
+  let realigned: number | undefined;
+  // Realign comment anchors from a reference docx (parity with --dual).
+  if (includeComments && referencePath && fs.existsSync(referencePath)) {
+    try {
+      const { realignMarkdown } = await import('./comment-realign.js');
+      const res = await realignMarkdown(referencePath, markdown);
+      if (res.success) {
+        markdown = res.markdown;
+        realigned = res.insertions;
+      }
+    } catch {
+      // Non-fatal — fall back to the anchors already in the markdown.
+    }
+  }
+  // 1. CriticMarkup ins/del/subst → pandoc-native track-change spans.
+  const { text: withSpans, stats } = criticToNativeTrackChanges(markdown, { author });
+  // 2. Strip remaining annotations (highlights, and comments unless threading
+  //    them). The native spans are inert to stripAnnotations — it only touches
+  //    CriticMarkup and `.mark` spans, which are gone or preserved as needed.
+  let content = stripAnnotations(withSpans, { keepComments: includeComments });
+  // 3. Shared DOCX transforms (author block, @fig: → "Figure 1", raw figures).
+  const registry = buildRegistry(directory, config.sections);
+  content = applyFormatTransforms(content, 'docx', config, registry);
+  // 4. Comment markers (parents get ⟦CMS⟧ ranges; replies drop out for later
+  //    threading). No-op when not including comments.
+  let comments: ReturnType<typeof prepareMarkdownWithMarkers>['comments'] = [];
+  if (includeComments) {
+    const prepared = prepareMarkdownWithMarkers(content);
+    content = prepared.markedMarkdown;
+    comments = prepared.comments;
+  }
+  const preparedPath = path.join(directory, '.paper-reviewed.md');
+  const tempDocx = path.join(directory, '.paper-reviewed.docx');
+  try {
+    fs.writeFileSync(preparedPath, content, 'utf-8');
+    // 5. Single pandoc pass — emits native tracked changes with full filter chain.
+    const pandocResult = await runPandoc(preparedPath, 'docx', config, {
+      outputPath: tempDocx,
+      pandocArgs,
+      verbose,
+    });
+    if (!pandocResult.success) {
+      return {
+        success: false,
+        error: pandocResult.error,
+        outputPath,
+        stats: emptyStats,
+        commentCount: 0,
+        replyCount: 0,
+        skippedComments: 0,
+        realigned,
+      };
+    }
+    const hasTrackChanges = stats.insertions + stats.deletions + stats.substitutions > 0;
+    if (hasTrackChanges) enableTrackRevisions(tempDocx);
+    // 6. Thread comments into the same file (or just move it into place).
+    if (comments.length > 0) {
+      const injection = await injectCommentsAtMarkers(tempDocx, comments, outputPath);
+      if (!injection.success) {
+        return {
+          success: false,
+          error: injection.error,
+          outputPath,
+          stats,
+          commentCount: 0,
+          replyCount: 0,
+          skippedComments: 0,
+          realigned,
+        };
+      }
+      return {
+        success: true,
+        outputPath,
+        stats,
+        commentCount: injection.commentCount,
+        replyCount: injection.replyCount ?? 0,
+        skippedComments: injection.skippedComments,
+        realigned,
+      };
+    }
+    fs.copyFileSync(tempDocx, outputPath);
+    return {
+      success: true,
+      outputPath,
+      stats,
+      commentCount: 0,
+      replyCount: 0,
+      skippedComments: 0,
+      realigned,
+    };
+  } finally {
+    if (!process.env.DEBUG) {
+      for (const tmp of [preparedPath, tempDocx]) {
+        try { fs.unlinkSync(tmp); } catch { /* best-effort */ }
+      }
+    }
+  }
+}
 /**
  * Convert @fig:label references to display format (Figure 1)
  */