zaniah 0.9.0 → 0.10.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: cc06ae1720a8d05abbc0da78849a355f7c36565c62b3907f941c80dd066594c5
-  data.tar.gz: fd00f6d9bd08c097a5ffa35ce079a83f949c07874d6ff7c76cdc802f7ddd8129
+  metadata.gz: bad32e7fbe4f1abe64589fbc41d73f242c4ed3aeee9f760c67a4d205d0c8d8d7
+  data.tar.gz: b57324bacd30eeea83d04407f689e9ca47d79178d1f0228acf5396fa2ea27881
 SHA512:
-  metadata.gz: 769bfa73b348d773f2139eb34039a7250f6878986375bdd25c361c3922b16d61ab68a3d14c59f8ef7f3cfd68e04a43d868286b624d1996d2fc2afdb92b23f861
-  data.tar.gz: a9642fa580bd9595e15c48903e698b95dfc5a6f876ca0d71438e488899522e2855351cef18a124e005dae5636e53b500aa46e90e101575c12796fc4e9ae80992
+  metadata.gz: 5bbf0bebdad77e095cb6faba2a614cf5129558dd10629c94f2e6ad9966f9cb50dfe32a37b551569cdcfb1ba74085d4c64a3667740ff1699fa7b8ce03c553ad4c
+  data.tar.gz: 9d2491ddb19ce68065497f484b9bba0aa4e026fa998a31e3bca3d7bd41f0ed6edd805f0096aefd28ce2b1acf9309f0b96785cbbce88d67ebea10526094060a2f

data/CHANGELOG.md

@@ -1,5 +1,12 @@
 # Changelog
 
+## 0.10.0 — 2026-09-24
+
+- Add Unicode bidirectional text layout, caret affinity, and Arabic joining.
+- Add vertical writing, ruby annotations, inline embeds, and richer text decoration.
+- Add a viewport-based code editor with optional buffer and syntax-highlighter adapters.
+- Use DirectWrite shaping on Windows while retaining portable text fallback.
+
 ## 0.9.0 — 2026-09-24
 
 - Add semantic vector recording for UI scenes, including text, images, and raster fallbacks for unsupported drawing.

data/docs/adr/019-bidirectional-caret-affinity.md

@@ -0,0 +1,35 @@
+# ADR 019: Bidirectional caret affinity
+
+- Status: Accepted
+- Date: 2026-09-24
+
+## Context
+
+UTF-8 byte offsets identify logical text positions, but a boundary between
+left-to-right and right-to-left runs can appear at two visual positions. A
+single `offset → x` mapping therefore loses information needed for pointer
+selection and arrow-key movement. Keeping logical movement only would avoid
+this ambiguity but would make arrow keys travel opposite to their visual
+direction inside right-to-left text. Storing display-order text instead would
+break editing, copying, and external byte-offset contracts.
+
+## Decision
+
+Keep text and selection offsets in logical UTF-8 byte order. A rendered line
+may associate an offset with upstream and downstream visual caret positions.
+Pointer hit testing returns both offset and affinity; existing offset-only
+methods remain as compatibility shortcuts. Arrow keys move through visual
+carets by default, while `caret_movement: :logical` preserves storage-order
+movement for applications such as code editors.
+
+Selection is a logical byte range rendered as a set of visual rectangles.
+The Unicode Bidirectional Algorithm resolves the paragraph before line-local
+reordering; neither glyph painting nor hit testing changes stored text order.
+
+## Consequences
+
+The editing path must retain affinity separately from the selection offset,
+and callers that want an exact caret position must use the affinity-aware
+methods. Existing LTR offset and caret APIs keep their values. This decision
+can be revisited if a platform-specific native text editor is adopted as the
+storage and interaction model instead of the toolkit's own text buffer.

data/docs/adr/020-lightweight-code-editor-providers.md

