things-api 0.19.0 → 0.19.2

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

@@ -60,7 +60,72 @@ export interface UiRecipe {
      */
     needsWindowReachability?: boolean;
 }
-export type UiPrimitive = "reveal" | "activate" | "resolve" | "press" | "set-value" | "select-popup" | "wait" | "key"
+export type UiPrimitive = "reveal" | "activate" | "resolve" | "press" | "set-value"
+/**
+ * Set ONE of the Repeat dialog's two numeric fields — the cadence INTERVAL
+ * ("Every [n] days") or the ENDS-AFTER COUNT ("Ends: after [n] times") —
+ * addressed by the ROW it sits on rather than by its index among the group's
+ * text fields (HXPC1). Both used to be spelled `text field 1 of group 1`,
+ * which is only correct in the order the create path happens to drive them:
+ * the interval is the group's sole text field until an "Ends: after" bound is
+ * selected, and the count then takes index 1 with the interval displaced to 2
+ * (measured, Things 3.23 — docs/lab/hxpc1-picker-assert.md §A). A RESCHEDULE
+ * opens the dialog PRE-POPULATED, so a rule that already ends after N
+ * presents both fields from the first step and the index spelling wrote the
+ * requested interval into the count field. The row anchor is the group's
+ * `Ends:` static text: the count is the field sharing its row, the interval
+ * is the field that does not (and after-completion rules, which offer no ends
+ * bound at all, have only the interval). {@link UiStep.numberTarget} picks
+ * which. Drives with the same focus → select-all → type → Tab → read-back
+ * closed loop as set-value, and fails closed when the row anchor resolves
+ * anything other than exactly one field.
+ */
+ | "set-group-number"
+/**
+ * Set a Repeat-dialog text field addressed by the pinned English LABEL sharing
+ * its row — the same discrimination law as `set-group-number`, for a field that
+ * lives on the dialog SHELL rather than in the cadence group. Its one caller is
+ * the "and start [n] days earlier" offset the "Add deadlines" checkbox reveals,
+ * which shipped as `text field 1` of the shell: a value-bearing field picked by
+ * index out of a tree whose shape depends on that checkbox, and verified only by
+ * re-reading the same index it wrote — the HXPC1 error class exactly. It was
+ * right on Things 3.23 (measured: the shell carries 0 direct text fields with
+ * deadlines off and exactly 1 with them on, CGRD1 §B), but nothing in the address
+ * said so. {@link UiStep.rowLabel} names the anchor (`days earlier`); a missing
+ * label, or anything but exactly one field on its row, fails closed naming the
+ * shell's whole text-field inventory.
+ */
+ | "set-row-field"
+/**
+ * PRE-COMMIT FULL-DIALOG AUDIT — re-read every control this drive set, through
+ * each control's own discriminated address, and refuse to press OK if any of
+ * them does not hold the intended value (CGRD1).
+ *
+ * Every setter in this vocabulary confirms its own write by re-reading the
+ * element it addressed, which proves the keystrokes landed where they were
+ * aimed and nothing more; a wrong ADDRESS is invisible to it (#589: the interval
+ * drive typed into the ends-count field, then read that field back and found its
+ * own number). This step is the outside view. The plan is derived from the
+ * recipe's own step list ({@link UiStep.audit}), so a control the recipe drives
+ * cannot be left out of the audit by omission, and it compares the dialog's
+ * complete intended state — frequency, cadence unit, interval, ends bound and
+ * count, deadline/reminder checkboxes, start-days-earlier, the weekday set, the
+ * monthly/yearly anchors, the first occurrence and the ends date. A mismatch
+ * names every differing control with both values and aborts the drive
+ * fail-closed BEFORE the commit, through the usual clean-abort path.
+ */
+ | "audit-dialog" | "select-popup" | "wait" | "key"
+/**
+ * Type literal text into whatever control currently holds focus (HXPC1). Used
+ * for the Move… picker's filter field, which the picker focuses for itself the
+ * moment it opens: the field is not addressable as a direct child of the
+ * picker window, and the set-value primitive's select-all + Tab commit is
+ * wrong for a search field anyway (Tab has no next key view in a popover). The
+ * keystroke is not the verification — the `click-picker-row` step that follows
+ * resolves the intended destination row by name and fails closed if the filter
+ * did not produce it, so a keystroke that went astray can never be committed.
+ */
+ | "type-text"
 /**
  * Synthesize a MOUSE click at an AX-resolved element's frame center (the
  * NATIVE1 JXA ObjC-bridge / HID-tap primitive). Used ONLY for Things' custom
@@ -71,6 +136,28 @@ export type UiPrimitive = "reveal" | "activate" | "resolve" | "press" | "set-val
  * foreground surface, NATIVE1-e), so a recipe using it must activate first.
  */
  | "click-element"
