pikachu companion: prominent START marker + centre on start; anchor block order at the start point

- route start drawn with halo, bold ring and START tag; selecting a colour
  pans to the start once the route is planned
- block walk now starts at the block containing the start point and expands
  outward row by row (serpentine/row-major within rows); last known start
  cached so the order doesn't flicker while a route re-plans
- setting a new start point restarts the block walk

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

Author: tmck-code

pages/pikachu-stitch-companion/js/blocks.js

@@ -4,6 +4,7 @@
 import { N } from './pattern.js';
 import { state, idxOf, rowOf, colOf, colourAt, isStitched } from './state.js';
 import { view, clampView, draw, stage } from './render.js';
+import { getRoute } from './planner.js';
 
 export const BLOCK_SIZE = 10;
 export const BLOCKS = N / BLOCK_SIZE; // 15 blocks per axis (150/10)
@@ -49,28 +50,63 @@ export function blockIsCompleteForColour(br, bc, v){
 }
 
 /**
- * blockOrderList(v) -> blocksForColour(v) reordered per
- * state.settings.blockOrder:
- *  - 'row-major': left-to-right, top-to-bottom throughout (bc ascending
- *    every row).
- *  - 'serpentine' (default): left-to-right on even block-rows, right-to-
- *    left on odd block-rows (boustrophedon), so consecutive blocks are
- *    always adjacent.
+ * startCellFor(v) -> cell index the route for colour v starts from (the
+ * user-set start point if valid, else the planned route's start), or null
+ * when neither is known yet.
+ */
+const lastKnownStart = new Map(); // colour -> cell; survives route invalidation
+export function startCellFor(v){
+  const sp = state.startPoints[v];
+  if (sp!=null && colourAt(sp)===v && !isStitched(sp)){ lastKnownStart.set(v, sp); return sp; }
+  const route = getRoute(v);
+  if (route && route.start!=null){ lastKnownStart.set(v, route.start); return route.start; }
+  // route is being re-planned (e.g. right after a mark) — keep the previous
+  // anchor so the block order doesn't jump around between frames
+  return lastKnownStart.has(v) ? lastKnownStart.get(v) : null;
+}
+
+/**
+ * blockOrderList(v, order?) -> blocksForColour(v) in navigation order,
+ * anchored at the block containing the colour's start point (startCellFor):
+ *  - block-rows are visited outward from the start row (start row first,
+ *    then the row below, the row above, two below, two above, …);
+ *  - within the start row, blocks are visited nearest-first from the start
+ *    block (ties: rightward first);
+ *  - 'row-major': every other row is left-to-right;
+ *  - 'serpentine' (default): every other row begins at the side nearest
+ *    where the previous row ended, so consecutive blocks stay adjacent.
+ * With no known start point the anchor is the top-left block (legacy).
  */
 export function blockOrderList(v, order = state.settings.blockOrder){
   const blocks = blocksForColour(v); // already row-major by br,bc
-  if(order === 'row-major') return blocks;
+  if(!blocks.length) return blocks;
+  const start = startCellFor(v);
+  const anchor = start!=null ? blockOf(start) : { br: blocks[0].br, bc: blocks[0].bc };
   const byRow = new Map();
   for(const b of blocks){
     if(!byRow.has(b.br)) byRow.set(b.br, []);
     byRow.get(b.br).push(b);
   }
+  const rows = [...byRow.keys()].sort((a,b)=>{
+    const da = Math.abs(a-anchor.br), db = Math.abs(b-anchor.br);
+    return da!==db ? da-db : b-a; // nearer first; tie → the lower row (below) first
+  });
   const out = [];
-  for(const br of [...byRow.keys()].sort((a,b)=>a-b)){
-    const row = byRow.get(br);
-    if(br % 2 === 1) row.reverse();
+  let lastBc = anchor.bc;
+  rows.forEach((br, k)=>{
+    let row = byRow.get(br).slice().sort((a,b)=>a.bc-b.bc);
+    if(k===0){
+      row.sort((a,b)=>{
+        const da = Math.abs(a.bc-anchor.bc), db = Math.abs(b.bc-anchor.bc);
+        return da!==db ? da-db : b.bc-a.bc;
+      });
+    } else if(order !== 'row-major'){
+      const first = row[0].bc, last = row[row.length-1].bc;
+      if(Math.abs(last-lastBc) < Math.abs(first-lastBc)) row.reverse();
+    }
     out.push(...row);
-  }
+    lastBc = row[row.length-1].bc;
+  });
   return out;
 }
 
@@ -94,3 +130,20 @@ export function gotoBlock(br, bc){
   clampView();
   draw();
 }
+
+/**
+ * centreOnCell(idx) - pans (keeping the current zoom, but at least 3x so the
+ * cell is legible) to put cell idx in the middle of the stage. Honours the
+ * back-view mirror like gotoBlock.
+ */
+export function centreOnCell(idx){
+  const w = stage.clientWidth, h = stage.clientHeight;
+  view.scale = Math.max(view.scale, 3);
+  const s = view.base * view.scale;
+  const col = colOf(idx) + 0.5, row = rowOf(idx) + 0.5;
+  const cx = (view.backView ? N - col : col) * s;
+  view.tx = w/2 - cx;
+  view.ty = h/2 - row*s;
+  clampView();
+  draw();
+}

pages/pikachu-stitch-companion/js/input.js

