docrev 0.11.1 → 0.11.3

package/dist/lib/input.d.ts

@@ -0,0 +1,67 @@
+/**
+ * Input routing: read a command's `[file]` argument as CriticMarkup Markdown,
+ * transparently handling Word documents.
+ *
+ * `rev status`/`rev comments` and friends were written to `readFileSync(file,
+ * 'utf-8')` every argument and regex it for CriticMarkup. A `.docx` is a binary
+ * ZIP; decoded as UTF-8 it occasionally yields a stray `{~~..~>..~~}` byte
+ * sequence, so the tool reported a small, plausible, wrong count with no error
+ * (gcol33/docrev#8). This module is the single front door that both:
+ *
+ *   - detects a Word document by extension AND by ZIP magic + `word/document.xml`
+ *     (so a mis-extensioned `.docx` renamed to `.md`/`.txt` is still caught), and
+ *   - converts it to the same annotated Markdown `rev import` produces, so every
+ *     downstream reader (`countAnnotations`, `getComments`, ...) sees real tags.
+ *
+ * Commands that only read report through `readAnnotatedInput`; commands that
+ * edit in place call `assertEditableMarkdown` first and refuse a `.docx` with a
+ * pointer to `rev import`, since CriticMarkup cannot be written back into a
+ * binary ZIP.
+ */
+/**
+ * A file cannot be read as (or converted to) CriticMarkup Markdown. Carries
+ * actionable suggestions so the command layer can render a helpful error.
+ */
+export declare class InputError extends Error {
+    suggestions: string[];
+    constructor(message: string, suggestions?: string[]);
+}
+/** True when the file begins with the ZIP local-file-header magic. */
+export declare function looksLikeZip(file: string): boolean;
+/**
+ * True when `file` is a Word document: it carries a Word extension, or it is a
+ * ZIP whose package contains `word/document.xml`. The content sniff catches a
+ * `.docx` renamed to `.md`/`.txt`, so those never get regexed as CriticMarkup.
+ */
+export declare function isWordDocument(file: string): boolean;
+/**
+ * Read a file as the CriticMarkup Markdown a command expects. A Word document
+ * is converted through the existing OOXML/pandoc reader (real insertions,
+ * deletions, substitutions, and comments); a Markdown/text file is read as
+ * UTF-8. A non-Word binary (image, PDF, unknown ZIP) is rejected rather than
+ * silently miscounted.
+ *
+ * @throws InputError if the file is a binary that is not a Word document, or a
+ *   Word document that cannot be parsed.
+ */
+export declare function readAnnotatedInput(file: string): Promise<string>;
+/**
+ * Guard for commands that edit the file in place (accept/reject/resolve/reply/
+ * review). A `.docx` cannot hold CriticMarkup, so refuse it with a pointer to
+ * `rev import` instead of corrupting the document.
+ *
+ * @throws InputError if `file` is a Word document.
+ */
+export declare function assertEditableMarkdown(file: string): void;
+/**
+ * Command front door: verify the file exists, then read it as annotated
+ * Markdown (converting a `.docx` on the way). On a bad input, print a friendly
+ * error and exit — matching how the rest of the CLI reports failures.
+ */
+export declare function loadAnnotated(file: string, fileType?: string): Promise<string>;
+/**
+ * Command front door for editing commands: verify existence and refuse a Word
+ * document (which cannot be edited in place), printing guidance and exiting.
+ */
+export declare function requireEditableMarkdown(file: string, fileType?: string): void;
+//# sourceMappingURL=input.d.ts.map

package/dist/lib/input.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"input.d.ts","sourceRoot":"","sources":["../../lib/input.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAaH;;;GAGG;AACH,qBAAa,UAAW,SAAQ,KAAK;IACnC,WAAW,EAAE,MAAM,EAAE,CAAC;gBACV,OAAO,EAAE,MAAM,EAAE,WAAW,GAAE,MAAM,EAAO;CAKxD;AAiBD,sEAAsE;AACtE,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAElD;AAED;;;;GAIG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAQpD;AAQD;;;;;;;;;GASG;AACH,wBAAsB,kBAAkB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAwBtE;AAED;;;;;;GAMG;AACH,wBAAgB,sBAAsB,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAWzD;AAMD;;;;GAIG;AACH,wBAAsB,aAAa,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,SAAkB,GAAG,OAAO,CAAC,MAAM,CAAC,CAQ7F;AAED;;;GAGG;AACH,wBAAgB,uBAAuB,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,SAAkB,GAAG,IAAI,CAQtF"}

