From 01059281e3f7534b8701edb9b10e05901c074247 Mon Sep 17 00:00:00 2001
From: Colin Rundel <rundel@gmail.com>
Date: Wed, 13 May 2026 19:12:40 -0400
Subject: [PATCH] feat(pampa): make quarto-system-runtime optional via
 `filters` feature
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Library consumers that only need the parser and writers could not build
on Linux x86_64 as a `cdylib` because pampa unconditionally re-exported
`unified_filter`, which pulls `quarto-system-runtime` → `deno_core` →
the prebuilt v8 static archive. Linking v8's local-exec TLS into a
shared object fails with `R_X86_64_TPOFF32`.

Gate the filter pipeline behind a new `filters` feature: mark
`quarto-system-runtime` optional, gate `pub mod citeproc_filter` and
`pub mod unified_filter` on `feature = "filters"`, and route both
`json-filter` and `lua-filter` through it. Default features are
unchanged, so binaries and existing library consumers see the same
dep graph. Parser-only consumers can opt out with
`default-features = false`.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---
 crates/pampa/Cargo.toml | 10 +++++++---
 crates/pampa/README.md  | 16 ++++++++++++++++
 crates/pampa/src/lib.rs |  2 ++
 3 files changed, 25 insertions(+), 3 deletions(-)

diff --git a/crates/pampa/Cargo.toml b/crates/pampa/Cargo.toml
index bfdba9461..a8398dd6c 100644
--- a/crates/pampa/Cargo.toml
+++ b/crates/pampa/Cargo.toml
@@ -25,10 +25,14 @@ cargo-fuzz = true
 default = ["terminal-support", "json-filter", "lua-filter", "template-fs"]
 terminal-support = ["dep:crossterm", "dep:supports-hyperlinks"]
 terminal-hyperlinks = ["dep:supports-hyperlinks"]
+# Enable filter pipeline support (pulls in quarto-system-runtime / deno_core / v8).
+# Parser-only consumers can disable this with `default-features = false` to avoid
+# the v8 link dependency, which is problematic in shared-library builds on Linux.
+filters = ["dep:quarto-system-runtime"]
 # Enable JSON filter support (requires subprocess spawning, disable for WASM)
-json-filter = []
+json-filter = ["filters"]
 # Enable Lua filter support (disable for WASM, where mlua is not available)
-lua-filter = ["dep:mlua"]
+lua-filter = ["filters", "dep:mlua"]
 # Enable filesystem-based template resolution (disable for WASM)
 template-fs = []
 
@@ -49,7 +53,7 @@ quarto-ast-reconcile = { path = "../quarto-ast-reconcile" }
 quarto-doctemplate = { workspace = true }
 quarto-citeproc = { path = "../quarto-citeproc" }
 quarto-csl = { path = "../quarto-csl" }
-quarto-system-runtime = { workspace = true }
+quarto-system-runtime = { workspace = true, optional = true }
 regex = { version = "1.12.3", features = ["unicode"] }
 clap = { version = "4.5", features = ["derive"] }
 serde = { workspace = true, features = ["derive"] }
diff --git a/crates/pampa/README.md b/crates/pampa/README.md
index 7850038ae..4bc445c57 100644
--- a/crates/pampa/README.md
+++ b/crates/pampa/README.md
@@ -84,6 +84,22 @@ We will, aspirationally, treat unintentional differences as bugs.
 The "reader" syntax allows users to recover the exact Pandoc markdown behavior when desired.
 With this feature, however, other quarto-markdown conveniences will be absent: no error messages, source tracking, etc.
 
+## Library usage
+
+When used as a library, pampa's default features include filter support
+(`json-filter`, `lua-filter`), which transitively pull in
+`quarto-system-runtime` and `deno_core`. Parser-only consumers (e.g. tooling
+that only needs the qmd reader and writers) can opt out:
+
+```toml
+[dependencies]
+pampa = { ..., default-features = false }
+```
+
+This drops the v8 link dependency, which avoids shared-library link failures
+on Linux x86_64 (`R_X86_64_TPOFF32` against v8 TLS symbols) for consumers
+building a `cdylib`.
+
 ## Current state
 
 Parses [quarto-web](https://github.com/quarto-dev/quarto-web) with a small number of changes
diff --git a/crates/pampa/src/lib.rs b/crates/pampa/src/lib.rs
index a214c6f00..3062f1d06 100644
--- a/crates/pampa/src/lib.rs
+++ b/crates/pampa/src/lib.rs
@@ -6,6 +6,7 @@
  * Copyright (c) 2025 Posit, PBC
  */
 
+#[cfg(feature = "filters")]
 pub mod citeproc_filter;
 pub mod errors;
 pub mod filter_context;
@@ -21,6 +22,7 @@ pub mod template;
 pub mod toc;
 pub mod transforms;
 pub mod traversals;
+#[cfg(feature = "filters")]
 pub mod unified_filter;
 pub mod utils;
 pub mod wasm_entry_points;