@@ -0,0 +1,36 @@
+# ADR 020: Lightweight code editor provider boundaries
+
+- Status: Accepted
+- Date: 2026-09-24
+
+## Context
+
+The original CodeEditor passed an entire document through one Text element and
+constructed a second Text element containing every line number. Both scale with
+the whole file, and the two elements disagree about row heights when code
+wraps. Applications may already have a rope buffer or incremental syntax
+highlighter; bundling either implementation here would duplicate their work.
+
+## Decision
+
+CodeEditor accepts a line-addressable buffer with `line_count`, `line(index)`,
+`line_start(index)`, `line_of(offset)`, `replace(range, text)`, `undo`, and
+`redo`. The default adapter wraps TextBuffer and indexes UTF-8 byte starts.
+`to_s` is optional for external providers. A highlighter supplies
+`tokens(line_index, text)` as byte ranges and scopes, and receives
+`edited(range, new_text)` after edits. Token scopes resolve through
+`theme.syntax`; the editor owns no parser or language grammar.
+
+The dedicated Surface uses List::HeightIndex to shape and paint only visible
+logical lines. A wrapped logical line owns all its display rows, so its line
+number is painted once at the first display row. The Surface owns one caret,
+one selection, IME candidate placement, standard text actions, and Tab
+indentation. The existing positional constructor remains accepted.
+
+## Consequences
+
+Buffer adapters must keep byte offsets stable and return UTF-8 lines. A
+highlighter can cache tokens incrementally, but may only paint within the
+current viewport. Multi-cursor editing, folding, LSP, and a minimap remain
+application concerns. Unknown row heights use an estimate until those rows
+are visited, so scrollbar position can refine as wrapped lines are measured.

data/docs/adr/022-vertical-writing-and-ruby.md

@@ -0,0 +1,37 @@
+# ADR 022: Vertical writing and ruby clusters
+
+- Status: Accepted
+- Date: 2026-09-24
+
+## Context
+
+Japanese documents need top-to-bottom lines, columns that progress right to
+left, and annotations adjacent to their parent text. Rotating an entire
+horizontal line would give incorrect caret, selection, wrapping, and ruby
+geometry. Inserting ruby readings into the text buffer would also corrupt
+logical UTF-8 offsets and copied text.
+
+## Decision
+
+`Paragraph`, `Text`, and `UI::RichText` accept `writing_mode: :vertical_rl`.
+The inline limit is measured top to bottom, and layout converts inline and
+cross axes to physical coordinates for painting and interaction. The built-in
+shaper uses OpenType `vmtx` advances and GSUB `vert`/`vrt2` when a font supplies
+them. Mixed orientation keeps CJK upright and rotates ordinary Latin glyphs;
+`:upright` suppresses that rotation. A RichText run can request
+`combine_upright: true` for a compact horizontal run inside a vertical line.
+
+Ruby is a style on a parent run, not buffer content. The run is an unbreakable
+editing cluster. Its annotation is centered above the parent in horizontal
+text or to its right in vertical text. Both parent and annotation contribute
+to inline/cross box size, but only the parent contributes to copied text.
+Accessibility and TUI readings include the annotation in parentheses.
+
+## Consequences
+
+Caret, hit testing, selection, and IME rectangles share the axis conversion
+used by painting; stored offsets remain logical UTF-8 byte offsets. Ruby and
+combine-upright cannot be combined on one run. The implementation does not
+claim full CSS Writing Modes or OpenType vertical typography: `VORG`, vertical
+GPOS kerning/mark positioning, and font-specific vertical baseline correction
+remain unsupported. Fonts without vertical tables use horizontal advances.

data/docs/components.md