package/dist/lib/input.js

@@ -0,0 +1,164 @@
+/**
+ * Input routing: read a command's `[file]` argument as CriticMarkup Markdown,
+ * transparently handling Word documents.
+ *
+ * `rev status`/`rev comments` and friends were written to `readFileSync(file,
+ * 'utf-8')` every argument and regex it for CriticMarkup. A `.docx` is a binary
+ * ZIP; decoded as UTF-8 it occasionally yields a stray `{~~..~>..~~}` byte
+ * sequence, so the tool reported a small, plausible, wrong count with no error
+ * (gcol33/docrev#8). This module is the single front door that both:
+ *
+ *   - detects a Word document by extension AND by ZIP magic + `word/document.xml`
+ *     (so a mis-extensioned `.docx` renamed to `.md`/`.txt` is still caught), and
+ *   - converts it to the same annotated Markdown `rev import` produces, so every
+ *     downstream reader (`countAnnotations`, `getComments`, ...) sees real tags.
+ *
+ * Commands that only read report through `readAnnotatedInput`; commands that
+ * edit in place call `assertEditableMarkdown` first and refuse a `.docx` with a
+ * pointer to `rev import`, since CriticMarkup cannot be written back into a
+ * binary ZIP.
+ */
+import * as fs from 'fs';
+import * as path from 'path';
+import { openDocx } from './ooxml.js';
+import { exitWithError, requireFile } from './errors.js';
+/** ZIP local-file-header magic: the first four bytes of any `.docx`. */
+const ZIP_MAGIC = Buffer.from([0x50, 0x4b, 0x03, 0x04]);
+/** OOXML Word extensions (all ZIP-backed, none Markdown). */
+const WORD_EXTENSIONS = new Set(['.docx', '.docm', '.dotx', '.dotm']);
+/**
+ * A file cannot be read as (or converted to) CriticMarkup Markdown. Carries
+ * actionable suggestions so the command layer can render a helpful error.
+ */
+export class InputError extends Error {
+    suggestions;
+    constructor(message, suggestions = []) {
+        super(message);
+        this.name = 'InputError';
+        this.suggestions = suggestions;
+    }
+}
+/** Read the first bytes of a file, or an empty buffer if unreadable. */
+function readMagic(file, length = 4) {
+    let fd;
+    try {
+        fd = fs.openSync(file, 'r');
+        const buf = Buffer.alloc(length);
+        const n = fs.readSync(fd, buf, 0, length, 0);
+        return buf.subarray(0, n);
+    }
+    catch {
+        return Buffer.alloc(0);
+    }
+    finally {
+        if (fd !== undefined)
+            fs.closeSync(fd);
+    }
+}
+/** True when the file begins with the ZIP local-file-header magic. */
+export function looksLikeZip(file) {
+    return readMagic(file).equals(ZIP_MAGIC);
+}
+/**
+ * True when `file` is a Word document: it carries a Word extension, or it is a
+ * ZIP whose package contains `word/document.xml`. The content sniff catches a
+ * `.docx` renamed to `.md`/`.txt`, so those never get regexed as CriticMarkup.
+ */
+export function isWordDocument(file) {
+    if (WORD_EXTENSIONS.has(path.extname(file).toLowerCase()))
+        return true;
+    if (!looksLikeZip(file))
+        return false;
+    try {
+        return openDocx(file).getEntry('word/document.xml') !== null;
+    }
+    catch {
+        return false;
+    }
+}
+/** A NUL byte in the head reliably marks binary; UTF-8 Markdown never has one. */
+function isBinaryBuffer(buf) {
+    if (buf.length >= 4 && buf.subarray(0, 4).equals(ZIP_MAGIC))
+        return true;
+    return buf.subarray(0, Math.min(buf.length, 8192)).includes(0x00);
+}
+/**
+ * Read a file as the CriticMarkup Markdown a command expects. A Word document
+ * is converted through the existing OOXML/pandoc reader (real insertions,
+ * deletions, substitutions, and comments); a Markdown/text file is read as
+ * UTF-8. A non-Word binary (image, PDF, unknown ZIP) is rejected rather than
+ * silently miscounted.
+ *
+ * @throws InputError if the file is a binary that is not a Word document, or a
+ *   Word document that cannot be parsed.
+ */
+export async function readAnnotatedInput(file) {
+    if (isWordDocument(file)) {
+        const { readDocxAsAnnotatedMarkdown } = await import('./import.js');
+        try {
+            return await readDocxAsAnnotatedMarkdown(file);
+        }
+        catch (err) {
+            throw new InputError(`Failed to read Word document ${path.basename(file)}: ${err.message}`, ['Run "rev import <docx>" to convert it to annotated Markdown first']);
+        }
+    }
+    const buf = fs.readFileSync(file);
+    if (isBinaryBuffer(buf)) {
+        throw new InputError(`${path.basename(file)} is not a text or Markdown file (binary content).`, [
+            'Word documents: run "rev import <docx>" first, or pass the imported .md',
+            'This command reads CriticMarkup Markdown, not binary files',
+        ]);
+    }
+    return buf.toString('utf-8');
+}
+/**
+ * Guard for commands that edit the file in place (accept/reject/resolve/reply/
+ * review). A `.docx` cannot hold CriticMarkup, so refuse it with a pointer to
+ * `rev import` instead of corrupting the document.
+ *
+ * @throws InputError if `file` is a Word document.
+ */
+export function assertEditableMarkdown(file) {
+    if (isWordDocument(file)) {
+        const base = path.basename(file);
+        throw new InputError(`${base} is a Word document; this command edits Markdown in place.`, [
+            `Run "rev import ${base}" to get an editable Markdown file, then edit that`,
+            'Read-only inspection works directly: "rev status" / "rev comments"',
+        ]);
+    }
+}
+// ---------------------------------------------------------------------------
+// Command-facing wrappers: translate InputError into the CLI's error surface.
+// ---------------------------------------------------------------------------
+/**
+ * Command front door: verify the file exists, then read it as annotated
+ * Markdown (converting a `.docx` on the way). On a bad input, print a friendly
+ * error and exit — matching how the rest of the CLI reports failures.
+ */
+export async function loadAnnotated(file, fileType = 'Markdown file') {
+    requireFile(file, fileType);
+    try {
+        return await readAnnotatedInput(file);
+    }
+    catch (err) {
+        if (err instanceof InputError)
+            exitWithError(err.message, err.suggestions);
+        throw err;
+    }
+}
+/**
+ * Command front door for editing commands: verify existence and refuse a Word
+ * document (which cannot be edited in place), printing guidance and exiting.
+ */
+export function requireEditableMarkdown(file, fileType = 'Markdown file') {
+    requireFile(file, fileType);
+    try {
+        assertEditableMarkdown(file);
+    }
+    catch (err) {
+        if (err instanceof InputError)
+            exitWithError(err.message, err.suggestions);
+        throw err;
+    }
+}
+//# sourceMappingURL=input.js.map

