protege 0.1.0.alpha.1

data/app/helpers/protege/components/forms_helper.rb

@@ -0,0 +1,223 @@
+# frozen_string_literal: true
+
+module Protege
+  module Components
+    # Form-building UI elements shared across engine views.
+    #
+    # Split out of +ComponentsHelper+ so each module stays focused; +FormsHelper+
+    # owns the input styling constants and the field/select/checkbox builders that
+    # wrap Rails form helpers in Protege's design system.
+    #
+    # Colors use CSS custom properties (--surface, --border, --text, --text-faint)
+    # defined in tailwind/application.css so dark mode works via a single .dark
+    # class toggle.
+    module FormsHelper
+      # Tailwind classes applied to text inputs, selects, and textareas.
+      FORM_INPUT    = 'block w-full rounded-sm px-2.5 py-1.5 text-sm shadow-sm ' \
+                      'focus:border-amber-500 focus:outline-none focus:ring-1 focus:ring-amber-500'
+      # Tailwind classes applied to field labels.
+      FORM_LABEL    = 'block text-sm font-medium mb-1'
+      # Tailwind classes applied to checkboxes.
+      FORM_CHECKBOX = 'h-4 w-4 rounded text-amber-600 focus:ring-amber-500'
+
+      # Build the inline style applied to form controls so they track the theme.
+      #
+      # @return [String] the CSS custom-property-backed style string
+      def form_input_style
+        'background: var(--surface); border: 1px solid var(--border); color: var(--text)'
+      end
+
+      # Render a record's validation errors as a styled list, or nothing when valid.
+      #
+      # @param record [ActiveModel::Validations] the record whose errors to render
+      # @return [ActiveSupport::SafeBuffer] the error block, or an empty buffer
+      def form_errors(record)
+        return ''.html_safe unless record.errors.any?
+
+        tag.div(class: 'rounded-lg border border-red-200 bg-red-50 px-4 py-3 text-sm text-red-700') do
+          tag.ul(class: 'list-disc pl-4 space-y-1') do
+            safe_join(record.errors.full_messages.map { |message| tag.li(message) })
+          end
+        end
+      end
+
+      # Render a labelled text field with an optional hint, wired to a form builder.
+      #
+      # @param form [ActionView::Helpers::FormBuilder] the form builder
+      # @param field [Symbol] the attribute the field edits
+      # @param label [String, nil] the label text; defaults to the attribute's humanized name
+      # @param hint [String, nil] optional helper text shown beneath the field
+      # @param input_attrs [Hash] extra HTML attributes forwarded to the input
+      # @return [ActiveSupport::SafeBuffer] the field markup
+      def form_field(form, field, label: nil, hint: nil, **input_attrs)
+        tag.div do
+          form.label(field, label, class: FORM_LABEL) +
+            form.text_field(field, class: FORM_INPUT, style: form_input_style, **input_attrs) +
+            form_hint(hint)
+        end
+      end
+
+      # Render a labelled select wired to a form builder.
+      #
+      # @param form [ActionView::Helpers::FormBuilder] the form builder
+      # @param field [Symbol] the attribute the select edits
+      # @param choices [Object] the option set passed to +FormBuilder#select+
+      # @param label [String, nil] the label text; defaults to the attribute's humanized name
+      # @param prompt [String, nil] optional blank-choice prompt
+      # @param selected [String, nil] the value to preselect — needed on a modelless form (e.g. a GET
+      #   search form) where the builder has no object to read the current value from
+      # @param attrs [Hash] extra HTML attributes forwarded to the select
+      # @return [ActiveSupport::SafeBuffer] the select markup
+      def form_select(form, field, choices, label: nil, prompt: nil, selected: nil, **attrs)
+        tag.div do
+          form.label(field, label, class: FORM_LABEL) +
+            form.select(field, choices, { prompt:, selected: }, class: FORM_INPUT, style: form_input_style, **attrs)
+        end
+      end
+
+      # Render the split prefix/domain email-address control for a persona.
+      #
+      # When domains exist, render a prefix text box, an +@+ separator, and a domain
+      # select preselected to the record's current domain; otherwise prompt the
+      # operator to add a domain first.
+      #
+      # @param record [Protege::Persona] the persona whose email address to edit
+      # @param domains [Enumerable<Protege::EmailDomain>] the selectable domains
+      # @return [ActiveSupport::SafeBuffer] the email-address control markup
+      def form_email_address(record, domains)
+        tag.div do
+          tag.label('Email address', class: FORM_LABEL) +
+            tag.div(class: 'flex items-center gap-2') do
+              domains.any? ? email_address_fields(record, domains) : email_address_empty
+            end
+        end
+      end
+
+      # Render a labelled textarea with an optional hint, wired to a form builder.
+      #
+      # @param form [ActionView::Helpers::FormBuilder] the form builder
+      # @param field [Symbol] the attribute the textarea edits
+      # @param label [String, nil] optional label text; omitted when nil
+      # @param hint [String, nil] optional helper text shown beneath the textarea
+      # @param fill [Boolean] when true, the wrapper and textarea flex to fill the height of a flex-column
+      #   parent (e.g. a resizable reply composer) instead of using the default fixed-minimum, self-resizable size
+      # @param input_attrs [Hash] extra HTML attributes forwarded to the textarea
+      # @return [ActiveSupport::SafeBuffer] the textarea markup
+      def form_text_area(form, field, label: nil, hint: nil, fill: false, **input_attrs)
+        input_attrs[:rows] ||= 3
+        size_class           = fill ? 'flex-1 min-h-0 resize-none' : 'resize-y min-h-[6rem]'
+        tag.div(class: fill ? 'flex min-h-0 flex-1 flex-col' : nil) do
+          (label ? form.label(field, label, class: FORM_LABEL) : ''.html_safe) +
+            form.text_area(field, class: "#{FORM_INPUT} font-mono #{size_class}",
+                                  style: form_input_style, **input_attrs) +
+            form_hint(hint)
+        end
+      end
+
+      # Render a labelled checkbox wired to a form builder.
+      #
+      # @param form [ActionView::Helpers::FormBuilder] the form builder
+      # @param field [Symbol] the attribute the checkbox edits
+      # @param label [String, nil] the label text; defaults to the attribute's humanized name
+      # @return [ActiveSupport::SafeBuffer] the checkbox markup
+      def form_checkbox(form, field, label: nil)
+        tag.div(class: 'flex items-center gap-3') do
+          form.check_box(field, class: FORM_CHECKBOX, style: 'border: 1px solid var(--border)') +
+            form.label(field, label, class: 'text-sm font-medium')
+        end
+      end
+
+      # Render a labelled checklist — one checkbox per item, backed by an array attribute, wired to a
+      # form builder. Rails' +collection_check_boxes+ emits the hidden blank field for us, so unchecking
+      # every box submits an empty array (clearing the attribute) instead of omitting it.
+      #
+      # @param form [ActionView::Helpers::FormBuilder] the form builder
+      # @param field [Symbol] the array attribute the checklist edits
+      # @param collection [Enumerable] the items, one checkbox each
+      # @param label [String, nil] the group label; omitted when nil
+      # @param hint [String, nil] optional helper text shown beneath the label
+      # @param value [Symbol, Proc] maps an item to its submitted value (default: +:to_s+)
+      # @param text [Symbol, Proc] maps an item to its checkbox label (default: +:to_s+)
+      # @return [ActiveSupport::SafeBuffer] the checklist markup
+      def form_checklist(form, field, collection, label: nil, hint: nil, value: :to_s, text: :to_s)
+        tag.div do
+          (label ? tag.label(label, class: FORM_LABEL) : ''.html_safe) +
+            form_hint(hint) +
+            tag.div(class: 'space-y-2 pt-1') do
+              form.collection_check_boxes(field, collection, value, text) do |b|
+                b.label(class: 'flex items-center gap-3 text-sm') do
+                  b.check_box(class: FORM_CHECKBOX, style: 'border: 1px solid var(--border)') + b.text
+                end
+              end
+            end
+        end
+      end
+
+      private
+
+      # Render the muted hint paragraph shown beneath a field, or nothing.
+      #
+      # @param hint [String, nil] the hint text
+      # @return [ActiveSupport::SafeBuffer] the hint paragraph, or an empty buffer
+      def form_hint(hint)
+        return ''.html_safe unless hint
+
+        tag.p(hint, class: 'mt-1 text-xs', style: 'color: var(--text-faint)')
+      end
+
+      # Render the prefix input, +@+ separator, and domain select for an address.
+      #
+      # @param record [Protege::Persona] the persona whose address to edit
+      # @param domains [Enumerable<Protege::EmailDomain>] the selectable domains
+      # @return [ActiveSupport::SafeBuffer] the prefix/separator/select markup
+      def email_address_fields(record, domains)
+        input_base = FORM_INPUT.sub('w-full ', '')
+
+        email_address_prefix(record, input_base) +
+          tag.span('@', class: 'text-sm select-none', style: 'color: var(--text-faint)') +
+          email_address_domain_select(record, domains, input_base)
+      end
+
+      # Render the local-part text input, seeded with the record's current prefix.
+      #
+      # @param record [Protege::Persona] the persona whose prefix to seed
+      # @param input_base [String] the shared input classes without the +w-full+ utility
+      # @return [ActiveSupport::SafeBuffer] the prefix input markup
+      def email_address_prefix(record, input_base)
+        tag.input(
+          type:        'text',
+          name:        'persona[email_prefix]',
+          value:       record.email_address&.split('@')&.first,
+          placeholder: 'alice',
+          class:       "block w-40 #{input_base}",
+          style:       form_input_style
+        )
+      end
+
+      # Render the domain select, preselecting the record's current domain.
+      #
+      # @param record [Protege::Persona] the persona whose domain to preselect
+      # @param domains [Enumerable<Protege::EmailDomain>] the selectable domains
+      # @param input_base [String] the shared input classes without the +w-full+ utility
+      # @return [ActiveSupport::SafeBuffer] the domain select markup
+      def email_address_domain_select(record, domains, input_base)
+        options = safe_join(domains.map do |domain|
+          tag.option(domain.domain, value:    domain.domain,
+                                    selected: record.email_address&.end_with?("@#{domain.domain}"))
+        end)
+
+        tag.select(options, name: 'persona[email_domain]', class: "block flex-1 #{input_base}",
+                            style: form_input_style)
+      end
+
+      # Render the placeholder shown when no email domains are configured.
+      #
+      # @return [ActiveSupport::SafeBuffer] the "add a domain" prompt
+      def email_address_empty
+        tag.span(class: 'text-xs italic', style: 'color: var(--text-faint)') do
+          'No domains configured — '.html_safe + ui_link('add one', new_email_domain_path)
+        end
+      end
+    end
+  end
+end

