sfml3-rb 0.0.1 → 0.2.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 7a02547990eb0f6906513fabe688b9bcb43ba17aaa510f5732a3f441ca7ad3b0
-  data.tar.gz: 964b816e089af1e0ba5cfb23c8cbafd71cc3f1260aef6247174d7f7247accba8
+  metadata.gz: cc41a984a71094455d29e95d4c529a1e228e5c5442333aca6eb57b9b7c9d3f5e
+  data.tar.gz: 835286043ece71ba5dc8c1790cdd6ab0370ae0924823771e03a811cd8acba1af
 SHA512:
-  metadata.gz: 215e64381b46f7b7ab21ad2d8ec7bec060b983d544253063f160d0b293ca17455a54f32b9f01a9167affe0b31426fa7e43c7bc00688be6c0b64630b702c97e54
-  data.tar.gz: 0db0e2855768aeb46f2bccaded19fdc5534aac48e181aa70e34d5dcb84bf3592278f9fa1c07859ff6d42edd312cc5b5ed1173dbe3e4e213f9fb053ca902115f9
+  metadata.gz: f75f7ce8244a36a0a8e93903ea0d323513753cfdf3e82f79364b3081a3d5ac651609897a0d4911c2509aac1e5107c37ab9ea9341eede85bb630a05228273ed3d
+  data.tar.gz: 68a989c7d4e1147cd5585bf8db85be15c3c1419bbefaeca95791fa37575900d8b841d1b33dd5009f9611e3b5a365b7410c7687ca8eecf96d188a05feb6de269f

data/CHANGELOG.md

