SteppingRecipeRunner
====================

Step-by-step recipe execution with checkpointing.

Enables stepping through recipes one action at a time, with the ability
to rewind to previous states and branch to create new variations.

See ADR-014 for architecture decisions.

Classes
-------

.. py:class:: SegmentationCheckpoint

   A saved state of the segmentation at a specific step.
   
   Stores the labelmap as a numpy array for fast restoration.
   
   Attributes:
       step_index: The step index this checkpoint represents (after executing that step).
       labelmap_array: The segmentation labelmap as a numpy array.
       timestamp: When the checkpoint was created.

   **Methods:**

   .. py:method:: size_bytes()

      Return the size of the labelmap in bytes.


.. py:class:: SteppingRecipeRunner

   Execute recipes step-by-step with checkpoint and rewind support.
   
   Usage:
       runner = SteppingRecipeRunner(action_recipe)
   
       # Set up the scene
       runner.setup()
   
       # Step through the recipe
       while runner.step_forward():
           action = runner.get_current_action()
           print(f"Executed step {runner.current_step}: {action.type}")
   
       # Rewind to step 2
       runner.goto_step(2)
   
       # Branch from here
       runner.start_branch()
       # ... user performs manual actions ...
       runner.add_manual_action(RecipeAction.paint(...))
       branched_recipe = runner.save_branch()
   
   Attributes:
       recipe: The ActionRecipe being executed.
       current_step: Current step index (-1 = before any steps).
       checkpoints: List of saved segmentation states.

   **Methods:**

   .. py:method:: __init__()

      Initialize the stepping runner.

   .. py:method:: total_steps()

      Return total number of steps in the recipe.

   .. py:method:: is_at_start()

      Return True if at the start (before any steps).

   .. py:method:: is_at_end()

      Return True if at the end (all steps executed).

   .. py:method:: is_branching()

      Return True if currently recording a branch.

   .. py:method:: set_step_callback()

      Set callback to be called after each step.

   .. py:method:: set_checkpoint_callback()

      Set callback to be called when a checkpoint is created.

   .. py:method:: setup()

      Set up the scene for recipe execution.

   .. py:method:: step_forward()

      Execute the next step in the recipe.

   .. py:method:: step_backward()

      Rewind to the previous step by restoring checkpoint.

   .. py:method:: goto_step()

      Go to a specific step by restoring checkpoint.

   .. py:method:: run_to_end()

      Execute all remaining steps.

   .. py:method:: get_current_action()

      Get the action for the current step.

   .. py:method:: get_next_action()

      Get the action for the next step.

   .. py:method:: start_branch()

      Start recording a branch from the current step.

   .. py:method:: stop_branch()

      Stop recording the branch without saving.

   .. py:method:: add_manual_action()

      Add a manually recorded action to the branch.

   .. py:method:: save_branch()

      Save the current branch as a new ActionRecipe.

   .. py:method:: get_checkpoint_stats()

      Get statistics about stored checkpoints.

   .. py:method:: cleanup()

      Clean up resources.


Functions
---------

.. py:function:: size_bytes()

   Return the size of the labelmap in bytes.

.. py:function:: total_steps()

   Return total number of steps in the recipe.

.. py:function:: is_at_start()

   Return True if at the start (before any steps).

.. py:function:: is_at_end()

   Return True if at the end (all steps executed).

.. py:function:: is_branching()

   Return True if currently recording a branch.

.. py:function:: set_step_callback()

   Set callback to be called after each step.
   
   Args:
       callback: Function taking (step_index, action) or None to clear.

.. py:function:: set_checkpoint_callback()

   Set callback to be called when a checkpoint is created.
   
   Args:
       callback: Function taking (checkpoint) or None to clear.

.. py:function:: setup()

   Set up the scene for recipe execution.
   
   Loads sample data, creates segmentation, and activates the effect.
   
   Returns:
       True if setup succeeded, False otherwise.

.. py:function:: step_forward()

   Execute the next step in the recipe.
   
   Returns:
       True if a step was executed, False if already at the end.

.. py:function:: step_backward()

   Rewind to the previous step by restoring checkpoint.
   
   Returns:
       True if rewound successfully, False if already at start.

.. py:function:: goto_step()

   Go to a specific step by restoring checkpoint.
   
   Args:
       step_index: Target step index (-1 for initial state).
   
   Returns:
       True if successful, False otherwise.

.. py:function:: run_to_end()

   Execute all remaining steps.
   
   Returns:
       Number of steps executed.

.. py:function:: get_current_action()

   Get the action for the current step.
   
   Returns:
       The current action, or None if at start.

.. py:function:: get_next_action()

   Get the action for the next step.
   
   Returns:
       The next action, or None if at end.

.. py:function:: start_branch()

   Start recording a branch from the current step.
   
   After calling this, manual actions can be added and saved as a new recipe.

.. py:function:: stop_branch()

   Stop recording the branch without saving.

.. py:function:: add_manual_action()

   Add a manually recorded action to the branch.
   
   Args:
       action: The action to add.

.. py:function:: save_branch()

   Save the current branch as a new ActionRecipe.
   
   Args:
       name: Name for the branched recipe. If None, auto-generated.
   
   Returns:
       The branched ActionRecipe.

.. py:function:: get_checkpoint_stats()

   Get statistics about stored checkpoints.
   
   Returns:
       Dictionary with checkpoint statistics.

.. py:function:: cleanup()

   Clean up resources.