prosereflect 0.1.1 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b84ac8ec1c9f76d0998f9b1be06b156f7ea6788f9c1d82fd2b2a34ef328263e0
-  data.tar.gz: 82c2549e3ae7a86cc6295e3b2230899638489743e4fa6d040a2a3f7fddbf8ffb
+  metadata.gz: d9f70970efc856c322c1d356262ae1492856c2432d2ed6343b7f00a4b96a97a9
+  data.tar.gz: 4670d12e397d85fa399ea4bd721d0eaa4d35aa24b7425c0bb7e6b61eb057a173
 SHA512:
-  metadata.gz: a7f45b590785499274eb6112a961e131af7af6a5c679a388eaf3bd01805a731f572fbf7d5efa938f5466e359e2c3dc81953816164ac3a3c0585ab9e98b97a220
-  data.tar.gz: dd99eed85e651b903869b53a09866a550e71b5fd29efbf8fa380b6f35bee33c2189675ca1897d10f11400975a45dbb13d798fef916a466b61181a9046fee5ff2
+  metadata.gz: 42bb32f0114a3cb597a65498681177c93345f3ddcff24412a2ba03dd8492b1ec0da306797ada94fac95c984e0f80a63631de555fae2a836b647c8805ab73e0b6
+  data.tar.gz: d6b5dcf22e6d6b0c923c5b35a1dbccecea6e7103af0001428ca567ad8f2333d2f63fe7652149f087b2ea0383beff80afc69e02b09f086f93b5fd51ee7be1dca1

data/.github/workflows/docs.yml

@@ -0,0 +1,63 @@
+name: docs
+
+on:
+  push:
+    branches: [main]
+    paths:
+    - 'docs/**'
+  pull_request:
+    paths:
+    - 'docs/**'
+  repository_dispatch:
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: false
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v6
+
+      - name: Setup Ruby
+        uses: ruby/setup-ruby@v1
+        with:
+          ruby-version: '3.3'
+          bundler-cache: true
+          cache-version: 0
+          working-directory: docs
+
+      - name: Setup Pages
+        id: pages
+        uses: actions/configure-pages@v5
+
+      - name: Build with Jekyll
+        run: bundle exec jekyll build --verbose --trace --baseurl "${{ steps.pages.outputs.base_path }}"
+        working-directory: docs
+        env:
+          JEKYLL_ENV: production
+
+      - name: Upload artifact
+        uses: actions/upload-pages-artifact@v4
+        with:
+          path: docs/_site
+
+  deploy:
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    if: ${{ github.ref == 'refs/heads/main' }}
+    runs-on: ubuntu-latest
+    needs: build
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4

data/.github/workflows/links.yml

@@ -0,0 +1,97 @@
+name: links
+
+on:
+  push:
+    branches:
+    - main
+    paths:
+    - 'docs/**'
+  pull_request:
+    paths:
+    - 'docs/**'
+
+# Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages
+permissions:
+  contents: read
+  pull-requests: write
+
+jobs:
+  link_checker:
+    runs-on: ubuntu-latest
+    steps:
+    - uses: actions/checkout@v6
+
+    - uses: ruby/setup-ruby@v1
+      with:
+        ruby-version: '3.4'
+        bundler-cache: true
+        working-directory: docs
+
+    - name: Build site
+      env:
+        JEKYLL_ENV: production
+      run: bundle exec jekyll build --trace
+      working-directory: docs
+
+    - name: Restore lychee cache
+      uses: actions/cache@v4
+      with:
+        path: .lycheecache
+        key: cache-lychee-${{ github.sha }}
+        restore-keys: cache-lychee-
+
+    - name: Check if site was built
+      run: |
+        if [ ! -d "_site" ]; then
+          echo "Error: _site directory not created"
+          exit 1
+        fi
+        echo "Site built successfully"
+        ls -la _site/
+      working-directory: docs
+
+    - name: Link Checker (Built Site)
+      uses: lycheeverse/lychee-action@v2
+      with:
+        args: >-
+          --verbose
+          --no-progress
+          --config lychee.toml
+          --root-dir "$(pwd)/_site"
+          --scheme https,http
+          '_site/**/*.html'
+        fail: true
+        output: link-check-results.md
+        format: markdown
+        workingDirectory: docs
+
+    - name: Upload link check results
+      if: always()
+      uses: actions/upload-artifact@v4
+      with:
+        name: link-check-results
+        path: |
+          docs/link-check-results.md
+        retention-days: 30
+
+    - name: Comment PR with results
+      if: failure() && github.event_name == 'pull_request'
+      uses: actions/github-script@v7
+      with:
+        script: |
+          const fs = require('fs');
+          let comment = '## Link Check Failed\n\n';
+
+          if (fs.existsSync('docs/link-check-results.md')) {
+            const results = fs.readFileSync('docs/link-check-results.md', 'utf8');
+            comment += '### Built Site Results\n\n' + results + '\n\n';
+          }
+
+          comment += '\n---\n\n*Please fix the broken links and push a new commit.*';
+
+          github.rest.issues.createComment({
+            issue_number: context.issue.number,
+            owner: context.repo.owner,
+            repo: context.repo.repo,
+            body: comment
+          });

