zaniah 0.8.0 → 0.10.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 0e4185eb60f475f07fb3deee4bf07f0e7e16240771ee9199f9783d3fe13130cb
-  data.tar.gz: 05cafb090e57d8552cda0826d8db0ff1fa980107eab05ab9841824d6a18187c6
+  metadata.gz: bad32e7fbe4f1abe64589fbc41d73f242c4ed3aeee9f760c67a4d205d0c8d8d7
+  data.tar.gz: b57324bacd30eeea83d04407f689e9ca47d79178d1f0228acf5396fa2ea27881
 SHA512:
-  metadata.gz: e5da9a69b48d186dcb04cf71cf48922d9e72fd019ff54919451f028cc211262fd8c49ecf85eb6dbbfd8b48213ad324ab98aefc9079473ace7d8a289401079ae4
-  data.tar.gz: f2b7ada32c16d932143db6cf68a9c2073e085ef0cda762aa7ed2f07ae7fdee5b9d5b1f5c3a5289b5fc54930fab9dbef1c0720e8035656c8ac700a2904012f431
+  metadata.gz: 5bbf0bebdad77e095cb6faba2a614cf5129558dd10629c94f2e6ad9966f9cb50dfe32a37b551569cdcfb1ba74085d4c64a3667740ff1699fa7b8ce03c553ad4c
+  data.tar.gz: 9d2491ddb19ce68065497f484b9bba0aa4e026fa998a31e3bca3d7bd41f0ed6edd805f0096aefd28ce2b1acf9309f0b96785cbbce88d67ebea10526094060a2f

data/CHANGELOG.md

@@ -1,5 +1,19 @@
 # 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.
+- Render shadows analytically across backends; their edge appearance changes from earlier releases.
+- Add shared multi-stop and conic gradient ramps across Software, OpenGL, Metal, and Vulkan rendering.
+- Support SVG gradients, dashed strokes, and alpha and luminance masks.
+
 ## 0.8.0 — 2026-09-24
 
 - Add native macOS and Windows menus, declarative context menus, and platform-aware shortcut labels.

data/docs/adr/005-instance-layout.md

@@ -26,10 +26,10 @@ fields for source UVs. Triangle vertices reuse rect and radii fields.
 | 32–37 | affine transform (`a,b,c,d,tx,ty`) | affine transform |
 | 38–39 | reserved shadow spread / inset or border flags | unused |
 
-Opacity is multiplied into both fill and border alpha before packing. Linear
-and radial gradients use exactly two stops; a future multi-stop implementation
-may use a 1D texture without another stride change. Shadows are expanded into
-ordinary quad instances, so the reserved shadow fields remain available.
+Opacity is multiplied into both fill and border alpha before packing. The
+original two-stop and expanded-quad behavior has since been extended without
+changing this layout: see [ADR 017](017-analytic-shadows.md) for the shadow
+fields and [ADR 018](018-gradient-ramps.md) for multistop ramps and conic fills.
 
 Metal, OpenGL, and Vulkan consume the layout directly, Software consumes the
 equivalent 40-float quad layout, and cached text sprite batches use the same

data/docs/adr/016-semantic-vector-recording.md

@@ -0,0 +1,33 @@
+# ADR 016: Record semantic drawing alongside the GPU scene
+
+- Status: Proposed
+- Date: 2026-09-24
+
+## Context
+
+The GPU scene contains packed quads and atlas sprites. Paths have already been
+rasterized and text has lost its font, glyph IDs, and source clusters by the
+time a renderer consumes those commands. Exporters need this information to
+produce searchable text and scalable artwork. Reconstructing it from packed
+GPU instances is impossible; maintaining a second application-specific layout
+for export makes screen and export drift.
+
+Two viable boundaries were considered: make the GPU scene itself semantic, or
+keep its fast packed representation and optionally observe the drawing calls.
+
+## Decision
+
+Keep the GPU scene unchanged and attach an optional vector sink to `Scene`.
+Emit semantic commands before paths and text are flattened. When a source has
+no supported vector form, preserve its pixels as a raster command instead.
+The sink is absent by default, so normal frames do not allocate vector data.
+Page assembly and document formats remain outside Zaniah.
+
+## Consequences
+
+Exporters can reuse the same element tree and retain font and outline data
+without adding a dependency on a PDF library. The optional path incurs a
+nil check when unused and stores additional frame data when enabled. Raster
+fallbacks keep output complete but cannot scale as cleanly as true vectors.
+This choice should be revisited if packed GPU commands become a lossless
+semantic representation or a common display list can serve both consumers.

data/docs/adr/017-analytic-shadows.md

