apex-ruby 1.0.6 → 1.0.8

data/ext/apex_ext/apex_src/cli/main.c

@@ -16,20 +16,164 @@
 #include <dirent.h>
 #include <sys/stat.h>
 #include <sys/ioctl.h>
+#include <limits.h>
 
-/* Remote plugin directory helpers (from plugins_remote.c) */
+    /* Remote plugin directory helpers (from plugins_remote.c) */
 typedef struct apex_remote_plugin apex_remote_plugin;
 typedef struct apex_remote_plugin_list apex_remote_plugin_list;
 
 apex_remote_plugin_list *apex_remote_fetch_directory(const char *url);
+apex_remote_plugin_list *apex_remote_fetch_filters_directory(const char *url);
 void apex_remote_print_plugins(apex_remote_plugin_list *list);
 void apex_remote_print_plugins_filtered(apex_remote_plugin_list *list,
                                         const char **installed_ids,
-                                        size_t installed_count);
+                                        size_t installed_count,
+                                        const char *noun);
 apex_remote_plugin *apex_remote_find_plugin(apex_remote_plugin_list *list, const char *id);
 void apex_remote_free_plugins(apex_remote_plugin_list *list);
 const char *apex_remote_plugin_repo(apex_remote_plugin *p);
 
+/* Shared JSON helpers used for filters as well */
+char *apex_remote_fetch_json(const char *url);
+char *apex_remote_extract_string(const char *obj, const char *key);
+
+/* ------------------------------------------------------------------------- */
+/* Syntax highlighting theme listing                                         */
+/* ------------------------------------------------------------------------- */
+
+static int apex_cli_terminal_width(void) {
+    struct winsize ws;
+    if (ioctl(STDOUT_FILENO, TIOCGWINSZ, &ws) == 0 && ws.ws_col > 0) {
+        return (int)ws.ws_col;
+    }
+    const char *cols_env = getenv("COLUMNS");
+    if (cols_env && *cols_env) {
+        long v = strtol(cols_env, NULL, 10);
+        if (v > 0 && v < INT_MAX) {
+            return (int)v;
+        }
+    }
+    return 80;
+}
+
+static void apex_cli_print_theme_section(const char *title,
+                                         const char *const *items,
+                                         size_t count) {
+    fprintf(stdout, "%s\n", title);
+    fprintf(stdout, "----------------------------------------\n");
+    if (count == 0) {
+        fprintf(stdout, "(no themes)\n\n");
+        return;
+    }
+
+    size_t max_len = 0;
+    for (size_t i = 0; i < count; i++) {
+        size_t len = strlen(items[i]);
+        if (len > max_len) max_len = len;
+    }
+
+    int term_width = apex_cli_terminal_width();
+    int col_width = (int)max_len + 2;
+    if (col_width <= 0) col_width = 16;
+    int max_cols = term_width > 0 ? term_width / col_width : 1;
+    if (max_cols < 1) max_cols = 1;
+    if (max_cols > 4) max_cols = 4;
+    int cols = max_cols;
+    int rows = (int)((count + (size_t)cols - 1) / (size_t)cols);
+    if (rows < 1) rows = 1;
+
+    for (int r = 0; r < rows; r++) {
+        for (int c = 0; c < cols; c++) {
+            size_t idx = (size_t)r + (size_t)rows * (size_t)c;
+            if (idx >= count) {
+                continue;
+            }
+            const char *name = items[idx];
+            int pad = col_width - (int)strlen(name);
+            if (pad < 1) pad = 1;
+            fprintf(stdout, "%s", name);
+            for (int p = 0; p < pad; p++) fputc(' ', stdout);
+        }
+        fputc('\n', stdout);
+    }
+    fputc('\n', stdout);
+}
+
+static void apex_cli_print_highlight_themes(void) {
+    static const char *const pygments_themes[] = {
+        "abap",
+        "algol",
+        "algol_nu",
+        "arduino",
+        "autumn",
+        "bw",
+        "borland",
+        "coffee",
+        "colorful",
+        "default",
+        "dracula",
+        "emacs",
+        "friendly_grayscale",
+        "friendly",
+        "fruity",
+        "github-dark",
+        "gruvbox-dark",
+        "gruvbox-light",
+        "igor",
+        "inkpot",
+        "lightbulb",
+        "lilypond",
+        "lovelace",
+        "manni",
+        "material",
+        "monokai",
+        "murphy",
+        "native",
+        "nord-darker",
+        "nord",
+        "one-dark",
+        "paraiso-dark",
+        "paraiso-light",
+        "pastie",
+        "perldoc",
+        "rainbow_dash",
+        "rrt",
+        "sas",
+        "solarized-dark",
+        "solarized-light",
+        "staroffice",
+        "stata-dark",
+        "stata-light",
+        "tango",
+        "trac",
+        "vim",
+        "vs",
+        "xcode",
+        "zenburn"
+    };
+    static const char *const skylighting_themes[] = {
+        "kate",
+        "breezeDark",
+        "pygments",
+        "espresso",
+        "tango",
+        "haddock",
+        "monochrome",
+        "zenburn"
+    };
+    static const char *const shiki_themes[] = {
+        "Bundled themes: see https://shiki.style/themes",
+        "Special theme: none (disables highlighting)"
+    };
+
+    apex_cli_print_theme_section("Pygments themes", pygments_themes,
+                                 sizeof(pygments_themes) / sizeof(pygments_themes[0]));
+    apex_cli_print_theme_section("Skylighting themes", skylighting_themes,
+                                 sizeof(skylighting_themes) / sizeof(skylighting_themes[0]));
+    apex_cli_print_theme_section("Shiki themes", shiki_themes,
+                                 sizeof(shiki_themes) / sizeof(shiki_themes[0]));
+}
+
 /* ------------------------------------------------------------------------- */
 /* Git helpers (mirrored from src/plugins.c for CLI-only use)               */
 /*                                                                           */