data/.github/workflows/rake.yml

@@ -8,6 +8,10 @@ on:
     tags: [ v* ]
   pull_request:
 
+permissions:
+  contents: write
+  packages: write
+
 jobs:
   rake:
     uses: metanorma/ci/.github/workflows/generic-rake.yml@main

data/.github/workflows/release.yml

@@ -14,6 +14,11 @@ on:
   repository_dispatch:
     types: [ do-release ]
 
+permissions:
+  contents: write
+  packages: write
+  id-token: write
+
 jobs:
   release:
     uses: metanorma/ci/.github/workflows/rubygems-release.yml@main

data/.gitignore

@@ -10,3 +10,7 @@
 # rspec failure tracking
 .rspec_status
 Gemfile.lock
+docs/_site/
+docs/.jekyll-cache/
+docs/.bundle/
+docs/vendor/

data/.rubocop.yml

@@ -1 +1,19 @@
-inherit_from: .rubocop_todo.yml
+# Auto-generated by Cimas: Do not edit it manually!
+# See https://github.com/metanorma/cimas
+inherit_from:
+  - https://raw.githubusercontent.com/riboseinc/oss-guides/main/ci/rubocop.yml
+  - .rubocop_todo.yml
+
+inherit_mode:
+  merge:
+    - Exclude
+
+# local repo-specific modifications
+# ...
+plugins:
+  - rubocop-rspec
+  - rubocop-performance
+  - rubocop-rake
+
+AllCops:
+  TargetRubyVersion: 3.0

data/.rubocop_todo.yml

@@ -1,247 +1,183 @@
 # This configuration was generated by
 # `rubocop --auto-gen-config`
-# on 2025-05-12 01:22:35 UTC using RuboCop version 1.75.5.
+# on 2026-04-14 23:12:52 UTC using RuboCop version 1.86.1.
 # The point is for the user to remove these configuration records
 # one by one as the offenses are removed from the code base.
 # Note that changes in the inspected code, or installation of new
 # versions of RuboCop, may require this file to be generated again.
 
 # Offense count: 1
-# This cop supports safe autocorrection (--autocorrect).
-Layout/BlockEndNewline:
+Gemspec/RequiredRubyVersion:
   Exclude:
-    - 'bin/extract-ituob-amendments.rb'
+    - 'prosereflect.gemspec'
 
 # Offense count: 2
 # This cop supports safe autocorrection (--autocorrect).
-# Configuration parameters: AllowForAlignment.
-Layout/CommentIndentation:
+Layout/ElseAlignment:
   Exclude:
-    - 'e118_amendment.rb'
+    - 'lib/prosereflect/schema/schema_main.rb'
 
 # Offense count: 1
 # This cop supports safe autocorrection (--autocorrect).
-Layout/EmptyLineAfterGuardClause:
+# Configuration parameters: EnforcedStyleAlignWith.
+# SupportedStylesAlignWith: keyword, variable, start_of_line
+Layout/EndAlignment:
   Exclude:
-    - 'e118_amendment.rb'
+    - 'lib/prosereflect/schema/schema_main.rb'
 
 # Offense count: 1
 # This cop supports safe autocorrection (--autocorrect).