data/app/helpers/protege/components/hotkeys_helper.rb

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+module Protege
+  module Components
+    # Rendering for the keyboard-shortcuts overlay (see +shared/_hotkeys+ and +keys.js+): the header "?"
+    # button that opens it, plus the section dividers, rows, and key caps its static, hand-authored
+    # template is composed from. keys.js stays purely behavioral — it only toggles the dialog and
+    # activates +[data-hotkey]+ elements — so the overlay's content is built here from plain markup.
+    module HotkeysHelper
+      # Render the keycap-styled "?" button that opens the overlay. Looks like a key (matching the caps
+      # below) and calls +toggleHotkeyHelp()+ (exposed by keys.js) — the same open/close path as "?".
+      #
+      # @return [ActiveSupport::SafeBuffer] the button markup
+      def hotkey_help_button
+        cap_style = 'background: var(--surface-subtle); border: 1px solid var(--border); color: var(--text-muted)'
+        tag.button('?',
+                   type:         'button',
+                   'aria-label': 'Keyboard shortcuts',
+                   title:        'Keyboard shortcuts',
+                   class:        'inline-flex px-1 h-5 w-5 items-center justify-center rounded text-xs font-mono ' \
+                                 'cursor-pointer transition-colors',
+                   style:        cap_style,
+                   onclick:      'toggleHotkeyHelp()')
+      end
+
+      # Render a titled section divider — the label followed by a rule filling the rest of the row
+      # ("Go to ————").
+      #
+      # @param title [String] the section label
+      # @return [ActiveSupport::SafeBuffer] the divider markup
+      def hotkey_section(title)
+        tag.div(class: 'flex items-center gap-2 pt-3 first:pt-0 text-xs font-semibold uppercase tracking-wider',
+                style: 'color: var(--text-faint)') do
+          tag.span(title) + tag.span('', class: 'flex-1', style: 'border-top: 1px solid var(--border)')
+        end
+      end
+
+      # Render one shortcut row: a label on the left, its key caps on the right.
+      #
+      # @param label [String] the shortcut's description
+      # @param keys [Array<String>] the keys to show as caps, in order (e.g. "g", "1")
+      # @return [ActiveSupport::SafeBuffer] the row markup
+      def hotkey_row(label, *keys)
+        tag.div(class: 'flex items-center justify-between gap-6 py-1') do
+          tag.span(label) +
+            tag.span(class: 'flex items-center gap-1') { safe_join(keys.map { |key| hotkey_cap(key) }) }
+        end
+      end
+
+      # Render a single keycap (+<kbd>+), styled to match the header's "?" button.
+      #
+      # @param key [String] the key label
+      # @return [ActiveSupport::SafeBuffer] the keycap markup
+      def hotkey_cap(key)
+        tag.kbd(key, class: 'rounded px-1.5 py-0.5 text-xs font-mono',
+                     style: 'background: var(--surface-subtle); border: 1px solid var(--border)')
+      end
+    end
+  end
+end

