prosemirror 0.0.1 → 0.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9930d278779ec6b0103e6ed49ad729967b9de2de4041e9d3c375c287318ad346
-  data.tar.gz: b749da9ec576d1f8044e43a27eaa1be3f7416f8e5d72b4d897b55e2c7e628507
+  metadata.gz: 7d4941e1033d3813a090427d6d94aac49e2ec017e24f5b1f4a3d8fe4f2600e29
+  data.tar.gz: 04b280abbbe4cb7d997f2c834696faba70e93cf1956a41f9516eeef62fc7ff2a
 SHA512:
-  metadata.gz: 7c6dee0d8cf9873e8e9eeb79d61b99f067a40e9046c8e531cf71576a2655668bc590b67749c2fdc791be8f085134307a9b111232425739d9f8a6e04e660f322e
-  data.tar.gz: c4ab45d99353f27037254abec0f38dfc21c4608beb6a535eb015094b7b263b699767782347c17fa0f1efaa3ebd4837ec0b3e6f0f5be369ec40bb4a202c2e4e74
+  metadata.gz: 1641b792c40a58d4b09f158a9ade19d48a85eebc15f7dc1039b913ab056b6c08c0bd4fc27e8809effbdee3e3a0681c1dc8dcf640ca2d2fdeae120314e341a4ce
+  data.tar.gz: cbcabc4bdcf30ad40931501c8f0ab10a84948c0d76d2e31939bcaa2783f17566a539505a897c4992e73817c454ab52e4178a1ef3a8383abf5f7e68dbf34c72ca

data/CHANGELOG.md

@@ -1,5 +1,15 @@
 ## [Unreleased]
 
+## [0.1.0] - 2026-10-23
+
+- Render ProseMirror and Tiptap JSON to HTML (`to_html`) and text (`to_text`). In Rails, `render doc` works in ERB templates and ViewComponents, and `render doc.to_phlex` in Phlex components.
+- `Schema.tiptap` and `Schema.prosemirror`, with `case: :camel` for camelCase type names.
+- Custom node and mark types, as Phlex components with Literal attributes.
+- Invalid attributes are converted, replaced by their default, or removed, and reported with `on_invalid`. `strict: true` raises instead.
+- Attributes a node or mark type doesn't declare are kept in `unknown_attrs`: never rendered, and given back by `to_h`.
+- URL scheme allowlist for links and images, and `resolve_url` to rewrite URLs. A URL that `resolve_url` turns into nil is removed and reported.
+- A cookbook with recipes: skip empty paragraphs, heading anchors, render your own components, links to records with GlobalID.
+
 ## [0.0.1] - 2023-07-03
 
 - Initial release

data/COOKBOOK.md