+/**
+ * Commit the Move… project picker by CLICKING the row that carries the
+ * destination project's exact title — never by pressing Return on whatever the
+ * filter happened to highlight (HXPC1). The picker exposes no selection,
+ * focus, or highlight attribute on any row, so there is nothing to read back
+ * from a keyboard commit; what it does expose is one `AXUnknown` per row whose
+ * `AXDescription` IS the project title, plus — whenever text has been typed —
+ * a `New Project "<typed text>"` row that CREATES a project when committed.
+ * The blind Return committed that row whenever the destination was absent from
+ * the picker, which is reachable from an ordinary database-resolved
+ * destination: a COMPLETED or CANCELED project is offered nowhere in the
+ * picker, so the drive silently created a second project of the same name and
+ * moved the heading into it (measured on Things 3.23,
+ * docs/lab/hxpc1-picker-assert.md §B4). Addressing the row by exact title
+ * cannot match the New-Project row (its description is the quoted form) and
+ * fails closed — naming every row the picker DID offer — when the intended one
+ * is absent, ambiguous, or scrolled out of its own scroll area (the CNCAC1
+ * off-screen-frame hazard). `path` is the picker WINDOW — the resolver reads its
+ * `AXIdentifier` to confirm identity before it looks at any row; `value` is the
+ * destination title.
+ */
+ | "click-picker-row"
 /**
  * Synthesize a MOUSE DRAG that reorders a sidebar AREA row (the AXDRAG1
  * primitive). The driver resolves the source row and the destination slot
@@ -80,6 +167,22 @@ export type UiPrimitive = "reveal" | "activate" | "resolve" | "press" | "set-val
  * bound like click-element.
  */
  | "drag-reorder"
+/**
+ * Reorder a project's HEADINGS with the arrow chords (CHORDMH1). Things has no
+ * menu item, context-menu item or AX action for heading order — the affordance
+ * is four bare keybindings on a selected heading row: ⌘↑/⌘↓ move it one slot,
+ * ⌘⌥↑/⌘⌥↓ move it to the top/bottom (HEADORD1). The driver selects the row
+ * with the pure-AX positional primitive and posts one chord at a time straight
+ * to the Things process, reading the heading order back out of the DATABASE
+ * after each — the only oracle a bare keybinding offers. Every chord is
+ * computed from that read (never fired speculatively: a chord the app declines
+ * costs the user an alert beep), and every chord must move exactly the intended
+ * heading exactly one slot with no other row's `index` and no child row
+ * touched, or the drive stops. Background-capable with no focus steal — the
+ * whole gesture runs with Things behind the user's frontmost app. See
+ * src/write/vectors/ui-chord.ts.
+ */
+ | "chord-reorder"
 /**
  * Select a PROJECT as a content-table ROW by matching its title, purely via
  * AX (UIC4-a): the content table's `AXSelectedRows` is settable, so the
@@ -174,6 +277,18 @@ export type UiPrimitive = "reveal" | "activate" | "resolve" | "press" | "set-val
  * the ≤3.22 `set-datetime next` drive wrote.
  */
  | "select-next-occurrence"