@@ -0,0 +1,31 @@
+# ADR 017: Draw each shadow as one analytic instance
+
+- Status: Accepted
+- Date: 2026-09-24
+
+## Context
+
+The previous shadow approximation layered eight rounded quads. It produced
+visible bands and made a scene with 100 shadows submit 800 instances.
+
+## Decision
+
+Keep the 40-float instance layout from ADR 005. Primitive kind `4` in field 31
+is a shadow; field 30 is blur sigma, field 38 is spread, and field 39 is the
+inset flag. Bounds 0–3 are expanded by `spread + 3 * blur + 1` for outer
+shadows. Inset shadows retain the original bounds. Corner radii occupy 12–15.
+
+Software and all three GPU fragment shaders evaluate the signed distance to
+the original rounded rectangle. A Gaussian edge is approximated by
+`0.5 - 0.5 * erf((distance - spread) / (sqrt(2) * blur))`, using the same bounded
+exponential approximation of `erf` in every backend. Zero blur uses direct
+coverage. Inset shadows multiply interior coverage by the inverted transition.
+The existing clipping, transforms, and alpha blending remain unchanged.
+
+## Consequences
+
+Shadow appearance intentionally changes; the golden images and changelog must
+record this. `bench/shadow.rb` compares 100 shadows against the old eight-quad
+approximation and requires the analytic Software path to be faster. GPU native
+capture tests remain platform-dependent; `script/compile_shaders` regenerates
+the bundled Vulkan SPIR-V from the checked-in GLSL.

data/docs/adr/018-gradient-ramps.md

@@ -0,0 +1,30 @@
+# ADR 018: Use bounded ramps for multistop gradients
+
+- Status: Accepted
+- Date: 2026-09-24
+
+## Context
+
+The shared instance format carries only two inline stop colors. Extending its
+stride would affect every renderer and text/sprite packing.
+
+## Decision
+
+Two-stop linear and radial gradients retain their inline color path. Two-stop
+conic gradients use kind `3` and the same interpolation path. Three or more
+stops use kinds `4` (linear), `5` (radial), or `6` (conic), and one row of a
+256-by-256 RGBA8 atlas baked from the ordered stops. Field 8 stores the row
+index; all renderers sample that row at the calculated gradient position. A
+`Scene` caches rows by immutable `Gradient` value in an LRU capped at 256
+entries. Rows used in the current frame cannot be evicted; if a frame exceeds
+256 distinct ramps, it uses reusable overflow atlases for the remainder of
+that frame. Normal quads continue to use packed-byte fast paths; only ramp
+quads need texture-aware batching.
+
+## Consequences
+
+No instance layout migration is required. Sampling precision is limited to
+256 positions. Adjacent ramps on the shared atlas batch together, while
+overflows can add batches. SVG gradient fills use the same ordered-stop
+interpolation semantics and fall back to a raster snapshot in vector recording
+because a `Vector::Path` currently stores solid fills only.

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/docs/vector.md

@@ -0,0 +1,60 @@
+# Vector recording
+
+Zaniah records the drawing it already performs without taking ownership of PDF
+pages, paper sizes, or export dialogs. Require `zaniah/vector` and render a normal
+element tree offscreen:
+
+```ruby
+document = Zaniah::Vector.record(width: 960, height: 540,
+  theme: Zaniah::Theme.light) { slide }
+document.commands.each { |command| export_command(command) }
+```
+
+To inspect a displayed frame, attach a recorder before rendering. `Scene#clear`
+resets its commands each frame; save `recorder.document` before the next frame.
+
+```ruby
+recorder = Zaniah::Vector::Recorder.new
+window.scene.vector_sink = recorder
+window.tick
+document = recorder.document
+window.scene.vector_sink = nil
+```
+
+`Document#width` and `#height` are logical pixels. A `Recorder` attached to a
+window receives that window's content size; a recorder attached to a bare
+`Scene` may instead be initialized with `width:` and `height:`. Coordinates use
+a top-left origin and downward y axis; colors are sRGB. Every command carries
+its transform, clip, opacity, layer, and sequence. `Document#commands` is sorted
+by layer and then sequence, matching `Scene#each_command`.
+
+| Command | Export information |
+|---|---|
+| `Quad` | Bounds, fill color or gradient, corner radii, border widths/color/style |
+| `Shadow` | Bounds, corner radii, color, blur, spread, inset |
+| `Path` | Alhena outline, fill, stroke, stroke width, fill rule and stroke cap/join |
+| `GlyphRun` | Alhena font, size, `[glyph_id, x, baseline_y]` triples, original text and UTF-8 byte clusters |
+| `Image` | Decoded `Zaniah::Image`, bounds and source rectangle, plus a frozen pixel snapshot |
+| `Underline` | Position, thickness and wave flag |
+| `Raster` | Frozen source texture bytes, pixel dimensions/format, tint and source rectangle |
+
+Ordinary sprites and packed sprite batches become `Raster`; bitmap-color text
+uses that fallback for the whole line. Simple SVG fills and strokes become
+`Path` commands. SVG clipping, gradients, dash arrays, masks, group opacity,
+and references use a `Raster`
+fallback, so they are not silently omitted. The `Raster` bytes are a snapshot
+at recording time, even if the source texture changes later. The converter must
+crop to `source`, apply `color` and `opacity`, then respect `transform` and
+`clip`. It may rasterize a `Path` or `GlyphRun` when its output format lacks
+an equivalent vector primitive.
+
+The headless offscreen API works on every OS and does not require a GPU.
+Attaching a recorder to macOS, Windows, X11, or Wayland uses the same `Scene`
+path. The TUI backend captures its terminal cells as a single `Raster` fallback
+at an 8-by-20 cell grid, using a bundled font approximation; terminal font
+appearance is outside Zaniah's control. Use the offscreen API when scalable
+text is required.
+
+See [ADR 016](adr/016-semantic-vector-recording.md) for why this is separate
+from the GPU command stream. [Vector and list](vector_and_list.md) documents
+the SVG input subset.