@@ -0,0 +1,108 @@
+# Cookbook
+
+Short recipes for common needs. Each one replaces a built-in type with a subclass, registered with `Schema#with`:
+
+```ruby
+Prosemirror.schema = Prosemirror::Schema.tiptap.with(Paragraph)
+```
+
+## Skip empty paragraphs
+
+Editors often leave empty paragraphs, for example after pressing Enter twice. To render nothing for them:
+
+```ruby
+class Paragraph < Prosemirror::Nodes::Paragraph
+  def view_template(&)
+    p(&) unless node.content.empty?
+  end
+end
+```
+
+A paragraph that only holds spaces or line breaks is not empty. To skip those too, check the text instead, keeping paragraphs with an inline image or another leaf node:
+
+```ruby
+class Paragraph < Prosemirror::Nodes::Paragraph
+  def view_template(&)
+    p(&) unless blank?
+  end
+
+  private
+
+  def blank?
+    node.text_content.strip.empty? && node.content.all? { |child| child.text? || child.type == :hard_break }
+  end
+end
+```
+
+`to_text` still separates empty paragraphs with a blank line, as ProseMirror does. `to_h` keeps them, so the editor gets the document back unchanged.
+
+## Heading anchors
+
+To link to a section, give each heading an `id` made from its text, unless the document already has one:
+
+```ruby
+class Heading < Prosemirror::Nodes::Heading
+  prop :id, _String?
+
+  def view_template(&)
+    tag(:"h#{@level}", id: @id || slug, &)
+  end
+
+  private
+
+  # "Café & co" becomes "cafe-co". In Rails, `node.text_content.parameterize` does the same.
+  def slug
+    slug = node.text_content.unicode_normalize(:nfkd).gsub(/\p{Mn}/, "").downcase.gsub(/[^a-z0-9]+/, "-")
+    slug = slug.delete_prefix("-").delete_suffix("-")
+    slug unless slug.empty?
+  end
+end
+```
+
+A node doesn't see the rest of the document, so two headings with the same text get the same `id`.
+
+## Render your own components
+
+A node type is a Phlex component, so it can render the app's Phlex components:
+
+```ruby
+class ImageBlock < Prosemirror::NodeType
+  group :block
+
+  prop :src, String
+  prop :caption, _String?
+
+  def view_template
+    render Components::Figure.new(src: safe_url(@src), caption: @caption)
+  end
+end
+```
+
+In Rails, components that use Rails helpers (`image_tag`, `url_for`…) need a view context. With [`phlex-rails`](https://github.com/yippee-fun/phlex-rails), they get one when the document is rendered with `render doc.to_phlex`, from a Phlex view or an ERB template. The same applies to a ViewComponent: `render FigureComponent.new(…)` works from a node in that case.
+
+`<%= render doc %>` and `to_html` render the document on its own, without a view context, for example in a mailer or a JSON response. To support them, render the component with a controller instead, and output its HTML as is:
+
+```ruby
+def view_template
+  raw safe(ApplicationController.render(FigureComponent.new(src: @src, caption: @caption), layout: false))
+end
+```
+
+`raw safe(...)` outputs HTML without escaping it: only use it for HTML built by your own components, never for a value from the document.
+
+## Links to records with GlobalID
+
+Store links to records as GlobalIDs (`gid://app/Page/1`), so they keep working when a record's URL changes, and turn them into URLs when rendering:
+
+```ruby
+Prosemirror::Schema.tiptap(
+  resolve_url: lambda do |url|
+    next url unless url.start_with?("gid://")
+
+    record = GlobalID::Locator.locate(url)
+    Rails.application.routes.url_helpers.polymorphic_path(record) if record
+  end
+)
+```
+
+`resolve_url` runs before the allowed URL schemes are checked, so `gid://` doesn't need to be allowed. When the record doesn't exist, the link is removed, its text is kept, and the problem goes to `on_invalid`. Each link runs one query.

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2026 Hans Lemuet
+
+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

@@ -1,31 +1,188 @@
-# Prosemirror
+# ProseMirror
 
-TODO: Delete this and the text below, and describe your gem
+Render [ProseMirror](https://prosemirror.net) and [Tiptap](https://tiptap.dev) documents to HTML and text, in Ruby.
 
-Welcome to your new gem! In this directory, you'll find the files you need to be able to package up your Ruby library into a gem. Put your Ruby code in the file `lib/prosemirror`. To experiment with that code, run `bin/console` for an interactive prompt.
+- HTML is built with [Phlex](https://www.phlex.fun) and escaped as it is written.
+- Attributes are typed with [Literal](https://literal.fun).
+- Link and image URLs must use an allowed scheme.
+- No Rails dependency.
+
+This gem replaces [prosemirror_to_html](https://github.com/etaminstudio/prosemirror_to_html) and [html_to_prosemirror](https://github.com/etaminstudio/html_to_prosemirror). HTML and Markdown import are planned: see the [roadmap](ROADMAP.md).
 
 ## Installation
 
-TODO: Replace `UPDATE_WITH_YOUR_GEM_NAME_PRIOR_TO_RELEASE_TO_RUBYGEMS_ORG` with your gem name right after releasing it to RubyGems.org. Please do not do it earlier due to security reasons. Alternatively, replace this section with instructions to install your gem from git if you don't plan to release to RubyGems.org.
+```sh
+bundle add prosemirror
+```
 
-Install the gem and add to the application's Gemfile by executing:
+## Usage
 
-    $ bundle add UPDATE_WITH_YOUR_GEM_NAME_PRIOR_TO_RELEASE_TO_RUBYGEMS_ORG
+```ruby
+require "prosemirror"
 
-If bundler is not being used to manage dependencies, install the gem by executing:
+doc = Prosemirror.parse(record.content)  # a Hash or a JSON string
 
-    $ gem install UPDATE_WITH_YOUR_GEM_NAME_PRIOR_TO_RELEASE_TO_RUBYGEMS_ORG
+doc.to_html  # => "<h2>Hello</h2><p>World</p>"
+doc.to_text  # => "Hello\n\nWorld"
+doc.to_h     # => { "type" => "doc", "content" => [...] }
+```
 
-## Usage
+`to_h` gives the document back as JSON, with invalid parts fixed (see [Invalid documents](#invalid-documents)). Attributes the schema doesn't declare, for example from a Tiptap extension it doesn't know, are kept as they are in `unknown_attrs`, and never rendered.
+
+In Rails, `to_html` returns an `html_safe` string, and documents can be rendered like other objects in ERB templates and ViewComponents:
+
+```erb
+<%= render doc %>
+```
+
+In a Phlex component, use `to_phlex`, which writes directly into the page:
+
+```ruby
+render doc.to_phlex
+```
+
+Documents are `Enumerable`, and nodes support pattern matching:
+
+```ruby
+doc.select { |node| node in { type: :heading, attrs: { level: 1 } } }
+doc.content.first.text_content
+```
+
+## Schemas
+
+Two schemas are included:
+
+```ruby
+Prosemirror::Schema.tiptap       # Tiptap's StarterKit, tables, images, underline, subscript, superscript, highlight (default)
+Prosemirror::Schema.prosemirror  # prosemirror-schema-basic and prosemirror-schema-list
+```
+
+Type names are written in snake_case (`bullet_list`). Use `case: :camel` to write camelCase (`bulletList`), as Tiptap does. Both cases are always accepted on input.
+
+```ruby
+Prosemirror.schema = Prosemirror::Schema.tiptap(case: :camel)
+```
+
+## Custom nodes and marks
+
+A node type is a Phlex component, and its attributes are Literal properties. The type name comes from the class name (`ImageBlock` → `image_block`).
+
+```ruby
+class ImageBlock < Prosemirror::NodeType
+  group :block
+
+  prop :src, String
+  prop :caption, _String?
+
+  def view_template
+    figure do
+      img(src: safe_url(@src))
+      figcaption { @caption } if @caption
+    end
+  end
+end
+
+Prosemirror.schema = Prosemirror::Schema.tiptap.with(ImageBlock)
+```
+
+In `view_template`, `node` is the node being rendered, and `render_content(nodes)` renders any of its descendants.
+
+When an attribute has another name in JSON, declare it with `json:`:
+
+```ruby
+prop :text_align, _String?, json: "textAlign"
+```
 
-TODO: Write usage instructions here
+See the [cookbook](COOKBOOK.md) for recipes, like skipping empty paragraphs.
+
+### Content expressions
+
+`content` says which children a node can have. It works like a regular expression, with node names or group names instead of characters:
+
+| Expression | Meaning |
+|---|---|
+| `"text*"` | zero or more text nodes |
+| `"inline*"` | zero or more nodes of the `inline` group (text, hard breaks…) |
+| `"block+"` | one or more nodes of the `block` group |
+| `"paragraph block*"` | a paragraph, then zero or more blocks |
+| `"(table_cell \| table_header)*"` | zero or more cells or header cells |
+| `"caption?"` | zero or one caption |
+| `"cell{2}"`, `"cell{1,5}"`, `"cell{2,}"` | exactly two, one to five, two or more cells |
+
+A node type joins a group with `group`, for example `group :block`. A node type without `content` has no children, like an image.
+
+The built-in types use these groups: `block` for paragraphs, headings, lists, tables…, `inline` for text and hard breaks, and `list` for lists.
+
+Today, content expressions are used to find the nodes that contain text, for `to_text`. Rendering doesn't check them. They will also be used by HTML import and validation. See [ProseMirror's guide](https://prosemirror.net/docs/guide/#schema.content_expressions) for details.
+
+### Other options
+
+| Node type option | Meaning |
+|---|---|
+| `group :block, :list` | the groups of the type |
+| `content "inline*"` | the allowed children |
+| `inline` | the node is inline, like text (also implied by `group :inline`) |
+| `marks ""` | the marks allowed inside: names or groups, `"_"` for all, `""` for none |
+| `code` | the node contains code |
+| `whitespace :pre` | keep whitespace when importing HTML (implied by `code`) |
+| `leaf_text "\n"` | the text of a node without children, for `to_text`; also takes a block called with the node |
+| `type_name :image_block` | the type name, when it differs from the class name |
+| `aliases :figure` | other type names accepted on input |
+
+| Mark type option | Meaning |
+|---|---|
+| `spanning false` | render one element per node, instead of one for adjacent nodes with the same mark |
+| `excludes "_"` | the marks it can't be combined with |
+| `group`, `code`, `type_name`, `aliases` | as for node types |
+
+### Changing built-in types
+
+To change how a built-in type renders, subclass it:
+
+```ruby
+class Paragraph < Prosemirror::Nodes::Paragraph
+  def view_template(&) = p(class: "text-lg", &)
+end
+
+Prosemirror.schema = Prosemirror::Schema.tiptap.with(Paragraph)
+```
+
+## Invalid documents
+
+Bad data doesn't break the page. For an invalid attribute, the gem:
+
+1. converts it when the meaning is clear (`"2"` becomes `2`);
+2. otherwise, uses its default;
+3. if it has no default, removes the node or mark (a link with an invalid `href` keeps its text).
+
+Unknown nodes render their content. Report problems, or raise them:
+
+```ruby
+Prosemirror::Schema.tiptap(on_invalid: ->(error) { Rails.error.report(error) })
+Prosemirror::Schema.tiptap(strict: true)  # raises Prosemirror::InvalidDocument
+```
+
+## URLs
+
+Links and images allow `http`, `https`, `mailto`, `tel` and relative URLs. Change the list with `url_schemes:`, or rewrite URLs before they are checked with `resolve_url:`:
+
+```ruby
+Prosemirror::Schema.tiptap(
+  url_schemes: %w[https],
+  resolve_url: ->(url) { url.start_with?("gid://") ? url_for(GlobalID::Locator.locate(url)) : url }
+)
+```
 
 ## Development
 
-After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake test` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake test` to run the tests, and `rake` to also run [Standard](https://github.com/standardrb/standard). You can also run `bin/console` for an interactive prompt that will allow you to experiment.
 
 To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and the created tag, and push the `.gem` file to [rubygems.org](https://rubygems.org).
 
 ## Contributing
 
-Bug reports and pull requests are welcome on GitHub at https://github.com/[USERNAME]/prosemirror.
+Bug reports and pull requests are welcome on GitHub at https://github.com/etaminstudio/prosemirror.
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](LICENSE.txt).

data/ROADMAP.md

@@ -0,0 +1,211 @@
+# Roadmap
+
+`prosemirror` is a Ruby gem for [ProseMirror](https://prosemirror.net) and [Tiptap](https://tiptap.dev) documents. It renders them to HTML or text, and imports HTML, Markdown or text into them.
+
+Feedback is welcome in the issues.
+
+## Why
+
+ProseMirror editors store documents as JSON. Ruby apps need to render this JSON to HTML, extract its text, and import old HTML or Markdown content. Today, this is split across several small gems:
+
+| Gem | Does | Downloads | Limits |
+|---|---|---|---|
+| [`prosemirror_to_html`](https://rubygems.org/gems/prosemirror_to_html) | JSON → HTML | 122k | Builds HTML strings, then cleans them with Loofah |
+| [`html_to_prosemirror`](https://rubygems.org/gems/html_to_prosemirror) | HTML → JSON | 19k | Few node types, regex-based cleanup |
+| [`prose_mirror_ruby`](https://rubygems.org/gems/prose_mirror_ruby) | JSON → Markdown | 78k | Needs ActiveSupport, no HTML |
+| [`prose_render`](https://github.com/mattbarrry/prose_render) (unreleased) | JSON → HTML | — | Needs Rails and ViewComponent |
+
+They use different type names (`bullet_list` or `bulletList`, `strong` or `bold`), and none of them uses the same schema for rendering and parsing. `prosemirror` replaces the first two, which have the same maintainers.
+
+## Principles
+
+- [Phlex](https://www.phlex.fun) builds the HTML and escapes text and attribute values. [Literal](https://literal.fun) types the attributes, so a heading level is an integer from 1 to 6. URLs must use an allowed scheme. Attribute names never come from the document. Nothing is cleaned up after rendering.
+- Output is HTML5 only: no `<strike>`, `<font>` or `align=`. The importer still reads them.
+- Bad data doesn't break the page. For an invalid attribute:
+  1. convert it when the meaning is clear (`"2"` becomes `2`);
+  2. otherwise, use its default (a heading with `level: "abc"` becomes an `h1`, and keeps its text);
+  3. if it has no default, remove what it belongs to: an image without a valid `src`, or a link with an invalid `href` (the text stays).
+
+  An unknown node renders its content. An `on_invalid` hook reports each problem, for example to an error tracker. A strict mode raises errors instead. `to_h` returns the corrected document.
+- Only `phlex` and `literal` are required: no Rails, no Nokogiri. [`herb`](https://herb-tools.dev) (HTML) and [`commonmarker`](https://github.com/gjtorikian/commonmarker) (Markdown) are loaded only by the importers.
+- Schemas, content expressions, marks and parse rules work as in [ProseMirror's guide](https://prosemirror.net/docs/guide/#schema), with the same JSON format. Methods keep ProseMirror's names in Ruby style (`text_content`, `descendants`, `check`).
+- Nodes are immutable values that support pattern matching. Documents are `Enumerable`. Node types are classes.
+- Each node type defines its attributes, its allowed content, its HTML output, and how to recognize it in HTML. Rendering and import use the same schema.
+
+## API
+
+```ruby
+doc = Prosemirror.parse(record.content)  # Hash or JSON string
+doc = Prosemirror.from_html(html)
+doc = Prosemirror.from_markdown(markdown)
+doc = Prosemirror.from_text(text)
+
+doc.to_html  # => "<h2>Hello</h2><p>World</p>"
+doc.to_text  # => "Hello\n\nWorld"
+doc.to_h     # for a json/jsonb column
+
+doc.select { |node| node in { type: :heading, attrs: { level: 1 } } }
+```
+
+### Custom nodes
+
+A node type is a Phlex component. Its attributes are Literal properties. Its name comes from the class name (`ImageBlock` → `image_block`).
+
+```ruby
+class ImageBlock < Prosemirror::NodeType
+  group :block
+
+  prop :src, _String?
+  prop :alt, _String?
+
+  parse_html tag: "img[data-block]" do |element|
+    { src: element["src"], alt: element["alt"] }
+  end
+
+  def view_template
+    figure { img(src: safe_url(@src), alt: @alt) }
+  end
+end
+
+schema = Prosemirror::Schema.tiptap.with(ImageBlock)
+Prosemirror.parse(json, schema:).to_html
+```
+
+To change a built-in type, subclass it:
+
+```ruby
+class Heading < Prosemirror::Nodes::Heading
+  prop :id, _String?
+
+  def view_template(&)
+    tag(:"h#{@level}", id: @id || slugify(node.text_content), class: "heading", &)
+  end
+end
+```
+
+A node can render parts of its content in different places, with `node` and `render_content`:
+
+```ruby
+# A quote whose last line, after a line break, is the author
+class Blockquote < Prosemirror::Nodes::Blockquote
+  def view_template
+    inline = node.content.flat_map(&:content)
+    split = inline.rindex { |child| child.type == :hard_break }
+
+    figure do
+      blockquote { render_content(split ? inline[...split] : inline) }
+      figcaption { render_content(inline[(split + 1)..]) } if split
+    end
+  end
+end
+```
+
+A `resolve_url` hook can rewrite URLs before they are checked, for example to turn `gid://` references into links:
+
+```ruby
+Prosemirror::Schema.tiptap(resolve_url: ->(url) { url.start_with?("gid://") ? url_for(GlobalID::Locator.locate(url)) : url })
+```
+
+In Rails, a custom node can render view components with [`phlex-rails`](https://github.com/yippee-fun/phlex-rails).
+
+### Schemas
+
+The gem has two schemas:
+
+```ruby
+Prosemirror::Schema.tiptap       # Tiptap's StarterKit and common extensions (default)
+Prosemirror::Schema.prosemirror  # ProseMirror's prosemirror-schema-basic and prosemirror-schema-list
+```
+
+They differ in more than names:
+
+| | `Schema.tiptap` | `Schema.prosemirror` |
+|---|---|---|
+| Marks | `bold`, `italic`, `code`, `link`, `strike`, `underline`… | `strong`, `em`, `code`, `link` |
+| Ordered list | `start` | `order` |
+| Code block | `language` | no attributes |
+| Image | block | inline |
+| Link | `href`, `target`, `rel`, `class` | `href`, `title` |
+
+- Both use snake_case type names (`bullet_list`, `hard_break`). `case: :camel` outputs camelCase type names (`bulletList`), as Tiptap does.
+- `case:` doesn't change attribute names. Editors only read the exact names they declare, and Tiptap mixes styles (`textAlign`, `colwidth`). In Ruby, attributes are snake_case properties. A different JSON name is declared on the property (`prop :text_align, _String?, json: "textAlign"`), and the built-in types use Tiptap's exact names. Input accepts both forms.
+- Both accept input in both cases, and with the other schema's names (`strong` for `bold`, `order` for `start`).
+- Nodes that are the same in both (paragraph, heading, blockquote…) use the same classes.
+
+## Milestones
+
+### 0.1: Rendering
+
+- `Node`, `Mark` and `Document` values, built from a Hash or a JSON string, with a nesting limit.
+- Normalization as in ProseMirror: marks sorted by schema order, adjacent text with the same marks joined, empty text removed.
+- `Schema`, `NodeType` and `MarkType`, with the options of ProseMirror's `NodeSpec` and `MarkSpec`: `content`, `group`, `inline`, `marks`, `whitespace`, `leaf_text`, `excludes`, `spanning`.
+- `Schema.tiptap`: `doc`, `paragraph`, `text`, `heading`, `blockquote`, `bullet_list`, `ordered_list`, `list_item`, `code_block`, `hard_break`, `horizontal_rule`, `image`, `table`, `table_row`, `table_header`, `table_cell`. Marks: `link`, `bold`, `italic`, `underline`, `strike`, `code`, `subscript`, `superscript`, `highlight`.
+- `Schema.prosemirror`: exactly the nodes and marks of `prosemirror-schema-basic` and `prosemirror-schema-list`.
+- `to_html`, with one tag for a mark shared by adjacent text (one `<a>` for a link with mixed formatting).
+- `to_text`, like Tiptap's `getText`.
+- `case: :camel`, name aliases, allowed URL schemes, `resolve_url`.
+- One JSON test fixture per node and mark.
+- Security tests, starting with every issue fixed in `prosemirror_to_html`:
+  - unescaped attribute values ([CVE-2025-64501](https://github.com/etaminstudio/prosemirror_to_html/security/advisories/GHSA-52c5-vh7f-26fx));
+  - attribute names from the document, like `onmouseover`, and `javascript:` URLs ([GHSA-6gj3-5qf2-wwvv](https://github.com/etaminstudio/prosemirror_to_html/security/advisories/GHSA-6gj3-5qf2-wwvv));
+  - a heading `level` like `1><script>`;
+  - other URL schemes, hidden schemes (`java\tscript:`), `style` injection, deep nesting.
+
+### 0.2: HTML import
+
+- `Prosemirror.from_html`, built on [Herb](https://herb-tools.dev), which doesn't raise on bad HTML and ships with Rails 8.2.
+- The importer also needs to:
+  - decode entities (`&amp;`, `&eacute;`), with the [WHATWG entity list](https://html.spec.whatwg.org/entities.json);
+  - keep `<% %>` in content as text;
+  - apply unclosed tags (`<strong>` without `</strong>`) to the rest of their parent;
+  - walk the tree without recursion, with a depth limit.
+- Parse rules like ProseMirror's `ParseRule`: simple CSS selectors, `style` rules, `attrs`, `priority`, `context`, `ignore`, `skip`, `preserve_whitespace`, and more.
+- ProseMirror's `DOMParser` behavior: collapse whitespace, wrap loose text in paragraphs, add missing wrappers (an `<li>` outside a list), unwrap unknown elements, ignore `script`, `style` and similar.
+- Marks from inline styles (`font-weight: bold`), for content pasted from Google Docs or Word.
+- Old HTML mapped to the schema: `<b>` and `<i>` to `bold` and `italic`, `<strike>` to `strike`, `<tt>` to `code`. `<font>` and `<center>` are unwrapped.
+- Tests: HTML from Tiptap gives the same JSON as Tiptap.
+
+### 0.3: Markdown and text import
+
+- `Prosemirror.from_markdown`, built from [`commonmarker`](https://github.com/gjtorikian/commonmarker)'s syntax tree, without going through HTML (like `prosemirror-markdown`). commonmarker's parser is written in Rust.
+- GitHub Flavored Markdown: tables, strikethrough, autolinks, task lists.
+- Custom node types can define their Markdown mapping.
+- Raw HTML in Markdown goes through the HTML importer if Herb is installed.
+- `Prosemirror.from_text`: blank lines make paragraphs, line breaks make hard breaks.
+
+### 0.4: Working with documents
+
+- Transformations that return a new document: rewrite links, unwrap lists, split paragraphs, remove empty ones.
+
+  ```ruby
+  doc.transform do |node|
+    case node
+    in { type: :bullet_list } then node.content.map { |item| item.content.first }
+    in { type: :paragraph } if node.blank? then nil
+    else node
+    end
+  end
+  ```
+- Validation against the schema (`check`).
+
+### 0.5: Markdown export
+
+- `doc.to_markdown`, like [`prosemirror-markdown`](https://github.com/ProseMirror/prosemirror-markdown). Useful to send content to LLMs.
+- Help wanted: it is self-contained and a good first contribution.
+
+### 0.6: More Tiptap node types
+
+- Task lists, text alignment, mentions, details, embeds.
+
+### 1.0
+
+- Stable API, documentation site, benchmarks.
+- Migration guides from `prosemirror_to_html` and `html_to_prosemirror`, and final releases of both pointing to `prosemirror`.
+- Used in production by [Trek](https://trek.etamin.studio), a Rails CMS that renders Tiptap documents with custom nodes.
+
+## Out of scope
+
+- CSS framework themes: subclass node types instead.
+- A Rails or ViewComponent dependency.
+- Editing features: positions, steps, commands, collaboration.
+- The editor itself.

data/lib/prosemirror/coerce.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+module Prosemirror
+  # Conversions for property values, used as Literal coercion blocks:
+  #
+  #   prop :level, _Integer(1..6), default: 1, &Coerce::INTEGER
+  module Coerce
+    # "2" becomes 2.
+    INTEGER = proc { |value| (value.is_a?(String) && value.match?(/\A\s*-?\d+\s*\z/)) ? value.to_i : value }
+
+    # "bullet_list" becomes :bullet_list.
+    SYMBOL = proc { |value| value.is_a?(String) ? value.to_sym : value }
+
+    # A frozen copy, unless the value is already frozen.
+    FROZEN = proc { |value| value.frozen? ? value : value.dup.freeze }
+  end
+end