markdown_exec 2.0.5 → 2.0.7

data/lib/hash_delegator.rb

@@ -200,7 +200,7 @@ module HashDelegatorSelf
 
     # Determine the state of breaker based on was_using_cli and the block type
     # true only when block_name is nil, block_name_from_cli is false, was_using_cli is true, and the block_state.block[:shell] equals BlockType::BASH. In all other scenarios, breaker is false.
-    breaker = !block_name && !block_name_from_cli && was_using_cli && block_state.block[:shell] == BlockType::BASH
+    breaker = !block_name && !block_name_from_cli && was_using_cli && block_state.block.fetch(:shell, nil) == BlockType::BASH
 
     # Reset block_name_from_cli if the conditions are not met
     block_name_from_cli ||= false
@@ -252,14 +252,16 @@ module HashDelegatorSelf
 
     # # Sanitize input (example: removing potentially harmful characters)
     # str = str.gsub(/[^0-9\+\-\*\/\(\)\<\>\!\=\%\&\|]/, '')
-
     # Evaluate the sanitized string
     result = nil
     binding.eval("result = #{str}")
 
     result
   rescue StandardError # catches NameError, StandardError
+    pp $!, $@
+    pp "code: #{str}"
     error_handler('safeval')
+    exit 1
   end
 
   # # Evaluates the given string as Ruby code and rescues any StandardErrors.
@@ -311,11 +313,11 @@ module HashDelegatorSelf
     File.write(
       filespec,
       ["-STDOUT-\n",
-       format_execution_streams(ExecutionStreams::StdOut, files),
+       format_execution_streams(ExecutionStreams::STD_OUT, files),
        "-STDERR-\n",
-       format_execution_streams(ExecutionStreams::StdErr, files),
+       format_execution_streams(ExecutionStreams::STD_ERR, files),
        "-STDIN-\n",
-       format_execution_streams(ExecutionStreams::StdIn, files),
+       format_execution_streams(ExecutionStreams::STD_IN, files),
        "\n"].join
     )
   end
@@ -387,7 +389,7 @@ module PathUtils
   # @param expression [String] The expression where a wildcard '*' is replaced by the path if it's not absolute.
   # @return [String] The absolute path or the expression with the wildcard replaced by the path.
   def self.resolve_path_or_substitute(path, expression)
-    if path.include?('/')
+    if path.start_with?('/')
       path
     else
       expression.gsub('*', path)
@@ -412,6 +414,74 @@ class BashCommentFormatter
   # end
 end
 
+class StringWrapper
+  attr_reader :width, :left_margin, :right_margin, :indent, :fill_margin
+
+  # Initializes the StringWrapper with the given options.
+  #
+  # @param width [Integer] the maximum width of each line
+  # @param left_margin [Integer] the number of spaces for the left margin
+  # @param right_margin [Integer] the number of spaces for the right margin
+  # @param indent [Integer] the number of spaces to indent all but the first line
+  # @param fill_margin [Boolean] whether to fill the left margin with spaces
+  def initialize(
+    width:,
+    fill_margin: false,
+    first_indent: '',
+    indent_space: '  ',
+    left_margin: 0,
+    margin_char: ' ',
+    rest_indent: '',
+    right_margin: 0
+  )
+    @fill_margin = fill_margin
+    @first_indent = first_indent
+    @indent = indent
+    @indent_space = indent_space
+    @rest_indent = rest_indent
+    @right_margin = right_margin
+    @width = width
+
+    @margin_space = fill_margin ? (margin_char * left_margin) : ''
+    @left_margin = @margin_space.length
+  end
+
+  # Wraps the given text according to the specified options.
+  #
+  # @param text [String] the text to wrap
+  # @return [String] the wrapped text
+  def wrap(text)
+    text = text.dup if text.frozen?
+    max_line_length = width - left_margin - right_margin - @indent_space.length
+    lines = []
+    current_line = String.new
+
+    words = text.split
+    words.each.with_index do |word, index|
+      trial_length = word.length
+      trial_length += @first_indent.length if index.zero?
+      trial_length += current_line.length + 1 + @rest_indent.length if index != 0
+      if trial_length > max_line_length && (words.count != 0)
+        lines << current_line
+        current_line = word
+        current_line = current_line.dup if current_line.frozen?
+      else
+        current_line << ' ' unless current_line.empty?
+        current_line << word
+      end
+    end
+    lines << current_line unless current_line.empty?
+
+    lines.map.with_index do |line, index|
+      @margin_space + if index.zero?
+                        @first_indent
+                      else
+                        @rest_indent
+                      end + line
+    end
+  end
+end
+
 module MarkdownExec
   class DebugHelper
     # Class-level variable to store history of printed messages
@@ -509,9 +579,24 @@ module MarkdownExec
         history_state_partition
         option_name = @delegate_object[:menu_option_back_name]
         insert_at_top = @delegate_object[:menu_back_at_top]
+      when MenuState::EDIT
+        option_name = @delegate_object[:menu_option_edit_name]
+        insert_at_top = @delegate_object[:menu_load_at_top]
       when MenuState::EXIT
         option_name = @delegate_object[:menu_option_exit_name]
         insert_at_top = @delegate_object[:menu_exit_at_top]
