/*
  Python 3 -- Loops and recursion
  while, for range(), for-each, recursion
  No em dashes anywhere -- use plain hyphens or rewrite the sentence.

  Line index comments mark each scenario's 0-based line numbers
  (blank lines are not counted).
*/
STEPPER_REGISTRY.register("python-3/loops", {
  label: 'Loops and recursion',
  panelConfig: {
    stack: true,
    heap:  false,
    custom: false,
    legend: [
      { color:'#1d5799', border:'#9dc0e8', label:'Currently running frame' },
      { color:'#68655f', border:'#d4d1cc', label:'Paused, waiting to resume' },
      { color:'#a0540a', border:'#e8c070', label:'Variable just assigned' },
      { color:'#095e40', border:'#90d4b8', label:'Holding a value' },
      { color:'#3d3490', border:'#b0a8e0', label:'Reference (list or object)' },
    ]
  },
  scenarios: [

    /* ------------------------------------------------------------------ */
    /*  1. while loop                                                       */
    /*                                                                      */
    /*  0  count = 0                                                        */
    /*  1  while count < 3:                                                 */
    /*  2      count += 1                                                   */
    /*  3  print("Done")                                                    */
    /* ------------------------------------------------------------------ */
    {
      label: 'while loop',
      lines: [
        { code: [['tok-op','count = '],['tok-num','0']] },
        { code: [['tok-kw','while '],['tok-op','count < '],['tok-num','3'],['tok-op',':']] },
        { code: [['','    '],['tok-op','count += '],['tok-num','1']] },
        { code: [['tok-meth','print'],['tok-op','('],['tok-str','"Done"'],['tok-op',')']] },
      ],
      steps: [
        { line:0, stack:[{name:'<module>',vars:[{n:'count',v:'0',fresh:true,cls:false}],active:true}],
          expl:{label:'Variable assigned', text:'<hi>count = 0</hi> creates a variable initialized to <hi>0</hi>.'} },
        { line:1, tokenRange:[1,2], stack:[{name:'<module>',vars:[{n:'count',v:'0',fresh:false,cls:false}],active:true}],
          expl:{label:'Condition: true', text:'Python evaluates <hi>count < 3</hi>. Since 0 < 3, the condition is true and the loop body runs.'} },
        { line:2, stack:[{name:'<module>',vars:[{n:'count',v:'1',fresh:true,cls:false}],active:true}],
          expl:{label:'Loop body', text:'<hi>count += 1</hi> increments <hi>count</hi> from 0 to 1.'} },
        { line:1, tokenRange:[1,2], stack:[{name:'<module>',vars:[{n:'count',v:'1',fresh:false,cls:false}],active:true}],
          expl:{label:'Condition: true', text:'Back at the top. <hi>1 < 3</hi> is still true -- another iteration begins.'} },
        { line:2, stack:[{name:'<module>',vars:[{n:'count',v:'2',fresh:true,cls:false}],active:true}],
          expl:{label:'Loop body', text:'<hi>count += 1</hi> increments <hi>count</hi> to 2.'} },
        { line:1, tokenRange:[1,2], stack:[{name:'<module>',vars:[{n:'count',v:'2',fresh:false,cls:false}],active:true}],
          expl:{label:'Condition: true', text:'<hi>2 < 3</hi> is still true -- one more iteration.'} },
        { line:2, stack:[{name:'<module>',vars:[{n:'count',v:'3',fresh:true,cls:false}],active:true}],
          expl:{label:'Loop body', text:'<hi>count += 1</hi> increments <hi>count</hi> to 3.'} },
        { line:1, tokenRange:[1,2], stack:[{name:'<module>',vars:[{n:'count',v:'3',fresh:false,cls:false}],active:true}],
          expl:{label:'Condition: false', text:'<hi>3 < 3</hi> is false. The loop exits -- execution continues after the while block.'} },
        { line:3, stack:[{name:'<module>',vars:[{n:'count',v:'3',fresh:false,cls:false}],active:true}],
          expl:{label:'After the loop', text:'<hi>count</hi> retains its value of <hi>3</hi>. <hi>print("Done")</hi> runs.'} },
        { line:3, stack:[{name:'<module>',vars:[{n:'count',v:'3',fresh:false,cls:false}],active:true}],
          expl:{label:'Script ends', text:'There is nothing more to run.'} },
      ]
    },

    /* ------------------------------------------------------------------ */
    /*  2. for loop with range()                                            */
    /*                                                                      */
    /*  0  total = 0                                                        */
    /*  1  for i in range(3):                                               */
    /*  2      total += i                                                   */
    /*  3  print(total)                                                     */
    /* ------------------------------------------------------------------ */
    {
      label: 'for loop with range()',
      lines: [
        { code: [['tok-op','total = '],['tok-num','0']] },
        { code: [['tok-kw','for '],['tok-op','i '],['tok-kw','in '],['tok-meth','range'],['tok-op','('],['tok-num','3'],['tok-op','):']] },
        { code: [['','    '],['tok-op','total += i']] },
        { code: [['tok-meth','print'],['tok-op','(total)']] },
      ],
      steps: [
        { line:0, stack:[{name:'<module>',vars:[{n:'total',v:'0',fresh:true,cls:false}],active:true}],
          expl:{label:'Variable assigned', text:'<hi>total = 0</hi> initializes the accumulator.'} },
        { line:1, stack:[{name:'<module>',vars:[{n:'total',v:'0',fresh:false,cls:false},{n:'i',v:'0',fresh:true,cls:false}],active:true}],
          expl:{label:'First value from range', text:'Python asks <hi>range(3)</hi> for its first value. <hi>i = 0</hi>. The loop body will now run.'} },
        { line:2, stack:[{name:'<module>',vars:[{n:'total',v:'0',fresh:false,cls:false},{n:'i',v:'0',fresh:false,cls:false}],active:true}],
          expl:{label:'Loop body', text:'<hi>total += i</hi> adds <hi>0</hi> to total. total stays <hi>0</hi> this iteration.'} },
        { line:1, stack:[{name:'<module>',vars:[{n:'total',v:'0',fresh:false,cls:false},{n:'i',v:'1',fresh:true,cls:false}],active:true}],
          expl:{label:'Next value from range', text:'Python asks <hi>range(3)</hi> for its next value. <hi>i = 1</hi>.'} },
        { line:2, stack:[{name:'<module>',vars:[{n:'total',v:'1',fresh:true,cls:false},{n:'i',v:'1',fresh:false,cls:false}],active:true}],
          expl:{label:'Loop body', text:'<hi>total += i</hi> adds <hi>1</hi>. total is now <hi>1</hi>.'} },
        { line:1, stack:[{name:'<module>',vars:[{n:'total',v:'1',fresh:false,cls:false},{n:'i',v:'2',fresh:true,cls:false}],active:true}],
          expl:{label:'Next value from range', text:'Python asks <hi>range(3)</hi> for its next value. <hi>i = 2</hi>.'} },
        { line:2, stack:[{name:'<module>',vars:[{n:'total',v:'3',fresh:true,cls:false},{n:'i',v:'2',fresh:false,cls:false}],active:true}],
          expl:{label:'Loop body', text:'<hi>total += i</hi> adds <hi>2</hi>. total is now <hi>3</hi>.'} },
        { line:1, stack:[{name:'<module>',vars:[{n:'total',v:'3',fresh:false,cls:false}],active:true}],
          expl:{label:'range exhausted', text:'<hi>range(3)</hi> has no more values. The loop ends and <hi>i</hi> goes out of scope.'} },
        { line:3, stack:[{name:'<module>',vars:[{n:'total',v:'3',fresh:false,cls:false}],active:true}],
          expl:{label:'After the loop', text:'<hi>print(total)</hi> prints <hi>3</hi> -- the sum of 0 + 1 + 2.'} },
        { line:3, stack:[{name:'<module>',vars:[{n:'total',v:'3',fresh:false,cls:false}],active:true}],
          expl:{label:'Script ends', text:'There is nothing more to run.'} },
      ]
    },

    /* ------------------------------------------------------------------ */
    /*  3. for-each (for n in list)                                         */
    /*                                                                      */
    /*  0  nums = [10, 20, 30]                                              */
    /*  1  total = 0                                                        */
    /*  2  for n in nums:                                                   */
    /*  3      total += n                                                   */
    /*  4  print(total)                                                     */
    /* ------------------------------------------------------------------ */
    {
      label: 'for-each loop',
      lines: [
        { code: [['tok-op','nums = ['],['tok-num','10'],['tok-op',', '],['tok-num','20'],['tok-op',', '],['tok-num','30'],['tok-op',']']] },
        { code: [['tok-op','total = '],['tok-num','0']] },
        { code: [['tok-kw','for '],['tok-op','n '],['tok-kw','in '],['tok-op','nums:']] },
        { code: [['','    '],['tok-op','total += n']] },
        { code: [['tok-meth','print'],['tok-op','(total)']] },
      ],
      steps: [
        { line:0, stack:[{name:'<module>',vars:[{n:'nums',v:'[10, 20, 30]',fresh:true,cls:true}],active:true}],
          expl:{label:'List created', text:'<hi>nums = [10, 20, 30]</hi> creates a list. <hi>nums</hi> holds a reference to it -- lists are reference types in Python.'} },
        { line:1, stack:[{name:'<module>',vars:[{n:'nums',v:'[10, 20, 30]',fresh:false,cls:true},{n:'total',v:'0',fresh:true,cls:false}],active:true}],
          expl:{label:'Accumulator initialized', text:'<hi>total = 0</hi>. It will hold the running sum.'} },
        { line:2, stack:[{name:'<module>',vars:[{n:'nums',v:'[10, 20, 30]',fresh:false,cls:true},{n:'total',v:'0',fresh:false,cls:false},{n:'n',v:'10',fresh:true,cls:false}],active:true}],
          expl:{label:'First element', text:'Python takes the first element from <hi>nums</hi>. <hi>n = 10</hi>.'} },
        { line:3, stack:[{name:'<module>',vars:[{n:'nums',v:'[10, 20, 30]',fresh:false,cls:true},{n:'total',v:'10',fresh:true,cls:false},{n:'n',v:'10',fresh:false,cls:false}],active:true}],
          expl:{label:'Loop body', text:'<hi>total += n</hi> adds <hi>10</hi>. total is now <hi>10</hi>.'} },
        { line:2, stack:[{name:'<module>',vars:[{n:'nums',v:'[10, 20, 30]',fresh:false,cls:true},{n:'total',v:'10',fresh:false,cls:false},{n:'n',v:'20',fresh:true,cls:false}],active:true}],
          expl:{label:'Next element', text:'Python takes the next element from <hi>nums</hi>. <hi>n = 20</hi>.'} },
        { line:3, stack:[{name:'<module>',vars:[{n:'nums',v:'[10, 20, 30]',fresh:false,cls:true},{n:'total',v:'30',fresh:true,cls:false},{n:'n',v:'20',fresh:false,cls:false}],active:true}],
          expl:{label:'Loop body', text:'<hi>total += n</hi> adds <hi>20</hi>. total is now <hi>30</hi>.'} },
        { line:2, stack:[{name:'<module>',vars:[{n:'nums',v:'[10, 20, 30]',fresh:false,cls:true},{n:'total',v:'30',fresh:false,cls:false},{n:'n',v:'30',fresh:true,cls:false}],active:true}],
          expl:{label:'Last element', text:'Python takes the last element from <hi>nums</hi>. <hi>n = 30</hi>.'} },
        { line:3, stack:[{name:'<module>',vars:[{n:'nums',v:'[10, 20, 30]',fresh:false,cls:true},{n:'total',v:'60',fresh:true,cls:false},{n:'n',v:'30',fresh:false,cls:false}],active:true}],
          expl:{label:'Loop body', text:'<hi>total += n</hi> adds <hi>30</hi>. total is now <hi>60</hi>.'} },
        { line:2, stack:[{name:'<module>',vars:[{n:'nums',v:'[10, 20, 30]',fresh:false,cls:true},{n:'total',v:'60',fresh:false,cls:false}],active:true}],
          expl:{label:'No more elements', text:'All elements have been visited. The loop exits and <hi>n</hi> goes out of scope.'} },
        { line:4, stack:[{name:'<module>',vars:[{n:'nums',v:'[10, 20, 30]',fresh:false,cls:true},{n:'total',v:'60',fresh:false,cls:false}],active:true}],
          expl:{label:'After the loop', text:'<hi>print(total)</hi> prints <hi>60</hi> -- the sum of all elements.'} },
        { line:4, stack:[{name:'<module>',vars:[{n:'nums',v:'[10, 20, 30]',fresh:false,cls:true},{n:'total',v:'60',fresh:false,cls:false}],active:true}],
          expl:{label:'Script ends', text:'There is nothing more to run.'} },
      ]
    },

    /* ------------------------------------------------------------------ */
    /*  4. Recursion                                                        */
    /*                                                                      */
    /*  Line index (blank lines excluded from count):                       */
    /*  0  def countdown(n):                                                */
    /*  1      if n == 0:                                                   */
    /*  2          print("Go!")                                             */
    /*  3          return                                                   */
    /*  4      print(n)                                                     */
    /*  5      countdown(n - 1)                                             */
    /*     (blank -- not counted)                                           */
    /*  6  countdown(3)                                                     */
    /* ------------------------------------------------------------------ */
    {
      label: 'Recursion',
      lines: [
        { code: [['tok-kw','def '],['tok-meth','countdown'],['tok-op','(n):']] },
        { code: [['','    '],['tok-kw','if '],['tok-op','n == '],['tok-num','0'],['tok-op',':']] },
        { code: [['','        '],['tok-meth','print'],['tok-op','('],['tok-str','"Go!"'],['tok-op',')']] },
        { code: [['','        '],['tok-kw','return']] },
        { code: [['','    '],['tok-meth','print'],['tok-op','(n)']] },
        { code: [['','    '],['tok-meth','countdown'],['tok-op','(n - '],['tok-num','1'],['tok-op',')']] },
        { blank: true },
        { code: [['tok-meth','countdown'],['tok-op','('],['tok-num','3'],['tok-op',')']] },
      ],
      steps: [
        { line:0, stack:[{name:'<module>',vars:[],active:true}],
          expl:{label:'Script starts', text:'Python reads the <hi>def</hi> statement and stores <hi>countdown</hi> as a function.'} },
        { line:6, stack:[{name:'<module>',vars:[],active:true}],
          expl:{label:'Calling countdown(3)', text:'<hi>countdown(3)</hi> is called. Python will push a new frame for it.'} },
        { line:1, stack:[{name:'countdown(n=3)',vars:[{n:'n',v:'3',fresh:true,cls:false}],active:true},{name:'<module>',vars:[],active:false}],
          expl:{label:'Frame created', text:'A new frame for <hi>countdown()</hi> is pushed. Parameter <hi>n</hi> is set to <hi>3</hi>. <hi>&lt;module&gt;</hi> is now waiting.'} },
        { line:1, stack:[{name:'countdown(n=3)',vars:[{n:'n',v:'3',fresh:false,cls:false}],active:true},{name:'<module>',vars:[],active:false}],
          expl:{label:'Base case check', text:'<hi>n == 0</hi>? No -- 3 is not 0. The if block is skipped.'} },
        { line:4, stack:[{name:'countdown(n=3)',vars:[{n:'n',v:'3',fresh:false,cls:false}],active:true},{name:'<module>',vars:[],active:false}],
          expl:{label:'Print n', text:'<hi>print(n)</hi> prints <hi>3</hi>.'} },
        { line:5, stack:[{name:'countdown(n=3)',vars:[{n:'n',v:'3',fresh:false,cls:false}],active:true},{name:'<module>',vars:[],active:false}],
          expl:{label:'Recursive call', text:'<hi>countdown(n - 1)</hi> calls itself with <hi>2</hi>. A new frame is about to be pushed.'} },
        { line:1, stack:[{name:'countdown(n=2)',vars:[{n:'n',v:'2',fresh:true,cls:false}],active:true},{name:'countdown(n=3)',vars:[{n:'n',v:'3',fresh:false,cls:false}],active:false},{name:'<module>',vars:[],active:false}],
          expl:{label:'Stack grows', text:'A second <hi>countdown()</hi> frame is pushed. Each call has its own <hi>n</hi>. The first call waits below.'} },
        { line:1, stack:[{name:'countdown(n=2)',vars:[{n:'n',v:'2',fresh:false,cls:false}],active:true},{name:'countdown(n=3)',vars:[{n:'n',v:'3',fresh:false,cls:false}],active:false},{name:'<module>',vars:[],active:false}],
          expl:{label:'Base case check', text:'<hi>n == 0</hi>? No -- 2 is not 0.'} },
        { line:4, stack:[{name:'countdown(n=2)',vars:[{n:'n',v:'2',fresh:false,cls:false}],active:true},{name:'countdown(n=3)',vars:[{n:'n',v:'3',fresh:false,cls:false}],active:false},{name:'<module>',vars:[],active:false}],
          expl:{label:'Print n', text:'Prints <hi>2</hi>.'} },
        { line:5, stack:[{name:'countdown(n=2)',vars:[{n:'n',v:'2',fresh:false,cls:false}],active:true},{name:'countdown(n=3)',vars:[{n:'n',v:'3',fresh:false,cls:false}],active:false},{name:'<module>',vars:[],active:false}],
          expl:{label:'Recursive call', text:'<hi>countdown(1)</hi> is called. Another frame will be pushed.'} },
        { line:1, stack:[{name:'countdown(n=1)',vars:[{n:'n',v:'1',fresh:true,cls:false}],active:true},{name:'countdown(n=2)',vars:[{n:'n',v:'2',fresh:false,cls:false}],active:false},{name:'countdown(n=3)',vars:[{n:'n',v:'3',fresh:false,cls:false}],active:false},{name:'<module>',vars:[],active:false}],
          expl:{label:'Stack grows', text:'Three <hi>countdown()</hi> frames now sit above <hi>&lt;module&gt;</hi>. Each is waiting for the one above it to finish.'} },
        { line:1, stack:[{name:'countdown(n=1)',vars:[{n:'n',v:'1',fresh:false,cls:false}],active:true},{name:'countdown(n=2)',vars:[{n:'n',v:'2',fresh:false,cls:false}],active:false},{name:'countdown(n=3)',vars:[{n:'n',v:'3',fresh:false,cls:false}],active:false},{name:'<module>',vars:[],active:false}],
          expl:{label:'Base case check', text:'<hi>n == 0</hi>? No -- 1 is not 0.'} },
        { line:4, stack:[{name:'countdown(n=1)',vars:[{n:'n',v:'1',fresh:false,cls:false}],active:true},{name:'countdown(n=2)',vars:[{n:'n',v:'2',fresh:false,cls:false}],active:false},{name:'countdown(n=3)',vars:[{n:'n',v:'3',fresh:false,cls:false}],active:false},{name:'<module>',vars:[],active:false}],
          expl:{label:'Print n', text:'Prints <hi>1</hi>.'} },
        { line:5, stack:[{name:'countdown(n=1)',vars:[{n:'n',v:'1',fresh:false,cls:false}],active:true},{name:'countdown(n=2)',vars:[{n:'n',v:'2',fresh:false,cls:false}],active:false},{name:'countdown(n=3)',vars:[{n:'n',v:'3',fresh:false,cls:false}],active:false},{name:'<module>',vars:[],active:false}],
          expl:{label:'Recursive call', text:'<hi>countdown(0)</hi> is called -- this will trigger the base case.'} },
        { line:1, stack:[{name:'countdown(n=0)',vars:[{n:'n',v:'0',fresh:true,cls:false}],active:true},{name:'countdown(n=1)',vars:[{n:'n',v:'1',fresh:false,cls:false}],active:false},{name:'countdown(n=2)',vars:[{n:'n',v:'2',fresh:false,cls:false}],active:false},{name:'countdown(n=3)',vars:[{n:'n',v:'3',fresh:false,cls:false}],active:false},{name:'<module>',vars:[],active:false}],
          expl:{label:'Deepest call', text:'The stack is now at its deepest: five frames. <hi>n = 0</hi> in this frame.'} },
        { line:1, stack:[{name:'countdown(n=0)',vars:[{n:'n',v:'0',fresh:false,cls:false}],active:true},{name:'countdown(n=1)',vars:[{n:'n',v:'1',fresh:false,cls:false}],active:false},{name:'countdown(n=2)',vars:[{n:'n',v:'2',fresh:false,cls:false}],active:false},{name:'countdown(n=3)',vars:[{n:'n',v:'3',fresh:false,cls:false}],active:false},{name:'<module>',vars:[],active:false}],
          expl:{label:'Base case: true', text:'<hi>n == 0</hi> is true. The base case is reached -- the if block executes.'} },
        { line:2, stack:[{name:'countdown(n=0)',vars:[{n:'n',v:'0',fresh:false,cls:false}],active:true},{name:'countdown(n=1)',vars:[{n:'n',v:'1',fresh:false,cls:false}],active:false},{name:'countdown(n=2)',vars:[{n:'n',v:'2',fresh:false,cls:false}],active:false},{name:'countdown(n=3)',vars:[{n:'n',v:'3',fresh:false,cls:false}],active:false},{name:'<module>',vars:[],active:false}],
          expl:{label:'Print "Go!"', text:'<hi>print("Go!")</hi> runs. The countdown is complete.'} },
        { line:3, stack:[{name:'countdown(n=0)',vars:[{n:'n',v:'0',fresh:false,cls:false}],active:true},{name:'countdown(n=1)',vars:[{n:'n',v:'1',fresh:false,cls:false}],active:false},{name:'countdown(n=2)',vars:[{n:'n',v:'2',fresh:false,cls:false}],active:false},{name:'countdown(n=3)',vars:[{n:'n',v:'3',fresh:false,cls:false}],active:false},{name:'<module>',vars:[],active:false}],
          expl:{label:'return', text:'<hi>return</hi> exits <hi>countdown(n=0)</hi>. Its frame is popped -- the stack begins to unwind.'} },
        { line:5, stack:[{name:'countdown(n=1)',vars:[{n:'n',v:'1',fresh:false,cls:false}],active:true},{name:'countdown(n=2)',vars:[{n:'n',v:'2',fresh:false,cls:false}],active:false},{name:'countdown(n=3)',vars:[{n:'n',v:'3',fresh:false,cls:false}],active:false},{name:'<module>',vars:[],active:false}],
          expl:{label:'Unwinding', text:'Back in <hi>countdown(n=1)</hi>. It has no more work to do -- it reaches the end of its body and returns.'} },
        { line:5, stack:[{name:'countdown(n=2)',vars:[{n:'n',v:'2',fresh:false,cls:false}],active:true},{name:'countdown(n=3)',vars:[{n:'n',v:'3',fresh:false,cls:false}],active:false},{name:'<module>',vars:[],active:false}],
          expl:{label:'Unwinding', text:'<hi>countdown(n=2)</hi> also completes and is popped.'} },
        { line:5, stack:[{name:'countdown(n=3)',vars:[{n:'n',v:'3',fresh:false,cls:false}],active:true},{name:'<module>',vars:[],active:false}],
          expl:{label:'Unwinding', text:'<hi>countdown(n=3)</hi> completes and is popped. Only <hi>&lt;module&gt;</hi> remains.'} },
        { line:6, stack:[{name:'<module>',vars:[],active:true}],
          expl:{label:'Back in module', text:'<hi>&lt;module&gt;</hi> resumes after the original <hi>countdown(3)</hi> call. Script ends.'} },
      ]
    },

  ]
});