carve-lang 0.1.5 → 0.1.7

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e85e18bc41b0f896bb4ec2fc821c61a96b29b707ec1ef9bd3279d45d01150d9f
-  data.tar.gz: 67f1b5a6638be12cd89c34eab2809e94c6b8b4719ea3d6710cc6aaa3eceaf5ee
+  metadata.gz: e1129dd70ab09658be69bfbbf0158a02d599d9e814fb5e3f015be6d1a6cc5621
+  data.tar.gz: bc87753903ba603238e2c766b20c8384259dc8f44e87da90af4ef3f6d26ac613
 SHA512:
-  metadata.gz: d80a8c11324fc602247a5780f19f07662bb77eb4482b352c84e7f4e684896466672b84dd4011e1c3f29a134da723c2decaf66255472ffb57860876c3d82aeb0b
-  data.tar.gz: fd1fdb9b4a222d6b7e0a558c4733a07f745e8a45bbe73bbd2aa5fc4850727c8af1937a331ed305d3569626b912a113420f45263bd8bd8ccb759acc57453f0dbb
+  metadata.gz: f4f5180ccfda64b312e035b7302db7de20b52293466dd1719715d7ab9fcdfa06ba61b23e993d042df746ced604219bdb78cd5931e09a6dd25388ee9fffcac102
+  data.tar.gz: c1276c1504398c7be637fc9e6699b42217e0a3845f49e7647348650701abdc25148fe2138c49643171154d8834c184ef711b294bd3f3215db29de509299e127c

data/CHANGELOG.md