@@ -0,0 +1,342 @@
+# Changelog
+
+All notable changes to this project are documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+### Added
+* **Full YARD API documentation and RBS type signatures**, covering every
+  bound class, module, method and constant. Doc comments live in-place in
+  the `ext/**/*.c` sources (YARD's C parser, the same convention RDoc uses),
+  so they're published automatically to
+  [rubydoc.info](https://rubydoc.info/gems/sfml3-rb) on release; `rake yard`
+  builds them locally into `doc/`. `sig/**/*.rbs` ships in the gem alongside
+  the extension sources, for IDE completion (Solargraph, RubyMine) and
+  static type-checking (Sorbet, Steep). Run `rake rbs` to validate the
+  signatures.
+
+## [0.2.2]
+
+### Fixed
+* **The macOS binary gems now build.** SFML 3.0.2 defaults
+  `CMAKE_OSX_DEPLOYMENT_TARGET` to 13.0, but the osxcross SDK in the
+  rake-compiler-dock image is 11.1 and rejects a newer target, so both Darwin
+  builds aborted while configuring SFML. The ports toolchain now pins the
+  deployment target to macOS 11.0, which is the floor Apple Silicon requires
+  anyway.
+
+## [0.2.1]
+
+### Added
+* **`SFML::Transform` is now a class**, wrapping `sfTransform` by value. It previously exposed
+  only `combine` and `inverse` as module functions over plain 9-element Arrays, leaving 11 of
+  CSFML's 13 transform functions unbound: you could read a matrix out of a `Sprite` but not build
+  one, apply one to a point, or compose one. It now has `Transform.identity` / `IDENTITY`,
+  `Transform.from_a`, `#to_a`/`#matrix`, `#gl_matrix`, `#==`, `#translate!`, `#rotate!`,
+  `#scale!` (the last two taking an optional centre), non-mutating `#translate`/`#rotate`/
+  `#scale`, `#transform_point`, `#transform_rect`, `#combine!`, `#*`, `#inverse` and `#copy`.
+* **`map_pixel_to_coords` and `map_coords_to_pixel` on both render targets.** The screen-to-world
+  conversion behind every click-to-select interaction; without it a zoomed, rotated or
+  viewport-shifted `View` could not be hit-tested from Ruby at all.
+* **`SFML::Window` gained the render-target methods only `RenderTexture` had**: `clear_stencil`,
+  `clear_color_and_stencil`, `viewport`, `scissor` and `srgb?`. Both classes also gained
+  `push_gl_states`, `pop_gl_states`, `reset_gl_states`, `draw_primitives` and
+  `draw_vertex_buffer_range`. The shared surface is generated once from
+  `ext/graphics/render_target.inc`, the same way `ext/audio/sound_source.inc` already serves the
+  three sound sources.
+* `SFML::View.from_rect`, `View#scissor` and `View#scissor=`.
+* `SFML::Transformable#inverse_transform` and `#copy` — every subclass (`Sprite`, `Text`,
+  `Circle`, `RectangleShape`, `ConvexShape`, `Shape`) already had both.
+* `SFML::Texture.srgb`, `.srgb_from_stream`, `.srgb_from_image`, `Texture#resize_srgb` and
+  `Texture#swap`.
+* `SFML::Shader#set_vec4_array`, `#set_mat3_array` and `#set_mat4_array`, completing the array
+  uniforms alongside the existing float/vec2/vec3 forms.
+* `SFML::Circle#point_count=`, `SFML::VertexBuffer#swap`, `SFML::Window.from_handle` and
+  `SFML::Window#create_vulkan_surface`.
+
+### Fixed
+* **Non-ASCII text and window titles were mangled.** `Text#string=`, `Window#title=`, window
+  creation and `FtpDirectoryResponse#directory` passed UTF-8 bytes to CSFML's `const char*`
+  entry points, which hand them to `sf::String`'s narrow-character constructor and decode them
+  with the C locale: `"héllo"` came back as `U+0068 U+FFFFFFFF U+FFFFFFFF U+006C U+006C U+006F`.
+  All four now go through the UTF-32 entry points and round-trip exactly, including astral-plane
+  characters. The converters live in `ext/core/unicode.c`.
+* **`Mouse.position`, `Mouse.position=` and `Touch.position` reinterpret-cast `sfRenderWindow*`
+  to `sfWindowBase*`**, relying on the base being at offset 0 — true of CSFML 3.0.0's layout but
+  not guaranteed by it. They now call `sfMouse_getPositionRenderWindow`,
+  `sfMouse_setPositionRenderWindow` and `sfTouch_getPositionRenderWindow`, which CSFML ships for
+  exactly this reason. Ruby-visible behaviour is unchanged.
+* `Shader#set_float_array`, `#set_vec2_array` and `#set_vec3_array` leaked their conversion
+  buffer if an element raised part-way through. All six array setters are now generated from one
+  macro built on `ALLOCV_N`, whose buffer Ruby frees while unwinding.
+* `VertexBuffer#update` had the same leak; it now shares `vertices_from_rb`, which validates
+  every element before allocating anything.
+* **Audio-thread callbacks re-entered the VM from a foreign native thread.** The
+  `SoundStream#on_get_data` / `#on_seek` callbacks and the effect processor run on SFML's audio
+  thread, which Ruby never created; calling back into Ruby from it (`rb_thread_call_with_gvl`) is
+  a fatal VM error. Each now hands off to one shared Ruby-owned worker
+  (`ext/core/foreign_thread.c`). `SoundSource#stop`, `Sound#buffer=` and the `Sound` / `Music` /
+  `SoundStream` destructors release the GVL while they wait on the audio thread, and a processor
+  that times out degrades to a full buffer of silence rather than stalling playback.
+
+### Changed
+* `Window` is created through `sfRenderWindow_createUnicode` rather than `sfRenderWindow_create`,
+  so a title given at construction is subject to the same UTF-8 fix as `#title=`.
+* `RenderTexture#viewport` and `#scissor` now take the view as an *optional* argument; omitting
+  it means the target's current view, matching CSFML's `NULL`.
+
+## [0.2.0]
+
+### Added
+* **Full Audio binding.** `SFML::Listener`, `SFML::SoundSourceCone`, `SFML::SoundBuffer`,
+  `SFML::Sound`, `SFML::Music`, `SFML::SoundStream`, `SFML::SoundRecorder` and
+  `SFML::SoundBufferRecorder`, plus the `SFML::SoundStatus` and `SFML::SoundChannel` enums. The
+  shared sound-source surface (play/pause/stop/status, pitch, pan, volume, spatialization,
+  position/direction/velocity, cone, doppler and attenuation factors, distance/gain bounds and
+  playing offset) is generated once from `ext/audio/sound_source.inc` for all three source classes.
+  `SoundStream` and `SoundRecorder` are subclassable through `#on_get_data`/`#on_seek` and
+  `#on_process`/`#on_start`/`#on_stop`; their callbacks re-enter Ruby under the GVL and treat an
+  exception as "stop", since they run on SFML's audio thread.
+* **Full Network binding.** `SFML::IpAddress` (string/bytes/integer constructors, `NONE`, `ANY`,
+  `LOCAL_HOST`, `BROADCAST`, local/public lookup), `SFML::Packet` (raw data plus every typed
+  reader/writer), `SFML::SocketSelector`, `SFML::TcpSocket`, `SFML::TcpListener`,
+  `SFML::UdpSocket`, `SFML::Http`/`HttpRequest`/`HttpResponse`, `SFML::Ftp` with its response,
+  directory-response and listing-response classes, and the `SocketStatus`, `HttpMethod`,
+  `HttpStatus`, `FtpStatus` and `FtpTransferMode` enums.
+* `SFML::SoundSource#effect_processor=` accepts a Ruby proc. Because `sfEffectProcessor` carries
+  no `userData` (so one C callback cannot tell which source invoked it), the binding dispatches
+  through a bounded pool of C thunks, one per active source; exceeding the pool raises.
+
+### Changed
+* The vendored CSFML/SFML archives are now linked by **full path** instead of `-l`. mkmf puts the
+  host's `-L/usr/lib64` ahead of the ports prefix, which made `-lfreetype` (and the new codec
+  libraries) resolve to the host's shared objects and silently add runtime dependencies. The
+  built extension again has no `libsfml`/`libcsfml`/`libfreetype`/`libvorbis`/`libFLAC`/`libogg`
+  shared dependency.
+
+### Build
+* `ext/ports.rb` now builds **Ogg 1.3.5, Vorbis 1.3.7 and FLAC 1.4.3** as pinned,
+  checksum-verified, static and position-independent ports, alongside FreeType. SFML 3's audio
+  backend is miniaudio, so OpenAL is not needed.
+* `SFML_BUILD_AUDIO`, `SFML_BUILD_NETWORK`, `CSFML_BUILD_AUDIO` and `CSFML_BUILD_NETWORK` are
+  enabled; `ws2_32` was added to the Windows system libraries and the CoreAudio/CoreFoundation
+  frameworks to the macOS ones. `CMakeLists.txt` finds and links the `Audio`/`Network` components.
+* Archive extraction accepts `.tar.xz` as well as `.tar.gz`, since the FLAC release ships only as
+  xz.
+
+### Known issues
+* Audio playback and capture need an audio device; the CI suite stays headless, so
+  `SoundStream#on_get_data` and `SoundRecorder` are exercised by construction and mapping only,
+  never by actually playing or capturing.
+* `Http` and `Ftp` perform real network I/O and are not exercised in CI beyond construction and
+  enum mapping.
+
+## [0.1.1]
+
+### Added
+* **Full Graphics binding.** `RectangleShape`, `ConvexShape`, a callback-based custom `Shape`, `Sprite`,
+  `Texture`, `Image`, `Font`, `Text`, `RenderTexture`, `Shader`, `Vertex`, `VertexArray`,
+  `VertexBuffer`, `Glyph`, and the value types `BlendMode`, `StencilMode`. `Circle` gained the
+  outline/texture/bounds surface it was missing.
+* **Full Window/input binding.** `Keyboard` real-time queries (`pressed?`, `scancode_pressed?`,
+  `localize`, `delocalize`, `description`), and the `Mouse`, `Joystick`, `Touch`, `Sensor`,
+  `Clipboard`, `Cursor`, `Context`, `ContextSettings` and `Vulkan` modules/classes. `Event` now
+  exposes every payload (text, mouse move/raw/button/wheel, joystick move/button/connect, touch,
+  sensor).
+* **System completeness.** `SFML::Time` (arithmetic, comparison, unit conversions), `SFML.sleep`,
+  `SFML::Buffer`, and `SFML::InputStream` (wraps any `#read`-able object so `Font`/`Texture`/`Image`/
+  `Shader` can load from streams).
+* **Value classes.** `Vector2`, `Vector3`, `Color`, `Rect` are now real Ruby classes; every setter
+  still accepts a plain array, and getters return the class (which behaves like an array via
+  `to_ary`/`Enumerable`).
+* `RenderTexture` is a draw target alongside `Window`: both route through the shared `Target`
+  dispatcher, so every drawable renders to either.
+* Predefined `Color` constants, `BlendMode`/`StencilMode` predefined values, `ContextSettings`,
+  and `VideoMode.desktop_mode` / `.fullscreen_modes`.
+* Initial project scaffolding: C extension wrapping CSFML (SFML 2 bindings).
+* Windows, video modes, events, keyboard input, transforms, drawables (circle, rectangle, sprite, image), textures, views, clocks, and render targets.
+* Unit tests (minitest) for Clock, Transformable, Circle, RenderState, VideoMode — headless, deterministic.
+* RuboCop configuration and CI integration (test, check, publish workflows).
+* Publish GitHub Action to build and upload the gem on release.
+* `ext/ports.rb`: downloads, checksum-verifies, and builds SFML 3.0.2 and CSFML 3.0.0 from source into a static, position-independent prefix. Ships inside the gem, so `gem install sfml3-rb` builds its own dependencies with no CSFML pre-installed. Shared by `rake ports` (development) and `ext/extconf.rb` (install time).
+* `ext/extconf.rb` three-way dependency resolution: `--enable-system-libraries` (or `SFML_USE_SYSTEM_LIBRARIES`) links a system CSFML 3; otherwise an existing `ports/<host>` prefix is reused, or built automatically.
+* A compile-time `CSFML_VERSION_MAJOR < 3` guard (`ext/ext/sfml.h`) and an `extconf.rb` header check, so a CSFML 2.x install fails with one actionable message instead of a wall of compiler errors.
+* `CMakeLists.txt` rewritten into a real, buildable configuration (CLion/IDE use only — `rake compile` remains the build of record): resolves the vendored `ports/<host>` prefix, links `find_package(SFML 3 ...)` and the CSFML static archives, and links through the C++ driver, since SFML is C++.
+
+### Changed
+* **Rebuilt the drawing path around `Target`.** `Target` now carries a `{type, handle}` union and
+  dispatches each draw call to the window or render-texture variant; `Window#draw` and every
+  drawable's `#draw` go through it. `RenderState` is initialized from `sfRenderStates_default`
+  instead of field-by-field, fixing the `stencilMode`/`coordinateType` fields that were left
+  uninitialized under CSFML 3, and it now exposes `blend_mode`, `stencil_mode`, `coordinate_type`,
+  `texture` and `shader`.
+* **Naming aligned with SFML 3, typos fixed.** `angle`/`angle=` → `rotation`/`rotation=`;
+  `escalate` → `scale!` (the mutating operation; `scale` remains the getter); `matrix` → `transform`
+  (`matrix` kept as an alias). `View#position`/`position=` were removed: the old setter wrote the
+  viewport rather than the center — use `center`/`viewport`.
+* `Clock#elapsed_time`/`#restart!` now return `SFML::Time` rather than bare `Float` seconds.
+* `Window.new` accepts `(video_mode, title, style = :default, state = :windowed, settings = nil)`
+  instead of hardcoding `sfDefaultStyle`/`sfWindowed`/no settings.
+* **The C extension is now organised by SFML subsystem.** The 24 sources no longer sit flat in `ext/`
+  with their headers in a doubled `ext/ext/` tree; each binding's `.c` and `.h` live together under
+  `ext/core/`, `ext/system/`, `ext/window/` or `ext/graphics/`, matching how SFML and CSFML split
+  themselves, so a binding's home follows from the CSFML header it wraps. Includes became
+  subsystem-relative (`#include "graphics/circle.h"`) and header guards path-derived
+  (`SFML_RB_GRAPHICS_CIRCLE_H`), retiring three `CANDY2D_EXT_*` guards left over from a previous
+  project name. `ext/extconf.rb` sets `$srcs` from a recursive glob and extends `$VPATH`, because mkmf
+  globs only the top level; objects stay flat, which is why every `.c` basename must remain unique.
+  `Rakefile` gained `source_pattern = '**/*.{c,h}'` — recursive so the new tree is seen at all, and
+  including headers because editing one previously triggered no rebuild. `CMakeLists.txt` globs
+  recursively to match.
+* `ext/ext/klass/transform.h` deleted: a stale duplicate of the live `module/transform.h` that nothing
+  included, and which would have collided with it in the new tree. The five unbound placeholders
+  (Image, Polygon, Rectangle, Sprite, Texture) were kept, so the layout still shows where they will
+  land.
+* `CrossBuild#build` now clears **every** staging directory under `pkg/`, not just the current
+  platform's. `rake native:<platform> gem` also runs the shared source-gem task, so a stale
+  `pkg/<name>-<version>/` fails the cross build with `... are not files` about files that plainly
+  exist — which is exactly what the restructuring triggered.
+* **The C extension moved from the untyped `Data_Wrap_Struct` family to `TypedData`.** All wrapped
+  types now carry an `rb_data_type_t`. `Data_*` has been deprecated since Ruby 2.3 and warns on every
+  use under Ruby 4.0, which was the extension's only compile-time portability problem — the build is
+  now warning-clean under `-Wall -Wextra` from Ruby 3.1 to 4.0. `TypedData_Get_Struct` also
+  type-checks, where `Data_Get_Struct` silently reinterpreted whatever pointer it was handed.
+* `ext/extconf.rb` now always compiles with `-Wall -Wextra`, and with `-Werror=deprecated-declarations`
+  when `SFML_STRICT=1`. CI sets it, so a regression to the deprecated API fails the build rather than
+  adding noise. It is opt-in because an unfamiliar compiler at `gem install` time must never fail on a
+  warning.
+* **Minimum Ruby raised from 2.5.0 to 3.1**, matched by `TargetRubyVersion` in `.rubocop.yml` and by
+  the binary gems, which is the point: there is now **one** floor rather than a source/binary split.
+  `>= 2.5.0` had never been exercised — every workflow ran only Ruby 3.3. 3.1 is the oldest
+  cross-ruby the `x64-mingw-ucrt` rake-compiler-dock image carries, so it is what lets a single
+  `RUBY_CC_VERSION` serve every platform.
+* `test.yaml` now runs the suite across 3.1, 3.2, 3.3, 3.4 and 4.0 — exactly the ABI set the binary
+  gems ship — so every Ruby that can receive a precompiled gem is also proven to build from source,
+  with `SFML_STRICT=1`.
+* `publish.yaml` gained a `verify-source` gate that installs the freshly built source gem on the floor
+  and requires `sfml`, so a release cannot ship a source gem that fails to build. Every supported
+  Ruby now has a binary gem, but most *platforms* (macOS, ARM, the BSDs) still do not, and that path
+  stays load-bearing.
+* `Gemfile` gained a `:test` group pinning `minitest` to `~> 5.0`; minitest 6 requires Ruby >= 3.2,
+  still above the floor. The cross-compile containers now install with `BUNDLE_WITHOUT="development
+  test"`.
+* `.rubocop.yml` excludes `pkg/`, `tmp/` and `ports/`. Those hold staged copies of `lib/` and `ext/`,
+  so every offence in a real source file was being counted twice or more.
+* **Packaging now produces precompiled binary gems** alongside the source gem. `rake gem:native`
+  cross-compiles inside [rake-compiler-dock](https://github.com/rake-compiler/rake-compiler-dock);
+  `rake platforms` lists the targets. On a covered platform `gem install sfml3-rb` no longer needs a
+  toolchain, CMake, or a source build at all. The source gem remains the fallback everywhere else,
+  unchanged in behaviour.
+* **Binary gems now cover i686 as well as x86_64, on both glibc and musl Linux and on 32- and 64-bit
+  Windows**: `x86-linux-gnu`, `x86-linux-musl` and `x86-mingw32` join `x86_64-linux-gnu`,
+  `x86_64-linux-musl` and `x64-mingw-ucrt`, with `aarch64-linux-gnu`, `x86_64-darwin` and
+  `arm64-darwin` still experimental. Two gaps are upstream, not ours: RubyInstaller publishes no
+  32-bit Ruby 4.0, so `x86-mingw32` stops at 3.4; and 64-bit Windows before Ruby 3.1 is a different
+  platform (`x64-mingw32`), which is not built.
+* `rakelib/package.rake` asserts the ABIs of each gem it builds against `EXPECTED_ABIS`.
+  rake-compiler only *warns* when an image lacks a cross-ruby it was asked for, so without this a gem
+  could quietly ship fewer ABIs than intended.
+* `ext/ports.rb` targets gained a `multiarch` key. i686 compiles with `i686-linux-gnu-gcc` but its
+  libraries live in `/usr/lib/i386-linux-gnu`, and feeding the compiler triple to
+  `CMAKE_LIBRARY_ARCHITECTURE` would have pointed CMake at a directory that does not exist.
+* The extension build moved from a hand-rolled `rake compile` (`ruby extconf.rb && make` inside
+  `ext/`, then a manual copy) to `rake-compiler`'s `Rake::ExtensionTask`. Builds are now out of tree
+  in `tmp/`, so `ext/` no longer accumulates `.o` files, a `Makefile` and `mkmf.log` beside its
+  sources.
+* `lib/sfml.rb` prefers `sfml/<major.minor>/sfml_ext` — the per-ABI layout binary gems use — and falls
+  back to `sfml/sfml_ext` for a source build.
+* `ext/ports.rb` is now cross-aware: prefixes and build trees are keyed by target (`ports/<target>`)
+  rather than by host, and a CMake toolchain file is generated per target. `SFML_TARGET` selects one;
+  a native build is unaffected.
+* Project renamed to sfml3.rb; **migrated from SFML 2 to SFML 3** (via CSFML 3) — no longer just
+  planned. Distro CSFML packages are frequently still 2.x and are no longer supported.
+* Native extension renamed from the bare `ext` to `sfml/sfml_ext`, matching the `sfml` gem namespace
+  and what `rake-compiler` cross-compilation expects.
+* `event_name.c` and `keyboard.c` name tables are now indexed by named enum constant (C99 designated
+  initializers) instead of raw ordinal position, so a future upstream reorder is a compile error
+  rather than a silently wrong event or key name.
+* `Window#clear` now takes a single `[r, g, b, a]` color array, matching every other color-setting
+  method in the API, instead of three positional numbers.
+* Removed the dead `install-package` extconf hook and its accompanying `ext/linux.sh` (empty) and
+  `ext/msys2.sh` stubs, and the unused `run_script`/`Arguments`/`library_nofound` helpers in
+  `ext/auxlib.rb`.
+* Removed the vendored `include/ruby/*.h` stubs and the empty `include/SFML/CSFML headers` placeholder;
+  nothing referenced them once `CMakeLists.txt` was fixed to query the real Ruby headers.
+* `sfml3-rb.gemspec` carries more information: a `documentation_uri` alongside the existing
+  source/bug-tracker/changelog links, a summary that actually names SFML 3 and the precompiled
+  binaries (it is the line `gem search` shows), and `extra_rdoc_files`/`rdoc_options`. It also ships
+  `CHANGELOG.md` and `TODO.md` — the latter being the module-by-module record of what is bound, which
+  is what tells someone whether the gem covers their case. Comments now record what a reader cannot
+  infer: that rake-compiler rewrites `platform`, `required_ruby_version` and `extensions` for binary
+  gems, and that `required_rubygems_version` is deliberately unset because pinning `>= 3.3.22` here
+  would lock Ruby 3.1.0 (RubyGems 3.3.3) out of the source gem. Reformatted to 2-space indentation.
+  No `homepage_uri`: it would duplicate `source_code_uri`, and RubyGems warns that only the first of a
+  duplicated link is shown.
+* `sfml.gemspec` → `sfml3-rb.gemspec`: description now describes the self-building install rather
+  than a still-planned migration; license changed to `0BSD`, matching `LICENSE.md`.
+* **Gem package renamed from `sfml` to `sfml3-rb`** (`gem install sfml3-rb`). `require 'sfml'` and the
+  `SFML` Ruby module are unchanged — only the RubyGems package name moved.
+
+### Fixed
+* `Circle#scale` returned the position, not the scale.
+* `RenderState` was missing a `dmark` slot; the wrapped struct now holds its texture/shader Ruby
+  references so a GC cannot collect them while the states are in use.
+* `View#position`/`position=` wrote the viewport under a misleading name (removed).
+* `raise_method_no_implemented` crashed on `NULL` and never reached its message branch.
+* `Window#joystick_threshold=` treated the threshold as a boolean.
+* `Circle#draw` raised unconditionally: its second argument check tested `rb_target` against
+  `RenderState` instead of `rb_state` (`ext/circle.c`), and a valid `Target` is never a `RenderState`,
+  so no call could get past it.
+* `Target#draw` unwrapped its `state` argument with no class check — the one remaining place a
+  caller-supplied object reached a struct accessor unguarded. Combined with the untyped
+  `Data_Get_Struct` it used to call, passing the wrong object there reinterpreted an arbitrary
+  pointer; it now raises before that can happen.
+* `ext/ext/module.h` and `ext/ext/klass/transform.h` each declared a `static VALUE` at file scope in a
+  **header**, giving every one of the ~10 including translation units its own zero-initialized copy.
+  `rb_mExt` moved into `ext.c`, its only user; `rb_cTransform` was dead and is gone.
+* An unused `hash` local in `Event_key` (`ext/event.c`).
+* Gem metadata: summary typo, empty description, incorrect homepage.
+* Double-free crash (`free(): double free detected in tcache`) in `Circle`, `Clock`, `Transformable`,
+  and `Window`: their `_free` functions called both CSFML's own `sfX_destroy` *and* `free()` on the
+  same pointer, though `sfX_destroy` already releases it.
+* `Event#size` read `event->size.height` for both components, so a resize event always reported a
+  square. Also fixes the CSFML 3 struct layout (`sfSizeEvent.size` is now a vector, not flat
+  `width`/`height`).
+* `View#get_rotation` and `RenderTarget#draw` were missing `return` statements, so both handed an
+  uninitialized `VALUE` back to Ruby — the same crash class as the double-free above, just not yet
+  triggered by the test suite.
+* `Transform.inverse` was bound to `Transform_combine` instead of `Transform_inverse` — a copy-paste
+  bug that made `.inverse` silently wrong (and unusable at 1 argument).
+* `Window#view=`, `#view`, and `#default_view` were fully implemented but never registered — calling
+  them raised `NoMethodError`.
+* CSFML 3 API port: video mode fields, `sfRenderWindow_create`'s new window-state parameter,
+  `sfRenderWindow_waitEvent`'s new timeout parameter, and `sfFloatRect`'s `position`/`size` fields
+  (was flat `left/top/width/height`).
+* A `%ul` printf format-string bug in `ext/exceptions.c` produced garbled error messages (e.g.
+  "given 3l"); corrected to `%lu`.
+* `test/sfml_test.rb`: `require 'minitest/unit'` (removed from modern minitest) →
+  `require 'minitest/autorun'`; classes referenced without their `SFML::` namespace;
+  `assert_in_epsilon` used directly on arrays, which fails because it calls `.abs` on the expected
+  value.
+
+### Known issues
+* Classes that wrap `T_DATA` never call `rb_define_alloc_func`, so Ruby prints `undefining the
+  allocator of T_DATA class ...` once per class on first construction. Harmless and long-standing;
+  fixing it means moving construction out of the singleton `new` into an alloc func plus
+  `initialize`.
+* Of the nine binary-gem targets, only `x86_64-linux-gnu` has been verified end to end (built,
+  installed, full suite passes). `x64-mingw-ucrt` cross-builds and links cleanly with correct PE
+  imports but has not been run on Windows. The rest have not been run on their target hardware;
+  `aarch64-linux-gnu`, `x86_64-darwin` and `arm64-darwin` are marked `experimental` in
+  `publish.yaml`, so a failure can't hold back a release.
+* The Windows gem imports `libwinpthread-1.dll`, which RubyInstaller ships in its
+  `ruby_builtin_dlls` directory. If that ever proves unreliable, add `-lwinpthread` to the
+  `-Wl,-Bstatic` group in `Ports.cxx_runtime`.
+* `bundle exec rubocop` does not pass on the repository as a whole (55 offenses across 14 files, 40
+  autocorrectable, mostly `Style/FrozenStringLiteralComment`) — this predates the packaging work and
+  `check.yaml` has been failing on it. The gemspec's own remaining offence is
+  `Gemspec/RequireMFA`, left deliberately: setting `rubygems_mfa_required` requires MFA on every
+  owner's RubyGems account, and `publish.yaml` pushes with an API token.
+* [TODO.md](TODO.md) tracks SFML 3 → Ruby API porting coverage, module by module.

data/README.md

@@ -4,8 +4,13 @@ Ruby bindings for [SFML 3](https://www.sfml-dev.org/), via its C API, [CSFML](ht
 
 ## Status
 
-Bound against **CSFML 3**. See [TODO.md](TODO.md) for which parts of the SFML 3 API are ported so
-far, and [CHANGELOG.md](CHANGELOG.md) for what changed recently.
+Latest release: **0.2.2**. Bound against **CSFML 3**. See [TODO.md](TODO.md) for which parts of the
+SFML 3 API are ported so far, and [CHANGELOG.md](CHANGELOG.md) for what changed recently.
+
+API docs (every class, module, method and constant) are on
+[rubydoc.info](https://rubydoc.info/gems/sfml3-rb). The gem also ships RBS type signatures
+(`sig/**/*.rbs`) alongside the extension sources, for IDE completion (Solargraph, RubyMine) and
+static type-checking (Sorbet, Steep).
 
 ## Install
 
@@ -16,18 +21,25 @@ gem install sfml3-rb
 On a platform with a precompiled gem this installs a binary with FreeType, SFML 3 and CSFML 3
 already linked in — no toolchain, no build, nothing to install system-wide:
 
-| Platform | Status |
-| --- | --- |
-| `x86_64-linux-gnu` | built, installed and tested |
-| `x64-mingw-ucrt` (Windows, RubyInstaller 3.1+) | builds and links cleanly; not yet run on Windows |
-| `aarch64-linux-gnu`, `x86_64-linux-musl`, `x86_64-darwin`, `arm64-darwin` | experimental, not yet built |
-
-Each gem carries one extension per Ruby ABI, covering Ruby 3.1 through 4.0.
-
-Anywhere else, RubyGems falls back to the source gem, which downloads and builds FreeType, SFML 3
-and CSFML 3 from pinned, checksum-verified tarballs at install time. That takes a few minutes and
-needs:
-
+| Platform | Ruby | Status |
+| --- | --- | --- |
+| `x86_64-linux-gnu` | 3.1 – 4.0 | built, installed and tested |
+| `x86-linux-gnu` | 3.1 – 4.0 | 32-bit glibc Linux |
+| `x86_64-linux-musl` | 3.1 – 4.0 | Alpine and other musl systems |
+| `x86-linux-musl` | 3.1 – 4.0 | 32-bit musl |
+| `x64-mingw-ucrt` | 3.1 – 4.0 | 64-bit Windows, RubyInstaller 3.1+ |
+| `x86-mingw32` | 3.1 – **3.4** | 32-bit Windows |
+| `aarch64-linux-gnu`, `x86_64-darwin`, `arm64-darwin` | 3.1 – 4.0 | experimental, not yet built |
+
+Each gem carries one extension per Ruby ABI. Two gaps come from upstream rather than from this
+project: **RubyInstaller publishes no 32-bit Ruby 4.0**, so `x86-mingw32` stops at 3.4; and 64-bit
+Windows before Ruby 3.1 used a different platform (`x64-mingw32`), which is not built.
+
+Anywhere else — macOS, ARM, the BSDs — RubyGems falls back to the source gem, which downloads and
+builds FreeType, SFML 3 and CSFML 3 from pinned, checksum-verified tarballs at install time. That
+takes a few minutes and needs:
+
+* Ruby >= 3.1
 * A C/C++ toolchain and CMake >= 3.22
 * On Linux, the X11/udev/OpenGL development headers SFML links against — these can't be bundled.
   On Fedora:
@@ -80,11 +92,32 @@ rake ports    # build the vendored FreeType + SFML 3 + CSFML 3 (rake compile doe
 rake compile  # build the C extension into lib/sfml/
 rake test     # compile, then run the test suite
 rake gem      # build the source gem into pkg/
+rake yard     # build API docs into doc/
+rake rbs      # validate sig/**/*.rbs
 ```
 
+`rake githooks:install` points your checkout at the committed `.githooks/` pre-commit hook, which
+lints staged Ruby with RuboCop and auto-formats staged C with clang-format (`sudo dnf install
+clang-tools-extra` on Fedora for the C side).
+
 `CMakeLists.txt` is a CLion/IDE convenience build against the same vendored `ports/` prefix — `rake`
 is the build of record.
 
+The C extension under `ext/` mirrors SFML's own subsystems, with each binding's `.c` and `.h`
+side by side: `core/` (CSFML umbrella header, macros, exceptions, UTF-32 conversion),
+`system/` (Clock, Time, vectors, streams), `window/` (Window, Event, VideoMode, and the input
+devices), `graphics/` (shapes, Color, Transform, View, Texture, Text, Shader, the render targets),
+`audio/` and `network/`. Includes are subsystem-relative, e.g. `#include "graphics/circle.h"`.
+
+Two `.inc` files hold method bodies shared by several classes and are included once per class with
+a different macro prefix: `audio/sound_source.inc` (Sound, Music, SoundStream) and
+`graphics/render_target.inc` (Window, RenderTexture).
+
+Note that mkmf flattens object files to their basenames, so every `.c` filename has to stay
+unique across the whole tree — and that `$srcs` is baked into the generated Makefile, so after
+adding a `.c` file run `touch ext/extconf.rb && rake compile` (or `rake clean compile`), otherwise
+it is silently left out of the link.
+
 ### Building the binary gems
 
 Cross-compilation runs in [rake-compiler-dock](https://github.com/rake-compiler/rake-compiler-dock),
@@ -108,3 +141,7 @@ that and falls back to the single `lib/sfml/sfml_ext.so` a source build installs
 ## License
 
 [0BSD](LICENSE.md)
+
+---
+
+Developed by: [Algaves](https://github.com/algaves/sfml3.rb) @ 2026