zaniah 0.7.0 → 0.9.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 74d3240032d7ae845a8a1f8f3208cb102ef0b68637cc184ba0f8860ac57b05ee
-  data.tar.gz: 4166002c76247745610218aed5d9090459889b9b383b97b669b199adac46761b
+  metadata.gz: cc06ae1720a8d05abbc0da78849a355f7c36565c62b3907f941c80dd066594c5
+  data.tar.gz: fd00f6d9bd08c097a5ffa35ce079a83f949c07874d6ff7c76cdc802f7ddd8129
 SHA512:
-  metadata.gz: d3e80aba0a90f7e946ce916e63e3eed342cac2b1c0eda9cb9dd14112f1c1a9affd4d0ee13bc2cfc81769bcbd12afa4288849825fe1a093396b6ee43893f68a7d
-  data.tar.gz: a1bd580a3da60ac7705f4329d7f7a4b435bdd85638e074710a84b2339a40744e5b1e82d7df243ac9eff439a29ca359e6737e7fa731cb86b6dbedd62b585e5db3
+  metadata.gz: 769bfa73b348d773f2139eb34039a7250f6878986375bdd25c361c3922b16d61ab68a3d14c59f8ef7f3cfd68e04a43d868286b624d1996d2fc2afdb92b23f861
+  data.tar.gz: a9642fa580bd9595e15c48903e698b95dfc5a6f876ca0d71438e488899522e2855351cef18a124e005dae5636e53b500aa46e90e101575c12796fc4e9ae80992

data/CHANGELOG.md

@@ -1,5 +1,19 @@
 # Changelog
 
+## 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.
+- Add MIME-keyed clipboard content on desktop backends, including HTML, PNG, file URLs, and X11 incremental transfers.
+- Add Grid and Table copy/paste hooks with TSV and HTML data.
+- Add window state persistence, frameless windows, and draggable title regions across native backends.
+
 ## 0.7.0 — 2026-09-24
 
 - Add a stable frame inspection API with accessibility queries and DevTools integration.

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/015-mime-clipboard-types.md

@@ -0,0 +1,25 @@
+# ADR 015: Use MIME names for clipboard representations
+
+- Status: Proposed
+- Date: 2026-09-24
+
+## Context
+
+Applications need to place text, HTML, images, and private formats on the
+clipboard at the same time. Each operating system names these formats
+differently. Exposing those native names would make application copy/paste
+logic platform-specific; using a closed enum would exclude private formats.
+
+## Decision
+
+Use MIME strings as the public representation keys. Platform adapters map
+common MIME names to native formats and preserve other names where the system
+allows it. Items contain eagerly supplied, immutable data. The toolkit owns
+transport and format negotiation, not conversion of application data.
+
+## Consequences
+
+Applications can offer multiple formats through one API without depending on
+an OS adapter. Adapters must maintain the native mappings and account for
+platform-specific limits. Lazy data providers may be added later if eager
+copies become a measured problem.

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/components.md