@@ -7,6 +7,78 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.1.7] - 2026-10-07
+
+### Changed
+
+- The engine is the published `carve-lang` 0.1.8 crate, up from 0.1.7. It closes
+  every row `resources/spec-drift.txt` declared: the gem renders all 2225 corpus
+  documents spec main declares byte-identically, where 0.1.7 rendered 30 of them
+  by a superseded rule. The ledger is empty again, which is the only state a tag
+  may ship.
+- **Breaking for a `Carve.to_html` consumer:** a heading cross-reference, a
+  numbered caption or equation reference, and a collapsed reference falling back
+  to heading text compare their target case exactly. `</#target>` against a
+  `# Target` heading no longer resolves and stays literal text; link-definition
+  labels, footnote labels and include fragment selectors already matched case
+  exactly. `carve fmt --migrate` in carve-rs repairs unambiguous case-only misses
+  (markup-carve/carve#2732, markup-carve/carve-rs#2320).
+- **Breaking for a `Carve.to_html` consumer:** a glossary reference matches its
+  term exactly and links to the matched entry, and two terms differing only in
+  case take two ids (markup-carve/carve#2739).
+- A render that blanks a denied destination scheme reports one
+  `destination-denied` loss, so a checked render of a `javascript:` destination
+  refuses where it used to pass. The emitted `href=""` does not move
+  (markup-carve/carve#2679).
+
+### Added
+
+- `Carve::EnginePanic`, a `StandardError` subclass raised when the engine
+  panics, so a host rendering untrusted input can rescue one and keep serving.
+  The message carries the panic text and its location in the engine source, and
+  the usual panic report still reaches stderr (#170).
+
+### Fixed
+
+- An engine panic arrives as a rescuable Ruby exception rather than `fatal`.
+  magnus catches the unwind but raises it as `fatal`, which no host can stop,
+  not even with `rescue Exception`, so any panic ended the process. The binding
+  now converts a caught panic itself (#170).
+- A line holding a single `|` followed by an attribute block, such as `|{.r}`,
+  renders as paragraph text. Under the 0.1.7 engine it panicked inside the table
+  check, and a panic crossing the FFI boundary reached Ruby as `fatal`, which
+  `rescue` cannot catch, so five bytes of input terminated the host process
+  (markup-carve/carve-rs#2341).
+
+## [0.1.6] - 2026-09-29
+
+### Changed
+
+- The engine is the published `carve-lang` 0.1.7 crate, up from 0.1.6. It closes
+  every row `resources/spec-drift.txt` declared: the gem renders all 2134 corpus
+  documents spec main declares byte-identically, where 0.1.6 rendered 158 of them
+  by a superseded rule. The ledger is empty again, which is the only state a tag
+  may ship (#151).
+- **Breaking for a `Carve.parse` consumer:** a footnote reference node spells its
+  target as `label`, where it spelled it `id`. PART 12 section 25 settles that
+  name on the definition, and every node also carries `attrs[:id]` for an
+  authored `{#x}`, so the old name stood for two unrelated values on one object.
+  `attrs[:id]` is untouched (markup-carve/carve-rs#1853).
+- **Breaking for a `Carve.parse` consumer:** a code block's `content` is the literal
+  payload text, so `a`, `a\n` and `a\n\n` stay distinct in the tree where they
+  collapsed to one shape, and an empty fence holds no newline. Rendered HTML is
+  unchanged (markup-carve/carve-rs#2191, markup-carve/carve-rs#2195).
+- `Carve.parse` publishes twelve further fields the tree gained: a fenced
+  blockquote, a loose definition list, a directive's kind and children, a line
+  block's attributes, an authored task state, a lone-image paragraph, a table's
+  columns and row groups, and a cell's colspan, rowspan and vertical alignment.
+- **Breaking for a `Carve.to_markdown` consumer:** the Markdown target follows
+  PART 11 section 11 for a GFM reader. A heading takes no `{#id}` suffix, and a
+  resolved cross-reference is written with the heading's GFM slug, so
+  `lowercase_heading_ids` no longer changes that anchor - the slug is the one a
+  GFM reader computes for itself. `Carve.to_html` still answers to the option
+  (markup-carve/carve-rs#2014).
+
 ## [0.1.5] - 2026-09-21
 
 ### Changed
@@ -287,7 +359,7 @@ are not listed, because no release ever shipped them.
   Frontmatter and footnote definitions are block nodes in `children` rather
   than root fields, which PART 12 §7 requires: a root field cannot carry the
   position §4 requires of every node, and both are source an editor navigates
-  to (carve#411, carve#418). Frontmatter is the first child, carrying `format`
+  to (markup-carve/carve#411, markup-carve/carve#418). Frontmatter is the first child, carrying `format`
   and **raw** `content` - not parsed key/values, which could not represent a
   `---toml` block at all. Anything reading `ast[:frontmatter]` or
   `ast[:footnoteDefs]` breaks.
@@ -296,9 +368,9 @@ are not listed, because no release ever shipped them.
   backslash escape is `{"type":"escaped_text","value":"-"}` instead of being
   folded into surrounding text - the backslash carries intent the character does
   not, since an author writes `\-\-` precisely so a consumer will not render an
-  en dash (carve#350). A `::: |` fence is `line_block` instead of a `div` with a
+  en dash (markup-carve/carve#350). A `::: |` fence is `line_block` instead of a `div` with a
   `.line-block` class, because inside it every newline is a hard break and a
-  class alone could not say which one a node was (carve#359). A block
+  class alone could not say which one a node was (markup-carve/carve#359). A block
   extension's `summary` is a list of inline nodes rather than a plain string,
   matching the admonition `title` shape. Definition lists publish
   `definition_term` and `definition_description` nodes
@@ -372,7 +444,9 @@ are not listed, because no release ever shipped them.
   Arrays (every AST node type is covered), enabling custom renderers such as
   [carve-hexapdf](https://github.com/markup-carve/carve-hexapdf).
 
-[Unreleased]: https://github.com/markup-carve/carve-rb/compare/v0.1.5...HEAD
+[Unreleased]: https://github.com/markup-carve/carve-rb/compare/v0.1.7...HEAD
+[0.1.7]: https://github.com/markup-carve/carve-rb/compare/v0.1.6...v0.1.7
+[0.1.6]: https://github.com/markup-carve/carve-rb/compare/v0.1.5...v0.1.6
 [0.1.5]: https://github.com/markup-carve/carve-rb/compare/v0.1.4...v0.1.5
 [0.1.4]: https://github.com/markup-carve/carve-rb/compare/v0.1.3...v0.1.4
 [0.1.3]: https://github.com/markup-carve/carve-rb/compare/v0.1.2...v0.1.3

data/README.md

@@ -1,387 +1,110 @@
 # carve (Ruby)
 
-Native Ruby bindings for the [Carve](https://github.com/markup-carve/carve)
-markup language. This gem is a thin native extension built with
-[magnus](https://github.com/matsadler/magnus) + [rb-sys](https://github.com/oxidize-rb/rb-sys)
-over the [carve-rs](https://github.com/markup-carve/carve-rs) engine. The parser
-is not reimplemented in Ruby; it calls into the Rust crate directly, mirroring
-how Djot's `djotter` gem wraps the `jotdown` crate.
+Native Ruby bindings for the
+[Carve](https://github.com/markup-carve/carve) markup language. The gem wraps
+the [carve-rs](https://github.com/markup-carve/carve-rs) engine through magnus
+and rb-sys rather than reimplementing the parser.
 
 ## Install
 
 ```ruby
-# Gemfile
 gem "carve-lang"
 ```
 
-```sh
+```bash
 bundle install
 ```
 
-Or install directly:
+The distribution name is `carve-lang`, while the require path is `carve`.
+Building from source requires Rust 1.75 or newer and Ruby development headers.
 
-```sh
-gem install carve-lang
-```
-
-Then `require "carve"` as normal - the gem distribution name is `carve-lang`
-but the require path stays `carve`.
-
-Building from source requires a **Rust toolchain** (`cargo`, Rust >= 1.75) and
-Ruby development headers. RubyGems compiles the native extension at install
-time via `rb_sys`.
-
-## Usage
+## Render Carve
 
 ```ruby
 require "carve"
 
 Carve.to_html("# Hello *world*")
-# => "<section id=\"Hello-world\">\n  <h1>Hello <strong>world</strong></h1>\n</section>"
-
-# Every core engine target is available from the binding.
 Carve.to_markdown(source)
 Carve.to_plain_text(source)
 Carve.to_ansi(source)
 Carve.to_carve(source)
-# Import reports use schema version 2, with fidelity and confidence per finding.
-# Markdown emits fidelity-unverified/dropped/fallback until its engine path
-# exposes construct-level fidelity.
-Carve.from_html('<p>Hello <strong>world</strong></p>')
-Carve.from_markdown('*em* and **strong**')
-
-# Carve syntax note: *...* is STRONG (bold), /.../ is EMPHASIS (italic).
-Carve.to_html("*bold* and /italic/")
-
-# Enable opt-in extensions (Symbols or Strings, snake_case or hyphenated):
-Carve.to_html(<<~CRV, extensions: [:math_block])
-  ```math
-  a^2 + b^2 = c^2
-  ```
-CRV
-
-Carve.to_html(src, extensions: %w[math-block list-table])
-```
-
-### Recognized extensions
-
-`Carve::EXTENSIONS` is the list, and it comes from the engine rather than from
-a copy kept here that could fall behind it:
-
-```ruby
-Carve::EXTENSIONS
-# => [:autolink, :citations, :"code-callouts", :"code-group", ...]
-```
-
-The canonical names are kebab-case (`:"math-block"`, `:"table-of-contents"`).
-Snake_case spellings (`:math_block`) work as arguments, as do the short aliases
-this binding has always taken: `:math`, `:permalinks`, `:mermaid`, `:dot`,
-`:graphviz`, `:chart`, `:toc`.
-
-An unknown extension name raises `ArgumentError`.
-
-### File includes
-
-Includes are opt-in and require an absolute containment root plus the absolute
-path of the source document. The result carries the rendered value, warnings,
-and root-relative dependencies. Other render methods leave include directives
-literal.
-
-```ruby
-result = Carve.to_html_with_includes(
-  File.read("book.crv"),
-  root: File.expand_path("."),
-  source_path: File.expand_path("book.crv"),
-  max_depth: 16,
-)
-puts result[:value]
 ```
 
-Every render option `Carve.to_html` takes is accepted here and reaches the
-included children too, so a document renders the same way whether or not it
-went through the include path: `extensions:`, `symbols:`, `profile:`, `mode:`,
-`renderers:`, `safe:` and `sections:`.
-
-`Carve.parse_with_includes` gives the expanded document as an AST instead, in
-the shape `Carve.parse` returns, for a host that walks the tree rather than
-rendering HTML:
+Options configure extensions, safe rendering, profiles, symbols, section
+wrappers, and custom renderers:
 
 ```ruby
-result = Carve.parse_with_includes(
-  File.read("book.crv"),
-  root: File.expand_path("."),
-  source_path: File.expand_path("book.crv"),
+Carve.to_html(
+  source,
+  extensions: %w[autolink list-table],
+  safe: true,
+  profile: "comment",
 )
-result[:value][:children]
 ```
 
-Its nodes carry no `:pos`, unlike `Carve.parse`. Spec I4 leaves position
-remapping out of scope in every engine, so a span on an included node would name
-an offset in a document the caller never passed.
-
-`Carve.render_with_includes` takes the same arguments plus `target:`, one of
-`"html"`, `"markdown"`, `"plain"`, `"ansi"` or `"ast"`. There is no `"carve"`
-target: spec I15 excludes the Carve writer from expansion, because inlining a
-child into the formatter's output rewrites the author's document rather than
-formatting it.
-
-The budgets `max_depth:`, `max_bytes:`, `max_resolver_calls:` and
-`max_warnings:` pass through to the engine; omit one to keep its default. A
-target refused by the byte budget still reports `resolved: true`, because
-section 19 charges the budget for what the resolver handed back and a target is
-resolved before its size is known.
-
-## Parsing to an AST
-
-`Carve.parse` returns the parsed document as a tree of Ruby Hashes and Arrays,
-for consumers that want to walk or transform the document rather than render
-HTML - for example a custom PDF renderer (see
-[`carve-hexapdf`](https://github.com/markup-carve/carve-hexapdf)).
-
-```ruby
-Carve.parse("# Hello *world*")
-# => {type: "document", frontmatter: {}, footnote_defs: {},
-#     children: [{type: "heading", level: 1,
-#                 children: [{type: "text", value: "Hello "},
-#                            {type: "emphasis", kind: "strong",
-#                             children: [{type: "text", value: "world"}], attrs: nil}],
-#                 attrs: nil}],
-#     source_len: 15}
-```
-
-Every node is a Hash with a `:type` key plus its fields; child collections are
-Arrays; `:attrs` is `nil` or a Hash of `{id:, classes:, key_values:}`. Keys are
-symbols. This is the raw parse tree (default profile, no extensions), so
-render-stage extension rewrites are not applied.
-
-## Static render mode + renderers
-
-By default `Carve.to_html` renders **interactive** HTML: client-script
-constructs (Mermaid/Graphviz/Chart diagrams, math) emit hydration elements
-(`<pre class="mermaid">`, ...) and disclosure stays collapsed (`<details>`).
-
-Pass `mode: :static` to emit **self-contained** HTML for print, PDF, or
-archival. Static mode forces disclosure (`<details open>`) and pre-renders
-client-script constructs through the `renderers:` callables you supply.
-
-```ruby
-Carve.to_html(<<~CRV, extensions: [:fenced_render], mode: :static,
-              renderers: { mermaid: ->(src) { "<svg>#{src}</svg>" } })
-  ```mermaid
-  graph TD; A-->B
-  ```
-CRV
-```
-
-### Renderer callable signatures
-
-The `renderers:` Hash is keyed by Symbol or String (see
-`Carve::RENDERER_KEYS`):
-
-| Key | Callable signature | Receives |
-| --- | ------------------ | -------- |
-| `:mermaid` | `(String) -> String` | the diagram source |
-| `:chart` | `(String) -> String` | the chart JSON source |
-| `:graphviz` | `(String) -> String` | the DOT / Graphviz source |
-| `:math` | `(String, display) -> String` | the TeX source and a `display` boolean (`true` for block / display math, `false` for inline) |
+`Carve::EXTENSIONS` reports the names accepted by the bundled engine. Unknown
+names raise `ArgumentError`.
 
-Each callable returns a self-contained HTML string (an `<svg>` / `<img>` for a
-diagram, MathML / HTML for math) that the engine emits **verbatim** on the
-static path.
+## Errors
 
-### Source fallback (graceful degradation)
+An invalid argument raises `ArgumentError`, and a render the engine refuses -
+input past a profile's `max_length`, or a denied construct - also raises
+`ArgumentError` with the engine's reason.
 
-When the renderer a construct needs is **absent**, or a supplied renderer
-**raises** or returns a **non-String**, the construct degrades to its source -
-never blank, and never raw HTML. The fallback source is **HTML-escaped**, so a
-construct body containing markup (e.g. `<img onerror=...>`) can never inject raw
-HTML. This is part of the cross-implementation graceful-degradation rollout
-(spec carve #205; siblings carve-js #242, carve-php #240, carve-rs #143,
-carve-py #1).
-
-An unknown `mode:` value or an unknown `renderers:` key raises `ArgumentError`.
-
-## Symbols
-
-A `:name:` symbol renders its literal `:name:` source unless the name is in the
-**symbols map** passed as `symbols:` (String or Symbol keys, String values):
-
-```ruby
-Carve.to_html("Ship it :rocket: :shrug:", symbols: { "rocket" => "🚀" })
-# => "<p>Ship it 🚀 :shrug:</p>"   (an unmapped name stays literal)
-```
-
-The leading word-boundary guard is unaffected by an active map: `a:b:c`,
-`10:30:` and `me@example.com` never become symbols. A non-String value raises
-`TypeError`.
-
-> **Security: symbol values are TRUSTED RAW output.**
-> A mapped value is inserted into the output **unescaped** - the same trust
-> class as a `renderers:` callable. `{ "b" => "<b>x</b>" }` emits a real `<b>`
-> element, not escaped text. This is deliberate (processor configuration is
-> trusted). **Never build a symbols map out of untrusted / user-supplied
-> input.**
-
-## Section wrappers
-
-A top-level heading is wrapped, along with the content following it up to the
-next same-or-shallower heading, in a `<section>` carrying the heading's id (spec
-PART 9 §13). Only the id moves - `{#install .featured}` gives
-`<section id="install"><h2 class="featured">` - and a heading inside a
-blockquote, div or list item is not wrapped at all.
-
-Pass `sections: false` to render headings flat, with the id back on the `<h*>`:
-
-```ruby
-Carve.to_html("# A\n\np\n")
-# => "<section id=\"A\">\n  <h1>A</h1>\n  <p>p</p>\n</section>"
-
-Carve.to_html("# A\n\np\n", sections: false)
-# => "<h1 id=\"A\">A</h1>\n<p>p</p>"
-```
-
-This is for a host whose CSS or JS assumes rendered blocks are direct children
-of the content container - the `.stack > * + *` spacing idiom, `:first-child`,
-`nth-child()` counting, DOM child walks - all of which stop matching once a
-wrapper sits in between. It is the one output change that breaks a document
-whose *source* migrated cleanly.
-
-Nothing else changes: ids, collision dedup, `</#id>` cross-references, implicit
-`[Heading][]` references and heading numbering all resolve against the slug
-rather than the element carrying it. The endnotes
-`<section role="doc-endnotes">` is a separate construct and is still emitted.
-
-## Untrusted input
-
-Carve's normative hardening is always on and needs no option: dangerous URL
-schemes are blanked, event-handler attributes like `onclick` are dropped, and the
-bidi override/isolate characters behind Trojan Source are removed from rendered
-text.
-
-Raw passthrough is the deliberate exception. A ` ```=html ` block or a
-`` `…`{=html} `` span renders **verbatim** by design, so it is the one thing
-input you did not author has to switch off:
+If the engine panics, the call raises `Carve::EnginePanic`, a `StandardError`
+subclass carrying the panic message and its location in the engine source. A
+panic means the engine reached a state it believed impossible, so the document
+is not renderable, but the process survives and a host can serve an error
+instead of losing the worker:
 
 ``` ruby
-Carve.to_html(user_input, safe: true, profile: :comment)
+begin
+  Carve.to_html(untrusted_source)
+rescue Carve::EnginePanic => e
+  logger.error("carve engine panic: #{e.message}")
+  "<p>This document could not be rendered.</p>"
+end
 ```
 
-`safe:` escapes those raw blocks and spans instead of emitting them. `profile:`
-restricts which constructs are allowed at all and caps input length -
-`:full`, `:article`, `:comment` or `:minimal`, String or Symbol. An unknown name
-raises `ArgumentError` rather than being ignored.
-
-A profile **rejection** raises too, rather than returning something that looks
-like output:
+Report any input that raises it: a panic is an engine defect, not a rejection.
 
-``` ruby
-Carve.to_html("x" * 20_000, profile: :minimal)
-# ArgumentError: Profile violations: 'document' is not allowed: max_length_exceeded (...)
-```
+## Migration and AST access
 
-That matters for untrusted input: the engine's infallible entry point answers a
-rejection with an empty String, which a caller cannot tell from a document that
-legitimately rendered to nothing.
+`Carve.from_html` and `Carve.from_markdown` return canonical Carve with
+structured fidelity reports. `Carve.parse` exposes a Ruby hash representation
+of the AST, and static rendering produces self-contained output for documents
+that do not load client-side renderers.
 
-Full recipe, defaults and threat model:
-[Security](https://markup-carve.github.io/carve/security).
+The [usage reference](docs/reference.md) documents AST fields, static
+rendering, symbols, wrappers, profiles, and the main methods.
 
-## Stored documents and spec versions
+## Includes
 
-`carve fmt --stamp` (in any Carve engine) records the spec version a document was
-last processed under. This gem reads that marker back, so a repository of stored
-`.crv` files can be checked for documents predating a breaking spec change:
+Includes are opt-in and require an absolute containment root plus the source
+document's absolute path:
 
-``` ruby
-Carve.read_stamp(source)
-# => {version: "0.1", generated_by: "carve-php 0.1.0"}
-
-Carve.needs_review?(source)   # true when the document predates this engine
-```
-
-An **unstamped** document answers `true`: its provenance is unknown, and assuming
-it is current is the unsafe direction. Both marker forms are read, and a marker
-written by any engine reads the same - the format is the contract, not any one
-API - so the answer matches carve-php, carve-js, carve-rs and carve-go on the
-same document.
-
-What a version difference means is the
-[versioning contract](https://markup-carve.github.io/carve/versioning): only
-`[behavior]` changelog entries between the stamped version and yours can require
-a document change.
-
-## API
-
-| Method | Description |
-| ------ | ----------- |
-| `Carve.to_html(source)` | Render Carve source to HTML. |
-| `Carve.parse(source)` | Parse Carve source into an AST (tree of Ruby Hashes/Arrays). |
-| `Carve.to_html(source, extensions: [...])` | Render with the named extensions enabled. |
-| `Carve.to_html(source, mode: :static, renderers: {...})` | Render self-contained static HTML with build-time renderers. |
-| `Carve.to_html(source, symbols: {...})` | Render with a `:name:` -> value symbol map (values are raw, see above). |
-| `Carve.to_html(source, safe: true, profile: :comment)` | Render untrusted input: escape `=html` raw blocks/spans, restrict constructs. |
-| `Carve.to_html(source, sections: false)` | Render headings flat, with the id on the `<h*>` instead of a `<section>` wrapper. |
-| `Carve.to_html_with_includes(source, root:, source_path:)` | Render contained file includes and return warnings and dependencies. |
-| `Carve.parse_with_includes(source, root:, source_path:)` | The same expansion, published as an AST instead of HTML. |
-| `Carve.render_with_includes(source, root:, source_path:, target:)` | The expansion over any render target: html, markdown, plain, ansi or ast. |
-| `Carve.read_stamp(source)` | Read a document's provenance marker: `{version:, generated_by:}` or `nil`. |
-| `Carve.needs_review?(source)` | Whether a document predates this engine's spec version (unstamped counts as yes). |
-| `Carve.to_html_with_extensions(source, names_array)` | Native primitive (Array of Strings). |
-| `Carve.to_html_full(source, names_array, mode_string, renderers_hash)` | Native static-mode primitive. |
-| `Carve.to_html_full_with_symbols(source, names_array, mode_string, renderers_hash, symbols_hash)` | Native primitive, static mode + symbol map. |
-| `Carve::VERSION` | Gem version. |
-| `Carve::EXTENSIONS` | Array of recognized extension symbols. |
-| `Carve::MODES` | Array of recognized render modes (`:interactive`, `:static`). |
-| `Carve::RENDERER_KEYS` | Array of recognized `renderers:` keys. |
-
-## Develop
-
-```sh
-bundle install
-rake compile   # builds the Rust extension into lib/carve/carve.so
-rake test      # runs the minitest suite
-```
-
-> [!NOTE]
-> The native build uses `rb_sys` + `bindgen` (libclang) to read Ruby's
-> headers. On systems where libclang cannot find its builtin C headers (the
-> `'stdarg.h' file not found` error), point it at the GCC builtin include dir:
->
-> ```sh
-> export BINDGEN_EXTRA_CLANG_ARGS="-I/usr/lib/gcc/x86_64-linux-gnu/13/include"
-> ```
->
-> (Adjust the GCC version directory to match your toolchain.)
-
-## carve-rs dependency pin
-
-`ext/carve/Cargo.toml` pins a specific carve-rs commit for reproducible gem
-builds:
-
-```toml
-carve_rs = { package = "carve-lang", git = "https://github.com/markup-carve/carve-rs", rev = "..." }
+```ruby
+result = Carve.to_html_with_includes(
+  File.read("book.crv"),
+  root: File.expand_path("."),
+  source_path: File.expand_path("book.crv"),
+)
 ```
 
-Read the current revision out of `ext/carve/Cargo.toml` rather than from a copy
-here. This section used to quote one, and it drifted three bumps behind the
-manifest before anyone noticed - a duplicated value goes stale the first time
-someone edits the original, and a stale one here is worse than none because it
-reads as authoritative.
+The result contains the value, warnings, and root-relative dependencies.
+Other render methods leave directives literal. See the
+[include reference](docs/reference.md#file-includes) for budgets, AST expansion,
+targets, and containment behavior.
 
-The crate is imported under the alias `carve_rs`. It is published as `carve-lang`
-(carve-rs renamed it from `carve`), so a pin at any revision past that rename
-needs `package = "carve-lang"` as above.
+## Security
 
-When bumping the `rev`, run `rake compile` and commit the resulting
-`ext/carve/Cargo.lock` in the same change. The lock records the resolved
-revision, so leaving it behind means every fresh clone gets a dirty working tree
-on its first build and the gem can resolve to a different engine than the one
-that was tested.
+Use `safe: true` and a restrictive profile for untrusted documents. Custom
+renderer callbacks and symbol values are trusted output and may emit raw HTML.
+The [untrusted-input reference](docs/reference.md#untrusted-input) describes
+resource limits and URL handling.
 
-Whether the pin is current is not a judgment call: CI runs the mandatory spec
-corpus through the compiled extension and requires byte-identical HTML, so a pin
-that has fallen behind fails a build. Locally:
+## Development
 
-```sh
-CARVE_SPEC_CORPUS=/path/to/carve/tests/corpus bundle exec rake test
-```
+Source builds, tests, and the carve-rs dependency pin are documented under
+[Development](docs/reference.md#develop) and
+[carve-rs dependency pin](docs/reference.md#carve-rs-dependency-pin).

data/ext/carve/Cargo.lock

@@ -37,22 +37,24 @@ checksum = "b4388bee8683e3d04af747c73422af53102d2bd24d9eadb6cbc100baef4b43f8"
 
 [[package]]
 name = "carve-lang"
-version = "0.1.6"
+version = "0.1.8"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "87fdad4ca9cefc502ad43595c578e09031d07be56280881ff0eb6c3cc59ca9fd"
+checksum = "0889683244be278df2ff8e1cd88e9f932036a424bb8d838546636b7f11e93903"
 dependencies = [
  "html5ever",
  "markup5ever_rcdom",
+ "memchr",
  "pulldown-cmark",
  "regex",
  "serde",
  "serde_json",
+ "smallvec",
  "unicode-normalization",
 ]
 
 [[package]]
 name = "carve-rb"
-version = "0.1.5"
+version = "0.1.7"
 dependencies = [
  "carve-lang",
  "magnus",

data/ext/carve/Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "carve-rb"
-version = "0.1.5"
+version = "0.1.7"
 edition = "2021"
 rust-version = "1.75"
 publish = false
@@ -22,4 +22,4 @@ serde_json = "1"
 # The Carve engine. Imported under the Rust crate alias `carve_rs` so the
 # binding's own crate name (`carve-rb`) does not collide with the engine's
 # package name (`carve`) in the Cargo lockfile.
-carve_rs = { package = "carve-lang", version = "=0.1.6" }
+carve_rs = { package = "carve-lang", version = "=0.1.8" }

data/ext/carve/src/lib.rs

@@ -27,8 +27,12 @@
 use carve_rs::extensions::registry;
 use carve_rs::{CarveExtension, Mode, Options, Profile, StaticRenderers};
 use magnus::value::{InnerValue, Opaque};
-use magnus::{function, prelude::*, Error, RArray, RHash, Ruby, Value};
+use magnus::{function, prelude::*, Error, ExceptionClass, RArray, RHash, Ruby, Value};
+use std::any::Any;
+use std::cell::RefCell;
+use std::panic::{self, AssertUnwindSafe};
 use std::path::{Path, PathBuf};
+use std::sync::Once;
 
 /// HTML-escape a string for the renderer-failure fallback path.
 ///
@@ -732,6 +736,192 @@ fn stamp_needs_review(source: String, current_version: Option<String>) -> bool {
     carve_rs::needs_review(&source, &current)
 }
 
+/// Panic deliberately inside the extension, so a test can observe the FFI
+/// panic contract rather than assuming it.
+///
+/// Nothing but a test calls this. It exists because no Carve input panics the
+/// pinned engine: the one that did (`|{.r}`) is fixed, and a test that cannot
+/// reach a panic cannot tell a working safety net from a missing one.
+fn panic_probe() -> String {
+    panic!("deliberate panic from the Carve extension panic probe");
+}
+
+// ---------------------------------------------------------------------------
+// FFI panic safety
+// ---------------------------------------------------------------------------
+//
+// magnus wraps every exposed call in catch_unwind, but `Error::from_panic`
+// raises the caught panic as Ruby's `fatal`, and Ruby does not let a host stop
+// a `fatal` -- not with `rescue Exception`, not with anything. So the unwind
+// that was supposed to protect the host still ends the process, and magnus
+// offers no way to choose a different class.
+//
+// Everything Ruby can reach therefore runs inside `guard`, which catches the
+// unwind FIRST and raises `Carve::EnginePanic` (a StandardError) instead. The
+// `panic = "unwind"` compile flag is still what makes any of this possible,
+// which is why `scripts/check-panic-unwind.sh` stays.
+
+thread_local! {
+    /// Where the most recent panic on this thread came from.
+    ///
+    /// The payload `catch_unwind` hands back carries the message but not the
+    /// location, and the location is the half that identifies the engine bug.
+    static PANIC_LOCATION: RefCell<Option<String>> = const { RefCell::new(None) };
+}
+
+/// Record panic locations without taking over panic reporting.
+///
+/// The previous hook still runs, so the `thread '<unnamed>' panicked at ...`
+/// line and any `RUST_BACKTRACE` output a developer relies on are unchanged.
+fn install_panic_hook() {
+    static ONCE: Once = Once::new();
+    ONCE.call_once(|| {
+        let previous = panic::take_hook();
+        panic::set_hook(Box::new(move |info| {
+            let location = info
+                .location()
+                .map(|l| format!("{}:{}:{}", l.file(), l.line(), l.column()));
+            PANIC_LOCATION.with(|slot| *slot.borrow_mut() = location);
+            previous(info);
+        }));
+    });
+}
+
+/// `Carve::EnginePanic`, or `RuntimeError` if the class cannot be looked up.
+///
+/// The fallback is still rescuable, which is the property that matters; losing
+/// the specific class is better than losing the process.
+fn engine_panic_class(ruby: &Ruby) -> ExceptionClass {
+    ruby.define_module("Carve")
+        .ok()
+        .and_then(|module| module.const_get::<_, ExceptionClass>("EnginePanic").ok())
+        .unwrap_or_else(|| ruby.exception_runtime_error())
+}
+
+/// Turn a caught unwind payload into a rescuable Ruby exception.
+fn engine_panic_error(payload: Box<dyn Any + Send>) -> Error {
+    let message = if let Some(m) = payload.downcast_ref::<&'static str>() {
+        (*m).to_string()
+    } else if let Some(m) = payload.downcast_ref::<String>() {
+        m.clone()
+    } else {
+        "panic".to_string()
+    };
+    let message = match PANIC_LOCATION.with(|slot| slot.borrow_mut().take()) {
+        Some(at) => format!("the Carve engine panicked at {at}: {message}"),
+        None => format!("the Carve engine panicked: {message}"),
+    };
+
+    // Unchecked for the same reason magnus does it in `Error::from_panic`: this
+    // only runs while a Ruby thread is calling into the extension.
+    let ruby = unsafe { Ruby::get_unchecked() };
+    Error::new(engine_panic_class(&ruby), message)
+}
+
+/// Run an exposed call with the panic net in front of magnus's.
+fn guard<T>(f: impl FnOnce() -> Result<T, Error>) -> Result<T, Error> {
+    match panic::catch_unwind(AssertUnwindSafe(f)) {
+        Ok(result) => result,
+        Err(payload) => Err(engine_panic_error(payload)),
+    }
+}
+
+/// Declare the guarded wrapper Ruby is given for an implementation function.
+///
+/// `=>` wraps an infallible implementation, `=>?` one that already returns
+/// `Result`. Registering a bare implementation instead of its wrapper would
+/// leave that one call raising `fatal` again, so `test/panic_unwind_test.rb`
+/// reads the `function!` registrations below and fails on any name that is not
+/// a `g_` wrapper.
+macro_rules! guarded {
+    ($wrapper:ident ( $($arg:ident : $ty:ty),* ) -> $ret:ty => $inner:ident) => {
+        #[allow(clippy::too_many_arguments)]
+        fn $wrapper($($arg: $ty),*) -> Result<$ret, Error> {
+            guard(|| Ok($inner($($arg),*)))
+        }
+    };
+    ($wrapper:ident ( $($arg:ident : $ty:ty),* ) -> $ret:ty =>? $inner:ident) => {
+        #[allow(clippy::too_many_arguments)]
+        fn $wrapper($($arg: $ty),*) -> Result<$ret, Error> {
+            guard(|| $inner($($arg),*))
+        }
+    };
+}
+
+guarded!(g_to_html(source: String) -> String => to_html);
+guarded!(g_to_markdown(source: String) -> String => to_markdown);
+guarded!(g_to_plain_text(source: String) -> String => to_plain_text);
+guarded!(g_to_ansi(source: String) -> String => to_ansi);
+guarded!(g_to_carve(source: String) -> String => to_carve);
+guarded!(g_from_markdown_json(source: String) -> String => from_markdown_json);
+guarded!(g_to_ast_json(source: String) -> String => to_ast_json);
+guarded!(g_extension_names() -> Vec<String> => extension_names);
+guarded!(g_panic_probe() -> String => panic_probe);
+guarded!(
+    g_stamp_needs_review(source: String, current_version: Option<String>) -> bool
+        => stamp_needs_review
+);
+guarded!(
+    g_from_html_json(ruby: &Ruby, source: String, mode: String) -> String =>? from_html_json
+);
+guarded!(g_read_stamp(ruby: &Ruby, source: String) -> Value =>? read_stamp);
+guarded!(
+    g_to_html_with_extensions(ruby: &Ruby, source: String, names: RArray) -> String
+        =>? to_html_with_extensions
+);
+guarded!(
+    g_to_html_full(
+        ruby: &Ruby,
+        source: String,
+        names: RArray,
+        mode: String,
+        renderers: RHash
+    ) -> String =>? to_html_full
+);
+guarded!(
+    g_to_html_full_with_symbols(
+        ruby: &Ruby,
+        source: String,
+        names: RArray,
+        mode: String,
+        renderers: RHash,
+        symbols: RHash
+    ) -> String =>? to_html_full_with_symbols
+);
+guarded!(
+    g_to_html_safe(
+        ruby: &Ruby,
+        source: String,
+        names: RArray,
+        mode: String,
+        renderers: RHash,
+        symbols: RHash,
+        safe: bool,
+        profile: Option<String>,
+        sections: bool
+    ) -> String =>? to_html_safe
+);
+guarded!(
+    g_render_with_includes_json(
+        ruby: &Ruby,
+        source: String,
+        root: String,
+        source_path: String,
+        target: String,
+        names: RArray,
+        mode: String,
+        renderers: RHash,
+        symbols: RHash,
+        safe: bool,
+        profile: Option<String>,
+        sections: bool,
+        max_depth: Option<usize>,
+        max_bytes: Option<usize>,
+        max_resolver_calls: Option<usize>,
+        max_warnings: Option<usize>
+    ) -> String =>? render_with_includes_json
+);
+
 /// Entry point invoked by Ruby when the extension is loaded.
 ///
 /// `name = "carve"` makes the macro emit the `Init_carve` symbol that matches
@@ -739,35 +929,43 @@ fn stamp_needs_review(source: String, current_version: Option<String>) -> bool {
 /// package is named `carve-rb`.
 #[magnus::init(name = "carve")]
 fn init(ruby: &Ruby) -> Result<(), Error> {
+    install_panic_hook();
+
     let module = ruby.define_module("Carve")?;
+    // Raised when the engine panics. A StandardError subclass on purpose:
+    // magnus would otherwise surface the panic as `fatal`, which no host can
+    // rescue, so an embedder taking untrusted input had no defense at all
+    // (markup-carve/carve-rb#170).
+    module.define_error("EnginePanic", ruby.exception_standard_error())?;
     // Native primitives. The pure-Ruby wrapper in lib/carve.rb defines the
     // public `Carve.to_html(source, extensions:, mode:, renderers:)` on top of
     // these. `_to_html` is the no-extension fast path; the wrapper owns the
     // bare `to_html` name.
-    module.define_singleton_method("_to_html", function!(to_html, 1))?;
-    module.define_singleton_method("to_markdown", function!(to_markdown, 1))?;
-    module.define_singleton_method("to_plain_text", function!(to_plain_text, 1))?;
-    module.define_singleton_method("to_ansi", function!(to_ansi, 1))?;
-    module.define_singleton_method("to_carve", function!(to_carve, 1))?;
+    module.define_singleton_method("_to_html", function!(g_to_html, 1))?;
+    module.define_singleton_method("to_markdown", function!(g_to_markdown, 1))?;
+    module.define_singleton_method("to_plain_text", function!(g_to_plain_text, 1))?;
+    module.define_singleton_method("to_ansi", function!(g_to_ansi, 1))?;
+    module.define_singleton_method("to_carve", function!(g_to_carve, 1))?;
     module.define_singleton_method(
         "_render_with_includes_json",
-        function!(render_with_includes_json, 15),
+        function!(g_render_with_includes_json, 15),
     )?;
-    module.define_singleton_method("_from_html_json", function!(from_html_json, 2))?;
-    module.define_singleton_method("_from_markdown_json", function!(from_markdown_json, 1))?;
-    module.define_singleton_method("_to_ast_json", function!(to_ast_json, 1))?;
+    module.define_singleton_method("_from_html_json", function!(g_from_html_json, 2))?;
+    module.define_singleton_method("_from_markdown_json", function!(g_from_markdown_json, 1))?;
+    module.define_singleton_method("_to_ast_json", function!(g_to_ast_json, 1))?;
     module.define_singleton_method(
         "to_html_with_extensions",
-        function!(to_html_with_extensions, 2),
+        function!(g_to_html_with_extensions, 2),
     )?;
-    module.define_singleton_method("to_html_full", function!(to_html_full, 4))?;
+    module.define_singleton_method("to_html_full", function!(g_to_html_full, 4))?;
     module.define_singleton_method(
         "to_html_full_with_symbols",
-        function!(to_html_full_with_symbols, 5),
+        function!(g_to_html_full_with_symbols, 5),
     )?;
-    module.define_singleton_method("_to_html_safe", function!(to_html_safe, 8))?;
-    module.define_singleton_method("_extension_names", function!(extension_names, 0))?;
-    module.define_singleton_method("_read_stamp", function!(read_stamp, 1))?;
-    module.define_singleton_method("_stamp_needs_review", function!(stamp_needs_review, 2))?;
+    module.define_singleton_method("_to_html_safe", function!(g_to_html_safe, 8))?;
+    module.define_singleton_method("_extension_names", function!(g_extension_names, 0))?;
+    module.define_singleton_method("_read_stamp", function!(g_read_stamp, 1))?;
+    module.define_singleton_method("_stamp_needs_review", function!(g_stamp_needs_review, 2))?;
+    module.define_singleton_method("_panic_probe", function!(g_panic_probe, 0))?;
     Ok(())
 }

data/lib/carve/version.rb

@@ -8,5 +8,5 @@ module Carve
   # compares it against ext/carve/Cargo.toml and against the newest cut
   # CHANGELOG section on every run, and .github/workflows/release.yml refuses to
   # publish a gem whose version is not the tag being released.
-  VERSION = "0.1.5"
+  VERSION = "0.1.7"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: carve-lang
 version: !ruby/object:Gem::Version
-  version: 0.1.5
+  version: 0.1.7
 platform: ruby
 authors:
 - markup-carve
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-09-23 00:00:00.000000000 Z
+date: 2026-10-07 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rb_sys