+/**
+ * Let the Things 3.23 `Next:` occurrence pop-up ABSORB the rule change the
+ * preceding steps made, before any further input reaches the dialog
+ * (NEXTPOP1). The dialog recomputes that control — its displayed first
+ * occurrence AND the menu of occurrences behind it — ASYNCHRONOUSLY, ~0.4s
+ * after a calendar-anchor change, and an input that lands inside that window
+ * CANCELS the recompute for good: the pop-up goes on describing the PREVIOUS
+ * rule indefinitely. The step polls the control until it moves (the common
+ * case, ~0.4s) or a bounded budget expires (nothing to absorb), so the next
+ * input never races it.
+ */
+ | "settle-occurrences"
 /**
  * Converge the weekly dialog's weekday ROWS onto an exact target set through a
  * deterministic closed loop (RDLG2, the RRD1 fix): read the live row count,
@@ -224,6 +339,42 @@ export interface UiStep {
     keys?: string;
     /** wait: how long to poll for the element before aborting. */
     timeoutMs?: number;
+    /**
+     * set-group-number only: WHICH of the Repeat dialog's two numeric fields to
+     * drive. `interval` = the cadence field ("Every [n] …"); `ends-count` = the
+     * "Ends: after [n] times" field. Each is resolved by the ROW it sits on, so
+     * the drive no longer depends on the order the dialog's controls were touched
+     * or on whether a reschedule opened it pre-populated. Required for every
+     * set-group-number step.
+     */
+    numberTarget?: "interval" | "ends-count";
+    /**
+     * set-row-field only: the pinned English static text whose ROW the target field
+     * shares (`days earlier` for the start-offset field). Locale fail-closed, like
+     * every other title-pinned selector here.
+     */
+    rowLabel?: string;
+    /**
+     * audit-dialog only: the complete set of controls to re-read before the commit,
+     * with the value the drive intended for each. Built by the recipe from its own
+     * emitted steps, so the audit and the drive can never disagree about which
+     * controls were touched.
+     */
+    audit?: DialogAuditPlan;
+    /**
+     * click-element only: resolve the click target by walking the addressed
+     * content TABLE's rows → cells → cell children for the element whose
+     * `AXDescription` equals this, instead of resolving `path` itself. The heading
+     * row's `…` button is the one control that needs it: it carries its heading's
+     * title in `AXDescription` ("More. <title>"), but it sits three levels below
+     * the table, and a `whose` clause on `UI elements of <table>` searches only
+     * the table's DIRECT children — the rows — so the shipped one-level spelling
+     * matched nothing and every ellipsis drive died at its own frame resolution
+     * (measured on Things 3.23, docs/lab/hxpc1-picker-assert.md §B0 — the same
+     * frame-resolution miss the timestamp cells recorded against the golden-v2
+     * rig). The walk is an exact match and fails closed naming what it sought.
+     */
+    rowCellDescription?: string;
     /**
      * click-element only: the element expected to appear right AFTER the click
      * (a popover opening, a sheet appearing). The driver polls for it and, on
@@ -253,6 +404,8 @@ export interface UiStep {
     activateFallback?: boolean;
     /** drag-reorder only: the sidebar move the drag driver performs. */
     drag?: import("./ui-drag.ts").SidebarDragSpec;