-# Configuration parameters: EmptyLineBetweenMethodDefs, EmptyLineBetweenClassDefs, EmptyLineBetweenModuleDefs, DefLikeMacros, AllowAdjacentOneLineDefs, NumberOfEmptyLines.
-Layout/EmptyLineBetweenDefs:
-  Exclude:
-    - 'e118_amendment.rb'
-
-# Offense count: 2
-# This cop supports safe autocorrection (--autocorrect).
-Layout/EmptyLines:
-  Exclude:
-    - 'e118_amendment.rb'
-
-# Offense count: 2
-# This cop supports safe autocorrection (--autocorrect).
-# Configuration parameters: EnforcedStyle.
-# SupportedStyles: empty_lines, empty_lines_except_namespace, empty_lines_special, no_empty_lines, beginning_only, ending_only
-Layout/EmptyLinesAroundClassBody:
-  Exclude:
-    - 'e118_amendment.rb'
-
-# Offense count: 2
-# This cop supports safe autocorrection (--autocorrect).
-# Configuration parameters: Width, AllowedPatterns.
+# Configuration parameters: Width, EnforcedStyleAlignWith, AllowedPatterns.
+# SupportedStylesAlignWith: start_of_line, relative_to_receiver
 Layout/IndentationWidth:
   Exclude:
-    - 'bin/extract-ituob-amendments.rb'
-    - 'e118_amendment.rb'
+    - 'lib/prosereflect/schema/schema_main.rb'
 
-# Offense count: 1
+# Offense count: 264
 # This cop supports safe autocorrection (--autocorrect).
-Lint/ScriptPermission:
+# Configuration parameters: Max, AllowHeredoc, AllowURI, AllowQualifiedName, URISchemes, AllowRBSInlineAnnotation, AllowCopDirectives, AllowedPatterns, SplitStrings.
+# URISchemes: http, https
+Layout/LineLength:
+  Enabled: false
+
+# Offense count: 5
+# Configuration parameters: IgnoreLiteralBranches, IgnoreConstantBranches, IgnoreDuplicateElseBranch.
+Lint/DuplicateBranch:
   Exclude:
-    - 'debug_loading.rb'
+    - 'lib/prosereflect/input/html.rb'
+    - 'lib/prosereflect/schema/attribute.rb'
+    - 'lib/prosereflect/schema/content_match.rb'
+    - 'lib/prosereflect/schema/mark.rb'
+    - 'spec/fixtures/test_builder/helpers.rb'
 
 # Offense count: 1
 # This cop supports safe autocorrection (--autocorrect).
-# Configuration parameters: AutoCorrect, ContextCreatingMethods, MethodCreatingMethods.
-Lint/UselessAccessModifier:
+# Configuration parameters: AllowUnusedKeywordArguments, IgnoreEmptyMethods, IgnoreNotImplementedMethods, NotImplementedExceptions.
+# NotImplementedExceptions: NotImplementedError
+Lint/UnusedMethodArgument:
   Exclude:
-    - 'e118_amendment.rb'
+    - 'lib/prosereflect/schema/node.rb'
 
-# Offense count: 5
-# Configuration parameters: AllowedMethods, AllowedPatterns, CountRepeatedAttributes.
+# Offense count: 57
+# Configuration parameters: AllowedMethods, AllowedPatterns, CountRepeatedAttributes, Max.
 Metrics/AbcSize:
-  Max: 98
+  Enabled: false
 
-# Offense count: 23
-# Configuration parameters: CountComments, CountAsOne, AllowedMethods, AllowedPatterns.
+# Offense count: 1
+# Configuration parameters: CountComments, CountAsOne, AllowedMethods, AllowedPatterns, inherit_mode.
 # AllowedMethods: refine
 Metrics/BlockLength:
-  Exclude:
-    - 'spec/prosereflect/input/html_spec.rb'
-  Max: 500
+  Max: 27
 
-# Offense count: 3
-Metrics/ClassLength:
-  Exclude:
-    - 'lib/prosereflect/input/html.rb'
-    - 'lib/prosereflect/output/html.rb'
-    - 'lib/prosereflect/node.rb'
+# Offense count: 1
+# Configuration parameters: CountBlocks, CountModifierForms.
+Metrics/BlockNesting:
+  Max: 4
 
-# Offense count: 4
-# Configuration parameters: AllowedMethods, AllowedPatterns.
+# Offense count: 57
+# Configuration parameters: AllowedMethods, AllowedPatterns, Max.
 Metrics/CyclomaticComplexity:
-  Max: 50
+  Enabled: false
 
-# Offense count: 6
+# Offense count: 82
 # Configuration parameters: CountComments, CountAsOne, AllowedMethods, AllowedPatterns.
 Metrics/MethodLength:
