things-api 0.20.0 → 0.20.2

package/dist/write/vectors/ui-drag.d.ts

@@ -61,15 +61,30 @@ export interface SidebarSnapshot {
     scroll: number | null;
     rows: SidebarRowInfo[];
 }
-/** Snapshot: sidebar rows (text + frames), viewport rect, scroll fraction. */
-export declare function jxaSidebarSnapshotScript(): string;
+/**
+ * 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 declare function jxaSidebarSnapshotScript(areaTitles: readonly string[]): string;
+/**
+ * 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 declare function jxaSidebarVisibilityScript(want: "show" | "hide"): string;
 /**
  * Scroll: move the pointer over the sidebar center (wheel events target the
  * surface under the cursor), then post `clicks` line-unit wheel events.
  * Positive clicks move the CONTENT down (earlier rows return, row y grows);
  * negative clicks reveal lower rows (row y shrinks) — AXDRAG1-b.
  */
-export declare function jxaSidebarScrollScript(clicks: number): string;
+export declare function jxaSidebarScrollScript(clicks: number, areaTitles: readonly string[]): string;
 /**
  * Drag: the NATIVE1 gesture verbatim — move, down, 3px wiggle to open the drag
  * session, ~25 interpolated drag events, a settle so the drop indicator locks,
@@ -88,7 +103,28 @@ export declare function jxaSidebarDragScript(sx: number, sy: number, tx: number,
  * Escape-aborts (AXDRAG1-d: byte-identical index vector) and reports it.
  */
 export declare function jxaSidebarHeldScrollDragScript(sx: number, sy: number, anchorTitle: string | null, // null = drop below the last row (to-last)
-maxTicks: number): string;
+maxTicks: number, areaTitles: readonly string[]): string;
+/**
+ * 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 declare function jxaSidebarChevronClickScript(title: string, ordinal: number, areaTitles: readonly string[]): string;
 /** Median height of the table's spacer rows (rows with no static text). */
 export declare function medianSpacerHeight(rows: SidebarRowInfo[]): number | null;
 /**
@@ -114,7 +150,32 @@ export declare function boundaryAboveRow(allRows: SidebarRowInfo[], ref: Sidebar
  * scrollable band even when the list is pinned to the bottom.
  */
 export declare function boundaryBelowLast(allRows: SidebarRowInfo[]): number | null;
-export declare function parseSidebarSnapshot(stdout: string): SidebarSnapshot | null;
+/**
+ * Why a snapshot did not come back. These were ONE sentence until SBRES1 — "the
+ * sidebar did not resolve (is the window open and the sidebar visible?)" — which
+ * is how a 30-second timeout, a locator that never matched, and a sidebar the
+ * user had genuinely hidden all reached the field wearing the same words, none
+ * of them true for two of the three cases (issues #665, #651).
+ */
+export type SnapshotFailure = "timeout" | "dispatch-failed" | "unparsable" | "no-window" | "no-list-candidates" | "no-title-match" | "ambiguous-sidebar" | "sidebar-hidden" | "no-viewport" | "no-rows";
+export interface SnapshotRefusal {
+    ok: false;
+    why: SnapshotFailure;
+    /** What the locator looked at, when it has something to name. */
+    searched?: {
+        frame: SidebarRect | null;
+        rows: number;
+    }[];
+    /** How many area titles the locator was hunting for. */
+    titles?: number;
+    /** The dispatcher's own words, for `dispatch-failed`. */
+    stderr?: string;
+}
+export type SnapshotOutcome = {
+    ok: true;
+    snapshot: SidebarSnapshot;
+} | SnapshotRefusal;
+export declare function parseSidebarSnapshot(stdout: string): SnapshotOutcome;
 /**
  * Does a row's static-text carry this exact title as a segment? Sidebar row
  * text concatenates descendant static texts with "|" (AXDRAG1: e.g.
@@ -182,6 +243,74 @@ export declare function staticBoundaryY(orderedAreaRows: {
  */
 export declare function correctedDropY(staticY: number, sourceCenterY: number, span: number): number;
 export declare function inBand(y: number, viewport: SidebarRect, pad?: number): boolean;
+/**
+ * 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 declare function usableDragSpan(viewport: SidebarRect): number;
+/**
+ * A sidebar SECTION is an area row plus every row Things renders under it (its
+ * projects, and its "Later Projects" row). `bottom` is the next area row's top —
+ * the last section runs to the bottom of the table.
+ */
+export interface SidebarSectionSpan {
+    title: string;
+    /** Section height in points (area row top → next area row top). */
+    height: number;
+    /** How many table rows the section contains (its own row included). */
+    rows: number;
+    /**
+     * Which same-titled sidebar row this section belongs to, in visual order
+     * (AXDRAG3); -1 when the title is unique. The collapse rung needs it to
+     * actuate the right chevron when two areas share a name.
+     */
+    ordinal: number;
+}
+/**
+ * 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 declare function sectionsInSpan(orderedAreaRows: {
+    title: string;
+    row: SidebarRowInfo;
+}[], allRows: SidebarRowInfo[], fromY: number, toY: number, sourceTitle: string): SidebarSectionSpan[];
+/** The tallest section in the travel span, or null when every one of them fits. */
+export declare function tallestSectionInSpan(orderedAreaRows: {
+    title: string;
+    row: SidebarRowInfo;
+}[], allRows: SidebarRowInfo[], fromY: number, toY: number, sourceTitle: string): SidebarSectionSpan | null;
+/**
+ * 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 declare function blockingSectionsInSpan(orderedAreaRows: {
+    title: string;
+    row: SidebarRowInfo;
+}[], allRows: SidebarRowInfo[], fromY: number, toY: number, sourceTitle: string, viewport: SidebarRect): SidebarSectionSpan[];
+/**
+ * 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 declare function sectionBlocks(section: SidebarSectionSpan, viewport: SidebarRect): boolean;
+/**
+ * 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 declare function blockedSectionDetail(section: SidebarSectionSpan, viewport: SidebarRect, destination: string, whyCollapseFailed?: string): string;
 /**
  * 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
@@ -199,7 +328,26 @@ export interface DragDriveResult {
     detail: string;
     /** A gesture may have landed before the failure — recovery state, honestly. */
     recovered?: boolean;
+    /**
+     * The collapse rung folded these sidebar areas away to clear the path, and put
+     * every one of them back. Present only when the rung actually ran, so an
+     * ordinary move carries nothing (SBCOL1).
+     */
+    collapsed?: string[];
+    /**
+     * A collapsed area the driver could NOT re-expand. The disclosure state lives
+     * in the app's own preferences and SURVIVES a relaunch (SBCOL1 §3), so a
+     * failed restore is a durable change to the user's sidebar and is never
+     * silent — even on an otherwise successful move.
+     */
+    restoreFailed?: string[];
 }
+/**
+ * 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 declare function describeSnapshotFailure(refusal: SnapshotRefusal): string;
 /**
  * The rung-2 anchor: every placement reduces to "drop above this area row"
  * (title) or "drop below the last row" (null). `undefined` = unresolvable.