@@ -31,6 +31,7 @@ Zaniah::UI::Button.variants[:variant][:brand] = ->(theme) {
 | L0 | `Spacer` | `(size = nil)` | fixed or flexible | none |
 | L0 | `Card` | `(*children)`, `child` | theme surface | group |
 | L0 | `Badge` | `(text, variant:)` | neutral/accent/success/warning/danger | text |
+| L0 | `Kbd` | `(keys, platform:)`; `.for(action, keymap:)` | OS shortcut notation, including multi-stroke bindings | text |
 | L0 | `Avatar` | `(name, image:, size:)` | initials or PNG | image |
 | L0 | `Skeleton` | `(width:, height:)` | pulsing loading placeholder | progressbar/busy |
 | L0 | `EmptyState` | `(title, message:, icon:, action:)` | compositional | group |
@@ -50,7 +51,7 @@ Zaniah::UI::Button.variants[:variant][:brand] = ->(theme) {
 | L2 | `Tooltip` | `(text, anchor:, side:, open:)` | top/bottom/left/right | tooltip |
 | L2 | `Popover` | `(content, anchor:, side:, width:, height:, open:, modal:)` | flipped and viewport-clamped | group |
 | L2 | `ContextMenu`, `Menu` | `(items, anchor:, open:)` | pointer + arrows/Home/End/Enter/Esc | menu/menuitem |
-| L2 | `MenuBar` | `(menus)` | compositional | menubar |
+| L2 | `MenuBar` | `(menus)` or `.from(app.menu_bar)` | declarative menu model or legacy pairs | menubar |
 | L2 | `Dropdown` | `(label, items:, value:)`; `on_change` | menu-backed | button |
 | L2 | `TextField` | `(value, placeholder:, label:, prefix:, suffix:, error:, max_length:, clearable:)` | IME, selection, counter | textbox |
 | L2 | `TextArea` | TextField plus `rows:` | multiline/wrapped | textbox/multiline |
@@ -83,8 +84,8 @@ Zaniah::UI::Button.variants[:variant][:brand] = ->(theme) {
 | L3 | `Resizable` | `(content, width:, height:, min_width:, min_height:, max_width:, max_height:)`; `on_resize` | drag or keyboard resize | group/separator |
 | L3 | `DockPanel` | `(center:, top:, right:, bottom:, left:)` | five-region layout | group |
 | L3 | `ListView` | `(items, height:, row_height:, selected:)`; `on_select` | virtual rows and keyboard selection | list/listitem |
-| L4 | `Table`, `DataGrid` | `(rows, columns:, height:, selection:, row_key:)`; `on_sort`, `on_select`, `on_edit` | virtual rows, sorting, resizing, editing | table/row/cell |
-| L4 | `Grid` | `(rows:, columns:, row_height:, column_width:, frozen_rows:, frozen_columns:)`; `scroll_to`, range `selection`, `on_select`, `on_edit`, `on_fill`, `on_resize` | two-axis virtualization, frozen panes, visible-cell resize/fill callbacks | table |
+| L4 | `Table`, `DataGrid` | `(rows, columns:, height:, selection:, row_key:)`; `on_sort`, `on_select`, `on_edit`, `on_copy`, `on_paste` | virtual rows, sorting, resizing, editing, typed clipboard hooks | table/row/cell |
+| L4 | `Grid` | `(rows:, columns:, row_height:, column_width:, frozen_rows:, frozen_columns:)`; `scroll_to`, range `selection`, `on_select`, `on_edit`, `on_fill`, `on_resize`, `on_copy`, `on_paste` | two-axis virtualization, frozen panes, visible-cell resize/fill and typed clipboard hooks | table |
 | L4 | `TreeView` | `(items, height:, selected:)`; `expand`, `collapse`, `replace`, `replace_children`, `invalidate`, lazy `children` proc | arrows/Home/End | tree/treeitem |
 | L5 | `Sparkline` | `(values, width:, height:, color:, label:)` | line + tooltip | image |
 | L5 | `LineChart`, `BarChart`, `StackedBarChart`, `AreaChart` | `(series, width:, height:, colors:, label:)`; `AreaChart(stacked:)` | shared axes, ticks, grid lines, color-keyed legend, tooltip | image |
@@ -106,8 +107,8 @@ input order. Pass `matcher:` to either component, or set a default with
 `match(query, labels)` and returns `UI::Matcher::Match` values with an original
 label `index`, descending `score`, and half-open UTF-8 byte `ranges` for highlighting.
 It may also implement `refine(previous_matches, query)` for incremental queries.
-`CommandPalette.from(app.actions)` uses registered action titles and disables
-unavailable actions; shortcuts will be added with `UI::Kbd` in the menu phase.
+`CommandPalette.from(app.actions)` uses registered action titles, disables
+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,
@@ -143,7 +144,9 @@ viewport.
 In a table, Up/Down/Home/End/Page keys move and select rows, Shift+Up/Down extends
 a range, and Cmd/Ctrl+A selects every row in multiple-selection mode. Sortable
 headers and resize handles are separate Tab stops; Enter sorts and arrow/Page keys
-resize. Tree views use Up/Down to select, Right to expand or enter the first child,
+resize. Grid and Table clipboard hooks receive half-open `Grid::Area` ranges;
+Table areas follow the current display order without changing its stable-ID
+selection. See [Layout](layout.md#two-axis-virtual-grid). Tree views use Up/Down to select, Right to expand or enter the first child,
 and Left to collapse or return to the parent.
 
 Run `bundle exec ruby tools/generate_component_gallery.rb` to rebuild the dark,

data/docs/layout.md

@@ -75,6 +75,27 @@ apply a validated batch with a single frame request; `row_hidden?` and
 destination areas; the application owns cell values and fill semantics. Shift
 extends a range; Cmd/Ctrl-click toggles an additional cell range.
 
+Copy and paste are opt-in: the grid never owns cell values. `on_copy` receives
+the selected `Grid::Area` values and returns MIME-keyed content, which Zaniah
+writes to the clipboard. `on_paste` receives the same half-open areas and all
+available clipboard formats; the application decides how to apply them.
+Without the corresponding hook, the action is unhandled. With a hook but no
+selection, the action is disabled.
+
+```ruby
+grid.on_copy do |areas, _cx|
+  {"text/plain" => cells_as_tsv(areas), "text/html" => cells_as_html(areas)}
+end
+grid.on_paste do |areas, content, _cx|
+  paste_cells(areas, content.fetch("text/plain")) if content.types.include?("text/plain")
+end
+```
+
+`UI::Table` and `UI::DataGrid` use the same hooks. Their existing `selection`
+remains a set of stable row IDs; hook arguments are `Grid::Area` ranges in the
+current sorted display order, covering all columns. Disjoint selected rows
+produce separate areas. The application retains ownership of table data.
+
 `bench/grid.rb` measures a headless 800×600 viewport over a 1,000,000×16,000
 grid at 23 sequential scroll positions, including cell construction, layout,
 prepaint, and paint. `BUDGET=1 ruby bench/grid.rb` asserts a 16.67 ms median

data/docs/menus.md

@@ -0,0 +1,64 @@
+# Menus and shortcuts
+
+`Zaniah::Menu` describes commands; the application owns what each command does.
+Register actions once and attach a menu model to the app:
+
+```ruby
+app.actions.register(:save, title: "Save") { |cx| save_document(cx) }
+app.menu_bar = Zaniah::Menu.build do
+  app_menu
+  submenu "File" do
+    item :save
+    separator
+    submenu "Recent", items: -> { recent_items }
+  end
+  submenu "Edit" do
+    standard_edit_items
+  end
+  window_menu
+end
+```
+
+`recent_items` must return a `Zaniah::Menu` or an array of `Menu::Item` values.
+The callback runs when that submenu opens, not when the menu bar is drawn.
+`app_menu` and `window_menu` are macOS-only placeholders. They are omitted on
+other platforms. A missing item title comes from `app.actions`; a missing
+shortcut comes from the most recent keymap binding valid in an empty context.
+Context-only bindings are not shown. Multi-stroke shortcuts appear in window
+menus and `UI::Kbd`, but native menus show only single strokes.
+
+For Linux, headless, and TUI, place `Zaniah::UI::MenuBar.from(app.menu_bar)` in
+the application layout. Zaniah never inserts it automatically. Menu commands
+use `dispatcher.perform(action, source: :menu)` and are enabled or checked by
+`available?` and `checked?` when a menu opens. The in-window menu exposes a
+Back row for nested submenus and restores the previously focused control so
+standard editing commands target that control. `Inspection.snapshot(window).overlays.menu`
+returns the app's current model. Existing `UI::MenuBar.new([[label, items]])`
+and `UI::Menu.new([[label, callback]])` forms remain valid.
+
+`UI::Kbd.new("cmd-shift-p", platform: :mac)` displays `⌘⇧P`; on Windows or
+Linux it displays `Super+Shift+P`. `UI::Kbd.for(:save, keymap: keymap)` uses
+the same binding as the menu. Its TUI text always uses readable names such as
+`Ctrl+Shift+P`.
+
+Windows attaches a native menu to each window. It refreshes enabled and checked
+states when a menu opens and evaluates dynamic submenus at that time. Single-key
+shortcuts appear after a tab in item labels; key input still runs only through
+the Zaniah keymap, not a Win32 accelerator table. The menu model remains
+available for inspection and in-window display on all backends; headless has
+no system menu.
+
+On macOS, `App#menu_bar` becomes the system main menu. The app menu uses native
+About, Hide, Show All, and Quit items; `window_menu` uses the native Window menu.
+Dynamic submenu callbacks run when that submenu opens. Enabled and checked
+states are refreshed from the active window's dispatcher. Native shortcuts
+display single-stroke keymap bindings and route key events through the keymap
+before AppKit can run a matching menu item. A missing menu model keeps the
+original Quit-only menu. Run `ruby examples/native_menu.rb` in a macOS graphical
+session to inspect the native behavior.
+
+`element.context_menu(Zaniah::Menu.build { item :save })` accepts the same
+command model as the menu bar, including separators, nested submenus, dynamic
+items, and current enabled/checked state. macOS and Windows use native context
+menus for this model; headless, TUI, and `UI::ContextMenu` use the in-window
+menu. The older `[["Save", -> { save }]]` form remains supported.

data/docs/native.md

@@ -42,6 +42,54 @@ file drops, fullscreen, cursors, URL opening, file dialogs, appearance changes,
 and PNG capture. Platform availability differs; see [the RBS declarations](../sig/native.rbs)
 and [platform declarations](../sig/platform.rbs) for the exact API.
 
+## Clipboard representations
+
+`Clipboard::Item` holds eager MIME-keyed data. `text/*` values are UTF-8 text;
+other values are bytes. The window's `clipboard` and `clipboard=` methods remain
+shortcuts for `text/plain`.
+
+```ruby
+item = Zaniah::Clipboard::Item.new(
+  "text/plain" => "a\tb",
+  "text/html" => "<b>a</b>",
+  "image/png" => png_bytes
+)
+window.write_clipboard([item])
+window.clipboard_types                   # available MIME names, without reading data
+content = window.read_clipboard(types: ["text/html", "text/plain"])
+content.types                            # formats found, in requested order
+content.fetch("text/html")
+```
+
+Headless keeps representations in per-window memory. TUI also keeps every
+representation in memory and sends only `text/plain` writes to the terminal
+with OSC 52; it cannot read the terminal's clipboard. Native macOS, Windows,
+X11, and Wayland exchange `text/plain`, `text/html`, and `image/png` with other
+applications. macOS also preserves arbitrary MIME types under reversible
+`com.noxdea.zaniah.mime.<hex>` pasteboard identifiers; Windows, X11, and
+Wayland use their native format mechanisms. Native clipboard exchange still
+depends on a running desktop session and should be checked on each target OS.
+
+## Window state and decorations
+
+`window.frame` uses logical screen coordinates; `window.state.to_h` can be saved
+by the application and passed back to `window.restore_state`. Missing displays
+and offscreen frames are corrected toward the primary display. `maximize`,
+`minimize`, `restore`, `fullscreen?`, `always_on_top=`, and `on_state_change`
+operate on the native window where supported. `decorations: :native` is the
+default; `:hidden_titlebar` and `:none` enable a custom titlebar built from
+`window_drag_region` and `window_control` elements. `min_size:`, `resizable:`,
+and macOS-only `traffic_lights:` are creation options.
+
+X11 window managers must support EWMH for state and drag requests. On X11,
+`:hidden_titlebar` has the same no-decoration effect as `:none` through Motif
+hints. Wayland does not expose a window position: its frame origin is `nil`
+and setting a position raises. Wayland also cannot request always-on-top or
+programmatically restore a minimized window; those operations raise rather
+than claim success. Client-side decorations on Wayland depend on the compositor
+and its decoration protocol. Verify native placement and drag behavior on each
+target desktop before relying on it.
+
 ## Displays, file watching, and terminals
 
 `Zaniah::Platform.displays` returns the available displays for a backend.
@@ -73,6 +121,7 @@ ruby examples/native_smoke.rb --gl --check /tmp/zaniah-gl.png
 ruby examples/linux_smoke.rb
 ruby examples/linux_smoke.rb --wayland
 ruby examples/native_watch.rb
+ruby examples/native_menu.rb              # macOS only
 ```
 
 Linux XIM composition is exercised in CI with Xvfb and IBus/KKC. Native input,

data/docs/tui.md

@@ -7,6 +7,7 @@ tests and non-window integrations.
 | Component family | Terminal representation |
 | --- | --- |
 | Label, Badge, Avatar | text, `[badge]`, `(initials)` |
+| Kbd | textual shortcut, such as `Ctrl+Shift+P`; multiple strokes are space-separated |
 | Icon | Unicode check/close/search/menu/info/warning symbol; unlabeled unknown icons are omitted |
 | Divider, Card | `─`/`│` and box-drawing characters |
 | Skeleton, Spinner, ProgressBar, Meter | shade cells, `◌`, or a ten-cell progress track; animation jumps to its terminal state |
@@ -16,7 +17,7 @@ tests and non-window integrations.
 | Text inputs | `[value]`; password values are masked and validation errors have `!` |
 | Select, Combobox, MultiSelect | labeled brackets, filtered menu marker, or comma-separated selected values |
 | DatePicker, TimePicker, ColorPicker | labeled ISO date, 24-hour time, or hex color in brackets |
-| Tooltip, Popover, Menu, Dropdown | status text or a box/menu with `>` selection marker |
+| Tooltip, Popover, Menu, MenuBar, Dropdown | status text or a box/menu with `>` selection marker; nested menus expose a Back row |
 | Tabs, Accordion, Collapsible | selected tab in brackets and `[+]`/`[-]` disclosure markers |
 | ScrollView, Scrollbar | clipped child content and `│`/`─` track |
 | Breadcrumb, Pagination, bars | slash-separated path, page status, space-separated content |

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/gallery.rb

@@ -22,6 +22,7 @@ module Gallery
       .child(Zaniah::Div.new.flex_row.items_center.gap(12).children([
         Zaniah::UI::Label.new("Label"), Zaniah::UI::Icon.new(:info, label: "Information"),
         Zaniah::UI::Badge.new("New", variant: :accent), Zaniah::UI::Avatar.new("Ruby UI"),
+        Zaniah::UI::Kbd.new("ctrl-shift-p", platform: :windows),
         Zaniah::UI::Spacer.new(4), Zaniah::UI::Skeleton.new]))
       .child(Zaniah::UI::Divider.new)
       .child(Zaniah::UI::EmptyState.new("No results", message: "Try another query").h(64))

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_menu.rb

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+# Run on macOS with a graphical session. Check File, Edit, Window, Cmd+S,
+# disabled and checked items, and the Recent submenu after opening it twice.
+$LOAD_PATH.unshift(File.expand_path("../lib", __dir__))
+require "zaniah/ui"
+
+raise "native_menu.rb requires macOS" unless RUBY_PLATFORM.include?("darwin")
+
+app = Zaniah::App.new
+count = 0
+enabled = true
+checked = false
+window = nil
+app.actions.register(:save, title: "Save", enabled: ->(_cx) { enabled }) do |_cx|
+  count += 1
+  puts "Save invoked #{count} time(s)"
+  window.request_frame
+end
+app.actions.register(:toggle, title: "Checked item", checked: ->(_cx) { checked }) do |_cx|
+  checked = !checked
+  window.request_frame
+end
+app.actions.register(:enable_save, title: "Enable Save") do |_cx|
+  enabled = !enabled
+  puts "Save enabled: #{enabled}"
+end
+app.menu_bar = Zaniah::Menu.build do
+  app_menu
+  submenu "File" do
+    item :save
+    item :enable_save
+    separator
+    submenu "Recent", items: -> { Zaniah::Menu.build { item :save, title: "Example.txt" }.items }
+  end
+  submenu "Edit" do
+    standard_edit_items
+    separator
+    item :toggle
+  end
+  window_menu
+end
+window = app.open_window(backend: :mac, width: 500, height: 180, title: "Zaniah native menu") do
+  Zaniah::Div.new.p(24).child(Zaniah::UI::Label.new("Open File/Edit/Window; press Cmd+S. Saves: #{count}"))
+end
+window.dispatcher.keymap.bind("cmd-s", :save)
+if ARGV.include?("--check")
+  window.tick
+  cocoa = Zaniah::Platform::Mac::O
+  menu = cocoa.send(Zaniah::Platform::Mac::App.instance.handle, "mainMenu")
+  count = cocoa.send(menu, "numberOfItems", result: :long)
+  raise "native main menu was not installed (#{count} items)" unless count == 4
+  app.menu_bar = nil
+  window.tick
+  fallback = cocoa.send(Zaniah::Platform::Mac::App.instance.handle, "mainMenu")
+  raise "Quit-only menu was not restored" unless cocoa.send(fallback, "numberOfItems", result: :long) == 1
+  puts "Native menu installed"
+  window.close
+else
+  app.run
+end

data/lib/zaniah/app.rb

@@ -7,7 +7,7 @@ require_relative "task_executor"
 
 module Zaniah
   class App
-    attr_reader :windows, :executor, :actions
+    attr_reader :windows, :executor, :actions, :menu_bar
 
     def initialize(clock: MONOTONIC_CLOCK)
       @slots, @generations, @free, @windows, @globals = [], [], [], [], {theme: Theme.dark}
@@ -131,6 +131,13 @@ module Zaniah
       @executor.shutdown
     end
 
+    def menu_bar=(menu)
+      raise ArgumentError, "menu_bar must be a Zaniah::Menu or nil" unless menu.nil? || menu.is_a?(Menu)
+      @menu_bar = menu
+      @windows.each(&:request_frame)
+      menu
+    end
+
     def hot_reload(paths, **options, &block)
       require_relative "devtools"
       reload = DevTools::HotReload.new(self, paths, **options, &block)