data/docs/vector_and_list.md

@@ -13,15 +13,24 @@ icon = Zaniah::SVG.parse(
 ```
 
 The renderer supports SVG paths, basic shapes, groups, transforms, view boxes,
-inherited fill and stroke, `currentColor`, opacity, local `defs`/`use`, and
-user-space clip paths. It is intended for static icons, not arbitrary web SVG.
+inherited fill and stroke, `currentColor`, opacity, local `defs`/`use`,
+user-space clip paths, linear/radial gradients, stroke dash arrays and offsets,
+and local alpha/luminance masks. It is intended for static icons, not arbitrary
+web SVG.
 
-Scripts, external references, CSS stylesheets, gradients, filters, masks, images,
-text, markers, dash arrays, nested viewports, and object-bounding-box clips are
+Scripts, external references, CSS stylesheets, filters, images,
+text, markers, nested viewports, and object-bounding-box clips are
 unsupported and raise `ArgumentError`. Input is bounded to 2 MiB, 10,000 XML
 nodes, 64 levels, and 100,000 path operations; each output texture is limited to
 one megapixel.
 
+SVG gradients support ordered stops, local references, `objectBoundingBox` and
+`userSpaceOnUse` coordinates, and the default pad spread. Other spread methods
+and external references remain unsupported. Masks rasterize within the same
+one-megapixel output limit. Gradient, dashed, and masked shapes are represented
+as a `Vector::Raster` fallback when recording; simple solid outlines remain
+`Vector::Path` commands.
+
 ## Variable-height lists
 
 ```ruby

data/examples/metal_effect_check.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+require_relative "../lib/zaniah"
+abort "This check needs macOS and a graphical login" unless RUBY_PLATFORM.include?("darwin")
+
+window = Zaniah::Platform.open_window(backend: :mac, gpu: :metal, width: 96, height: 72,
+  title: "Metal effect check")
+begin
+  scene = Zaniah::Scene.new
+  scene.quad(4, 4, 30, 24, color: Zaniah::Gradient.linear(angle: 0,
+    stops: [[0, "#f00"], [0.5, "#0f0"], [1, "#00f"]]))
+  scene.quad(38, 4, 30, 24, color: Zaniah::Gradient.conic(stops: [[0, "#f00"], [1, "#00f"]]))
+  scene.shadow(28, 40, 32, 18, color: "#000", blur: 3, spread: 1, radius: 4)
+  expected = Zaniah::GPU::Software.new(96, 72).render(scene, clear: "#fff")
+  window.device.render(scene, clear: "#fff")
+  actual = window.device.pixels
+  scale = window.scale_factor
+  pixel_width = (96 * scale).round
+  samples = [[6, 15], [18, 15], [31, 15], [60, 16], [22, 49], [28, 49], [44, 49], [75, 49]]
+  samples.each do |x, y|
+    index = (y * 96 + x) * 4
+    native_index = (((y + 0.5) * scale).floor * pixel_width + ((x + 0.5) * scale).floor) * 4
+    left, right = expected.byteslice(index, 4).bytes, actual.byteslice(native_index, 4).bytes
+    raise "effect mismatch at #{x},#{y}: #{right.inspect} != #{left.inspect}" unless
+      left.zip(right).all? { |a, b| (a - b).abs <= 8 }
+  end
+  puts "Metal analytic shadow and gradient check: #{samples.length} samples passed"
+ensure
+  window.close
+end

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/gpu/instance_packing.rb

@@ -17,6 +17,7 @@ module Zaniah
           case kind
           when :quad
             q, i = scene.quads, offset
+            texture = scene.quad_texture(offset)
             data.push(q[i], q[i+1], q[i+2], q[i+3], q[i+4], q[i+5], q[i+6], q[i+7],
               q[i+8], q[i+9], q[i+10], q[i+11], q[i+12], q[i+13], q[i+14], q[i+15],
               q[i+16], q[i+17], q[i+18], q[i+19], q[i+20], q[i+21], q[i+22], q[i+23],
@@ -64,6 +65,7 @@ module Zaniah
         expected = 0
         scene.each_command do |kind, offset, clip|
           return unless kind == :quad && offset == expected
+          return if scene.quad_texture(offset)
           if batches.empty? || batches.last[0][2] != clip
             batches << [[:quad, nil, clip], expected / STRIDE, 1]
           else