okab 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 8ccd04c824a28ca26ec41d2610efdcd2912a51adc0a6d9cb49fe26a8aa858751
-  data.tar.gz: 26a86a7f3b03e6406015ea712f8b2dac25909b947c22cc6d0d36d0edde7f58ff
+  metadata.gz: a450b67de73b065f7d9a15aefce5a2341640fe4e40f97ccf71d2e0e92cfd7b0e
+  data.tar.gz: 3f5cf2767ec1f0f33277917bb2579dec77365771b1c5d480013cd6ad59d2a61a
 SHA512:
-  metadata.gz: 0e98d8261aff467b1e97f93242a73e6cacbc75d3a7d964e20da9f2fd1d900656342a31b72da32e715b593984e06c5ba08f9e5a4a70b4edddeb49b15c3cb269a8
-  data.tar.gz: 81794209eebf9639ecd66023f0d42872d2573906a27de87a6a3d05f36e8e619522a8ac0fbf4d12677cf58aae5c80350b836548c3a49b7458aa4861c3465f2163
+  metadata.gz: 9ce197d51db85374f0cc879e8355a6a56d9feadcd70dcd434fa73116237e1ab45e8f22e4da247582189de2afd02b18216dcdbe6880efbd67b3db78e37638a5bb
+  data.tar.gz: dc25ea8a7ac3069facf207845cdc0eec481fe14a5cb2b2b368fe9eda730555b6f9789bab96102153b3cae6392c93333ac62b21b28ce9a8ddcaf5d07c7b7cbe34

data/CHANGELOG.md

@@ -1,5 +1,9 @@
 # Changelog
 
+## 0.2.0 — 2026-09-24
+
+- Add an optional Zaniah vector-document adapter that preserves PDF paths, searchable shaped glyphs, images, clipping, and opacity while rasterizing unsupported effects one command at a time.
+
 ## 0.1.0 — 2026-09-23
 
 - Initial release.

data/README.md

