inkmark 0.1.4-aarch64-linux → 0.2.0-aarch64-linux

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f8cd41a17a7a68ec37bbb4b34d4acbd02a23ec16a0cbcb62e656ccca368cc944
-  data.tar.gz: 14195af984e186ecc5931a4b0529812e059a59d3351951ac3f5cee2f63f5a777
+  metadata.gz: 1a62cd9232907088d1781df13ebc9772f6d2ec3a20a3f331bf1edc07ab6cfa4e
+  data.tar.gz: e5e2ebb5eac180adc92c780473aacddbbd6185d8c97101bf58afa2825ce5ce73
 SHA512:
-  metadata.gz: 0efa722d2c457d4af8e6b2dc702239fa618638663998e52758ffbf755d6c7df326f30341d96fd8bc6a5d986079ee59d694940c2046e725f52b1433c868122248
-  data.tar.gz: ef8a749da3406c397c3e22cff35660c544dda1dd9f1643b604e9250b8edce0fe7c9aefab8975628a12cd9da49578e0d73c776d9218fa0ff62b4f66b23dbcf75b
+  metadata.gz: c5630ebc0b28c23efac86f7ff45cdb4367b5af804c923ff386a7b310020624e69f9cba7d824f40267e7d062e9ae45aac6c112ab330bb1737dfc0333b149eb5d1
+  data.tar.gz: 3e338f4b6e7418c24e4cd2b55813038c4224af2e56135b9c5a7b1dc905406ccc0c3bd0283ccb73e46d96977a39a285a3b8888b075e28dfa1f2b4c05194b076a2

data/CHANGELOG.md

