things-api 0.16.0 → 0.18.0

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

@@ -1,4 +1,4 @@
-import type { ThingsApiConfig } from "../../config.ts";
+import { type ThingsApiConfig } from "../../config.ts";
 import { type UiDriveAux } from "./ui-drag.ts";
 import type { UiPrimitive, UiStep, WriteVector } from "./types.ts";
 /**
@@ -53,6 +53,24 @@ export declare function axPressScript(path: string): string;
  * reveal/activate preamble puts Things there. One stable command shape.
  */
 export declare function axSetValueScript(path: string, value: string, attempts?: number): string;
+/**
+ * ensure-checkbox: converge a dialog checkbox to a target state through a
+ * DETERMINISTIC CLOSED LOOP (RRD1, determinism doctrine) — never a blind toggle.
+ * It reads the checkbox's `AXValue` (0 = unchecked, 1 = checked), presses it ONLY
+ * when the observed value differs from `target`, then RE-READS to confirm the new
+ * value equals `target`. A press that did not register (or a value that has not
+ * settled) is retried a bounded number of times; if it never converges the script
+ * FAILS CLOSED (an `error`, i.e. a transport failure the pipeline re-verifies).
+ *
+ * This is what makes the "Add deadlines" / "Add reminders" checkboxes safe on a
+ * PRE-POPULATED reschedule dialog: the dialog opens with the item's CURRENT
+ * deadline/reminder state already ticked, so the old unconditional `click`
+ * FLIPPED an already-correct box the wrong way — the live #493-adjacent bug where
+ * a blind "Add deadlines" press UNCHECKED an already-deadlined rule and hid the
+ * "start N days earlier" field, collapsing the drive. Reading before pressing
+ * makes an already-correct box a no-op. One stable command shape per primitive.
+ */
+export declare function axEnsureCheckboxScript(path: string, target: boolean, attempts?: number): string;
 /**
  * select-popup: choose an item in a pop-up button by NAME. Setting `value` on a
  * Things pop-up button is a silent no-op (UIC1 / UI2-i) — the control must be
@@ -78,6 +96,74 @@ export declare function axSelectPopupScript(path: string, value: string): string
  * plural-safe. One stable command shape per primitive.
  */
 export declare function axSelectPopupCandidatesScript(path: string, values: string[]): string;