@@ -1,46 +1,110 @@
-# Okab
-
-Okab (ζ Aquilae) takes its name from Arabic *ʿuqāb*, “eagle”. It is a small Ruby library for creating searchable PDF 1.7 documents with embedded TrueType and supported CFF1-outline fonts.
+<h1 align="center">Okab</h1>
+
+<p align="center">
+  <strong>Generate searchable PDFs with embedded TrueType and CFF1 fonts in pure Ruby</strong>
+</p>
+
+<p align="center">
+  <a href="https://rubygems.org/gems/okab"><img src="https://img.shields.io/gem/v/okab.svg" alt="Gem version"></a>
+  <a href="https://rubygems.org/gems/okab"><img src="https://img.shields.io/gem/dt/okab.svg" alt="Gem downloads"></a>
+  <a href="https://github.com/noxdea/okab/actions/workflows/main.yml"><img src="https://github.com/noxdea/okab/actions/workflows/main.yml/badge.svg" alt="CI"></a>
+  <img src="https://img.shields.io/badge/Ruby-%3E%3D%203.2-cc342d.svg" alt="Ruby 3.2 or newer">
+  <a href="LICENSE.txt"><img src="https://img.shields.io/badge/license-MIT-blue.svg" alt="MIT license"></a>
+</p>
+
+<p align="center">
+  <a href="#features">Features</a> ·
+  <a href="#installation">Installation</a> ·
+  <a href="#quick-start">Quick start</a> ·
+  <a href="#limits">Limits</a> ·
+  <a href="#development">Development</a>
+</p>
+
+---
+
+Okab is a small Ruby library for generating PDF 1.7 documents. It embeds font
+subsets through [Alhena](https://github.com/noxdea/alhena) and writes `ToUnicode`
+mappings so text remains searchable and copyable. The same document inputs
+produce stable output without timestamps. Its name comes from Arabic *ʿuqāb*,
+“eagle” (ζ Aquilae).
 
 ## Features
 
-- TrueType and static name-keyed CFF1 font subsetting through [Alhena](https://github.com/noxdea/alhena), with CID fonts and `ToUnicode` mappings for text search and copy
-- Text, wrapped text, paths, clipping, transforms, opacity, links, and outlines
+- TrueType and supported static CFF1 font embedding, including Japanese text when the font contains the glyphs
+- Text and wrapped text, vector paths, clipping, transforms, and opacity
 - PNG images with alpha and JPEG images embedded without re-encoding
-- Stable output for the same document inputs; timestamps are omitted
-
-PDF reading/editing, encryption, signatures, forms, and PDF/A are out of scope. CFF2, variable CFF1, and already CID-keyed CFF fonts are not supported; CFF embedding requires `subset: true`. PNG input is limited to non-interlaced 8-bit images; JPEG input is limited to 8-bit grayscale or RGB baseline, extended-sequential, or progressive images, and Exif orientation is not applied.
+- Optional Zaniah vector-document bridge with searchable glyph runs
+- Page links, document outlines, and deterministic PDF output
 
 ## Installation
 
-```ruby
-gem "okab"
+```sh
+gem install okab
 ```
 
-Okab requires Ruby 3.2 or later and Alhena 0.3.0 or later.
+Okab requires Ruby 3.2 or newer and Alhena 0.3.x. With Bundler, add `gem "okab"`
+to your Gemfile.
+
+## Quick start
 
-## Usage
+Supply a TrueType font containing the text you want to render:
 
 ```ruby
 require "okab"
 
 font = Okab::Font.load("/path/to/font.ttf")
-document = Okab::Document.new(title: "Quarterly report", author: "Yudai Takada")
-page = document.page(width: 595, height: 842) # points
-page.text("四半期報告", x: 48, y: 790, font: font, size: 24)
-page.text_block("A searchable report with embedded fonts.", x: 48, y: 750,
-  width: 360, font: font, size: 12, line_height: 18)
-page.rect(48, 700, 120, 28).fill([0.2, 0.4, 0.8])
-page.link([48, 700, 120, 28], uri: "https://example.com")
+document = Okab::Document.new(title: "Quarterly report")
+page = document.page(width: 595, height: 842) # PDF points
+page.text("Quarterly report", x: 48, y: 790, font: font, size: 24)
+page.text_block("A searchable report with embedded fonts.",
+  x: 48, y: 750, width: 360, font: font, size: 12, line_height: 18)
 document.outline("Report", page: page)
 document.write("report.pdf")
 ```
 
-Coordinates use PDF points, with the origin at the lower-left corner. Text must be UTF-8. Supply a font that contains the characters you want to render.
+Coordinates are in PDF points, with the origin at the lower-left corner. Text
+must be valid UTF-8. Use a font with Japanese glyphs to render Japanese text.
+
+### Zaniah vector documents
+
+Install Zaniah separately, then load the optional bridge explicitly:
+
+```ruby
+require "okab/zaniah_vector"
+
+vector = Zaniah::Vector.record(width: 595, height: 842) { slide_element }
+pdf = Okab::Document.new
+page = pdf.page(width: vector.width, height: vector.height)
+Okab::ZaniahVector.draw(page, vector)
+pdf.write("slide.pdf")
+```
+
+The bridge converts Zaniah's top-left coordinates to PDF's lower-left
+coordinates. Solid quads and paths remain PDF vector operations, shaped glyph
+IDs are embedded with `ToUnicode` mappings, and images remain PDF images.
+Unsupported paint effects such as multi-stop gradients and shadows are
+rasterized individually, never as a full-page screenshot. See
+[the adapter notes](docs/zaniah-vector.md) for the mapping and limits.
+
+## Limits
+
+Okab generates PDFs; it does not read or edit them. Encryption, signatures,
+forms, and PDF/A are out of scope.
+
+- CFF2, variable CFF1, and already CID-keyed CFF fonts are unsupported. CFF embedding requires `subset: true`.
+- PNG input must be non-interlaced and 8-bit.
+- JPEG input must be 8-bit grayscale or RGB, using baseline, extended-sequential, or progressive encoding. Exif orientation is not applied.
 
 ## Development
 
-Run `bundle exec rake` and `bundle exec rbs -I sig validate`. To exercise real Japanese extraction locally, set `OKAB_TEST_FONT` to a TrueType font containing Japanese characters and install Poppler's `pdftotext` utility:
+```sh
+bundle install
+bundle exec rake
+bundle exec rbs -I sig -r alhena validate
+```
+
+To test real Japanese text extraction, set `OKAB_TEST_FONT` to a TrueType font
+with Japanese glyphs and install Poppler's `pdftotext` utility:
 
 ```sh
 OKAB_TEST_FONT=/path/to/japanese-font.ttf bundle exec rake
@@ -48,4 +112,4 @@ OKAB_TEST_FONT=/path/to/japanese-font.ttf bundle exec rake
 
 ## License
 
-MIT
+Okab is released under the [MIT License](LICENSE.txt).

data/docs/zaniah-vector.md

@@ -0,0 +1,26 @@
+# Zaniah vector-document adapter
+
+`require "okab/zaniah_vector"` loads the optional integration. Call
+`Okab::ZaniahVector.draw(page, vector_document)` with an `Okab::Page` whose
+dimensions match the `Zaniah::Vector::Document`. The method returns the page.
+The core `require "okab"` path does not load or depend on Zaniah.
+
+| Zaniah command | PDF representation |
+|---|---|
+| Solid `Quad`, `Path`, plain `Underline` | PDF fill/stroke path with the source color, fill rule, line cap/join, and opacity |
+| `GlyphRun` | Embedded `Okab::Font` CID glyphs at their shaped positions, with source clusters in `ToUnicode` |
+| `Image`, `Raster` | Image XObject (including alpha and source cropping); raster tint is applied before embedding |
+| Clip, transform, opacity | PDF graphics-state clip, transform, and `ExtGState` |
+| Gradient `Quad`, `Shadow`, wavy underline, unsupported dashed-border combination | Local image XObject of that command only |
+
+This is a drawing adapter, not a layout engine. Persisted or printed text stays
+searchable when Zaniah records a `GlyphRun`, including multi-character clusters.
+The original font must be embeddable by Okab: static TrueType and supported
+static CFF1 are supported; CFF2 and variable CFF1 are not. An invalid or
+unknown vector command raises an error instead of silently dropping content.
+The PDF page uses points at 72 per inch; choose matching Zaniah document
+dimensions when recording. The adapter does not automatically scale pages.
+
+To test the optional integration locally, make Zaniah available on Ruby's load
+path and run `bundle exec rspec spec/zaniah_vector_spec.rb`. The image comparison
+test uses `pdftoppm` when installed; the text extraction test uses `pdftotext`.

data/lib/okab/document.rb

@@ -33,7 +33,7 @@ module Okab
       font = Font.new(font) if font.is_a?(Alhena::Font)
       raise ArgumentError, "font must be an Okab::Font or Alhena::Font" unless font.is_a?(Font)
 
-      key = [font.object_id, !!subset]
+      key = [font.face.object_id, !!subset]
       @fonts[key] ||= EmbeddedFont.new(self, font, subset: subset)
     end
 

data/lib/okab/font.rb

@@ -58,6 +58,22 @@ module Okab
       cids.pack("n*")
     end
 
+    # Preserve glyph IDs produced by an external shaper instead of shaping the
+    # source text a second time when a vector display list is embedded.
+    def encode_glyph(glyph, unicode:)
+      raise ArgumentError, "invalid glyph ID" unless glyph.is_a?(Integer) && glyph.between?(0, face.glyph_count - 1)
+      raise ArgumentError, "glyph text must be valid UTF-8" unless unicode.is_a?(String) && unicode.encoding == Encoding::UTF_8 && unicode.valid_encoding?
+      key = [unicode, glyph]
+      cid = @cid_by_character[key]
+      unless cid
+        cid = @characters.length
+        raise ArgumentError, "a PDF font cannot encode more than 65,535 characters" if cid > 65_535
+        @cid_by_character[key] = cid
+        @characters[cid] = [unicode.empty? ? "\uFFFD" : unicode, glyph]
+      end
+      [cid].pack("n")
+    end
+
     def glyph_ids
       @characters.values.map(&:last).uniq
     end

data/lib/okab/page.rb

@@ -57,6 +57,15 @@ module Okab
       self
     end
 
+    def glyph(glyph_id, x:, y:, font:, size:, unicode:, color: [0, 0, 0])
+      size = finite(size, "font size")
+      raise ArgumentError, "font size must be positive" unless size.positive?
+      embedded = @document.embed_font(font)
+      encoded = embedded.encode_glyph(glyph_id, unicode: unicode)
+      @operations << [:text, finite(x, "x"), finite(y, "y"), embedded, encoded, size, rgb(color), 0.0, false, false]
+      self
+    end
+
     def text_block(string, x:, y:, width:, font:, size:, line_height:, align: :left, color: [0, 0, 0], tracking: 0)
       validate_text(string)
       x, y = finite(x, "x"), finite(y, "y")
@@ -90,8 +99,28 @@ module Okab
       raw(path.commands.join("\n"))
     end
 
-    def fill(color) = raw("#{rgb(color).join(' ')} rg\nf")
-    def stroke(color, width: 1) = raw("#{rgb(color).join(' ')} RG\n#{positive(width, 'line width')} w\nS")
+    def path(outline)
+      raise ArgumentError, "path must not be empty" unless outline.is_a?(Path) && !outline.commands.empty?
+      raw(outline.commands.join("\n"))
+    end
+
+    def fill(color, rule: :nonzero)
+      raise ArgumentError, "fill rule must be nonzero or evenodd" unless %i[nonzero evenodd].include?(rule)
+      raw("#{rgb(color).join(' ')} rg\n#{rule == :evenodd ? 'f*' : 'f'}")
+    end
+
+    def stroke(color, width: 1, cap: :butt, join: :miter, miter: 10, dash: nil)
+      raise ArgumentError, "line cap must be butt, round, or square" unless %i[butt round square].include?(cap)
+      raise ArgumentError, "line join must be miter, round, or bevel" unless %i[miter round bevel].include?(join)
+      style = "#{rgb(color).join(' ')} RG\n#{positive(width, 'line width')} w\n#{ {butt: 0, round: 1, square: 2}.fetch(cap) } J\n#{ {miter: 0, round: 1, bevel: 2}.fetch(join) } j\n#{positive(miter, 'miter limit')} M"
+      if dash
+        raise ArgumentError, "dash must contain positive lengths" unless dash.is_a?(Array) && !dash.empty? && dash.all? { |value| value.is_a?(Numeric) && value.finite? && value.positive? }
+        style << "\n[#{dash.map { |value| PDF::Encoding.number(value) }.join(' ')}] 0 d"
+      else
+        style << "\n[] 0 d"
+      end
+      raw("#{style}\nS")
+    end
     def fill_and_stroke(color, width: 1) = raw("#{rgb(color).join(' ')} rg\n#{rgb(color).join(' ')} RG\n#{positive(width, 'line width')} w\nB")
 
     def clip
@@ -104,6 +133,22 @@ module Okab
       self
     end
 
+    def with_clip(path, rule: :nonzero)
+      raise ArgumentError, "clip requires a block" unless block_given?
+      raise ArgumentError, "clip path must not be empty" unless path.is_a?(Path) && !path.commands.empty?
+      raise ArgumentError, "clip rule must be nonzero or evenodd" unless %i[nonzero evenodd].include?(rule)
+      start = @operations.length
+      @operations << [:raw, "q\n#{path.commands.join("\n")}\n#{rule == :evenodd ? 'W*' : 'W'} n"]
+      begin
+        yield self
+      rescue StandardError
+        @operations.slice!(start..)
+        raise
+      end
+      @operations << [:raw, "Q"]
+      self
+    end
+
     def transform(a, b, c, d, e, f)
       raise ArgumentError, "transform requires a block" unless block_given?
       values = [a, b, c, d, e, f].map { |value| finite(value, 'transform') }

data/lib/okab/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Okab
-  VERSION = "0.1.0"
+  VERSION = "0.2.0"
 end

data/lib/okab/zaniah_vector.rb

@@ -0,0 +1,291 @@
+# frozen_string_literal: true
+
+require_relative "../okab"
+require "zaniah/vector"
+
+module Okab
+  # Optional bridge: each display-list item remains a PDF path, glyph, or image.
+  # Only effects without an equivalent PDF page operation are rasterized locally.
+  class ZaniahVector
+    KAPPA = 0.5522847498307936
+
+    def self.draw(page, vector_document) = new(page, vector_document).draw
+
+    def initialize(page, vector_document)
+      unless page.is_a?(Page) && vector_document.is_a?(::Zaniah::Vector::Document)
+        raise ArgumentError, "expected an Okab::Page and Zaniah::Vector::Document"
+      end
+      unless page.width == vector_document.width && page.height == vector_document.height
+        raise ArgumentError, "PDF page and vector document dimensions must match"
+      end
+      @page, @vector, @fonts = page, vector_document, {}.compare_by_identity
+    end
+
+    def draw
+      @vector.commands.each do |command|
+        clipped(command) do
+          transformed(command) { draw_command(command) }
+        end
+      end
+      @page
+    end
+
+    private
+
+    def clipped(command)
+      return yield unless command.clip
+      clip = command.clip
+      path = Path.new.rect(clip.x, @page.height - clip.bottom, clip.width, clip.height)
+      @page.with_clip(path) { yield }
+    end
+
+    def transformed(command)
+      transform = command.transform
+      return yield unless transform && transform != ::Zaniah::Transform.identity
+      a, b, c, d, tx, ty = transform.to_a
+      height = @page.height
+      @page.transform(a, -b, -c, d, c * height + tx, height * (1 - d) - ty) { yield }
+    end
+
+    def draw_command(command)
+      case command
+      when ::Zaniah::Vector::Quad then draw_quad(command)
+      when ::Zaniah::Vector::Path then draw_path(command)
+      when ::Zaniah::Vector::GlyphRun then draw_glyph_run(command)
+      when ::Zaniah::Vector::Image, ::Zaniah::Vector::Raster then draw_image(command)
+      when ::Zaniah::Vector::Underline then draw_underline(command)
+      when ::Zaniah::Vector::Shadow then draw_shadow(command)
+      else raise ArgumentError, "unsupported vector command #{command.class}"
+      end
+    end
+
+    def draw_quad(command)
+      bounds = command.bounds
+      return if bounds.width <= 0 || bounds.height <= 0
+      unless command.fill.is_a?(::Zaniah::Color)
+        return draw_raster_image(raster_quad(command), bounds, command.opacity)
+      end
+      widths, border_color = command.border
+      if command.border_style == :dashed && widths.uniq.length != 1
+        return draw_raster_image(raster_quad(command), bounds, command.opacity)
+      end
+      outer = rounded_rect(bounds, command.radii)
+      paint_fill(outer, command.fill, command.opacity)
+      return unless widths.any?(&:positive?) && border_color.a.positive?
+      if command.border_style == :dashed
+        inset = widths.first / 2.0
+        center = rounded_rect(inset_bounds(bounds, [inset] * 4), command.radii.map { |radius| [radius - inset, 0].max })
+        paint_stroke(center, border_color, widths.first, command.opacity, dash: [widths.first * 3, widths.first * 2])
+      else
+        inner = inset_bounds(bounds, widths)
+        if inner.width.positive? && inner.height.positive?
+          radii = command.radii.each_with_index.map do |radius, index|
+            adjacent = [[widths[0], widths[3]], [widths[0], widths[1]],
+              [widths[2], widths[1]], [widths[2], widths[3]]].fetch(index)
+            [radius - adjacent.max, 0].max
+          end
+          ring = Path.new
+          ring.commands.concat(outer.commands).concat(rounded_rect(inner, radii).commands)
+          paint_fill(ring, border_color, command.opacity, rule: :evenodd)
+        else
+          paint_fill(outer, border_color, command.opacity)
+        end
+      end
+    end
+
+    def draw_path(command)
+      path = outline_path(command.outline)
+      paint_fill(path, command.fill, command.opacity, rule: command.fill_rule) if command.fill
+      if command.stroke && command.stroke_width.positive?
+        paint_stroke(path, command.stroke, command.stroke_width, command.opacity,
+          cap: command.stroke_cap, join: command.stroke_join, miter: command.stroke_miter)
+      end
+    end
+
+    def draw_glyph_run(command)
+      font = (@fonts[command.font] ||= Font.new(command.font))
+      color = command.color
+      with_alpha(color.a * command.opacity) do
+        command.glyphs.zip(command.clusters).each do |(glyph, x, y), cluster|
+          unicode = command.text.byteslice(cluster[0]...cluster[1])
+          unicode = "\uFFFD" unless unicode&.valid_encoding? && !unicode.empty?
+          @page.glyph(glyph, x: x, y: @page.height - y, font: font,
+            size: command.size, unicode: unicode, color: rgb(color))
+        end
+      end
+    end
+
+    def draw_image(command)
+      image = pixel_image(command)
+      draw_raster_image(image, command.bounds, command.opacity)
+    end
+
+    def draw_underline(command)
+      if command.wave
+        bounds = ::Zaniah::Bounds.new(command.x, command.y - command.thickness,
+          command.width, command.thickness * 3)
+        scene = ::Zaniah::Scene.new
+        scene.underline(0, command.thickness, command.width, color: command.color,
+          thickness: command.thickness, wave: true)
+        draw_raster_image(raster_scene(scene, bounds), bounds, command.opacity)
+      else
+        bounds = ::Zaniah::Bounds.new(command.x, command.y, command.width, command.thickness)
+        paint_fill(rounded_rect(bounds, [0] * 4), command.color, command.opacity)
+      end
+    end
+
+    def draw_shadow(command)
+      bounds = command.bounds
+      margin = (command.blur * 3 + command.spread.abs + 2).ceil
+      local = ::Zaniah::Bounds.new(bounds.x - margin, bounds.y - margin,
+        bounds.width + margin * 2, bounds.height + margin * 2)
+      scene = ::Zaniah::Scene.new
+      scene.shadow(margin, margin, bounds.width, bounds.height, color: command.color,
+        blur: command.blur, spread: command.spread, radius: command.radii, inset: command.inset)
+      draw_raster_image(raster_scene(scene, local), local, command.opacity)
+    end
+
+    def raster_quad(command)
+      bounds = command.bounds
+      scene = ::Zaniah::Scene.new
+      scene.quad(0, 0, bounds.width, bounds.height, color: command.fill,
+        radius: command.radii, border_width: command.border.first,
+        border_color: command.border.last, border_style: command.border_style)
+      raster_scene(scene, ::Zaniah::Bounds.new(0, 0, bounds.width, bounds.height))
+    end
+
+    def raster_scene(scene, bounds)
+      width, height = [bounds.width.ceil, 1].max, [bounds.height.ceil, 1].max
+      rgba_image(::Zaniah::GPU::Software.new(width, height).render(scene, clear: "#0000"), width, height)
+    end
+
+    def draw_raster_image(image, bounds, opacity)
+      with_alpha(opacity) do
+        @page.image(image, x: bounds.x, y: @page.height - bounds.bottom,
+          width: bounds.width, height: bounds.height)
+      end
+    end
+
+    def pixel_image(command)
+      width, height = command.pixel_width, command.pixel_height
+      source = command.source || ::Zaniah::Bounds.new(0, 0, width, height)
+      tint = command.is_a?(::Zaniah::Vector::Raster) ? command.color : ::Zaniah::Color.new(1, 1, 1, 1)
+      if [source.x, source.y, source.width, source.height].all? { |value| value.is_a?(Integer) } &&
+          source.x >= 0 && source.y >= 0 && source.right <= width && source.bottom <= height
+        rgba = +"".b
+        channels = command.format == :r8 ? 1 : 4
+        source.height.times do |row|
+          offset = ((source.y + row) * width + source.x) * channels
+          slice = command.pixels.byteslice(offset, source.width * channels)
+          if channels == 1
+            slice.each_byte do |coverage|
+              rgba << [(tint.r * 255).round, (tint.g * 255).round, (tint.b * 255).round,
+                (coverage * tint.a).round].pack("C4")
+            end
+          else
+            slice.bytes.each_slice(4) do |red, green, blue, alpha|
+              rgba << [(red * tint.r).round, (green * tint.g).round,
+                (blue * tint.b).round, (alpha * tint.a).round].pack("C4")
+            end
+          end
+        end
+        rgba_image(rgba, source.width, source.height)
+      else
+        texture = ::Zaniah::GPU::Texture.new(width, height, format: command.format, data: command.pixels)
+        scene = ::Zaniah::Scene.new
+        scene.sprite(0, 0, command.bounds.width, command.bounds.height,
+          texture: texture, source: source, color: tint)
+        raster_scene(scene, ::Zaniah::Bounds.new(0, 0, command.bounds.width, command.bounds.height))
+      end
+    end
+
+    def rgba_image(pixels, width, height)
+      rgb, alpha = +"".b, +"".b
+      pixels.bytes.each_slice(4) do |red, green, blue, opacity|
+        rgb << [red, green, blue].pack("C3")
+        alpha << opacity.chr
+      end
+      Image.new(width: width, height: height, color_space: :rgb,
+        data: rgb, alpha: alpha.each_byte.all? { |value| value == 255 } ? nil : alpha)
+    end
+
+    def outline_path(outline)
+      path = Path.new
+      current = start = [0.0, 0.0]
+      outline.each do |operation, *values|
+        case operation
+        when :move_to
+          current = start = values
+          path.move_to(values[0], @page.height - values[1])
+        when :line_to
+          current = values
+          path.line_to(values[0], @page.height - values[1])
+        when :quad_to
+          cx, cy, x, y = values
+          x1 = current[0] + (cx - current[0]) * 2 / 3.0
+          y1 = current[1] + (cy - current[1]) * 2 / 3.0
+          x2 = x + (cx - x) * 2 / 3.0
+          y2 = y + (cy - y) * 2 / 3.0
+          path.curve_to(x1, @page.height - y1, x2, @page.height - y2, x, @page.height - y)
+          current = [x, y]
+        when :cubic_to
+          x1, y1, x2, y2, x, y = values
+          path.curve_to(x1, @page.height - y1, x2, @page.height - y2, x, @page.height - y)
+          current = [x, y]
+        when :close
+          path.close
+          current = start
+        else raise ArgumentError, "unsupported outline command #{operation}"
+        end
+      end
+      path
+    end
+
+    def rounded_rect(bounds, radii)
+      x, y, width, height = bounds.x, bounds.y, bounds.width, bounds.height
+      tl, tr, br, bl = radii.map { |radius| radius.clamp(0, [width, height].min / 2.0) }
+      path = Path.new
+      point = ->(px, py) { [px, @page.height - py] }
+      path.move_to(*point.call(x + tl, y))
+      path.line_to(*point.call(x + width - tr, y))
+      path.curve_to(*point.call(x + width - tr + KAPPA * tr, y),
+        *point.call(x + width, y + tr - KAPPA * tr), *point.call(x + width, y + tr)) if tr.positive?
+      path.line_to(*point.call(x + width, y + height - br))
+      path.curve_to(*point.call(x + width, y + height - br + KAPPA * br),
+        *point.call(x + width - br + KAPPA * br, y + height), *point.call(x + width - br, y + height)) if br.positive?
+      path.line_to(*point.call(x + bl, y + height))
+      path.curve_to(*point.call(x + bl - KAPPA * bl, y + height),
+        *point.call(x, y + height - bl + KAPPA * bl), *point.call(x, y + height - bl)) if bl.positive?
+      path.line_to(*point.call(x, y + tl))
+      path.curve_to(*point.call(x, y + tl - KAPPA * tl),
+        *point.call(x + tl - KAPPA * tl, y), *point.call(x + tl, y)) if tl.positive?
+      path.close
+    end
+
+    def inset_bounds(bounds, widths)
+      top, right, bottom, left = widths
+      ::Zaniah::Bounds.new(bounds.x + left, bounds.y + top,
+        bounds.width - left - right, bounds.height - top - bottom)
+    end
+
+    def paint_fill(path, color, opacity, rule: :nonzero)
+      return unless color.a.positive?
+      with_alpha(color.a * opacity) { @page.path(path).fill(rgb(color), rule: rule.to_sym) }
+    end
+
+    def paint_stroke(path, color, width, opacity, cap: :butt, join: :miter, miter: 10, dash: nil)
+      return unless color.a.positive?
+      with_alpha(color.a * opacity) do
+        @page.path(path).stroke(rgb(color), width: width, cap: cap || :butt,
+          join: join || :miter, miter: miter || 10, dash: dash)
+      end
+    end
+
+    def with_alpha(alpha)
+      return if alpha <= 0
+      alpha < 1 ? @page.opacity(alpha) { yield } : yield
+    end
+
+    def rgb(color) = [color.r, color.g, color.b]
+  end
+end

data/sig/okab.rbs

@@ -37,6 +37,7 @@ module Okab
     attr_reader document: Document
     def initialize: (Document document, width: Numeric, height: Numeric) -> void
     def text: (String string, x: Numeric, y: Numeric, font: Font | EmbeddedFont | Alhena::Font, size: Numeric, ?color: Array[Numeric], ?tracking: Numeric, ?bold: bool, ?italic: bool) -> self
+    def glyph: (Integer glyph_id, x: Numeric, y: Numeric, font: Font | Alhena::Font, size: Numeric, unicode: String, ?color: Array[Numeric]) -> self
     def text_block: (String string, x: Numeric, y: Numeric, width: Numeric, font: Font | EmbeddedFont | Alhena::Font, size: Numeric, line_height: Numeric, ?align: Symbol, ?color: Array[Numeric], ?tracking: Numeric) -> self
     def move_to: (Numeric x, Numeric y) -> self
     def line_to: (Numeric x, Numeric y) -> self
@@ -44,10 +45,12 @@ module Okab
     def close: () -> self
     def rect: (Numeric x, Numeric y, Numeric width, Numeric height) -> self
     def ellipse: (Numeric x, Numeric y, Numeric width, Numeric height) -> self
-    def fill: (Array[Numeric] color) -> self
-    def stroke: (Array[Numeric] color, ?width: Numeric) -> self
+    def path: (Path outline) -> self
+    def fill: (Array[Numeric] color, ?rule: :nonzero | :evenodd) -> self
+    def stroke: (Array[Numeric] color, ?width: Numeric, ?cap: :butt | :round | :square, ?join: :miter | :round | :bevel, ?miter: Numeric, ?dash: Array[Numeric]?) -> self
     def fill_and_stroke: (Array[Numeric] color, ?width: Numeric) -> self
     def clip: () { (Path) -> void } -> self
+    def with_clip: (Path path, ?rule: :nonzero | :evenodd) { (Page) -> void } -> self
     def transform: (Numeric a, Numeric b, Numeric c, Numeric d, Numeric e, Numeric f) { (Page) -> void } -> self
     def opacity: (Numeric value) { (Page) -> void } -> self
     def image: (String | Image data, x: Numeric, y: Numeric, width: Numeric, height: Numeric, ?format: Symbol) -> self
@@ -71,6 +74,7 @@ module Okab
     def face: () -> Alhena::Font
     def measure: (String text, size: Numeric) -> Float
     def encode: (String string) -> String
+    def encode_glyph: (Integer glyph, unicode: String) -> String
     def glyph_ids: () -> Array[Integer]
     def subset_font: () -> [String, Alhena::Font, Hash[Integer, Integer], bool]
     def characters: () -> Hash[Integer, [String, Integer]]
@@ -88,4 +92,8 @@ module Okab
     def self.decode: (String bytes, ?format: Symbol) -> Image
     def initialize: (width: Integer, height: Integer, color_space: Symbol, data: String, ?alpha: String?, ?filter: Symbol?, ?decode_parms: String?) -> void
   end
+
+  class ZaniahVector
+    def self.draw: (Page page, untyped vector_document) -> Page
+  end
 end

metadata

@@ -1,13 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: okab
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.2.0
 platform: ruby
 authors:
 - Yudai Takada
+autorequire:
 bindir: exe
 cert_chain: []
-date: 1980-01-02 00:00:00.000000000 Z
+date: 2026-09-24 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: alhena
@@ -55,6 +56,7 @@ files:
 - LICENSE.txt
 - README.md
 - Rakefile
+- docs/zaniah-vector.md
 - lib/okab.rb
 - lib/okab/document.rb
 - lib/okab/font.rb
@@ -62,6 +64,7 @@ files:
 - lib/okab/page.rb
 - lib/okab/pdf/writer.rb
 - lib/okab/version.rb
+- lib/okab/zaniah_vector.rb
 - sig/okab.rbs
 homepage: https://github.com/noxdea/okab
 licenses:
@@ -71,6 +74,7 @@ metadata:
   source_code_uri: https://github.com/noxdea/okab/tree/main
   changelog_uri: https://github.com/noxdea/okab/blob/main/CHANGELOG.md
   rubygems_mfa_required: 'true'
+post_install_message:
 rdoc_options: []
 require_paths:
 - lib
@@ -85,7 +89,8 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 4.0.16
+rubygems_version: 3.4.19
+signing_key:
 specification_version: 4
 summary: Generate searchable, font-embedded PDF documents
 test_files: []