ratatui_ruby 0.10.1 → 0.10.2

data/ext/ratatui_ruby/src/widgets/layout.rs

@@ -5,11 +5,11 @@ use crate::errors::type_error_with_context;
 use crate::rendering::render_node;
 use magnus::{prelude::*, Error, Symbol, Value};
 use ratatui::{
+    buffer::Buffer,
     layout::{Constraint, Direction, Flex, Layout, Rect},
-    Frame,
 };
 
-pub fn render(frame: &mut Frame, area: Rect, node: Value) -> Result<(), Error> {
+pub fn render(buffer: &mut Buffer, area: Rect, node: Value) -> Result<(), Error> {
     let ruby = magnus::Ruby::get().unwrap();
     let direction_sym: Symbol = node.funcall("direction", ())?;
     let children_val: Value = node.funcall("children", ())?;
@@ -72,7 +72,7 @@ pub fn render(frame: &mut Frame, area: Rect, node: Value) -> Result<(), Error> {
             let index = isize::try_from(i)
                 .map_err(|e| Error::new(ruby.exception_range_error(), e.to_string()))?;
             let child: Value = children_array.entry(index)?;
-            if let Err(e) = render_node(frame, chunks[i], child) {
+            if let Err(e) = render_node(buffer, chunks[i], child) {
                 eprintln!("Error rendering child {i}: {e:?}");
             }
         }

data/ext/ratatui_ruby/src/widgets/line_gauge.rs

@@ -5,9 +5,10 @@ use crate::style::{parse_block, parse_style};
 use crate::text::parse_span;
 use bumpalo::Bump;
 use magnus::{prelude::*, Error, Value};
-use ratatui::{layout::Rect, widgets::LineGauge, Frame};
+use ratatui::buffer::Buffer;
+use ratatui::{layout::Rect, widgets::LineGauge, widgets::Widget};
 
-pub fn render(frame: &mut Frame, area: Rect, node: Value) -> Result<(), Error> {
+pub fn render(buffer: &mut Buffer, area: Rect, node: Value) -> Result<(), Error> {
     let bump = Bump::new();
     let ratio: f64 = node.funcall("ratio", ())?;
     let label_val: Value = node.funcall("label", ())?;
@@ -52,7 +53,7 @@ pub fn render(frame: &mut Frame, area: Rect, node: Value) -> Result<(), Error> {
         gauge = gauge.block(parse_block(block_val, &bump)?);
     }
 
-    frame.render_widget(gauge, area);
+    gauge.render(area, buffer);
     Ok(())
 }
 

data/ext/ratatui_ruby/src/widgets/list.rs

@@ -7,14 +7,14 @@ use crate::text::{parse_line, parse_span};
 use crate::widgets::list_state::RubyListState;
 use bumpalo::Bump;
 use magnus::{prelude::*, Error, Symbol, TryConvert, Value};
+use ratatui::buffer::Buffer;
 use ratatui::{
     layout::Rect,
     text::Line,
-    widgets::{HighlightSpacing, List, ListItem, ListState},
-    Frame,
+    widgets::{HighlightSpacing, List, ListItem, ListState, StatefulWidget},
 };
 
-pub fn render(frame: &mut Frame, area: Rect, node: Value) -> Result<(), Error> {
+pub fn render(buffer: &mut Buffer, area: Rect, node: Value) -> Result<(), Error> {
     let bump = Bump::new();
     let ruby = magnus::Ruby::get().unwrap();
     let items_val: Value = node.funcall("items", ())?;
@@ -107,7 +107,7 @@ pub fn render(frame: &mut Frame, area: Rect, node: Value) -> Result<(), Error> {
         list = list.block(parse_block(block_val, &bump)?);
     }
 
-    frame.render_stateful_widget(list, area, &mut state);
+    StatefulWidget::render(list, area, buffer, &mut state);
     Ok(())
 }
 
@@ -116,7 +116,7 @@ pub fn render(frame: &mut Frame, area: Rect, node: Value) -> Result<(), Error> {
 /// This function ignores `selected_index` and `offset` from the widget.
 /// The State object is the single source of truth for selection and scroll position.
 pub fn render_stateful(
-    frame: &mut Frame,
+    buffer: &mut Buffer,
     area: Rect,
     node: Value,
     state_wrapper: Value,
@@ -210,7 +210,7 @@ pub fn render_stateful(
     // Borrow the inner ListState, render, and release the borrow immediately
     {
         let mut inner_state = state.borrow_mut();
-        frame.render_stateful_widget(list, area, &mut inner_state);
+        StatefulWidget::render(list, area, buffer, &mut inner_state);
     }
     // Borrow is now released
 
@@ -299,7 +299,6 @@ mod tests {
         state.select(Some(1));
 
         let mut buf = Buffer::empty(Rect::new(0, 0, 10, 2));
-        use ratatui::widgets::StatefulWidget;
         StatefulWidget::render(list, Rect::new(0, 0, 10, 2), &mut buf, &mut state);
 
         let content = buf.content().iter().map(|c| c.symbol()).collect::<String>();
@@ -328,7 +327,6 @@ mod tests {
         state.select(Some(0));
 
         let mut buf1 = Buffer::empty(Rect::new(0, 0, 10, 2));
-        use ratatui::widgets::StatefulWidget;
         StatefulWidget::render(
             list_without_repeat,
             Rect::new(0, 0, 10, 2),
@@ -370,7 +368,6 @@ mod tests {
         state.select(Some(1));
 
         let mut buf = Buffer::empty(Rect::new(0, 0, 15, 4));
-        use ratatui::widgets::StatefulWidget;
         StatefulWidget::render(list, Rect::new(0, 0, 15, 4), &mut buf, &mut state);
 
         let content = buf.content().iter().map(|c| c.symbol()).collect::<String>();

data/ext/ratatui_ruby/src/widgets/overlay.rs

@@ -4,9 +4,9 @@
 use crate::errors::type_error_with_context;
 use crate::rendering::render_node;
 use magnus::{prelude::*, Error, Value};
-use ratatui::{layout::Rect, Frame};
+use ratatui::{buffer::Buffer, layout::Rect};
 
-pub fn render(frame: &mut Frame, area: Rect, node: Value) -> Result<(), Error> {
+pub fn render(buffer: &mut Buffer, area: Rect, node: Value) -> Result<(), Error> {
     let ruby = magnus::Ruby::get().unwrap();
     let layers_val: Value = node.funcall("layers", ())?;
     let layers_array = magnus::RArray::from_value(layers_val)
@@ -16,7 +16,7 @@ pub fn render(frame: &mut Frame, area: Rect, node: Value) -> Result<(), Error> {
         let index = isize::try_from(i)
             .map_err(|e| Error::new(ruby.exception_range_error(), e.to_string()))?;
         let layer: Value = layers_array.entry(index)?;
-        if let Err(e) = render_node(frame, area, layer) {
+        if let Err(e) = render_node(buffer, area, layer) {
             eprintln!("Error rendering overlay layer {i}: {e:?}");
         }
     }

data/ext/ratatui_ruby/src/widgets/paragraph.rs

@@ -4,15 +4,15 @@
 use crate::style::{parse_block, parse_style};
 use bumpalo::Bump;
 use magnus::{prelude::*, Error, Symbol, Value};
+use ratatui::buffer::Buffer;
 use ratatui::{
     layout::{HorizontalAlignment, Rect},
-    widgets::{Paragraph, Wrap},
-    Frame,
+    widgets::{Paragraph, Widget, Wrap},
 };
 
 use crate::text::parse_text;
 
-fn create_paragraph(node: Value, bump: &Bump) -> Result<Paragraph<'_>, Error> {
+pub fn create_paragraph(node: Value, bump: &Bump) -> Result<Paragraph<'_>, Error> {
     let text_val: Value = node.funcall("text", ())?;
     let style_val: Value = node.funcall("style", ())?;
     let block_val: Value = node.funcall("block", ())?;
@@ -50,10 +50,10 @@ fn create_paragraph(node: Value, bump: &Bump) -> Result<Paragraph<'_>, Error> {
     Ok(paragraph)
 }
 
-pub fn render(frame: &mut Frame, area: Rect, node: Value) -> Result<(), Error> {
+pub fn render(buffer: &mut Buffer, area: Rect, node: Value) -> Result<(), Error> {
     let bump = Bump::new();
     let paragraph = create_paragraph(node, &bump)?;
-    frame.render_widget(paragraph, area);
+    Widget::render(paragraph, area, buffer);
     Ok(())
 }
 
@@ -78,7 +78,6 @@ mod tests {
     fn test_paragraph_rendering() {
         let p = Paragraph::new("test content").alignment(HorizontalAlignment::Center);
         let mut buf = Buffer::empty(Rect::new(0, 0, 20, 1));
-        use ratatui::widgets::Widget;
         p.render(Rect::new(0, 0, 20, 1), &mut buf);
         let content = buf.content().iter().map(|c| c.symbol()).collect::<String>();
         assert!(content.contains("test content"));

data/ext/ratatui_ruby/src/widgets/ratatui_logo.rs

@@ -4,16 +4,16 @@
 
 use magnus::Value;
 use ratatui::{
+    buffer::Buffer,
     layout::Rect,
-    widgets::{RatatuiLogo, RatatuiLogoSize},
-    Frame,
+    widgets::{RatatuiLogo, RatatuiLogoSize, Widget},
 };
 
-pub fn render(frame: &mut Frame, area: Rect, _node: Value) {
+pub fn render(buffer: &mut Buffer, area: Rect, _node: Value) {
     // RatatuiLogo does not support custom styling (it has fixed colors).
     // It requires a size argument.
     let widget = RatatuiLogo::new(RatatuiLogoSize::Small);
-    frame.render_widget(widget, area);
+    widget.render(area, buffer);
 }
 
 #[cfg(test)]

data/ext/ratatui_ruby/src/widgets/ratatui_mascot.rs

@@ -5,9 +5,13 @@
 use crate::style::parse_block;
 use bumpalo::Bump;
 use magnus::{prelude::*, Error, Value};
-use ratatui::{layout::Rect, widgets::RatatuiMascot, Frame};
+use ratatui::{
+    buffer::Buffer,
+    layout::Rect,
+    widgets::{RatatuiMascot, Widget},
+};
 
-pub fn render_ratatui_mascot(frame: &mut Frame, area: Rect, node: Value) -> Result<(), Error> {
+pub fn render_ratatui_mascot(buffer: &mut Buffer, area: Rect, node: Value) -> Result<(), Error> {
     let block_val: Value = node.funcall("block", ())?;
 
     let mut inner_area = area;
@@ -16,11 +20,11 @@ pub fn render_ratatui_mascot(frame: &mut Frame, area: Rect, node: Value) -> Resu
         let bump = Bump::new();
         let block = parse_block(block_val, &bump)?;
         inner_area = block.inner(area);
-        frame.render_widget(block, area);
+        block.render(area, buffer);
     }
 
     let widget = RatatuiMascot::new();
-    frame.render_widget(widget, inner_area);
+    widget.render(inner_area, buffer);
     Ok(())
 }
 

data/ext/ratatui_ruby/src/widgets/scrollbar.rs

@@ -6,12 +6,12 @@ use crate::widgets::scrollbar_state::RubyScrollbarState;
 use bumpalo::Bump;
 use magnus::{prelude::*, Error, Symbol, TryConvert, Value};
 use ratatui::{
+    buffer::Buffer,
     layout::Rect,
-    widgets::{Scrollbar, ScrollbarOrientation, ScrollbarState},
-    Frame,
+    widgets::{Scrollbar, ScrollbarOrientation, ScrollbarState, StatefulWidget, Widget},
 };
 
-pub fn render(frame: &mut Frame, area: Rect, node: Value) -> Result<(), Error> {
+pub fn render(buffer: &mut Buffer, area: Rect, node: Value) -> Result<(), Error> {
     let content_length: usize = node.funcall("content_length", ())?;
     let position: usize = node.funcall("position", ())?;
     let orientation_sym: Symbol = node.funcall("orientation", ())?;
@@ -79,13 +79,13 @@ pub fn render(frame: &mut Frame, area: Rect, node: Value) -> Result<(), Error> {
     }
 
     if block_val.is_nil() {
-        frame.render_stateful_widget(scrollbar, area, &mut state);
+        StatefulWidget::render(scrollbar, area, buffer, &mut state);
     } else {
         let bump = Bump::new();
         let block = parse_block(block_val, &bump)?;
         let inner_area = block.inner(area);
-        frame.render_widget(block, area);
-        frame.render_stateful_widget(scrollbar, inner_area, &mut state);
+        block.render(area, buffer);
+        StatefulWidget::render(scrollbar, inner_area, buffer, &mut state);
     }
     Ok(())
 }
@@ -95,7 +95,7 @@ pub fn render(frame: &mut Frame, area: Rect, node: Value) -> Result<(), Error> {
 /// The State object is the single source of truth for position and `content_length`.
 /// Widget properties (`position`, `content_length`) are ignored.
 pub fn render_stateful(
-    frame: &mut Frame,
+    buffer: &mut Buffer,
     area: Rect,
     node: Value,
     state_wrapper: Value,
@@ -168,13 +168,13 @@ pub fn render_stateful(
     {
         let mut inner_state = state.borrow_mut();
         if block_val.is_nil() {
-            frame.render_stateful_widget(scrollbar, area, &mut inner_state);
+            StatefulWidget::render(scrollbar, area, buffer, &mut inner_state);
         } else {
             let bump = Bump::new();
             let block = parse_block(block_val, &bump)?;
             let inner_area = block.inner(area);
-            frame.render_widget(block, area);
-            frame.render_stateful_widget(scrollbar, inner_area, &mut inner_state);
+            block.render(area, buffer);
+            StatefulWidget::render(scrollbar, inner_area, buffer, &mut inner_state);
         }
     }
 

data/ext/ratatui_ruby/src/widgets/sparkline.rs

@@ -4,9 +4,10 @@
 use crate::style::{parse_bar_set, parse_block, parse_style};
 use bumpalo::Bump;
 use magnus::{prelude::*, Error, RString, Value};
-use ratatui::{layout::Rect, widgets::RenderDirection, widgets::Sparkline, Frame};
+use ratatui::buffer::Buffer;
+use ratatui::{layout::Rect, widgets::RenderDirection, widgets::Sparkline, widgets::Widget};
 
-pub fn render(frame: &mut Frame, area: Rect, node: Value) -> Result<(), Error> {
+pub fn render(buffer: &mut Buffer, area: Rect, node: Value) -> Result<(), Error> {
     let bump = Bump::new();
     let ruby = magnus::Ruby::get().unwrap();
     let data_val: magnus::RArray = node.funcall("data", ())?;
@@ -72,7 +73,7 @@ pub fn render(frame: &mut Frame, area: Rect, node: Value) -> Result<(), Error> {
         sparkline = sparkline.bar_set(parse_bar_set(bar_set_val, &bump)?);
     }
 
-    frame.render_widget(sparkline, area);
+    sparkline.render(area, buffer);
     Ok(())
 }
 

data/ext/ratatui_ruby/src/widgets/table.rs

@@ -8,12 +8,12 @@ use crate::widgets::table_state::RubyTableState;
 use bumpalo::Bump;
 use magnus::{prelude::*, Error, Symbol, TryConvert, Value};
 use ratatui::{
+    buffer::Buffer,
     layout::{Constraint, Flex, Rect},
-    widgets::{Cell, HighlightSpacing, Row, Table, TableState},
-    Frame,
+    widgets::{Cell, HighlightSpacing, Row, StatefulWidget, Table, TableState},
 };
 
-pub fn render(frame: &mut Frame, area: Rect, node: Value) -> Result<(), Error> {
+pub fn render(buffer: &mut Buffer, area: Rect, node: Value) -> Result<(), Error> {
     let bump = Bump::new();
     let ruby = magnus::Ruby::get().unwrap();
     let header_val: Value = node.funcall("header", ())?;
@@ -123,7 +123,7 @@ pub fn render(frame: &mut Frame, area: Rect, node: Value) -> Result<(), Error> {
         *state.offset_mut() = offset;
     }
 
-    frame.render_stateful_widget(table, area, &mut state);
+    StatefulWidget::render(table, area, buffer, &mut state);
     Ok(())
 }
 
@@ -132,7 +132,7 @@ pub fn render(frame: &mut Frame, area: Rect, node: Value) -> Result<(), Error> {
 /// This function ignores `selected_row`, `selected_column`, and `offset` from the widget.
 /// The State object is the single source of truth for selection and scroll position.
 pub fn render_stateful(
-    frame: &mut Frame,
+    buffer: &mut Buffer,
     area: Rect,
     node: Value,
     state_wrapper: Value,
@@ -230,7 +230,7 @@ pub fn render_stateful(
     // Borrow the inner TableState, render, and release the borrow immediately
     {
         let mut inner_state = state.borrow_mut();
-        frame.render_stateful_widget(table, area, &mut inner_state);
+        StatefulWidget::render(table, area, buffer, &mut inner_state);
     }
 
     Ok(())

data/ext/ratatui_ruby/src/widgets/tabs.rs

@@ -6,12 +6,13 @@ use crate::style::parse_block;
 use crate::text::{parse_line, parse_span};
 use bumpalo::Bump;
 use magnus::{prelude::*, Error, Value};
-use ratatui::{layout::Rect, text::Line, widgets::Tabs, Frame};
+use ratatui::buffer::Buffer;
+use ratatui::{layout::Rect, text::Line, widgets::Tabs, widgets::Widget};
 
-pub fn render(frame: &mut Frame, area: Rect, node: Value) -> Result<(), Error> {
+pub fn render(buffer: &mut Buffer, area: Rect, node: Value) -> Result<(), Error> {
     let bump = Bump::new();
     let tabs = create_tabs(node, &bump)?;
-    frame.render_widget(tabs, area);
+    tabs.render(area, buffer);
     Ok(())
 }
 

data/lib/ratatui_ruby/labs/a11y.rb

@@ -0,0 +1,173 @@
+# frozen_string_literal: true
+
+#--
+# SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
+# SPDX-License-Identifier: LGPL-3.0-or-later
+#++
+
+require "tmpdir"
+require "rexml/document"
+
+module RatatuiRuby
+  module Labs
+    # A11Y lab: exports widget tree as XML.
+    #
+    # Writes an XML representation of the widget tree to a temporary file
+    # every frame when enabled.
+    module A11y
+      # Path to the XML output file in the system temp directory.
+      OUTPUT_PATH = File.join(Dir.tmpdir, "ratatui_ruby_a11y.xml").freeze
+
+      class << self
+        # Dumps the widget tree to XML (single widget for tree mode).
+        def dump_widget_tree(widget, _area = nil)
+          doc = REXML::Document.new
+          doc.add(REXML::XMLDecl.new("1.0", "UTF-8"))
+          doc.add(build_element(widget))
+          write_document(doc)
+        end
+
+        # Returns startup message for users to see before TUI launches.
+        #
+        # Since stdout is captured during TUI rendering, users need to know
+        # where the XML file will be written before the app starts.
+        def startup_message
+          <<~MSG
+            A11Y Lab enabled! Widget tree will be written to:
+              #{OUTPUT_PATH}
+
+            Press Enter to launch the TUI...
+          MSG
+        end
+
+        # Dumps multiple widgets captured from Frame API mode.
+        def dump_widgets(widgets_with_areas)
+          Labs.warn_once!("Labs::A11y (RR_LABS=A11Y)")
+
+          # Reset counter each frame for stable IDs
+          @widget_id_counter = 0
+
+          doc = REXML::Document.new
+          doc.add(REXML::XMLDecl.new("1.0", "UTF-8"))
+
+          frame = REXML::Element.new("RatatuiFrame")
+          widgets_with_areas.each do |widget, area|
+            frame.add(build_element_with_area(widget, area))
+          end
+          doc.add(frame)
+
+          write_document(doc)
+        end
+
+        private def write_document(doc)
+          output = +""
+          formatter = REXML::Formatters::Pretty.new(2)
+          formatter.compact = true
+          formatter.write(doc, output)
+          File.write(OUTPUT_PATH, output)
+        end
+
+        private def build_element_with_area(widget, area)
+          class_name = widget.class.name&.split("::")&.last || "Unknown"
+          element = REXML::Element.new(class_name)
+
+          # Generate unique id for this widget
+          @widget_id_counter ||= 0
+          @widget_id_counter += 1
+          widget_id = "w#{@widget_id_counter}"
+          element.add_attribute("id", widget_id)
+
+          # Add area attributes
+          element.add_attribute("x", area.x.to_s)
+          element.add_attribute("y", area.y.to_s)
+          element.add_attribute("width", area.width.to_s)
+          element.add_attribute("height", area.height.to_s)
+
+          add_members(element, widget, parent_id: widget_id)
+          element
+        end
+
+        private def build_element(node)
+          class_name = node.class.name&.split("::")&.last || "Unknown"
+          element = REXML::Element.new(class_name)
+
+          if node.respond_to?(:to_h) && node.respond_to?(:members)
+            add_members(element, node)
+          else
+            element.text = node.to_s
+          end
+
+          element
+        end
+
+        private def add_members(element, node, parent_id: nil)
+          return unless node.respond_to?(:to_h) && node.respond_to?(:members)
+
+          node.to_h.each do |key, value|
+            # Skip nil and empty values entirely (no noise in output)
+            next if value.nil?
+            next if value.respond_to?(:empty?) && value.empty?
+
+            # Skip objects where all members are nil/empty (like default Style)
+            if value.respond_to?(:to_h) && value.respond_to?(:members)
+              attrs = value.to_h.compact
+              next if attrs.empty? || attrs.values.all? { |v| v.respond_to?(:empty?) && v.empty? }
+            end
+
+            # Scalar values → XML attributes
+            # Exception: 'text' and 'content' accept Text (multi-line capable)
+            # Complex values → XML child elements
+            multiline_keys = %w[text content]
+            if scalar?(value) && !multiline_keys.include?(key.to_s)
+              element.add_attribute(key.to_s, value.to_s)
+            else
+              # Special handling for 'block' wrapper - add ARIA role and id/for
+              is_block_wrapper = key.to_s == "block" && parent_id
+              child = build_child_element(key, value, is_wrapper: is_block_wrapper, parent_id:)
+              element.add(child) if child
+            end
+          end
+        end
+
+        private def scalar?(value)
+          case value
+          when String, Symbol, Numeric, TrueClass, FalseClass
+            true
+          else
+            false
+          end
+        end
+
+        private def build_child_element(key, value, is_wrapper: false, parent_id: nil)
+          element = REXML::Element.new(key.to_s)
+
+          # Add ARIA role and id/for association for block wrappers
+          if is_wrapper && parent_id
+            element.add_attribute("role", "group")
+            element.add_attribute("for", parent_id)
+          end
+
+          case value
+          when Array
+            value.each { |item| element.add(build_element(item)) }
+          when Hash
+            # Plain Hash: serialize keys as attributes
+            value.each do |k, v|
+              next if v.nil?
+              next if v.respond_to?(:empty?) && v.empty?
+              element.add_attribute(k.to_s, v.to_s)
+            end
+          else
+            if value.respond_to?(:to_h) && value.respond_to?(:members)
+              add_members(element, value)
+            else
+              element.text = value.to_s
+            end
+          end
+
+          element
+        end
+      end
+    end
+  end
+end

data/lib/ratatui_ruby/labs/frame_a11y_capture.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+#--
+# SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
+# SPDX-License-Identifier: LGPL-3.0-or-later
+#++
+
+module RatatuiRuby
+  class Frame
+    # A11Y Lab Integration
+    #
+    # When the A11Y lab is enabled, we capture widgets as they are rendered
+    # and write the tree to XML when flush_a11y_capture is called.
+    module A11yCapture
+      # Intercepts render_widget to capture widgets for A11Y export.
+      # @param widget [widget] The widget being rendered
+      # @param area [Layout::Rect] The area to render into
+      def render_widget(widget, area)
+        if Labs.enabled?(:a11y)
+          widgets = (@a11y_widgets ||= []) #: Array[[(_CustomWidget | widget), Layout::Rect]]
+          widgets << [widget, area]
+        end
+        super
+      end
+
+      # Intercepts render_stateful_widget to capture widgets for A11Y export.
+      # @param widget [widget] The widget being rendered
+      # @param area [Layout::Rect] The area to render into
+      # @param state [Object] The widget state
+      def render_stateful_widget(widget, area, state)
+        if Labs.enabled?(:a11y)
+          widgets = (@a11y_widgets ||= []) #: Array[[(_CustomWidget | widget), Layout::Rect]]
+          widgets << [widget, area]
+        end
+        super
+      end
+
+      # Called at end of draw block to flush captured widgets
+      def flush_a11y_capture
+        widgets = @a11y_widgets
+        return unless Labs.enabled?(:a11y) && widgets&.any?
+
+        Labs::A11y.dump_widgets(widgets)
+        @a11y_widgets = nil
+      end
+    end
+
+    prepend A11yCapture
+  end
+end

data/lib/ratatui_ruby/labs.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+#--
+# SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
+# SPDX-License-Identifier: LGPL-3.0-or-later
+#++
+
+module RatatuiRuby
+  # Experimental lab features.
+  module Labs
+    @enabled_lab = nil #: Symbol?
+
+    class << self
+      # Returns whether the specified lab is enabled.
+      def enabled?(lab)
+        @enabled_lab == lab.to_sym.downcase
+      end
+
+      # Enables a lab programmatically.
+      def enable!(lab)
+        @enabled_lab = lab.to_sym.downcase
+      end
+
+      # Resets all labs (for testing only).
+      def reset!
+        @enabled_lab = nil
+        @warned = false
+      end
+
+      # Emits experimental warning once per session.
+      def warn_once!(feature_name)
+        return if @warned
+
+        RatatuiRuby.warn_experimental_feature(feature_name)
+        @warned = true
+      end
+    end
+  end
+end
+
+# Auto-enable from environment variable
+if (lab = ENV["RR_LABS"])
+  RatatuiRuby::Labs.enable!(lab)
+end
+
+require_relative "labs/a11y"
+require_relative "labs/frame_a11y_capture"

data/lib/ratatui_ruby/layout/position.rb

@@ -50,6 +50,32 @@ module RatatuiRuby
       def initialize(x: 0, y: 0)
         super(x: Integer(x), y: Integer(y))
       end
+
+      # Enables array destructuring for convenient coordinate extraction.
+      #
+      # Returns:: Array of [x, y] coordinates.
+      #
+      # === Example
+      #
+      #--
+      # SPDX-SnippetBegin
+      # SPDX-FileCopyrightText: 2026 Kerrick Long
+      # SPDX-License-Identifier: MIT-0
+      #++
+      #   pos = Position.new(x: 10, y: 5)
+      #   x, y = pos  # Uses deconstruct
+      #   puts "Column: #{x}, Row: #{y}"
+      #--
+      # SPDX-SnippetEnd
+      #++
+      def deconstruct
+        [x, y]
+      end
+
+      # Alias for implicit array conversion.
+      #
+      # Enables `x, y = position` syntax by making Position respond to +to_ary+.
+      alias to_ary deconstruct
     end
   end
 end