+/**
+ * probe-dialog-shape: MEASURE which Repeat dialog is open (RDLG2) — the whole
+ * version fork, decided by STRUCTURE rather than by the app version, so the
+ * recipe self-selects on any host and a future redesign refuses instead of
+ * silently pressing the wrong control:
+ *
+ *  - `next-popup` (Things 3.23+) — the first occurrence is an `AXPopUpButton`
+ *    listing the rule's own upcoming occurrences. It sits between Ends and every
+ *    per-frequency control, so weekday / monthly / yearly pop-ups are one index
+ *    further along.
+ *  - `legacy` (Things ≤ 3.22) — the first occurrence is a free-form
+ *    `AXDateTimeArea`, and the per-frequency controls follow Ends directly.
+ *
+ * The discriminator is the CONTROL CLASS on the `Next:` row, not the presence of
+ * the label: RDLG2d measured Things 3.22.14 and found it carries the same
+ * `Next:` static text (and the same occurrence-preview line) as 3.23 — only the
+ * control beside it changed. So the probe reads the label's row position and asks
+ * what kind of control shares that row, which also keeps it independent of the
+ * dialog's Ends state (an `Ends: on date` bound adds a SECOND date area, on a
+ * different row, in both shapes). Each branch is a POSITIVE match, so an
+ * unrecognized third dialog returns "unknown" and the driver refuses. Labels are
+ * pinned English, exactly like every other selector here.
+ */
+export declare function axProbeDialogShapeScript(groupPath: string, rowTolerance?: number): string;
+/**
+ * select-next-occurrence: set the first occurrence through the Things 3.23
+ * `Next:` POP-UP (RDLG2). 3.23 replaced the free-form first-occurrence date area
+ * with a bounded MENU — `Today`, then the rule's own upcoming occurrences, then a
+ * `More…` item whose submenu carries the next hundred, cascading further the same
+ * way. Two consequences this script encodes:
+ *
+ *  - a requested date is reachable ONLY if the rule itself produces it (or it is
+ *    today): the menu offers nothing else, so an OFF-RULE first occurrence — free
+ *    to set on ≤3.22 — is UNEXPRESSIBLE in this dialog and must fail closed with
+ *    a named reason rather than land some neighbouring date;
+ *  - item titles are localized (`Sun, Jul 12, 2026`), so the match is made by
+ *    PARSING each title to a date (with a leading-weekday retry) and comparing
+ *    calendar components — never by rebuilding the app's display string.
+ *
+ * The cascade is walked to a bounded depth; the click is verified by reading the
+ * pop-up's value back and requiring it to equal the clicked item's own title
+ * (the fail-closed read-back the ANCH2/YANCH1 date drives established).
+ */
+export declare function axSelectNextOccurrenceScript(popupPath: string, isoDate: string, maxLevels?: number): string;
+/**
+ * converge-weekdays: drive the weekly dialog's weekday ROWS onto an exact target
+ * set through a deterministic closed loop (RDLG2 — the RRD1 fix).
+ *
+ * The shipped drive set the FIRST weekday row and then pressed "+" and re-drove
+ * THE SAME row index per extra weekday, which on a PRE-POPULATED reschedule
+ * dialog left the rule's existing weekdays untouched: `{mon,wed}` retargeted to
+ * `{tue,thu,sat}` committed `{mon,tue,thu,sat}` (VMQ1 cell 2Tb — caught only by
+ * the write pipeline's verify). It also had no way to SHRINK a set.
+ *
+ * The loop instead: (1) read the live row count; (2) press the row-add button —
+ * the smaller-x button of a weekday row, resolved from live geometry rather than
+ * a pinned index, because the row buttons enumerate in an unstable order — until
+ * there are at least as many rows as target weekdays; (3) assign EVERY row from
+ * the target set, cycling, so a surplus row duplicates a target weekday instead
+ * of keeping a stale one (the app stores the weekdays as a SET, so duplicates
+ * collapse on commit — this is what makes shrinking possible without the
+ * remove button); (4) read every row back and require the set to match exactly.
+ * Anything else errors — the pipeline re-verifies against the DB regardless.
+ *
+ * `base` is the 1-based group pop-up index of the first weekday row (2 on the
+ * legacy dialog, 3 once the 3.23 `Next:` pop-up sits in front of them).
+ */
+export declare function axConvergeWeekdaysScript(groupPath: string, base: number, titles: string[]): string;
 /**
  * select-row: select a PROJECT row by title, purely via AX (UIC4-a). Walks the
  * content table's rows, issues the row `select` action on each (which REPLACES
@@ -112,12 +198,41 @@ export declare function axSelectRowScript(tablePath: string, title: string): str
  * One stable command shape per primitive.
  */
 export declare function axSelectHeadingRowScript(tablePath: string, ordinal: number): string;
+/**
+ * assert-eligible: after a `things:///show?id=` reveal, VERIFY the target to-do
+ * is genuinely the sole selection AND that the menu item that acts on it is
+ * enabled — before the menu is pressed (ADR1, issue #480). The reveal is assumed
+ * to select the row, but on some surfaces it can navigate without selecting; an
+ * AXPress on the resulting DISABLED `Items ▸ Repeat…` is a silent no-op, so the
+ * dialog never opens and the drive dies far downstream at the dialog-wait timeout
+ * with no hint of the real cause. Reading `Things3 → id of selected to dos` is
+ * uuid-precise (never a fuzzy title match), so a match GUARANTEES the intended row
+ * is selected. Returns "OK" only when exactly the target is selected and the menu
+ * item is enabled; otherwise a diagnostic (`NOTSEL…`/`WRONGSEL…`/`DISABLED…`)
+ * naming expected vs observed. Pure System Events + Things scripting, background-
+ * capable. One stable command shape per primitive.
+ */
+export declare function axAssertEligibleScript(targetUuid: string, menuItemPath: string): string;
 /** activate: foreground Things (the fallback preamble step). */
 export declare function axActivateScript(): string;
 /** key: a space-separated keystroke spec (e.g. "down down return"). */
 export declare function axKeyScript(keys: string): string;
 /** The abort keystroke sent to dismiss a half-open sheet/popover on failure. */
 export declare function axAbortScript(): string;