@@ -94,8 +94,8 @@ Zaniah::UI::Button.variants[:variant][:brand] = ->(theme) {
 | L5 | `Validation` | `required`, `format`, `length`, `number`, `rule` | composable rules | n/a |
 | L5 | `FormField` | `(name, value:, label:, control:, validation:, hint:)` | errors + describedby | group/control/alert |
 | L5 | `Form` | `field`, `on_change`, `on_submit`, `values`, `valid?` | validates before submit | form |
-| L5 | `CodeEditor` | `(value, language:, line_numbers:, read_only:)`; `on_change` | multiline editor with scrolling | textbox |
-| L5 | `RichText` | `(runs, selectable:, editable:)`; `apply`, `insert`, `delete`, `replace`, `paragraph_style` | styled editing, IME, range selection and caret | text/textbox |
+| L5 | `CodeEditor` | `(value, buffer:, highlighter:, wrap:, language:, line_numbers:, read_only:)`; `on_change` | viewport-only multiline editor with syntax scopes and Tab indentation | textbox |
+| L5 | `RichText` | `(runs, selectable:, editable:, writing_mode:, text_orientation:)`; `apply`, `insert`, `delete`, `replace`, `append`, `insert_embed`, `paragraph_style` | styled editing, inline embeds, ruby, vertical text, IME, range selection and caret | text/textbox |
 
 All input components are keyboard operable. Disabled controls remain visible but are
 removed from focus traversal. Overlay components close on Esc; modal overlays restore
@@ -111,9 +111,30 @@ It may also implement `refine(previous_matches, query)` for incremental queries.
 unavailable actions, and displays shortcuts with `UI::Kbd`. See [Menus](menus.md).
 
 `UI::RichText` accepts UTF-8 byte ranges at grapheme boundaries. Inline styles are
-`bold`, `italic`, `size`, `color`, `font`, and `link`; paragraphs support start,
-center, end, and non-final-line justification, plus bullet/ordered lists and levels.
-It is read-only by default; set `editable: true` to enable keyboard editing and IME.
+`bold`, `italic`, `size`, `color`, `font`, `link`, `underline` (`:single`, `:double`,
+`:wavy`), `underline_color`, `strikethrough`, `background`, `baseline`
+(`:superscript` or `:subscript`), `letter_spacing`, `ruby: "reading"`, and
+`combine_upright: true`. Ruby parent text is one unbreakable selection cluster;
+copying omits the annotation, while accessibility and TUI expose it in
+parentheses. Ruby and combine-upright cannot be set together on one run.
+`writing_mode: :vertical_rl` uses top-to-bottom lines and right-to-left columns;
+`text_orientation: :mixed` rotates ordinary Latin by default, whereas `:upright`
+keeps it upright. Paragraph styles include
+alignment, lists, levels, `indent`, `quote`, `background`, and before/after spacing.
+`insert_embed(offset, key:, width:, height:) { |cx| element }` stores U+FFFC in the
+text and lays the element out at that inline position. `append(text, style:)` reuses
+cached layouts for unchanged earlier fragments. RichText is read-only by default;
+set `editable: true` to enable keyboard editing and IME.
+
+`UI::CodeEditor` keeps the legacy positional constructor and also accepts a
+line-addressable `buffer:` with `line_count`, `line(index)`, `line_start(index)`,
+`line_of(offset)`, `replace(range, text)`, `undo`, and `redo`. A plain string or
+`TextBuffer` uses the bundled adapter. Optional `highlighter:` provides
+`tokens(line_index, text)` byte ranges with scopes and receives
+`edited(range, new_text)` notifications. Scopes use `theme.syntax` colors. Only
+visible logical lines are shaped; wrapped display rows share one line number.
+The editor supports one caret/selection, standard text actions, IME placement,
+and Tab indentation. See [ADR 020](adr/020-lightweight-code-editor-providers.md).
 
 ## Image decoding
 

data/docs/text.md

@@ -38,18 +38,43 @@ Provider objects may be supplied instead of symbols:
 | `segmenter` | `grapheme_clusters(text)` | Strings that exactly partition the input |
 | `font_raster` | `rasterize(font, glyph_id, size:, subpixel_x:)` | A glyph bitmap |
 
+Shapers may additionally accept `script:`, `language:`, `direction:`,
+`features:`, and `writing_mode:`. The typesetter inspects accepted keywords, so an existing
+`shape(glyphs, size:, text:)` provider remains valid. If a provider does not
+accept `direction:`, a right-to-left run is shaped in storage order and its
+glyphs are reversed for display. Hebrew works with this fallback; Arabic
+joining in a legacy provider still requires a direction-aware shaper. The built-in shaper
+accepts `direction: :ltr/:rtl` and a four-character OpenType feature map such
+as `{"liga" => false}`.
+
 Providers may implement `close`; the text system closes them when it closes.
 Custom mutable providers used by `fork` must also implement `layout_copy` and
 return an independent provider.
 
 The default Ruby shaper supports horizontal Latin, CJK, and kana text, including
 common OpenType ligatures, contextual substitutions, pair positioning, and
-legacy kerning. It is not a replacement for full complex-script shaping:
-Arabic/Indic reordering, AAT `morx`, vertical text, complete mark positioning,
-and variation-index positioning are unsupported.
-
-Built-in rasterizers are `:native`/`:alhena`, `:freetype`, and `:coretext`
-(`:core_text` is an alias). FreeType and CoreText require their platform library.
+legacy kerning. For Arabic-script OpenType fonts with GSUB, it selects
+`isol`/`fina`/`medi`/`init` from Unicode 18 Joining_Type and then applies
+`rlig`; transparent marks and ZWJ/ZWNJ affect joining. The input `text:` is
+needed to select forms. Fonts using AAT `morx` (including some macOS Arabic
+fonts), advanced Arabic substitutions, complete mark and cursive positioning,
+Indic reordering, complete vertical GPOS positioning, and variation-index
+positioning still need an external shaper. The bundled Abel font has no Arabic
+glyphs. Vertical layout uses `vmtx` advances and GSUB `vert`/`vrt2` where
+available; fonts without vertical metrics retain horizontal advances.
+
+Built-in rasterizers are `:native`/`:alhena`, `:freetype`, `:coretext`
+(`:core_text` is an alias), and Windows-only `:directwrite` (`:direct_write`
+is an alias). FreeType, CoreText, and DirectWrite require their platform library.
+DirectWrite remains opt-in; Windows still defaults to `:native`. It loads fonts
+opened by `FontDB` from their file paths, and other in-memory fonts through the
+Windows 10 in-memory font loader. Its default atlas bitmap is grayscale;
+`Platform::Windows::DirectWrite#rasterize(..., antialias: :cleartype)` returns
+an RGB coverage bitmap for callers that can display subpixel coverage. Compare
+it with Alhena using `ruby examples/native_font.rb path/to/font.ttf --directwrite`
+on Windows. Variable-font instances with selected axes use Alhena's rasterizer
+until an axis-aware DirectWrite face is available. Close an explicitly created
+DirectWrite provider when finished.
 Unimplemented symbolic adapters raise `ArgumentError`; pass a provider object to
 integrate another shaper, segmenter, font database, or rasterizer.
 
@@ -121,6 +146,41 @@ offset = paragraph.hit_test(Zaniah::Point.new(40, 20))
 point = paragraph.offset_to_point(offset)
 ```
 
+Bidirectional text uses Unicode 18.0's UAX #9 rules, with Unicode tables
+generated by `tools/generate_unicode_tables.rb` and no runtime data download.
+`Text.new(value, text_direction: :auto)` detects paragraph direction; use
+`:ltr` or `:rtl` to override it. Layout-only callers may pass `direction:`
+to `layout_paragraph` or `layout_line`. `align: :start/:end` follows paragraph
+direction. Text remains in logical UTF-8 byte order for editing and copying.
+
+At a boundary between directional runs, the same byte offset can have two
+screen positions. `LineLayout#caret_x(offset, affinity: :downstream)` chooses
+one, and `LineLayout#hit_test(x)` returns `[offset, affinity]`. The old
+`x_for_index` and `index_for_x` methods remain available for callers that do
+not retain affinity. `selection_rects(range)` returns the visual rectangles
+occupied by a logical range. `Text.new(..., caret_movement: :logical)` opts
+out of the default visual left/right arrow movement.
+
+Vertical Japanese layout is opt-in. The `width:` argument to a vertical
+paragraph is its inline (top-to-bottom) limit; columns advance right to left.
+On `Text`, use `.h(...)` for that limit:
+
+```ruby
+paragraph = system.layout_paragraph("縦書き", width: 240,
+  writing_mode: :vertical_rl)
+text = Zaniah::Text.new("縦書き", writing_mode: :vertical_rl,
+  text_orientation: :mixed).h(240)
+```
+
+`text_orientation: :mixed` keeps CJK glyphs upright and rotates ordinary Latin
+letters and digits 90 degrees. `:upright` keeps all glyphs upright. Hit testing,
+caret, selection, composition underline, and IME bounds use vertical geometry;
+offsets and clipboard text stay in logical UTF-8 byte order. This is a
+lightweight vertical layout, not a complete CSS Writing Modes implementation:
+it does not implement `VORG`, vertical kerning/mark positioning, script-specific
+vertical baseline adjustment, or arbitrary sideways writing modes. Font support
+determines whether vertical glyph substitutions and metrics are available.
+
 Wrapping supports `:none`, `:word`, and `:anywhere`; Japanese kinsoku modes are
 `:push`, `:hanging`, and `:none`. Font fallback is selected per grapheme from the
 requested font through CJK, emoji, symbol, and general system faces. Colored
@@ -158,8 +218,21 @@ text.insert(text.text.bytesize, " — draft")
 text.paragraph_style(0...text.text.bytesize, align: :start, list: :bullet, level: 0)
 ```
 
-Supported inline styles are `bold`, `italic`, `size`, `color`, `font`, and
-`link`. Paragraph styles support `align: :start/:center/:end/:justify`,
+Supported inline styles include `bold`, `italic`, `size`, `color`, `font`,
+`link`, decoration/background styles, `ruby:`, and `combine_upright:`.
+`ruby: "reading"` annotates one unbreakable parent run; copying selects only
+the parent text, while accessibility and TUI readings include the annotation
+in parentheses. `combine_upright: true` keeps a short run such as `12` upright
+inside vertical text. Ruby and combine-upright cannot be combined on one run.
+
+```ruby
+rich = Zaniah::UI::RichText.new([
+  {text: "漢字", ruby: "かんじ"},
+  {text: "12", combine_upright: true}
+], writing_mode: :vertical_rl).h(240)
+```
+
+Paragraph styles support `align: :start/:center/:end/:justify`,
 `list: :none/:bullet/:ordered`, and nonnegative nesting levels. `on_change`
 receives `(text, rich_text)`; selection changes are reported by `on_select`.
 IME composition uses the existing `TextBuffer` composition path.

data/docs/theme.md

@@ -1,7 +1,7 @@
 # Themes and state styles
 
 `Zaniah::Theme.dark`, `.light`, and `.high_contrast` provide semantic color,
-spacing, radius, shadow, typography, and motion tokens. `App` installs the dark
+spacing, radius, shadow, typography, syntax, and motion tokens. `App` installs the dark
 theme by default and follows native window appearance changes. Read the active
 theme with `FrameContext#theme` or `EntityContext#theme`.
 
@@ -32,6 +32,9 @@ themes' raw color values.
 - `spacing`: a compact 4-pixel scale indexed by token number.
 - `radii` and `shadows`: semantic `none`, `sm`, `md`, `lg`, and `full` values.
 - `typography`: sans/mono families, six sizes, four weights, and three line heights.
+- `syntax`: keyword, string, comment, number, function, type, constant,
+  punctuation, operator, variable, and fallback text colors. `syntax.color(scope)`
+  accepts dotted highlighter scopes such as `"keyword.control"`.
 - `motion`: fast/base/slow durations, easing names, and `reduced?`.
 
 Records support `with`, so a local override does not mutate the shared theme:
@@ -45,6 +48,9 @@ quiet = base.with(
 app.global(:theme, quiet)
 ```
 
+Omitting `syntax:` in `Theme.new` derives readable syntax colors from `colors`.
+Pass a `Theme::Syntax` value to override them explicitly.
+
 Native windows select dark or light initially and refresh the application theme
 when system appearance changes. A system reduced-motion preference sets
 `theme.motion.reduced?` and collapses animation durations to zero.

data/docs/tui.md

@@ -29,7 +29,8 @@ tests and non-window integrations.
 | TreeView | indentation with `▸`/`▾` expansion markers |
 | Sparkline and all chart types | eight-level Unicode sparkline summary |
 | Form, FormField | labeled values, `!` errors, and a submit button |
-| CodeEditor, RichText | numbered plain-text lines or concatenated text runs |
+| CodeEditor | numbered logical lines; wrap, syntax colors, and inline IME underline degrade to plain cells |
+| RichText | concatenated text runs; ruby readings appear in parentheses; inline embeds appear as U+FFFC and decoration/paragraph backgrounds and vertical geometry degrade to plain cells |
 
 Rounded corners, shadows, gradients, and alpha scrims reduce to solid cells. Focus is
 reported by the terminal cursor/reverse-video capability; motion introduced in M7 is

data/examples/native_font.rb

@@ -4,12 +4,27 @@ $LOAD_PATH.unshift(File.expand_path("../lib", __dir__))
 require "zaniah"
 require "alhena"
 
-provider_name = ARGV.delete("--freetype") ? :freetype : :coretext
-require "zaniah/platform/#{provider_name == :freetype ? 'linux/free_type' : 'mac/core_text'}"
-provider = provider_name == :freetype ? Zaniah::Platform::Linux::FreeType.new : Zaniah::Platform::Mac::CoreText.new
-font = Alhena::Font.open(ARGV.fetch(0))
-bitmap = provider.rasterize(font, font.glyph_id("A"), size: 32)
+provider_name = if ARGV.delete("--directwrite") || RUBY_PLATFORM.match?(/mswin|mingw/)
+  :directwrite
+elsif ARGV.delete("--freetype") || !RUBY_PLATFORM.include?("darwin")
+  :freetype
+else
+  :coretext
+end
+require "zaniah/platform/#{ {directwrite: 'windows/direct_write', freetype: 'linux/free_type', coretext: 'mac/core_text'}.fetch(provider_name) }"
+path = File.expand_path(ARGV.fetch(0))
+db = Zaniah::TextSystem::FontDB.new(paths: [path])
+font = db.open(path)
+provider = case provider_name
+when :directwrite then Zaniah::Platform::Windows::DirectWrite.new(font_db: db)
+when :freetype then Zaniah::Platform::Linux::FreeType.new
+else Zaniah::Platform::Mac::CoreText.new
+end
+glyph = font.glyph_id("A".ord)
+bitmap = provider.rasterize(font, glyph, size: 32)
 raise "empty native font bitmap" unless bitmap.width.positive? && bitmap.height.positive? && bitmap.coverage.bytes.any?(&:positive?)
-puts "#{provider_name}: #{bitmap.width}x#{bitmap.height}, bearing=#{bitmap.left},#{bitmap.top}"
-puts bitmap.to_ascii
+reference = font.rasterize(glyph, size: 32)
+puts "Alhena #{reference.width}x#{reference.height}, bearing=#{reference.left},#{reference.top} | #{provider_name} #{bitmap.width}x#{bitmap.height}, bearing=#{bitmap.left},#{bitmap.top}"
+left, right = reference.to_ascii.lines, bitmap.to_ascii.lines
+[left.length, right.length].max.times { |index| puts "#{left[index].to_s.chomp.ljust(34)} | #{right[index]}" }
 provider.close

data/lib/zaniah/input/keymap.rb

@@ -23,6 +23,7 @@ module Zaniah
           primary = mac ? "cmd" : "ctrl"
           map = new(**options)
             .bind("tab", :focus_next)
+            .bind("tab", :insert_tab, context: "in_code_editor")
             .bind("shift-tab", :focus_previous)
             .bind("left", :focus_left, context: "!in_text_field && !in_list")
             .bind("right", :focus_right, context: "!in_text_field && !in_list")

data/lib/zaniah/platform/windows/direct_write.rb

@@ -0,0 +1,147 @@
+# frozen_string_literal: true
+
+require "fiddle"
+require "alhena"
+require_relative "../../ffi/com"
+
+module Zaniah
+  module Platform
+    module Windows
+      # Rasterizes the same glyph IDs that the selected shaper produced. DirectWrite
+      # owns the font face and glyph cache; Zaniah still owns layout and its atlas.
+      class DirectWrite
+        P, I, F = Fiddle::TYPE_VOIDP, Fiddle::TYPE_INT, Fiddle::TYPE_FLOAT
+        FACTORY5_IID = [0x958db99a, 0xbe2a, 0x4f09].pack("L<S<S<") +
+          [0xaf, 0x7d, 0x65, 0x18, 0x98, 0x03, 0xd1, 0xd3].pack("C8")
+        MAX_PIXELS = 16_777_216
+
+        def initialize(font_db: nil)
+          raise Error, "DirectWrite is available only on Windows" unless RUBY_PLATFORM.match?(/mswin|mingw/)
+          @font_db, @faces = font_db, {}.compare_by_identity
+          @library = FFI::Library.new("dwrite.dll")
+          output = pointer_out
+          FFI::COM.check(@library.fn(:DWriteCreateFactory, [I, P, P], I).call(0, FACTORY5_IID, output))
+          @factory = output.unpack1("J")
+          raise Error, "DirectWrite factory unavailable" if @factory.zero?
+        end
+
+        def cache_key = "directwrite/#{RUBY_PLATFORM}/factory5"
+
+        def rasterize(font, glyph, size:, subpixel_x: 0, antialias: :grayscale, **_options)
+          raise IOError, "DirectWrite provider closed" unless @factory
+          raise ArgumentError, "invalid font size" unless size.is_a?(Numeric) && size.finite? && size.positive?
+          raise ArgumentError, "invalid glyph ID" unless glyph.is_a?(Integer) && glyph.between?(0, font.glyph_count - 1) && glyph <= 0xffff
+          raise ArgumentError, "invalid subpixel position" unless subpixel_x.is_a?(Numeric) && subpixel_x.finite?
+          raise ArgumentError, "antialias must be grayscale or cleartype" unless %i[grayscale cleartype].include?(antialias)
+          # CreateFontFace selects a collection face, not a variable-font instance.
+          # Preserve requested axes until a DirectWrite axis-aware face path exists.
+          if font.respond_to?(:axis_values) && !font.axis_values.empty?
+            return font.rasterize(glyph, size: size, subpixel_x: subpixel_x,
+              lcd: antialias == :cleartype ? :rgb : nil)
+          end
+
+          face = native_face(font)
+          index = [glyph].pack("S<")
+          advance = [0.0].pack("e")
+          run = [face, size.to_f, 1, Fiddle::Pointer[index].to_i,
+            Fiddle::Pointer[advance].to_i, 0, 0, 0].pack("Q<eL<Q<Q<Q<L<L<")
+          output = pointer_out
+          FFI::COM.check(FFI::COM.vcall(@factory, 23, [P, F, P, I, I, F, F, P], I,
+            run, 1.0, 0, 4, 0, subpixel_x.to_f, 0.0, output))
+          analysis = output.unpack1("J")
+          bounds = "\0".b * 16
+          FFI::COM.check(FFI::COM.vcall(analysis, 3, [I, P], I, 1, bounds))
+          left, top, right, bottom = bounds.unpack("l<4")
+          width, height = right - left, bottom - top
+          return Alhena::Bitmap.new(width: 0, height: 0, coverage: "") if width.zero? || height.zero?
+          raise Error, "DirectWrite bitmap exceeds size limit" unless width.positive? && height.positive? && width * height <= MAX_PIXELS
+          rgb = "\0".b * (width * height * 3)
+          FFI::COM.check(FFI::COM.vcall(analysis, 4, [I, P, P, I], I, 1, bounds, rgb, rgb.bytesize))
+          coverage = if antialias == :cleartype
+            rgb
+          else
+            gray = "\0".b * (width * height)
+            gray.bytesize.times do |index|
+              offset = index * 3
+              gray.setbyte(index, (rgb.getbyte(offset) + rgb.getbyte(offset + 1) + rgb.getbyte(offset + 2) + 1) / 3)
+            end
+            gray
+          end
+          Alhena::Bitmap.new(width: width, height: height, left: left, top: -top,
+            channels: antialias == :cleartype ? 3 : 1, coverage: coverage)
+        ensure
+          FFI::COM.release(analysis) if analysis && !analysis.zero?
+        end
+
+        def close
+          return unless @factory
+          @faces.each_value { |face| FFI::COM.release(face) }
+          @faces.clear
+          if @memory_loader
+            FFI::COM.check(FFI::COM.vcall(@factory, 14, [P], I, @memory_loader))
+            FFI::COM.release(@memory_loader)
+          end
+          FFI::COM.release(@factory)
+          @factory = nil
+        end
+
+        private
+
+        def pointer_out = [0].pack("J")
+
+        def native_face(font)
+          @faces[font] ||= begin
+            path = @font_db.path_for(font) if @font_db&.respond_to?(:path_for)
+            path = nil if path && (!File.file?(path) || File.binread(path) != font.data)
+            file = path ? file_from_path(path) : file_from_memory(font.data)
+            supported, _file_type, face_type, count = analyze(file)
+            raise Error, "DirectWrite cannot read font data" if supported.zero? || font.index >= count
+            output = pointer_out
+            files = [file].pack("J")
+            FFI::COM.check(FFI::COM.vcall(@factory, 9, [I, I, P, I, I, P], I,
+              face_type, 1, files, font.index, 0, output))
+            output.unpack1("J")
+          ensure
+            FFI::COM.release(file) if file && !file.zero?
+          end
+        end
+
+        def file_from_path(path)
+          output = pointer_out
+          wide = path.encode("UTF-16LE").b + "\0\0".b
+          FFI::COM.check(FFI::COM.vcall(@factory, 7, [P, P, P], I, wide, 0, output))
+          output.unpack1("J")
+        end
+
+        def file_from_memory(bytes)
+          raise Error, "DirectWrite font data exceeds size limit" if bytes.bytesize > 0xffffffff
+          unless @memory_loader
+            output = pointer_out
+            # Factory5 adds this method after 3 + 21 + 2 + 5 + 9 + 3 + 1 entries.
+            FFI::COM.check(FFI::COM.vcall(@factory, 44, [P], I, output))
+            loader = output.unpack1("J")
+            begin
+              FFI::COM.check(FFI::COM.vcall(@factory, 13, [P], I, loader))
+              @memory_loader = loader
+            rescue StandardError
+              FFI::COM.release(loader) unless loader.zero?
+              raise
+            end
+          end
+          output = pointer_out
+          # A null owner asks DirectWrite to copy bytes, so no Ruby object is pinned.
+          FFI::COM.check(FFI::COM.vcall(@memory_loader, 4, [P, P, I, P, P], I,
+            @factory, bytes, bytes.bytesize, 0, output))
+          output.unpack1("J")
+        end
+
+        def analyze(file)
+          supported, file_type, face_type, count = Array.new(4) { [0].pack("L<") }
+          FFI::COM.check(FFI::COM.vcall(file, 5, [P, P, P, P], I,
+            supported, file_type, face_type, count))
+          [supported, file_type, face_type, count].map { |value| value.unpack1("L<") }
+        end
+      end
+    end
+  end
+end