@@ -1,3 +1,10 @@
+## [0.2.0] - 2026-09-06
+
+- Ractor-safe: the native extension declares `rb_ext_ractor_safe`, and every public API works from non-main Ractors.
+- `Inkmark.default_options` is now frozen; configure process-wide defaults with `Inkmark.configure { |o| ... }` or `Inkmark.default_options=`.
+- Load YAML on the first `frontmatter` parse instead of at require time.
+- Updated dependencies.
+
 ## [0.1.4] - 2026-06-25
 
 - Fix `frontmatter: true` leaking the frontmatter block into `to_markdown`, `chunks_by_heading`, and `chunks_by_size` output. Bug report by @freesteph [#3]

data/README.md

@@ -38,6 +38,7 @@ A very fast, feature-packed, AI-first Markdown gem for Ruby.
 - [Plain-text extraction](#plain-text-extraction)
 - [Markdown-to-Markdown pipeline](#markdown-to-markdown-pipeline)
 - [Event handlers](#event-handlers)
+- [Ractors](#ractors)
 - [Benchmarks](#benchmarks)
 - [Contributing](#contributing)
 - [Acknowledgements](#acknowledgements)
@@ -177,9 +178,15 @@ g.options.math = true
 g.options.tables = false
 g.to_html
 
-# Process-level defaults, to set in your application initializer
-Inkmark.default_options.math = true
-Inkmark.new(md).to_html  # picks up the default
+# Process-wide defaults, set once in your application initializer
+Inkmark.configure do |options|
+  options.math = true
+  options.links = { nofollow: true }
+end
+Inkmark.new(md).to_html  # picks up the defaults
+
+# Or replace them wholesale
+Inkmark.default_options = { preset: :recommended, math: true }
 ```
 
 Unknown option keys raise `ArgumentError` immediately, including via the
@@ -1029,6 +1036,21 @@ Post-render filters (`syntax_highlight`, allowlists, `images: { lazy: true }`,
   highlighter
 - Handler-set `dest=` values pass through host and scheme allowlists
 
+## Ractors
+
+Inkmark is Ractor-safe: every public API works inside non-main Ractors,
+so documents can be rendered in parallel without leaving the native fast
+path.
+
+```ruby
+workers = sources.each_slice(250).map do |slice|
+  Ractor.new(slice) do |batch|
+    batch.map { |src| Inkmark.to_html(src, options: { preset: :recommended }) }
+  end
+end
+html = workers.flat_map(&:value)  # Ruby 4.0; use #take on 3.3 and 3.4
+```
+
 ## Benchmarks
 
 Inkmark ships a benchmark harness comparing it against `kramdown`,

data/lib/inkmark/options.rb

@@ -22,22 +22,28 @@ class Inkmark
     # Per-element-policy schemas. Each entry is +{ default:, types: }+; the
     # validators use +types+ for type checking and +default+ to seed fresh
     # nested hashes. Keep in sync with {NESTED_TO_FLAT}.
+    #
+    # Every constant in this class is frozen all the way down, not just
+    # at the top level: a non-main Ractor may only read constants whose
+    # whole object graph is frozen (+Ractor.shareable?+), so the inner
+    # Hashes and Arrays are frozen explicitly and the larger nested
+    # tables go through +Ractor.make_shareable+.
     HEADINGS_SCHEMA = {
-      attributes: {default: false, types: [TrueClass, FalseClass]},
-      ids: {default: false, types: [TrueClass, FalseClass]}
+      attributes: {default: false, types: [TrueClass, FalseClass].freeze}.freeze,
+      ids: {default: false, types: [TrueClass, FalseClass].freeze}.freeze
     }.freeze
 
     IMAGES_SCHEMA = {
-      lazy: {default: false, types: [TrueClass, FalseClass]},
-      allowed_hosts: {default: nil, types: [NilClass, Array]},
-      allowed_schemes: {default: nil, types: [NilClass, Array]}
+      lazy: {default: false, types: [TrueClass, FalseClass].freeze}.freeze,
+      allowed_hosts: {default: nil, types: [NilClass, Array].freeze}.freeze,
+      allowed_schemes: {default: nil, types: [NilClass, Array].freeze}.freeze
     }.freeze
 
     LINKS_SCHEMA = {
-      autolink: {default: false, types: [TrueClass, FalseClass]},
-      nofollow: {default: false, types: [TrueClass, FalseClass]},
-      allowed_hosts: {default: nil, types: [NilClass, Array]},
-      allowed_schemes: {default: nil, types: [NilClass, Array]}
+      autolink: {default: false, types: [TrueClass, FalseClass].freeze}.freeze,
+      nofollow: {default: false, types: [TrueClass, FalseClass].freeze}.freeze,
+      allowed_hosts: {default: nil, types: [NilClass, Array].freeze}.freeze,
+      allowed_schemes: {default: nil, types: [NilClass, Array].freeze}.freeze
     }.freeze
 
     # Registry of nested hash options => their schemas. Iterated by the
@@ -52,7 +58,7 @@ class Inkmark
     # Map from +(parent, child)+ user-facing keys to the flat key name the
     # Rust side reads. Used by {#to_native_hash} / {#to_native_hash_frozen}
     # to serialize the user-shaped hash into the FFI wire format.
-    NESTED_TO_FLAT = {
+    NESTED_TO_FLAT = Ractor.make_shareable({
       [:headings, :attributes] => :heading_attributes,
       [:headings, :ids] => :heading_ids,
       [:images, :lazy] => :lazy_images,
@@ -62,7 +68,7 @@ class Inkmark
       [:links, :nofollow] => :nofollow_external_links,
       [:links, :allowed_hosts] => :allowed_link_hosts,
       [:links, :allowed_schemes] => :allowed_link_schemes
-    }.freeze
+    })
 
     # Build a frozen defaults hash for a nested schema from its +default+
     # entries.
@@ -200,11 +206,11 @@ class Inkmark
     # the accepted type set (nil-default-but-Array-when-set, polymorphic
     # +toc+, nested-hash element-policy groups).
     TYPES = {
-      extract: [NilClass, Hash],
-      toc: [TrueClass, FalseClass, Hash],
-      headings: [Hash],
-      images: [Hash],
-      links: [Hash]
+      extract: [NilClass, Hash].freeze,
+      toc: [TrueClass, FalseClass, Hash].freeze,
+      headings: [Hash].freeze,
+      images: [Hash].freeze,
+      links: [Hash].freeze
     }.freeze
 
     # Element kinds accepted inside +extract: { ... }+. Mirrors the match
@@ -237,7 +243,7 @@ class Inkmark
     #   The GFM tagfilter stays on. **Dangerous.** Use only for content
     #   the caller fully trusts (internal team-authored docs). The
     #   caller is fully responsible for sanitizing output.
-    PRESETS = {
+    PRESETS = Ractor.make_shareable({
       commonmark: {
         gfm: false,
         gfm_tag_filter: false,
@@ -245,7 +251,7 @@ class Inkmark
         strikethrough: false,
         tasklists: false,
         footnotes: false
-      }.freeze,
+      },
 
       gfm: {
         gfm: true,
@@ -254,7 +260,7 @@ class Inkmark
         strikethrough: true,
         tasklists: true,
         footnotes: true
-      }.freeze,
+      },
 
       recommended: {
         gfm: true,
@@ -272,7 +278,7 @@ class Inkmark
         syntax_highlight: true,
         hard_wrap: true,
         frontmatter: true
-      }.freeze,
+      },
 
       trusted: {
         gfm: true,
@@ -290,8 +296,8 @@ class Inkmark
         syntax_highlight: true,
         hard_wrap: true,
         frontmatter: true
-      }.freeze
-    }.freeze
+      }
+    })
 
     # Preset applied by {#initialize} when the caller doesn't pass
     # +preset:+. +:gfm+ matches {DEFAULTS}, so the default constructor
@@ -387,7 +393,16 @@ class Inkmark
     #   hashes; the input value as-is otherwise)
     # @raise [ArgumentError] if +key+ is unknown, or the value (or any
     #   nested sub-value) has the wrong type
+    # @raise [FrozenError] if this instance is frozen (as
+    #   {Inkmark.default_options} always is)
     def []=(key, value)
+      if frozen?
+        raise FrozenError.new(
+          "can't modify frozen #{self.class}: use Inkmark.configure to change " \
+          "the process-wide defaults, or dup for a mutable copy",
+          receiver: self
+        )
+      end
       validate_key!(key)
       # Deep-merge partial nested-hash overrides (+:headings+,
       # +:images+, +:links+) so callers pass only the sub-keys they
@@ -429,11 +444,17 @@ class Inkmark
     # FFI calls that don't need to add per-call params. The cache is
     # invalidated in {#[]=} and {#initialize_copy}.
     #
-    # @return [Hash{Symbol => Object}] frozen, shared across calls until
-    #   a mutation invalidates it
+    # The hash is frozen all the way down, as a copy: nested Arrays and
+    # Hashes are duplicated before freezing so caller-supplied values
+    # (an +allowed_hosts+ Array, say) stay mutable in the caller's hands.
+    # A deeply frozen memo is what lets a frozen +Options+ be shared
+    # across Ractors.
+    #
+    # @return [Hash{Symbol => Object}] deeply frozen, shared across calls
+    #   until a mutation invalidates it
     # @api private
     def to_native_hash_frozen
-      @frozen_native_hash ||= build_native_hash.freeze
+      @frozen_native_hash ||= deep_frozen_copy(build_native_hash)
     end
 
     # Return a new Options instance with +other+'s values applied on top.
@@ -457,6 +478,18 @@ class Inkmark
     end
     alias_method :eql?, :==
 
+    # Freeze this instance. The memoized FFI hash is computed first, while
+    # the instance is still mutable, so {#to_native_hash_frozen} never has
+    # to write to a frozen object. +Ractor.make_shareable+ calls +freeze+
+    # on every object it visits, which is what makes a shared
+    # {Inkmark.default_options} renderable from any Ractor.
+    #
+    # @return [self]
+    def freeze
+      to_native_hash_frozen
+      super
+    end
+
     # Duplicate this instance, deep-copying the internal values hash so the
     # clone is fully independent from the original.
     def initialize_copy(orig)
@@ -466,14 +499,26 @@ class Inkmark
       @frozen_native_hash = nil
     end
 
-    # @!macro [attach] inkmark_options_accessor
-    #   @!attribute [rw] $1
-    #     Reader and writer for the +$1+ option. The writer routes through
-    #     {#[]=} so key validation and (for nested groups) deep-merge apply
-    #     uniformly.
+    # Reader and writer for every option key. The writer routes through
+    # {#[]=} so key validation and (for nested groups) deep-merge apply
+    # uniformly.
+    #
+    # Generated from source strings rather than +define_method+ blocks:
+    # a block-defined method carries its Proc, and Ruby refuses to call
+    # such a method from a non-main Ractor ("defined with an un-shareable
+    # Proc in a different Ractor"). Plain +def+ bodies have no such
+    # baggage. +key+ is always a Symbol from {DEFAULTS}, so interpolating
+    # it is safe.
     DEFAULTS.each_key do |key|
-      define_method(key) { @values[key] }
-      define_method("#{key}=") { |value| self[key] = value }
+      class_eval(<<~RUBY, __FILE__, __LINE__ + 1)
+        def #{key}                # def tables
+          @values[:#{key}]        #   @values[:tables]
+        end                       # end
+
+        def #{key}=(value)        # def tables=(value)
+          self[:#{key}] = value   #   self[:tables] = value
+        end                       # end
+      RUBY
     end
 
     private
@@ -517,6 +562,19 @@ class Inkmark
     def validate_key!(key) = self.class.send(:validate_key!, key)
     def validate_value!(key, value) = self.class.send(:validate_value!, key, value)
 
+    # Return a frozen copy of +value+ with every nested Hash, Array, and
+    # String frozen too. Scalars (booleans, nil, Integers, Symbols) are
+    # returned as is. Only the container shapes {#build_native_hash} can
+    # produce are handled.
+    def deep_frozen_copy(value)
+      case value
+      when Hash then value.transform_values { |v| deep_frozen_copy(v) }.freeze
+      when Array then value.map { |v| deep_frozen_copy(v) }.freeze
+      when String then -value
+      else value
+      end
+    end
+
     # Build the Rust-facing flat hash: nested element-policy hashes expand
     # into their flat keys via {NESTED_TO_FLAT}; the internal +@toc_depth+
     # is injected when set.
@@ -624,10 +682,13 @@ class Inkmark
     # +options: { preset: :name }+ call pattern, which would otherwise
     # build a fresh +Options+ instance (seed defaults, 6–14 +[]=+
     # with validation, +build_native_hash+) on every call. The cached
-    # hashes are frozen and safe to share across threads.
-    PRESETS_NATIVE_HASH = PRESETS.keys.each_with_object({}) do |name, h|
-      h[name] = new(preset: name).to_native_hash_frozen
-    end.freeze
+    # hashes are deeply frozen and safe to share across threads and
+    # Ractors.
+    PRESETS_NATIVE_HASH = Ractor.make_shareable(
+      PRESETS.keys.each_with_object({}) do |name, h|
+        h[name] = new(preset: name).to_native_hash_frozen
+      end
+    )
 
     # Build a Rust-facing flat hash from +overrides+ without allocating
     # an +Options+ instance or walking +build_native_hash+. Starts from

data/lib/inkmark/version.rb

@@ -2,5 +2,5 @@
 
 class Inkmark
   # Current gem version.
-  VERSION = "0.1.4"
+  VERSION = "0.2.0"
 end

data/lib/inkmark.rb

@@ -1,7 +1,5 @@
 # frozen_string_literal: true
 
-require "yaml"
-
 # Inkmark is a very fast, feature-rich, AI-first CommonMark/GFM
 # markdown renderer backed by the Rust pulldown-cmark parser.
 #
@@ -64,12 +62,11 @@ class Inkmark
     # This is a class-method fast path that skips Inkmark instance and
     # Options copy allocation for the common one-shot render pattern.
     # When the caller passes +options: nil+ (the default), we reuse the
-    # cached frozen hash that {Inkmark::Options#to_native_hash_frozen}
-    # returns; the cache lives on the Options instance itself and is
-    # invalidated by the Options mutation methods, so
-    # +Inkmark.default_options.tables = false+ followed by
-    # +Inkmark.to_html(src)+ picks up the new value without stale-cache
-    # bugs.
+    # frozen hash memoized on {default_options} by
+    # {Inkmark::Options#to_native_hash_frozen}. {configure} and
+    # {default_options=} install a whole new frozen instance rather than
+    # mutating the shared one, so the next render sees the new values
+    # without any stale-cache bugs.
     #
     # **Raw HTML safety.** +raw_html: false+ (the default) escapes
     # every raw HTML tag in the source—safe for untrusted input.
@@ -351,33 +348,65 @@ class Inkmark
     end
 
     # Return an array of available syntax-highlighting theme names.
-    # Memoized—the theme list is fixed at compile time.
+    # Memoized—the theme list is fixed at compile time. The memo is
+    # warmed while this file loads (see the bottom of the file), so
+    # non-main Ractors only ever read it.
     #
-    # @return [Array<String>]
+    # @return [Array<String>] frozen, with frozen elements
     def highlight_themes
-      @highlight_themes ||= _syntax_themes.freeze
+      @highlight_themes ||= _syntax_themes.each(&:freeze).freeze
     end
 
-    # The class-level default options used when no per-instance options are given.
+    # The process-wide default options, used when a render is given no
+    # options of its own. The instance is frozen all the way down and
+    # shared by every thread and Ractor in the process; change it with
+    # {configure} or {default_options=}, never in place.
     #
-    # @return [Inkmark::Options]
+    # @return [Inkmark::Options] frozen
     def default_options
-      @default_options ||= Inkmark::Options.new
+      @default_options || DEFAULT_OPTIONS
     end
 
-    # Replace the class-level default options.
+    # Replace the process-wide default options. The value is copied and
+    # frozen all the way down (+Ractor.make_shareable+), so the caller
+    # keeps its own object mutable and worker Ractors can read the
+    # result. Call this on the main Ractor before spawning workers.
     #
-    # @param value [Hash, Inkmark::Options] new defaults; a Hash is converted to
-    #   Inkmark::Options, a Inkmark::Options is duped
-    # @return [Inkmark::Options] the stored options object
+    # @param value [Hash, Inkmark::Options] new defaults; a Hash is
+    #   converted to Inkmark::Options
+    # @return [Inkmark::Options] the stored, frozen options
     # @raise [TypeError] if +value+ is not a Hash or Inkmark::Options
+    # @example
+    #   Inkmark.default_options = { preset: :recommended, math: true }
     def default_options=(value)
-      @default_options =
+      options =
         case value
-        when Inkmark::Options then value.dup
+        when Inkmark::Options then value
         when Hash then Inkmark::Options.new(value)
         else raise TypeError, "default_options must be a Hash or Inkmark::Options, got #{value.class}"
         end
+      # Copy-on-write of a shareable value: main-Ractor configuration.
+      @default_options = Ractor.make_shareable(options, copy: true) # audition:disable class-level-state
+    end
+
+    # Adjust the process-wide default options. Yields a mutable copy of
+    # the current {default_options}; the result is stored frozen through
+    # {default_options=}. Successive calls build on each other. Call this
+    # on the main Ractor before spawning workers.
+    #
+    # @yieldparam options [Inkmark::Options] a mutable copy of the
+    #   current defaults
+    # @return [Inkmark::Options] the stored, frozen options
+    # @example In an application initializer
+    #   Inkmark.configure do |options|
+    #     options.math = true
+    #     options.links = { nofollow: true }
+    #   end
+    def configure
+      options = default_options.dup
+      yield options
+      self.default_options = options
+      default_options
     end
 
     private
@@ -413,12 +442,18 @@ class Inkmark
     end
   end
 
+  # Built-in defaults, served by {default_options} until {configure} or
+  # {default_options=} installs a replacement. Frozen all the way down
+  # (which also memoizes its FFI hash, see {Inkmark::Options#freeze}).
+  DEFAULT_OPTIONS = Ractor.make_shareable(Inkmark::Options.new)
+  private_constant :DEFAULT_OPTIONS
+
   # Create a new renderer for +source+.
   #
   # @param source [String, nil] markdown source; +nil+ is treated as an
   #   empty string
   # @param options [Hash, Inkmark::Options, nil] rendering options; falls back
-  #   to a dup of {Inkmark.default_options} when nil
+  #   to a mutable copy of {Inkmark.default_options} when nil
   # @raise [TypeError] if +options+ is not a Hash, Inkmark::Options, or nil
   def initialize(source = nil, options: nil)
     self.source = source
@@ -459,8 +494,8 @@ class Inkmark
 
   # Set rendering options.
   #
-  # @param value [Hash, Inkmark::Options, nil] new options; nil resets to a dup
-  #   of {Inkmark.default_options}
+  # @param value [Hash, Inkmark::Options, nil] new options; nil resets to a
+  #   mutable copy of {Inkmark.default_options}
   # @return [Inkmark::Options] the stored options object
   # @raise [TypeError] if +value+ is not a Hash, Inkmark::Options, or nil
   def options=(value)
@@ -681,6 +716,9 @@ class Inkmark
   # The raw YAML text is extracted by Rust during the event walk;
   # parsing uses Ruby's stdlib +YAML.safe_load+ so all standard YAML
   # types (strings, numbers, arrays, nested hashes) are supported.
+  # Psych is loaded here, on first use, rather than with the gem: front
+  # matter is opt-in, and this keeps Psych's load time and its own
+  # constants out of processes that never enable it.
   #
   # @return [Hash, nil] parsed frontmatter or nil
   # @example
@@ -691,7 +729,10 @@ class Inkmark
     return @frontmatter if defined?(@frontmatter)
     return @frontmatter = nil unless @options[:frontmatter]
     to_html unless @frontmatter_raw
-    @frontmatter = @frontmatter_raw ? YAML.safe_load(@frontmatter_raw) : nil
+    return @frontmatter = nil unless @frontmatter_raw
+
+    require "yaml" unless defined?(::YAML) # audition:disable runtime-require
+    @frontmatter = YAML.safe_load(@frontmatter_raw)
   end
 
   private
@@ -715,3 +756,8 @@ class Inkmark
     extract.is_a?(Hash) && extract.any? { |_, v| v }
   end
 end
+
+# Warm the class-level memo on the main Ractor while loading, so worker
+# Ractors only ever read it (a first write from a worker would raise
+# Ractor::IsolationError).
+Inkmark.highlight_themes

data/sig/inkmark.rbs

@@ -179,6 +179,7 @@ class Inkmark
   def self.highlight_themes: () -> Array[String]
   def self.default_options: () -> Inkmark::Options
   def self.default_options=: (options_input value) -> Inkmark::Options
+  def self.configure: () { (Inkmark::Options options) -> void } -> Inkmark::Options
 
   # ── Native bindings (private in spirit; registered on the class) ──────
   def self._native_to_html: (String source, Hash[Symbol, untyped]? opts_hash) -> String

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: inkmark
 version: !ruby/object:Gem::Version
-  version: 0.1.4
+  version: 0.2.0
 platform: aarch64-linux
 authors:
 - Yaroslav Markin
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2026-06-25 00:00:00.000000000 Z
+date: 2026-09-06 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rake
@@ -44,14 +44,14 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '3.9'
+        version: '4.0'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '3.9'
+        version: '4.0'
 - !ruby/object:Gem::Dependency
   name: yard
   requirement: !ruby/object:Gem::Requirement