+      when MenuState::LOAD
+        option_name = @delegate_object[:menu_option_load_name]
+        insert_at_top = @delegate_object[:menu_load_at_top]
+      when MenuState::SAVE
+        option_name = @delegate_object[:menu_option_save_name]
+        insert_at_top = @delegate_object[:menu_load_at_top]
+      when MenuState::SHELL
+        option_name = @delegate_object[:menu_option_shell_name]
+        insert_at_top = @delegate_object[:menu_load_at_top]
+      when MenuState::VIEW
+        option_name = @delegate_object[:menu_option_view_name]
+        insert_at_top = @delegate_object[:menu_load_at_top]
       end
 
       formatted_name = format(@delegate_object[:menu_link_format],
@@ -519,7 +604,7 @@ module MarkdownExec
       chrome_block = FCB.new(
         chrome: true,
         dname: HashDelegator.new(@delegate_object).string_send_color(
-          formatted_name, :menu_link_color
+          formatted_name, :menu_chrome_color
         ),
         oname: formatted_name
       )
@@ -607,6 +692,8 @@ module MarkdownExec
     #
     # @return [Array<FCB>] An array of FCB objects representing the blocks.
     def blocks_from_nested_files
+      register_console_attributes(@delegate_object)
+
       blocks = []
       iter_blocks_from_nested_files do |btype, fcb|
         process_block_based_on_type(blocks, btype, fcb)
@@ -617,6 +704,20 @@ module MarkdownExec
       HashDelegator.error_handler('blocks_from_nested_files')
     end
 
+    # find a block by its original (undecorated) name or nickname (not visible in menu)
+    # if matched, the block returned has properties that it is from cli and not ui
+    def block_state_for_name_from_cli(block_name)
+      SelectedBlockMenuState.new(
+        @dml_blocks_in_file.find do |item|
+          block_name == item.pub_name
+        end&.merge(
+          block_name_from_cli: true,
+          block_name_from_ui: false
+        ),
+        MenuState::CONTINUE
+      )
+    end
+
     # private
 
     def calc_logged_stdout_filename(block_name:)
@@ -663,7 +764,7 @@ module MarkdownExec
     # @return [Array<String>] Required code blocks as an array of lines.
     def collect_required_code_lines(mdoc:, selected:, block_source:, link_state: LinkState.new)
       required = mdoc.collect_recursively_required_code(
-        anyname: selected[:nickname] || selected[:oname],
+        anyname: selected.pub_name,
         label_format_above: @delegate_object[:shell_code_label_format_above],
         label_format_below: @delegate_object[:shell_code_label_format_below],
         block_source: block_source
@@ -701,47 +802,15 @@ module MarkdownExec
         system(
           format(
             @delegate_object[:execute_command_format],
-            {
-              batch_index: @run_state.batch_index,
-              batch_random: @run_state.batch_random,
-              block_name: @delegate_object[:block_name],
-              document_filename: File.basename(@delegate_object[:filename]),
-              document_filespec: @delegate_object[:filename],
-              home: Dir.pwd,
-              output_filename: File.basename(@delegate_object[:logged_stdout_filespec]),
-              output_filespec: @delegate_object[:logged_stdout_filespec],
-              script_filename: @run_state.saved_filespec,
-              script_filespec: File.join(Dir.pwd, @run_state.saved_filespec),
-              started_at: @run_state.started_at.strftime(
-                @delegate_object[:execute_command_title_time_format]
-              )
-            }
+            command_execute_in_own_window_format_arguments
           )
         )
 
       else
         @run_state.in_own_window = false
-        Open3.popen3(@delegate_object[:shell],
-                     '-c', command,
-                     @delegate_object[:filename],
-                     *args) do |stdin, stdout, stderr, exec_thr|
-          handle_stream(stream: stdout, file_type: ExecutionStreams::StdOut) do |line|
-            yield nil, line, nil, exec_thr if block_given?
-          end
-          handle_stream(stream: stderr, file_type: ExecutionStreams::StdErr) do |line|
-            yield nil, nil, line, exec_thr if block_given?
-          end
-
-          in_thr = handle_stream(stream: $stdin, file_type: ExecutionStreams::StdIn) do |line|
-            stdin.puts(line)
-            yield line, nil, nil, exec_thr if block_given?
-          end
-
-          wait_for_stream_processing
-          exec_thr.join
-          sleep 0.1
-          in_thr.kill if in_thr&.alive?
-        end
+        execute_command_with_streams(
+          [@delegate_object[:shell], '-c', command, @delegate_object[:filename], *args]
+        )
       end
 
       @run_state.completed_at = Time.now.utc
@@ -750,32 +819,33 @@ module MarkdownExec
       @run_state.aborted_at = Time.now.utc
       @run_state.error_message = err.message
       @run_state.error = err
-      @run_state.files[ExecutionStreams::StdErr] += [@run_state.error_message]
+      @run_state.files[ExecutionStreams::STD_ERR] += [@run_state.error_message]
       @fout.fout "Error ENOENT: #{err.inspect}"
     rescue SignalException => err
       # Handle SignalException
       @run_state.aborted_at = Time.now.utc
       @run_state.error_message = 'SIGTERM'
       @run_state.error = err
-      @run_state.files[ExecutionStreams::StdErr] += [@run_state.error_message]
+      @run_state.files[ExecutionStreams::STD_ERR] += [@run_state.error_message]
       @fout.fout "Error ENOENT: #{err.inspect}"
     end
 
-    def load_cli_or_user_selected_block(all_blocks: [], menu_blocks: [], default: nil)
-      if @delegate_object[:block_name].present?
-        block = all_blocks.find do |item|
-          item[:oname] == @delegate_object[:block_name]
-        end&.merge(block_name_from_ui: false)
-      else
-        block_state = wait_for_user_selected_block(all_blocks, menu_blocks,
-                                                   default)
-        block = block_state.block&.merge(block_name_from_ui: true)
-        state = block_state.state
-      end
-
-      SelectedBlockMenuState.new(block, state)
-    rescue StandardError
-      HashDelegator.error_handler('load_cli_or_user_selected_block')
+    def command_execute_in_own_window_format_arguments(home: Dir.pwd)
+      {
+        batch_index: @run_state.batch_index,
+        batch_random: @run_state.batch_random,
+        block_name: @delegate_object[:block_name],
+        document_filename: File.basename(@delegate_object[:filename]),
+        document_filespec: @delegate_object[:filename],
+        home: home,
+        output_filename: File.basename(@delegate_object[:logged_stdout_filespec]),
+        output_filespec: @delegate_object[:logged_stdout_filespec],
+        script_filename: @run_state.saved_filespec,
+        script_filespec: File.join(home, @run_state.saved_filespec),
+        started_at: @run_state.started_at.strftime(
+          @delegate_object[:execute_command_title_time_format]
+        )
+      }
     end
 
     # This method is responsible for handling the execution of generic blocks in a markdown document.
@@ -799,7 +869,12 @@ module MarkdownExec
       execute_required_lines(required_lines: required_lines, selected: selected) if allow_execution
 
       link_state.block_name = nil
-      LoadFileLinkState.new(LoadFile::Reuse, link_state)
+      LoadFileLinkState.new(LoadFile::REUSE, link_state)
+    end
+
+    # Check if the expression contains wildcard characters
+    def contains_wildcards?(expr)
+      expr.match(%r{\*|\?|\[})
     end
 
     def copy_to_clipboard(required_lines)
@@ -828,16 +903,70 @@ module MarkdownExec
     # @param match_data [MatchData] The match data containing named captures for formatting.
     # @param format_option [String] The format string to be used for the new block.
     # @param color_method [Symbol] The color method to apply to the block's display name.
-    def create_and_add_chrome_block(blocks:, match_data:, format_option:,
-                                    color_method:)
-      oname = format(format_option,
-                     match_data.named_captures.transform_keys(&:to_sym))
-      blocks.push FCB.new(
-        chrome: true,
-        disabled: '',
-        dname: oname.send(color_method),
-        oname: oname
-      )
+    # return number of lines added
+    def create_and_add_chrome_block(blocks:, match_data:,
+                                    format_option:, color_method:,
+                                    case_conversion: nil,
+                                    center: nil,
+                                    wrap: nil)
+      line_cap = match_data.named_captures.transform_keys(&:to_sym)
+
+      # replace tabs in indent
+      line_cap[:indent] ||= ''
+      line_cap[:indent] = line_cap[:indent].dup if line_cap[:indent].frozen?
+      line_cap[:indent].gsub!("\t", '    ')
+      # replace tabs in text
+      line_cap[:text] ||= ''
+      line_cap[:text] = line_cap[:text].dup if line_cap[:text].frozen?
+      line_cap[:text].gsub!("\t", '    ')
+      # missing capture
+      line_cap[:line] ||= ''
+
+      accepted_width = @delegate_object[:console_width] - 2
+      line_caps = if wrap
+                    if line_cap[:text].length > accepted_width
+                      wrapper = StringWrapper.new(width: accepted_width - line_cap[:indent].length)
+                      wrapper.wrap(line_cap[:text]).map do |line|
+                        line_cap.dup.merge(text: line)
+                      end
+                    else
+                      [line_cap]
+                    end
+                  else
+                    [line_cap]
+                  end
+      if center
+        line_caps.each do |line_obj|
+          line_obj[:indent] = if line_obj[:text].length < accepted_width
+                                ' ' * ((accepted_width - line_obj[:text].length) / 2)
+                              else
+                                ''
+                              end
+        end
+      end
+
+      line_caps.each do |line_obj|
+        next if line_obj[:text].nil?
+
+        case case_conversion
+        when :upcase
+          line_obj[:text].upcase!
+        when :downcase
+          line_obj[:text].downcase!
+        end
+
+        # format expects :line to be text only
+        line_obj[:line] = line_obj[:text]
+        oname = format(format_option, line_obj)
+        line_obj[:line] = line_obj[:indent] + line_obj[:text]
+        blocks.push FCB.new(
+          chrome: true,
+          disabled: '',
+          dname: line_obj[:indent] + oname.send(color_method),
+          oname: line_obj[:text]
+        )
+      end
+      line_caps.count
     end
 
     ##
@@ -848,12 +977,12 @@ module MarkdownExec
     # @param use_chrome [Boolean] Indicates if the chrome styling should be applied.
     def create_and_add_chrome_blocks(blocks, fcb)
       match_criteria = [
-        { color: :menu_heading1_color, format: :menu_heading1_format, match: :heading1_match },
-        { color: :menu_heading2_color, format: :menu_heading2_format, match: :heading2_match },
-        { color: :menu_heading3_color, format: :menu_heading3_format, match: :heading3_match },
+        { color: :menu_heading1_color, format: :menu_heading1_format, match: :heading1_match, center: true, case_conversion: :upcase, wrap: true },
+        { color: :menu_heading2_color, format: :menu_heading2_format, match: :heading2_match, center: true, wrap: true },
+        { color: :menu_heading3_color, format: :menu_heading3_format, match: :heading3_match, center: true, case_conversion: :downcase, wrap: true },
         { color: :menu_divider_color,  format: :menu_divider_format,  match: :menu_divider_match },
-        { color: :menu_note_color,     format: :menu_note_format,     match: :menu_note_match },
-        { color: :menu_task_color,     format: :menu_task_format,     match: :menu_task_match }
+        { color: :menu_note_color,     format: :menu_note_format,     match: :menu_note_match, wrap: true },
+        { color: :menu_task_color,     format: :menu_task_format,     match: :menu_task_match, wrap: true }
       ]
       # rubocop:enable Style/UnlessElse
       match_criteria.each do |criteria|
@@ -864,9 +993,12 @@ module MarkdownExec
 
         create_and_add_chrome_block(
           blocks: blocks,
-          match_data: mbody,
+          case_conversion: criteria[:case_conversion],
+          center: criteria[:center],
+          color_method: @delegate_object[criteria[:color]].to_sym,
           format_option: @delegate_object[criteria[:format]],
-          color_method: @delegate_object[criteria[:color]].to_sym
+          match_data: mbody,
+          wrap: criteria[:wrap]
         )
         break
       end
@@ -950,164 +1082,495 @@ module MarkdownExec
                                                    @delegate_object[:logged_stdout_filespec])
     end
 
-    # Executes a block of code that has been approved for execution.
-    # It sets the script block name, writes command files if required, and handles the execution
-    # including output formatting and summarization.
-    #
-    # @param required_lines [Array<String>] The lines of code to be executed.
-    # @param selected [FCB] The selected functional code block object.
-    def execute_required_lines(required_lines: [], selected: FCB.new)
-      write_command_file(required_lines: required_lines, selected: selected) if @delegate_object[:save_executed_script]
-      calc_logged_stdout_filename(block_name: @dml_block_state.block[:oname]) if @dml_block_state
-      format_and_execute_command(code_lines: required_lines)
-      post_execution_process
-    end
-
-    # Execute a code block after approval and provide user interaction options.
-    #
-    # This method displays required code blocks, asks for user approval, and
-    # executes the code block if approved. It also allows users to copy the
-    # code to the clipboard or save it to a file.
+    # Select and execute a code block from a Markdown document.
     #
-    # @param opts [Hash] Options hash containing configuration settings.
-    # @param mdoc [YourMDocClass] An instance of the MDoc class.
+    # This method allows the user to interactively select a code block from a
+    # Markdown document, obtain approval, and execute the chosen block of code.
     #
-    def execute_shell_type(selected:, mdoc:, block_source:, link_state: LinkState.new)
-      if selected.fetch(:shell, '') == BlockType::LINK
-        debounce_reset
-        push_link_history_and_trigger_load(link_block_body: selected.fetch(:body, ''),
-                                           mdoc: mdoc,
-                                           selected: selected,
-                                           link_state: link_state,
-                                           block_source: block_source)
+    # @return [Nil] Returns nil if no code block is selected or an error occurs.
+    def document_inpseq
+      @menu_base_options = @delegate_object
+      @dml_link_state = LinkState.new(
+        block_name: @delegate_object[:block_name],
+        document_filename: @delegate_object[:filename]
+      )
+      # @dml_link_state_block_name_from_cli = @dml_link_state.block_name.present? ###
+      @run_state.block_name_from_cli = @dml_link_state.block_name.present?
+      @cli_block_name = @dml_link_state.block_name
+      @dml_now_using_cli = @run_state.block_name_from_cli
+      @dml_menu_default_dname = nil
+      @dml_block_state = SelectedBlockMenuState.new
+      @doc_saved_lines_files = []
 
-      elsif @menu_user_clicked_back_link
-        debounce_reset
-        pop_link_history_and_trigger_load
+      ## load file with code lines per options
+      #
+      if @menu_base_options[:load_code].present?
+        @dml_link_state.inherited_lines = []
+        @menu_base_options[:load_code].split(':').map do |path|
+          @dml_link_state.inherited_lines += File.readlines(path, chomp: true)
+        end
 
-      elsif selected[:shell] == BlockType::OPTS
-        debounce_reset
-        block_names = []
-        code_lines = []
-        dependencies = {}
-        options_state = read_show_options_and_trigger_reuse(selected: selected, link_state: link_state)
+        inherited_block_names = []
+        inherited_dependencies = {}
+        selected = { oname: 'load_code' }
+        pop_add_current_code_to_head_and_trigger_load(@dml_link_state, inherited_block_names, code_lines, inherited_dependencies, selected)
+      end
 
-        ## apply options to current state
-        #
-        @menu_base_options.merge!(options_state.options)
-        @delegate_object.merge!(options_state.options)
+      item_back = format(@delegate_object[:menu_link_format], HashDelegator.safeval(@delegate_object[:menu_option_back_name]))
+      item_edit = format(@delegate_object[:menu_link_format], HashDelegator.safeval(@delegate_object[:menu_option_edit_name]))
+      item_load = format(@delegate_object[:menu_link_format], HashDelegator.safeval(@delegate_object[:menu_option_load_name]))
+      item_save = format(@delegate_object[:menu_link_format], HashDelegator.safeval(@delegate_object[:menu_option_save_name]))
+      item_shell = format(@delegate_object[:menu_link_format], HashDelegator.safeval(@delegate_object[:menu_option_shell_name]))
+      item_view = format(@delegate_object[:menu_link_format], HashDelegator.safeval(@delegate_object[:menu_option_view_name]))
 
-        ### options_state.load_file_link_state
-        link_state = LinkState.new
-        link_history_push_and_next(
-          curr_block_name: selected[:oname],
-          curr_document_filename: @delegate_object[:filename],
-          inherited_block_names: ((link_state&.inherited_block_names || []) + block_names).sort.uniq,
-          inherited_dependencies: (link_state&.inherited_dependencies || {}).merge(dependencies || {}), ### merge, not replace, key data
-          inherited_lines: HashDelegator.code_merge(link_state&.inherited_lines, code_lines),
-          next_block_name: '',
-          next_document_filename: @delegate_object[:filename],
-          next_load_file: LoadFile::Reuse
-        )
+      @run_state.batch_random = Random.new.rand
+      @run_state.batch_index = 0
 
-      elsif selected[:shell] == BlockType::VARS
-        debounce_reset
-        block_names = []
-        code_lines = set_environment_variables_for_block(selected)
-        dependencies = {}
-        link_history_push_and_next(
-          curr_block_name: selected[:oname],
-          curr_document_filename: @delegate_object[:filename],
-          inherited_block_names: ((link_state&.inherited_block_names || []) + block_names).sort.uniq,
-          inherited_dependencies: (link_state&.inherited_dependencies || {}).merge(dependencies || {}), ### merge, not replace, key data
-          inherited_lines: HashDelegator.code_merge(link_state&.inherited_lines, code_lines),
-          next_block_name: '',
-          next_document_filename: @delegate_object[:filename],
-          next_load_file: LoadFile::Reuse
-        )
+      InputSequencer.new(
+        @delegate_object[:filename],
+        @delegate_object[:input_cli_rest]
+      ).run do |msg, data|
+        case msg
+        when :parse_document # once for each menu
+          # puts "@ - parse document #{data}"
+          inpseq_parse_document(data)
 
-      elsif debounce_allows
-        compile_execute_and_trigger_reuse(mdoc: mdoc,
-                                          selected: selected,
-                                          link_state: link_state,
-                                          block_source: block_source)
+          if @delegate_object[:menu_for_saved_lines] && @delegate_object[:document_saved_lines_glob].present?
 
-      else
-        LoadFileLinkState.new(LoadFile::Reuse, link_state)
-      end
-    end
+            sf = document_name_in_glob_as_file_name(@dml_link_state.document_filename, @delegate_object[:document_saved_lines_glob])
+            files = sf ? Dir.glob(sf) : []
+            @doc_saved_lines_files = files.count.positive? ? files : []
 
-    # Retrieves a specific data symbol from the delegate object, converts it to a string,
-    # and applies a color style based on the specified color symbol.
-    #
-    # @param default [String] The default value if the data symbol is not found.
-    # @param data_sym [Symbol] The symbol key to fetch data from the delegate object.
-    # @param color_sym [Symbol] The symbol key to fetch the color option for styling.
-    # @return [String] The color-styled string.
-    def fetch_color(default: '',
-                    data_sym: :execution_report_preview_head,
-                    color_sym: :execution_report_preview_frame_color)
-      data_string = @delegate_object.fetch(data_sym, default).to_s
-      string_send_color(data_string, color_sym)
-    end
+            lines_count = @dml_link_state.inherited_lines&.count || 0
 
-    def format_and_execute_command(code_lines:)
-      formatted_command = code_lines.flatten.join("\n")
-      @fout.fout fetch_color(data_sym: :script_execution_head,
-                             color_sym: :script_execution_frame_color)
-      command_execute(formatted_command, args: @pass_args)
-      @fout.fout fetch_color(data_sym: :script_execution_tail,
-                             color_sym: :script_execution_frame_color)
-    end
+            # add menu items (glob, load, save) and enable selectively
+            menu_add_disabled_option(sf) if files.count.positive? || lines_count.positive?
+            menu_enable_option(format(@delegate_object[:menu_link_format], HashDelegator.safeval(@delegate_object[:menu_option_load_name])), files.count, 'files', menu_state: MenuState::LOAD) if files.count.positive?
+            menu_enable_option(format(@delegate_object[:menu_link_format], HashDelegator.safeval(@delegate_object[:menu_option_edit_name])), lines_count, 'lines', menu_state: MenuState::EDIT) if lines_count.positive?
+            menu_enable_option(format(@delegate_object[:menu_link_format], HashDelegator.safeval(@delegate_object[:menu_option_save_name])), 1, '', menu_state: MenuState::SAVE) if lines_count.positive?
+            menu_enable_option(format(@delegate_object[:menu_link_format], HashDelegator.safeval(@delegate_object[:menu_option_view_name])), 1, '', menu_state: MenuState::VIEW) if lines_count.positive?
+            menu_enable_option(format(@delegate_object[:menu_link_format], HashDelegator.safeval(@delegate_object[:menu_option_shell_name])), 1, '', menu_state: MenuState::SHELL) if @delegate_object[:menu_with_shell]
+          end
 
-    # Formats a string based on a given context and applies color styling to it.
-    # It retrieves format and color information from the delegate object and processes accordingly.
-    #
-    # @param default [String] The default value if the format symbol is not found (unused in current implementation).
-    # @param context [Hash] Contextual data used for string formatting.
-    # @param format_sym [Symbol] Symbol key to fetch the format string from the delegate object.
-    # @param color_sym [Symbol] Symbol key to fetch the color option for string styling.
-    # @return [String] The formatted and color-styled string.
-    def format_references_send_color(default: '', context: {},
-                                     format_sym: :output_execution_label_format,
-                                     color_sym: :execution_report_preview_frame_color)
-      formatted_string = format(@delegate_object.fetch(format_sym, ''),
-                                context).to_s
-      string_send_color(formatted_string, color_sym)
-    end
+        when :display_menu
+          # warn "@ - display menu:"
+          # ii_display_menu
+          @dml_block_state = SelectedBlockMenuState.new
+          @delegate_object[:block_name] = nil
 
-    # Processes a block to generate its summary, modifying its attributes based on various matching criteria.
-    # It handles special formatting for bash blocks, extracting and setting properties like call, stdin, stdout, and dname.
-    #
-    # @param fcb [Object] An object representing a functional code block.
-    # @return [Object] The modified functional code block with updated summary attributes.
-    def get_block_summary(fcb)
-      return fcb unless @delegate_object[:bash]
+        when :user_choice
+          if @dml_link_state.block_name.present?
+            # @prior_block_was_link = true
+            @dml_block_state.block = @dml_blocks_in_file.find do |item|
+              item.pub_name == @dml_link_state.block_name
+            end
+            @dml_link_state.block_name = nil
+          else
+            # puts "? - Select a block to execute (or type #{$texit} to exit):"
+            break if inpseq_user_choice == :break # into @dml_block_state
+            break if @dml_block_state.block.nil? # no block matched
+          end
+          # puts "! - Executing block: #{data}"
+          @dml_block_state.block&.pub_name
 
-      fcb.call = fcb.title.match(Regexp.new(@delegate_object[:block_calls_scan]))&.fetch(1, nil)
-      titlexcall = fcb.call ? fcb.title.sub("%#{fcb.call}", '') : fcb.title
-      bm = extract_named_captures_from_option(titlexcall,
-                                              @delegate_object[:block_name_match])
+        when :execute_block
+          case (block_name = data)
+          when item_back
+            debounce_reset
+            @menu_user_clicked_back_link = true
+            load_file_link_state = pop_link_history_and_trigger_load
+            @dml_link_state = load_file_link_state.link_state
 
-      fcb.stdin = extract_named_captures_from_option(titlexcall,
-                                                     @delegate_object[:block_stdin_scan])
-      fcb.stdout = extract_named_captures_from_option(titlexcall,
-                                                      @delegate_object[:block_stdout_scan])
+            InputSequencer.merge_link_state(
+              @dml_link_state,
+              InputSequencer.next_link_state(
+                block_name: @dml_link_state.block_name,
+                document_filename: @dml_link_state.document_filename,
+                prior_block_was_link: true
+              )
+            )
 
-      shell_color_option = SHELL_COLOR_OPTIONS[fcb[:shell]]
+          when item_edit
+            debounce_reset
+            edited = edit_text(@dml_link_state.inherited_lines.join("\n"))
+            @dml_link_state.inherited_lines = edited.split("\n") if edited
+            InputSequencer.next_link_state(prior_block_was_link: true)
 
-      if @delegate_object[:block_name_nick_match].present? && fcb.oname =~ Regexp.new(@delegate_object[:block_name_nick_match])
-        fcb.nickname = $~[0]
-        fcb.title = fcb.oname = format_multiline_body_as_title(fcb.body)
-      else
-        fcb.title = fcb.oname = bm && bm[1] ? bm[:title] : titlexcall
+          when item_load
+            debounce_reset
+            sf = document_name_in_glob_as_file_name(@dml_link_state.document_filename, @delegate_object[:document_saved_lines_glob])
+            load_filespec = load_filespec_from_expression(sf)
+            if load_filespec
+              @dml_link_state.inherited_lines ||= []
+              @dml_link_state.inherited_lines += File.readlines(load_filespec, chomp: true)
+            end
+            InputSequencer.next_link_state(prior_block_was_link: true)
+
+          when item_save
+            debounce_reset
+            sf = document_name_in_glob_as_file_name(@dml_link_state.document_filename, @delegate_object[:document_saved_lines_glob])
+            save_filespec = save_filespec_from_expression(sf)
+            if save_filespec && !write_file_with_directory_creation(
+              save_filespec,
+              HashDelegator.join_code_lines(@dml_link_state.inherited_lines)
+            )
+              return :break
+
+            end
+            InputSequencer.next_link_state(prior_block_was_link: true)
+
+          when item_shell
+            debounce_reset
+            loop do
+              command = prompt_for_command(":MDE #{Time.now.strftime('%FT%TZ')}> ".bgreen)
+              break if !command.present? || command == 'exit'
+
+              exit_status = execute_command_with_streams(
+                [@delegate_object[:shell], '-c', command]
+              )
+              case exit_status
+              when 0
+                warn "#{'OK'.green} #{exit_status}"
+              else
+                warn "#{'ERR'.bred} #{exit_status}"
+              end
+            end
+            InputSequencer.next_link_state(prior_block_was_link: true)
+
+          when item_view
+            debounce_reset
+            warn @dml_link_state.inherited_lines.join("\n")
+            InputSequencer.next_link_state(prior_block_was_link: true)
+
+          else
+            @dml_block_state = block_state_for_name_from_cli(block_name)
+            if @dml_block_state.block && @dml_block_state.block.fetch(:shell, nil) == BlockType::OPTS
+              debounce_reset
+              link_state = LinkState.new
+              options_state = read_show_options_and_trigger_reuse(
+                selected: @dml_block_state.block,
+                link_state: link_state
+              )
+
+              @menu_base_options.merge!(options_state.options)
+              @delegate_object.merge!(options_state.options)
+              options_state.load_file_link_state.link_state
+            else
+              inpseq_execute_block(block_name)
+
+              if prompt_user_exit(block_name_from_cli: @run_state.block_name_from_cli,
+                                  selected: @dml_block_state.block)
+                return :break
+              end
+
+              ## order of block name processing: link block, cli, from user
+              #
+              @dml_link_state.block_name, @run_state.block_name_from_cli, cli_break = \
+                HashDelegator.next_link_state(
+                  block_name: @dml_link_state.block_name,
+                  block_name_from_cli: @dml_now_using_cli,
+                  block_state: @dml_block_state,
+                  was_using_cli: @dml_now_using_cli
+                )
+
+              if !@dml_block_state.block[:block_name_from_ui] && cli_break
+                # &bsp '!block_name_from_ui + cli_break -> break'
+                return :break
+              end
+
+              InputSequencer.next_link_state(
+                block_name: @dml_link_state.block_name,
+                prior_block_was_link: @dml_block_state.block.fetch(:shell, nil) != BlockType::BASH
+              )
+            end
+          end
+
+        when :exit?
+          data == $texit
+        when :stay?
+          data == $stay
+        else
+          raise "Invalid message: #{msg}"
+        end
+      end
+    rescue StandardError
+      HashDelegator.error_handler('document_inpseq',
+                                  { abort: true })
+    end
+
+    # remove leading "./"
+    # replace characters: / : . * (space) with: (underscore)
+    def document_name_in_glob_as_file_name(document_filename, glob)
+      return document_filename if document_filename.nil? || document_filename.empty?
+
+      format(glob, { document_filename: document_filename.gsub(%r{^\./}, '').gsub(/[\/:\.\* ]/, '_') })
+    end
+
+    def dump_and_warn_block_state(selected:)
+      if selected.nil?
+        Exceptions.warn_format("Block not found -- name: #{@delegate_object[:block_name]}",
+                               { abort: true })
       end
 
-      fcb.dname = HashDelegator.indent_all_lines(
-        apply_shell_color_option(fcb.oname, shell_color_option),
-        fcb.fetch(:indent, nil)
+      return unless @delegate_object[:dump_selected_block]
+
+      warn selected.to_yaml.sub(/^(?:---\n)?/, "Block:\n")
+    end
+
+    # Outputs warnings based on the delegate object's configuration
+    #
+    # @param delegate_object [Hash] The delegate object containing configuration flags.
+    # @param blocks_in_file [Hash] Hash of blocks present in the file.
+    # @param menu_blocks [Hash] Hash of menu blocks.
+    # @param link_state [LinkState] Current state of the link.
+    def dump_delobj(blocks_in_file, menu_blocks, link_state)
+      warn format_and_highlight_hash(@delegate_object, label: '@delegate_object') if @delegate_object[:dump_delegate_object]
+
+      if @delegate_object[:dump_blocks_in_file]
+        warn format_and_highlight_dependencies(compact_and_index_hash(blocks_in_file),
+                                               label: 'blocks_in_file')
+      end
+
+      if @delegate_object[:dump_menu_blocks]
+        warn format_and_highlight_dependencies(compact_and_index_hash(menu_blocks),
+                                               label: 'menu_blocks')
+      end
+
+      warn format_and_highlight_lines(link_state.inherited_block_names, label: 'inherited_block_names') if @delegate_object[:dump_inherited_block_names]
+      warn format_and_highlight_lines(link_state.inherited_dependencies, label: 'inherited_dependencies') if @delegate_object[:dump_inherited_dependencies]
+      return unless @delegate_object[:dump_inherited_lines]
+
+      warn format_and_highlight_lines(link_state.inherited_lines, label: 'inherited_lines')
+    end
+
+    # Opens text in an editor for user modification and returns the modified text.
+    #
+    # This method reads the provided text, opens it in the default editor,
+    # and allows the user to modify it. If the user makes changes, the
+    # modified text is returned. If the user exits the editor without
+    # making changes or the editor is closed abruptly, appropriate messages
+    # are displayed.
+    #
+    # @param [String] initial_text The initial text to be edited.
+    # @param [String] temp_name The base name for the temporary file (default: 'edit_text').
+    # @return [String, nil] The modified text, or nil if no changes were made or the editor was closed abruptly.
+    def edit_text(initial_text, temp_name: 'edit_text')
+      # Create a temporary file to store the initial text
+      temp_file = Tempfile.new(temp_name)
+      temp_file.write(initial_text)
+      temp_file.rewind
+
+      # Capture the modification time of the temporary file before editing
+      before_mtime = temp_file.mtime
+
+      # Open the temporary file in the default editor
+      system("#{ENV['EDITOR'] || 'vi'} #{temp_file.path}")
+
+      # Capture the exit status of the editor
+      editor_exit_status = $?.exitstatus
+
+      # Reopen the file to ensure the updated modification time is read
+      temp_file.open
+      after_mtime = temp_file.mtime
+
+      # Check if the editor was exited normally or was interrupted
+      if editor_exit_status != 0
+        warn 'The editor was closed abruptly. No changes were made.'
+        temp_file.close
+        temp_file.unlink
+        return
+      end
+
+      result_text = nil
+      # Read the file if it was modified
+      if before_mtime != after_mtime
+        temp_file.rewind
+        result_text = temp_file.read
+      end
+
+      # Remove the temporary file
+      temp_file.close
+      temp_file.unlink
+
+      result_text
+    end
+
+    def exec_bash_next_state(selected:, mdoc:, link_state:, block_source: {})
+      lfls = execute_shell_type(
+        selected: selected,
+        mdoc: mdoc,
+        link_state: link_state,
+        block_source: block_source
       )
-      fcb
+
+      # if the same menu is being displayed, collect the display name of the selected menu item for use as the default item
+      [lfls.link_state,
+       lfls.load_file == LoadFile::LOAD ? nil : selected[:dname]]
+      #.tap { |ret| pp [__FILE__,__LINE__,'exec_bash_next_state()',ret] }
+    end
+
+    # Executes a given command and processes its input, output, and error streams.
+    #
+    # @param [Array<String>] command the command to execute along with its arguments.
+    # @yield [stdin, stdout, stderr, thread] if a block is provided, it yields input, output, error lines, and the execution thread.
+    # @return [Integer] the exit status of the executed command (0 to 255).
+    #
+    # @example
+    #   status = execute_command_with_streams(['ls', '-la']) do |stdin, stdout, stderr, thread|
+    #     puts "STDOUT: #{stdout}" if stdout
+    #     puts "STDERR: #{stderr}" if stderr
+    #   end
+    #   puts "Command exited with status: #{status}"
+    def execute_command_with_streams(command)
+      exit_status = nil
+
+      Open3.popen3(*command) do |stdin, stdout, stderr, exec_thread|
+        # Handle stdout stream
+        handle_stream(stream: stdout, file_type: ExecutionStreams::STD_OUT) do |line|
+          yield nil, line, nil, exec_thread if block_given?
+        end
+
+        # Handle stderr stream
+        handle_stream(stream: stderr, file_type: ExecutionStreams::STD_ERR) do |line|
+          yield nil, nil, line, exec_thread if block_given?
+        end
+
+        # Handle stdin stream
+        input_thread = handle_stream(stream: $stdin, file_type: ExecutionStreams::STD_IN) do |line|
+          stdin.puts(line)
+          yield line, nil, nil, exec_thread if block_given?
+        end
+
+        # Wait for all streams to be processed
+        wait_for_stream_processing
+        exec_thread.join
+
+        # Ensure the input thread is killed if it's still alive
+        sleep 0.1
+        input_thread.kill if input_thread&.alive?
+
+        # Retrieve the exit status
+        exit_status = exec_thread.value.exitstatus
+      end
+
+      exit_status
+    end
+
+    # Executes a block of code that has been approved for execution.
+    # It sets the script block name, writes command files if required, and handles the execution
+    # including output formatting and summarization.
+    #
+    # @param required_lines [Array<String>] The lines of code to be executed.
+    # @param selected [FCB] The selected functional code block object.
+    def execute_required_lines(required_lines: [], selected: FCB.new)
+      write_command_file(required_lines: required_lines, selected: selected) if @delegate_object[:save_executed_script]
+      calc_logged_stdout_filename(block_name: @dml_block_state.block[:oname]) if @dml_block_state
+      format_and_execute_command(code_lines: required_lines)
+      post_execution_process
+    end
+
+    # Execute a code block after approval and provide user interaction options.
+    #
+    # This method displays required code blocks, asks for user approval, and
+    # executes the code block if approved. It also allows users to copy the
+    # code to the clipboard or save it to a file.
+    #
+    # @param opts [Hash] Options hash containing configuration settings.
+    # @param mdoc [YourMDocClass] An instance of the MDoc class.
+    #
+    def execute_shell_type(selected:, mdoc:, block_source:, link_state: LinkState.new)
+      if selected.fetch(:shell, '') == BlockType::LINK
+        debounce_reset
+        push_link_history_and_trigger_load(link_block_body: selected.fetch(:body, ''),
+                                           mdoc: mdoc,
+                                           selected: selected,
+                                           link_state: link_state,
+                                           block_source: block_source)
+
+      elsif @menu_user_clicked_back_link
+        debounce_reset
+        pop_link_history_and_trigger_load
+
+      elsif selected[:shell] == BlockType::OPTS
+        debounce_reset
+        block_names = []
+        code_lines = []
+        dependencies = {}
+        options_state = read_show_options_and_trigger_reuse(selected: selected, link_state: link_state)
+
+        ## apply options to current state
+        #
+        @menu_base_options.merge!(options_state.options)
+        @delegate_object.merge!(options_state.options)
+
+        ### options_state.load_file_link_state
+        link_state = LinkState.new
+        link_history_push_and_next(
+          curr_block_name: selected.pub_name,
+          curr_document_filename: @delegate_object[:filename],
+          inherited_block_names: ((link_state&.inherited_block_names || []) + block_names).sort.uniq,
+          inherited_dependencies: (link_state&.inherited_dependencies || {}).merge(dependencies || {}), ### merge, not replace, key data
+          inherited_lines: HashDelegator.code_merge(link_state&.inherited_lines, code_lines),
+          next_block_name: '',
+          next_document_filename: @delegate_object[:filename],
+          next_load_file: LoadFile::REUSE
+        )
+
+      elsif selected[:shell] == BlockType::VARS
+        debounce_reset
+        block_names = []
+        code_lines = set_environment_variables_for_block(selected)
+        dependencies = {}
+        link_history_push_and_next(
+          curr_block_name: selected.pub_name,
+          curr_document_filename: @delegate_object[:filename],
+          inherited_block_names: ((link_state&.inherited_block_names || []) + block_names).sort.uniq,
+          inherited_dependencies: (link_state&.inherited_dependencies || {}).merge(dependencies || {}), ### merge, not replace, key data
+          inherited_lines: HashDelegator.code_merge(link_state&.inherited_lines, code_lines),
+          next_block_name: '',
+          next_document_filename: @delegate_object[:filename],
+          next_load_file: LoadFile::REUSE
+        )
+
+      elsif debounce_allows
+        compile_execute_and_trigger_reuse(mdoc: mdoc,
+                                          selected: selected,
+                                          link_state: link_state,
+                                          block_source: block_source)
+
+      else
+        LoadFileLinkState.new(LoadFile::REUSE, link_state)
+      end
+    end
+
+    # Retrieves a specific data symbol from the delegate object, converts it to a string,
+    # and applies a color style based on the specified color symbol.
+    #
+    # @param default [String] The default value if the data symbol is not found.
+    # @param data_sym [Symbol] The symbol key to fetch data from the delegate object.
+    # @param color_sym [Symbol] The symbol key to fetch the color option for styling.
+    # @return [String] The color-styled string.
+    def fetch_color(default: '',
+                    data_sym: :execution_report_preview_head,
+                    color_sym: :execution_report_preview_frame_color)
+      data_string = @delegate_object.fetch(data_sym, default).to_s
+      string_send_color(data_string, color_sym)
+    end
+
+    def format_and_execute_command(code_lines:)
+      formatted_command = code_lines.flatten.join("\n")
+      @fout.fout fetch_color(data_sym: :script_execution_head,
+                             color_sym: :script_execution_frame_color)
+      command_execute(formatted_command, args: @pass_args)
+      @fout.fout fetch_color(data_sym: :script_execution_tail,
+                             color_sym: :script_execution_frame_color)
+    end
+
+    # Format expression using environment variables and run state
+    def format_expression(expr)
+      data = link_load_format_data
+      ENV.each { |key, value| data[key] = value }
+      format(expr, data)
     end
 
     # Formats multiline body content as a title string.
@@ -1120,6 +1583,61 @@ module MarkdownExec
       end.join("\n") + "\n"
     end
 
+    # Formats a string based on a given context and applies color styling to it.
+    # It retrieves format and color information from the delegate object and processes accordingly.
+    #
+    # @param default [String] The default value if the format symbol is not found (unused in current implementation).
+    # @param context [Hash] Contextual data used for string formatting.
+    # @param format_sym [Symbol] Symbol key to fetch the format string from the delegate object.
+    # @param color_sym [Symbol] Symbol key to fetch the color option for string styling.
+    # @return [String] The formatted and color-styled string.
+    def format_references_send_color(default: '', context: {},
+                                     format_sym: :output_execution_label_format,
+                                     color_sym: :execution_report_preview_frame_color)
+      formatted_string = format(@delegate_object.fetch(format_sym, ''),
+                                context).to_s
+      string_send_color(formatted_string, color_sym)
+    end
+
+    # Expand expression if it contains format specifiers
+    def formatted_expression(expr)
+      expr.include?('%{') ? format_expression(expr) : expr
+    end
+
+    # Processes a block to generate its summary, modifying its attributes based on various matching criteria.
+    # It handles special formatting for bash blocks, extracting and setting properties like call, stdin, stdout, and dname.
+    #
+    # @param fcb [Object] An object representing a functional code block.
+    # @return [Object] The modified functional code block with updated summary attributes.
+    def get_block_summary(fcb)
+      return fcb unless @delegate_object[:bash]
+
+      fcb.call = fcb.title.match(Regexp.new(@delegate_object[:block_calls_scan]))&.fetch(1, nil)
+      titlexcall = fcb.call ? fcb.title.sub("%#{fcb.call}", '') : fcb.title
+      bm = extract_named_captures_from_option(titlexcall,
+                                              @delegate_object[:block_name_match])
+
+      fcb.stdin = extract_named_captures_from_option(titlexcall,
+                                                     @delegate_object[:block_stdin_scan])
+      fcb.stdout = extract_named_captures_from_option(titlexcall,
+                                                      @delegate_object[:block_stdout_scan])
+
+      shell_color_option = SHELL_COLOR_OPTIONS[fcb[:shell]]
+
+      if @delegate_object[:block_name_nick_match].present? && fcb.oname =~ Regexp.new(@delegate_object[:block_name_nick_match])
+        fcb.nickname = $~[0]
+        fcb.title = fcb.oname = format_multiline_body_as_title(fcb.body)
+      else
+        fcb.title = fcb.oname = bm && bm[1] ? bm[:title] : titlexcall
+      end
+
+      fcb.dname = HashDelegator.indent_all_lines(
+        apply_shell_color_option(fcb.oname, shell_color_option),
+        fcb.fetch(:indent, nil)
+      )
+      fcb
+    end
+
     # Updates the delegate object's state based on the provided block state.
     # It sets the block name and determines if the user clicked the back link in the menu.
     #
@@ -1131,7 +1649,7 @@ module MarkdownExec
         return
       end
 
-      @delegate_object[:block_name] = block_state.block[:oname]
+      @delegate_object[:block_name] = block_state.block.pub_name
       @menu_user_clicked_back_link = block_state.state == MenuState::BACK
     end
 
@@ -1140,7 +1658,7 @@ module MarkdownExec
         Thread.new do
           stream.each_line do |line|
             line.strip!
-            @run_state.files[file_type] << line
+            @run_state.files[file_type] << line if @run_state.files
 
             if @delegate_object[:output_stdout]
               # print line
@@ -1157,21 +1675,61 @@ module MarkdownExec
       end
     end
 
-    # Initializes variables for regex and other states
-    def initial_state
-      {
-        fenced_start_and_end_regex: Regexp.new(@delegate_object.fetch(
-                                                 :fenced_start_and_end_regex, '^(?<indent> *)`{3,}'
-                                               )),
-        fenced_start_extended_regex: Regexp.new(@delegate_object.fetch(
-                                                  :fenced_start_and_end_regex, '^(?<indent> *)`{3,}'
-                                                )),
-        fcb: MarkdownExec::FCB.new,
-        in_fenced_block: false,
-        headings: []
-      }
-    end
-
+    # Initializes variables for regex and other states
+    def initial_state
+      {
+        fenced_start_and_end_regex: Regexp.new(@delegate_object.fetch(
+                                                 :fenced_start_and_end_regex, '^(?<indent> *)`{3,}'
+                                               )),
+        fenced_start_extended_regex: Regexp.new(@delegate_object.fetch(
+                                                  :fenced_start_and_end_regex, '^(?<indent> *)`{3,}'
+                                                )),
+        fcb: MarkdownExec::FCB.new,
+        in_fenced_block: false,
+        headings: []
+      }
+    end
+
+    def inpseq_execute_block(block_name)
+      @dml_block_state = block_state_for_name_from_cli(block_name)
+
+      dump_and_warn_block_state(selected: @dml_block_state.block)
+      @dml_link_state, @dml_menu_default_dname = \
+        exec_bash_next_state(
+          selected: @dml_block_state.block,
+          mdoc: @dml_mdoc,
+          link_state: @dml_link_state,
+          block_source: {
+            document_filename: @delegate_object[:filename],
+            time_now_date: Time.now.utc.strftime(@delegate_object[:shell_code_label_time_format])
+          }
+        )
+    end
+
+    def inpseq_parse_document(_document_filename)
+      @run_state.batch_index += 1
+      @run_state.in_own_window = false
+
+      # &bsp 'loop', block_name_from_cli, @cli_block_name
+      @run_state.block_name_from_cli, @dml_now_using_cli, @dml_blocks_in_file, @dml_menu_blocks, @dml_mdoc = \
+        set_delobj_menu_loop_vars(block_name_from_cli: @run_state.block_name_from_cli,
+                                  now_using_cli: @dml_now_using_cli,
+                                  link_state: @dml_link_state)
+    end
+
+    def inpseq_user_choice
+      @dml_block_state = load_cli_or_user_selected_block(all_blocks: @dml_blocks_in_file,
+                                                         menu_blocks: @dml_menu_blocks,
+                                                         default: @dml_menu_default_dname)
+      # &bsp '@run_state.block_name_from_cli:',@run_state.block_name_from_cli
+      if !@dml_block_state
+        HashDelegator.error_handler('block_state missing', { abort: true })
+      elsif @dml_block_state.state == MenuState::EXIT
+        # &bsp 'load_cli_or_user_selected_block -> break'
+        :break
+      end
+    end
+
     # Iterates through blocks in a file, applying the provided block to each line.
     # The iteration only occurs if the file exists.
     # @yield [Symbol] :filter Yields to obtain selected messages for processing.
@@ -1198,25 +1756,9 @@ module MarkdownExec
         file.write(all_code.join("\n"))
         file.rewind
 
-        if link_block_data.fetch(LinkKeys::Exec, false)
+        if link_block_data.fetch(LinkKeys::EXEC, false)
           @run_state.files = Hash.new([])
-
-          Open3.popen3(cmd) do |stdin, stdout, stderr, _exec_thr|
-            handle_stream(stream: stdout, file_type: ExecutionStreams::StdOut) do |line|
-              output_lines.push(line)
-            end
-            handle_stream(stream: stderr, file_type: ExecutionStreams::StdErr) do |line|
-              output_lines.push(line)
-            end
-
-            in_thr = handle_stream(stream: $stdin, file_type: ExecutionStreams::StdIn) do |line|
-              stdin.puts(line)
-            end
-
-            wait_for_stream_processing
-            sleep 0.1
-            in_thr.kill if in_thr&.alive?
-          end
+          execute_command_with_streams([cmd])
 
           ## select output_lines that look like assignment or match other specs
           #
@@ -1239,13 +1781,13 @@ module MarkdownExec
       label_format_below = @delegate_object[:shell_code_label_format_below]
 
       [label_format_above && format(label_format_above,
-                                    block_source.merge({ block_name: selected[:oname] }))] +
+                                    block_source.merge({ block_name: selected.pub_name }))] +
         output_lines.map do |line|
           re = Regexp.new(link_block_data.fetch('pattern', '(?<line>.*)'))
           re.gsub_format(line, link_block_data.fetch('format', '%{line}')) if re =~ line
         end.compact +
         [label_format_below && format(label_format_below,
-                                      block_source.merge({ block_name: selected[:oname] }))]
+                                      block_source.merge({ block_name: selected.pub_name }))]
     end
 
     def link_history_push_and_next(
@@ -1275,6 +1817,54 @@ module MarkdownExec
       )
     end
 