-  Max: 90
-
-# Offense count: 3
-# Configuration parameters: AllowedMethods, AllowedPatterns.
-Metrics/PerceivedComplexity:
-  Max: 35
+  Max: 93
 
 # Offense count: 9
-# Configuration parameters: EnforcedStyle, CheckMethodNames, CheckSymbols, AllowedIdentifiers, AllowedPatterns.
-# SupportedStyles: snake_case, normalcase, non_integer
-# AllowedIdentifiers: TLS1_1, TLS1_2, capture3, iso8601, rfc1123_date, rfc822, rfc2822, rfc3339, x86_64
-Naming/VariableNumber:
-  Exclude:
-    - 'e118_entry.rb'
+# Configuration parameters: CountKeywordArgs, MaxOptionalParameters.
+Metrics/ParameterLists:
+  Max: 8
 
-# Offense count: 2
-# This cop supports safe autocorrection (--autocorrect).
-# Configuration parameters: EnforcedStyle, ProceduralMethods, FunctionalMethods, AllowedMethods, AllowedPatterns, AllowBracesOnProceduralOneLiners, BracesRequiredMethods.
-# SupportedStyles: line_count_based, semantic, braces_for_chaining, always_braces
-# ProceduralMethods: benchmark, bm, bmbm, create, each_with_object, measure, new, realtime, tap, with_object
-# FunctionalMethods: let, let!, subject, watch
-# AllowedMethods: lambda, proc, it
-Style/BlockDelimiters:
-  Exclude:
-    - 'bin/extract-ituob-amendments.rb'
+# Offense count: 52
+# Configuration parameters: AllowedMethods, AllowedPatterns, Max.
+Metrics/PerceivedComplexity:
+  Enabled: false
 
-# Offense count: 11
-# Configuration parameters: AllowedConstants.
-Style/Documentation:
-  Exclude:
-    - 'spec/**/*'
-    - 'test/**/*'
-    - 'e118_amendment.rb'
-    - 'e118_entry.rb'
-    - 'lib/prosereflect/document.rb'
-    - 'lib/prosereflect/hard_break.rb'
-    - 'lib/prosereflect/node.rb'
-    - 'lib/prosereflect/paragraph.rb'
-    - 'lib/prosereflect/parser.rb'
-    - 'lib/prosereflect/table.rb'
-    - 'lib/prosereflect/table_cell.rb'
-    - 'lib/prosereflect/table_row.rb'
-    - 'lib/prosereflect/text.rb'
-    - 'lib/prosereflect/heading.rb'
-    - 'lib/prosereflect/attribute.rb'
-    - 'lib/prosereflect/attribute/base.rb'
-    - 'lib/prosereflect/attribute/bold.rb'
-    - 'lib/prosereflect/attribute/href.rb'
-    - 'lib/prosereflect/attribute/id.rb'
-    - 'lib/prosereflect/input/html.rb'
-    - 'lib/prosereflect/output/html.rb'
-    - 'lib/prosereflect/mark.rb'
-    - 'lib/prosereflect/mark/base.rb'
+# Offense count: 7
+# Configuration parameters: MinNameLength, AllowNamesEndingInNumbers, AllowedNames, ForbiddenNames.
+# AllowedNames: as, at, by, cc, db, id, if, in, io, ip, of, on, os, pp, to
+Naming/MethodParameterName:
+  Exclude:
+    - 'lib/prosereflect/schema/content_match.rb'
+    - 'lib/prosereflect/schema/fragment.rb'
+    - 'lib/prosereflect/schema/mark.rb'
+    - 'lib/prosereflect/schema/node.rb'
+
+# Offense count: 8
+# Configuration parameters: Mode, AllowedMethods, AllowedPatterns, AllowBangMethods, WaywardPredicates.
+# AllowedMethods: call
+# WaywardPredicates: infinite?, nonzero?
+Naming/PredicateMethod:
+  Exclude:
+    - 'lib/prosereflect/schema/attribute.rb'
+    - 'lib/prosereflect/schema/content_match.rb'
+    - 'lib/prosereflect/schema/node.rb'
+
+# Offense count: 12
+# Configuration parameters: NamePrefix, ForbiddenPrefixes, AllowedMethods, MethodDefinitionMacros, UseSorbetSigs.
+# NamePrefix: is_, has_, have_, does_
+# ForbiddenPrefixes: is_, has_, have_, does_
+# AllowedMethods: is_a?
+# MethodDefinitionMacros: define_method, define_singleton_method
+Naming/PredicatePrefix:
+  Exclude:
+    - 'lib/prosereflect/schema/mark.rb'
+    - 'lib/prosereflect/schema/mark_type.rb'
+    - 'lib/prosereflect/schema/node.rb'
+    - 'lib/prosereflect/schema/node_type.rb'
 
 # Offense count: 1