package/dist/lib/input.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"input.js","sourceRoot":"","sources":["../../lib/input.ts"],"names":[],"mappings":"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"}

package/dist/lib/macro-filter.lua

@@ -1,201 +1,201 @@
---[[
-docrev macro filter.
-
-Reads a JSON sidecar describing one-argument LaTeX-style macros and expands
-them per output FORMAT. Used for the built-in \tofill{X} (bold orange [X]
-placeholder) and any user-declared macros from rev.yaml.
-
-Sidecar path is passed via the DOCREV_MACROS_FILE environment variable, set
-by build.ts before spawning pandoc. Env vars (not metadata) because pandoc's
-filter traversal runs RawInline/RawBlock BEFORE Meta, so by the time we'd
-read metadata the inline expansions have already happened.
-
-Why raw OpenXML for docx? Pandoc 3.x's docx writer does NOT honor
-`Span{style="color: #..."}` — those spans render as plain text with no
-<w:color> run property. So for docx we emit raw <w:r> nodes directly. Same
-reasoning for the pptx-color-filter.
-
-For latex/pdf/beamer the markdown source already contains \tofill{X} as a raw
-LaTeX inline; we leave it alone because build.ts injects a \providecommand
-into header-includes. For html we emit a raw <span> with inline style. For
-everything else (markdown, gfm, plain) we degrade to **bold [X]** so the
-placeholder never silently disappears.
-]]
-
-local json = require('pandoc.json')
-
-local macros_by_name = {}
-
-local function load_sidecar()
-  local path = os.getenv('DOCREV_MACROS_FILE')
-  if not path or path == '' then
-    return
-  end
-  local fh = io.open(path, 'r')
-  if not fh then
-    io.stderr:write('docrev macro-filter: cannot read sidecar: ' .. path .. '\n')
-    return
-  end
-  local content = fh:read('*a')
-  fh:close()
-  local ok, parsed = pcall(json.decode, content)
-  if not ok or type(parsed) ~= 'table' or type(parsed.macros) ~= 'table' then
-    io.stderr:write('docrev macro-filter: malformed sidecar JSON\n')
-    return
-  end
-  for _, m in ipairs(parsed.macros) do
-    if type(m) == 'table' and type(m.name) == 'string' then
-      macros_by_name[m.name] = m
-    end
-  end
-end
-
-load_sidecar()
-
-local function xml_escape(s)
-  return (s:gsub('&', '&amp;'):gsub('<', '&lt;'):gsub('>', '&gt;'))
-end
-
-local function html_escape(s)
-  return (s
-    :gsub('&', '&amp;')
-    :gsub('<', '&lt;')
-    :gsub('>', '&gt;')
-    :gsub('"', '&quot;'))
-end
-
--- Resolve effective style for a macro in the current pandoc format.
--- Per-format entry wins over `default` (replacement, not merge — matches
--- macros.ts semantics).
-local function pick_style(macro, format)
-  if macro.formats and macro.formats[format] then
-    return macro.formats[format]
-  end
-  return macro.default or {}
-end
-
--- Build the inside of the bracket: [prefix][arg][suffix], optionally without
--- brackets when style.bracket == false.
-local function compose_text(style, arg)
-  local prefix = style.prefix or ''
-  local suffix = style.suffix or ''
-  local inner = prefix .. arg .. suffix
-  if style.bracket == false then
-    return inner
-  end
-  return '[' .. inner .. ']'
-end
-
-local function render_docx_run(style, arg)
-  local rpr = {}
-  if style.color then
-    table.insert(rpr, '<w:color w:val="' .. style.color .. '"/>')
-  end
-  if style.bold then
-    table.insert(rpr, '<w:b/>')
-  end
-  if style.italic then
-    table.insert(rpr, '<w:i/>')
-  end
-  local rpr_xml = ''
-  if #rpr > 0 then
-    rpr_xml = '<w:rPr>' .. table.concat(rpr) .. '</w:rPr>'
-  end
-  local text = xml_escape(compose_text(style, arg))
-  return '<w:r>' .. rpr_xml ..
-         '<w:t xml:space="preserve">' .. text .. '</w:t></w:r>'
-end
-
-local function render_html(style, arg)
-  local css = {}
-  if style.color then
-    table.insert(css, 'color:#' .. style.color)
-  end
-  if style.bold then
-    table.insert(css, 'font-weight:bold')
-  end
-  if style.italic then
-    table.insert(css, 'font-style:italic')
-  end
-  local text = html_escape(compose_text(style, arg))
-  if #css == 0 then
-    return '<span>' .. text .. '</span>'
-  end
-  return '<span style="' .. table.concat(css, ';') .. '">' .. text .. '</span>'
-end
-
--- Fallback path: produce native pandoc inlines so the macro never silently
--- disappears in markdown/gfm/plain output. Used when the current format has
--- no native rich-text path (or we couldn't open the sidecar).
-local function fallback_inlines(style, arg)
-  local doc = pandoc.read(compose_text(style, arg), 'markdown')
-  local inlines = pandoc.utils.blocks_to_inlines(doc.blocks)
-  if style.bold then
-    inlines = { pandoc.Strong(inlines) }
-  end
-  if style.italic then
-    inlines = { pandoc.Emph(inlines) }
-  end
-  return inlines
-end
-
--- Match `\NAME{...}` (with balanced braces inside the argument is NOT
--- supported — the use case is plain placeholder text, mirroring the reference
--- filter; users who need nested braces should use a different mechanism).
-local function parse_call(text)
-  local name, arg = text:match('^\\([A-Za-z][A-Za-z0-9]*)%s*{(.*)}%s*$')
-  if name and arg and macros_by_name[name] then
-    return name, arg
-  end
-  return nil, nil
-end
-
-local function expand_inline(el)
-  if el.format ~= 'tex' and el.format ~= 'latex' then
-    return nil
-  end
-  local name, arg = parse_call(el.text)
-  if not name then return nil end
-  local macro = macros_by_name[name]
-  local style = pick_style(macro, FORMAT)
-
-  if FORMAT == 'docx' then
-    return pandoc.RawInline('openxml', render_docx_run(style, arg))
-  elseif FORMAT == 'html' or FORMAT == 'html4' or FORMAT == 'html5' or FORMAT == 'chunkedhtml' then
-    return pandoc.RawInline('html', render_html(style, arg))
-  elseif FORMAT == 'latex' or FORMAT == 'beamer' or FORMAT == 'context' then
-    -- Leave the raw LaTeX as-is. build.ts injects \providecommand into
-    -- header-includes, so the LaTeX engine renders it directly.
-    return nil
-  else
-    return fallback_inlines(style, arg)
-  end
-end
-
-local function expand_block(el)
-  if el.format ~= 'tex' and el.format ~= 'latex' then
-    return nil
-  end
-  local name, arg = parse_call(el.text)
-  if not name then return nil end
-  local macro = macros_by_name[name]
-  local style = pick_style(macro, FORMAT)
-
-  if FORMAT == 'docx' then
-    return pandoc.RawBlock('openxml', '<w:p>' .. render_docx_run(style, arg) .. '</w:p>')
-  elseif FORMAT == 'html' or FORMAT == 'html4' or FORMAT == 'html5' or FORMAT == 'chunkedhtml' then
-    return pandoc.RawBlock('html', '<p>' .. render_html(style, arg) .. '</p>')
-  elseif FORMAT == 'latex' or FORMAT == 'beamer' or FORMAT == 'context' then
-    return nil
-  else
-    return pandoc.Para(fallback_inlines(style, arg))
-  end
-end
-
-function RawInline(el)
-  return expand_inline(el)
-end
-
-function RawBlock(el)
-  return expand_block(el)
-end
+--[[
+docrev macro filter.
+
+Reads a JSON sidecar describing one-argument LaTeX-style macros and expands
+them per output FORMAT. Used for the built-in \tofill{X} (bold orange [X]
+placeholder) and any user-declared macros from rev.yaml.
+
+Sidecar path is passed via the DOCREV_MACROS_FILE environment variable, set
+by build.ts before spawning pandoc. Env vars (not metadata) because pandoc's
+filter traversal runs RawInline/RawBlock BEFORE Meta, so by the time we'd
+read metadata the inline expansions have already happened.
+
+Why raw OpenXML for docx? Pandoc 3.x's docx writer does NOT honor
+`Span{style="color: #..."}` — those spans render as plain text with no
+<w:color> run property. So for docx we emit raw <w:r> nodes directly. Same
+reasoning for the pptx-color-filter.
+
+For latex/pdf/beamer the markdown source already contains \tofill{X} as a raw
+LaTeX inline; we leave it alone because build.ts injects a \providecommand
+into header-includes. For html we emit a raw <span> with inline style. For
+everything else (markdown, gfm, plain) we degrade to **bold [X]** so the
+placeholder never silently disappears.
+]]
+
+local json = require('pandoc.json')
+
+local macros_by_name = {}
+
+local function load_sidecar()
+  local path = os.getenv('DOCREV_MACROS_FILE')
+  if not path or path == '' then
+    return
+  end
+  local fh = io.open(path, 'r')
+  if not fh then
+    io.stderr:write('docrev macro-filter: cannot read sidecar: ' .. path .. '\n')
+    return
+  end
+  local content = fh:read('*a')
+  fh:close()
+  local ok, parsed = pcall(json.decode, content)
+  if not ok or type(parsed) ~= 'table' or type(parsed.macros) ~= 'table' then
+    io.stderr:write('docrev macro-filter: malformed sidecar JSON\n')
+    return
+  end
+  for _, m in ipairs(parsed.macros) do
+    if type(m) == 'table' and type(m.name) == 'string' then
+      macros_by_name[m.name] = m
+    end
+  end
+end
+
+load_sidecar()
+
+local function xml_escape(s)
+  return (s:gsub('&', '&amp;'):gsub('<', '&lt;'):gsub('>', '&gt;'))
+end
+
+local function html_escape(s)
+  return (s
+    :gsub('&', '&amp;')
+    :gsub('<', '&lt;')
+    :gsub('>', '&gt;')
+    :gsub('"', '&quot;'))
+end
+
+-- Resolve effective style for a macro in the current pandoc format.
+-- Per-format entry wins over `default` (replacement, not merge — matches
+-- macros.ts semantics).
+local function pick_style(macro, format)
+  if macro.formats and macro.formats[format] then
+    return macro.formats[format]
+  end
+  return macro.default or {}
+end
+
+-- Build the inside of the bracket: [prefix][arg][suffix], optionally without
+-- brackets when style.bracket == false.
+local function compose_text(style, arg)
+  local prefix = style.prefix or ''
+  local suffix = style.suffix or ''
+  local inner = prefix .. arg .. suffix
+  if style.bracket == false then
+    return inner
+  end
+  return '[' .. inner .. ']'
+end
+
+local function render_docx_run(style, arg)
+  local rpr = {}
+  if style.color then
+    table.insert(rpr, '<w:color w:val="' .. style.color .. '"/>')
+  end
+  if style.bold then
+    table.insert(rpr, '<w:b/>')
+  end
+  if style.italic then
+    table.insert(rpr, '<w:i/>')
+  end
+  local rpr_xml = ''
+  if #rpr > 0 then
+    rpr_xml = '<w:rPr>' .. table.concat(rpr) .. '</w:rPr>'
+  end
+  local text = xml_escape(compose_text(style, arg))
+  return '<w:r>' .. rpr_xml ..
+         '<w:t xml:space="preserve">' .. text .. '</w:t></w:r>'
+end
+
+local function render_html(style, arg)
+  local css = {}
+  if style.color then
+    table.insert(css, 'color:#' .. style.color)
+  end
+  if style.bold then
+    table.insert(css, 'font-weight:bold')
+  end
+  if style.italic then
+    table.insert(css, 'font-style:italic')
+  end
+  local text = html_escape(compose_text(style, arg))
+  if #css == 0 then
+    return '<span>' .. text .. '</span>'
+  end
+  return '<span style="' .. table.concat(css, ';') .. '">' .. text .. '</span>'
+end
+
+-- Fallback path: produce native pandoc inlines so the macro never silently
+-- disappears in markdown/gfm/plain output. Used when the current format has
+-- no native rich-text path (or we couldn't open the sidecar).
+local function fallback_inlines(style, arg)
+  local doc = pandoc.read(compose_text(style, arg), 'markdown')
+  local inlines = pandoc.utils.blocks_to_inlines(doc.blocks)
+  if style.bold then
+    inlines = { pandoc.Strong(inlines) }
+  end
+  if style.italic then
+    inlines = { pandoc.Emph(inlines) }
+  end
+  return inlines
+end
+
+-- Match `\NAME{...}` (with balanced braces inside the argument is NOT
+-- supported — the use case is plain placeholder text, mirroring the reference
+-- filter; users who need nested braces should use a different mechanism).
+local function parse_call(text)
+  local name, arg = text:match('^\\([A-Za-z][A-Za-z0-9]*)%s*{(.*)}%s*$')
+  if name and arg and macros_by_name[name] then
+    return name, arg
+  end
+  return nil, nil
+end
+
+local function expand_inline(el)
+  if el.format ~= 'tex' and el.format ~= 'latex' then
+    return nil
+  end
+  local name, arg = parse_call(el.text)
+  if not name then return nil end
+  local macro = macros_by_name[name]
+  local style = pick_style(macro, FORMAT)
+
+  if FORMAT == 'docx' then
+    return pandoc.RawInline('openxml', render_docx_run(style, arg))
+  elseif FORMAT == 'html' or FORMAT == 'html4' or FORMAT == 'html5' or FORMAT == 'chunkedhtml' then
+    return pandoc.RawInline('html', render_html(style, arg))
+  elseif FORMAT == 'latex' or FORMAT == 'beamer' or FORMAT == 'context' then
+    -- Leave the raw LaTeX as-is. build.ts injects \providecommand into
+    -- header-includes, so the LaTeX engine renders it directly.
+    return nil
+  else
+    return fallback_inlines(style, arg)
+  end
+end
+
+local function expand_block(el)
+  if el.format ~= 'tex' and el.format ~= 'latex' then
+    return nil
+  end
+  local name, arg = parse_call(el.text)
+  if not name then return nil end
+  local macro = macros_by_name[name]
+  local style = pick_style(macro, FORMAT)
+
+  if FORMAT == 'docx' then
+    return pandoc.RawBlock('openxml', '<w:p>' .. render_docx_run(style, arg) .. '</w:p>')
+  elseif FORMAT == 'html' or FORMAT == 'html4' or FORMAT == 'html5' or FORMAT == 'chunkedhtml' then
+    return pandoc.RawBlock('html', '<p>' .. render_html(style, arg) .. '</p>')
+  elseif FORMAT == 'latex' or FORMAT == 'beamer' or FORMAT == 'context' then
+    return nil
+  else
+    return pandoc.Para(fallback_inlines(style, arg))
+  end
+end
+
+function RawInline(el)
+  return expand_inline(el)
+end
+
+function RawBlock(el)
+  return expand_block(el)
+end