/*
  Java 17 -- Arrays
  Declare and index, access with a loop, update by index, remove by shifting, copy with a loop.
  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("java-17/arrays", {
  label: 'Arrays',
  panelConfig: {
    stack: true,
    heap:  false,
    custom: false,
    legend: [
      { color:'#1d5799', border:'#9dc0e8', label:'Currently running frame' },
      { color:'#a0540a', border:'#e8c070', label:'Variable just assigned' },
      { color:'#095e40', border:'#90d4b8', label:'Holding a value' },
      { color:'#3d3490', border:'#b0a8e0', label:'Reference (array)' },
    ]
  },
  scenarios: [

    /* ------------------------------------------------------------------ */
    /*  1. Declare and index (read)                                         */
    /*                                                                      */
    /*  0  static void main(String[] args) {                                */
    /*  1    int[] nums = {10, 20, 30};                                     */
    /*  2    int x = nums[0];                                               */
    /*  3    int y = nums[2];                                               */
    /*  4  }                                                                */
    /* ------------------------------------------------------------------ */
    {
      label: 'Declare and index',
      lines: [
        { code: [['tok-kw','static '],['tok-kw','void '],['tok-meth','main'],['tok-op','(String[] args) {']] },
        { code: [['','  '],['tok-type','int'],['tok-op','[] nums = {'],['tok-num','10'],['tok-op',', '],['tok-num','20'],['tok-op',', '],['tok-num','30'],['tok-op','};']] },
        { code: [['','  '],['tok-type','int '],['tok-op','x = nums['],['tok-num','0'],['tok-op','];']] },
        { code: [['','  '],['tok-type','int '],['tok-op','y = nums['],['tok-num','2'],['tok-op','];']] },
        { code: [['tok-op','}']] },
      ],
      steps: [
        { line:0, stack:[{name:'main()',vars:[],active:true}],
          expl:{label:'Program starts', text:'Java enters <hi>main()</hi> and pushes a new frame onto the call stack.'} },
        { line:1, stack:[{name:'main()',vars:[{n:'nums',v:'[10, 20, 30]',fresh:true,cls:true}],active:true}],
          expl:{label:'Array created', text:'<hi>int[] nums = {10, 20, 30}</hi> allocates a 3-element array and stores a reference to it in <hi>nums</hi>. The purple pill signals it is a reference, not a primitive value.'} },
        { line:2, stack:[{name:'main()',vars:[{n:'nums',v:'[10, 20, 30]',fresh:false,cls:true},{n:'x',v:'10',fresh:true,cls:false}],active:true}],
          expl:{label:'Reading index 0', text:'<hi>nums[0]</hi> reads the element at index 0. Arrays are zero-indexed, so the first element is <hi>10</hi>. That value is copied into <hi>x</hi>.'} },
        { line:3, stack:[{name:'main()',vars:[{n:'nums',v:'[10, 20, 30]',fresh:false,cls:true},{n:'x',v:'10',fresh:false,cls:false},{n:'y',v:'30',fresh:true,cls:false}],active:true}],
          expl:{label:'Reading index 2', text:'<hi>nums[2]</hi> reads the last element. Index 2 holds <hi>30</hi>, which is copied into <hi>y</hi>. Valid indices for a 3-element array are 0, 1, and 2.'} },
        { line:4, stack:[{name:'main()',vars:[{n:'nums',v:'[10, 20, 30]',fresh:false,cls:true},{n:'x',v:'10',fresh:false,cls:false},{n:'y',v:'30',fresh:false,cls:false}],active:true}],
          expl:{label:'Program ends', text:'<hi>main()</hi> reaches its closing brace. All local variables go out of scope and the program finishes.'} },
      ]
    },

    /* ------------------------------------------------------------------ */
    /*  2. Access with a loop                                               */
    /*                                                                      */
    /*  0  static void main(String[] args) {                                */
    /*  1    int[] nums = {10, 20, 30};                                     */
    /*  2    int sum = 0;                                                   */
    /*  3    for (int i = 0; i < 3; i++) {                                  */
    /*  4      sum = sum + nums[i];                                         */
    /*  5    }                                                               */
    /*  6  }                                                                */
    /* ------------------------------------------------------------------ */
    {
      label: 'Access with a loop',
      lines: [
        { code: [['tok-kw','static '],['tok-kw','void '],['tok-meth','main'],['tok-op','(String[] args) {']] },
        { code: [['','  '],['tok-type','int'],['tok-op','[] nums = {'],['tok-num','10'],['tok-op',', '],['tok-num','20'],['tok-op',', '],['tok-num','30'],['tok-op','};']] },
        { code: [['','  '],['tok-type','int '],['tok-op','sum = '],['tok-num','0'],['tok-op',';']] },
        { code: [['','  '],['tok-kw','for '],['tok-op','('],['tok-type','int '],['tok-op','i = '],['tok-num','0'],['tok-op','; '],['tok-op','i < '],['tok-num','3'],['tok-op','; '],['tok-op','i++'],['tok-op',') {']] },
        { code: [['','    '],['tok-op','sum = sum + nums[i];']] },
        { code: [['','  '],['tok-op','}']] },
        { code: [['tok-op','}']] },
      ],
      steps: [
        { line:0, stack:[{name:'main()',vars:[],active:true}],
          expl:{label:'Program starts', text:'Java enters <hi>main()</hi> and pushes a frame onto the call stack.'} },
        { line:1, stack:[{name:'main()',vars:[{n:'nums',v:'[10, 20, 30]',fresh:true,cls:true}],active:true}],
          expl:{label:'Array created', text:'<hi>nums</hi> holds a reference to a 3-element array. We will visit each element using a loop.'} },
        { line:2, stack:[{name:'main()',vars:[{n:'nums',v:'[10, 20, 30]',fresh:false,cls:true},{n:'sum',v:'0',fresh:true,cls:false}],active:true}],
          expl:{label:'Accumulator initialized', text:'<hi>sum</hi> starts at <hi>0</hi>. Each loop iteration will read one element from <hi>nums</hi> and add it to <hi>sum</hi>.'} },
        { line:3, tokenRange:[3,5], stack:[{name:'main()',vars:[{n:'nums',v:'[10, 20, 30]',fresh:false,cls:true},{n:'sum',v:'0',fresh:false,cls:false},{n:'i',v:'0',fresh:true,cls:false}],active:true}],
          expl:{label:'Init', text:'<hi>int i = 0</hi> creates the loop counter. <hi>i</hi> is set to <hi>0</hi>. It will serve as the index into <hi>nums</hi>.'} },
        { line:3, tokenRange:[7,8], stack:[{name:'main()',vars:[{n:'nums',v:'[10, 20, 30]',fresh:false,cls:true},{n:'sum',v:'0',fresh:false,cls:false},{n:'i',v:'0',fresh:false,cls:false}],active:true}],
          expl:{label:'Condition: true', text:'Java checks <hi>i < 3</hi>. 0 < 3 is true -- first iteration begins.'} },
        { line:4, stack:[{name:'main()',vars:[{n:'nums',v:'[10, 20, 30]',fresh:false,cls:true},{n:'sum',v:'10',fresh:true,cls:false},{n:'i',v:'0',fresh:false,cls:false}],active:true}],
          expl:{label:'Read index 0', text:'<hi>nums[i]</hi> is <hi>nums[0]</hi>, which is <hi>10</hi>. <hi>sum = 0 + 10</hi> gives <hi>sum = 10</hi>.'} },
        { line:3, tokenRange:[10,10], stack:[{name:'main()',vars:[{n:'nums',v:'[10, 20, 30]',fresh:false,cls:true},{n:'sum',v:'10',fresh:false,cls:false},{n:'i',v:'1',fresh:true,cls:false}],active:true}],
          expl:{label:'Increment', text:'<hi>i++</hi> runs. <hi>i</hi> goes from 0 to <hi>1</hi>.'} },
        { line:3, tokenRange:[7,8], stack:[{name:'main()',vars:[{n:'nums',v:'[10, 20, 30]',fresh:false,cls:true},{n:'sum',v:'10',fresh:false,cls:false},{n:'i',v:'1',fresh:false,cls:false}],active:true}],
          expl:{label:'Condition: true', text:'Java checks <hi>i < 3</hi>. 1 < 3 is true -- next iteration.'} },
        { line:4, stack:[{name:'main()',vars:[{n:'nums',v:'[10, 20, 30]',fresh:false,cls:true},{n:'sum',v:'30',fresh:true,cls:false},{n:'i',v:'1',fresh:false,cls:false}],active:true}],
          expl:{label:'Read index 1', text:'<hi>nums[1]</hi> is <hi>20</hi>. <hi>sum = 10 + 20</hi> gives <hi>sum = 30</hi>.'} },
        { line:3, tokenRange:[10,10], stack:[{name:'main()',vars:[{n:'nums',v:'[10, 20, 30]',fresh:false,cls:true},{n:'sum',v:'30',fresh:false,cls:false},{n:'i',v:'2',fresh:true,cls:false}],active:true}],
          expl:{label:'Increment', text:'<hi>i++</hi> runs. <hi>i</hi> goes from 1 to <hi>2</hi>.'} },
        { line:3, tokenRange:[7,8], stack:[{name:'main()',vars:[{n:'nums',v:'[10, 20, 30]',fresh:false,cls:true},{n:'sum',v:'30',fresh:false,cls:false},{n:'i',v:'2',fresh:false,cls:false}],active:true}],
          expl:{label:'Condition: true', text:'Java checks <hi>i < 3</hi>. 2 < 3 is true -- final iteration.'} },
        { line:4, stack:[{name:'main()',vars:[{n:'nums',v:'[10, 20, 30]',fresh:false,cls:true},{n:'sum',v:'60',fresh:true,cls:false},{n:'i',v:'2',fresh:false,cls:false}],active:true}],
          expl:{label:'Read index 2', text:'<hi>nums[2]</hi> is <hi>30</hi>. <hi>sum = 30 + 30</hi> gives <hi>sum = 60</hi>. All elements have been visited.'} },
        { line:3, tokenRange:[10,10], stack:[{name:'main()',vars:[{n:'nums',v:'[10, 20, 30]',fresh:false,cls:true},{n:'sum',v:'60',fresh:false,cls:false},{n:'i',v:'3',fresh:true,cls:false}],active:true}],
          expl:{label:'Increment', text:'<hi>i++</hi> runs. <hi>i</hi> goes from 2 to <hi>3</hi>.'} },
        { line:3, tokenRange:[7,8], stack:[{name:'main()',vars:[{n:'nums',v:'[10, 20, 30]',fresh:false,cls:true},{n:'sum',v:'60',fresh:false,cls:false},{n:'i',v:'3',fresh:false,cls:false}],active:true}],
          expl:{label:'Condition: false', text:'Java checks <hi>i < 3</hi>. 3 < 3 is false. The loop exits and <hi>i</hi> goes out of scope.'} },
        { line:6, stack:[{name:'main()',vars:[{n:'nums',v:'[10, 20, 30]',fresh:false,cls:true},{n:'sum',v:'60',fresh:false,cls:false}],active:true}],
          expl:{label:'Program ends', text:'The loop visited every element once, using <hi>i</hi> as the index. The final value of <hi>sum</hi> is <hi>60</hi>: 10 + 20 + 30.'} },
      ]
    },

    /* ------------------------------------------------------------------ */
    /*  3. Update by index                                                   */
    /*                                                                      */
    /*  0  static void main(String[] args) {                                */
    /*  1    int[] nums = {10, 20, 30};                                     */
    /*  2    nums[1] = 99;                                                  */
    /*  3  }                                                                */
    /* ------------------------------------------------------------------ */
    {
      label: 'Update by index',
      lines: [
        { code: [['tok-kw','static '],['tok-kw','void '],['tok-meth','main'],['tok-op','(String[] args) {']] },
        { code: [['','  '],['tok-type','int'],['tok-op','[] nums = {'],['tok-num','10'],['tok-op',', '],['tok-num','20'],['tok-op',', '],['tok-num','30'],['tok-op','};']] },
        { code: [['','  '],['tok-op','nums['],['tok-num','1'],['tok-op','] = '],['tok-num','99'],['tok-op',';']] },
        { code: [['tok-op','}']] },
      ],
      steps: [
        { line:0, stack:[{name:'main()',vars:[],active:true}],
          expl:{label:'Program starts', text:'Java enters <hi>main()</hi>.'} },
        { line:1, stack:[{name:'main()',vars:[{n:'nums',v:'[10, 20, 30]',fresh:true,cls:true}],active:true}],
          expl:{label:'Array created', text:'<hi>nums</hi> holds a reference to a 3-element array: <hi>[10, 20, 30]</hi>.'} },
        { line:2, stack:[{name:'main()',vars:[{n:'nums',v:'[10, 99, 30]',fresh:true,cls:true}],active:true}],
          expl:{label:'Element updated', text:'<hi>nums[1] = 99</hi> overwrites the element at index 1. The array goes from <hi>[10, 20, 30]</hi> to <hi>[10, 99, 30]</hi>. Index 0 and 2 are unchanged.'} },
        { line:3, stack:[{name:'main()',vars:[{n:'nums',v:'[10, 99, 30]',fresh:false,cls:true}],active:true}],
          expl:{label:'Program ends', text:'<hi>main()</hi> finishes. The array held <hi>[10, 99, 30]</hi> at the end.'} },
      ]
    },

    /* ------------------------------------------------------------------ */
    /*  3. Remove by shifting                                               */
    /*                                                                      */
    /*  0  static void main(String[] args) {                                */
    /*  1    int[] nums = {10, 20, 30};                                     */
    /*  2    nums[1] = nums[2];  // shift left                              */
    /*  3    nums[2] = 0;        // clear last slot                         */
    /*  4  }                                                                */
    /* ------------------------------------------------------------------ */
    {
      label: 'Remove by shifting',
      lines: [
        { code: [['tok-kw','static '],['tok-kw','void '],['tok-meth','main'],['tok-op','(String[] args) {']] },
        { code: [['','  '],['tok-type','int'],['tok-op','[] nums = {'],['tok-num','10'],['tok-op',', '],['tok-num','20'],['tok-op',', '],['tok-num','30'],['tok-op','};']] },
        { code: [['','  '],['tok-op','nums['],['tok-num','1'],['tok-op','] = nums['],['tok-num','2'],['tok-op','];'],['','  '],['tok-cmt','// shift left']] },
        { code: [['','  '],['tok-op','nums['],['tok-num','2'],['tok-op','] = '],['tok-num','0'],['tok-op',';'],['','        '],['tok-cmt','// clear last slot']] },
        { code: [['tok-op','}']] },
      ],
      steps: [
        { line:0, stack:[{name:'main()',vars:[],active:true}],
          expl:{label:'Program starts', text:'Java enters <hi>main()</hi>. We will "remove" the middle element by shifting elements down.'} },
        { line:1, stack:[{name:'main()',vars:[{n:'nums',v:'[10, 20, 30]',fresh:true,cls:true}],active:true}],
          expl:{label:'Array created', text:'<hi>nums</hi> is <hi>[10, 20, 30]</hi>. Arrays in Java have a fixed length -- we cannot shrink them. "Removing" an element means shifting values to fill the gap, then zeroing the tail.'} },
        { line:2, stack:[{name:'main()',vars:[{n:'nums',v:'[10, 30, 30]',fresh:true,cls:true}],active:true}],
          expl:{label:'Shift: overwrite index 1', text:'<hi>nums[1] = nums[2]</hi> reads the value at index 2 (<hi>30</hi>) and writes it over index 1. The old value <hi>20</hi> is gone. Both slots now hold <hi>30</hi>.'} },
        { line:3, stack:[{name:'main()',vars:[{n:'nums',v:'[10, 30, 0]',fresh:true,cls:true}],active:true}],
          expl:{label:'Clear: zero the tail', text:'<hi>nums[2] = 0</hi> resets the last slot to the default int value. The array is now <hi>[10, 30, 0]</hi> -- logically the element at index 1 has been removed.'} },
        { line:4, stack:[{name:'main()',vars:[{n:'nums',v:'[10, 30, 0]',fresh:false,cls:true}],active:true}],
          expl:{label:'Program ends', text:'<hi>main()</hi> finishes. The array still has length 3 -- only its contents changed.'} },
      ]
    },

    /* ------------------------------------------------------------------ */
    /*  4. Copy with a for loop                                             */
    /*                                                                      */
    /*  0  static void main(String[] args) {                                */
    /*  1    int[] src = {1, 2, 3};                                         */
    /*  2    int[] copy = new int[3];                                       */
    /*  3    for (int i = 0; i < 3; i++) {                                  */
    /*  4      copy[i] = src[i];                                            */
    /*  5    }                                                               */
    /*  6  }                                                                */
    /* ------------------------------------------------------------------ */
    {
      label: 'Copy with a loop',
      lines: [
        { code: [['tok-kw','static '],['tok-kw','void '],['tok-meth','main'],['tok-op','(String[] args) {']] },
        { code: [['','  '],['tok-type','int'],['tok-op','[] src = {'],['tok-num','1'],['tok-op',', '],['tok-num','2'],['tok-op',', '],['tok-num','3'],['tok-op','};']] },
        { code: [['','  '],['tok-type','int'],['tok-op','[] copy = '],['tok-kw','new '],['tok-type','int'],['tok-op','['],['tok-num','3'],['tok-op','];']] },
        { code: [['','  '],['tok-kw','for '],['tok-op','('],['tok-type','int '],['tok-op','i = '],['tok-num','0'],['tok-op','; '],['tok-op','i < '],['tok-num','3'],['tok-op','; '],['tok-op','i++'],['tok-op',') {']] },
        { code: [['','    '],['tok-op','copy[i] = src[i];']] },
        { code: [['','  '],['tok-op','}']] },
        { code: [['tok-op','}']] },
      ],
      steps: [
        { line:0, stack:[{name:'main()',vars:[],active:true}],
          expl:{label:'Program starts', text:'Java enters <hi>main()</hi>. We will copy one array into a separate, independent array.'} },
        { line:1, stack:[{name:'main()',vars:[{n:'src',v:'[1, 2, 3]',fresh:true,cls:true}],active:true}],
          expl:{label:'Source array created', text:'<hi>src</hi> holds a reference to <hi>[1, 2, 3]</hi>. This is the array we want to copy from.'} },
        { line:2, stack:[{name:'main()',vars:[{n:'src',v:'[1, 2, 3]',fresh:false,cls:true},{n:'copy',v:'[0, 0, 0]',fresh:true,cls:true}],active:true}],
          expl:{label:'Destination array created', text:'<hi>new int[3]</hi> allocates a fresh 3-element array. Java automatically fills it with <hi>0</hi>. <hi>copy</hi> is a separate array in memory -- not the same object as <hi>src</hi>.'} },
        { line:3, tokenRange:[3,5], stack:[{name:'main()',vars:[{n:'src',v:'[1, 2, 3]',fresh:false,cls:true},{n:'copy',v:'[0, 0, 0]',fresh:false,cls:true},{n:'i',v:'0',fresh:true,cls:false}],active:true}],
          expl:{label:'Init', text:'The initializer <hi>int i = 0</hi> runs exactly once. <hi>i</hi> is created and set to <hi>0</hi>.'} },
        { line:3, tokenRange:[7,8], stack:[{name:'main()',vars:[{n:'src',v:'[1, 2, 3]',fresh:false,cls:true},{n:'copy',v:'[0, 0, 0]',fresh:false,cls:true},{n:'i',v:'0',fresh:false,cls:false}],active:true}],
          expl:{label:'Condition: true', text:'Java checks <hi>i < 3</hi>. 0 < 3 is true -- first iteration begins.'} },
        { line:4, stack:[{name:'main()',vars:[{n:'src',v:'[1, 2, 3]',fresh:false,cls:true},{n:'copy',v:'[1, 0, 0]',fresh:true,cls:true},{n:'i',v:'0',fresh:false,cls:false}],active:true}],
          expl:{label:'Copy index 0', text:'<hi>copy[0] = src[0]</hi> reads <hi>1</hi> from <hi>src</hi> and writes it to <hi>copy</hi>. <hi>copy</hi> is now <hi>[1, 0, 0]</hi>.'} },
        { line:3, tokenRange:[10,10], stack:[{name:'main()',vars:[{n:'src',v:'[1, 2, 3]',fresh:false,cls:true},{n:'copy',v:'[1, 0, 0]',fresh:false,cls:true},{n:'i',v:'1',fresh:true,cls:false}],active:true}],
          expl:{label:'Increment', text:'<hi>i++</hi> runs. <hi>i</hi> goes from 0 to <hi>1</hi>.'} },
        { line:3, tokenRange:[7,8], stack:[{name:'main()',vars:[{n:'src',v:'[1, 2, 3]',fresh:false,cls:true},{n:'copy',v:'[1, 0, 0]',fresh:false,cls:true},{n:'i',v:'1',fresh:false,cls:false}],active:true}],
          expl:{label:'Condition: true', text:'Java checks <hi>i < 3</hi>. 1 < 3 is true -- next iteration.'} },
        { line:4, stack:[{name:'main()',vars:[{n:'src',v:'[1, 2, 3]',fresh:false,cls:true},{n:'copy',v:'[1, 2, 0]',fresh:true,cls:true},{n:'i',v:'1',fresh:false,cls:false}],active:true}],
          expl:{label:'Copy index 1', text:'<hi>copy[1] = src[1]</hi> copies <hi>2</hi>. <hi>copy</hi> is now <hi>[1, 2, 0]</hi>.'} },
        { line:3, tokenRange:[10,10], stack:[{name:'main()',vars:[{n:'src',v:'[1, 2, 3]',fresh:false,cls:true},{n:'copy',v:'[1, 2, 0]',fresh:false,cls:true},{n:'i',v:'2',fresh:true,cls:false}],active:true}],
          expl:{label:'Increment', text:'<hi>i++</hi> runs. <hi>i</hi> goes from 1 to <hi>2</hi>.'} },
        { line:3, tokenRange:[7,8], stack:[{name:'main()',vars:[{n:'src',v:'[1, 2, 3]',fresh:false,cls:true},{n:'copy',v:'[1, 2, 0]',fresh:false,cls:true},{n:'i',v:'2',fresh:false,cls:false}],active:true}],
          expl:{label:'Condition: true', text:'Java checks <hi>i < 3</hi>. 2 < 3 is true -- final iteration.'} },
        { line:4, stack:[{name:'main()',vars:[{n:'src',v:'[1, 2, 3]',fresh:false,cls:true},{n:'copy',v:'[1, 2, 3]',fresh:true,cls:true},{n:'i',v:'2',fresh:false,cls:false}],active:true}],
          expl:{label:'Copy index 2', text:'<hi>copy[2] = src[2]</hi> copies <hi>3</hi>. All elements are now copied. <hi>copy</hi> is <hi>[1, 2, 3]</hi>.'} },
        { line:3, tokenRange:[10,10], stack:[{name:'main()',vars:[{n:'src',v:'[1, 2, 3]',fresh:false,cls:true},{n:'copy',v:'[1, 2, 3]',fresh:false,cls:true},{n:'i',v:'3',fresh:true,cls:false}],active:true}],
          expl:{label:'Increment', text:'<hi>i++</hi> runs. <hi>i</hi> goes from 2 to <hi>3</hi>.'} },
        { line:3, tokenRange:[7,8], stack:[{name:'main()',vars:[{n:'src',v:'[1, 2, 3]',fresh:false,cls:true},{n:'copy',v:'[1, 2, 3]',fresh:false,cls:true},{n:'i',v:'3',fresh:false,cls:false}],active:true}],
          expl:{label:'Condition: false', text:'Java checks <hi>i < 3</hi>. 3 < 3 is false. The loop exits and <hi>i</hi> goes out of scope.'} },
        { line:6, stack:[{name:'main()',vars:[{n:'src',v:'[1, 2, 3]',fresh:false,cls:true},{n:'copy',v:'[1, 2, 3]',fresh:false,cls:true}],active:true}],
          expl:{label:'Two separate arrays', text:'<hi>src</hi> and <hi>copy</hi> each hold a reference to a different array object. Changing one will not affect the other.'} },
      ]
    },

  ]
});