-# This cop supports unsafe autocorrection (--autocorrect-all).
-# Configuration parameters: EnforcedStyle.
-# SupportedStyles: always, always_true, never
-Style/FrozenStringLiteralComment:
+# Configuration parameters: MinSize.
+Performance/CollectionLiteralInLoop:
   Exclude:
-    - '**/*.arb'
-    - 'bin/extract-ituob-amendments.rb'
+    - 'lib/prosereflect/input/html.rb'
 
 # Offense count: 7
-# This cop supports safe autocorrection (--autocorrect).
-Style/IfUnlessModifier:
-  Exclude:
-    - 'e118_amendment.rb'
-    - 'e118_entry.rb'
-
-# Offense count: 1
-# This cop supports safe autocorrection (--autocorrect).
-# Configuration parameters: EnforcedStyle, MinBodyLength, AllowConsecutiveConditionals.
-# SupportedStyles: skip_modifier_ifs, always
-Style/Next:
+# Configuration parameters: Prefixes, AllowedPatterns.
+# Prefixes: when, with, without
+RSpec/ContextWording:
   Exclude:
-    - 'e118_amendment.rb'
+    - 'spec/prosereflect/parser_spec.rb'
+    - 'spec/prosereflect/schema/conftest.rb'
+    - 'spec/support/shared_examples.rb'
 
-# Offense count: 9
-# This cop supports unsafe autocorrection (--autocorrect-all).
-# Configuration parameters: EnforcedStyle, AllowedMethods, AllowedPatterns.
-# SupportedStyles: predicate, comparison
-Style/NumericPredicate:
-  Exclude:
-    - 'spec/**/*'
-    - 'e118_amendment.rb'
-    - 'e118_entry.rb'
-    - 'lib/prosereflect/table.rb'
+# Offense count: 254
+# Configuration parameters: CountAsOne.
+RSpec/ExampleLength:
+  Max: 134
 
-# Offense count: 1
-# This cop supports safe autocorrection (--autocorrect).
-Style/ParallelAssignment:
-  Exclude:
-    - 'e118_amendment.rb'
+# Offense count: 158
+RSpec/MultipleExpectations:
+  Max: 8
 
-# Offense count: 1
-# This cop supports safe autocorrection (--autocorrect).
-Style/RedundantSelf:
-  Exclude:
-    - 'e118_amendment.rb'
+# Offense count: 7
+# Configuration parameters: AllowedGroups.
+RSpec/NestedGroups:
+  Max: 4
 
 # Offense count: 1
-# This cop supports safe autocorrection (--autocorrect).
-# Configuration parameters: EnforcedStyle.
-# SupportedStyles: implicit, explicit
-Style/RescueStandardError:
+# Configuration parameters: CustomTransform, IgnoreMethods, IgnoreMetadata, InflectorPath, EnforcedInflector.
+# SupportedInflectors: default, active_support
+RSpec/SpecFilePathFormat:
   Exclude:
-    - 'bin/extract-ituob-amendments.rb'
+    - 'spec/prosereflect/schema/schema_spec.rb'
 
-# Offense count: 4
+# Offense count: 2
 # This cop supports unsafe autocorrection (--autocorrect-all).
-# Configuration parameters: ConvertCodeThatCanStartToReturnNil, AllowedMethods, MaxChainLength.
-# AllowedMethods: present?, blank?, presence, try, try!
-Style/SafeNavigation:
+Style/IdenticalConditionalBranches:
   Exclude:
-    - 'e118_amendment.rb'
+    - 'lib/prosereflect/schema/mark.rb'
 
 # Offense count: 1
-# This cop supports unsafe autocorrection (--autocorrect-all).
-Style/SlicingWithRange:
-  Exclude:
-    - 'lib/prosereflect/table.rb'
-
-# Offense count: 38
-# This cop supports safe autocorrection (--autocorrect).
-# Configuration parameters: EnforcedStyle, ConsistentQuotesInMultiline.
-# SupportedStyles: single_quotes, double_quotes
-Style/StringLiterals:
+# Configuration parameters: EnforcedStyle.
+# SupportedStyles: allow_single_line, disallow
+Style/NumberedParameters:
   Exclude:
-    - 'Gemfile'
-    - 'Rakefile'
-    - 'bin/console'
-    - 'bin/extract-ituob-amendments.rb'
-    - 'lib/prosereflect.rb'
-    - 'lib/prosereflect/version.rb'
-    - 'prosereflect.gemspec'
+    - 'lib/prosereflect/schema/content_match.rb'
 
-# Offense count: 7
-# This cop supports unsafe autocorrection (--autocorrect-all).
-Style/ZeroLengthPredicate:
+# Offense count: 1
+# Configuration parameters: AllowedClasses.
+Style/OneClassPerFile:
   Exclude:
-    - 'e118_amendment.rb'
-    - 'e118_entry.rb'
-
-# Offense count: 6
-# This cop supports safe autocorrection (--autocorrect).
-# Configuration parameters: AllowHeredoc, AllowURI, URISchemes, IgnoreCopDirectives, AllowedPatterns, SplitStrings.
-# URISchemes: http, https
-Layout/LineLength:
-  Max: 153
+    - 'lib/prosereflect/schema.rb'

data/CLAUDE.md

@@ -0,0 +1,78 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Overview
+
+`prosereflect` is a Ruby gem for parsing, manipulating, and traversing ProseMirror rich text editor document trees. It provides a Ruby object model over ProseMirror's JSON/YAML format with HTML import/export capabilities.
+
+## Commands
+
+```bash
+# Install dependencies
+bundle install
+
+# Run tests and linting
+rake
+
+# Run tests only
+rake spec
+
+# Run a specific spec file
+rspec spec/prosereflect/parser_spec.rb
+
+# Run a specific test
+rspec spec/prosereflect/parser_spec.rb:42
+
+# Run linting only
+rake rubocop
+```
+
+## Architecture
+
+### Core Classes
+
+- **Node** (`lib/prosereflect/node.rb`) - Base class for all document elements, extends `Lutaml::Model::Serializable`. All node types inherit `type`, `attrs`, `marks`, and `content` attributes.
+- **Document** (`lib/prosereflect/document.rb`) - Top-level container, extends Node. Provides convenience methods like `tables`, `paragraphs`, `find_first`, `find_all`, `find_children`.
+- **Parser** (`lib/prosereflect/parser.rb`) - Converts ProseMirror JSON/YAML hash structure into Node objects via `parse_document`.
+
+### Node Hierarchy
+
+All node types inherit from Node and define a `PM_TYPE` constant matching ProseMirror's type strings:
+- Block nodes: `Document`, `Paragraph`, `Heading`, `Table`, `TableRow`, `TableCell`, `TableHeader`, `BulletList`, `OrderedList`, `ListItem`, `Blockquote`, `CodeBlockWrapper`, `CodeBlock`, `HorizontalRule`, `Image`, `HardBreak`
+- Text nodes: `Text` with `Mark` collections (Bold, Italic, Code, Link, Strike, Subscript, Superscript, Underline)
+- Special: `User` for @mentions
+
+### HTML Conversion
+
+- **Input::Html** (`lib/prosereflect/input/html.rb`) - Parses HTML strings into Document using Nokogiri
+- **Output::Html** (`lib/prosereflect/output/html.rb`) - Converts Document back to HTML using Nokogiri::HTML::Builder
+
+### Serialization
+
+Uses `lutaml-model` for attribute serialization. The `key_value` block defines how Ruby attributes map to ProseMirror JSON keys. Override `to_h` methods handle special cases for attrs/marks serialization.
+
+### Key Dependencies
+
+- `lutaml-model` (~> 0.8) - Serialization framework
+- `nokogiri` (~> 1.18) - HTML parsing/generation
+
+## Superseding prosemirror-py
+
+This library aims to be a full superset of the Python [prosemirror-py](https://github.com/metanorma/prosemirror-py). See `TODO.py-audit/` for detailed feature gap analysis and implementation plans to achieve complete compliance and schema validation parity.
+
+## Data Model Pattern
+
+```ruby
+class SomeNode < Node
+  PM_TYPE = 'some_node'
+
+  attribute :custom_attr, :string
+
+  key_value do
+    map 'type', to: :type, render_default: true
+    map 'attrs', to: :attrs
+    map 'content', to: :content
+  end
+end
+```