data/app/helpers/protege/components/icons_helper.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+module Protege
+  module Components
+    # Inline SVG icons — a small registry of single-path, stroked glyphs (Lucide geometry). Each renders
+    # as +currentColor+ so it inherits the surrounding text color and theme. Add an entry to +ICONS+ to
+    # introduce a new glyph; render one with +icon(:name)+.
+    module IconsHelper
+      # Icon key => the +d+ attribute of its single +<path>+.
+      ICONS = {
+        paperclip: 'M21.44 11.05l-9.19 9.19a6 6 0 0 1-8.49-8.49l9.19-9.19a4 4 0 0 1 5.66 5.66' \
+                   'l-9.2 9.19a2 2 0 0 1-2.83-2.83l8.49-8.48'
+      }.freeze
+
+      # Render a named icon as an inline SVG that inherits the current text color.
+      #
+      # @param name [Symbol] the icon key (see +ICONS+)
+      # @param size [Integer] the pixel width and height
+      # @param attrs [Hash] extra attributes merged onto the +<svg>+ (e.g. +class:+)
+      # @return [ActiveSupport::SafeBuffer] the SVG markup
+      # @raise [ArgumentError] when +name+ is not a registered icon
+      def icon(name, size: 16, **attrs)
+        path = ICONS.fetch(name) { raise ArgumentError, "unknown icon #{name.inspect}" }
+
+        tag.svg(
+          tag.path(d: path),
+          xmlns:             'http://www.w3.org/2000/svg',
+          width:             size,
+          height:            size,
+          viewBox:           '0 0 24 24',
+          fill:              'none',
+          stroke:            'currentColor',
+          'stroke-width':    2,
+          'stroke-linecap':  'round',
+          'stroke-linejoin': 'round',
+          **attrs
+        )
+      end
+    end
+  end
+end

