carve-lang 0.1.10-arm64-darwin

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 86eef0770ac1b9531bfea6931d7c467c6e61e1fc09ba069eafaaa45e3ffd9c3b
+  data.tar.gz: 429fe9a681b71ff7cbff437f303006f41d53b3f0949571d97eb00f507fe50860
+SHA512:
+  metadata.gz: 93a749f4aa83892c233ffdc9e8e4a0f2fc8fd78b2ddafe0176ce0f839a9e243289493f966f824729e1bc8e082f2933f9382020dd551ad4cb6e65bc05680c3923
+  data.tar.gz: d09698dcac343bf51d650258eb71209ff7671c74690fcc77c236cd7b4895b15cd773e3704c4ded6da5d40264bd7093932d4a35a71353247be41a518956d7f859

data/CHANGELOG.md

@@ -0,0 +1,541 @@
+# Changelog
+
+All notable changes to this project are documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.1.10] - 2026-10-23
+
+### Breaking
+
+- The engine is the published `carve-lang` 0.1.11 crate. A quote-prefixed `+`
+  needs one space after each `>`, so `>+` and `>>+` now render as text, and a
+  continuation marker reads only at column 0 or right after a block opener.
+  Re-check documents that place `+` elsewhere (#215, markup-carve/carve#3421).
+- Includes of a file that is not valid UTF-8 are refused with an
+  `include-non-text` warning instead of being spliced (#215,
+  markup-carve/carve-rs#2885).
+
+### Fixes
+
+- The carve-lang 0.1.11 pin corrects container ownership for quotes, lazy lines,
+  colon divs and footnotes, fences inside nested lists and quotes, and list
+  tightness around captions (#215).
+- Includes see through a byte order mark and keep link definitions and region
+  markers in place. Markdown import keeps link destinations, autolink brackets
+  and pipe escapes as written (#215).
+- `Carve.render_with_includes` with the `markdown`, `plain` and `ansi` targets
+  keeps a link definition where it was written, as `Carve.to_markdown` does,
+  instead of moving it to the end (#221).
+
+### Improvements
+
+- Precompiled gems for `x86_64-linux`, `x86_64-linux-musl`, `aarch64-linux`,
+  `x86_64-darwin`, `arm64-darwin` and `x64-mingw-ucrt` install without a Rust
+  toolchain on Ruby 3.0 to 4.0 (#214).
+- `Carve.to_carve(source, align_tables: true)` pads table columns to display
+  width (#215).
+- `Carve.select_include_region(source, name, mode:)` resolves a named
+  `@region` to a Range of content lines and raises `Carve::IncludeRegionError`
+  for a missing or malformed region (#215).
+- An include with `@code` or `@code:lang` splices a file or region as one code
+  block (#215).
+- Include warnings carry `includedBy`, the chain of directives that reached the
+  file the warning arose in, with root-relative paths, lines and columns (#221).
+
+## [0.1.9] - 2026-10-18
+
+### Breaking
+
+- `Carve.parse` and AST include results carry `astVersion: "1.2"` on the root.
+  Exact-key readers must accept the new field (#210).
+- The carve-lang 0.1.10 pin adds `resolved` to resolved link and image references
+  and `form` to comments. `[text]()` and `![alt]()` render as links and images,
+  and a bare `[r]:` defines an empty destination. Escape `\[` to keep that
+  spelling literal. Checked render reports can also include
+  `table-span-flattened`, `table-header-row-demoted`,
+  `table-header-row-hoisted`, and `table-header-cell-demoted` (#207).
+
+### Fixes
+
+- Source strings in other encodings such as Shift_JIS are transcoded to UTF-8.
+  Malformed UTF-8 and binary bytes become replacement characters instead of
+  failing at the native boundary (#207).
+
+### Improvements
+
+- The carve-lang 0.1.10 pin adds CSV and TSV table fences and keeps plain-text
+  list continuation blocks at their item's indentation. It also corrects
+  parsing of nested lists with quotes and containers (#207).
+
+## [0.1.8] - 2026-10-14
+
+### Breaking
+
+- The engine is the published `carve-lang` 0.1.9 crate, so the AST follows contract 1.1: a cell joined across lines holds a `cell_wrap` node between its text halves, tables carry `separatorWidths`, and `delim` and `bulletChar` appear only for `)` and `*` (#200, markup-carve/carve-rs#2482).
+- New loss codes such as `carrier-attribute-dropped`, `list-style-dropped` and `frontmatter-synthesized`. A check that fails on unknown codes has to list them (#200, markup-carve/carve-rs#2523).
+- Image alt text and quoted include paths decode punctuation escapes, so double a literal backslash. The include rename warning's rule id is now `include-id-rename` instead of `include-heading-id-rename` (#184, markup-carve/carve#2772).
+
+### Fixes
+
+- A Markdown writer refusal raises `ArgumentError` instead of panicking in the engine (#184).
+- Adjacent alphabetic and Roman ordered lists stay separate through HTML import and formatting (#185).
+- Under the article profile, denied raw blocks become code blocks that keep their payload (#185).
+
+### Improvements
+
+- Markdown import reports assess construct fidelity, including preserved constructs as well as losses (#185).
+- Ordered lists keep a `)` delimiter as `data-delim` in HTML and through Markdown import (#185).
+
+## [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
+
+- The engine comes from the published `carve-lang` 0.1.6 crate on crates.io
+  instead of a carve-rs git revision. `gem install carve-lang` no longer
+  fetches from GitHub while it compiles the extension. The engine code is the
+  same carve-rs 0.1.6 the previous release pinned by revision (#136).
+
+## [0.1.4] - 2026-09-19
+
+### Added
+
+- `Carve.to_html_with_includes` renders a file-backed document with its
+  `{{ path }}` directives expanded, contained to an absolute root the caller
+  names. It returns the rendered HTML alongside sanitized warnings and
+  root-relative dependencies, and forwards extension and include budget
+  settings to the engine. The binding canonicalizes the root and the source
+  path and requires the source to sit inside the root (#123, #125).
+- `Carve.parse_with_includes` publishes the expanded document as a tree, in the
+  shape `Carve.parse` returns, and the include path takes the same render
+  options the string entry points take. A consumer that draws from the tree
+  rather than from HTML, such as carve-hexapdf, was blocked without it. Its
+  nodes carry no `pos`: spec I4 leaves position remapping across an include out
+  of scope in every engine (#126, #127).
+
+### Changed
+
+- HTML and Markdown migration reports use schema version 2 with shared
+  preserved, normalized, degraded, and dropped fidelity plus confidence.
+  Markdown retains the existing `source_format` key as a compatibility alias
+  for the shared `sourceFormat` spelling and now emits a conservative
+  `fidelity-unverified` dropped/fallback finding on every import instead of
+  the previous empty diagnostics array (#117).
+- **Breaking:** A substitution node in the tree carries `old` and `new` as
+  arrays of inline nodes, where it carried the strings `oldText` and `newText`.
+  A caller reading that node walks the halves instead of reading them (#130,
+  markup-carve/carve-rs#1756).
+- The engine moves from carve-rs `42df4092` to released 0.1.6 (`d7837249`).
+  Beyond the substitution change, the range brings the include pass this
+  release exposes, mention and tag handling (a nameless mention or tag is
+  dropped and reported, an unspellable name is refused, attributes survive the
+  editor bridge), and writer and parser fixes: the Markdown and Carve writers
+  escape what would reopen a construct on the way back in, and parsing tightens
+  around braced inlines, forced closers, escaped markers, adjacent links, blank
+  table rows and a code span's closer. 1740 of 1740 corpus documents render
+  byte-identically, and `resources/spec-drift.txt` is empty.
+
+## [0.1.3] - 2026-09-08
+
+### Changed
+
+- The engine moves from carve-rs `da45f9d2` to `42df4092`, 46 commits, clearing
+  the binding-parity drift the nightly run found on 34 corpus documents (#110).
+  A comment leaf span begins at its markup, an emptied definition description
+  narrows to its marker line, a footnote nested past a footnote body becomes its
+  own note, a nested item's lead fence or colon container takes its flush-left
+  body, and an all-blank or lone-pipe row is no longer read as a table (the lone
+  pipe no longer panics).
+- The engine moves from carve-rs `2e9c43f2` to `da45f9d2`, 20 commits. A colon
+  followed by a space and a tab opens no description, an authored task state
+  reaches the tree and the HTML, a titled medium emits one title attribute, an
+  empty external link target is omitted, and a table continuation survives Djot
+  migration. The stale pin is what failed PART 12 binding parity in
+  markup-carve/carve#1877 - a binding has no vote of its own.
+
+## [0.1.2] - 2026-08-27
+
+### Security
+
+- The gem is published through RubyGems trusted publishing rather than a
+  long-lived API key, and the gemspec sets `rubygems_mfa_required`, so RubyGems
+  refuses a push from an account without MFA (#81).
+
+### Changed
+
+- The engine moves from carve-rs `0.1.3` (`a33c42ad`), which `0.1.1` shipped, to
+  `bd19414d` - 106 commits across four pin bumps (#80, #82, #84, #87). Rendering
+  changes an existing document can see: a column's alignment defaults come from
+  the header section, an explicit alignment run is validated and inherited, and
+  a table cell's marker run must end at a space; tables gained semantic row
+  partitions and a list table can carry local headers; a braced hyphen pair is
+  an en dash, an empty brace pair is text, and the doubled run is the canonical
+  arrow; a hyphen run opening a word after whitespace is a flag, not a dash; a
+  continuation marker attaches only a flush-left block; the footnote backlink
+  has an accessible name; a caption no longer disables a diagram fence's preset;
+  the first code group is numbered like every other one; a heading at a content
+  column leaves no paragraph open, and a definition at a list item's content
+  column closes its paragraph; an all-blank raw payload stays distinct from an
+  absent one; and depth limits guard every recursive parse, render and AST-JSON
+  path. `<thead>` and `<tfoot>` also write one row per line, which changes the
+  emitted HTML without changing what it renders. The last bump adds: three blank
+  lines are a hard list boundary rather than a wide gap between two items, so a
+  document that used the run as spacing now parses as two lists; a heading id
+  can opt in to ASCII folding; a tab control renders as a button and a code
+  group takes the mode option; and a `%%` line a verbatim run has already
+  swallowed no longer produces a comment node after that run, which changes the
+  tree without changing the HTML (#84).
+  The fourth bump is 18 further commits, and over the spec corpus exactly one
+  document's HTML moves with it: a list marker at an item's content column
+  opens a sublist whether or not it is the item's first, so a marker that
+  follows a blank line and a paragraph inside an item no longer joins that
+  paragraph (markup-carve/carve-rs#1251). A further 104 documents change only
+  their reported positions, because a container's span now starts at its
+  opening markup and ends at its last placed child, and a definition list's
+  likewise (markup-carve/carve-rs#1238, markup-carve/carve-rs#1248,
+  markup-carve/carve-rs#1252). Nothing else an existing document can see
+  changes (#87).
+- The engine then moves from `bd19414d` to `f2fbb24c` - 39 further commits
+  (#91). A container with no closer ends at its last placed child rather than
+  one codepoint past it, which is the PART 12 §4 extent defect this gem was
+  still the one implementation reporting (markup-carve/carve-rs#1308, #89); a
+  footnote continuation survives a blank run (markup-carve/carve-rs#1295); and
+  a list takes PART 9 §17 L7's consumed `loose` attribute, which loosens the
+  list instead of being emitted on it and which `Carve.parse` publishes on a
+  definition list as a `loose` field (markup-carve/carve-rs#1304). Seven corpus
+  documents move with the bump and all seven are documents the corpus gained,
+  so nothing that already rendered correctly changed.
+- The embedded engine moves to carve-rs `42a952cb`. An indented lone image now
+  parses as a paragraph holding an inline image rather than a block image
+  (markup-carve/carve#1660, markup-carve/carve-rs#1347). AST only - the
+  rendered HTML is unchanged on every corpus document (#93).
+- The embedded engine moves from `42a952cb` to `468e71af` - 70 further commits
+  across three pin bumps (#96, #97, #98), and each of the three changes what an
+  existing document renders as. The first two settle one rule between them: a
+  list item's content column is measured from the bare marker, so neither the
+  task checkbox nor a marker-attached attribute block widens it
+  (markup-carve/carve-rs#1364, markup-carve/carve-rs#1374,
+  markup-carve/carve-rs#1379). `-{#k} [x] a` has content column 2, so a `# h`
+  written under it at column 2 opens a heading inside the item where the wider
+  column made it lazy paragraph text. Also in those two: a lone image at an
+  item's content column keeps the item's looseness, restoring the `<p>` wrapper
+  the item used to drop (markup-carve/carve-rs#1359); the ANSI quote bar
+  reports containment, so a quoted heading, code block, table, thematic break
+  and lone image keep the bar and a quoted list's bar sits outside its marker
+  (markup-carve/carve-rs#1363); and on the import side an imported heading
+  records its id, an imported task item comes back a task item, an input's type
+  matches the checkbox keyword case-insensitively, an HTML comment imports as a
+  Carve comment, and an imported code block no longer gains a trailing blank
+  line on every pass (markup-carve/carve-rs#1361, markup-carve/carve-rs#1366,
+  markup-carve/carve-rs#1378, markup-carve/carve-rs#1386,
+  markup-carve/carve-rs#1384).
+  The third bump is 44 commits on its own, and rendered HTML moves on 50 corpus
+  documents with it. Measured against the corpus's own expected output at the
+  spec the new pin pins, the old pin differed on all 50 and the new pin on
+  none, so those 50 were being rendered wrongly and this is a correctness fix
+  rather than a preference. What an author notices is that a recognized block
+  opener written past a container's content column now opens that block inside
+  the container instead of folding into text: an indented `> q` under a list
+  item wrote `<p>&gt; q</p>` and now writes a block quote, an indented `# h`
+  wrote `<p># h</p>` and now writes a heading, an indented code fence folded
+  into inline code inside a paragraph and now writes a `<pre>` block, and a
+  tab-indented `> quote` wrote text on the item's own line and now writes a
+  block quote; where a blank line preceded the block, the item is no longer
+  reported loose either. The same authored base applies inside a footnote body
+  and a definition description, so a table or a link reference definition
+  written past the body's column registers there (markup-carve/carve-rs#1387,
+  markup-carve/carve-rs#1420, markup-carve/carve-rs#1422,
+  markup-carve/carve-rs#1425, markup-carve/carve-rs#1431,
+  markup-carve/carve-rs#1432, markup-carve/carve-rs#1433, measured over the
+  corpus that markup-carve/carve-rs#1417 pins). Four further changes an
+  existing document can see ride along: an explicit id or class may begin with
+  an ASCII digit, so `::: 123` opens a div with that class instead of staying a
+  paragraph (markup-carve/carve-rs#1393); `::: >` spells a block quote with no
+  marker column, and its closing fence takes a caption
+  (markup-carve/carve-rs#1399, markup-carve/carve-rs#1411); reference and
+  footnote labels differing only in ASCII whitespace resolve to one definition
+  (markup-carve/carve-rs#1397); and `{align=left|right|center}` on an element
+  whose `align` means text alignment renders a CSS declaration rather than the
+  deprecated presentational attribute (markup-carve/carve-rs#1412).
+  `Carve.to_carve` also writes one space after a definition separator
+  (markup-carve/carve-rs#1426) (#98).
+- The final release pin moves from `0c54d2ea` to the released carve-rs 0.1.4
+  (`2e9c43f2`). This closes every declared spec-drift window: link and
+  abbreviation definitions below a definition body's column follow the same
+  folding rule, a comment in a footnote body leaves no blank line behind, the
+  continuation marker's column gate reaches every container, an empty
+  description body writes the `{empty}` sentinel, citation items are typed and
+  positioned, and paragraph block-image promotion is published on the AST.
+- The stale pin is what made this gem the only implementation failing PART 12
+  conformance in markup-carve/carve#1451 - a binding has no vote of its own, and
+  this one was voting with an engine 28 commits behind (#82). It recurred within
+  two days, on three documents and a pin one day old, because nothing in this
+  repository compares the tree this gem produces against the engine's own (#84).
+  It recurred again the next day, on one document, with that comparison still
+  unmerged (#86) and the pin 18 commits behind (#87). It recurred twice more
+  inside this window: at 39 commits behind, still carrying the PART 12 §4
+  extent defect (#89, #91), and again on a ruling only the tree can see,
+  which a byte-for-byte HTML comparison cannot detect (#93).
+
+### Added
+
+- `Carve.from_html(source, mode: :safe)` and `Carve.from_markdown(source)`
+  import an existing document into canonical Carve (#92). Both return the
+  shared migration shape `{value:, report:}`: `value` is the Carve source, and
+  `report` carries `diagnostics`, each with `code`, `message`, `severity` and,
+  where the engine placed one, `path`. `from_html` takes `:safe`, `:semantic`
+  or `:roundtrip` and reports back the `mode` and `adapter` it ran with; any
+  other mode raises `ArgumentError`. `from_markdown` reports
+  `source_format: "markdown"` and diagnoses nothing.
+- `Carve.to_markdown`, `to_plain_text`, `to_ansi` and `to_carve`, so every core
+  render target the embedded engine already understood is reachable from Ruby
+  (#88). `Carve.to_html` and the AST entry points are unchanged.
+
+## [0.1.1] - 2026-08-18
+
+Everything below is the delta from `v0.1.0`, which is the only version a
+reader can be upgrading from. The engine pin moved seven times inside this
+window and lands on carve-rs `0.1.3` (`a33c42ad`); the intermediate revisions
+are not listed, because no release ever shipped them.
+
+### Security
+
+- **A list-valued URL attribute is probed at every candidate, not at its head**
+  (PART 9 §25, markup-carve/carve#1320). The sanitizer read only the value's
+  leading scheme, which vouches for the whole value only where the whole value
+  is one URL, so `srcset="safe.png 1x, javascript:alert(1) 2x"` passed on its
+  second entry. `srcset`, `imagesrcset`, `ping` and `attributionsrc` are now
+  split into tokens and every candidate is read, and any hit blanks the whole
+  value. The engine embedded in `0.1.0` predates the fix, so the gem published
+  on 2026-07-12 carries the defect.
+
+### Added
+
+- **`Carve.parse` publishes source positions.** Every block node the engine can
+  place carries `pos` with `startLine`, `endLine`, `startColumn`, `endColumn`,
+  `startOffset` and `endOffset`, as PART 12 §4 spells it: lines and columns
+  1-based, offsets 0-based, counted in Unicode codepoints, `endColumn` and
+  `endOffset` exclusive. A node whose span the engine could not determine has
+  no `pos` key at all rather than one holding placeholder numbers - an absent
+  position is a fact a consumer can act on, an invented one is not. Inline
+  nodes do not carry positions yet (markup-carve/carve-rs#333).
+
+- **`Carve.to_html(source, sections: false)` renders headings without the
+  `<section>` wrapper** (#36, PART 9 §13). The id goes back on the `<h*>`
+  alongside its other attributes and the blocks that would have been section
+  children stay siblings. Default `true`, so existing output is unchanged. The
+  wrapper is the one output change that breaks a site whose source migrated
+  cleanly: CSS and JS assuming rendered blocks are direct children of the
+  content container stop matching once a `<section>` sits in between.
+
+- **Every extension the engine registers is reachable from Ruby.**
+  `Carve::EXTENSIONS` lists 31 names instead of 15, adding glossary, index,
+  table-of-contents placement (`::: toc`), heading numbers, heading references,
+  heading level shift, code groups, tabs, the img fence, color swatches, smart
+  quotes, and the remaining fenced-render presets (PlantUML, D2, WaveDrom,
+  Vega-Lite, ABC). The list comes from the engine's registry rather than being
+  typed out in the native binding and again in `lib/carve.rb`. Canonical names
+  are the engine's kebab-case keys; snake_case spellings and the short aliases
+  (`:math`, `:permalinks`, `:mermaid`, `:dot`, `:chart`, `:toc`) still work.
+
+- **Composite figures** (PART 9 §4c). A **bare** `::: figure` fence is no longer
+  a generic container: it is one figure of ordered panels, rendering
+  `<figure class="carve-figure-group">` around a
+  `<div class="carve-figure-panels">` whose members are each a
+  `<figure class="carve-figure-panel">`, and a `^ ` line following the closer
+  becomes the group's `<figcaption>` instead of an ordinary paragraph. A fence
+  carrying a title or a `[label]` keeps the old shape, so a document that named
+  its figure divs renders as before. `Carve.parse` publishes the group as a new
+  `figure_group` node type.
+
+### Changed
+
+- **Breaking (`Carve.parse`): the published tree now matches the reference
+  shape.** A tree from this binding did not interoperate with carve-js or
+  carve-php, so several names and the root's shape moved at once:
+
+  | was | now |
+  |---|---|
+  | `critic_insert` / `critic_delete` / `critic_substitute` | `insert` / `delete` / `substitution` |
+  | `footnote` (both forms) | `footnote_ref` / `inline_footnote` |
+  | `ref_id` | `refId` |
+  | `footnote_defs` | `footnoteDefs` |
+  | `source_len` | `srcByteLength` |
+  | `emoji` | `symbol` (and it carries `attrs`) |
+
+  The root now carries exactly `type`, `children` and `srcByteLength`.
+  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 (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.
+
+- **Breaking (`Carve.parse`): three constructs became their own node types.** A
+  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 (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 (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
+  (markup-carve/carve-rs#374).
+
+  These are additive for a consumer with a default branch and a compile error
+  for one without.
+
+- **Delimited inline comments carried in from the engine.** `{% … %}` is an
+  inline comment that ends at its closer, alongside the trailing `%%` form that
+  runs to the end of its inline run (PART 9 §21a). Both render nothing; in
+  `Carve.parse` they are the same `comment` node, told apart by a `delimited`
+  field, because the two spell different documents and a writer has to
+  reproduce the one that was written.
+
+- **Language changes carried in from the engine.** Superscript and subscript are
+  braced-only - bare `^x^` and `,x,` are literal text, the markup is `{^x^}` and
+  `{,x,}`. The `:name:` symbol inline was added, with a leading word-boundary
+  guard so `a:b:c`, `10:30:` and `me@example.com` stay literal. Compact semantic
+  spans arrived: `[Tab]{kbd}` renders `<kbd>Tab</kbd>`, with `abbr`, `time` and
+  `kbd` in core and `samp`, `var`, `cite` and `dfn` behind the `semantic-span`
+  extension.
+
+  Every `<th>` carries a `scope` - `col` in the header run, `row` for a
+  `|=` cell in a body row. A cell's attribute block binds after its kind and
+  alignment markers, so a `{...}` following a cell's `=` marker is read as
+  attributes rather than rendered as cell text. A mandatory base class merges
+  into the author's class slot at its authored position rather than leading it,
+  so `:widget[x]{#i .c}` keeps `id` first.
+
+- **Rendering corrections carried in from the engine.** A block-attribute line
+  reaches the nested list it was written for, and a flush-left attribute line is
+  read as attributes rather than as paragraph text. A figure group holds its
+  panels directly. A table's sections and rows keep the attributes they have a
+  slot for. A code block resolves the no-break-space sentinel instead of
+  emitting it. A fence opened inside a
+  container keeps that container open, so a boundary line, a list marker at the
+  content column and a closed fence's residue land where PART 9 §24 puts them
+  rather than folding into the code text. A lazy line folded into a container
+  leaves it open. A caption attaches across at most one blank line, so two blank
+  lines detach it and the image stays an image. A definition body is an
+  indented-block collector, so a line below its column ends it. A heading with
+  no `<section>` wrapper renders the author's attributes first and the generated
+  id last. A frontmatter block whose opener named no format is written back as
+  `---yaml`, and a blank line inside a fenced block under a footnote definition
+  or a definition-list description is written empty rather than indented.
+
+  Reference resolution reaches three places it used to stop short of: a
+  reference inside an inline note, a critic insertion or a critic deletion
+  resolves against the document's definitions; a footnote inside an unresolved
+  reference stays a footnote rather than being swallowed by the failed
+  reference; and a reference tail no longer seals its own link text, so the
+  text a reference link carries survives the frame that resolves it.
+
+  For `Carve.parse` specifically: a nested link and an autolink stay nodes and
+  the renderers unwrap them; a collapsed reference publishes the label it
+  resolves by; a heading's derived display text clones the heading's nodes
+  instead of re-rendering them, so an escaped character in a heading reaches the
+  label; and `attrs.keyValues` is published in the author's source order, the
+  same order the sibling `attrs.order` field states.
+
+
+## [0.1.0] - 2026-07-12
+
+### Added
+
+- Initial release: `Carve.to_html` exposes the carve-rs engine as a native
+  Ruby extension (magnus + rb-sys), with the full extension/option surface,
+  the static/print render mode, and pluggable diagram/math renderers.
+- `Carve.parse` returns the full parse tree as symbol-keyed Ruby Hashes and
+  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.10...HEAD
+[0.1.10]: https://github.com/markup-carve/carve-rb/compare/v0.1.9...v0.1.10
+[0.1.9]: https://github.com/markup-carve/carve-rb/compare/v0.1.8...v0.1.9
+[0.1.8]: https://github.com/markup-carve/carve-rb/compare/v0.1.7...v0.1.8
+[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
+[0.1.2]: https://github.com/markup-carve/carve-rb/compare/v0.1.1...v0.1.2
+[0.1.1]: https://github.com/markup-carve/carve-rb/compare/v0.1.0...v0.1.1
+[0.1.0]: https://github.com/markup-carve/carve-rb/releases/tag/v0.1.0

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) markup-carve
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,154 @@
+# carve (Ruby)
+
+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
+gem "carve-lang"
+```
+
+```bash
+bundle install
+```
+
+The distribution name is `carve-lang`, while the require path is `carve`.
+
+Releases after 0.1.9 ship precompiled gems for `x86_64-linux`,
+`x86_64-linux-musl`, `aarch64-linux`, `x86_64-darwin`, `arm64-darwin` and
+`x64-mingw-ucrt`, with a binary for each Ruby from 3.0 to 4.0 (from 3.1 on
+Windows, where Ruby 3.0 has no UCRT build). On those platforms `gem install`
+needs no Rust toolchain or libclang. Everywhere else, including newer Rubies,
+RubyGems installs the source gem and builds it as described below.
+
+## Installing from source
+
+Version 0.1.9 and earlier ship source only, and so does every release on a
+platform or Ruby without a precompiled gem. There `gem install carve-lang`
+compiles a Rust extension on your machine, so the install needs:
+
+- A Rust toolchain with `cargo`, Rust 1.77 or newer. [rustup](https://rustup.rs)
+  is the usual way to get one.
+- Ruby development headers (`ruby-dev` on Debian and Ubuntu).
+- libclang and clang. The build runs `bindgen` through `rb-sys` to read Ruby's
+  C headers. On Debian and Ubuntu:
+
+```bash
+sudo apt install libclang-dev clang
+```
+
+If only libclang is installed, without the `clang` package, the build stops
+with this error:
+
+```text
+/usr/include/ruby-3.2.0/ruby/ruby.h:23:10: fatal error: 'stdarg.h' file not found
+thread 'main' panicked at .../rb-sys-0.9.128/build/main.rs:52:6:
+generate bindings: ClangDiagnostic("/usr/include/ruby-3.2.0/ruby/ruby.h:23:10: fatal error: 'stdarg.h' file not found\n")
+error: failed to run custom build command for `rb-sys v0.9.128`
+```
+
+libclang cannot find its own builtin headers. Install `clang`, or point
+bindgen at GCC's copy of those headers:
+
+```bash
+BINDGEN_EXTRA_CLANG_ARGS="-I$(gcc -print-file-name=include)" gem install carve-lang
+```
+
+With Bundler, export the variable before running `bundle install`.
+
+## Render Carve
+
+```ruby
+require "carve"
+
+Carve.to_html("# Hello *world*")
+Carve.to_markdown(source)
+Carve.to_plain_text(source)
+Carve.to_ansi(source)
+Carve.to_carve(source)
+Carve.to_carve(source, align_tables: true) # pad table columns
+```
+
+Options configure extensions, safe rendering, profiles, symbols, section
+wrappers, and custom renderers:
+
+```ruby
+Carve.to_html(
+  source,
+  extensions: %w[autolink list-table],
+  safe: true,
+  profile: "comment",
+)
+```
+
+`Carve::EXTENSIONS` reports the names accepted by the bundled engine. Unknown
+names raise `ArgumentError`.
+
+## Errors
+
+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.
+
+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
+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
+```
+
+Report any input that raises it: a panic is an engine defect, not a rejection.
+
+## Migration and AST access
+
+`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.
+
+The [usage reference](docs/reference.md) documents AST fields, static
+rendering, symbols, wrappers, profiles, and the main methods.
+
+## Includes
+
+Includes are opt-in and require an absolute containment root plus the source
+document's absolute path:
+
+```ruby
+result = Carve.to_html_with_includes(
+  File.read("book.crv"),
+  root: File.expand_path("."),
+  source_path: File.expand_path("book.crv"),
+)
+```
+
+The result contains the value, warnings, and root-relative dependencies. A
+warning from an included file names the chain of directives that reached it in
+`:includedBy`.
+Other render methods leave directives literal. See the
+[include reference](docs/reference.md#file-includes) for budgets, AST expansion,
+targets, and containment behavior.
+
+## Security
+
+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.
+
+## Development
+
+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/lib/carve/version.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+module Carve
+  # The released version of this gem. The gemspec derives `spec.version` from
+  # it, and an embedder quoting a version in a bug report is quoting this.
+  #
+  # It is not kept correct by hand on release: test/release_version_test.rb
+  # 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.10"
+end

data/lib/carve.rb

@@ -0,0 +1,385 @@
+# frozen_string_literal: true
+
+# Carve: Ruby bindings for the Carve markup language.
+#
+# This file loads the compiled native extension (built from ext/carve, a Rust
+# crate wrapping the carve-rs engine via magnus) and layers a small,
+# idiomatic Ruby API on top of the raw primitives it exports.
+require "json"
+require_relative "carve/version"
+
+# Load the compiled native extension. A precompiled platform gem ships one per
+# Ruby ABI under lib/carve/<major.minor>/; a source install and `rake compile`
+# build lib/carve/carve.so (or .bundle on macOS).
+# Chosen by directory rather than by rescuing LoadError, so a binary that is
+# present but cannot load (an older glibc, say) reports its own error.
+abi = RUBY_VERSION[/\A\d+\.\d+/]
+if File.directory?(File.join(__dir__, "carve", abi))
+  require_relative "carve/#{abi}/carve"
+else
+  require_relative "carve/carve"
+end
+
+module Carve
+  # Raised by .select_include_region when the region is missing or a marker is
+  # malformed, unpaired or duplicated. +rule+ is the engine's warning rule id.
+  class IncludeRegionError < ArgumentError
+    attr_reader :rule
+
+    def initialize(rule, name)
+      @rule = rule
+      super("#{rule}: region #{name.inspect} is missing or its markers are malformed")
+    end
+  end
+
+  # Extension names the native binding understands.
+  #
+  # Taken from the engine itself rather than typed out here. This was a literal
+  # array, and the native binding had its own match arm listing the same names,
+  # so an extension carve-rs gained was unreachable from Ruby until somebody
+  # updated both by hand - and nothing failed in the meantime.
+  #
+  # The names are the engine's kebab-case keys, exposed as symbols
+  # (`:"math-block"`). The snake_case spellings this binding has always taken
+  # (`:math_block`) and its short aliases (`:mermaid`, `:dot`, `:toc`) still
+  # work as ARGUMENTS; this constant lists the canonical names.
+  EXTENSIONS = _extension_names.map(&:to_sym).freeze
+
+  # Render modes the native binding understands.
+  #
+  # +:interactive+ (default) emits live HTML with client-script hooks (e.g.
+  # `<pre class="mermaid">`, `<details>`). +:static+ emits self-contained HTML
+  # for print / PDF / archival: it forces disclosure (`<details open>`) and
+  # pre-renders client-script constructs through the +renderers:+ callables,
+  # degrading to (escaped) source when a renderer is absent or fails.
+  MODES = %i[interactive static].freeze
+
+  # Renderer keys accepted by the +renderers:+ Hash (see .to_html). Each maps a
+  # construct's source to a self-contained HTML string emitted on the static
+  # path. +mermaid+ / +chart+ / +graphviz+ are callables `(String) -> String`;
+  # +math+ is `(String, display_bool) -> String`.
+  RENDERER_KEYS = %i[mermaid chart graphviz math].freeze
+
+  class << self
+    # Render +source+ to HTML with its <tt>{{ path }}</tt> includes expanded,
+    # contained to +root:+.
+    #
+    #   Carve.to_html_with_includes(File.read(page), root: "/srv/site",
+    #                               source_path: page, symbols: {smile: "\u{1F604}"})
+    #
+    # +root:+ and +source_path:+ are absolute, and the source file lives inside
+    # the root. A relative value raises ArgumentError rather than rooting
+    # containment at the process working directory, which is arbitrary with
+    # respect to the document.
+    #
+    # Returns +{value:, warnings:, dependencies:, suppressedWarnings:}+. Paths
+    # in +warnings+ and +dependencies+ are relative to the root, so a report can
+    # be shown to a reader as it stands. Each warning's +includedBy+ lists the
+    # directives that reached its file, top-level first, as +{file:, line:, column:}+.
+    #
+    # Every render option +to_html+ takes is accepted and reaches the included
+    # children too: an extension, a symbol map or a profile means the same thing
+    # in a child as in the parent.
+    def to_html_with_includes(source, root:, source_path:, extensions: nil, mode: nil,
+                              renderers: nil, symbols: nil, safe: false, profile: nil,
+                              sections: true, max_depth: nil, max_bytes: nil,
+                              max_resolver_calls: nil, max_warnings: nil)
+      render_with_includes(
+        source, target: "html", root: root, source_path: source_path,
+        extensions: extensions, mode: mode, renderers: renderers, symbols: symbols,
+        safe: safe, profile: profile, sections: sections, max_depth: max_depth,
+        max_bytes: max_bytes, max_resolver_calls: max_resolver_calls,
+        max_warnings: max_warnings
+      )
+    end
+
+    # The expanded document as an AST, in the shape +.parse+ returns.
+    #
+    #   Carve.parse_with_includes(File.read(page), root: root, source_path: page)
+    #   # => {value: {type: "document", ...}, warnings: [], dependencies: [...], ...}
+    #
+    # For a host that walks the tree rather than rendering HTML - carve-hexapdf
+    # draws its PDF from this shape.
+    #
+    # Nodes carry NO +:pos+, unlike +.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.
+    def parse_with_includes(source, root:, source_path:, extensions: nil, profile: nil,
+                            max_depth: nil, max_bytes: nil, max_resolver_calls: nil,
+                            max_warnings: nil)
+      render_with_includes(
+        source, target: "ast", root: root, source_path: source_path,
+        extensions: extensions, profile: profile, max_depth: max_depth,
+        max_bytes: max_bytes, max_resolver_calls: max_resolver_calls,
+        max_warnings: max_warnings
+      )
+    end
+
+    # The include pass over any render target: +"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.
+    def render_with_includes(source, root:, source_path:, target: "html", extensions: nil,
+                             mode: nil, renderers: nil, symbols: nil, safe: false,
+                             profile: nil, sections: true, max_depth: nil, max_bytes: nil,
+                             max_resolver_calls: nil, max_warnings: nil)
+      JSON.parse(
+        _render_with_includes_json(
+          source.to_s,
+          root.to_s,
+          source_path.to_s,
+          target.to_s,
+          Array(extensions).map(&:to_s),
+          (mode || :interactive).to_s,
+          renderers || {},
+          symbols || {},
+          !!safe,
+          profile&.to_s,
+          !!sections,
+          max_depth,
+          max_bytes,
+          max_resolver_calls,
+          max_warnings,
+        ),
+        symbolize_names: true,
+        # The engine bounds nesting itself, above Ruby JSON's default of 100, so
+        # a legal document would otherwise raise here. Same reason as .parse.
+        max_nesting: false,
+      )
+    end
+
+    # Format +source+ into canonical Carve. A writer refusal returns the source
+    # as authored. +align_tables:+ pads table cells into aligned columns.
+    def to_carve(source, align_tables: false)
+      _to_carve(source, align_tables ? true : false)
+    end
+
+    # Resolve <tt>@region:name</tt> in a file's text with the engine's marker
+    # rules, so an editor jumping to a region agrees with the render.
+    #
+    #   Carve.select_include_region(text, "setup", mode: :carve) # => 3..4
+    #
+    # Returns the 1-based, inclusive Range of content lines; an empty region is
+    # an empty Range such as +2..1+. +mode: :carve+ accepts only
+    # <tt>%% #region</tt> markers, +mode: :code+ also the source-comment forms
+    # of an +@code+ include. Raises IncludeRegionError otherwise.
+    def select_include_region(source, name, mode:)
+      result = _select_include_region(source, name.to_s, mode.to_s)
+      raise IncludeRegionError.new(result, name.to_s) if result.is_a?(String)
+
+      result[0]..result[1]
+    end
+
+    # Import HTML or Markdown into canonical Carve. Both methods return the
+    # shared migration shape `{ value:, report: }`.
+    def from_html(source, mode: :safe)
+      JSON.parse(_from_html_json(source, mode.to_s), symbolize_names: true)
+    end
+
+    def from_markdown(source)
+      result = JSON.parse(_from_markdown_json(source), symbolize_names: true)
+      # Keep the 0.1.x spelling while exposing the shared cross-language key.
+      result[:report][:source_format] = result[:report][:sourceFormat]
+      result
+    end
+
+    # Render Carve +source+ to an HTML string.
+    #
+    # With no extensions:
+    #   Carve.to_html("# Hello")             # => "<section ...>\n  <h1>Hello</h1>..."
+    #
+    # With extensions (Array of names as Symbols or Strings):
+    #   Carve.to_html(src, extensions: [:math_block])
+    #   Carve.to_html(src, extensions: %w[math-block list-table])
+    #
+    # Recognized extension names: see Carve::EXTENSIONS. Names may be given
+    # snake_case (:math_block) or hyphenated ("math-block").
+    #
+    # An unknown extension name raises ArgumentError (from the native layer).
+    #
+    # ==== Static render mode
+    #
+    # Pass +mode: :static+ (or "static") to emit self-contained HTML for print /
+    # PDF / archival. In static mode disclosure is forced (`<details open>`) and
+    # client-script constructs are pre-rendered through the +renderers:+ Hash:
+    #
+    #   Carve.to_html(src, extensions: [:fenced_render], mode: :static,
+    #                 renderers: { mermaid: ->(s) { "<svg>#{s}</svg>" } })
+    #
+    # Renderer callables (Symbol or String keys, see Carve::RENDERER_KEYS):
+    #   * +:mermaid+ / +:chart+ / +:graphviz+ -> callable `(String) -> String`
+    #   * +:math+                             -> callable `(String, display) -> String`
+    #
+    # When a needed renderer is absent, or a renderer raises / returns a
+    # non-String, the construct degrades to its HTML-ESCAPED source (never blank,
+    # never raw HTML). Omitting +mode:+ defaults to interactive (non-breaking).
+    #
+    # An unknown mode or renderer key raises ArgumentError (from the native
+    # layer).
+    #
+    # ==== Symbols
+    #
+    # A +:name:+ symbol renders its literal +:name:+ source unless the name is
+    # in the +symbols:+ Hash (String or Symbol keys, String values):
+    #
+    #   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 (from the native layer).
+    #
+    # SECURITY: a mapped symbol value is inserted as TRUSTED RAW output in the
+    # target format - it is NOT escaped, the same trust class as a +renderers:+
+    # callable. <tt>{ "b" => "<b>x</b>" }</tt> 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
+    # <tt><section id="install"><h2 class="featured"></tt> - 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*>+:
+    #
+    #   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 <tt>.stack > * + *</tt> 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, <tt></#id></tt>
+    # cross-references, implicit +[Heading][]+ references and heading numbering
+    # all resolve against the slug rather than the element carrying it. The
+    # endnotes <tt><section role="doc-endnotes"></tt> is a separate construct and
+    # is still emitted.
+    #
+    # ==== Untrusted input
+    #
+    # Carve's normative hardening is always on and needs no argument here:
+    # dangerous URL schemes are blanked, event-handler attributes such as
+    # +onclick+ are dropped, and the bidi override / isolate characters behind
+    # Trojan Source are removed from rendered text.
+    #
+    # Raw passthrough is the deliberate exception - a <tt>```=html</tt> block or
+    # a <tt>`...`{=html}</tt> span renders VERBATIM by design - so it is the one
+    # thing input you did not author has to switch off:
+    #
+    #   Carve.to_html(user_input, safe: true, profile: :comment)
+    #
+    # +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),
+    # +nil+ for no profile. An unknown profile name raises ArgumentError (from
+    # the native layer) rather than being ignored.
+    #
+    # A profile REJECTION also raises ArgumentError - input past the profile's
+    # +max_length+, or a denied construct when the profile's action is error:
+    #
+    #   Carve.to_html("x" * 20_000, profile: :minimal)
+    #   # ArgumentError: Profile violations: 'document' is not allowed:
+    #   #   max_length_exceeded (...)
+    #
+    # It is an exception rather than a return value because 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.
+    def to_html(source, extensions: nil, mode: nil, renderers: nil, symbols: nil,
+                safe: false, profile: nil, sections: true)
+      list = Array(extensions)
+
+      # Fast path: interactive (default), no extensions, no renderers, no
+      # symbols, neither safe-render control in play, and section wrapping left
+      # on. `sections: false` MUST fall through -- `_to_html` takes no options,
+      # so short-circuiting to it would drop the flag and return wrapped output
+      # with no error, which is the failure mode a caller cannot see.
+      if list.empty? && (mode.nil? || mode.to_s == "interactive") &&
+         (renderers.nil? || renderers.empty?) && (symbols.nil? || symbols.empty?) &&
+         !safe && profile.nil? && sections
+        return _to_html(source.to_s)
+      end
+
+      _to_html_safe(
+        source.to_s,
+        list.map(&:to_s),
+        (mode || :interactive).to_s,
+        renderers || {},
+        symbols || {},
+        !!safe,
+        profile&.to_s,
+        !!sections,
+      )
+    end
+
+
+    # Read a document's provenance marker, as written by +carve fmt --stamp+.
+    #
+    #   Carve.read_stamp(source)
+    #   # => {version: "0.1", generated_by: "carve-php 0.1.0"}
+    #   Carve.read_stamp("# Hi\n")
+    #   # => nil
+    #
+    # Returns +nil+ when the document carries no marker. That is the normal case
+    # for a hand-written document and means "unknown", not "current".
+    #
+    # Both documented marker forms are read - the trailing +%%+ line and the
+    # +%%%+ block - and a marker written by any Carve engine reads the same,
+    # which is the point of recording it.
+    def read_stamp(source)
+      _read_stamp(source.to_s)
+    end
+
+    # Whether a document was last processed under an older spec version than
+    # this engine targets, so the +[behavior]+ changelog entries between the two
+    # are worth reviewing.
+    #
+    #   Carve.needs_review?(stored_document)
+    #
+    # An UNSTAMPED document answers true: its provenance is unknown, and
+    # assuming it is current is the unsafe direction. Pass +current_version+ to
+    # compare against something other than this engine's spec version.
+    #
+    # See https://markup-carve.github.io/carve/versioning for what a version
+    # difference means for a stored document.
+    def needs_review?(source, current_version = nil)
+      _stamp_needs_review(source.to_s, current_version&.to_s)
+    end
+
+    # Parse Carve +source+ into an AST: a tree of Ruby Hashes and Arrays.
+    #
+    #   Carve.parse("# Hi")
+    #   # => {type: "document",
+    #   #     children: [{type: "heading", level: 1,
+    #   #                 children: [{type: "text", value: "Hi"}], attrs: nil}],
+    #   #     srcByteLength: 4, astVersion: "1.2"}
+    #
+    # The root carries exactly +:type+, +:children+, +:srcByteLength+ and
+    # +:astVersion+ (spec
+    # PART 12 §7). Frontmatter and footnote definitions are block nodes in
+    # +:children+, not root fields: a root field cannot carry the position §4
+    # requires of every node, and both are source an editor navigates to.
+    # Frontmatter is the first child, carrying +:format+ and RAW +:content+.
+    #
+    # 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), suitable for a custom renderer (e.g. Carve -> PDF).
+    def parse(source)
+      # max_nesting: false - the engine already bounds nesting (its own
+      # MAX_NESTING_DEPTH cap), and that cap exceeds Ruby JSON's default
+      # max_nesting of 100. Without this, deeply-nested-but-valid documents
+      # that Carve.to_html renders fine would raise JSON::NestingError here.
+      JSON.parse(_to_ast_json(source.to_s), symbolize_names: true, max_nesting: false)
+    end
+  end
+end

metadata

@@ -0,0 +1,102 @@
+--- !ruby/object:Gem::Specification
+name: carve-lang
+version: !ruby/object:Gem::Version
+  version: 0.1.10
+platform: arm64-darwin
+authors:
+- markup-carve
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2026-10-23 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+- !ruby/object:Gem::Dependency
+  name: rake-compiler
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.2'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.2'
+- !ruby/object:Gem::Dependency
+  name: minitest
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '5.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '5.0'
+description: |-
+  Parse and render Carve markup to HTML from Ruby. A native extension
+  (magnus + rb-sys) over the carve-rs engine, mirroring how Djot's djotter
+  gem wraps the jotdown crate. No parser is reimplemented in Ruby.
+email: 
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE
+- README.md
+- lib/carve.rb
+- lib/carve/3.0/carve.bundle
+- lib/carve/3.1/carve.bundle
+- lib/carve/3.2/carve.bundle
+- lib/carve/3.3/carve.bundle
+- lib/carve/3.4/carve.bundle
+- lib/carve/4.0/carve.bundle
+- lib/carve/version.rb
+homepage: https://github.com/markup-carve/carve-rb
+licenses:
+- MIT
+metadata:
+  rubygems_mfa_required: 'true'
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.0'
+  - - "<"
+    - !ruby/object:Gem::Version
+      version: 4.1.dev
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.5.23
+signing_key: 
+specification_version: 4
+summary: Native Ruby bindings for the Carve markup language.
+test_files: []