+/**
+ * The PROVEN app-level clearance / relocation maneuver (SESSGATE, #480, live-host
+ * recovery): close the front Things window — which takes an attached modal sheet
+ * with it — then reopen and activate. Runs entirely through Things' own
+ * AppleScript dictionary, so it works WITHOUT the Accessibility tree (the exact
+ * property needed when the session is AX-blind). Two uses:
+ *   - CLEANUP: clear a stuck modal sheet a failed drive left open (unblocks the
+ *     app-wide AppleScript-mutation freeze that sheet imposes);
+ *   - RELOCATION: pull a window that was on another Space back to the current one
+ *     so its dialog can open AX-reachably (the wrong-Space recovery branch).
+ * `reopen` restores the default window on the CURRENT Space; `activate` foregrounds
+ * it. Returns "OK".
+ */
+export declare function axCloseReopenActivateScript(): string;
 /**
  * sheet-open probe: is a modal SHEET attached to the Things standard window, OR
  * a detached repeat-editor / popover window (an `AXUnknown` that is not the
@@ -147,19 +262,46 @@ export declare function axFrameScript(path: string): string;
  */
 export declare function jxaClickScript(x: number, y: number): string;
 /**
- * set-datetime: set the Repeat dialog's `AXDateTimeArea` (reminder time / "ends
- * on date" bound) via the ObjC AX bridge. Things' date/time control holds an
- * NSDate, and System Events cannot write it (`set value … to <date>` → -10000,
- * UIC6), so — like the mouse-synthesis primitive — this runs in JXA and calls
- * `AXUIElementSetAttributeValue(…, AXValue, <NSDate>)` directly. The control is
- * found by ROLE within Things' front dialog (there is exactly one during a
- * reminder/end-date step; the matrix never sets both at once), polled briefly
- * so it is caught right after the checkbox/pop-up that reveals it, and the
- * script THROWS when absent so the driver fails closed. `spec` is
- * `time:HH:mm` (keep the control's date, overwrite the time-of-day) or
- * `date:YYYY-MM-DD` (overwrite the date at midnight). One stable JXA shape.
- */
-export declare function axSetDateTimeScript(spec: string): string;
+ * set-datetime: set ONE of the Repeat dialog's `AXDateTimeArea` controls via the
+ * ObjC AX bridge. Things' date/time controls hold an NSDate, and System Events
+ * cannot write them (`set value … to <date>` → -10000, UIC6), so — like the
+ * mouse-synthesis primitive — this runs in JXA and calls
+ * `AXUIElementSetAttributeValue(…, AXValue, <NSDate>)` directly.
+ *
+ * A fixed rule can expose up to THREE date areas at once — "Next:" (first
+ * occurrence), "Ends: on date", and the reminder time (ANCH2 census). Targeting
+ * "the first AXDateTimeArea by role" is therefore AMBIGUOUS — that ambiguity
+ * collapsed the series when `--ends-on` added a second area (oddities §8v, now
+ * retracted) and made the reminder look undrivable (UIC6-g, now retracted). This
+ * driver selects DETERMINISTICALLY by `target` (ANCH2, docs/lab/anch2-next-field.md):
+ *   - `reminder` — the only area carrying a time-of-day (the date pickers sit at
+ *     midnight); falls back to the bottom-most area if none carry a time.
+ *   - `next` — the TOP (smallest-y) midnight date picker.
+ *   - `ends` — the BOTTOM (largest-y) midnight date picker (present only once
+ *     "Ends: on date" is selected).
+ * The areas are polled briefly (revealed a beat after the checkbox/pop-up), and
+ * the script THROWS a NAMED, structured error when the addressed control is
+ * absent — reporting which target was sought and the FULL date-area inventory of
+ * the current dialog state (count + per-area y / time-of-day) — so a dialog shape
+ * that does not present the target (e.g. the deadline-mode variant, YANCH1 #493)
+ * fails closed with an actionable message, never an uncaught `-[__NSArray0
+ * objectAtIndex:]` (-2700) from indexing an empty collection. It then READS THE
+ * CONTROL BACK after the write and throws if the committed value differs from the
+ * request: a control that silently rejects the write (the macOS error beep the
+ * user hears) must fail the step loudly, never leave a garbled/default value to be
+ * verified as ok (YANCH1; UIC6-g refuse-rather-than-commit precedent). `spec` is
+ * `time:HH:mm` (keep the date, set the time-of-day) or `date:YYYY-MM-DD` (set the
+ * calendar date at midnight). One stable JXA shape.
+ */
+export declare function axSetDateTimeScript(spec: string, target: "next" | "ends" | "reminder"): string;
+/**
+ * The converge-weekdays step encodes both of its inputs in `value` as
+ * `"<base>|<Weekday>,<Weekday>…"`: the base is the group pop-up index of the
+ * FIRST weekday row, which the dialog SHAPE decides (2 legacy / 3 next-popup),
+ * so it rides the same shape-selected `value` the driver merges in.
+ */
+export declare function weekdayBaseOf(value: string): number;
+export declare function weekdayTitlesOf(value: string): string[];
 /** Parse a resolve-frame "x y w h" line into the frame's center point. */
 export declare function parseFrameCenter(stdout: string): {
     x: number;