data/app/helpers/protege/components/introspection_helper.rb

@@ -0,0 +1,162 @@
+# frozen_string_literal: true
+
+module Protege
+  module Components
+    # View helpers for the thread **introspection panel** — the collapsible right sidebar in the console
+    # that surfaces the agent's reasoning and tool use for the open thread. Mirrors +LayoutHelper+'s
+    # sidebar builders: small composable pieces (panel shell, section, tool card, toggle) so the view
+    # stays declarative and the panel's markup lives in one place as it grows.
+    module IntrospectionHelper
+      # DOM id of the panel +<aside>+ — the toggle shows/hides this element.
+      INTROSPECTION_PANEL_ID = 'thread-introspection'
+
+      # Render the panel shell: a full-height right +<aside>+ (mirroring the left inbox aside) with a fixed
+      # header and a scrollable body that yields its content (the activity feed).
+      #
+      # The user can resize its width by dragging the left-edge handle (the general +resize_handle+ paired
+      # with the engine's self-contained +resize.js+), bounded by min/max and remembered across page loads.
+      # Collapsing (open/close) is handled by +introspection_toggle+ in the thread header.
+      #
+      # @yield the panel body (e.g. +introspection_feed+)
+      # @return [ActiveSupport::SafeBuffer] the panel markup
+      def introspection_panel(&block)
+        class_names = 'relative flex w-80 flex-shrink-0 flex-col overflow-hidden'
+
+        data = {
+          resize:      '',
+          resize_edge: 'left',
+          resize_min:  240,
+          resize_max:  720,
+          resize_key:  'protege:introspection-width'
+        }
+
+        tag.aside(id: INTROSPECTION_PANEL_ID, class: class_names, data:) do
+          resize_handle(edge: :left) +
+            introspection_header +
+            tag.div(class: 'flex-1 overflow-y-auto px-4 py-3', &block)
+        end
+      end
+
+      # The toggle button (placed in the thread header) that shows/hides the panel.
+      #
+      # @return [ActiveSupport::SafeBuffer] the toggle button markup
+      def introspection_toggle
+        button('Introspection',
+               variant: :secondary,
+               type:    'button',
+               onclick: "document.getElementById('#{INTROSPECTION_PANEL_ID}').classList.toggle('hidden')")
+      end
+
+      # The live activity feed container — the single scrollable target the +IntrospectionBroadcaster+
+      # appends reasoning tokens and tool-call cards into, interleaved chronologically. Live-only: the
+      # +introspection-empty+ placeholder (see tailwind/application.css) shows until the next run streams in.
+      #
+      # Marked +data-turbo-permanent+ so the accumulated feed survives Turbo Drive navigations (the id is
+      # per-thread, so it is only preserved within the same thread). A hard page reload still starts it
+      # empty — permanence spans Drive visits only — keeping the feed live-only.
+      #
+      # @param thread [Protege::EmailThread] the open thread
+      # @return [ActiveSupport::SafeBuffer] the feed container markup
+      def introspection_feed(thread)
+        tag.div(id:    dom_id(thread, :activity),
+                class: 'introspection-empty text-xs font-mono leading-relaxed',
+                style: 'color: var(--text-muted)',
+                data:  { empty: 'Waiting for activity…', turbo_permanent: '' })
+      end
+
+      # A reasoning block — one paragraph of the model's streamed reasoning. The +IntrospectionBroadcaster+
+      # appends a fresh block after each tool call and streams that turn's tokens into it (by +id+), so
+      # reasoning is grouped into spaced, whitespace-preserving paragraphs rather than loose text nodes.
+      #
+      # @param id [String] the block's DOM id (the target the run's tokens append into)
+      # @param content [String, nil] the block's initial token text
+      # @return [ActiveSupport::SafeBuffer] the reasoning block markup
+      def introspection_reasoning(id:, content: nil)
+        tag.div(content, id:, class: 'my-3 whitespace-pre-wrap')
+      end
+
+      # A single tool-call card: a status glyph, the tool name, an optional one-line args summary, and an
+      # optional response preview (done) or error (failed). Streamed into the panel as a +:pending+ card
+      # the instant the model requests the call, then replaced in place with the outcome — so pass a stable
+      # +id:+ (the card's DOM id) that the replace can target.
+      #
+      # @param name [String] the tool name
+      # @param args [String, nil] a one-line argument summary
+      # @param status [Symbol] +:pending+, +:done+, or +:failed+
+      # @param preview [String, nil] a response preview or error string
+      # @param id [String, nil] the card's DOM id (so a pending card can be replaced by its outcome)
+      # @return [ActiveSupport::SafeBuffer] the card markup
+      def introspection_tool_card(name:, args: nil, status: :done, preview: nil, id: nil)
+        glyph, color, pulsing = tool_card_glyph(status)
+        tag.div(id:, class: 'my-3 pl-2 text-xs font-mono', style: 'border-left: 2px solid var(--border)') do
+          tag.div(class: 'flex items-center gap-2') do
+            tag.span(glyph, class: pulsing ? 'animate-pulse' : '', style: "color: #{color}") +
+              tag.span(name, class: 'font-medium', style: 'color: var(--text)')
+          end +
+            introspection_card_line(args, color: 'var(--text-muted)') +
+            introspection_card_line(preview.present? ? "→ #{preview}" : nil, color: 'var(--text-faint)')
+        end
+      end
+
+      # A run-lifecycle marker in the activity feed: a pulsing "Processing…" line while the run is in
+      # flight, or a red error when it fails. Appended on run start; on success it is removed, on failure
+      # replaced in place (by its +id+) with the error — so each run reads as processing → reasoning/tool
+      # use, then repeats for the next reply.
+      #
+      # @param id [String] the marker's DOM id (stable across the run so the outcome replaces it)
+      # @param status [Symbol] +:processing+ or +:failed+
+      # @param detail [String, nil] the error message, shown when +:failed+
+      # @return [ActiveSupport::SafeBuffer] the marker markup
+      def introspection_run_marker(id:, status: :processing, detail: nil)
+        if status == :failed
+          tag.div(id:, class: 'my-3 text-xs font-mono', style: 'color: #ef4444') do
+            tag.div('✗ Run failed', class: 'font-medium') +
+              introspection_card_line(detail, color: '#ef4444')
+          end
+        else
+          tag.div(id:, class: 'my-3 flex items-center gap-2 text-xs animate-pulse',
+                  style: 'color: var(--text-faint)') do
+            tag.span('•') + tag.span('Processing…')
+          end
+        end
+      end
+
+      private
+
+      # The glyph, color, and pulse for a tool card's status.
+      #
+      # @param status [Symbol] +:pending+, +:done+, or +:failed+
+      # @return [Array(String, String, Boolean)] the glyph, its CSS color, and whether it pulses
+      def tool_card_glyph(status)
+        case status
+        when :failed  then ['✗', '#ef4444', false]
+        when :pending then ['•', 'var(--text-faint)', true]
+        else               ['✓', 'var(--text-faint)', false]
+        end
+      end
+
+      # The panel's fixed header row (matches +sidebar_header+'s styling).
+      #
+      # @return [ActiveSupport::SafeBuffer] the header markup
+      def introspection_header
+        tag.div(class: 'flex h-10 flex-shrink-0 items-center px-4',
+                style: 'border-bottom: 1px solid var(--border)') do
+          tag.span('Introspection',
+                   class: 'text-xs font-semibold uppercase tracking-wider',
+                   style: 'color: var(--text-faint)')
+        end
+      end
+
+      # One wrapping text line inside a tool card, or an empty buffer when blank.
+      #
+      # @param text [String, nil] the line text
+      # @param color [String] the CSS color value
+      # @return [ActiveSupport::SafeBuffer] the line markup, or an empty buffer
+      def introspection_card_line(text, color:)
+        return ''.html_safe if text.blank?
+
+        tag.div(text, class: 'mt-1 whitespace-pre-wrap break-all', style: "color: #{color}")
+      end
+    end
+  end
+end

