things-api 0.20.0 → 0.20.2

package/dist/write/vectors/ui-drag.js

@@ -88,43 +88,167 @@ function pidOf(n){ return Application('System Events').processes.byName(n).unixI
 function sleep(ms){ $.NSThread.sleepForTimeInterval(ms/1000) }
 function attr(el,name){ var out=Ref(); if($.AXUIElementCopyAttributeValue(el,$(name),out)!==0) return null; return ObjC.castRefToObject(out[0]) }
 function sv(el,name){ var v=attr(el,name); return v? v.js : '' }
-function frame(el){ var p=attr(el,'AXPosition'), z=attr(el,'AXSize'); if(!p||!z) return null;
+function rectOf(p,z){ if(!p||!z) return null;
   var pd=ObjC.castRefToObject($.CFCopyDescription(p)).js, zd=ObjC.castRefToObject($.CFCopyDescription(z)).js;
   var pm=pd.match(/x:([-0-9.]+) y:([-0-9.]+)/), zm=zd.match(/w:([-0-9.]+) h:([-0-9.]+)/);
   return (pm&&zm)?{x:+pm[1],y:+pm[2],w:+zm[1],h:+zm[2]}:null }
+function frame(el){ return rectOf(attr(el,'AXPosition'), attr(el,'AXSize')) }
 function kids(el){ var c=attr(el,'AXChildren'); if(!c) return []; var a=[]; for(var i=0;i<c.count;i++) a.push(c.objectAtIndex(i)); return a }
 function findAll(el, wantRole, depth, acc){ acc=acc||[]; if(depth<0) return acc; var ch=kids(el);
   for(var i=0;i<ch.length;i++){ if(sv(ch[i],'AXRole')===wantRole) acc.push(ch[i]); findAll(ch[i], wantRole, depth-1, acc) } return acc }
 function appEl(){ return $.AXUIElementCreateApplication(pidOf('Things3')) }
-function stdWindow(){ var ws=kids(appEl()); for(var i=0;i<ws.length;i++){ if(sv(ws[i],'AXSubrole')==='AXStandardWindow') return ws[i] } return ws.length?ws[0]:null }
-function sidebarTable(){ var w=stdWindow(); if(!w) return null; var tables=findAll(w,'AXTable',12,[]); var best=null;
-  for(var i=0;i<tables.length;i++){ var f=frame(tables[i]); if(!f) continue; if(f.w<400){ if(!best||f.w<best.f.w) best={el:tables[i],f:f} } }
-  return best?best.el:null }
+function mainWindow(){ var ws=kids(appEl()), std=[];
+  for(var i=0;i<ws.length;i++){ if(sv(ws[i],'AXRole')==='AXWindow' && sv(ws[i],'AXSubrole')==='AXStandardWindow') std.push(ws[i]) }
+  for(var k=0;k<std.length;k++){ if(sv(std[k],'AXMain')===true) return std[k] }
+  return std.length? std[0] : null }
+var NODE_ATTRS=$(['AXValue','AXDescription','AXTitle','AXChildren','AXPosition','AXSize','AXRole']);
+function node(el){ var out=Ref();
+  if($.AXUIElementCopyMultipleAttributeValues(el,NODE_ATTRS,0,out)!==0) return null;
+  var a=ObjC.castRefToObject(out[0]); if(!a||Number(a.count)<7) return null;
+  function s(i){ var v=a.objectAtIndex(i); if(!v) return ''; var j; try{ j=v.js }catch(e){ return '' } return typeof j==='string'? j:'' }
+  var ch=[], c=a.objectAtIndex(3);
+  try{ var n=Number(c.count); for(var i=0;i<n;i++) ch.push(c.objectAtIndex(i)) }catch(e){ ch=[] }
+  var f=null; try{ f=rectOf(a.objectAtIndex(4), a.objectAtIndex(5)) }catch(e){ f=null }
+  return { value:s(0), desc:s(1), title:s(2), children:ch, frame:f, role:s(6) } }
+function textOf(n, acc, depth){ if(n===null||depth<0) return acc;
+  if(n.value) acc.push(n.value); if(n.desc) acc.push(n.desc); if(n.title) acc.push(n.title);
+  for(var i=0;i<n.children.length;i++) textOf(node(n.children[i]), acc, depth-1); return acc }
+function isList(role){ return role==='AXTable'||role==='AXOutline'||role==='AXList' }
+function listPanes(el, depth, acc, sa){ if(depth<0) return acc; var ch=kids(el);
+  for(var i=0;i<ch.length;i++){ var role=sv(ch[i],'AXRole');
+    if(isList(role)){ acc.push({table:ch[i], scroll:sa}); continue }
+    if(role==='AXRow'||role==='AXCell') continue;
+    listPanes(ch[i], depth-1, acc, role==='AXScrollArea'? ch[i] : sa) }
+  return acc }
+function harvestRows(tableEl, depth){ var out=[], ch=kids(tableEl);
+  for(var i=0;i<ch.length;i++){ var n=node(ch[i]); if(n===null) continue;
+    if(n.role!=='AXRow'&&n.role!=='AXTableRow') continue;
+    var f=n.frame;
+    out.push({ text: textOf(n,[],depth).join('|'), x:f?f.x:null, y:f?f.y:null, w:f?f.w:null, h:f?f.h:null }) }
+  return out }
+function segMatch(text, title){ var segs=text.split('|');
+  for(var j=0;j<segs.length;j++){ if(segs[j]===title||segs[j]===title+'.') return true } return false }
+function countTitles(rows, titles){ var n=0;
+  for(var t=0;t<titles.length;t++){ for(var r=0;r<rows.length;r++){ if(segMatch(rows[r].text,titles[t])){ n++; break } } }
+  return n }
+function overlapPx(a,b){ if(!a||!b) return 0; return Math.min(a.x+a.w,b.x+b.w) - Math.max(a.x,b.x) }
+/*
+ * The scroll bar is a DIRECT child of the scroll area (measured), so this reads
+ * the children and stops. It used to be a findAll to depth 4, which walked the
+ * whole table and every row underneath it — the last full-subtree enumeration
+ * in the snapshot, and worth ~0.8s of its ~1.2s on an 85-row sidebar.
+ */
+function scrollFraction(sa){ if(!sa) return null; var ch=kids(sa);
+  for(var b=0;b<ch.length;b++){ if(sv(ch[b],'AXRole')!=='AXScrollBar') continue;
+    var v=attr(ch[b],'AXValue'); if(v===null) continue;
+    var d=ObjC.castRefToObject($.CFCopyDescription(v)).js; var m=d.match(/value = ([+\\-0-9.]+)/);
+    if(m) return +m[1] }
+  return null }
+/*
+ * THE SIDEBAR LOCATOR (SBRES1). Structural + semantic, never geometric:
+ *  - the window is the one carrying AXMain (measured: exactly one does, and it
+ *    is the front one) — never the 40x40 untitled placeholder that always sits
+ *    in the app's AXChildren beside the menu bar;
+ *  - candidate lists are collected by a walk that STOPS at every list container
+ *    and never enters a row, so its cost is a function of window chrome rather
+ *    than of the user's data (measured 125 AX calls vs the old walk's ~3,900);
+ *  - the sidebar is the candidate whose rows carry the caller's own AREA TITLES,
+ *    which is what a sidebar IS. No width threshold: the old w < 400 test
+ *    silently unresolved every sidebar dragged past 400pt (issues #665/#651).
+ */
+function resolveSidebar(titles, depth){
+  var w = mainWindow();
+  if (w === null) return { ok:false, why:'no-window' };
+  var panes = listPanes(w, 8, [], null);
+  if (panes.length === 0) return { ok:false, why:'no-list-candidates', windowFrame:frame(w) };
+  var scored = [], i;
+  for (i=0;i<panes.length;i++){
+    var rows = harvestRows(panes[i].table, depth);
+    scored.push({ pane:panes[i], rows:rows, hits:countTitles(rows,titles), frame:frame(panes[i].table) });
+  }
+  var best=null, tie=false;
+  for (i=0;i<scored.length;i++){
+    if (best===null || scored[i].hits>best.hits){ best=scored[i]; tie=false }
+    else if (scored[i].hits===best.hits && best.hits>0) tie=true;
+  }
+  if (best===null || best.hits===0){
+    var seen=[]; for(i=0;i<scored.length;i++) seen.push({frame:scored[i].frame, rows:scored[i].rows.length});
+    return { ok:false, why:'no-title-match', searched:seen, titles:titles.length };
+  }
+  if (tie) return { ok:false, why:'ambiguous-sidebar', titles:titles.length };
+  // HIDDEN-SIDEBAR SIGNATURE (measured): View > Hide Sidebar leaves the sidebar
+  // scroll area in the tree with its old frame while the content pane slides
+  // over it, so the two list panes OVERLAP horizontally by the sidebar's width.
+  // Visible (and full-screen) states never overlap. No AX attribute marks it.
+  var vp = best.pane.scroll===null? null : frame(best.pane.scroll);
+  for (i=0;i<scored.length;i++){
+    if (scored[i]===best || scored[i].pane.scroll===null) continue;
+    if (overlapPx(vp, frame(scored[i].pane.scroll)) > 1) return { ok:false, why:'sidebar-hidden' };
+  }
+  if (vp === null) return { ok:false, why:'no-viewport' };
+  if (best.rows.length === 0) return { ok:false, why:'no-rows' };
+  return { ok:true, table:best.pane.table, scroll:best.pane.scroll, viewport:vp, rows:best.rows, hits:best.hits };
+}
 var MOVED=5, DOWN=1, UP=2, DRAG=6;
 function mev(t,x,y,cs){ var e=$.CGEventCreateMouseEvent($(), t, $.CGPointMake(x,y), 0); if(cs) $.CGEventSetIntegerValueField(e,1,cs); return e }
 function postHID(ev){ $.CGEventPost($.kCGHIDEventTap, ev) }`;
-/** Snapshot: sidebar rows (text + frames), viewport rect, scroll fraction. */
-export function jxaSidebarSnapshotScript() {
+/**
+ * How deep the per-row text walk goes on the FAST path, and on the fallback.
+ *
+ * MEASURED (SBRES1, 84-row sidebar): the driver consumes a row's text in exactly
+ * two ways — `text === ''` (spacer detection) and an exact segment match against
+ * a known area title — and depth 2 agrees with the old depth-6 walk on BOTH for
+ * every row, at 235 AX calls / 197ms instead of 3,376 / 1,675ms. Depth 4 and up
+ * is byte-identical to the old output, so the escalation below can never lose
+ * information the ladder used to have.
+ */
+const ROW_TEXT_DEPTH_FAST = 2;
+const ROW_TEXT_DEPTH_FULL = 6;
+/**
+ * Snapshot: sidebar rows (text + frames), viewport rect, scroll fraction.
+ *
+ * `areaTitles` is what makes the locator semantic — the sidebar is identified as
+ * the list that holds the caller's own areas. It is also the ESCALATION oracle:
+ * every area always renders a sidebar row (AXDRAG1: even off-viewport rows
+ * expose valid virtualized frames), so a shallow harvest that finds fewer titles
+ * than the database holds is re-run at full depth before the ladder sees it.
+ */
+export function jxaSidebarSnapshotScript(areaTitles) {
     return `${JXA_PRELUDE}
-function allText(el, acc, depth){ acc=acc||[]; depth=depth==null?6:depth; if(depth<0) return acc;
-  var v=sv(el,'AXValue'); if(v) acc.push(v); var d=sv(el,'AXDescription'); if(d) acc.push(d);
-  var t=sv(el,'AXTitle'); if(t) acc.push(t); var ch=kids(el); for(var i=0;i<ch.length;i++) allText(ch[i],acc,depth-1); return acc }
-var t = sidebarTable();
-var out = { viewport: null, scroll: null, rows: [] };
-if (t !== null) {
-  var w = stdWindow();
-  var areas = findAll(w,'AXScrollArea',12,[]);
-  for (var i=0;i<areas.length;i++){ var f=frame(areas[i]); if(f && f.w<400){ out.viewport=f;
-    var bars=findAll(areas[i],'AXScrollBar',4,[]);
-    for (var b=0;b<bars.length;b++){ var v=attr(bars[b],'AXValue'); if(v===null) continue;
-      var d=ObjC.castRefToObject($.CFCopyDescription(v)).js; var m=d.match(/value = ([+\\-0-9.]+)/);
-      if(m){ out.scroll = +m[1]; break } }
-    break } }
-  var ch = kids(t);
-  for (var r=0;r<ch.length;r++){ var role=sv(ch[r],'AXRole');
-    if (role==='AXRow'||role==='AXTableRow'){ var rf=frame(ch[r]);
-      out.rows.push({ text: allText(ch[r],[],6).join('|'), x: rf?rf.x:null, y: rf?rf.y:null, w: rf?rf.w:null, h: rf?rf.h:null }) } }
+var TITLES = ${JSON.stringify([...areaTitles])};
+var r = resolveSidebar(TITLES, ${ROW_TEXT_DEPTH_FAST});
+var out;
+if (r.ok !== true) { out = { ok:false, why:r.why, searched:r.searched||null, titles:r.titles||null, windowFrame:r.windowFrame||null } }
+else {
+  var deep = false;
+  if (r.hits < TITLES.length) {
+    var full = resolveSidebar(TITLES, ${ROW_TEXT_DEPTH_FULL});
+    if (full.ok === true && full.hits > r.hits) { r = full; deep = true }
+  }
+  out = { ok:true, viewport:r.viewport, scroll:scrollFraction(r.scroll), rows:r.rows,
+          deep:deep, matched:r.hits, expected:TITLES.length };
+}
+JSON.stringify(out)`;
 }
+/**
+ * Show or hide the sidebar through Things' own View menu (SBRES1 normalization
+ * rung). English-pinned and fail-closed: a menu without the item — a localized
+ * app, or a Things update that moved it — refuses and names what it did find,
+ * rather than clicking whatever sits in that position (UIC1 precedent).
+ */
+export function jxaSidebarVisibilityScript(want) {
+    const wanted = want === "show" ? "Show Sidebar" : "Hide Sidebar";
+    return `var se = Application('System Events');
+var out = { clicked:false, why:'', items:[] };
+try {
+  var items = se.processes.byName('Things3').menuBars[0].menuBarItems.byName('View').menus[0].menuItems;
+  for (var i = 0; i < items.length; i++) {
+    var name = items[i].name();
+    if (name) out.items.push(name);
+    if (name === ${JSON.stringify(wanted)}) { items[i].click(); out.clicked = true }
+  }
+  if (!out.clicked) out.why = 'the View menu has no "${wanted}" item';
+} catch (e) { out.why = 'the View menu did not respond: ' + e }
 JSON.stringify(out)`;
 }
 /**
@@ -133,13 +257,12 @@ JSON.stringify(out)`;
  * Positive clicks move the CONTENT down (earlier rows return, row y grows);
  * negative clicks reveal lower rows (row y shrinks) — AXDRAG1-b.
  */
-export function jxaSidebarScrollScript(clicks) {
+export function jxaSidebarScrollScript(clicks, areaTitles) {
     const n = Math.trunc(clicks);
     return `${JXA_PRELUDE}
-var w = stdWindow();
-var sb = null;
-if (w !== null) { var sas = findAll(w,'AXScrollArea',12,[]);
-  for (var i=0;i<sas.length;i++){ var f=frame(sas[i]); if(f && f.w<400){ sb=f; break } } }
+var TITLES = ${JSON.stringify([...areaTitles])};
+var r = resolveSidebar(TITLES, ${ROW_TEXT_DEPTH_FAST});
+var sb = r.ok === true ? r.viewport : null;
 if (sb === null) { 'NO_SIDEBAR' } else {
   postHID(mev(MOVED, sb.x + sb.w/2, sb.y + sb.h/2, 0)); sleep(50);
   var n = ${n}, dir = n < 0 ? -1 : 1;
@@ -168,20 +291,28 @@ postHID(mev(DRAG, tx, ty, 1)); sleep(400);
 postHID(mev(UP, tx, ty, 1));
 'DONE'`;
 }
-function snapshotCommand() {
+function snapshotCommand(areaTitles) {
     return {
         primitive: "sidebar-snapshot",
         label: "read the sidebar rows and viewport",
         lang: "javascript",
-        script: jxaSidebarSnapshotScript(),
+        script: jxaSidebarSnapshotScript(areaTitles),
+    };
+}
+function sidebarVisibilityCommand(want) {
+    return {
+        primitive: "sidebar-visibility",
+        label: want === "show" ? "show the sidebar (View menu)" : "hide the sidebar again (View menu)",
+        lang: "javascript",
+        script: jxaSidebarVisibilityScript(want),
     };
 }
-function scrollCommand(clicks) {
+function scrollCommand(clicks, areaTitles) {
     return {
         primitive: "sidebar-scroll",
         label: `scroll the sidebar (${clicks} clicks)`,
         lang: "javascript",
-        script: jxaSidebarScrollScript(clicks),
+        script: jxaSidebarScrollScript(clicks, areaTitles),
     };
 }
 function dragCommand(sx, sy, tx, ty) {
@@ -203,22 +334,19 @@ function dragCommand(sx, sy, tx, ty) {
  * Escape-aborts (AXDRAG1-d: byte-identical index vector) and reports it.
  */
 export function jxaSidebarHeldScrollDragScript(sx, sy, anchorTitle, // null = drop below the last row (to-last)
-maxTicks) {
+maxTicks, areaTitles) {
     const [a, b] = [sx, sy].map(Math.round);
     const anchor = JSON.stringify(anchorTitle);
     return `${JXA_PRELUDE}
-function allText(el, acc, depth){ acc=acc||[]; depth=depth==null?6:depth; if(depth<0) return acc;
-  var v=sv(el,'AXValue'); if(v) acc.push(v); var d=sv(el,'AXDescription'); if(d) acc.push(d);
-  var t=sv(el,'AXTitle'); if(t) acc.push(t); var ch=kids(el); for(var i=0;i<ch.length;i++) allText(ch[i],acc,depth-1); return acc }
-function liveRows(){ var t=sidebarTable(); if(!t) return []; var out=[]; var ch=kids(t);
-  for(var r=0;r<ch.length;r++){ var role=sv(ch[r],'AXRole');
-    if(role==='AXRow'||role==='AXTableRow'){ var f=frame(ch[r]);
-      if(f) out.push({text:allText(ch[r],[],6).join('|'), f:f}) } }
+var TITLES = ${JSON.stringify([...areaTitles])};
+function liveRows(){ var r=resolveSidebar(TITLES, ${ROW_TEXT_DEPTH_FAST}); if(r.ok!==true) return [];
+  var out=[]; for(var i=0;i<r.rows.length;i++){ var w=r.rows[i];
+    if(w.y===null||w.h===null) continue;
+    out.push({text:w.text, f:{x:w.x,y:w.y,w:w.w,h:w.h}}) }
   out.sort(function(p,q){ return p.f.y-q.f.y }); return out }
 function matches(text, title){ var segs=text.split('|');
   for(var j=0;j<segs.length;j++){ if(segs[j]===title||segs[j]===title+'.') return true } return false }
-function viewportRect(){ var w=stdWindow(); if(!w) return null; var sas=findAll(w,'AXScrollArea',12,[]);
-  for(var i=0;i<sas.length;i++){ var f=frame(sas[i]); if(f && f.w<400) return f } return null }
+function viewportRect(){ var r=resolveSidebar(TITLES, ${ROW_TEXT_DEPTH_FAST}); return r.ok===true? r.viewport : null }
 var sx=${a}, sy=${b}, anchorTitle=${anchor}, maxTicks=${Math.trunc(maxTicks)};
 var vp = viewportRect();
 if (vp === null) { JSON.stringify({aborted:true, why:'no sidebar viewport'}) } else {
@@ -265,8 +393,8 @@ if (b0 === null) {
     // Post-wheel SETTLE: the list can drift a few px after the last tick
     // (AXDRAG2-a saw ~8px). Wait until the live boundary is stable across
     // two consecutive reads before aiming.
-    var stable = 0, lastY = null, w = 0;
-    for (w = 0; w < 12 && stable < 2; w++) {
+    var stable = 0, lastY = null, settleTick = 0;
+    for (settleTick = 0; settleTick < 12 && stable < 2; settleTick++) {
       postHID(mev(DRAG, sx, sy, 1)); sleep(140);
       var bs = boundaryNow(); if (bs === null) break;
       if (lastY !== null && Math.abs(bs.y - lastY) < 1) stable++;
@@ -293,12 +421,93 @@ if (b0 === null) {
 JSON.stringify(result)
 }`;
 }
-function heldScrollDragCommand(sx, sy, anchorTitle, maxTicks) {
+/**
+ * SBCOL1 — actuate an area row's DISCLOSURE CHEVRON.
+ *
+ * The toggle is two nodes: an inert `AXImage d="Source Toggle Template"` (what
+ * AXDRAG2-b measured and called "not actuatable") inside an `AXUnknown` wrapper
+ * that DOES advertise `AXPress` — and that press is DECORATIVE, exactly as REPX1
+ * §1.2 predicts for Things' custom rows (`AXError = 0`, zero census delta). What
+ * actuates is a synthesized click at the image's OWN resolved frame; SBCOL1
+ * toggled it both directions twice with zero beeps and zero focus steal.
+ *
+ * Fail-closed twice over: the chevron is resolved from the LIVE tree inside this
+ * same script (never a frame carried over from an earlier snapshot generation),
+ * and a chevron whose center lies outside the scroll-area band is REFUSED rather
+ * than clicked — an off-viewport row still exposes a valid virtualized frame
+ * (AXDRAG1), so clicking one would land somewhere else entirely.
+ *
+ * `ordinal` selects among same-titled rows in visual (y) order, the AXDRAG3
+ * disambiguation the rest of the driver uses; -1 means "the only row with this
+ * title", and an ambiguous match refuses.
+ */
+export function jxaSidebarChevronClickScript(title, ordinal, areaTitles) {
+    const want = JSON.stringify(title);
+    const ord = Math.trunc(ordinal);
+    return `${JXA_PRELUDE}
+var TITLES = ${JSON.stringify([...areaTitles])};
+function allText(el, acc, depth){ acc=acc||[]; depth=depth==null?6:depth; if(depth<0) return acc;
+  var v=sv(el,'AXValue'); if(v) acc.push(v); var d=sv(el,'AXDescription'); if(d) acc.push(d);
+  var t=sv(el,'AXTitle'); if(t) acc.push(t); var ch=kids(el); for(var i=0;i<ch.length;i++) allText(ch[i],acc,depth-1); return acc }
+function matches(el, title){ var segs=allText(el,[],6);
+  for(var j=0;j<segs.length;j++){ if(segs[j]===title||segs[j]===title+'.') return true } return false }
+function chevronOf(el, depth){ if(depth<0) return null; var ch=kids(el);
+  for(var i=0;i<ch.length;i++){
+    if(sv(ch[i],'AXRole')==='AXImage' && sv(ch[i],'AXDescription').indexOf('Toggle')>=0) return ch[i];
+    var r=chevronOf(ch[i], depth-1); if(r) return r }
+  return null }
+var want=${want}, ord=${ord};
+var sb = resolveSidebar(TITLES, ${ROW_TEXT_DEPTH_FAST});
+if (sb.ok !== true) { JSON.stringify({clicked:false, why:'the sidebar did not resolve (' + sb.why + ')'}) } else {
+var t = sb.table, vp = sb.viewport;
+if (vp === null) { JSON.stringify({clicked:false, why:'the sidebar viewport did not resolve'}) } else {
+var ch = kids(t), hits = [];
+for (var r=0;r<ch.length;r++){ var role=sv(ch[r],'AXRole');
+  if (role!=='AXRow' && role!=='AXTableRow') continue;
+  if (!matches(ch[r], want)) continue;
+  var rf = frame(ch[r]); if (rf) hits.push({el:ch[r], f:rf}) }
+hits.sort(function(p,q){ return p.f.y-q.f.y });
+var pick = ord < 0 ? (hits.length === 1 ? hits[0] : null) : (hits[ord] || null);
+if (pick === null) {
+  JSON.stringify({clicked:false, why:'the area row did not resolve uniquely', rows:hits.length})
+} else {
+  var img = chevronOf(pick.el, 5);
+  if (img === null) { JSON.stringify({clicked:false, why:'the row exposes no disclosure chevron'}) }
+  else {
+    var cf = frame(img);
+    if (cf === null) { JSON.stringify({clicked:false, why:'the chevron exposed no frame'}) }
+    else {
+      var cx = cf.x + cf.w/2, cy = cf.y + cf.h/2;
+      if (cy < vp.y + 6 || cy > vp.y + vp.h - 6) {
+        JSON.stringify({clicked:false, why:'the chevron is outside the visible sidebar band', y:cy})
+      } else {
+        // REPX1 §1.2 rig law: flags set EXPLICITLY on EVERY synthetic event
+        // (zero included), and a MOVED settle before the press.
+        var mv=mev(MOVED,cx,cy,0); $.CGEventSetFlags(mv,0); postHID(mv); sleep(300);
+        var dn=mev(DOWN,cx,cy,1); $.CGEventSetFlags(dn,0); postHID(dn); sleep(90);
+        var up=mev(UP,cx,cy,1); $.CGEventSetFlags(up,0); postHID(up); sleep(250);
+        JSON.stringify({clicked:true, x:cx, y:cy})
+      }
+    }
+  }
+}
+}}`;
+}
+function chevronClickCommand(title, ordinal, areaTitles) {
+    return {
+        primitive: "sidebar-chevron",
+        label: `toggle the disclosure arrow on the area row "${title}"`,
+        lang: "javascript",
+        script: jxaSidebarChevronClickScript(title, ordinal, areaTitles),
+        meta: { title, ordinal },
+    };
+}
+function heldScrollDragCommand(sx, sy, anchorTitle, maxTicks, areaTitles) {
     return {
         primitive: "sidebar-held-drag",
         label: "held-scroll drag toward the destination",
         lang: "javascript",
-        script: jxaSidebarHeldScrollDragScript(sx, sy, anchorTitle, maxTicks),
+        script: jxaSidebarHeldScrollDragScript(sx, sy, anchorTitle, maxTicks, areaTitles),
         meta: { sx, sy, anchorTitle, maxTicks },
     };
 }
@@ -370,20 +579,51 @@ export function boundaryBelowLast(allRows) {
     const half = (medianSpacerHeight(allRows) ?? last.h / 2) / 2;
     return last.y + last.h + half;
 }
+const SNAPSHOT_FAILURES = new Set([
+    "no-window",
+    "no-list-candidates",
+    "no-title-match",
+    "ambiguous-sidebar",
+    "sidebar-hidden",
+    "no-viewport",
+    "no-rows",
+]);
 export function parseSidebarSnapshot(stdout) {
+    let parsed;
     try {
-        const parsed = JSON.parse(stdout.trim());
-        if (typeof parsed !== "object" || parsed === null || !Array.isArray(parsed.rows))
-            return null;
-        return {
-            viewport: parsed.viewport ?? null,
-            scroll: parsed.scroll ?? null,
-            rows: parsed.rows.filter((r) => typeof r.y === "number" && typeof r.x === "number" && typeof r.h === "number"),
-        };
+        parsed = JSON.parse(stdout.trim());
     }
     catch {
-        return null;
+        return { ok: false, why: "unparsable" };
+    }
+    if (typeof parsed !== "object" || parsed === null)
+        return { ok: false, why: "unparsable" };
+    const obj = parsed;
+    if (obj["ok"] !== true) {
+        const why = typeof obj["why"] === "string" && SNAPSHOT_FAILURES.has(obj["why"]) ? obj["why"] : null;
+        if (why === null)
+            return { ok: false, why: "unparsable" };
+        return {
+            ok: false,
+            why: why,
+            ...(Array.isArray(obj["searched"]) && {
+                searched: obj["searched"],
+            }),
+            ...(typeof obj["titles"] === "number" && { titles: obj["titles"] }),
+        };
     }
+    if (!Array.isArray(obj["rows"]))
+        return { ok: false, why: "unparsable" };
+    const rows = obj["rows"].filter((r) => typeof r.y === "number" && typeof r.x === "number" && typeof r.h === "number");
+    const viewport = obj["viewport"] ?? null;
+    if (viewport === null)
+        return { ok: false, why: "no-viewport" };
+    if (rows.length === 0)
+        return { ok: false, why: "no-rows" };
+    return {
+        ok: true,
+        snapshot: { viewport, scroll: obj["scroll"] ?? null, rows },
+    };
 }
 /**
  * Does a row's static-text carry this exact title as a segment? Sidebar row
@@ -530,6 +770,98 @@ export function correctedDropY(staticY, sourceCenterY, span) {
 export function inBand(y, viewport, pad = BAND_PAD) {
     return y >= viewport.y + pad && y <= viewport.y + viewport.h - pad;
 }
+/**
+ * The travel a single certified drag can cover inside this viewport: the band
+ * minus the grab/drop margins at both ends. The rung-1 shared-viewport test and
+ * the tall-section pre-flight both measure against this ONE number.
+ */
+export function usableDragSpan(viewport) {
+    return viewport.h - 4 * BAND_PAD;
+}
+/**
+ * The TALLEST section the gesture would have to climb over, or null when every
+ * one of them fits. #658: an area's projects render beneath it, so a section can
+ * be taller than the whole sidebar viewport — and BOTH shipped rungs need the
+ * source row and the drop boundary visible AT ONCE, so such a section is a wall
+ * no amount of scrolling gets around. Measured over the travel span between the
+ * grab point and the aimed boundary; the source's OWN section is excluded (
+ * lifting it collapses it) and a section is only counted when the snapshot
+ * actually resolved rows inside it, so a partially-materialized AX tree cannot
+ * fabricate a wall out of a gap between two distant rows.
+ */
+export function sectionsInSpan(orderedAreaRows, allRows, fromY, toY, sourceTitle) {
+    const lo = Math.min(fromY, toY);
+    const hi = Math.max(fromY, toY);
+    const tableBottom = allRows.reduce((max, r) => Math.max(max, r.y + r.h), -Infinity);
+    const out = [];
+    for (let i = 0; i < orderedAreaRows.length; i++) {
+        const section = orderedAreaRows[i];
+        if (section === undefined || section.title === sourceTitle)
+            continue;
+        const top = section.row.y;
+        const bottom = orderedAreaRows[i + 1]?.row.y ?? tableBottom;
+        if (bottom <= lo || top >= hi)
+            continue; // outside the travel span
+        const rows = allRows.filter((r) => r.y >= top && r.y < bottom).length;
+        // Which same-titled row IS this one, in visual order (AXDRAG3) — the
+        // chevron primitive needs it to click the right one.
+        const ordinal = orderedAreaRows
+            .filter((a) => a.title === section.title)
+            .findIndex((a) => a.row === section.row);
+        out.push({
+            title: section.title,
+            height: bottom - top,
+            rows,
+            ordinal: orderedAreaRows.filter((a) => a.title === section.title).length > 1 ? ordinal : -1,
+        });
+    }
+    return out;
+}
+/** The tallest section in the travel span, or null when every one of them fits. */
+export function tallestSectionInSpan(orderedAreaRows, allRows, fromY, toY, sourceTitle) {
+    let worst = null;
+    for (const s of sectionsInSpan(orderedAreaRows, allRows, fromY, toY, sourceTitle)) {
+        if (worst === null || s.height > worst.height)
+            worst = s;
+    }
+    return worst;
+}
+/**
+ * Every section in the travel span the ladder cannot climb — tallest FIRST, so
+ * the collapse rung clears the worst obstruction before spending a gesture on a
+ * marginal one. SBCOL1 §4 measured a two-wall span: collapsing both turned a
+ * ten-position move into an ordinary multi-hop.
+ */
+export function blockingSectionsInSpan(orderedAreaRows, allRows, fromY, toY, sourceTitle, viewport) {
+    return sectionsInSpan(orderedAreaRows, allRows, fromY, toY, sourceTitle)
+        .filter((s) => sectionBlocks(s, viewport))
+        .toSorted((a, b) => b.height - a.height);
+}
+/**
+ * Is this section a WALL for the shipped ladder (rung 1 + the multi-hop floor)?
+ * A section taller than one drag's usable span can never be crossed, because
+ * every hop must land the source on the far side of it in ONE gesture.
+ */
+export function sectionBlocks(section, viewport) {
+    return section.height > usableDragSpan(viewport) && section.rows >= 2;
+}
+/**
+ * The refusal an unclimbable section earns once the COLLAPSE RUNG has failed on
+ * it (SBCOL1) — the honest twin of the old "the viewport is too small to make
+ * progress" copy, which blamed the window size for a geometry no window size
+ * fixes (#658). `whyCollapseFailed` names what stopped the driver from folding
+ * the section away itself, so the advice to do it by hand is not offered blind.
+ */
+export function blockedSectionDetail(section, viewport, destination, whyCollapseFailed) {
+    return (`the area "${section.title}" and the ${section.rows - 1} row(s) Things renders under it ` +
+        `stand between this area and ${destination}, and that block is taller than the sidebar ` +
+        `shows at once (about ${Math.round(section.height)}pt of rows against ${Math.round(viewport.h)}pt ` +
+        "of visible list) — a drag has to see where it starts and where it lands at the same time, " +
+        `so no gesture can cross it. Collapsing "${section.title}" out of the way did not work` +
+        `${whyCollapseFailed === undefined ? "" : ` (${whyCollapseFailed})`}. Collapse it in the ` +
+        "sidebar with the arrow on its row, or make the Things window taller, then re-run — or drag " +
+        "the area by hand");
+}
 /**
  * Grab/drop x: a fixed FRACTION of the row's resolved width (≈ the label area
  * NATIVE1 clicked at x+170 on a 240px row), clear of the leading icon and the
@@ -585,13 +917,61 @@ async function runCmd(ctx, cmd) {
     return ctx.run(cmd, STEP_TIMEOUT_MS);
 }
 async function takeSnapshot(ctx) {
-    const res = await runCmd(ctx, snapshotCommand());
-    if (!res.ok)
-        return null;
-    const snap = parseSidebarSnapshot(res.stdout);
-    if (snap === null || snap.viewport === null || snap.rows.length === 0)
-        return null;
-    return snap;
+    const res = await runCmd(ctx, snapshotCommand(ctx.areaTitles));
+    if (res.timedOut === true)
+        return { ok: false, why: "timeout" };
+    if (!res.ok) {
+        return { ok: false, why: "dispatch-failed", ...(res.stderr.trim() && { stderr: res.stderr }) };
+    }
+    return parseSidebarSnapshot(res.stdout);
+}
+/** The snapshot when only its presence matters (scroll loops, re-censuses). */
+async function snapshotOrNull(ctx) {
+    const out = await takeSnapshot(ctx);
+    return out.ok ? out.snapshot : null;
+}
+/**
+ * One honest sentence per real cause, each naming the thing to change. The
+ * remediation matters as much as the diagnosis: the old copy told a user with a
+ * plainly-open sidebar to check whether the sidebar was open.
+ */
+export function describeSnapshotFailure(refusal) {
+    switch (refusal.why) {
+        case "timeout":
+            return (`reading the sidebar took longer than ${Math.round(STEP_TIMEOUT_MS / 1000)}s and was ` +
+                "stopped — nothing was dragged. This is a very large sidebar, a busy Mac, or both; " +
+                "collapse some areas or close other windows and re-run");
+        case "dispatch-failed":
+            return `the sidebar read did not run${refusal.stderr ? `: ${refusal.stderr.trim()}` : ""}`;
+        case "unparsable":
+            return "the sidebar read returned output this version cannot read";
+        case "no-window":
+            return ("Things is running but has no open window — only the placeholder it keeps in the " +
+                "background. Open the Things window (click its Dock icon) and re-run");
+        case "no-list-candidates":
+            return ("the Things window exposes no list at all — it may still be opening. Wait for it to " +
+                "finish drawing and re-run");
+        case "sidebar-hidden":
+            return ("the sidebar is hidden in this Things window — show it with View ▸ Show Sidebar (⌘/) " +
+                "and re-run");
+        case "no-title-match": {
+            const where = refusal.searched === undefined
+                ? ""
+                : ` (searched ${refusal.searched.length} list(s): ${refusal.searched
+                    .map((s) => `${s.rows} row(s)${s.frame ? ` at ${Math.round(s.frame.w)}pt wide` : ""}`)
+                    .join(", ")})`;
+            return (`none of the lists in the Things window holds a row for any of your ${refusal.titles ?? 0} ` +
+                `area(s)${where} — the sidebar may be scrolled inside a different window, or a Things ` +
+                "update may have changed how it exposes rows");
+        }
+        case "ambiguous-sidebar":
+            return ("two lists in the Things window both look like the sidebar, so nothing was dragged — " +
+                "close the extra Things window (File ▸ Close) and re-run");
+        case "no-viewport":
+            return "the sidebar's scrolling container did not resolve";
+        case "no-rows":
+            return "the sidebar resolved but exposed no rows — quit and reopen Things, then retry";
+    }
 }
 /**
  * Scroll until `wanted(snapshot)` returns a zero-ish error, re-resolving
@@ -608,7 +988,7 @@ async function scrollUntil(ctx, wanted, goodEnough) {
     let stalls = 0;
     for (let iter = 0; iter < MAX_SCROLL_ITER; iter++) {
         // each scroll must observe the frames the previous scroll produced
-        const snap = await takeSnapshot(ctx);
+        const snap = await snapshotOrNull(ctx);
         if (snap === null)
             return null;
         const err = wanted(snap);
@@ -637,7 +1017,7 @@ async function scrollUntil(ctx, wanted, goodEnough) {
         const clicks = Math.max(-12, Math.min(12, Math.round(err / pxPerClick) || Math.sign(err))) * dirFactor;
         lastClicks = clicks;
         // strictly sequential scroll-and-remeasure loop
-        const res = await runCmd(ctx, scrollCommand(clicks));
+        const res = await runCmd(ctx, scrollCommand(clicks, ctx.areaTitles));
         if (!res.ok)
             return null;
     }
@@ -654,6 +1034,159 @@ async function pollState(ctx, check) {
     }
     return null;
 }
+// ------------------------------------------------- the collapse rung (SBCOL1)
+/** How many table rows a titled section currently renders (its own row included). */
+function sectionRowCount(snap, areaTitles, title, ordinal) {
+    const ordered = areaRowsInOrder(snap.rows, areaTitles);
+    const i = ordinal < 0 ? ordered.findIndex((a) => a.title === title) : nthByTitle(ordered, title, ordinal);
+    const section = ordered[i];
+    if (i < 0 || section === undefined)
+        return null;
+    const tableBottom = snap.rows.reduce((max, r) => Math.max(max, r.y + r.h), -Infinity);
+    const bottom = ordered[i + 1]?.row.y ?? tableBottom;
+    return snap.rows.filter((r) => r.y >= section.row.y && r.y < bottom).length;
+}
+/**
+ * Scroll the named area's row into the visible band, then actuate its chevron
+ * and CONFIRM the section changed size.
+ *
+ * The scrutiny doctrine's probe law in production form: a re-census follows the
+ * one input step, and a click that did not move the section fast-fails — the
+ * ladder must never proceed on the assumption that a gesture worked. `want`
+ * says which direction counts as success, so the same primitive collapses and
+ * re-expands.
+ */
+async function toggleDisclosure(ctx, areaTitles, title, ordinal, want) {
+    // The row must be inside the band before the chevron can be clicked: an
+    // off-viewport row still exposes a valid virtualized frame (AXDRAG1), so an
+    // unscrolled click would land outside the sidebar entirely.
+    const ready = await scrollUntil(ctx, (s) => {
+        if (s.viewport === null)
+            return null;
+        const row = resolveAreaRow(s.rows, title, ordinal);
+        if (row === null)
+            return null;
+        const center = row.y + row.h / 2;
+        if (inBand(center, s.viewport))
+            return null;
+        return s.viewport.y + s.viewport.h / 2 - center;
+    });
+    if (ready === null) {
+        return { clicked: false, ok: false, why: `"${title}"'s row could not be scrolled into view` };
+    }
+    const rowsBefore = sectionRowCount(ready, areaTitles, title, ordinal);
+    if (rowsBefore === null) {
+        return { clicked: false, ok: false, why: `"${title}"'s row did not resolve` };
+    }
+    // the gesture must land before the re-census that judges it
+    const res = await runCmd(ctx, chevronClickCommand(title, ordinal, ctx.areaTitles));
+    let clicked = false;
+    let why = "the disclosure arrow did not respond";
+    if (res.ok) {
+        try {
+            const parsed = JSON.parse(res.stdout.trim());
+            clicked = parsed.clicked === true;
+            if (typeof parsed.why === "string")
+                why = parsed.why;
+        }
+        catch {
+            /* keep the default reason */
+        }
+    }
+    if (!clicked)
+        return { clicked: false, ok: false, why };
+    // The click WENT OUT. Everything below reports `clicked: true` even when it
+    // fails, because the app has already changed its state and a verification
+    // that could not run is not evidence that nothing happened. SBCOL1 §6 found
+    // this the hard way: quitting Things during the re-census left the area
+    // collapsed on disk while the ledger — written only on success — held
+    // nothing, so a durable change to the sidebar went unmentioned. The ledger
+    // records what the driver DID, not what it managed to confirm.
+    //
+    // RE-CENSUS after the input step — a gesture whose effect we cannot see is
+    // still never allowed to carry the ladder forward.
+    await ctx.sleep(600);
+    const after = await takeSnapshot(ctx);
+    if (!after.ok) {
+        return { clicked: true, ok: false, why: describeSnapshotFailure(after) };
+    }
+    const rowsAfter = sectionRowCount(after.snapshot, areaTitles, title, ordinal);
+    if (rowsAfter === null) {
+        return { clicked: true, ok: false, why: `"${title}"'s row did not resolve after the click` };
+    }
+    const moved = want === "fewer" ? rowsAfter < rowsBefore : rowsAfter > rowsBefore;
+    if (!moved) {
+        return {
+            clicked: true,
+            ok: false,
+            why: `the click left "${title}" rendering ${rowsAfter} row(s) — the section did not ${want === "fewer" ? "collapse" : "re-expand"}`,
+        };
+    }
+    return { clicked: true, ok: true, rowsBefore, rowsAfter };
+}
+/**
+ * Fold every blocking section away, recording what to put back. Stops at the
+ * FIRST section it cannot collapse — a half-cleared path is not a path, and the
+ * caller falls through to the honest refusal (with the already-collapsed areas
+ * restored by the epilogue like any other exit).
+ */
+async function collapseWalls(ctx, walls, areaTitles, collapsed) {
+    for (const wall of walls) {
+        // Already folded and STILL measuring as a wall: the gesture is not working
+        // on this section, so stop rather than clicking at it again.
+        if (collapsed.some((c) => c.title === wall.title && c.ordinal === wall.ordinal)) {
+            return { ok: false, why: `"${wall.title}" stayed oversized after it was collapsed` };
+        }
+        // each collapse must be verified before the next one is attempted
+        const outcome = await toggleDisclosure(ctx, areaTitles, wall.title, wall.ordinal, "fewer");
+        // Ledger on the CLICK, not on the confirmation (SBCOL1 §6): a fold that
+        // went out and could not be verified is still a fold to answer for.
+        if (outcome.clicked) {
+            collapsed.push({
+                title: wall.title,
+                ordinal: wall.ordinal,
+                rowsExpanded: outcome.ok ? outcome.rowsBefore : null,
+            });
+        }
+        if (!outcome.ok)
+            return { ok: false, why: outcome.why };
+    }
+    return { ok: true };
+}
+/**
+ * Put the sidebar back — in REVERSE order, so the list reflows the way it was
+ * folded. Runs on EVERY exit path (success, refusal, abort, throw): the
+ * disclosure state lives in the app's preferences and survives a relaunch
+ * (SBCOL1 §3), so an unrestored collapse is a durable change to the user's
+ * sidebar that they never asked for.
+ */
+async function restoreDisclosure(ctx, areaTitles, collapsed) {
+    const failed = [];
+    for (const entry of collapsed.toReversed()) {
+        // each re-expansion must be verified before the next one is attempted
+        const outcome = await toggleDisclosure(ctx, areaTitles, entry.title, entry.ordinal, "more");
+        if (!outcome.ok)
+            failed.push(entry.title);
+    }
+    return failed;
+}
+/** Append the collapse rung's own account to whatever the ladder concluded. */
+function withCollapseOutcome(result, collapsed, restoreFailed) {
+    if (collapsed.length === 0)
+        return result;
+    const names = collapsed.map((c) => `"${c.title}"`).join(", ");
+    const restored = restoreFailed.length === 0
+        ? "and expanded again afterwards"
+        : `but ${restoreFailed.map((t) => `"${t}"`).join(", ")} could not be expanded again — ` +
+            "the sidebar is left collapsed there until you click the arrow (or Things is relaunched, " +
+            "which keeps it collapsed)";
+    return {
+        ...result,
+        detail: `${result.detail} (${names} collapsed to clear the path, ${restored})`,
+        collapsed: collapsed.map((c) => c.title),
+        ...(restoreFailed.length > 0 && { restoreFailed }),
+    };
+}
 /** Resolve source row + corrected drop Y against ONE snapshot generation. */
 function planDrop(snap, spec, areaTitles, placement, 
 // DUPLICATE-title disambiguation (ORDFIN2 AXDRAG3), recomputed from live state
@@ -738,7 +1271,91 @@ export async function driveSidebarAreaReorder(spec, run, aux, sleep = (ms) => ne
                 "only run through the full client",
         };
     }
-    const ctx = { run, state: aux.areaState, sleep };
+    const areaTitlesForRestore = aux.areaState().areas.map((a) => a.title);
+    const ctx = {
+        run,
+        state: aux.areaState,
+        sleep,
+        areaTitles: areaTitlesForRestore,
+    };
+    // The collapse rung's ledger, owned OUT HERE so the restore epilogue covers
+    // every way the ladder can end — including a throw (FGRD2 cleanup shape).
+    const collapsed = [];
+    // The chrome ledger, same shape and for the same reason: a sidebar this drive
+    // revealed is hidden again on EVERY exit path. The user's window chrome is
+    // theirs; a move must not silently leave it changed (SBCOL1 precedent).
+    const chrome = { revealedSidebar: false };
+    try {
+        const result = await runDragLadder(ctx, spec, collapsed, chrome);
+        // the ladder (and any recovery drag inside it) must finish before the
+        // sidebar is folded back — the recovery needs the cleared path too
+        const restoreFailed = await restoreDisclosure(ctx, areaTitlesForRestore, collapsed);
+        const chromeNote = await restoreChrome(ctx, chrome);
+        return withChromeOutcome(withCollapseOutcome(result, collapsed, restoreFailed), chromeNote);
+    }
+    catch (err) {
+        // the sidebar is put back even when the ladder blew up
+        await restoreDisclosure(ctx, areaTitlesForRestore, collapsed);
+        await restoreChrome(ctx, chrome);
+        throw err;
+    }
+}
+/**
+ * NORMALIZATION RUNG (SBRES1): a hidden sidebar is not a dead end.
+ *
+ * Things' View ▸ Show Sidebar is a real, documented command, so the drive uses
+ * it — and then CLOSES THE LOOP, exactly as the determinism doctrine requires:
+ * the reveal only counts once a fresh snapshot resolves. A click that went out
+ * is ledgered whether or not it verified, because the app has already changed.
+ */
+async function revealSidebar(ctx, chrome) {
+    const res = await runCmd(ctx, sidebarVisibilityCommand("show"));
+    let clicked = false;
+    let why = "the View menu did not respond";
+    if (res.ok) {
+        try {
+            const parsed = JSON.parse(res.stdout.trim());
+            clicked = parsed.clicked === true;
+            if (typeof parsed.why === "string" && parsed.why !== "")
+                why = parsed.why;
+        }
+        catch {
+            /* keep the default reason */
+        }
+    }
+    if (!clicked)
+        return { ok: false, why };
+    chrome.revealedSidebar = true;
+    await ctx.sleep(600);
+    const after = await takeSnapshot(ctx);
+    if (after.ok)
+        return { ok: true, snapshot: after.snapshot };
+    return { ok: false, why: describeSnapshotFailure(after) };
+}
+/** Put the window chrome back. Runs on every exit path. */
+async function restoreChrome(ctx, chrome) {
+    if (!chrome.revealedSidebar)
+        return null;
+    const res = await runCmd(ctx, sidebarVisibilityCommand("hide"));
+    let clicked = false;
+    if (res.ok) {
+        try {
+            clicked = JSON.parse(res.stdout.trim()).clicked === true;
+        }
+        catch {
+            clicked = false;
+        }
+    }
+    return clicked
+        ? "the sidebar was shown to run the move and hidden again afterwards"
+        : "the sidebar was shown to run the move and could NOT be hidden again — hide it with " +
+            "View ▸ Hide Sidebar (⌘/)";
+}
+function withChromeOutcome(result, note) {
+    return note === null ? result : { ...result, detail: `${result.detail} (${note})` };
+}
+/** The ladder proper. Its caller owns the collapse ledger and the restore. */
+async function runDragLadder(ctx, spec, collapsed, chrome) {
     const pre = ctx.state();
     const preTies = hasRankTies(pre);
     const areaTitles = pre.areas.map((a) => a.title);
@@ -822,10 +1439,27 @@ export async function driveSidebarAreaReorder(spec, run, aux, sleep = (ms) => ne
     let hopCap = Math.min(MAX_HOPS_CEILING, pre.areas.length + 2);
     for (let attempt = 0; attempt <= MAX_HOPS_CEILING; attempt++) {
         // every hop depends on the layout the previous hop produced
-        const snap = await takeSnapshot(ctx);
-        if (snap === null) {
-            return refuseOrRecover(ctx, pre, spec, hops, "the sidebar did not resolve (is the window open and the sidebar visible?)");
+        let snapOutcome = await takeSnapshot(ctx);
+        // A HIDDEN sidebar is normalized, not refused: Things' own View menu shows
+        // it, the epilogue hides it again, and the refusal below is reached only
+        // when that fails. Everything else is reported as the cause it actually is.
+        if (!snapOutcome.ok && snapOutcome.why === "sidebar-hidden") {
+            const revealed = await revealSidebar(ctx, chrome);
+            snapOutcome = revealed.ok
+                ? { ok: true, snapshot: revealed.snapshot }
+                : {
+                    ok: false,
+                    why: "sidebar-hidden",
+                    ...{ stderr: revealed.why },
+                };
         }
+        if (!snapOutcome.ok) {
+            const why = snapOutcome.why === "sidebar-hidden" && snapOutcome.stderr !== undefined
+                ? `the sidebar is hidden in this Things window and showing it did not work (${snapOutcome.stderr})`
+                : describeSnapshotFailure(snapOutcome);
+            return refuseOrRecover(ctx, pre, spec, hops, why);
+        }
+        const snap = snapOutcome.snapshot;
         const viewport = snap.viewport;
         {
             // ceil(areas / visible-slots) + 2, from the frame-derived slot pitch.
@@ -847,10 +1481,35 @@ export async function driveSidebarAreaReorder(spec, run, aux, sleep = (ms) => ne
         }
         resolveRetried = false;
         const grab = grabPoint(finalPlan.source);
+        const spanNeeded = Math.abs(grab.y - finalPlan.dropY);
+        // PRE-FLIGHT (#658, AXDRAG5): every shipped rung needs the grab point and
+        // the drop boundary inside the viewport AT ONCE, so a sidebar SECTION taller
+        // than one drag's usable span can never be crossed — not by rung 1, and not
+        // one hop at a time. Detect it from the geometry BEFORE any gesture and
+        // refuse honestly; the old behavior was to hop until no anchor fit and then
+        // blame the window size after minutes of AX round-trips.
+        if (spanNeeded >= usableDragSpan(viewport)) {
+            const orderedNow = areaRowsInOrder(snap.rows, areaTitles);
+            const walls = blockingSectionsInSpan(orderedNow, snap.rows, grab.y, finalPlan.dropY, spec.targetTitle, viewport);
+            if (walls.length > 0) {
+                // COLLAPSE RUNG (SBCOL1). A wall is not a dead end: fold the blocking
+                // section(s) away with their disclosure chevrons — each collapse
+                // verified by a re-census — and re-plan against the shorter sidebar.
+                // The epilogue puts every one of them back.
+                // the sidebar must actually fold before the ladder re-plans against it
+                const folded = await collapseWalls(ctx, walls, areaTitles, collapsed);
+                if (folded.ok)
+                    continue; // re-plan from a fresh snapshot
+                const wall = walls[0];
+                const detail = blockedSectionDetail(wall, viewport, describeAnchor(finalPlan.anchor), folded.why);
+                return hops === 0
+                    ? { ok: false, detail }
+                    : abortPartial(ctx, spec, hops, `${detail} — so the move stopped part-way`);
+            }
+        }
         // Rung 1: both the grab point and the drop boundary visible (or scrollable
         // into simultaneous view) → one certified drag.
-        const spanNeeded = Math.abs(grab.y - finalPlan.dropY);
-        if (spanNeeded < viewport.h - 4 * BAND_PAD) {
+        if (spanNeeded < usableDragSpan(viewport)) {
             let ready = snap;
             if (!inBand(grab.y, viewport) || !inBand(finalPlan.dropY, viewport)) {
                 // pre-scroll must land before the drag
@@ -948,7 +1607,7 @@ export async function driveSidebarAreaReorder(spec, run, aux, sleep = (ms) => ne
                         continue;
                     const maxTicks = Math.min(400, Math.max(20, Math.ceil(travel / 15)));
                     // the held gesture must complete before its DB assert
-                    const res = await runCmd(ctx, heldScrollDragCommand(g.x, g.y, anchor, maxTicks));
+                    const res = await runCmd(ctx, heldScrollDragCommand(g.x, g.y, anchor, maxTicks, ctx.areaTitles));
                     const parsed = parseHeldDragResult(res);
                     if (parsed.dropped) {
                         // the final assert gates success
@@ -1039,8 +1698,27 @@ export async function driveSidebarAreaReorder(spec, run, aux, sleep = (ms) => ne
             }
         }
         if (hopAnchor === null) {
-            return refuseOrRecover(ctx, pre, spec, hops, "no drop slot toward the destination fits the visible sidebar — the viewport is too " +
-                "small to make progress");
+            // Name the real cause (#658): normally the next area toward the
+            // destination begins a section taller than the visible list, which no
+            // window size fixes. Only fall back to the generic sentence when the
+            // geometry does NOT show such a section.
+            const planNow = planDrop(parked, spec, areaTitles, spec.placement, ranks);
+            const wallsHere = "error" in planNow
+                ? []
+                : blockingSectionsInSpan(ordered, parked.rows, grabPoint(planNow.source).y, planNow.dropY, spec.targetTitle, parked.viewport);
+            if (wallsHere.length > 0) {
+                // The same collapse rung, reached from the hop side: the next area
+                // toward the destination begins a section taller than the visible list.
+                // the fold must land before the ladder re-plans
+                const folded = await collapseWalls(ctx, wallsHere, areaTitles, collapsed);
+                if (folded.ok) {
+                    hops -= 1; // the fold is not a hop; the re-plan gets the slot back
+                    continue;
+                }
+                return refuseOrRecover(ctx, pre, spec, hops, blockedSectionDetail(wallsHere[0], parked.viewport, describeAnchor("error" in planNow ? "the requested position" : planNow.anchor), folded.why));
+            }
+            return refuseOrRecover(ctx, pre, spec, hops, "no drop slot toward the destination fits the visible sidebar — the nearest area row " +
+                "toward it sits more than one drag away, so the gesture has nowhere to land");
         }
         const anchorUuid = hopAnchor.uuid;
         // the hop gesture must land before its DB assert
@@ -1097,6 +1775,20 @@ export async function driveSidebarAreaReorder(spec, run, aux, sleep = (ms) => ne
     }
     return abortPartial(ctx, spec, hops, "exceeded the hop budget without converging");
 }
+/** The destination, as the refusal copy names it. */
+function describeAnchor(anchor) {
+    return anchor === "the end of the sidebar list" || anchor === "the requested position"
+        ? anchor
+        : `"${anchor}"`;
+}
+/** Where the area sits RIGHT NOW, for a report that never has to guess. */
+function describePosition(state, uuid) {
+    const pos = positionOf(state, uuid);
+    if (pos < 0)
+        return "the area no longer resolves in the database";
+    return (`the area now sits at sidebar position ${pos + 1} of ${state.areas.length}` +
+        (pos > 0 ? `, below "${state.areas[pos - 1]?.title ?? "?"}"` : ", at the top"));
+}
 /**
  * Abort mid-ladder WITHOUT recovery (design amendment: a partially-moved area
  * is benign) — send Escape as a safety valve and report exactly where the
@@ -1108,12 +1800,7 @@ async function abortPartial(ctx, spec, hops, why) {
         label: "abort (Escape)",
         script: `tell application "System Events" to key code 53`,
     });
-    const state = ctx.state();
-    const pos = positionOf(state, spec.targetUuid);
-    const where = pos < 0
-        ? "the area no longer resolves in the database"
-        : `the area now sits at sidebar position ${pos + 1} of ${state.areas.length}` +
-            (pos > 0 ? `, below "${state.areas[pos - 1]?.title ?? "?"}"` : ", at the top");
+    const where = describePosition(ctx.state(), spec.targetUuid);
     return {
         ok: false,
         detail: `${why} after ${hops} hop(s); ${where}. Its to-dos and projects are untouched — ` +
@@ -1128,12 +1815,27 @@ async function abortPartial(ctx, spec, hops, why) {
 async function refuseOrRecover(ctx, pre, spec, hops, why) {
     const now = ctx.state();
     const orderChanged = now.areas.map((a) => a.uuid).join(",") !== pre.areas.map((a) => a.uuid).join(",");
-    if (!orderChanged || hasRankTies(pre)) {
+    if (!orderChanged) {
         return {
             ok: false,
             detail: `${why}. No sidebar change was left behind${hops > 0 ? ` after ${hops} hop(s)` : ""}.`,
         };
     }
+    // The order DID change. Tied pre-op ranks (every never-dragged area sits at
+    // `index` 0, so ties are the norm on real data) make the restore anchor
+    // ambiguous, so no recovery drag is attempted — but #658: the change must be
+    // REPORTED, never claimed away. The old code short-circuited on the tie and
+    // emitted "No sidebar change was left behind" over a move that had landed,
+    // was visible in the sidebar, and was syncing to the user's other devices.
+    if (hasRankTies(pre)) {
+        return {
+            ok: false,
+            detail: `${why}. The sidebar order DID change${hops > 0 ? ` over ${hops} hop(s)` : ""} and was ` +
+                `left in place: ${describePosition(now, spec.targetUuid)}. Several areas share the same ` +
+                "stored rank, so putting it back automatically could move the wrong one — re-run the " +
+                "move, or drag it back in the app.",
+        };
+    }
     // Which area was actually displaced? Normally the target; but a DUPLICATE-title
     // positional grab may have moved a SAME-TITLED SIBLING instead (the target's
     // own slot is unchanged). Restore whichever uuid drifted farthest from its