+    def link_load_format_data
+      {
+        batch_index: @run_state.batch_index,
+        batch_random: @run_state.batch_random,
+        block_name: @delegate_object[:block_name],
+        document_filename: File.basename(@delegate_object[:filename]),
+        document_filespec: @delegate_object[:filename],
+        home: Dir.pwd,
+        started_at: Time.now.utc.strftime(@delegate_object[:execute_command_title_time_format])
+      }
+    end
+
+    # Loads auto blocks based on delegate object settings and updates if new filename is detected.
+    # Executes a specified block once per filename.
+    # @param all_blocks [Array] Array of all block elements.
+    # @return [Boolean, nil] True if values were modified, nil otherwise.
+    def load_auto_opts_block(all_blocks)
+      block_name = @delegate_object[:document_load_opts_block_name]
+      return unless block_name.present? && @most_recent_loaded_filename != @delegate_object[:filename]
+
+      block = HashDelegator.block_find(all_blocks, :oname, block_name)
+      return unless block
+
+      options_state = read_show_options_and_trigger_reuse(selected: block)
+      @menu_base_options.merge!(options_state.options)
+      @delegate_object.merge!(options_state.options)
+
+      @most_recent_loaded_filename = @delegate_object[:filename]
+      true
+    end
+
+    def load_cli_or_user_selected_block(all_blocks: [], menu_blocks: [], default: nil)
+      if @delegate_object[:block_name].present?
+        block = all_blocks.find do |item|
+          item.pub_name == @delegate_object[:block_name]
+        end&.merge(block_name_from_ui: false)
+      else
+        block_state = wait_for_user_selected_block(all_blocks, menu_blocks,
+                                                   default)
+        block = block_state.block&.merge(block_name_from_ui: true)
+        state = block_state.state
+      end
+
+      SelectedBlockMenuState.new(block, state)
+    rescue StandardError
+      HashDelegator.error_handler('load_cli_or_user_selected_block')
+    end
+
     # format + glob + select for file in load block
     # name has references to ENV vars and doc and batch vars incl. timestamp
     def load_filespec_from_expression(expression)