data/app/helpers/protege/components/layout_helper.rb

@@ -0,0 +1,169 @@
+# frozen_string_literal: true
+
+module Protege
+  module Components
+    # Page-scaffolding UI elements shared across engine views — the app shell (body,
+    # header, content region, main column), page headers and containers, navigation,
+    # and the theme toggle. A flat helper module among peers, all aggregated by
+    # +Protege::ApplicationHelper+ and mixed into the view together.
+    #
+    # Colors use CSS custom properties (--surface, --border, --text, --text-muted,
+    # --text-faint) defined in tailwind/application.css so dark mode works via a
+    # single .dark class toggle.
+    module LayoutHelper
+      # ── App shell ────────────────────────────────────────────────
+
+      # Render the app +<body>+ — a full-height flex column holding the fixed header and the content region
+      # (so the layout template carries no structural classes of its own). The block is the main content.
+      #
+      # @yield the main content
+      # @return [ActiveSupport::SafeBuffer] the body markup
+      def app_body(&main)
+        tag.body(class: 'h-full flex flex-col antialiased') { app_header + app_content(&main) }
+      end
+
+      # Render the app content region below the header — the full-height flex row holding the optional
+      # sidebar and the main column. The sidebar is drawn from the +:sidebar+ content buffer (a view's
+      # +content_for :sidebar+), so pages opt in just by defining it; the block is the main content.
+      #
+      # @yield the main content
+      # @return [ActiveSupport::SafeBuffer] the content-region markup
+      def app_content(&main)
+        tag.div(class: 'flex min-h-0 flex-1') { app_sidebar + app_main(&main) }
+      end
+
+      private
+
+      # Render the app's fixed top header (the shared header partial).
+      #
+      # @return [ActiveSupport::SafeBuffer] the header markup
+      def app_header
+        render('protege/shared/header')
+      end
+
+      # Render the docked sidebar from the +:sidebar+ content buffer, or nothing when a page defines none.
+      #
+      # @return [ActiveSupport::SafeBuffer] the sidebar shell, or an empty buffer
+      def app_sidebar
+        sidebar = content_for(:sidebar)
+        return ''.html_safe if sidebar.blank?
+
+        sidebar_container { sidebar }
+      end
+
+      # Render the main content column that fills the space beside the sidebar.
+      #
+      # @yield the main content
+      # @return [ActiveSupport::SafeBuffer] the +<main>+ markup
+      def app_main(&)
+        tag.main(class: 'flex min-w-0 flex-1 flex-col overflow-hidden', &)
+      end
+
+      # ── Page layout ──────────────────────────────────────────────
+
+      # Render a page header with a title, optional description, and optional actions.
+      #
+      # @param title [String] the page title
+      # @param description [String, nil] optional subtitle shown beneath the title
+      # @yield optional actions rendered to the right of the title
+      # @return [ActiveSupport::SafeBuffer] the header markup
+      def page_header(title, description = nil, &block)
+        tag.div(class: 'flex items-center justify-between mb-6') do
+          left = tag.div do
+            heading_1(title) +
+              (if description
+                 tag.p(description, class: 'mt-1 text-sm',
+                                    style: 'color: var(--text-muted)')
+               else
+                 ''.html_safe
+               end)
+          end
+
+          right = block ? capture(&block) : ''.html_safe
+
+          left + right
+        end
+      end
+
+      # Render the light/dark theme toggle switch. Carries the +g t+ hotkey directly (keys.js clicks it),
+      # so the shortcut lives on the real control rather than a hidden duplicate.
+      #
+      # @return [ActiveSupport::SafeBuffer] the toggle markup
+      def theme_toggle
+        tag.button(type:    'button',
+                   class:   'relative inline-flex h-5 w-9 items-center rounded-full cursor-pointer transition-colors',
+                   style:   'background: var(--surface-subtle); border: 1px solid var(--border)',
+                   data:    { hotkey: 'g t' },
+                   onclick: 'toggleTheme()') do
+          dot_position = dark_mode? ? 'translate-x-4' : 'translate-x-1'
+          dot_class    = 'toggle-dot inline-block h-3 w-3 rounded-full transition-transform bg-amber-500'
+          tag.span('', class: "#{dot_class} #{dot_position}")
+        end
+      end
+
+      # Report whether dark mode is the server-rendered default.
+      #
+      # Theme state lives client-side; this always returns false so the initial
+      # render is light and JS swaps the class as needed.
+      #
+      # @return [Boolean] always false
+      def dark_mode?
+        false
+      end
+
+      # Render the scrollable, centered page content wrapper.
+      #
+      # @yield the page body content
+      # @return [ActiveSupport::SafeBuffer] the container markup
+      def page_container(&block)
+        tag.div(class: 'overflow-y-auto flex-1') do
+          tag.div(class: 'p-6 pb-16 max-w-4xl mx-auto', &block)
+        end
+      end
+
+      # Render a centered empty-state container.
+      #
+      # @yield the empty-state message
+      # @return [ActiveSupport::SafeBuffer] the empty-state markup
+      def page_empty(&)
+        tag.div(class: 'flex h-full items-center justify-center text-sm', style: 'color: var(--text-faint)', &)
+      end
+
+      # Render a card summarizing a topic with an optional "Learn more" link.
+      #
+      # @param title [String] the card title
+      # @param description [String] the card body text
+      # @param href [String, nil] optional link target for "Learn more"
+      # @return [ActiveSupport::SafeBuffer] the card markup
+      def grid_card(title, description, href: nil)
+        tag.div(class: 'rounded-xl p-5',
+                style: 'background: var(--surface); border: 1px solid var(--border)') do
+          tag.div(class: 'mb-1') { heading_3(title) } +
+            tag.p(description, class: 'text-xs leading-relaxed') +
+            (href ? tag.div(class: 'mt-3') { ui_link('Learn more', href, target: '_blank') } : ''.html_safe)
+        end
+      end
+
+      # Render a responsive grid wrapper with one, two, or three columns.
+      #
+      # @param cols [Integer] the column count (1, 2, or 3)
+      # @yield the grid items
+      # @return [ActiveSupport::SafeBuffer] the grid markup
+      def grid_container(cols: 2, &)
+        col_class = { 1 => 'grid-cols-1', 2 => 'grid-cols-2', 3 => 'grid-cols-3' }[cols]
+        tag.div(class: "grid #{col_class} gap-4", &)
+      end
+
+      # A drag handle laid over a resizable container's edge. The +resize-handle+ class draws the divider
+      # line and its hover affordance (see tailwind/application.css); this element is the invisible grab
+      # strip +resize.js+ listens on. The container itself carries the +data-resize*+ attributes.
+      #
+      # @param edge [Symbol] which edge the handle sits on — +:left+ (default), +:right+, or +:top+
+      # @return [ActiveSupport::SafeBuffer] the handle markup
+      def resize_handle(edge: :left)
+        variant = { right: ' resize-handle--right', top: ' resize-handle--top' }[edge].to_s
+        tag.div('', class: "resize-handle#{variant}", data: { resize_handle: '' })
+      end
+    end
+  end
+end