@@ -171,6 +171,7 @@ stage.addEventListener('pointerdown',e=>{
         invalidateRoute(state.selected);
         requestRoute(state.selected);
         disarmSetStart();
+        setBlockIdx(0); // block order is anchored at the start point, so restart the walk
         refreshUI(); draw();
       }
     } else if (markMode && state.selected!=null){

pages/pikachu-stitch-companion/js/render.js

@@ -87,6 +87,7 @@ export function draw(){
   const topDir = state.settings.topLegDirection;   // '/' or '\\'
   const showSymbols = symbolsOn && s>=11;
   const textQueue = [];              // {x,y,text,dark} — drawn un-mirrored after restore
+  let startTag = null;               // {x,y} grid-space anchor for the START label
 
   // ---- mirrored region: cells, tie-off knots + buried-tail shading, carry hops ----
   ctx.save();
@@ -215,10 +216,17 @@ export function draw(){
         ctx.beginPath(); ctx.moveTo(px,py-s*0.22); ctx.lineTo(px+s*0.18,py); ctx.lineTo(px,py+s*0.22); ctx.lineTo(px-s*0.18,py);
         ctx.closePath(); ctx.fill();
       }
-      // highlighted start point
+      // highlighted start point: soft halo + bold ring so it reads at any
+      // zoom, plus a "START" tag (queued so it isn't mirrored / clipped)
       const sx=colOf(route.start)*s+s/2, sy=rowOf(route.start)*s+s/2;
-      ctx.strokeStyle='#fde949'; ctx.lineWidth=Math.max(1.4,s*0.1);
-      ctx.beginPath(); ctx.arc(sx,sy,Math.max(3,s*0.32),0,Math.PI*2); ctx.stroke();
+      const rr=Math.max(6,s*0.6);
+      ctx.fillStyle='rgba(253,233,73,0.22)';
+      ctx.beginPath(); ctx.arc(sx,sy,rr*1.9,0,Math.PI*2); ctx.fill();
+      ctx.strokeStyle='#0d0b2c'; ctx.lineWidth=Math.max(4,s*0.22);
+      ctx.beginPath(); ctx.arc(sx,sy,rr,0,Math.PI*2); ctx.stroke();
+      ctx.strokeStyle='#fde949'; ctx.lineWidth=Math.max(2,s*0.12);
+      ctx.beginPath(); ctx.arc(sx,sy,rr,0,Math.PI*2); ctx.stroke();
+      startTag = {x:sx, y:sy-rr*1.9-2};
     }
   }
 
@@ -291,6 +299,18 @@ export function draw(){
     }
   }
 
+  // START tag above the route start marker (front view only; drawn here so
+  // the text isn't mirrored and sits above the cell layers)
+  if (startTag){
+    const fs = Math.max(10, Math.min(16, s*0.9));
+    ctx.font = `800 ${fs}px ui-rounded, system-ui, sans-serif`;
+    ctx.textAlign='center'; ctx.textBaseline='bottom';
+    ctx.lineWidth = 4; ctx.strokeStyle='#0d0b2c'; ctx.lineJoin='round';
+    ctx.strokeText('START', startTag.x, startTag.y);
+    ctx.fillStyle='#fde949';
+    ctx.fillText('START', startTag.x, startTag.y);
+  }
+
   // fine per-cell grid when zoomed close
   if (s>=10){
     ctx.strokeStyle='rgba(244,241,255,0.07)';

pages/pikachu-stitch-companion/js/ui.js

@@ -6,7 +6,7 @@ import { state, colourAt, isStitched, isColourComplete, setStitched, logEvent, u
 import { draw, drawMiniMap, setConfettiHeatOn, confettiHeatOn } from './render.js';
 import { resetProgress, markDirty } from './persistence.js';
 import { getRoute, requestRoute, getPlanningColour, setOnRouteReady, invalidateAllRoutes, stitchesPerLength } from './planner.js';
-import { blockOrderList, gotoBlock, blockOf } from './blocks.js';
+import { blockOrderList, gotoBlock, blockOf, centreOnCell } from './blocks.js';
 import { stitchesPerHour, estimatedFinish, RAILROADING_SLOWDOWN, LENGTHS_PER_SKEIN, skeinsForLengths } from './insights.js';
 
 /* ---------- legend ---------- */
@@ -23,7 +23,11 @@ COLORS.forEach((c,i)=>{
   chip.addEventListener('click', ()=>{
     state.selected = (state.selected === idx) ? null : idx;
     blockIdx = 0; // reset block-nav position (4.4) on colour change
-    if (state.selected!=null) requestRoute(state.selected);
+    centreOnStartPending = state.selected!=null;
+    if (state.selected!=null){
+      const r = requestRoute(state.selected);
+      if (r && r.start!=null){ centreOnStartPending = false; centreOnCell(r.start); }
+    }
     refreshUI(); draw();
   });
   legend.appendChild(chip);
@@ -139,7 +143,16 @@ export function updatePosReadout(i){
     posReadout.textContent = `col ${c+1}, row ${r+1}`;
   }
 }
-setOnRouteReady((v)=>{ if (state.selected===v) refreshRoutePanel(); });
+let centreOnStartPending = false; // set by the chip click; consumed once the route is ready
+setOnRouteReady((v, route)=>{
+  if (state.selected!==v) return;
+  if (centreOnStartPending && route && route.start!=null){
+    centreOnStartPending = false;
+    centreOnCell(route.start);
+    blockIdx = 0; // block order is anchored at the start, so restart the walk
+  }
+  refreshUI();
+});
 
 function refreshRoutePanel(){
   const v = state.selected;