@@ -1289,68 +1879,8 @@ module MarkdownExec
       end
     end
 
-    def save_filespec_from_expression(expression)
-      # Process expression with embedded formatting
-      formatted = formatted_expression(expression)
-
-      # Handle wildcards or direct file specification
-      if contains_wildcards?(formatted)
-        save_filespec_wildcard_expansion(formatted)
-      else
-        formatted
-      end
-    end
-
     # private
 
-    # Expand expression if it contains format specifiers
-    def formatted_expression(expr)
-      expr.include?('%{') ? format_expression(expr) : expr
-    end
-
-    # Format expression using environment variables and run state
-    def format_expression(expr)
-      data = link_load_format_data
-      ENV.each { |key, value| data[key] = value }
-      format(expr, data)
-    end
-
-    # Check if the expression contains wildcard characters
-    def contains_wildcards?(expr)
-      expr.match(%r{\*|\?|\[})
-    end
-
-    # Handle expression with wildcard characters
-    def load_filespec_wildcard_expansion(expr)
-      files = find_files(expr)
-      case files.count
-      when 0
-        HashDelegator.error_handler("no files found with '#{expr}' ", { abort: true })
-      when 1
-        files.first
-      else
-        prompt_select_code_filename(files)
-      end
-    end
-
-    # Handle expression with wildcard characters
-    # allow user to select or enter
-    def puts_gets_oprompt_(filespec)
-      puts format(@delegate_object[:prompt_show_expr_format],
-                  { expr: filespec })
-      puts @delegate_object[:prompt_enter_filespec]
-      gets.chomp
-    end
-
-    # prompt user to enter a path (i.e. containing a path separator)
-    # or name to substitute into the wildcard expression
-    def prompt_for_filespec_with_wildcard(filespec)
-      puts format(@delegate_object[:prompt_show_expr_format],
-                  { expr: filespec })
-      puts @delegate_object[:prompt_enter_filespec]
-      PathUtils.resolve_path_or_substitute(gets.chomp, filespec)
-    end
-
     # def read_block_name(line)
     #   bm = extract_named_captures_from_option(line, @delegate_object[:block_name_match])
     #   name = bm[:title]
@@ -1363,38 +1893,6 @@ module MarkdownExec
     #   name
     # end
 
-    # Handle expression with wildcard characters
-    # allow user to select or enter
-    def save_filespec_wildcard_expansion(filespec)
-      files = find_files(filespec)
-      case files.count
-      when 0
-        prompt_for_filespec_with_wildcard(filespec)
-      else
-        ## user selects from existing files or other
-        # input into path with wildcard for easy entry
-        #
-        name = prompt_select_code_filename([@delegate_object[:prompt_filespec_other]] + files)
-        if name == @delegate_object[:prompt_filespec_other]
-          prompt_for_filespec_with_wildcard(filespec)
-        else
-          name
-        end
-      end
-    end
-
-    def link_load_format_data
-      {
-        batch_index: @run_state.batch_index,
-        batch_random: @run_state.batch_random,
-        block_name: @delegate_object[:block_name],
-        document_filename: File.basename(@delegate_object[:filename]),
-        document_filespec: @delegate_object[:filename],
-        home: Dir.pwd,
-        started_at: Time.now.utc.strftime(@delegate_object[:execute_command_title_time_format])
-      }
-    end
-
     #     # Loads auto link block.
     #     def load_auto_link_block(all_blocks, link_state, mdoc, block_source:)
     #       block_name = @delegate_object[:document_load_link_block_name]
@@ -1418,23 +1916,23 @@ module MarkdownExec
     #       end
     #     end
 
-    # Loads auto blocks based on delegate object settings and updates if new filename is detected.
-    # Executes a specified block once per filename.
-    # @param all_blocks [Array] Array of all block elements.
-    # @return [Boolean, nil] True if values were modified, nil otherwise.
-    def load_auto_opts_block(all_blocks)
-      block_name = @delegate_object[:document_load_opts_block_name]
-      return unless block_name.present? && @most_recent_loaded_filename != @delegate_object[:filename]
-
-      block = HashDelegator.block_find(all_blocks, :oname, block_name)
-      return unless block
-
-      options_state = read_show_options_and_trigger_reuse(selected: block)
-      @menu_base_options.merge!(options_state.options)
-      @delegate_object.merge!(options_state.options)
-
-      @most_recent_loaded_filename = @delegate_object[:filename]
-      true
+    # Handle expression with wildcard characters
+    def load_filespec_wildcard_expansion(expr, auto_load_single: false)
+      files = find_files(expr)
+      if files.count.zero?
+        HashDelegator.error_handler("no files found with '#{expr}' ", { abort: true })
+      elsif auto_load_single && files.count == 1
+        files.first
+      else
+        ## user selects from existing files or other
+        #
+        case (name = prompt_select_code_filename([@delegate_object[:prompt_filespec_back]] + files))
+        when @delegate_object[:prompt_filespec_back]
+          # do nothing
+        else
+          name
+        end
+      end
     end
 
     def mdoc_and_blocks_from_nested_files
@@ -1458,10 +1956,37 @@ module MarkdownExec
       menu_blocks = mdoc.fcbs_per_options(@delegate_object)
       add_menu_chrome_blocks!(menu_blocks: menu_blocks, link_state: link_state)
       ### compress empty lines
-      HashDelegator.delete_consecutive_blank_lines!(menu_blocks) if true
+      HashDelegator.delete_consecutive_blank_lines!(menu_blocks)
       [all_blocks, menu_blocks, mdoc]
     end
 
+    def menu_add_disabled_option(name)
+      raise unless name.present?
+      raise if @dml_menu_blocks.nil?
+
+      block = @dml_menu_blocks.find { |item| item[:oname] == name }
+
+      # create menu item when it is needed (count > 0)
+      #
+      return unless block.nil?
+
+      # append_chrome_block(menu_blocks: @dml_menu_blocks, menu_state: MenuState::LOAD)
+      chrome_block = FCB.new(
+        chrome: true,
+        disabled: '',
+        dname: HashDelegator.new(@delegate_object).string_send_color(
+          name, :menu_inherited_lines_color
+        ),
+        oname: formatted_name
+      )
+
+      if insert_at_top
+        @dml_menu_blocks.unshift(chrome_block)
+      else
+        @dml_menu_blocks.push(chrome_block)
+      end
+    end
+
     # Formats and optionally colors a menu option based on delegate object's configuration.
     # @param option_symbol [Symbol] The symbol key for the menu option in the delegate object.
     # @return [String] The formatted and possibly colored value of the menu option.
@@ -1486,6 +2011,47 @@ module MarkdownExec
       end
     end
 
+    def menu_enable_option(name, count, type, menu_state: MenuState::LOAD)
+      raise unless name.present?
+      raise if @dml_menu_blocks.nil?
+
+      item = @dml_menu_blocks.find { |block| block[:oname] == name }
+
+      # create menu item when it is needed (count > 0)
+      #
+      if item.nil? && count.positive?
+        append_chrome_block(menu_blocks: @dml_menu_blocks, menu_state: menu_state)
+        item = @dml_menu_blocks.find { |block| block[:oname] == name }
+      end
+
+      # update item if it exists
+      #
+      return unless item
+
+      item[:dname] = type.present? ? "#{name} (#{count} #{type})" : name
+      if count.positive?
+        item.delete(:disabled)
+      else
+        item[:disabled] = ''
+      end
+    end
+
+    def manage_cli_selection_state(block_name_from_cli:, now_using_cli:, link_state:)
+      if block_name_from_cli && @cli_block_name == @menu_base_options[:menu_persist_block_name]
+        # &bsp 'pause cli control, allow user to select block'
+        block_name_from_cli = false
+        now_using_cli = false
+        @menu_base_options[:block_name] = \
+          @delegate_object[:block_name] = \
+            link_state.block_name = \
+              @cli_block_name = nil
+      end
+
+      @delegate_object = @menu_base_options.dup
+      @menu_user_clicked_back_link = false
+      [block_name_from_cli, now_using_cli]
+    end
+
     # If a method is missing, treat it as a key for the @delegate_object.
     def method_missing(method_name, *args, &block)
       if @delegate_object.respond_to?(method_name)
@@ -1567,20 +2133,20 @@ module MarkdownExec
         @link_history.push(next_state)
 
         next_state.block_name = nil
-        LoadFileLinkState.new(LoadFile::Load, next_state)
+        LoadFileLinkState.new(LoadFile::LOAD, next_state)
       else
         # no history exists; must have been called independently => retain script
         link_history_push_and_next(
-          curr_block_name: selected[:oname],
+          curr_block_name: selected.pub_name,
           curr_document_filename: @delegate_object[:filename],
           inherited_block_names: ((link_state&.inherited_block_names || []) + block_names).sort.uniq,
           inherited_dependencies: (link_state&.inherited_dependencies || {}).merge(dependencies || {}), ### merge, not replace, key data
           inherited_lines: HashDelegator.code_merge(link_state&.inherited_lines, code_lines),
-          next_block_name: '', # not link_block_data[LinkKeys::Block] || ''
+          next_block_name: '', # not link_block_data[LinkKeys::BLOCK] || ''
           next_document_filename: @delegate_object[:filename], # not next_document_filename
-          next_load_file: LoadFile::Reuse # not next_document_filename == @delegate_object[:filename] ? LoadFile::Reuse : LoadFile::Load
+          next_load_file: LoadFile::REUSE # not next_document_filename == @delegate_object[:filename] ? LoadFile::REUSE : LoadFile::LOAD
         )
-        # LoadFileLinkState.new(LoadFile::Reuse, link_state)
+        # LoadFileLinkState.new(LoadFile::REUSE, link_state)
       end
     end
 
@@ -1591,7 +2157,7 @@ module MarkdownExec
     def pop_link_history_and_trigger_load
       pop = @link_history.pop
       peek = @link_history.peek
-      LoadFileLinkState.new(LoadFile::Load, LinkState.new(
+      LoadFileLinkState.new(LoadFile::LOAD, LinkState.new(
                                               document_filename: pop.document_filename,
                                               inherited_block_names: peek.inherited_block_names,
                                               inherited_dependencies: peek.inherited_dependencies,
@@ -1705,6 +2271,32 @@ module MarkdownExec
       exit 1
     end
 
+    def prompt_for_command(prompt)
+      print prompt
+
+      gets.chomp
+    rescue Interrupt
+      nil
+    end
+
+    # Prompts the user to enter a path or name to substitute into the wildcard expression.
+    # If interrupted by the user (e.g., pressing Ctrl-C), it returns nil.
+    #
+    # @param filespec [String] the wildcard expression to be substituted
+    # @return [String, nil] the resolved path or substituted expression, or nil if interrupted
+    def prompt_for_filespec_with_wildcard(filespec)
+      puts format(@delegate_object[:prompt_show_expr_format], { expr: filespec })
+      puts @delegate_object[:prompt_enter_filespec]
+
+      begin
+        input = gets.chomp
+        PathUtils.resolve_path_or_substitute(input, filespec)
+      rescue Interrupt
+        puts "\nOperation interrupted. Returning nil."
+        nil
+      end
+    end
+
     ##
     # Presents a menu to the user for approving an action and performs additional tasks based on the selection.
     # The function provides options for approval, rejection, copying data to clipboard, or saving data to a file.
@@ -1748,38 +2340,46 @@ module MarkdownExec
       exit 1
     end
 
-    def prompt_select_continue
-      sel = @prompt.select(
-        string_send_color(@delegate_object[:prompt_after_script_execution],
+    # public
+
+    def prompt_select_code_filename(filenames)
+      @prompt.select(
+        string_send_color(@delegate_object[:prompt_select_code_file],
                           :prompt_color_after_script_execution),
         filter: true,
         quiet: true
       ) do |menu|
-        menu.choice @delegate_object[:prompt_yes]
-        menu.choice @delegate_object[:prompt_exit]
+        filenames.each do |filename|
+          menu.choice filename
+        end
       end
-      sel == @delegate_object[:prompt_exit] ? MenuState::EXIT : MenuState::CONTINUE
     rescue TTY::Reader::InputInterrupt
       exit 1
     end
-
-    # public
-
-    def prompt_select_code_filename(filenames)
-      @prompt.select(
-        string_send_color(@delegate_object[:prompt_select_code_file],
+
+    def prompt_select_continue
+      sel = @prompt.select(
+        string_send_color(@delegate_object[:prompt_after_script_execution],
                           :prompt_color_after_script_execution),
         filter: true,
         quiet: true
       ) do |menu|
-        filenames.each do |filename|
-          menu.choice filename
-        end
+        menu.choice @delegate_object[:prompt_yes]
+        menu.choice @delegate_object[:prompt_exit]
       end
+      sel == @delegate_object[:prompt_exit] ? MenuState::EXIT : MenuState::CONTINUE
     rescue TTY::Reader::InputInterrupt
       exit 1
     end
 
+    # user prompt to exit if the menu will be displayed again
+    #
+    def prompt_user_exit(block_name_from_cli:, selected:)
+      selected[:shell] == BlockType::BASH &&
+        @delegate_object[:pause_after_script_execution] &&
+        prompt_select_continue == MenuState::EXIT
+    end
+
     # Handles the processing of a link block in Markdown Execution.
     # It loads YAML data from the link_block_body content, pushes the state to history,
     # sets environment variables, and decides on the next block to load.
@@ -1796,7 +2396,7 @@ module MarkdownExec
       #
       if mdoc
         code_info = mdoc.collect_recursively_required_code(
-          anyname: selected[:oname],
+          anyname: selected.pub_name,
           label_format_above: @delegate_object[:shell_code_label_format_above],
           label_format_below: @delegate_object[:shell_code_label_format_below],
           block_source: block_source
@@ -1812,397 +2412,189 @@ module MarkdownExec
 
       # load key and values from link block into current environment
       #
-      if link_block_data[LinkKeys::Vars]
-        code_lines.push BashCommentFormatter.format_comment(selected[:oname])
-        (link_block_data[LinkKeys::Vars] || []).each do |(key, value)|
+      if link_block_data[LinkKeys::VARS]
+        code_lines.push BashCommentFormatter.format_comment(selected.pub_name)
+        (link_block_data[LinkKeys::VARS] || []).each do |(key, value)|
           ENV[key] = value.to_s
           code_lines.push(assign_key_value_in_bash(key, value))
         end
-      end
-
-      ## append blocks loaded, apply LinkKeys::Eval
-      #
-      if (load_expr = link_block_data.fetch(LinkKeys::Load, '')).present?
-        load_filespec = load_filespec_from_expression(load_expr)
-        code_lines += File.readlines(load_filespec, chomp: true) if load_filespec
-      end
-
-      # if an eval link block, evaluate code_lines and return its standard output
-      #
-      if link_block_data.fetch(LinkKeys::Eval,
-                               false) || link_block_data.fetch(LinkKeys::Exec, false)
-        code_lines = link_block_data_eval(link_state, code_lines, selected, link_block_data, block_source: block_source)
-      end
-
-      next_document_filename = write_inherited_lines_to_file(link_state, link_block_data)
-
-      if link_block_data[LinkKeys::Return]
-        pop_add_current_code_to_head_and_trigger_load(link_state, block_names, code_lines,
-                                                      dependencies, selected)
-
-      else
-        link_history_push_and_next(
-          curr_block_name: selected[:oname],
-          curr_document_filename: @delegate_object[:filename],
-          inherited_block_names: ((link_state&.inherited_block_names || []) + block_names).sort.uniq,
-          inherited_dependencies: (link_state&.inherited_dependencies || {}).merge(dependencies || {}), ### merge, not replace, key data
-          inherited_lines: HashDelegator.code_merge(link_state&.inherited_lines, code_lines),
-          next_block_name: link_block_data.fetch(LinkKeys::NextBlock,
-                                                 nil) || link_block_data[LinkKeys::Block] || '',
-          next_document_filename: next_document_filename,
-          next_load_file: next_document_filename == @delegate_object[:filename] ? LoadFile::Reuse : LoadFile::Load
-        )
-      end
-    end
-
-    # Check if the delegate object responds to a given method.
-    # @param method_name [Symbol] The name of the method to check.
-    # @param include_private [Boolean] Whether to include private methods in the check.
-    # @return [Boolean] true if the delegate object responds to the method, false otherwise.
-    def respond_to?(method_name, include_private = false)
-      if super
-        true
-      elsif @delegate_object.respond_to?(method_name, include_private)
-        true
-      elsif method_name.to_s.end_with?('=') && @delegate_object.respond_to?(:[]=, include_private)
-        true
-      else
-        @delegate_object.respond_to?(method_name, include_private)
-      end
-    end
-
-    def runtime_exception(exception_sym, name, items)
-      if @delegate_object[exception_sym] != 0
-        data = { name: name, detail: items.join(', ') }
-        warn(
-          format(
-            @delegate_object.fetch(:exception_format_name, "\n%{name}"),
-            data
-          ).send(@delegate_object.fetch(:exception_color_name, :red)) +
-          format(
-            @delegate_object.fetch(:exception_format_detail, " - %{detail}\n"),
-            data
-          ).send(@delegate_object.fetch(:exception_color_detail, :yellow))
-        )
-      end
-      return unless (@delegate_object[exception_sym]).positive?
-
-      exit @delegate_object[exception_sym]
-    end
-
-    def save_to_file(required_lines:, selected:)
-      write_command_file(required_lines: required_lines, selected: selected)
-      @fout.fout "File saved: #{@run_state.saved_filespec}"
-    end
-
-    def block_state_for_name_from_cli(block_name)
-      SelectedBlockMenuState.new(
-        @dml_blocks_in_file.find do |item|
-          item[:oname] == block_name
-        end&.merge(
-          block_name_from_cli: true,
-          block_name_from_ui: false
-        ),
-        MenuState::CONTINUE
-      )
-    end
-
-    # Select and execute a code block from a Markdown document.
-    #
-    # This method allows the user to interactively select a code block from a
-    # Markdown document, obtain approval, and execute the chosen block of code.
-    #
-    # @return [Nil] Returns nil if no code block is selected or an error occurs.
-    def document_menu_loop
-      @menu_base_options = @delegate_object
-      @dml_link_state = LinkState.new(
-        block_name: @delegate_object[:block_name],
-        document_filename: @delegate_object[:filename]
-      )
-      @run_state.block_name_from_cli = @dml_link_state.block_name.present?
-      @cli_block_name = @dml_link_state.block_name
-      @dml_now_using_cli = @run_state.block_name_from_cli
-      @dml_menu_default_dname = nil
-      @dml_block_state = SelectedBlockMenuState.new
-
-      @run_state.batch_random = Random.new.rand
-      @run_state.batch_index = 0
-
-      InputSequencer.new(
-        @delegate_object[:filename],
-        @delegate_object[:input_cli_rest]
-      ).run do |msg, data|
-        case msg
-        when :parse_document # once for each menu
-          # puts "@ - parse document #{data}"
-          ii_parse_document(data)
-
-        when :display_menu
-          # warn "@ - display menu:"
-          # ii_display_menu
-          @dml_block_state = SelectedBlockMenuState.new
-          @delegate_object[:block_name] = nil
-
-        when :user_choice
-          if @dml_link_state.block_name.present?
-            # @prior_block_was_link = true
-            @dml_block_state.block = @dml_blocks_in_file.find do |item|
-              item[:oname] == @dml_link_state.block_name
-            end
-            @dml_link_state.block_name = nil
-          else
-            # puts "? - Select a block to execute (or type #{$texit} to exit):"
-            break if ii_user_choice == :break # into @dml_block_state
-            break if @dml_block_state.block.nil? # no block matched
-          end
-          # puts "! - Executing block: #{data}"
-          # @dml_block_state.block[:oname]
-          @dml_block_state.block&.fetch(:oname, nil)
-
-        when :execute_block
-          block_name = data
-          if block_name == '* Back' ####
-            debounce_reset
-            @menu_user_clicked_back_link = true
-            load_file_link_state = pop_link_history_and_trigger_load
-            @dml_link_state = load_file_link_state.link_state
-
-            InputSequencer.merge_link_state(
-              @dml_link_state,
-              InputSequencer.next_link_state(
-                block_name: @dml_link_state.block_name,
-                document_filename: @dml_link_state.document_filename,
-                prior_block_was_link: true
-              )
-            )
-
-          else
-            @dml_block_state = block_state_for_name_from_cli(block_name)
-            if @dml_block_state.block[:shell] == BlockType::OPTS
-              debounce_reset
-              link_state = LinkState.new
-              options_state = read_show_options_and_trigger_reuse(
-                selected: @dml_block_state.block,
-                link_state: link_state
-              )
-
-              @menu_base_options.merge!(options_state.options)
-              @delegate_object.merge!(options_state.options)
-              options_state.load_file_link_state.link_state
-            else
-              ii_execute_block(block_name)
-
-              if prompt_user_exit(block_name_from_cli: @run_state.block_name_from_cli,
-                                  selected: @dml_block_state.block)
-                return :break
-              end
-
-              ## order of block name processing: link block, cli, from user
-              #
-              @dml_link_state.block_name, @run_state.block_name_from_cli, cli_break = \
-                HashDelegator.next_link_state(
-                  block_name: @dml_link_state.block_name,
-                  block_name_from_cli: !@dml_link_state.block_name.present?,
-                  block_state: @dml_block_state,
-                  was_using_cli: @dml_now_using_cli
-                )
-
-              if !@dml_block_state.block[:block_name_from_ui] && cli_break
-                # &bsp '!block_name_from_ui + cli_break -> break'
-                return :break
-              end
-
-              InputSequencer.next_link_state(
-                block_name: @dml_link_state.block_name,
-                prior_block_was_link: @dml_block_state.block[:shell] != BlockType::BASH
-              )
-            end
-          end
-
-        when :exit?
-          data == $texit
-        when :stay?
-          data == $stay
-        else
-          raise "Invalid message: #{msg}"
-        end
-      end
-    rescue StandardError
-      HashDelegator.error_handler('document_menu_loop',
-                                  { abort: true })
-    end
-
-    def ii_parse_document(_document_filename)
-      @run_state.batch_index += 1
-      @run_state.in_own_window = false
-
-      # &bsp 'loop', block_name_from_cli, @cli_block_name
-      @run_state.block_name_from_cli, @dml_now_using_cli, @dml_blocks_in_file, @dml_menu_blocks, @dml_mdoc = \
-        set_delobj_menu_loop_vars(block_name_from_cli: @run_state.block_name_from_cli,
-                                  now_using_cli: @dml_now_using_cli,
-                                  link_state: @dml_link_state)
-    end
-
-    def ii_user_choice
-      @dml_block_state = load_cli_or_user_selected_block(all_blocks: @dml_blocks_in_file,
-                                                         menu_blocks: @dml_menu_blocks,
-                                                         default: @dml_menu_default_dname)
-      # &bsp '@run_state.block_name_from_cli:',@run_state.block_name_from_cli
-      if !@dml_block_state
-        HashDelegator.error_handler('block_state missing', { abort: true })
-      elsif @dml_block_state.state == MenuState::EXIT
-        # &bsp 'load_cli_or_user_selected_block -> break'
-        :break
-      end
-    end
-
-    def ii_execute_block(block_name)
-      @dml_block_state = block_state_for_name_from_cli(block_name)
-
-      dump_and_warn_block_state(selected: @dml_block_state.block)
-      @dml_link_state, @dml_menu_default_dname = \
-        exec_bash_next_state(
-          selected: @dml_block_state.block,
-          mdoc: @dml_mdoc,
-          link_state: @dml_link_state,
-          block_source: {
-            document_filename: @delegate_object[:filename],
-            time_now_date: Time.now.utc.strftime(@delegate_object[:shell_code_label_time_format])
-          }
-        )
-    end
-
-    def exec_bash_next_state(selected:, mdoc:, link_state:, block_source: {})
-      lfls = execute_shell_type(
-        selected: selected,
-        mdoc: mdoc,
-        link_state: link_state,
-        block_source: block_source
-      )
-
-      # if the same menu is being displayed, collect the display name of the selected menu item for use as the default item
-      [lfls.link_state,
-       lfls.load_file == LoadFile::Load ? nil : selected[:dname]]
-    end
+      end
 
-    def set_delobj_menu_loop_vars(block_name_from_cli:, now_using_cli:, link_state:)
-      block_name_from_cli, now_using_cli = \
-        manage_cli_selection_state(block_name_from_cli: block_name_from_cli,
-                                   now_using_cli: now_using_cli,
-                                   link_state: link_state)
-      set_delob_filename_block_name(link_state: link_state,
-                                    block_name_from_cli: block_name_from_cli)
+      ## append blocks loaded, apply LinkKeys::EVAL
+      #
+      if (load_expr = link_block_data.fetch(LinkKeys::LOAD, '')).present?
+        load_filespec = load_filespec_from_expression(load_expr)
+        code_lines += File.readlines(load_filespec, chomp: true) if load_filespec
+      end
 
-      # update @delegate_object and @menu_base_options in auto_load
+      # if an eval link block, evaluate code_lines and return its standard output
       #
-      blocks_in_file, menu_blocks, mdoc = mdoc_menu_and_blocks_from_nested_files(link_state)
-      dump_delobj(blocks_in_file, menu_blocks, link_state)
+      if link_block_data.fetch(LinkKeys::EVAL,
+                               false) || link_block_data.fetch(LinkKeys::EXEC, false)
+        code_lines = link_block_data_eval(link_state, code_lines, selected, link_block_data, block_source: block_source)
+      end
 
-      [block_name_from_cli, now_using_cli, blocks_in_file, menu_blocks, mdoc]
+      next_document_filename = write_inherited_lines_to_file(link_state, link_block_data)
+
+      if link_block_data[LinkKeys::RETURN]
+        pop_add_current_code_to_head_and_trigger_load(link_state, block_names, code_lines,
+                                                      dependencies, selected)
+
+      else
+        link_history_push_and_next(
+          curr_block_name: selected.pub_name,
+          curr_document_filename: @delegate_object[:filename],
+          inherited_block_names: ((link_state&.inherited_block_names || []) + block_names).sort.uniq,
+          inherited_dependencies: (link_state&.inherited_dependencies || {}).merge(dependencies || {}), ### merge, not replace, key data
+          inherited_lines: HashDelegator.code_merge(link_state&.inherited_lines, code_lines),
+          next_block_name: link_block_data.fetch(LinkKeys::NEXT_BLOCK,
+                                                 nil) || link_block_data[LinkKeys::BLOCK] || '',
+          next_document_filename: next_document_filename,
+          next_load_file: next_document_filename == @delegate_object[:filename] ? LoadFile::REUSE : LoadFile::LOAD
+        )
+      end
     end
 
-    # user prompt to exit if the menu will be displayed again
-    #
-    def prompt_user_exit(block_name_from_cli:, selected:)
-      !block_name_from_cli &&
-        selected[:shell] == BlockType::BASH &&
-        @delegate_object[:pause_after_script_execution] &&
-        prompt_select_continue == MenuState::EXIT
+    # Handle expression with wildcard characters
+    # allow user to select or enter
+    def puts_gets_oprompt_(filespec)
+      puts format(@delegate_object[:prompt_show_expr_format],
+                  { expr: filespec })
+      puts @delegate_object[:prompt_enter_filespec]
+      gets.chomp
     end
 
-    def manage_cli_selection_state(block_name_from_cli:, now_using_cli:, link_state:)
-      if block_name_from_cli && @cli_block_name == @menu_base_options[:menu_persist_block_name]
-        # &bsp 'pause cli control, allow user to select block'
-        block_name_from_cli = false
-        now_using_cli = false
-        @menu_base_options[:block_name] = \
-          @delegate_object[:block_name] = \
-            link_state.block_name = \
-              @cli_block_name = nil
+    # Processes YAML data from the selected menu item, updating delegate objects and optionally printing formatted output.
+    # @param selected [Hash] Selected item from the menu containing a YAML body.
+    # @param tgt2 [Hash, nil] An optional target hash to update with YAML data.
+    # @return [LoadFileLinkState] An instance indicating the next action for loading files.
+    def read_show_options_and_trigger_reuse(selected:, link_state: LinkState.new)
+      obj = {}
+      data = YAML.load(selected[:body].join("\n"))
+      (data || []).each do |key, value|
+        sym_key = key.to_sym
+        obj[sym_key] = value
+
+        print_formatted_option(key, value) if @delegate_object[:menu_opts_set_format].present?
       end
 
-      @delegate_object = @menu_base_options.dup
-      @menu_user_clicked_back_link = false
-      [block_name_from_cli, now_using_cli]
+      link_state.block_name = nil
+      OpenStruct.new(options: obj,
+                     load_file_link_state: LoadFileLinkState.new(
+                       LoadFile::REUSE, link_state
+                     ))
     end
 
-    # Update the block name in the link state and delegate object.
-    #
-    # This method updates the block name based on whether it was specified
-    # through the CLI or derived from the link state.
-    #
-    # @param link_state [LinkState] The current link state object.
-    # @param block_name_from_cli [Boolean] Indicates if the block name is from CLI.
-    def set_delob_filename_block_name(link_state:, block_name_from_cli:)
-      @delegate_object[:filename] = link_state.document_filename
-      link_state.block_name = @delegate_object[:block_name] =
-        block_name_from_cli ? @cli_block_name : link_state.block_name
+    def register_console_attributes(opts)
+      unless opts[:console_width]
+        require 'io/console'
+        opts[:console_height], opts[:console_width] = opts[:console_winsize] = IO.console.winsize
+      end
+      opts[:per_page] = opts[:select_page_height] = [opts[:console_height] - 3, 4].max unless opts[:select_page_height]&.positive?
+    rescue StandardError
+      HashDelegator.error_handler('register_console_attributes', { abort: true })
     end
 
-    # Outputs warnings based on the delegate object's configuration
-    #
-    # @param delegate_object [Hash] The delegate object containing configuration flags.
-    # @param blocks_in_file [Hash] Hash of blocks present in the file.
-    # @param menu_blocks [Hash] Hash of menu blocks.
-    # @param link_state [LinkState] Current state of the link.
-    def dump_delobj(blocks_in_file, menu_blocks, link_state)
-      warn format_and_highlight_hash(@delegate_object, label: '@delegate_object') if @delegate_object[:dump_delegate_object]
-
-      if @delegate_object[:dump_blocks_in_file]
-        warn format_and_highlight_dependencies(compact_and_index_hash(blocks_in_file),
-                                               label: 'blocks_in_file')
+    # Check if the delegate object responds to a given method.
+    # @param method_name [Symbol] The name of the method to check.
+    # @param include_private [Boolean] Whether to include private methods in the check.
+    # @return [Boolean] true if the delegate object responds to the method, false otherwise.
+    def respond_to?(method_name, include_private = false)
+      if super
+        true
+      elsif @delegate_object.respond_to?(method_name, include_private)
+        true
+      elsif method_name.to_s.end_with?('=') && @delegate_object.respond_to?(:[]=, include_private)
+        true
+      else
+        @delegate_object.respond_to?(method_name, include_private)
       end
+    end
 
-      if @delegate_object[:dump_menu_blocks]
-        warn format_and_highlight_dependencies(compact_and_index_hash(menu_blocks),
-                                               label: 'menu_blocks')
+    def runtime_exception(exception_sym, name, items)
+      if @delegate_object[exception_sym] != 0
+        data = { name: name, detail: items.join(', ') }
+        warn(
+          format(
+            @delegate_object.fetch(:exception_format_name, "\n%{name}"),
+            data
+          ).send(@delegate_object.fetch(:exception_color_name, :red)) +
+          format(
+            @delegate_object.fetch(:exception_format_detail, " - %{detail}\n"),
+            data
+          ).send(@delegate_object.fetch(:exception_color_detail, :yellow))
+        )
       end
+      return unless (@delegate_object[exception_sym]).positive?
 
-      warn format_and_highlight_lines(link_state.inherited_block_names, label: 'inherited_block_names') if @delegate_object[:dump_inherited_block_names]
-      warn format_and_highlight_lines(link_state.inherited_dependencies, label: 'inherited_dependencies') if @delegate_object[:dump_inherited_dependencies]
-      return unless @delegate_object[:dump_inherited_lines]
-
-      warn format_and_highlight_lines(link_state.inherited_lines, label: 'inherited_lines')
+      exit @delegate_object[exception_sym]
     end
 
-    def dump_and_warn_block_state(selected:)
-      if selected.nil?
-        Exceptions.warn_format("Block not found -- name: #{@delegate_object[:block_name]}",
-                               { abort: true })
+    # allow user to select or enter
+    def save_filespec_from_expression(expression)
+      # Process expression with embedded formatting
+      formatted = formatted_expression(expression)
+
+      # Handle wildcards or direct file specification
+      if contains_wildcards?(formatted)
+        save_filespec_wildcard_expansion(formatted)
+      else
+        formatted
       end
+    end
 
-      return unless @delegate_object[:dump_selected_block]
+    # Handle expression with wildcard characters
+    # allow user to select or enter
+    def save_filespec_wildcard_expansion(filespec)
+      files = find_files(filespec)
+      case files.count
+      when 0
+        prompt_for_filespec_with_wildcard(filespec)
+      else
+        ## user selects from existing files or other
+        # input into path with wildcard for easy entry
+        #
+        name = prompt_select_code_filename([@delegate_object[:prompt_filespec_back], @delegate_object[:prompt_filespec_other]] + files)
+        case name
+        when @delegate_object[:prompt_filespec_back]
+          # do nothing
+        when @delegate_object[:prompt_filespec_other]
+          prompt_for_filespec_with_wildcard(filespec)
+        else
+          name
+        end
+      end
+    end
 
-      warn selected.to_yaml.sub(/^(?:---\n)?/, "Block:\n")
+    def save_to_file(required_lines:, selected:)
+      write_command_file(required_lines: required_lines, selected: selected)
+      @fout.fout "File saved: #{@run_state.saved_filespec}"
     end
 
     # Presents a TTY prompt to select an option or exit, returns metadata including option and selected
     def select_option_with_metadata(prompt_text, names, opts = {})
       ## configure to environment
       #
-      unless opts[:select_page_height].positive?
-        require 'io/console'
-        opts[:per_page] = opts[:select_page_height] = [IO.console.winsize[0] - 3, 4].max
-      end
+      register_console_attributes(opts)
 
       # crashes if all menu options are disabled
       selection = @prompt.select(prompt_text,
                                  names,
                                  opts.merge(filter: true))
-      item = names.find do |item|
+      selected_name = names.find do |item|
         if item.instance_of?(Hash)
           item[:dname] == selection
         else
           item == selection
         end
       end
-      item = { dname: item } if item.instance_of?(String)
-      unless item
+      selected_name = { dname: selected_name } if selected_name.instance_of?(String)
+      unless selected_name
         HashDelegator.error_handler('select_option_with_metadata', error: 'menu item not found')
         exit 1
       end
 
-      item.merge(
+      selected_name.merge(
         if selection == menu_chrome_colored_option(:menu_option_back_name)
           { option: selection, shell: BlockType::LINK }
         elsif selection == menu_chrome_colored_option(:menu_option_exit_name)
@@ -2217,6 +2609,35 @@ module MarkdownExec
       HashDelegator.error_handler('select_option_with_metadata')
     end
 
+    # Update the block name in the link state and delegate object.
+    #
+    # This method updates the block name based on whether it was specified
+    # through the CLI or derived from the link state.
+    #
+    # @param link_state [LinkState] The current link state object.
+    # @param block_name_from_cli [Boolean] Indicates if the block name is from CLI.
+    def set_delob_filename_block_name(link_state:, block_name_from_cli:)
+      @delegate_object[:filename] = link_state.document_filename
+      link_state.block_name = @delegate_object[:block_name] =
+        block_name_from_cli ? @cli_block_name : link_state.block_name
+    end
+
+    def set_delobj_menu_loop_vars(block_name_from_cli:, now_using_cli:, link_state:)
+      block_name_from_cli, now_using_cli = \
+        manage_cli_selection_state(block_name_from_cli: block_name_from_cli,
+                                   now_using_cli: now_using_cli,
+                                   link_state: link_state)
+      set_delob_filename_block_name(link_state: link_state,
+                                    block_name_from_cli: block_name_from_cli)
+
+      # update @delegate_object and @menu_base_options in auto_load
+      #
+      blocks_in_file, menu_blocks, mdoc = mdoc_menu_and_blocks_from_nested_files(link_state)
+      dump_delobj(blocks_in_file, menu_blocks, link_state)
+
+      [block_name_from_cli, now_using_cli, blocks_in_file, menu_blocks, mdoc]
+    end
+
     def set_environment_variables_for_block(selected)
       code_lines = []
       YAML.load(selected[:body].join("\n"))&.each do |key, value|
@@ -2352,31 +2773,12 @@ module MarkdownExec
       end
     end
 
-    # Processes YAML data from the selected menu item, updating delegate objects and optionally printing formatted output.
-    # @param selected [Hash] Selected item from the menu containing a YAML body.
-    # @param tgt2 [Hash, nil] An optional target hash to update with YAML data.
-    # @return [LoadFileLinkState] An instance indicating the next action for loading files.
-    def read_show_options_and_trigger_reuse(selected:, link_state: LinkState.new)
-      obj = {}
-      data = YAML.load(selected[:body].join("\n"))
-      (data || []).each do |key, value|
-        sym_key = key.to_sym
-        obj[sym_key] = value
-
-        print_formatted_option(key, value) if @delegate_object[:menu_opts_set_format].present?
-      end
-
-      link_state.block_name = nil
-      OpenStruct.new(options: obj,
-                     load_file_link_state: LoadFileLinkState.new(
-                       LoadFile::Reuse, link_state
-                     ))
-    end
-
     def wait_for_stream_processing
       @process_mutex.synchronize do
         @process_cv.wait(@process_mutex)
       end
+    rescue Interrupt
+      # user interrupts process
     end
 
     def wait_for_user_selected_block(all_blocks, menu_blocks, default)
@@ -2417,7 +2819,7 @@ module MarkdownExec
       time_now = Time.now.utc
       @run_state.saved_script_filename =
         SavedAsset.script_name(
-          blockname: selected[:nickname] || selected[:oname],
+          blockname: selected.pub_name,
           filename: @delegate_object[:filename],
           prefix: @delegate_object[:saved_script_filename_prefix],
           time: time_now
@@ -2447,14 +2849,34 @@ module MarkdownExec
       HashDelegator.error_handler('write_command_file')
     end
 
+    # Ensure the directory exists before writing the file
+    def write_file_with_directory_creation(save_filespec, content)
+      directory = File.dirname(save_filespec)
+
+      begin
+        FileUtils.mkdir_p(directory)
+        File.write(save_filespec, content)
+      rescue Errno::EACCES
+        warn "Permission denied: Unable to write to file '#{save_filespec}'"
+        nil
+      rescue Errno::EROFS
+        warn "Read-only file system: Unable to write to file '#{save_filespec}'"
+        nil
+      rescue StandardError => err
+        warn "An error occurred while writing to file '#{save_filespec}': #{err.message}"
+        nil
+      end
+    end
+
+    # return next document file name
     def write_inherited_lines_to_file(link_state, link_block_data)
-      save_expr = link_block_data.fetch(LinkKeys::Save, '')
+      save_expr = link_block_data.fetch(LinkKeys::SAVE, '')
       if save_expr.present?
         save_filespec = save_filespec_from_expression(save_expr)
         File.write(save_filespec, HashDelegator.join_code_lines(link_state&.inherited_lines))
         @delegate_object[:filename]
       else
-        link_block_data[LinkKeys::File] || @delegate_object[:filename]
+        link_block_data[LinkKeys::FILE] || @delegate_object[:filename]
       end
     end
   end
@@ -2595,21 +3017,21 @@ module MarkdownExec
 
     # Test case for empty body
     def test_push_link_history_and_trigger_load_with_empty_body
-      assert_equal LoadFile::Reuse,
+      assert_equal LoadFile::REUSE,
                    @hd.push_link_history_and_trigger_load.load_file
     end
 
     # Test case for non-empty body without 'file' key
     def test_push_link_history_and_trigger_load_without_file_key
       body = ["vars:\n  KEY: VALUE"]
-      assert_equal LoadFile::Reuse,
+      assert_equal LoadFile::REUSE,
                    @hd.push_link_history_and_trigger_load(link_block_body: body).load_file
     end
 
     # Test case for non-empty body with 'file' key
     def test_push_link_history_and_trigger_load_with_file_key
       body = ["file: sample_file\nblock: sample_block\nvars:\n  KEY: VALUE"]
-      expected_result = LoadFileLinkState.new(LoadFile::Load,
+      expected_result = LoadFileLinkState.new(LoadFile::LOAD,
                                               LinkState.new(block_name: 'sample_block',
                                                             document_filename: 'sample_file',
                                                             inherited_dependencies: {},
@@ -2647,8 +3069,9 @@ module MarkdownExec
     end
 
     def test_safeval_rescue_from_error
-      HashDelegator.stubs(:error_handler).with('safeval')
-      assert_nil HashDelegator.safeval('invalid code')
+      assert_raises(SystemExit) do
+        HashDelegator.safeval('invalid_code_raises_exception')
+      end
     end
 
     def test_set_fcb_title
@@ -2755,7 +3178,6 @@ module MarkdownExec
 
       def test_blocks_from_nested_files
         result = @hd.blocks_from_nested_files
-
         assert_kind_of Array, result
         assert_kind_of FCB, result.first
       end
@@ -3054,7 +3476,7 @@ module MarkdownExec
 
         # Asserting the result is an instance of LoadFileLinkState
         assert_instance_of LoadFileLinkState, result
-        assert_equal LoadFile::Load, result.load_file
+        assert_equal LoadFile::LOAD, result.load_file
         assert_nil result.link_state.block_name
       end
     end
@@ -3441,4 +3863,60 @@ module MarkdownExec
       assert_equal expected, BashCommentFormatter.format_comment(input)
     end
   end
+
+  class PromptForFilespecWithWildcardTest < Minitest::Test
+    def setup
+      @delegate_object = {
+        prompt_show_expr_format: 'Current expression: %{expr}',
+        prompt_enter_filespec: 'Please enter a filespec:'
+      }
+      @original_stdin = $stdin
+    end
+
+    def teardown
+      $stdin = @original_stdin
+    end
+
+    def test_prompt_for_filespec_with_normal_input
+      $stdin = StringIO.new("test_input\n")
+      result = prompt_for_filespec_with_wildcard('*.txt')
+      assert_equal 'resolved_path_or_substituted_value', result
+    end
+
+    def test_prompt_for_filespec_with_interruption
+      $stdin = StringIO.new
+      # rubocop disable:Lint/NestedMethodDefinition
+      def $stdin.gets; raise Interrupt; end
+      # rubocop enable:Lint/NestedMethodDefinition
+
+      result = prompt_for_filespec_with_wildcard('*.txt')
+      assert_nil result
+    end
+
+    def test_prompt_for_filespec_with_empty_input
+      $stdin = StringIO.new("\n")
+      result = prompt_for_filespec_with_wildcard('*.txt')
+      assert_equal 'resolved_path_or_substituted_value', result
+    end
+
+    private
+
+    def prompt_for_filespec_with_wildcard(filespec)
+      puts format(@delegate_object[:prompt_show_expr_format], { expr: filespec })
+      puts @delegate_object[:prompt_enter_filespec]
+
+      begin
+        input = gets.chomp
+        PathUtils.resolve_path_or_substitute(input, filespec)
+      rescue Interrupt
+        nil
+      end
+    end
+
+    module PathUtils
+      def self.resolve_path_or_substitute(input, filespec)
+        'resolved_path_or_substituted_value' # Placeholder implementation
+      end
+    end
+  end
 end # module MarkdownExec