mahjong-render 0.1.0

data/assets/tiles/Ton.svg

@@ -0,0 +1,242 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!-- Created with Inkscape (http://www.inkscape.org/) -->
+
+<svg
+   xmlns:osb="http://www.openswatchbook.org/uri/2009/osb"
+   xmlns:dc="http://purl.org/dc/elements/1.1/"
+   xmlns:cc="http://creativecommons.org/ns#"
+   xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#"
+   xmlns:svg="http://www.w3.org/2000/svg"
+   xmlns="http://www.w3.org/2000/svg"
+   xmlns:sodipodi="http://sodipodi.sourceforge.net/DTD/sodipodi-0.dtd"
+   xmlns:inkscape="http://www.inkscape.org/namespaces/inkscape"
+   width="300"
+   height="400"
+   viewBox="0 0 300 400"
+   id="svg2"
+   version="1.1"
+   inkscape:version="0.91 r13725"
+   sodipodi:docname="Ton.svg"
+   inkscape:export-filename="C:\Users\Fluffy\Documents\Projects\ExtraRiichi\Ton.png"
+   inkscape:export-xdpi="180"
+   inkscape:export-ydpi="180">
+  <defs
+     id="defs4">
+    <inkscape:path-effect
+       effect="skeletal"
+       id="path-effect7963"
+       is_visible="true"
+       pattern="m -90.825902,-314.06958 23.03016,41.38503 13.798268,-41.38503 z"
+       copytype="repeated_stretched"
+       prop_scale="1"
+       scale_y_rel="false"
+       spacing="0"
+       normal_offset="0"
+       tang_offset="0"
+       prop_units="false"
+       vertical_pattern="false"
+       fuse_tolerance="0"
+       pattern-nodetypes="cccc" />
+    <inkscape:path-effect
+       effect="skeletal"
+       id="path-effect7830"
+       is_visible="true"
+       pattern="M -12.828427,33.715729 -17,-11 l 9.0000001,0 z"
+       copytype="repeated_stretched"
+       prop_scale="-1"
+       scale_y_rel="false"
+       spacing="5.1"
+       normal_offset="0"
+       tang_offset="0"
+       prop_units="false"
+       vertical_pattern="false"
+       fuse_tolerance="0"
+       pattern-nodetypes="cccc" />
+    <linearGradient
+       id="linearGradient10055"
+       osb:paint="solid">
+      <stop
+         style="stop-color:#000000;stop-opacity:1;"
+         offset="0"
+         id="stop10057" />
+    </linearGradient>
+    <marker
+       inkscape:stockid="Arrow1Lstart"
+       orient="auto"
+       refY="0"
+       refX="0"
+       id="Arrow1Lstart"
+       style="overflow:visible"
+       inkscape:isstock="true">
+      <path
+         id="path4978"
+         d="M 0,0 5,-5 -12.5,0 5,5 0,0 Z"
+         style="fill:#000000;fill-opacity:1;fill-rule:evenodd;stroke:#ff5c00;stroke-width:1pt;stroke-opacity:1"
+         transform="matrix(0.8,0,0,0.8,10,0)"
+         inkscape:connector-curvature="0" />
+    </marker>
+    <clipPath
+       clipPathUnits="userSpaceOnUse"
+       id="clipPath4243">
+      <circle
+         style="opacity:1;fill:#000000;fill-opacity:0.29670332;fill-rule:nonzero;stroke:#000000;stroke-width:19.13299942;stroke-linecap:butt;stroke-linejoin:round;stroke-miterlimit:4;stroke-dasharray:none;stroke-dashoffset:0;stroke-opacity:1"
+         id="circle4245"
+         cx="-264.65997"
+         cy="-198.20665"
+         r="293.95438" />
+    </clipPath>
+    <clipPath
+       clipPathUnits="userSpaceOnUse"
+       id="clipPath7847">
+      <ellipse
+         style="opacity:1;fill:#822600;fill-opacity:1;fill-rule:nonzero;stroke:none;stroke-width:12;stroke-linecap:round;stroke-linejoin:round;stroke-miterlimit:4;stroke-dasharray:none;stroke-dashoffset:0;stroke-opacity:1"
+         id="ellipse7849"
+         cx="394"
+         cy="552.36218"
+         rx="349.49533"
+         ry="216" />
+    </clipPath>
+    <clipPath
+       clipPathUnits="userSpaceOnUse"
+       id="clipPath4243-1">
+      <circle
+         style="opacity:1;fill:#000000;fill-opacity:0.29670332;fill-rule:nonzero;stroke:#000000;stroke-width:19.13299942;stroke-linecap:butt;stroke-linejoin:round;stroke-miterlimit:4;stroke-dasharray:none;stroke-dashoffset:0;stroke-opacity:1"
+         id="circle4245-4"
+         cx="-264.65997"
+         cy="-198.20665"
+         r="293.95438" />
+    </clipPath>
+    <clipPath
+       clipPathUnits="userSpaceOnUse"
+       id="clipPath7876">
+      <circle
+         style="opacity:1;fill:#000000;fill-opacity:0.29670332;fill-rule:nonzero;stroke:#000000;stroke-width:19.13299942;stroke-linecap:butt;stroke-linejoin:round;stroke-miterlimit:4;stroke-dasharray:none;stroke-dashoffset:0;stroke-opacity:1"
+         id="circle7878"
+         cx="-264.65997"
+         cy="-198.20665"
+         r="293.95438" />
+    </clipPath>
+    <clipPath
+       clipPathUnits="userSpaceOnUse"
+       id="clipPath14693">
+      <rect
+         style="opacity:1;fill:#a53c3c;fill-opacity:1;fill-rule:nonzero;stroke:none;stroke-width:8;stroke-linecap:round;stroke-linejoin:round;stroke-miterlimit:4;stroke-dasharray:none;stroke-dashoffset:0;stroke-opacity:1"
+         id="rect14695"
+         width="131.78395"
+         height="168.82127"
+         x="-332.59583"
+         y="383.49765"
+         rx="1.2551664"
+         ry="3.7514515"
+         transform="matrix(0.99939083,-0.03489951,0.03489951,0.99939083,0,0)" />
+    </clipPath>
+    <clipPath
+       clipPathUnits="userSpaceOnUse"
+       id="clipPath14952">
+      <ellipse
+         style="opacity:1;fill:#a53c3c;fill-opacity:1;fill-rule:nonzero;stroke:none;stroke-width:7;stroke-linecap:round;stroke-linejoin:round;stroke-miterlimit:4;stroke-dasharray:none;stroke-dashoffset:0;stroke-opacity:1"
+         id="ellipse14954"
+         cx="-271.34384"
+         cy="647.25604"
+         rx="69.057365"
+         ry="116.91089"
+         transform="matrix(0.99939083,-0.03489951,0.03489951,0.99939083,0,0)" />
+    </clipPath>
+  </defs>
+  <sodipodi:namedview
+     id="base"
+     pagecolor="#aeffff"
+     bordercolor="#666666"
+     borderopacity="1"
+     inkscape:pageopacity="0"
+     inkscape:pageshadow="2"
+     inkscape:zoom="0.50548197"
+     inkscape:cx="363.15718"
+     inkscape:cy="458.34028"
+     inkscape:document-units="px"
+     inkscape:current-layer="layer1"
+     showgrid="true"
+     inkscape:window-width="1920"
+     inkscape:window-height="1017"
+     inkscape:window-x="1912"
+     inkscape:window-y="-8"
+     inkscape:window-maximized="1"
+     showguides="true"
+     inkscape:guide-bbox="true"
+     units="px">
+    <inkscape:grid
+       type="xygrid"
+       id="grid4774"
+       visible="true"
+       dotted="false"
+       color="#3f3fff"
+       opacity="0.03921569"
+       empcolor="#3f3fff"
+       empopacity="0.07843137"
+       enabled="false" />
+    <sodipodi:guide
+       position="150,200"
+       orientation="0,1"
+       id="guide8231"
+       inkscape:label=""
+       inkscape:color="rgb(0,0,255)" />
+    <sodipodi:guide
+       position="150,200"
+       orientation="1,0"
+       id="guide8233"
+       inkscape:label=""
+       inkscape:color="rgb(0,0,255)" />
+  </sodipodi:namedview>
+  <metadata
+     id="metadata7">
+    <rdf:RDF>
+      <cc:Work
+         rdf:about="">
+        <dc:format>image/svg+xml</dc:format>
+        <dc:type
+           rdf:resource="http://purl.org/dc/dcmitype/StillImage" />
+        <dc:title />
+      </cc:Work>
+    </rdf:RDF>
+  </metadata>
+  <g
+     inkscape:label="Layer 1"
+     inkscape:groupmode="layer"
+     id="layer1"
+     transform="translate(0,-652.36216)">
+    <g
+       id="g4182"
+       transform="matrix(0.90070005,0,0,0.97528977,22.480539,21.079387)">
+      <path
+         sodipodi:nodetypes="ccccccccccccccccccccccc"
+         inkscape:connector-curvature="0"
+         id="path4169"
+         d="M 233.62512,755.29109 C 178.13441,766.77996 64.370638,790.79873 58.640429,785.71129 42.658218,774.8367 25.686157,781.4533 35.789288,796.11051 c 16.240064,27.58037 41.08272,52.95267 53.054176,82.84405 2.288277,4.33456 4.578233,5.00952 6.866511,4.97624 34.894055,0.59778 59.617015,-7.13696 92.959705,-10.00028 5.24648,-0.50585 12.18032,5.19713 16.07777,3.49424 3.45211,-1.88029 4.88869,-8.56661 5.7989,-12.75873 6.85855,-25.41545 28.05224,-47.67676 39.89617,-72.71328 1.50503,-2.99478 9.84505,-3.54971 9.78218,-6.44028 -1.21917,-10.81663 -17.3035,-30.7056 -26.59958,-30.22138 z m -23.13944,33.57895 c 12.46189,-0.30489 -0.39856,25.04533 -5.5016,26.11044 -5.68441,0.83505 -6.59045,-7.30247 -13.55667,-7.44593 -5.23392,0.54881 -4.04327,3.93106 -9.43905,5.54094 -32.92047,6.46479 -57.05235,8.76033 -91.40148,12.13597 -4.332557,0.10941 -15.065211,-17.22193 -9.013958,-18.63046 40.940618,-9.93723 109.784008,-17.44402 128.912758,-17.71096 z m -16.38918,50.02681 c 4.01395,6.86764 -2.84402,13.79985 -7.80917,14.56359 -30.19331,4.51502 -78.25363,12.14709 -82.00667,8.23091 -2.66879,-2.84434 -8.082537,-10.97917 -7.221842,-16.53793 11.136252,-3.71556 92.300252,-14.42426 97.037682,-6.25657 z"
+         style="fill:#142896;fill-opacity:1;fill-rule:evenodd;stroke:none;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1" />
+      <path
+         sodipodi:nodetypes="ccccccccccscccc"
+         inkscape:connector-curvature="0"
+         id="path4165"
+         d="m 123.10112,656.13043 c -18.37065,-7.40086 -20.37189,5.83216 -17.90295,14.33847 6.2135,20.20143 14.42853,28.63207 24.53852,42.67785 1.80515,2.41778 3.80884,7.05879 3.50496,9.27068 l -2.80317,207.5969 c 0.0245,6.49844 -1.22391,27.05521 -5.33713,23.81363 -16.25707,-12.35739 -21.17086,-19.29273 -47.244611,-51.54601 -11.141011,-14.92882 -19.888636,-6.9441 -6.365572,12.59128 42.459393,54.62391 46.079123,59.83408 46.706613,115.10687 1.6238,29.1788 31.75855,24.6486 34.5721,6.1383 3.42954,-19.9718 -1.64734,-51.78318 -1.84988,-73.7618 -0.77433,-84.02764 -0.85925,-158.3381 12.84541,-239.53344 2.59385,-12.6668 22.99001,-23.06614 33.97476,-26.71095 4.86607,-1.61964 10.28698,-13.97417 0.90028,-14.45229 -25.17978,-2.64878 -52.28301,-15.55116 -75.53933,-25.52949 z"
+         style="fill:#142896;fill-opacity:1;fill-rule:evenodd;stroke:none;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1" />
+      <path
+         sodipodi:nodetypes="cccccc"
+         inkscape:connector-curvature="0"
+         id="path4167"
+         d="m 90.058998,749.95518 c -28.498411,-1.30744 -7.40777,15.78722 -1.003352,15.35489 35.469434,-3.22236 93.934624,-11.66451 130.102704,-19.88981 2.50231,-0.0783 -0.19108,-17.18993 -17.33839,-18.91906 -5.21285,-0.25484 -4.31683,2.60115 -10.47943,4.83506 -27.63258,6.00227 -76.15552,20.22066 -101.281532,18.61892 z"
+         style="fill:#142896;fill-opacity:1;fill-rule:evenodd;stroke:none;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1" />
+      <path
+         sodipodi:nodetypes="ccccc"
+         inkscape:connector-curvature="0"
+         id="path4178"
+         d="M 101.07932,860.47476 C 81.038575,899.28326 62.611644,913.1005 1.9825743,939.28575 -21.477214,948.67859 -19.805065,962.93934 8.6272375,953.18208 85.796234,923.19531 101.97857,904.47533 114.56321,868.12926 Z"
+         style="fill:#142896;fill-opacity:1;fill-rule:evenodd;stroke:none;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1" />
+      <path
+         sodipodi:nodetypes="ccccccc"
+         inkscape:connector-curvature="0"
+         id="path4180"
+         d="m 148.90381,861.23655 c 24.81185,28.93873 58.74403,106.95253 77.55965,95.36697 14.85312,-9.54021 33.94987,-10.66782 42.06647,-8.48169 10.62302,2.79871 11.13375,7.75465 17.07981,10.96967 15.63489,6.5882 12.36449,-2.02074 6.9373,-9.59456 -14.04344,-21.5996 -80.57109,-34.66827 -122.31035,-92.57081 z"
+         style="fill:#142896;fill-opacity:1;fill-rule:evenodd;stroke:none;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1" />
+    </g>
+  </g>
+</svg>

data/docs/adr/0001-renderer-selection.md

@@ -0,0 +1,7 @@
+# ADR 0001: Renderer selection
+
+Status: accepted for v0.1.0.
+
+The core must run with Ruby alone. The [ecosystem review](../research/existing-renderers.md) found capable JavaScript and TeX renderers, but using either at runtime would add another language or a TeX installation. The Ruby Jekyll plugin is coupled to Liquid and separate image files, and its regex parser does not enforce valid input.
+
+Reuse [FluffyStuff's CC0 tile artwork](https://github.com/FluffyStuff/riichi-mahjong-tiles), pinned by commit and checksums. Implement only the missing strict compact-notation parser and a Ruby SVG compositor. Keep Asciidoctor in an optional adapter. Do not copy code from the rejected renderers.

data/docs/adr/0002-license.md

@@ -0,0 +1,5 @@
+# ADR 0002: License
+
+Status: accepted for v0.1.0.
+
+Use Apache-2.0 (`SPDX-License-Identifier: Apache-2.0`) for project code and documentation, attributed to Maejima Kenya. The bundled tile SVGs and `examples/hand.png`, which is generated from those SVGs, remain independently CC0-1.0. Gem metadata lists both identifiers; `THIRD_PARTY_NOTICES.md` explains which files each covers because a license list alone cannot express component boundaries. Preserve the upstream declaration, full CC0 legal text, attribution, source revision, and file hashes. Keep optional and development dependency licenses separate from bundled content. CI fails when the Apache license copy changes or a locked dependency has no approved license metadata.

data/docs/adr/0003-notation.md

@@ -0,0 +1,5 @@
+# ADR 0003: Compact notation
+
+Status: accepted for v0.1.0.
+
+Use established MPSZ grouping: each digit before `m`, `p`, `s`, or `z` is one tile. `0` is a red five in suited groups; honors accept only `1` through `7`. `405m` means `4m 0m 5m`, and `10m` means `1m 0m`. The original request's `10m` invalid example conflicts with this rule and is corrected here. Reject malformed input without skipping characters, and report token, zero-based character position, and reason. Hand legality and tile-count checks are outside this rendering library.

data/docs/adr/0004-assets.md

@@ -0,0 +1,5 @@
+# ADR 0004: Asset strategy
+
+Status: accepted for v0.1.0.
+
+Bundle the 37 normal and red-five SVG faces plus the tile-front SVG from the pinned CC0 source. Layer the front below each face. Each rendered SVG embeds the needed asset bytes as `data:image/svg+xml;base64` image references. This keeps repeated SVGs deterministic and independent of external files, network requests, document-wide IDs, and installed fonts. The tradeoff is a larger output for hands containing repeated tiles; v0.1 prioritizes offline portability. CI verifies source hashes, XML structure, and absence of active or external SVG content.

data/docs/adr/0005-package.md

@@ -0,0 +1,5 @@
+# ADR 0005: Package strategy
+
+Status: accepted for v0.1.0.
+
+Distribute one Ruby gem named `mahjong-render`. `require "mahjong_render"` exposes the renderer without loading Asciidoctor. `require "mahjong_render/asciidoctor"` registers the HTML5 block macro when the separate `asciidoctor` gem is installed. This meets Ruby-only operation without splitting the small project into several packages. GitHub and RubyGems publication are separate follow-up actions after the local package, documentation, examples, CI, and license checks pass.

data/docs/release.md

@@ -0,0 +1,32 @@
+# Release process
+
+1. Confirm `CHANGELOG.md` and `lib/mahjong_render/version.rb` use the intended SemVer version. Recheck that `mahjong-render` is available on RubyGems; a prior missing-name response does not reserve it.
+2. In the devcontainer, run `bundle exec rake lint test assets:check licenses:check example:build`, `gem build mahjong-render.gemspec`, and `ruby script/check_package.rb mahjong-render-0.1.0.gem`. Confirm the build has no warnings.
+3. Install the built gem locally and reproduce the Ruby and AsciiDoc commands in both READMEs without network access. Inspect the gem contents and confirm the Apache-2.0 license, CC0 legal text, artwork, notices, preview image, examples, and linked documentation are present.
+4. For the first release, create the public `kjun1/mahjong-render` GitHub repository. Confirm the homepage and gem metadata URLs resolve, verify CI on the default branch, and enable GitHub private vulnerability reporting.
+5. Review and date the 0.1.0 changelog entry. Configure Trusted Publishing as described below, then choose one of the release triggers.
+6. After publication, confirm the RubyGems version and ownership, install the gem from RubyGems, and check that the pending publisher became a trusted publisher.
+
+## Trusted Publishing setup
+
+1. In the GitHub repository, create an environment named `release` under **Settings → Environments**. If deployment branch and tag restrictions are enabled, allow the `main` branch and `v*` tags.
+2. Enable MFA for the RubyGems account. The gemspec sets `rubygems_mfa_required` to `true`.
+3. Sign in to RubyGems and open [Pending trusted publishers](https://rubygems.org/profile/oidc/pending_trusted_publishers). Create a pending publisher with these exact values:
+
+   | Field | Value |
+   | --- | --- |
+   | Gem name | `mahjong-render` |
+   | Repository owner | `kjun1` |
+   | Repository name | `mahjong-render` |
+   | Workflow filename | `release.yml` |
+   | Environment | `release` |
+   | Workflow repository owner/name | Leave blank |
+
+   No RubyGems API key or GitHub secret is needed. RubyGems converts the pending publisher after the first successful push.
+
+## Choose a release trigger
+
+- **Manual event:** Open GitHub **Actions → Publish gem → Run workflow**, select the `main` branch, and enter version `0.1.0`. The workflow publishes the version in `main` without creating a Git tag.
+- **Tag push:** Push a tag matching the gem version, for example `git tag v0.1.0` followed by `git push origin v0.1.0`. The tag push publishes that version automatically.
+
+Both routes validate the version, run the release checks, build the gem, and use the `release` environment. If a version from this repository is already on RubyGems, a later run checks its source metadata and skips the duplicate push. The RubyGems version cannot be overwritten; bump the gem version for any subsequent release.

data/docs/research/existing-renderers.md

@@ -0,0 +1,21 @@
+# Existing ecosystem review
+
+Reviewed for v0.1.0 on 2026-09-24. `yes/no/unclear` describes documented capability, not a promise of API compatibility. Maintenance is based on upstream activity visible at review time. Browser and Node columns concern direct use without a translation layer.
+
+| Project / repository | Language | Code / asset license | Notation / parser | SVG / red five / meld | Browser / Node | Maintenance | Reusable / integration cost / decision |
+| --- | --- | --- | --- | --- | --- | --- | --- |
+| [mahjong-font](https://github.com/rutopio/mahjong-font) | TypeScript | MIT / SIL OFL 1.1 font | tile strings; parser tied to application | yes / yes / unclear | yes / unclear | active in 2026 | Font is reusable in principle; hosted image API violates offline runtime, application is not a Ruby gem. Do not depend on it. |
+| [mjimage](https://github.com/konoui/mjimage) | TypeScript | MIT / tile-image provenance not established in repository docs | compact notation; parser yes | yes / yes / yes | yes / yes | active in 2026 | npm package exists, but requires a JS runtime and separately hosted tile images by default. High integration cost for Ruby-only operation; do not depend on it. |
+| [mahjong-tiles](https://github.com/DrCMWither/mahjong-tiles) | LaTeX3 | MIT / CC0 art stated upstream | extended MPSZF; parser internal | PDF asset composition, not direct SVG / yes / yes | no / no | active in 2026 | Requires TeX and PDF assets. Good notation reference; not a suitable runtime renderer. |
+| [mahjong-tex](https://github.com/Schmytzi/mahjong-tex) | LaTeX3 | MIT / README credits CC BY art | MPSZ; parser internal | PDF asset composition, not direct SVG / yes / yes | no / no | maintenance unclear | Requires TeX and cannot provide a small Ruby-only SVG path. Do not depend on it. |
+| [tilekit](https://github.com/csimi/tilekit) | JavaScript | ISC / Arphic Public License glyph data | compact notation; parser yes | yes / yes / no | yes / yes | 2026 release, short history | Small direct SVG library, but Ruby-only runtime excludes it; transitive glyph-data terms would need separate attribution. Do not depend on it. |
+| [jekyll-mahjong](https://github.com/peter1357908/jekyll-mahjong) | Ruby | MIT / Uzaku font-derived art credited; asset terms need separate review | compact notation; regex in Liquid tag | individual SVG files in HTML / unclear / sideways tile | no / no | last repository activity in 2023 | Ruby-native, but coupled to Jekyll/Liquid, external CSS and separate image files. Regex skips invalid text. Do not adapt it for the public renderer. |
+| [riichi-mahjong-tiles](https://github.com/FluffyStuff/riichi-mahjong-tiles) | SVG assets | CC0-1.0 | not applicable | yes / yes / not applicable | yes / yes | stable art; last pinned revision 2024 | Reuse 37 tile faces and the tile front. Low integration cost and clear redistribution terms. |
+
+## AsciiDoc integration
+
+[Ruby Asciidoctor's block macro extension](https://docs.asciidoctor.org/asciidoctor/latest/extensions/block-macro-processor/) already handles macro syntax and registration. The adapter uses that API and delegates only tile rendering to `MahjongRender.render`. No custom AsciiDoc parser is needed.
+
+## Decision summary
+
+The public runtime must work with Ruby alone. Reusing the CC0 tile vectors avoids recreating artwork. A small parser is needed because the available Ruby/Jekyll candidate silently skips invalid notation, while the JS and TeX parsers cannot be used without extra runtimes. The SVG composer only places those tile vectors into one offline image. See the [ADR](../adr/0001-renderer-selection.md).

data/examples/basic.adoc

@@ -0,0 +1,13 @@
+= Mahjong Render Example
+
+== Basic hand
+
+mahjong::123m456p789s12344z[]
+
+== Red five
+
+mahjong::405m456p789s12344z[]
+
+== Groups with extra space
+
+mahjong::123m|456p|(0.5)789s[]

data/lib/mahjong_render/asciidoctor.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+# Copyright 2026 Maejima Kenya
+# SPDX-License-Identifier: Apache-2.0
+
+require "asciidoctor"
+require "asciidoctor/extensions"
+require_relative "../mahjong_render"
+
+module MahjongRender
+  class UnsupportedBackendError < StandardError; end
+  class UnsupportedAttributeError < StandardError; end
+
+  module Asciidoctor
+    class BlockMacro < ::Asciidoctor::Extensions::BlockMacroProcessor
+      use_dsl
+      named :mahjong
+
+      def process(parent, target, attrs)
+        raise UnsupportedBackendError, "mahjong block macro supports HTML output only" unless parent.document.basebackend?("html")
+        raise UnsupportedAttributeError, "mahjong block macro does not support attributes: #{attrs.keys.join(', ')}" unless attrs.empty?
+
+        svg = MahjongRender.render(target)
+        create_pass_block(parent, %(<div class="mahjong-render">#{svg}</div>), {}, subs: nil)
+      end
+    end
+  end
+end
+
+Asciidoctor::Extensions.register do
+  block_macro MahjongRender::Asciidoctor::BlockMacro
+end

data/lib/mahjong_render/parser.rb

@@ -0,0 +1,113 @@
+# frozen_string_literal: true
+
+# Copyright 2026 Maejima Kenya
+# SPDX-License-Identifier: Apache-2.0
+
+module MahjongRender
+  class NotationError < StandardError
+    attr_reader :token, :position, :reason
+
+    def initialize(token:, position:, reason:)
+      @token = token
+      @position = position
+      @reason = reason
+      super("#{reason} at character #{position}: #{token.inspect}")
+    end
+  end
+
+  module Parser
+    SUITS = %w[m p s z].freeze
+    MULTIPLIER = /\A[0-9]+(?:\.[0-9]+)?\z/
+    DEFAULT_GAP_MULTIPLIER = Rational(1, 4)
+    Layout = Struct.new(:tiles, :gaps, keyword_init: true)
+
+    module_function
+
+    def parse(notation)
+      parse_layout(notation).tiles
+    end
+
+    def parse_layout(notation)
+      raise TypeError, "notation must be a String" unless notation.is_a?(String)
+
+      layout = Layout.new(tiles: [], gaps: [])
+      digits = +""
+      start = nil
+      pending_gap = nil
+      separator_position = nil
+      chars = notation.chars
+      position = 0
+
+      while position < chars.length
+        char = chars[position]
+        if char.match?(/[0-9]/)
+          start ||= position
+          digits << char
+        elsif SUITS.include?(char)
+          error(char, position, "suit needs at least one digit") if digits.empty?
+          append_tiles(layout, digits, char, start, pending_gap)
+          pending_gap = nil
+          digits.clear
+          start = nil
+        elsif char.match?(/\s/)
+          error(digits, start, "missing suit before whitespace") unless digits.empty?
+        elsif char == "|"
+          validate_separator(layout.tiles, digits, start, pending_gap, position)
+          separator_position = position
+          pending_gap, position = parse_gap(chars, position)
+        else
+          error(char, position, "unknown notation character")
+        end
+        position += 1
+      end
+
+      error(digits, start, "missing suit") unless digits.empty?
+      error("|", separator_position, "separator needs a following group") unless pending_gap.nil?
+      error("", 0, "notation is empty") if layout.tiles.empty?
+      freeze_layout(layout)
+    end
+
+    def append_tiles(layout, digits, suit, start, gap)
+      digits.each_char.with_index do |digit, offset|
+        error("#{digit}z", start + offset, "honor rank must be 1–7") if suit == "z" && !digit.match?(/[1-7]/)
+        layout.gaps << (gap || 0) unless layout.tiles.empty?
+        layout.tiles << "#{digit}#{suit}"
+        gap = nil
+      end
+    end
+    private_class_method :append_tiles
+
+    def freeze_layout(layout)
+      layout.tiles.freeze
+      layout.gaps.freeze
+      layout.freeze
+    end
+    private_class_method :freeze_layout
+
+    def validate_separator(tiles, digits, start, pending_gap, position)
+      error(digits, start, "missing suit before separator") unless digits.empty?
+      error("|", position, "separator needs a preceding group") if tiles.empty?
+      error("|", position, "consecutive separators") unless pending_gap.nil?
+    end
+    private_class_method :validate_separator
+
+    def parse_gap(chars, position)
+      return [DEFAULT_GAP_MULTIPLIER, position] unless chars[position + 1] == "("
+
+      closing = position + 2
+      closing += 1 while closing < chars.length && chars[closing] != ")"
+      error("|(", position, "missing closing parenthesis for gap multiplier") if closing == chars.length
+
+      token = chars[(position + 2)...closing].join
+      error("|(#{token})", position, "invalid gap multiplier") unless MULTIPLIER.match?(token)
+
+      [Rational(token), closing]
+    end
+    private_class_method :parse_gap
+
+    def error(token, position, reason)
+      raise NotationError.new(token: token.dup, position: position, reason: reason)
+    end
+    private_class_method :error
+  end
+end

data/lib/mahjong_render/renderer.rb

@@ -0,0 +1,105 @@
+# frozen_string_literal: true
+
+# Copyright 2026 Maejima Kenya
+# SPDX-License-Identifier: Apache-2.0
+
+module MahjongRender
+  module Renderer
+    TILE_WIDTH = 300
+    TILE_HEIGHT = 400
+    GAP = 12
+    ASSET_DIRECTORY = File.expand_path("../../assets/tiles", __dir__)
+    XML_ESCAPE = { "&" => "&amp;", '"' => "&quot;", "<" => "&lt;", ">" => "&gt;" }.freeze
+    SUIT_NAMES = { "m" => "characters", "p" => "circles", "s" => "bamboo" }.freeze
+    ASSET_SUITS = { "m" => "Man", "p" => "Pin", "s" => "Sou" }.freeze
+    HONORS = {
+      "1" => ["Ton.svg", "east wind"],
+      "2" => ["Nan.svg", "south wind"],
+      "3" => ["Shaa.svg", "west wind"],
+      "4" => ["Pei.svg", "north wind"],
+      "5" => ["Haku.svg", "white dragon"],
+      "6" => ["Hatsu.svg", "green dragon"],
+      "7" => ["Chun.svg", "red dragon"]
+    }.freeze
+
+    module_function
+
+    def render(layout)
+      tiles = layout.tiles
+      width = (tiles.length * TILE_WIDTH) + ((tiles.length - 1) * GAP) + layout.gaps.sum { |gap| gap * TILE_WIDTH }
+      %(<svg #{svg_attributes(tiles, width)}>#{image_elements(layout).join}</svg>)
+    end
+
+    def svg_attributes(tiles, width)
+      label = "Mahjong tiles: #{tiles.map { |tile| tile_label(tile) }.join(', ')}".gsub(/[&"<>]/, XML_ESCAPE)
+      %(xmlns="http://www.w3.org/2000/svg" width="#{svg_number(width)}" height="#{TILE_HEIGHT}" ) +
+        %(viewBox="0 0 #{svg_number(width)} #{TILE_HEIGHT}" role="img" aria-label="#{label}" style="max-width:100%;height:auto")
+    end
+    private_class_method :svg_attributes
+
+    def image_elements(layout)
+      uris = {}
+      front = encode_asset("Front.svg")
+      layout.tiles.zip(tile_positions(layout.gaps)).map do |tile, x|
+        uri = uris[tile] ||= data_uri(tile)
+        image_element(x, front) + image_element(x, uri)
+      end
+    end
+    private_class_method :image_elements
+
+    def tile_positions(gaps)
+      positions = [0]
+      gaps.each { |gap| positions << (positions.last + TILE_WIDTH + GAP + (gap * TILE_WIDTH)) }
+      positions
+    end
+    private_class_method :tile_positions
+
+    def image_element(left, uri)
+      %(<image x="#{svg_number(left)}" y="0" width="#{TILE_WIDTH}" height="#{TILE_HEIGHT}" href="#{uri}" />)
+    end
+    private_class_method :image_element
+
+    def svg_number(value)
+      return value.numerator.to_s if value.denominator == 1
+
+      whole, remainder = value.numerator.divmod(value.denominator)
+      fraction = +""
+      until remainder.zero?
+        digit, remainder = (remainder * 10).divmod(value.denominator)
+        fraction << digit.to_s
+      end
+      "#{whole}.#{fraction}"
+    end
+    private_class_method :svg_number
+
+    def tile_label(tile)
+      rank = tile[0]
+      suit = tile[1]
+      return HONORS.fetch(rank).last if suit == "z"
+      return "red 5 of #{SUIT_NAMES.fetch(suit)}" if rank == "0"
+
+      "#{rank} of #{SUIT_NAMES.fetch(suit)}"
+    end
+    private_class_method :tile_label
+
+    def data_uri(tile)
+      rank = tile[0]
+      suit = tile[1]
+      filename = if suit == "z"
+                   HONORS.fetch(rank).first
+                 elsif rank == "0"
+                   "#{ASSET_SUITS.fetch(suit)}5-Dora.svg"
+                 else
+                   "#{ASSET_SUITS.fetch(suit)}#{rank}.svg"
+                 end
+      encode_asset(filename)
+    end
+    private_class_method :data_uri
+
+    def encode_asset(filename)
+      bytes = File.binread(File.join(ASSET_DIRECTORY, filename))
+      "data:image/svg+xml;base64,#{[bytes].pack('m0')}"
+    end
+    private_class_method :encode_asset
+  end
+end

data/lib/mahjong_render/version.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+# Copyright 2026 Maejima Kenya
+# SPDX-License-Identifier: Apache-2.0
+
+module MahjongRender
+  VERSION = "0.1.0"
+end

data/lib/mahjong_render.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+# Copyright 2026 Maejima Kenya
+# SPDX-License-Identifier: Apache-2.0
+
+require_relative "mahjong_render/version"
+require_relative "mahjong_render/parser"
+require_relative "mahjong_render/renderer"
+
+module MahjongRender
+  def self.render(notation)
+    Renderer.render(Parser.parse_layout(notation))
+  end
+end