prosemirror 0.0.1 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9930d278779ec6b0103e6ed49ad729967b9de2de4041e9d3c375c287318ad346
-  data.tar.gz: b749da9ec576d1f8044e43a27eaa1be3f7416f8e5d72b4d897b55e2c7e628507
+  metadata.gz: 1006b6a2ecb95f5a4d603d5d9321bbdab419f26f882365ff14d1692f27970ce7
+  data.tar.gz: 22734518a2e81ecaba0ff64ed5057f40705dfb55dcd919567673f88e7cbf7e45
 SHA512:
-  metadata.gz: 7c6dee0d8cf9873e8e9eeb79d61b99f067a40e9046c8e531cf71576a2655668bc590b67749c2fdc791be8f085134307a9b111232425739d9f8a6e04e660f322e
-  data.tar.gz: c4ab45d99353f27037254abec0f38dfc21c4608beb6a535eb015094b7b263b699767782347c17fa0f1efaa3ebd4837ec0b3e6f0f5be369ec40bb4a202c2e4e74
+  metadata.gz: 0f4b24b76e78e49523f068aa8520304c955428d4ff295c0e0f918dfad07ad0bc5b7ee391b8dacaeabf258f871d99f2dcfba15e4ebad4bec961e97529cdd24f34
+  data.tar.gz: be218156ef3b417342de7d393d219b5019fe6f270a9c865e5cce9b5f9a2436008f59d5ada72d0111e09152586a06e21a7e98653ce4002923049eb0e70331daa0

data/CHANGELOG.md

@@ -1,5 +1,25 @@
 ## [Unreleased]
 
+## [0.2.0] - 2026-10-23
+
+- Import HTML with `Prosemirror.from_html` (or `schema.parse_html`), as ProseMirror's `DOMParser` does. Needs the [`herb`](https://herb-tools.dev) gem, which isn't installed with this gem.
+- Node and mark types declare how to recognize them in HTML with `parse_html`, like ProseMirror's parse rules, and attributes with `prop …, parse_html:`. The built-in types have Tiptap's rules.
+- Table cells have an `align` attribute (`left`, `right` or `center`), rendered as a `text-align` style.
+- `Schema.tiptap` sorts marks in Tiptap's order: `code` now comes before `italic`, and `strike` before `underline`.
+- Tiptap's `code` mark can't be combined with other marks, as in Tiptap. `Schema.prosemirror` uses a new `Marks::Basic::Code`, which can.
+- `TYPES.md` documents node and mark types: options, attributes, rendering helpers and parse rules.
+- Custom types can pass Array, Hash or Date attribute values to Phlex outside Rails. Phlex 2.4.1 raised a `NameError` without the `date` library.
+
+## [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,174 @@
-# 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, and import HTML into them, 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). Markdown import is 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
+```
+
+## HTML import
+
+HTML import uses [Herb](https://herb-tools.dev)'s parser, which never raises on malformed HTML. Add it to your Gemfile:
+
+```sh
+bundle add herb
+```
+
+```ruby
+doc = Prosemirror.from_html("<h2>Hello</h2><p>World</p>")
+doc.to_h  # => { "type" => "doc", "content" => [{ "type" => "heading", ... }, ...] }
+```
+
+It works like ProseMirror's `DOMParser`, and for the built-in types gives the same JSON as Tiptap's `generateJSON`, apart from invalid attributes:
+
+- each node and mark type recognizes its elements with its parse rules: `<b>`, `<strong>` and `font-weight: bold` all give `bold`;
+- whitespace is collapsed, except in code blocks;
+- content that doesn't fit where it is gets wrapped or moved: loose text becomes a paragraph, an `<li>` outside a list gets a list;
+- elements without a rule are unwrapped, and `script`, `style` and similar are ignored;
+- entities are decoded, and ERB tags (`<%= … %>`) are kept as text;
+- invalid attributes are fixed and reported, as in [Invalid documents](#invalid-documents).
+
+## 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`).
 
-TODO: Write usage instructions here
+```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.
+
+`parse_html` says which elements become this type when importing HTML, and `prop … parse_html:` how to read an attribute:
+
+```ruby
+class ImageBlock < Prosemirror::NodeType
+  prop :caption, _String?, parse_html: ->(element) { element.query("figcaption")&.text_content }
+
+  parse_html(tag: "figure.image") { |element| {src: element.query("img")&.[]("src")} }
+end
+```
+
+[Node and mark types](TYPES.md) documents every option: groups, content expressions, allowed marks, attribute names in JSON, rendering helpers, and parse rules. See the [cookbook](COOKBOOK.md) for recipes, like skipping empty paragraphs.
+
+### 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,215 @@
+# 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 (released)
+
+- `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.
+- Attributes a type doesn't declare kept in `unknown_attrs`: never rendered, and given back by `to_h`.
+- `Schema`, `NodeType` and `MarkType`, with the options of ProseMirror's `NodeSpec` and `MarkSpec`: `content`, `group`, `inline`, `marks`, `whitespace`, `leaf_text`, `excludes`, `spanning`. `marks`, `whitespace` and `excludes` are declared, but only take effect with HTML import (0.2) and validation (0.4), as ProseMirror's `fromJSON` doesn't enforce them either.
+- `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_phlex` to render in Phlex components, and `render doc` in ERB templates and ViewComponents.
+- `node` and `render_content` in node types, to render parts of a node's content.
+- `to_text`, like Tiptap's `getText`.
+- `case: :camel`, name aliases, allowed URL schemes, `resolve_url` (a URL it can't resolve is removed and reported).
+- One JSON test fixture per node and mark, for both schemas.
+- A [cookbook](COOKBOOK.md).
+- 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 (released)
+
+- `Prosemirror.from_html`, built on [Herb](https://herb-tools.dev), which doesn't raise on bad HTML.
+- 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.