+    /** chord-reorder only: the heading order the chord driver steps the project into. */
+    chord?: import("./ui-chord.ts").HeadingChordSpec;
     /**
      * set-datetime only: WHICH of the dialog's date areas to drive (ANCH2). The
      * driver selects deterministically — `reminder` = the only time-bearing area;
@@ -287,6 +440,47 @@ export interface UiStep {
         value?: string;
     }>>;
 }
+/**
+ * ONE control of the pre-commit dialog audit, as the RECIPE declares it — before
+ * the driver has resolved which dialog shell is live or which shape the dialog is.
+ * Paths are per-shell candidate lists in the same order as {@link DialogAuditPlan.shells}.
+ */
+export interface DialogAuditControl {
+    /** Human name of the control, as the mismatch report should say it. */
+    label: string;
+    kind: "popup" | "checkbox" | "group-number" | "row-field" | "weekdays" | "occurrence-popup" | "date-area";
+    /** popup / checkbox / occurrence-popup: per-shell candidate paths. */
+    pathCandidates?: string[];
+    /** group-number: which of the cadence group's numeric fields. */
+    numberTarget?: "interval" | "ends-count";
+    /** row-field: the pinned English label sharing the field's row. */
+    rowLabel?: string;
+    /** weekdays: the group pop-up index of the first weekday row. */
+    weekdayBase?: number;
+    /** date-area: which of the dialog's `AXDateTimeArea` controls. */
+    dtTarget?: "next" | "ends" | "reminder";
+    /** date-area: the spec the drive wrote (`date:YYYY-MM-DD` / `time:HH:mm`). */
+    dtSpec?: string;
+    /** The accepted observed values — ANY one satisfies (the singular/plural pair). */
+    expected?: string[];
+    /** How the intended value should READ in the report ("checked", not "1"). */
+    expectedLabel?: string;
+    /** Check this control ONLY under the named dialog shape (the +1-index fork). */
+    onlyShape?: RepeatDialogShape;
+    /** Per-shape overrides, merged once the dialog shape is measured. */
+    shaped?: Partial<Record<RepeatDialogShape, {
+        pathCandidates?: string[];
+        weekdayBase?: number;
+    }>>;
+}
+/** The pre-commit audit an `audit-dialog` step carries. */
+export interface DialogAuditPlan {
+    /** The dialog shells, in the SAME priority order the drive resolves them. */
+    shells: string[];
+    /** The cadence group inside each shell (same order as {@link shells}). */
+    groups: string[];
+    controls: DialogAuditControl[];
+}
 /**
  * The structural SHAPE of the Repeat dialog, MEASURED live (never sniffed from
  * the app version — a version string says nothing about the tree the driver has
@@ -325,6 +519,16 @@ export interface VectorSupport {
     notes?: string;
 }
 export type VectorMatrix = Partial<Record<OperationKind, VectorSupport>>;
+/**
+ * How the ui vector's audited cleanup ladder left an open dialog (issue #620):
+ * `none` — nothing was open; `dismissed` — closed, and a fresh read confirmed
+ * it closed; `cleared-blind` — cleared by the window close+reopen on an
+ * AX-blind session, so it cannot be confirmed; `foreign` — a dialog this drive
+ * did not open was found and deliberately LEFT ALONE; `may-remain` — ours, and
+ * nothing in the ladder would close it (the stranded case, which also holds
+ * Things Cloud sync until someone dismisses it).
+ */
+export type UiClearOutcome = "none" | "dismissed" | "cleared-blind" | "foreign" | "may-remain";
 export interface ExecuteResult {
     exitCode: number | null;
     stdout: string;
@@ -358,8 +562,8 @@ export interface ExecuteResult {
         elapsedMs: number;
         /** The step the drive was about to run (or running) when the budget blew. */
         lastStep: string;
-        /** How the open dialog was cleaned up (SESSGATE clearDialog outcome). */
-        clear: "dismissed" | "cleared-blind" | "may-remain";
+        /** How the open dialog was cleaned up (the audited cleanup ladder's outcome). */
+        clear: UiClearOutcome;
         /** The local trace file reconstructing the timeline, when tracing is on. */
         tracePath?: string | null;
     };
@@ -387,7 +591,7 @@ export interface ExecuteResult {
          */
         cause: "unreachable" | "unresponsive";
         /** How a half-open sheet was cleaned up, when the drive had opened one. */
-        clear?: "dismissed" | "cleared-blind" | "may-remain";
+        clear?: UiClearOutcome;
         /** What the caller does to make a retry work. */
         remediation: string;
     };
@@ -406,6 +610,18 @@ export interface WriteVector {
      * vectors and the simulator, so a caller with no ui vector simply skips the gate.
      */
     probeReachability?: () => Promise<import("./session-reachability.ts").ReachabilityVerdict>;
+    /**
+     * ui vector ONLY: read the window/focus census (read-only — no click, no
+     * keystroke, no activation), so a composite ORCHESTRATOR can refuse BEFORE it
+     * seeds a row when a dialog is already standing in Things (MODALX1, issue
+     * #620). Measured: the seed leg rides the URL scheme, which an open dialog
+     * does not touch, so the copy lands and then every AppleScript leg after it
+     * fails with `-1728` — the compound mutates for a reason it could have known
+     * up front. Null means the state could not be read; the caller proceeds (the
+     * drive's own precondition is the backstop). Absent on the real transport
+     * vectors and the simulator.
+     */
+    probeUiState?: () => Promise<import("./ui-state.ts").UiState | null>;
     /**
      * The bench-harness SIMULATOR vector (src/write/vectors/simulator.ts). It
      * presents under a real {@link VectorId} but applies mutations via SQL from
@@ -445,4 +661,20 @@ export interface WriteVector {
      * imports the developer's own grants into CI).
      */
     drivesGui?: boolean;
+    /**
+     * This vector delivers MUTATIONS through `things:///` URLs, so it is subject
+     * to Things' own in-app authorization — Settings ▸ General ▸ "Enable Things
+     * URLs" (URLEN1, #611). No macOS consent class is involved, but the two
+     * not-enabled states are both silent from the caller's side: an explicitly
+     * disabled app discards the command outright, and an app nobody has answered
+     * the first-use dialog for PARKS the command behind that dialog. Either way
+     * the write reports a silent no-op minutes later, so the pipeline reads the
+     * setting prompt-free and refuses before dispatch instead.
+     *
+     * Set ONLY by {@link import("./url-scheme.ts").createUrlSchemeVector}, for the
+     * same reason as its two siblings above: engine tests substitute fakes under
+     * the real ids, and a fake that opens no URL must not be gated on the state of
+     * the developer's own Things install.
+     */
+    dispatchesUrls?: boolean;
 }

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

@@ -1,7 +1,9 @@
 import { UI_DRIVE_OPS } from "../operations.js";
 /** The manifest profile — records the tier + Things build the suite certified. */
-export const UI_CERTIFICATION_PROFILE = "UIC1 + UIC3 + AXDRAG2 + UIC5 + UIC6 + UIC7 + UIC7b + HEADCERT1 + HXPC1 + DISS1 in-VM (Things 3.22.11) + " +
-    "UIC8 promote-via-clone compounds in-VM (golden-v2 / Things 3.22.12) — on-device pending";
+export const UI_CERTIFICATION_PROFILE = "UIC1 + UIC3 + AXDRAG2 + UIC5 + UIC6 + UIC7 + UIC7b + HEADCERT1 + HEADXPROJ + DISS1 in-VM (Things 3.22.11) + " +
+    "UIC8 promote-via-clone compounds in-VM (golden-v2 / Things 3.22.12) + RDLG2 recipe re-point + " +
+    "HXPC1 heading-ellipsis/Move-picker paths in-VM (golden-v4 / Things 3.23) + " +
+    "CHORDMH1 heading-order arrow chords in-VM (golden-v4 / Things 3.23) — on-device pending";
 const CERTIFICATION = {
     "todo.make-repeating": {
         status: "lab-certified",
@@ -48,16 +50,59 @@ const CERTIFICATION = {
         evidence: ["UI2-d", "UIC1-a", "HEADCERT1"],
     },
     "project.move-heading-to-project": {
-        // HXPC1 (2026-07-28, bjhx-lab, Things 3.22.11): the ellipsis Move… recipe ran
-        // end-to-end in the clone — HID-click the "More. <title>" button → Move… →
-        // type the destination → Return — and the exact HEADXPROJ delta was observed:
-        // heading `HXH` project-FK rewritten HX-PA → HX-PB, both children followed via
-        // their intact heading FK (project NULL, heading=HXH), single-row change, no
-        // index churn. The shipped recipe's popover-item AX PATHS (description-based
-        // click-element) are provisional pending an on-device sitting — HXPC1 drove the
-        // equivalent frame-center synthesis; the DB oracle + recipe flow are certified.
+        // HEADXPROJ (2026-07-27, bjhx-lab, Things 3.22.11) established the flow and the
+        // DB oracle with a hand-written driver: HID-click the "More. <title>" button →
+        // Move… → type the destination → Return, and heading `HXH`'s project FK
+        // rewritten HX-PA → HX-PB with both children following via their intact heading
+        // FK (project NULL, heading=HXH) — a single-row change, no index churn.
+        //
+        // HXPC1 (2026-08-25, hxpc1-lab, Things 3.23 / golden-v4) certified the SHIPPED
+        // recipe for the first time and corrected three of the four provisional paths:
+        // the "More. <title>" button is three levels below the content table (so the
+        // shipped one-level `whose` clause matched nothing and the drive never got past
+        // its first click), the picker is a detached `MovePopUpDialog-` window rather
+        // than a sheet of the main window, and the commit is a CLICK on the row whose
+        // title matches exactly — the blind Return could take the picker's
+        // `New Project "<typed>"` row whenever the destination was absent from it,
+        // which a completed or canceled destination is. 7/7 through the production CLI
+        // (clean match, prefix collision, completed-destination refusal with zero
+        // mutation). docs/lab/hxpc1-picker-assert.md.
         status: "lab-certified",
-        evidence: ["HXPC1"],
+        evidence: ["HEADXPROJ", "HXPC1"],
+    },
+    "project.move-heading": {
+        // HEADORD1 (2026-08-25, headord1-lab, Things 3.23 / golden-v4) discovered and
+        // characterised the affordance: ⌘↑/⌘↓ = ±1 slot, ⌘⌥↑/⌘⌥↓ = to top/bottom on a
+        // selected heading row; a single-row `index` rewrite with no sibling renumber
+        // and children untouched behind their FK; a chord with nowhere to go declined
+        // with zero delta and one alert beep; System Events modifiers frontmost-only,
+        // `CGEventPostToPid` background-capable.
+        //
+        // CHORDMH1 (2026-08-25, chordmh1-lab, Things 3.23 / golden-v4) certified the
+        // SHIPPED op. Its delivery gate re-measured the whole gesture with Things
+        // never activated at all — `open -g` reveal, pure-AX row select, pid-posted
+        // chord — and Finder frontmost at every stage, so the op ships BACKGROUND
+        // delivery with no `activate` step (the least-disruptive tier any ordering op
+        // has reached). The certification arms drove the production CLI over
+        // 3-heading fixtures: ±1 up, ±1 down, to-top, to-bottom, a multi-hop, the
+        // already-in-position no-op, the dry run, and the ungated call — children
+        // byte-identical on every arm, sibling indexes byte-identical, zero beeps on
+        // the normal paths. docs/lab/chordmh1-move-heading-build.md.
+        //
+        // CHORDMH2 (2026-08-25, chordmh2-lab, Things 3.23 / golden-v4) lifted CHORDMH1's
+        // one deliberate capability cut — the whole-project refusal on any archived
+        // heading — after CHORD2 cell 7a′ measured that an archived heading renders no
+        // content row, takes no ordinal in the walk, and is skipped by a live heading's
+        // ±1. The fence stood in for an ordinal mismatch, so the three reads that feed
+        // the plan, the driver and the bare-placement anchor now return the RENDERED
+        // (`status = 0`) order. Certified through the production CLI: one chord carried
+        // a heading past an archived row's slot, that heading was the only row
+        // rewritten, the archived row was byte-untouched on status/index/stopDate/umd,
+        // children intact, zero beeps; an archived heading named as a movee or an
+        // anchor still refuses with zero mutation.
+        // docs/lab/chordmh2-archived-fence-lift.md.
+        status: "lab-certified",
+        evidence: ["HEADORD1", "CHORDMH1", "CHORDMH2"],
     },
     "project.dissolve-heading": {
         // DISS1 (2026-07-28, bjhx-lab, Things 3.22.11): the ellipsis Delete recipe ran
@@ -66,8 +111,13 @@ const CERTIFICATION = {
         // TMTask), its 3 children re-homed as DIRECT project children (heading→NULL,
         // project→parent, index preserved: c1<c2<c3, trashed=0). NO confirm sheet.
         // Popover items are AX-description-enumerable (the recipe resolves Delete by
-        // description, scoped to the popover). The shipped recipe's popover AX paths are
-        // provisional pending an on-device sitting; the DB oracle + flow are certified.
+        // description, scoped to the popover) — the one provisional path HXPC1 measured
+        // CORRECT. Its sibling was not: the "More. <title>" button this drive opens the
+        // popover with was addressed one level too shallow, so it resolved nothing and
+        // the drive died at its first click on every host. HXPC1 (2026-08-25, Things
+        // 3.23) fixed the walk and certified it through the move-heading sibling, but
+        // this op was NOT driven end to end there — its next sitting should carry a cell
+        // (docs/lab/hxpc1-picker-assert.md §B0/§D). The DB oracle + flow are certified.
         status: "lab-certified",
         evidence: ["DISS1"],
     },

package/dist/write/vectors/ui-certification.js.map

@@ -1 +1 @@
-{"version":3,"file":"ui-certification.js","sourceRoot":"","sources":["../../../src/write/vectors/ui-certification.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"ui-certification.js","sourceRoot":"","sources":["../../../src/write/vectors/ui-certification.ts"],"names":[],"mappings":"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"}

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

@@ -0,0 +1,144 @@
+import type { DatabaseSync } from "node:sqlite";
+import type { UiCommand, UiRunner } from "./ui.ts";
+/** The move a `chord-reorder` step performs, compiled from the pre-state. */
+export interface HeadingChordSpec {
+    /** The project whose headings are being reordered. */
+    projectUuid: string;
+    /**
+     * Every LIVE (`status = 0`) heading of the project, in the order they must end
+     * up in — the full end state, not just the moved block. The driver places them
+     * left to right, so this doubles as the verification target. Archived headings
+     * are absent by construction: they render no row, so they are neither
+     * addressable nor displaced (CHORD2 cell 7a′).
+     */
+    targetOrder: string[];
+    /**
+     * The headings the caller named. Only these may ever be chorded: if the
+     * driver's placement walk would have to move a heading the caller did not
+     * name, it refuses rather than touch a bystander.
+     */
+    movees: string[];
+    /** The project view's content table (the recipe supplies the one path). */
+    tablePath: string;
+}
+/** The database read the driver asserts against between chords. */
+export interface HeadingOrderState {
+    /**
+     * The project's LIVE (`status = 0`) headings in `index` order, with their raw
+     * index — the rows the project view actually renders, and therefore the rows
+     * the positional `select-heading-row` walk enumerates. An ARCHIVED heading is
+     * absent: it renders no row, takes no ordinal, and a live heading's ±1 chord
+     * skips its slot in one dispatch (CHORD2 cell 7a′). Filtering here is what
+     * keeps the driver's ordinals in step with the walk's.
+     */
+    headings: {
+        uuid: string;
+        index: number;
+    }[];
+    /**
+     * Digest over every non-trashed child of those headings: `uuid:headingFK:index`.
+     * The chord law says children are untouched behind their FK — this is what
+     * proves it, and what catches the one measured hazard in the family (a row
+     * driven across a heading boundary has its heading FK rewritten, HEADORD1 §2
+     * cells 1h4/1i2; it cannot happen to a heading, and this asserts that).
+     */
+    childDigest: string;
+    /** How many child rows the digest covers (reported in the failure text). */
+    childCount: number;
+}
+/** The database seam the chord driver reads its ground truth through. */
+export type HeadingOrderReader = (projectUuid: string) => HeadingOrderState;
+/**
+ * The client-side default: heading order + child containment, from the open DB.
+ *
+ * The heading read is filtered to `status = 0` so it returns the RENDERED order
+ * (CHORD2 cell 7a′). The child digest is deliberately NOT filtered — it covers
+ * every non-trashed child of every heading of the project, archived headings
+ * included, because no heading chord may disturb any of them.
+ */
+export declare function createHeadingOrderReader(db: DatabaseSync): HeadingOrderReader;
+/**
+ * The four chords, as `(key code, CGEventFlags)` pairs. `126`/`125` are the
+ * arrow keys; `0x100000` is `kCGEventFlagMaskCommand` and `0x80000`
+ * `kCGEventFlagMaskAlternate`. Named rather than inlined so the recipe trace and
+ * the failure text can say which chord was posted.
+ */
+export type ChordId = "up-one" | "down-one" | "to-top" | "to-bottom";
+export declare function chordGlyph(id: ChordId): string;
+/**
+ * Post ONE modifier-bearing key event pair straight at the Things process
+ * (`CGEventPostToPid`), through the same JXA ObjC bridge every other synthetic
+ * input in this codebase rides.
+ *
+ * Why not System Events. The shipped `key` primitive emits `key code N` with no
+ * modifier support at all, and the System-Events spelling that DOES carry
+ * modifiers only lands while Things is FRONTMOST (HEADORD1 cell 1h2b: with
+ * Finder frontmost it produced no delta). `CGEventPostToPid` addresses the
+ * process rather than the focused surface, so the whole gesture — reveal,
+ * select, chord — runs with Things in the background and the user's focus
+ * untouched. Measured on Things 3.23 / golden-v4 (HEADORD1 1h2a; re-measured end
+ * to end, with Things never activated at all, by CHORDMH1's delivery gate).
+ *
+ * Note this is the KEYBOARD tap only. NATIVE1-e measured `CGEventPostToPid` as
+ * inert for Things' MOUSE hit-testing, which is why click synthesis still uses
+ * the HID tap and stays foreground-bound; keyboard events to the pid are a
+ * different path and do land.
+ */
+export declare function jxaChordScript(id: ChordId): string;
+export declare function chordCommand(id: ChordId): UiCommand;
+/** Select the Nth heading row of the revealed project view (the shipped primitive). */
+export declare function chordSelectCommand(tablePath: string, ordinal: number, script: string): UiCommand;
+export interface ChordDriveResult {
+    ok: boolean;
+    /** Human-readable outcome (chords posted) or the refusal reason. */
+    detail: string;
+    /** How many chords were posted before the outcome (partial-state honesty). */
+    chords: number;
+}
+/** One scheduled step: which heading to chord, with what, and where it must land. */
+export interface ChordStep {
+    /** The heading to select and move — ALWAYS one the caller named. */
+    uuid: string;
+    chord: ChordId;
+    /** The position the heading must occupy afterwards (the progress assertion). */
+    landsAt: number;
+}
+/**
+ * The next chord that advances `order` towards `target`, or null when they
+ * already agree. `movees` is the only set of rows a chord may ever move.
+ *
+ * THE SCHEDULE, and why it is this one. The obvious walk — "put target[i] into
+ * slot i, left to right" — is WRONG here, because target[i] is very often a row
+ * the caller never named: asking to move heading A down one slot produces a
+ * target whose first element is the BYSTANDER B. Moving B is not an option (it
+ * would break the untouched-siblings law the whole vector rests on), and the
+ * equally obvious repair — "push whichever movee sits at slot i down" — thrashes
+ * forever when two movees sit side by side, each pushing the other back.
+ *
+ * So the rule fixes the first mismatched slot `i` from the row's own side:
+ *
+ *  - target[i] IS a movee → it is necessarily BELOW slot i (everything above
+ *    already matches), so step it UP; from slot 0 the one-dispatch ⌘⌥↑ takes it
+ *    there directly.
+ *  - target[i] is a bystander `R` → every row between slot i and R's current
+ *    position is provably a movee (the non-movees keep their relative order, so
+ *    R is the first non-movee at or below i), and pushing the ONE movee directly
+ *    above R down past it moves R up by exactly one slot.
+ *
+ * Both branches strictly reduce a distance that cannot go below zero, so the
+ * schedule terminates, and every chord it emits moves a named heading by one
+ * slot. Two endpoint shortcuts run first, because they are the common single
+ * heading requests and each costs one dispatch instead of a walk: a movee whose
+ * target is the very top or the very bottom is sent there with ⌘⌥↑ / ⌘⌥↓.
+ */
+export declare function planChordStep(order: readonly string[], target: readonly string[], movees: ReadonlySet<string>): ChordStep | {
+    error: string;
+} | null;
+/**
+ * Drive a project's headings into `spec.targetOrder`, one verified chord at a
+ * time (see {@link planChordStep} for the schedule). Nothing here trusts the
+ * plan it made a moment ago: every step is re-derived from a fresh database
+ * read, and the step is only counted once the database says it landed where it
+ * was aimed with nothing else touched.
+ */
+export declare function driveHeadingChordReorder(spec: HeadingChordSpec, run: UiRunner, reader: HeadingOrderReader | undefined, selectScript: (ordinal: number) => string, sleep?: (ms: number) => Promise<void>): Promise<ChordDriveResult>;