@@ -469,17 +613,21 @@ static void print_usage(const char *program_name) {
     fprintf(stderr, "  --base-dir DIR         Base directory for resolving relative paths (for images, includes, wiki links)\n");
     fprintf(stderr, "  --bibliography FILE     Bibliography file (BibTeX, CSL JSON, or CSL YAML) - can be used multiple times\n");
     fprintf(stderr, "  --captions POSITION    Table caption position: above or below (default: below)\n");
-    fprintf(stderr, "  --code-highlight TOOL  Use external tool for syntax highlighting (pygments, skylighting, or abbreviations p, s)\n");
+    fprintf(stderr, "  --code-highlight TOOL  Use external tool for syntax highlighting (pygments, skylighting, shiki, or abbreviations p, s, sh)\n");
+    fprintf(stderr, "  --code-highlight-theme THEME  Theme/style name for external syntax highlighters (tool-specific)\n");
+    fprintf(stderr, "  --list-themes          List available syntax highlighting themes for pygments, skylighting, and Shiki\n");
     fprintf(stderr, "  --code-line-numbers    Include line numbers in syntax-highlighted code blocks (requires --code-highlight)\n");
     fprintf(stderr, "  --highlight-language-only  Only highlight code blocks that have a language specified (requires --code-highlight)\n");
     fprintf(stderr, "  --combine              Concatenate Markdown files (expanding includes) into a single Markdown stream\n");
     fprintf(stderr, "                         When a SUMMARY.md file is provided, treat it as a GitBook index and combine\n");
     fprintf(stderr, "                         the linked files in order. Output is raw Markdown suitable for piping back into Apex.\n");
     fprintf(stderr, "  --csl FILE              Citation style file (CSL format)\n");
-    fprintf(stderr, "  --css FILE, --style FILE  Link to CSS file(s) in document head (requires --standalone, overrides CSS metadata)\n");
-    fprintf(stderr, "                         Can be used multiple times or accept comma-separated list (e.g., --css style.css,syntax.css)\n");
+    fprintf(stderr, "  --css FILE, --style FILE  Link to CSS file(s) in document head. With HTML: requires -s/--standalone.\n");
+    fprintf(stderr, "                         With -t man-html -s: include custom CSS in the man page. Can be used multiple times or comma-separated (e.g., --css style.css)\n");
     fprintf(stderr, "  --embed-css            Embed CSS file contents into a <style> tag in the document head (used with --css)\n");
     fprintf(stderr, "  --embed-images         Embed local images as base64 data URLs in HTML output\n");
+    fprintf(stderr, "  --[no-]image-captions  Wrap images with title or alt text in <figure>/<figcaption> (default: on in unified/mmd)\n");
+    fprintf(stderr, "  --[no-]title-captions-only  Only add captions for images with title; alt-only images get no caption\n");
     fprintf(stderr, "  --hardbreaks           Treat newlines as hard breaks\n");
     fprintf(stderr, "  --header-anchors        Generate <a> anchor tags instead of header IDs\n");
     fprintf(stderr, "  -h, --help             Show this help message\n");
@@ -488,6 +636,13 @@ static void print_usage(const char *program_name) {
     fprintf(stderr, "  --[no-]includes        Enable file inclusion (enabled by default in unified mode)\n");
     fprintf(stderr, "  --indices               Enable index processing (mmark, TextIndex, and Leanpub syntax)\n");
     fprintf(stderr, "  --install-plugin ID    Install plugin by id from directory, or by Git URL/GitHub shorthand (user/repo)\n");
+    fprintf(stderr, "  --list-filters         List installed filters and available filters from the remote directory\n");
+    fprintf(stderr, "  --install-filter ID    Install AST filter by id from the central filters directory or by Git URL/GitHub shorthand\n");
+    fprintf(stderr, "  --uninstall-filter ID  Uninstall filter by id\n");
+    fprintf(stderr, "  --filter NAME          Run a single AST filter from ~/.config/apex/filters/NAME (Pandoc-style JSON filter)\n");
+    fprintf(stderr, "  --filters              Run all executable filters in ~/.config/apex/filters (sorted by name)\n");
+    fprintf(stderr, "  --lua-filter FILE      Run a Lua script as an AST filter via 'lua FILE' (Pandoc-style JSON filter)\n");
+    fprintf(stderr, "  --no-strict-filters    Do not abort on AST filter errors/invalid JSON; skip failing filters instead\n");
     fprintf(stderr, "  --link-citations       Link citations to bibliography entries\n");
     fprintf(stderr, "  --list-plugins         List installed plugins and available plugins from the remote directory\n");
     fprintf(stderr, "  --uninstall-plugin ID  Uninstall plugin by id\n");
@@ -497,6 +652,7 @@ static void print_usage(const char *program_name) {
     fprintf(stderr, "  --mmd-merge            Merge files from one or more mmd_merge-style index files into a single Markdown stream\n");
     fprintf(stderr, "                         Index files list document parts line-by-line; indentation controls header level shifting.\n");
     fprintf(stderr, "  -m, --mode MODE        Processor mode: commonmark, gfm, mmd, kramdown, unified (default)\n");
+    fprintf(stderr, "  -t, --to FORMAT        Output format: html (default), json (before filters), json-filtered/ast-json/ast (after filters), markdown/md, mmd, commonmark/cmark, kramdown, gfm, terminal/cli, terminal256, man, man-html\n");
     fprintf(stderr, "  --no-bibliography       Suppress bibliography output\n");
     fprintf(stderr, "  --no-footnotes         Disable footnote support\n");
     fprintf(stderr, "  --no-ids                Disable automatic header ID generation\n");
@@ -509,6 +665,7 @@ static void print_usage(const char *program_name) {
     fprintf(stderr, "  --no-smart             Disable smart typography\n");
     fprintf(stderr, "  --no-sup-sub           Disable superscript/subscript syntax\n");
     fprintf(stderr, "  --[no-]divs            Enable or disable Pandoc fenced divs (Unified mode only)\n");
+    fprintf(stderr, "  --[no-]one-line-definitions  Enable or disable one-line definition lists (Term :: Definition)\n");
     fprintf(stderr, "  --[no-]spans           Enable or disable bracketed spans [text]{IAL} (Pandoc-style, enabled by default in unified mode)\n");
     fprintf(stderr, "  --no-tables            Disable table support\n");
     fprintf(stderr, "  --no-transforms        Disable metadata variable transforms\n");
@@ -520,13 +677,15 @@ static void print_usage(const char *program_name) {
     fprintf(stderr, "  --[no-]progress          Show progress indicator during processing (enabled by default for TTY)\n");
     fprintf(stderr, "  --plugins              Enable external/plugin processing\n");
     fprintf(stderr, "  --pretty               Pretty-print HTML with indentation and whitespace\n");
+    fprintf(stderr, "  --xhtml                HTML5 output with self-closing void tags (<br />, <meta ... />)\n");
+    fprintf(stderr, "  --strict-xhtml         Polyglot XHTML/XML for parsers (xmlns, application/xhtml+xml meta; implies --xhtml). Mutually exclusive with --xhtml.\n");
     fprintf(stderr, "  --reject               Reject all Critic Markup changes (revert edits)\n");
     fprintf(stderr, "  --[no-]relaxed-tables  Enable or disable relaxed table parsing (no separator rows required)\n");
     fprintf(stderr, "  --[no-]per-cell-alignment  Enable or disable per-cell alignment markers (colons at start/end of cells, enabled by default in unified mode)\n");
     fprintf(stderr, "  --script VALUE         Inject <script> tags before </body> (standalone) or at end of HTML (snippet).\n");
     fprintf(stderr, "                          VALUE can be a path, URL, or shorthand (mermaid, mathjax, katex). Can be used multiple times or as a comma-separated list.\n");
     fprintf(stderr, "  --show-tooltips         Show tooltips on citations\n");
-    fprintf(stderr, "  -s, --standalone       Generate complete HTML document (with <html>, <head>, <body>)\n");
+    fprintf(stderr, "  -s, --standalone       Generate complete HTML document (with <html>, <head>, <body>). For -t man-html, -s adds nav sidebar and full page; without -s, output is snippet only.\n");
     fprintf(stderr, "  --[no-]sup-sub         Enable or disable MultiMarkdown-style superscript (^text^) and subscript (~text~) syntax\n");
     fprintf(stderr, "  --[no-]strikethrough   Enable or disable GFM-style ~~strikethrough~~ processing\n");
     fprintf(stderr, "  --title TITLE          Document title (requires --standalone, default: \"Document\")\n");
@@ -547,6 +706,9 @@ static void print_usage(const char *program_name) {
     fprintf(stderr, "  --wikilink-space MODE  Space replacement for wiki links: dash, none, underscore, space (default: dash)\n");
     fprintf(stderr, "  --wikilink-extension EXT  File extension to append to wiki links (e.g., html, md)\n");
     fprintf(stderr, "  --[no-]wikilink-sanitize  Sanitize wiki link URLs (lowercase, remove apostrophes, etc.)\n");
+    fprintf(stderr, "  --theme NAME            Terminal theme name for -t terminal/terminal256 (from ~/.config/apex/terminal/themes/NAME.theme)\n");
+    fprintf(stderr, "  --width N               Hard-wrap terminal/terminal256 output at N visible columns\n");
+    fprintf(stderr, "  -p, --paginate          Page terminal/cli/terminal256 output through a pager (APEX_PAGER, then PAGER, then less -R)\n");
     fprintf(stderr, "\n");
     fprintf(stderr, "If no file is specified, reads from stdin.\n");
 }
@@ -692,6 +854,121 @@ static int add_script_tag(char ***tags, size_t *count, size_t *capacity, const c
     return 0;
 }
 
+/* Wrap ANSI-colored output to a fixed column width.
+ * This operates on the final rendered string and counts only visible
+ * characters toward the width, skipping over ANSI CSI sequences.
+ */
+static char *wrap_ansi_to_width(const char *input, int width) {
+    if (!input || width <= 0) {
+        return NULL;
+    }
+
+    size_t in_len = strlen(input);
+    /* Heuristic for output capacity: input length plus space for added newlines. */
+    size_t cap = in_len + (in_len / (size_t)width + 2) * 2 + 1;
+    char *out = malloc(cap);
+    if (!out) {
+        return NULL;
+    }
+
+    size_t oi = 0;
+    int col = 0;
+
+    for (size_t i = 0; i < in_len; ) {
+        char c = input[i];
+
+        /* Newlines reset the column counter. */
+        if (c == '\n') {
+            if (oi + 1 >= cap) {
+                cap *= 2;
+                char *nb = realloc(out, cap);
+                if (!nb) {
+                    free(out);
+                    return NULL;
+                }
+                out = nb;
+            }
+            out[oi++] = c;
+            col = 0;
+            i++;
+            continue;
+        }
+
+        /* Simple handling for carriage return: pass through. */
+        if (c == '\r') {
+            if (oi + 1 >= cap) {
+                cap *= 2;
+                char *nb = realloc(out, cap);
+                if (!nb) {
+                    free(out);
+                    return NULL;
+                }
+                out = nb;
+            }
+            out[oi++] = c;
+            i++;
+            continue;
+        }
+
+        /* Preserve ANSI CSI sequences without counting them toward width. */
+        if (c == '\x1b' && i + 1 < in_len && input[i + 1] == '[') {
+            size_t start = i;
+            i += 2;
+            while (i < in_len && !((input[i] >= 'A' && input[i] <= 'Z') ||
+                                   (input[i] >= 'a' && input[i] <= 'z'))) {
+                i++;
+            }
+            if (i < in_len) {
+                i++; /* consume final letter */
+            }
+            size_t seq_len = i - start;
+            if (oi + seq_len + 1 >= cap) {
+                cap = cap + seq_len + 16;
+                char *nb = realloc(out, cap);
+                if (!nb) {
+                    free(out);
+                    return NULL;
+                }
+                out = nb;
+            }
+            memcpy(out + oi, input + start, seq_len);
+            oi += seq_len;
+            continue;
+        }
+
+        /* Insert a newline before adding another visible char if we've hit width. */
+        if (col >= width) {
+            if (oi + 1 >= cap) {
+                cap *= 2;
+                char *nb = realloc(out, cap);
+                if (!nb) {
+                    free(out);
+                    return NULL;
+                }
+                out = nb;
+            }
+            out[oi++] = '\n';
+            col = 0;
+        }
+
+        if (oi + 1 >= cap) {
+            cap *= 2;
+            char *nb = realloc(out, cap);
+            if (!nb) {
+                free(out);
+                return NULL;
+            }
+            out = nb;
+        }
+        out[oi++] = c;
+        col++;
+        i++;
+    }
+
+    out[oi] = '\0';
+    return out;
+}
+
 /**
  * Normalize a plugin identifier to a Git repository URL.
  * Returns a newly allocated string that must be freed by caller, or NULL on error.
@@ -1248,8 +1525,14 @@ int main(int argc, char *argv[]) {
     bool plugins_cli_override = false;
     bool plugins_cli_value = false;
     bool list_plugins = false;
+    bool list_themes = false;
     const char *install_plugin_id = NULL;
     const char *uninstall_plugin_id = NULL;
+    bool list_filters = false;
+    const char *uninstall_filter_id = NULL;
+
+    /* Filter install (AST filters) */
+    const char *install_filter_id = NULL;
     const char *input_file = NULL;
     const char *output_file = NULL;
     const char *meta_file = NULL;
@@ -1284,6 +1567,24 @@ int main(int argc, char *argv[]) {
     size_t script_tag_count = 0;
     size_t script_tag_capacity = 4;
 
+    /* AST filters (Pandoc-style JSON filters) configured from CLI */
+    char   **ast_filter_names = NULL;   /* Filter names from --filter (resolved in config dir) */
+    size_t   ast_filter_name_count = 0;
+    size_t   ast_filter_name_capacity = 4;
+    bool     run_all_filters_dir = false;  /* --filters */
+    bool     ast_filters_strict = true;    /* default strict mode; --no-strict-filters disables */
+
+    /* Lua filters: explicit script paths run via 'lua <script>' */
+    char   **lua_filter_paths = NULL;
+    size_t   lua_filter_count = 0;
+    size_t   lua_filter_capacity = 4;
+
+    /* Optional fixed-width wrapping for terminal output */
+    int width_override = 0;
+
+    /* Pagination for terminal/terminal256 output */
+    bool paginate_cli = false;
+
     /* Parse command-line arguments */
     for (int i = 1; i < argc; i++) {
         if (strcmp(argv[i], "-h") == 0 || strcmp(argv[i], "--help") == 0) {
@@ -1311,6 +1612,57 @@ int main(int argc, char *argv[]) {
                 fprintf(stderr, "Error: Unknown mode '%s'\n", argv[i]);
                 return 1;
             }
+        } else if (strcmp(argv[i], "-t") == 0 || strcmp(argv[i], "--to") == 0) {
+            if (++i >= argc) {
+                fprintf(stderr, "Error: --to requires an argument\n");
+                return 1;
+            }
+            if (strcmp(argv[i], "html") == 0) {
+                options.output_format = APEX_OUTPUT_HTML;
+            } else if (strcmp(argv[i], "json") == 0) {
+                options.output_format = APEX_OUTPUT_JSON;
+            } else if (strcmp(argv[i], "json-filtered") == 0 || strcmp(argv[i], "ast-json") == 0 || strcmp(argv[i], "ast") == 0) {
+                options.output_format = APEX_OUTPUT_JSON_FILTERED;
+            } else if (strcmp(argv[i], "markdown") == 0 || strcmp(argv[i], "md") == 0) {
+                options.output_format = APEX_OUTPUT_MARKDOWN;
+            } else if (strcmp(argv[i], "mmd") == 0) {
+                options.output_format = APEX_OUTPUT_MMD;
+            } else if (strcmp(argv[i], "commonmark") == 0 || strcmp(argv[i], "cmark") == 0) {
+                options.output_format = APEX_OUTPUT_COMMONMARK;
+            } else if (strcmp(argv[i], "kramdown") == 0) {
+                options.output_format = APEX_OUTPUT_KRAMDOWN;
+            } else if (strcmp(argv[i], "gfm") == 0) {
+                options.output_format = APEX_OUTPUT_GFM;
+            } else if (strcmp(argv[i], "terminal") == 0 || strcmp(argv[i], "cli") == 0) {
+                options.output_format = APEX_OUTPUT_TERMINAL;
+            } else if (strcmp(argv[i], "terminal256") == 0) {
+                options.output_format = APEX_OUTPUT_TERMINAL256;
+            } else if (strcmp(argv[i], "man") == 0) {
+                options.output_format = APEX_OUTPUT_MAN;
+            } else if (strcmp(argv[i], "man-html") == 0) {
+                options.output_format = APEX_OUTPUT_MAN_HTML;
+            } else {
+                fprintf(stderr, "Error: Unknown output format '%s'\n", argv[i]);
+                fprintf(stderr, "Supported formats: html, json, json-filtered/ast-json/ast, markdown/md, mmd, commonmark/cmark, kramdown, gfm, terminal/cli, terminal256, man, man-html\n");
+                return 1;
+            }
+        } else if (strcmp(argv[i], "--theme") == 0) {
+            if (++i >= argc) {
+                fprintf(stderr, "Error: --theme requires a name argument\n");
+                return 1;
+            }
+            options.theme_name = argv[i];
+        } else if (strcmp(argv[i], "--width") == 0) {
+            if (++i >= argc) {
+                fprintf(stderr, "Error: --width requires a column width argument\n");
+                return 1;
+            }
+            width_override = atoi(argv[i]);
+            if (width_override < 0) {
+                width_override = 0;
+            }
+        } else if (strcmp(argv[i], "-p") == 0 || strcmp(argv[i], "--paginate") == 0) {
+            paginate_cli = true;
         } else if (strcmp(argv[i], "-o") == 0 || strcmp(argv[i], "--output") == 0) {
             if (++i >= argc) {
                 fprintf(stderr, "Error: --output requires an argument\n");
@@ -1327,12 +1679,77 @@ int main(int argc, char *argv[]) {
             plugins_cli_value = false;
         } else if (strcmp(argv[i], "--list-plugins") == 0) {
             list_plugins = true;
+        } else if (strcmp(argv[i], "--list-themes") == 0) {
+            list_themes = true;
         } else if (strcmp(argv[i], "--install-plugin") == 0) {
             if (++i >= argc) {
                 fprintf(stderr, "Error: --install-plugin requires an id argument\n");
                 return 1;
             }
             install_plugin_id = argv[i];
+        } else if (strcmp(argv[i], "--list-filters") == 0) {
+            list_filters = true;
+        } else if (strcmp(argv[i], "--install-filter") == 0) {
+            if (++i >= argc) {
+                fprintf(stderr, "Error: --install-filter requires an id argument\n");
+                return 1;
+            }
+            install_filter_id = argv[i];
+        } else if (strcmp(argv[i], "--uninstall-filter") == 0) {
+            if (++i >= argc) {
+                fprintf(stderr, "Error: --uninstall-filter requires an id argument\n");
+                return 1;
+            }
+            uninstall_filter_id = argv[i];
+        } else if (strcmp(argv[i], "--filter") == 0) {
+            if (++i >= argc) {
+                fprintf(stderr, "Error: --filter requires a name argument\n");
+                return 1;
+            }
+            /* Collect filter names; resolution to full paths happens later */
+            if (!ast_filter_names) {
+                ast_filter_names = malloc(ast_filter_name_capacity * sizeof(char *));
+                if (!ast_filter_names) {
+                    fprintf(stderr, "Error: Memory allocation failed\n");
+                    return 1;
+                }
+            } else if (ast_filter_name_count >= ast_filter_name_capacity) {
+                size_t new_cap = ast_filter_name_capacity ? ast_filter_name_capacity * 2 : 4;
+                char **tmp = realloc(ast_filter_names, new_cap * sizeof(char *));
+                if (!tmp) {
+                    fprintf(stderr, "Error: Memory allocation failed\n");
+                    return 1;
+                }
+                ast_filter_names = tmp;
+                ast_filter_name_capacity = new_cap;
+            }
+            ast_filter_names[ast_filter_name_count++] = argv[i];
+        } else if (strcmp(argv[i], "--filters") == 0) {
+            run_all_filters_dir = true;
+        } else if (strcmp(argv[i], "--no-strict-filters") == 0) {
+            ast_filters_strict = false;
+        } else if (strcmp(argv[i], "--lua-filter") == 0) {
+            if (++i >= argc) {
+                fprintf(stderr, "Error: --lua-filter requires a script path argument\n");
+                return 1;
+            }
+            if (!lua_filter_paths) {
+                lua_filter_paths = malloc(lua_filter_capacity * sizeof(char *));
+                if (!lua_filter_paths) {
+                    fprintf(stderr, "Error: Memory allocation failed\n");
+                    return 1;
+                }
+            } else if (lua_filter_count >= lua_filter_capacity) {
+                size_t new_cap = lua_filter_capacity ? lua_filter_capacity * 2 : 4;
+                char **tmp = realloc(lua_filter_paths, new_cap * sizeof(char *));
+                if (!tmp) {
+                    fprintf(stderr, "Error: Memory allocation failed\n");
+                    return 1;
+                }
+                lua_filter_paths = tmp;
+                lua_filter_capacity = new_cap;
+            }
+            lua_filter_paths[lua_filter_count++] = argv[i];
         } else if (strcmp(argv[i], "--uninstall-plugin") == 0) {
             if (++i >= argc) {
                 fprintf(stderr, "Error: --uninstall-plugin requires an id argument\n");
@@ -1538,6 +1955,10 @@ int main(int argc, char *argv[]) {
             options.document_title = argv[i];
         } else if (strcmp(argv[i], "--pretty") == 0) {
             options.pretty = true;
+        } else if (strcmp(argv[i], "--xhtml") == 0) {
+            options.xhtml = true;
+        } else if (strcmp(argv[i], "--strict-xhtml") == 0) {
+            options.strict_xhtml = true;
         } else if (strcmp(argv[i], "--accept") == 0) {
             options.enable_critic_markup = true;
             options.critic_mode = 0;  /* CRITIC_ACCEPT */
@@ -1586,7 +2007,7 @@ int main(int argc, char *argv[]) {
             }
         } else if (strcmp(argv[i], "--code-highlight") == 0) {
             if (++i >= argc) {
-                fprintf(stderr, "Error: --code-highlight requires a tool name (pygments, skylighting, or abbreviations p, s)\n");
+                fprintf(stderr, "Error: --code-highlight requires a tool name (pygments, skylighting, shiki, or abbreviations p, s, sh)\n");
                 return 1;
             }
             /* Accept full names and abbreviations */
@@ -1594,10 +2015,19 @@ int main(int argc, char *argv[]) {
                 options.code_highlighter = "pygments";
             } else if (strcmp(argv[i], "skylighting") == 0 || strcmp(argv[i], "s") == 0 || strcmp(argv[i], "sky") == 0) {
                 options.code_highlighter = "skylighting";
+            } else if (strcmp(argv[i], "shiki") == 0 || strcmp(argv[i], "sh") == 0) {
+                options.code_highlighter = "shiki";
             } else {
-                fprintf(stderr, "Error: --code-highlight tool must be 'pygments' (p) or 'skylighting' (s)\n");
+                fprintf(stderr, "Error: --code-highlight tool must be 'pygments' (p), 'skylighting' (s), or 'shiki' (sh)\n");
                 return 1;
             }
+        } else if (strcmp(argv[i], "--code-highlight-theme") == 0 ||
+                   strcmp(argv[i], "--code-hilight-theme") == 0) {
+            if (++i >= argc) {
+                fprintf(stderr, "Error: --code-highlight-theme requires a theme name\n");
+                return 1;
+            }
+            options.code_highlight_theme = argv[i];
         } else if (strcmp(argv[i], "--code-line-numbers") == 0) {
             options.code_line_numbers = true;
         } else if (strcmp(argv[i], "--highlight-language-only") == 0) {
@@ -1622,6 +2052,10 @@ int main(int argc, char *argv[]) {
             options.enable_divs = true;
         } else if (strcmp(argv[i], "--no-divs") == 0) {
             options.enable_divs = false;
+        } else if (strcmp(argv[i], "--one-line-definitions") == 0) {
+            options.enable_definition_lists = true;
+        } else if (strcmp(argv[i], "--no-one-line-definitions") == 0) {
+            options.enable_definition_lists = false;
         } else if (strcmp(argv[i], "--spans") == 0) {
             options.enable_spans = true;
         } else if (strcmp(argv[i], "--no-spans") == 0) {
@@ -1848,12 +2282,23 @@ int main(int argc, char *argv[]) {
         return 1;
     }
 
+    if (options.xhtml && options.strict_xhtml) {
+        fprintf(stderr, "Error: --xhtml and --strict-xhtml cannot be used together (use --strict-xhtml alone).\n");
+        return 1;
+    }
+
     /* --combine and --mmd-merge are mutually exclusive */
     if (combine_mode && mmd_merge_mode) {
         fprintf(stderr, "Error: --combine and --mmd-merge cannot be used together\n");
         return 1;
     }
 
+    /* Handle theme listing before normal conversion */
+    if (list_themes) {
+        apex_cli_print_highlight_themes();
+        return 0;
+    }
+
     /* Handle plugin listing/installation/uninstallation commands before normal conversion */
     if (list_plugins || install_plugin_id || uninstall_plugin_id) {
         if ((install_plugin_id && uninstall_plugin_id) || (install_plugin_id && list_plugins && uninstall_plugin_id)) {
@@ -2037,7 +2482,7 @@ int main(int argc, char *argv[]) {
                 cli_free_installed_plugins(installed_head);
                 return 1;
             }
-            apex_remote_print_plugins_filtered(plist, (const char **)installed_ids, installed_count);
+            apex_remote_print_plugins_filtered(plist, (const char **)installed_ids, installed_count, "plugins");
             apex_remote_free_plugins(plist);
             if (installed_ids) {
                 for (size_t i = 0; i < installed_count; i++) free(installed_ids[i]);
@@ -2260,6 +2705,378 @@ int main(int argc, char *argv[]) {
         }
     }
 
+    /* Handle filter listing/installation/uninstallation before normal conversion.
+     * Filters are distributed from the apex-filters directory:
+     *   https://github.com/ApexMarkdown/apex-filters
+     * and installed into:
+     *   $XDG_CONFIG_HOME/apex/filters or ~/.config/apex/filters
+     */
+    if (list_filters || install_filter_id || uninstall_filter_id) {
+        if (install_filter_id && uninstall_filter_id) {
+            fprintf(stderr, "Error: --install-filter and --uninstall-filter cannot be combined.\n");
+            return 1;
+        }
+
+        /* Determine filters root: $XDG_CONFIG_HOME/apex/filters or ~/.config/apex/filters */
+        const char *xdg = getenv("XDG_CONFIG_HOME");
+        char root[1024];
+        if (xdg && *xdg) {
+            snprintf(root, sizeof(root), "%s/apex/filters", xdg);
+        } else {
+            const char *home = getenv("HOME");
+            if (!home || !*home) {
+                fprintf(stderr, "Error: HOME not set; cannot determine filter install directory.\n");
+                return 1;
+            }
+            snprintf(root, sizeof(root), "%s/.config/apex/filters", home);
+        }
+
+        /* Uninstall filter */
+        if (uninstall_filter_id) {
+            char target[1200];
+            snprintf(target, sizeof(target), "%s/%s", root, uninstall_filter_id);
+
+            struct stat st;
+            if (stat(target, &st) != 0) {
+                /* Try with common extensions (e.g. code-includes.lua from path install) */
+                const char *exts[] = { ".lua", ".py", ".rb" };
+                int found = 0;
+                for (size_t e = 0; e < sizeof(exts)/sizeof(exts[0]); e++) {
+                    snprintf(target, sizeof(target), "%s/%s%s", root, uninstall_filter_id, exts[e]);
+                    if (stat(target, &st) == 0) {
+                        found = 1;
+                        break;
+                    }
+                }
+                if (!found) {
+                    snprintf(target, sizeof(target), "%s/%s", root, uninstall_filter_id);
+                    fprintf(stderr, "Error: filter '%s' is not installed at %s\n", uninstall_filter_id, target);
+                    return 1;
+                }
+            }
+
+            fprintf(stderr, "About to remove filter:\n  %s\n", target);
+            fprintf(stderr, "Proceed? [y/N]: ");
+            fflush(stderr);
+
+            char answer[16];
+            if (!fgets(answer, sizeof(answer), stdin)) {
+                fprintf(stderr, "Aborted.\n");
+                return 1;
+            }
+            if (answer[0] != 'y' && answer[0] != 'Y') {
+                fprintf(stderr, "Aborted.\n");
+                return 1;
+            }
+
+            if (S_ISDIR(st.st_mode)) {
+                char rm_cmd[1400];
+                snprintf(rm_cmd, sizeof(rm_cmd), "rm -rf \"%s\"", target);
+                int rm_rc = system(rm_cmd);
+                if (rm_rc != 0) {
+                    fprintf(stderr, "Error: failed to remove filter directory '%s'.\n", target);
+                    return 1;
+                }
+            } else {
+                if (unlink(target) != 0) {
+                    fprintf(stderr, "Error: failed to remove filter '%s'.\n", target);
+                    return 1;
+                }
+            }
+
+            fprintf(stderr, "Uninstalled filter '%s' from %s\n", uninstall_filter_id, target);
+            return 0;
+        }
+
+        /* List filters: installed from root + available from remote directory */
+        if (list_filters) {
+            const char *dir_url = "https://raw.githubusercontent.com/ApexMarkdown/apex-filters/refs/heads/main/apex-filters.json";
+            apex_remote_plugin_list *flist = apex_remote_fetch_filters_directory(dir_url);
+
+            /* Collect installed filter ids (files and directories in root) */
+            char *installed_ids[128];
+            size_t installed_count = 0;
+            DIR *dir = opendir(root);
+            if (dir) {
+                struct dirent *ent;
+                while ((ent = readdir(dir)) != NULL && installed_count < 128) {
+                    if (ent->d_name[0] == '.' && (ent->d_name[1] == '\0' || (ent->d_name[1] == '.' && ent->d_name[2] == '\0')))
+                        continue;
+                    if (strncmp(ent->d_name, ".apex_", 6) == 0)
+                        continue;
+                    installed_ids[installed_count] = strdup(ent->d_name);
+                    if (installed_ids[installed_count])
+                        installed_count++;
+                }
+                closedir(dir);
+            }
+
+            printf("## Installed Filters\n");
+            if (installed_count == 0) {
+                printf("(none)\n");
+            } else {
+                for (size_t i = 0; i < installed_count; i++)
+                    printf("%s\n", installed_ids[i]);
+            }
+
+            printf("---\n");
+            printf("## Available Filters\n");
+            apex_remote_print_plugins_filtered(flist, (const char **)installed_ids, installed_count, "filters");
+
+            for (size_t i = 0; i < installed_count; i++)
+                free(installed_ids[i]);
+            if (flist) apex_remote_free_plugins(flist);
+            return 0;
+        }
+
+        /* Install filter */
+        if (install_filter_id) {
+        /* Check if install_filter_id is a direct URL/shorthand (GitHub repo) */
+        char *normalized_repo = normalize_plugin_repo_url(install_filter_id);
+        const char *repo = NULL;
+        char *final_filter_id = NULL;
+        char *filter_path = NULL;  /* optional: single file path inside repo (e.g. "src/code-includes.lua") */
+
+        if (normalized_repo) {
+            repo = normalized_repo;
+
+            fprintf(stderr,
+                    "Apex filters execute unverified code. Only install filters from trusted sources.\n"
+                    "Continue? (y/n) ");
+            fflush(stderr);
+            char answer[8] = {0};
+            if (!fgets(answer, sizeof(answer), stdin) ||
+                (answer[0] != 'y' && answer[0] != 'Y')) {
+                fprintf(stderr, "Aborted filter install.\n");
+                free(normalized_repo);
+                return 1;
+            }
+        } else {
+            /* Not a URL - look up in the remote filters directory */
+            const char *dir_url = "https://raw.githubusercontent.com/ApexMarkdown/apex-filters/refs/heads/main/apex-filters.json";
+            char *json = apex_remote_fetch_json(dir_url);
+            if (!json) {
+                fprintf(stderr, "Error: failed to fetch filter directory from %s\n", dir_url);
+                return 1;
+            }
+
+            /* Very small JSON scan: find entry with matching "id" and extract "repo" */
+            const char *p = json;
+            int found = 0;
+            while ((p = strstr(p, "\"id\"")) != NULL) {
+                const char *id_start = strchr(p, ':');
+                if (!id_start) break;
+                id_start++;
+                while (*id_start == ' ' || *id_start == '\t') id_start++;
+                if (*id_start != '\"') { p = id_start; continue; }
+                id_start++;
+                const char *id_end = strchr(id_start, '\"');
+                if (!id_end) break;
+                size_t id_len = (size_t)(id_end - id_start);
+
+                if (strlen(install_filter_id) == id_len &&
+                    strncmp(install_filter_id, id_start, id_len) == 0) {
+                    /* Found matching id; search for "repo" and optional "path" in this object */
+                    const char *obj_start = p;
+                    char *repo_val = apex_remote_extract_string(obj_start, "repo");
+                    if (!repo_val) {
+                        fprintf(stderr, "Error: filter '%s' missing repo URL in directory.\n", install_filter_id);
+                        free(json);
+                        return 1;
+                    }
+                    repo = repo_val;
+                    final_filter_id = strdup(install_filter_id);
+                    filter_path = apex_remote_extract_string(obj_start, "path");
+                    found = 1;
+                    break;
+                }
+                p = id_end;
+            }
+
+            if (!found) {
+                fprintf(stderr, "Error: filter '%s' not found in directory.\n", install_filter_id);
+                free(json);
+                return 1;
+            }
+            free(json);
+        }
+
+        /* Ensure root directory exists */
+        char mkdir_cmd[1200];
+        snprintf(mkdir_cmd, sizeof(mkdir_cmd), "mkdir -p \"%s\"", root);
+        int mkrc = system(mkdir_cmd);
+        if (mkrc != 0) {
+            fprintf(stderr, "Error: failed to create filter directory '%s'.\n", root);
+            if (normalized_repo) free(normalized_repo);
+            if (final_filter_id) free(final_filter_id);
+            if (filter_path) free(filter_path);
+            if (repo && repo != normalized_repo) free((void *)repo);
+            return 1;
+        }
+
+        /* Single-file install: clone to temp, copy path to root/<basename(path)>, remove temp */
+        if (filter_path && final_filter_id) {
+            const char *path_basename = strrchr(filter_path, '/');
+            path_basename = path_basename ? (path_basename + 1) : filter_path;
+            char final_file[1200];
+            snprintf(final_file, sizeof(final_file), "%s/%s", root, path_basename);
+            char test_cmd[1300];
+            snprintf(test_cmd, sizeof(test_cmd), "[ -e \"%s\" ]", final_file);
+            if (system(test_cmd) == 0) {
+                fprintf(stderr, "Error: filter '%s' already exists at %s. Remove it first to reinstall.\n", final_filter_id, final_file);
+                if (normalized_repo) free(normalized_repo);
+                if (final_filter_id) free(final_filter_id);
+                if (filter_path) free(filter_path);
+                if (repo && repo != normalized_repo) free((void *)repo);
+                return 1;
+            }
+            char temp_target[1200];
+            snprintf(temp_target, sizeof(temp_target), "%s/.apex_install_%s", root, final_filter_id);
+            char clone_cmd[2048];
+            snprintf(clone_cmd, sizeof(clone_cmd), "git clone --depth 1 \"%s\" \"%s\"", repo, temp_target);
+            int git_rc = system(clone_cmd);
+            if (git_rc != 0) {
+                fprintf(stderr, "Error: git clone failed for '%s'. Is git installed and the URL correct?\n", repo);
+                if (normalized_repo) free(normalized_repo);
+                if (final_filter_id) free(final_filter_id);
+                if (filter_path) free(filter_path);
+                if (repo && repo != normalized_repo) free((void *)repo);
+                return 1;
+            }
+            char src_file[1800];
+            snprintf(src_file, sizeof(src_file), "%s/%s", temp_target, filter_path);
+            char cp_cmd[3000];
+            snprintf(cp_cmd, sizeof(cp_cmd), "cp \"%s\" \"%s\"", src_file, final_file);
+            if (system(cp_cmd) != 0) {
+                fprintf(stderr, "Error: failed to copy '%s' from repo to %s\n", filter_path, final_file);
+                snprintf(cp_cmd, sizeof(cp_cmd), "rm -rf \"%s\"", temp_target);
+                system(cp_cmd);
+                if (normalized_repo) free(normalized_repo);
+                if (final_filter_id) free(final_filter_id);
+                if (filter_path) free(filter_path);
+                if (repo && repo != normalized_repo) free((void *)repo);
+                return 1;
+            }
+            char chmod_cmd[1300];
+            snprintf(chmod_cmd, sizeof(chmod_cmd), "chmod +x \"%s\"", final_file);
+            system(chmod_cmd);
+            snprintf(cp_cmd, sizeof(cp_cmd), "rm -rf \"%s\"", temp_target);
+            system(cp_cmd);
+            fprintf(stderr, "Installed filter '%s' into %s\n", final_filter_id, final_file);
+            if (normalized_repo) free(normalized_repo);
+            if (final_filter_id) free(final_filter_id);
+            if (filter_path) free(filter_path);
+            if (repo && repo != normalized_repo) free((void *)repo);
+            return 0;
+        }
+
+        /* Determine temporary or final target directory */
+        char temp_target[1200];
+        if (!final_filter_id) {
+            /* Derive a temporary name from repo URL */
+            const char *last_slash = strrchr(repo, '/');
+            const char *name_start = last_slash ? (last_slash + 1) : repo;
+            const char *name_end = strstr(name_start, ".git");
+            if (!name_end) name_end = name_start + strlen(name_start);
+            size_t name_len = name_end - name_start;
+            if (name_len > 0 && name_len < 200) {
+                char temp_name[256];
+                memcpy(temp_name, name_start, name_len);
+                temp_name[name_len] = '\0';
+                snprintf(temp_target, sizeof(temp_target), "%s/.apex_install_%s", root, temp_name);
+            } else {
+                snprintf(temp_target, sizeof(temp_target), "%s/.apex_install_temp", root);
+            }
+        } else {
+            snprintf(temp_target, sizeof(temp_target), "%s/%s", root, final_filter_id);
+        }
+
+        /* Refuse to overwrite existing directory when using a final id */
+        if (final_filter_id) {
+            char test_cmd[1300];
+            snprintf(test_cmd, sizeof(test_cmd), "[ -d \"%s\" ]", temp_target);
+            int exists_rc = system(test_cmd);
+            if (exists_rc == 0) {
+                fprintf(stderr, "Error: filter directory '%s' already exists. Remove it first to reinstall.\n", temp_target);
+                if (normalized_repo) free(normalized_repo);
+                if (final_filter_id) free(final_filter_id);
+                if (filter_path) free(filter_path);
+                if (repo && repo != normalized_repo) free((void *)repo);
+                return 1;
+            }
+        }
+
+        /* Clone repo using git */
+        char clone_cmd[2048];
+        snprintf(clone_cmd, sizeof(clone_cmd), "git clone \"%s\" \"%s\"", repo, temp_target);
+        int git_rc = system(clone_cmd);
+        if (git_rc != 0) {
+            fprintf(stderr, "Error: git clone failed for '%s'. Is git installed and the URL correct?\n", repo);
+            if (normalized_repo) free(normalized_repo);
+            if (final_filter_id) free(final_filter_id);
+            if (filter_path) free(filter_path);
+            if (repo && repo != normalized_repo) free((void *)repo);
+            return 1;
+        }
+
+        /* If we didn't get a final id from the directory, use install_filter_id as the final name */
+        if (!final_filter_id) {
+            final_filter_id = strdup(install_filter_id);
+            if (!final_filter_id) {
+                fprintf(stderr, "Error: Memory allocation failed\n");
+                if (normalized_repo) free(normalized_repo);
+                if (filter_path) free(filter_path);
+                if (repo && repo != normalized_repo) free((void *)repo);
+                return 1;
+            }
+        }
+
+        char final_target[1200];
+        snprintf(final_target, sizeof(final_target), "%s/%s", root, final_filter_id);
+
+        /* If temp_target != final_target, move into place */
+        if (strcmp(temp_target, final_target) != 0) {
+            char final_test_cmd[1300];
+            snprintf(final_test_cmd, sizeof(final_test_cmd), "[ -d \"%s\" ]", final_target);
+            int final_exists_rc = system(final_test_cmd);
+            if (final_exists_rc == 0) {
+                fprintf(stderr, "Error: filter directory '%s' already exists. Remove it first to reinstall.\n", final_target);
+                char rm_cmd[1300];
+                snprintf(rm_cmd, sizeof(rm_cmd), "rm -rf \"%s\"", temp_target);
+                system(rm_cmd);
+                free(final_filter_id);
+                if (normalized_repo) free(normalized_repo);
+                if (filter_path) free(filter_path);
+                if (repo && repo != normalized_repo) free((void *)repo);
+                return 1;
+            }
+
+            char mv_cmd[2500];
+            snprintf(mv_cmd, sizeof(mv_cmd), "mv \"%s\" \"%s\"", temp_target, final_target);
+            int mv_rc = system(mv_cmd);
+            if (mv_rc != 0) {
+                fprintf(stderr, "Error: failed to move filter to final location '%s'.\n", final_target);
+                char rm_cmd[1300];
+                snprintf(rm_cmd, sizeof(rm_cmd), "rm -rf \"%s\"", temp_target);
+                system(rm_cmd);
+                free(final_filter_id);
+                if (normalized_repo) free(normalized_repo);
+                if (filter_path) free(filter_path);
+                if (repo && repo != normalized_repo) free((void *)repo);
+                return 1;
+            }
+        }
+
+        fprintf(stderr, "Installed filter '%s' into %s\n", final_filter_id, final_target);
+
+        if (normalized_repo) free(normalized_repo);
+        if (final_filter_id) free(final_filter_id);
+        if (filter_path) free(filter_path);
+        if (repo && repo != normalized_repo) free((void *)repo);
+        return 0;
+        }
+    }
+
     /* mmd-merge mode: emulate MultiMarkdown mmd_merge.pl and exit */
     if (mmd_merge_mode) {
         FILE *out = stdout;
@@ -2604,9 +3421,11 @@ int main(int argc, char *argv[]) {
 
     /* Apply metadata to options - allows per-document control of command-line options */
     /* Note: Bibliography file loading from metadata will be handled in citations extension */
+    apex_output_format_t saved_output_format = options.output_format;
     if (merged_metadata) {
         apex_apply_metadata_to_options(merged_metadata, &options);
-        /* Restore bibliography files if they were lost (e.g., if mode was set in metadata) */
+        /* Restore explicit CLI choices that metadata mode reset */
+        options.output_format = saved_output_format;
         if (saved_bibliography_files && !options.bibliography_files) {
             options.bibliography_files = saved_bibliography_files;
         }
@@ -2622,6 +3441,232 @@ int main(int argc, char *argv[]) {
         options.enable_plugins = plugins_cli_value;
     }
 
+    /* Resolve AST filters configured from CLI into absolute command paths.
+     * Filters live in $XDG_CONFIG_HOME/apex/filters or ~/.config/apex/filters.
+     */
+    char **ast_filter_commands = NULL;
+    size_t ast_filter_count = 0;
+    if (run_all_filters_dir || ast_filter_name_count > 0 || lua_filter_count > 0) {
+        const char *xdg = getenv("XDG_CONFIG_HOME");
+        char root[1024];
+        if (xdg && *xdg) {
+            snprintf(root, sizeof(root), "%s/apex/filters", xdg);
+        } else {
+            const char *home = getenv("HOME");
+            if (!home || !*home) {
+                fprintf(stderr, "Error: HOME not set; cannot determine filters directory.\n");
+                return 1;
+            }
+            snprintf(root, sizeof(root), "%s/.config/apex/filters", home);
+        }
+
+        /* Ensure root directory exists when running --filters or --filter */
+        struct stat st_root;
+        if (stat(root, &st_root) != 0 || !S_ISDIR(st_root.st_mode)) {
+            if (run_all_filters_dir || ast_filter_name_count > 0) {
+                fprintf(stderr, "Error: filters directory '%s' does not exist.\n", root);
+                return 1;
+            }
+        }
+
+        /* Collect all filters from directory when --filters is set */
+        if (run_all_filters_dir) {
+            DIR *d = opendir(root);
+            if (!d) {
+                fprintf(stderr, "Error: cannot open filters directory '%s'\n", root);
+                return 1;
+            }
+            struct dirent *ent;
+            size_t capacity = 8;
+            ast_filter_commands = malloc(capacity * sizeof(char *));
+            if (!ast_filter_commands) {
+                closedir(d);
+                fprintf(stderr, "Error: Memory allocation failed\n");
+                return 1;
+            }
+            while ((ent = readdir(d)) != NULL) {
+                if (ent->d_name[0] == '.') continue;
+                char path[1200];
+                snprintf(path, sizeof(path), "%s/%s", root, ent->d_name);
+                struct stat st;
+                if (stat(path, &st) != 0 || !S_ISREG(st.st_mode)) {
+                    continue;
+                }
+                if (ast_filter_count == capacity) {
+                    capacity *= 2;
+                    char **tmp = realloc(ast_filter_commands, capacity * sizeof(char *));
+                    if (!tmp) {
+                        closedir(d);
+                        fprintf(stderr, "Error: Memory allocation failed\n");
+                        return 1;
+                    }
+                    ast_filter_commands = tmp;
+                }
+                ast_filter_commands[ast_filter_count] = strdup(path);
+                if (!ast_filter_commands[ast_filter_count]) {
+                    closedir(d);
+                    fprintf(stderr, "Error: Memory allocation failed\n");
+                    return 1;
+                }
+                ast_filter_count++;
+            }
+            closedir(d);
+        }
+
+        /* Resolve individual --filter NAME entries to absolute paths.
+         *
+         * Resolution rules:
+         *   - If root/NAME is a regular file, use that directly.
+         *   - If root/NAME is a directory, look for a script inside it:
+         *       root/NAME/NAME
+         *       root/NAME/NAME.lua
+         *       root/NAME/NAME.py
+         *       root/NAME/NAME.rb
+         *     and use the first regular file found.
+         */
+        if (ast_filter_name_count > 0) {
+            size_t capacity = (ast_filter_commands ? ast_filter_count : 0) + ast_filter_name_count;
+            if (!ast_filter_commands) {
+                ast_filter_commands = malloc(capacity * sizeof(char *));
+                if (!ast_filter_commands) {
+                    fprintf(stderr, "Error: Memory allocation failed\n");
+                    return 1;
+                }
+            } else {
+                char **tmp = realloc(ast_filter_commands, capacity * sizeof(char *));
+                if (!tmp) {
+                    fprintf(stderr, "Error: Memory allocation failed\n");
+                    return 1;
+                }
+                ast_filter_commands = tmp;
+            }
+
+            for (size_t i = 0; i < ast_filter_name_count; i++) {
+                const char *name = ast_filter_names[i];
+                char path[1200];
+                snprintf(path, sizeof(path), "%s/%s", root, name);
+                struct stat st;
+                int path_exists = (stat(path, &st) == 0);
+
+                char resolved[1400];
+                int  resolved_ok = 0;
+
+                /* Try root/NAME as regular file first */
+                if (path_exists && S_ISREG(st.st_mode)) {
+                    snprintf(resolved, sizeof(resolved), "%s", path);
+                    resolved_ok = 1;
+                }
+                /* Else try root/NAME.lua, root/NAME.py, root/NAME.rb as regular files (single-file installs) */
+                if (!resolved_ok) {
+                    const char *exts[] = { ".lua", ".py", ".rb" };
+                    for (size_t e = 0; e < sizeof(exts)/sizeof(exts[0]); e++) {
+                        char with_ext[1400];
+                        snprintf(with_ext, sizeof(with_ext), "%s/%s%s", root, name, exts[e]);
+                        struct stat ste;
+                        if (stat(with_ext, &ste) == 0 && S_ISREG(ste.st_mode)) {
+                            snprintf(resolved, sizeof(resolved), "%s", with_ext);
+                            resolved_ok = 1;
+                            break;
+                        }
+                    }
+                }
+                /* Else if root/NAME is a directory, look for script inside */
+                if (!resolved_ok && path_exists && S_ISDIR(st.st_mode)) {
+                    const char *candidates[4];
+                    char buf0[1400], buf1[1400], buf2[1400], buf3[1400];
+
+                    snprintf(buf0, sizeof(buf0), "%s/%s", path, name);
+                    snprintf(buf1, sizeof(buf1), "%s/%s.lua", path, name);
+                    snprintf(buf2, sizeof(buf2), "%s/%s.py", path, name);
+                    snprintf(buf3, sizeof(buf3), "%s/%s.rb", path, name);
+
+                    candidates[0] = buf0;
+                    candidates[1] = buf1;
+                    candidates[2] = buf2;
+                    candidates[3] = buf3;
+
+                    for (size_t c = 0; c < 4; c++) {
+                        struct stat stc;
+                        if (stat(candidates[c], &stc) == 0 && S_ISREG(stc.st_mode)) {
+                            snprintf(resolved, sizeof(resolved), "%s", candidates[c]);
+                            resolved_ok = 1;
+                            break;
+                        }
+                    }
+
+                    if (!resolved_ok) {
+                        fprintf(stderr,
+                                "Error: filter '%s' is a directory at %s but no executable script was found inside.\n",
+                                name, path);
+                        fprintf(stderr,
+                                "Tried: %s/%s, %s/%s.lua, %s/%s.py, %s/%s.rb\n",
+                                path, name, path, name, path, name, path, name);
+                        return 1;
+                    }
+                }
+                if (!resolved_ok) {
+                    fprintf(stderr, "Error: filter '%s' not found at %s (or %s.lua, %s.py, %s.rb)\n",
+                            name, path, path, path, path);
+                    return 1;
+                }
+
+                /* Lua scripts without shebang: run via `lua "path"` */
+                size_t rlen = strlen(resolved);
+                int is_lua = (rlen > 4 && strcmp(resolved + rlen - 4, ".lua") == 0);
+                if (is_lua) {
+                    char cmd[1400];
+                    snprintf(cmd, sizeof(cmd), "lua \"%s\"", resolved);
+                    ast_filter_commands[ast_filter_count] = strdup(cmd);
+                } else {
+                    ast_filter_commands[ast_filter_count] = strdup(resolved);
+                }
+                if (!ast_filter_commands[ast_filter_count]) {
+                    fprintf(stderr, "Error: Memory allocation failed\n");
+                    return 1;
+                }
+                ast_filter_count++;
+            }
+        }
+
+        /* Append explicit Lua filters as commands: `lua <script>` */
+        if (lua_filter_count > 0) {
+            size_t capacity = (ast_filter_commands ? ast_filter_count : 0) + lua_filter_count;
+            if (!ast_filter_commands) {
+                ast_filter_commands = malloc(capacity * sizeof(char *));
+                if (!ast_filter_commands) {
+                    fprintf(stderr, "Error: Memory allocation failed\n");
+                    return 1;
+                }
+            } else {
+                char **tmp = realloc(ast_filter_commands, capacity * sizeof(char *));
+                if (!tmp) {
+                    fprintf(stderr, "Error: Memory allocation failed\n");
+                    return 1;
+                }
+                ast_filter_commands = tmp;
+            }
+
+            for (size_t i = 0; i < lua_filter_count; i++) {
+                const char *script = lua_filter_paths[i];
+                /* Build a simple 'lua "<script>"' command */
+                char cmd[1400];
+                snprintf(cmd, sizeof(cmd), "lua \"%s\"", script);
+                ast_filter_commands[ast_filter_count] = strdup(cmd);
+                if (!ast_filter_commands[ast_filter_count]) {
+                    fprintf(stderr, "Error: Memory allocation failed\n");
+                    return 1;
+                }
+                ast_filter_count++;
+            }
+        }
+
+        if (ast_filter_count > 0) {
+            options.ast_filter_commands = (const char **)ast_filter_commands;
+            options.ast_filter_count = ast_filter_count;
+            options.ast_filter_strict = ast_filters_strict;
+        }
+    }
+
     /* Attach any collected script tags to options as a NULL-terminated array */
     if (script_tags) {
         /* Ensure NULL terminator */
@@ -2648,7 +3693,12 @@ int main(int argc, char *argv[]) {
         last_stage = NULL;
     }
 
-    /* Convert to HTML */
+    /* Man page output must keep -- as literal double hyphen; option names must not become en-dash */
+    if (options.output_format == APEX_OUTPUT_MAN || options.output_format == APEX_OUTPUT_MAN_HTML) {
+        options.enable_smart_typography = false;
+    }
+
+    /* Convert to output (HTML, Markdown, terminal, etc.) */
     char *html = apex_markdown_to_html(final_markdown, final_len, &options);
 
     /* Check if we should show delayed progress (in case processing took > 1s but no progress was shown) */
@@ -2675,9 +3725,61 @@ int main(int argc, char *argv[]) {
         return 1;
     }
 
-    /* Write output */
+    /* For terminal output, optionally wrap to a fixed width when requested.
+     * Precedence: CLI --width > metadata/config terminal.width > theme default.
+     * (Theme files are currently not consulted for width.)
+     */
+    if (options.output_format == APEX_OUTPUT_TERMINAL ||
+        options.output_format == APEX_OUTPUT_TERMINAL256) {
+        int effective_width = 0;
+        if (width_override > 0) {
+            effective_width = width_override;
+        } else if (options.terminal_width > 0) {
+            effective_width = options.terminal_width;
+        }
+        if (effective_width > 0) {
+            char *wrapped = wrap_ansi_to_width(html, effective_width);
+            if (wrapped) {
+                apex_free_string(html);
+                html = wrapped;
+            }
+        }
+    }
+
+    /* Determine whether to paginate terminal output.
+     * Pagination is only applied for terminal/terminal256 output when writing to stdout.
+     * Precedence: CLI -p/--paginate OR config/metadata paginate:true.
+     */
+    bool paginate_effective = false;
+    if (!output_file &&
+        (options.output_format == APEX_OUTPUT_TERMINAL ||
+         options.output_format == APEX_OUTPUT_TERMINAL256)) {
+        if (paginate_cli || options.paginate) {
+            paginate_effective = true;
+        }
+    }
+
+    /* Write output (optionally via pager) */
     PROFILE_START(file_write);
-    if (output_file) {
+    if (paginate_effective) {
+        const char *pager_cmd = getenv("APEX_PAGER");
+        if (!pager_cmd || !*pager_cmd) {
+            pager_cmd = getenv("PAGER");
+        }
+        if (!pager_cmd || !*pager_cmd) {
+            pager_cmd = "less -R";
+        }
+
+        FILE *pager = popen(pager_cmd, "w");
+        size_t html_len = strlen(html);
+        if (!pager) {
+            /* Fall back to direct stdout if pager cannot be started */
+            fwrite(html, 1, html_len, stdout);
+        } else {
+            fwrite(html, 1, html_len, pager);
+            pclose(pager);
+        }
+    } else if (output_file) {
         FILE *fp = fopen(output_file, "w");
         if (!fp) {
             fprintf(stderr, "Error: Cannot open output file '%s'\n", output_file);
@@ -2711,6 +3813,16 @@ int main(int argc, char *argv[]) {
         free(script_tags);
     }
 
+    /* Free AST filter command paths allocated for this run */
+    if (ast_filter_commands) {
+        for (size_t i = 0; i < ast_filter_count; i++) {
+            free(ast_filter_commands[i]);
+        }
+        free(ast_filter_commands);
+    }
+
+    /* lua_filter_paths entries are argv pointers; no need to free them here */
+
     /* Free base_directory if we allocated it */
     if (allocated_base_dir) {
         free(allocated_base_dir);