things-api 0.19.2 → 0.19.4

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

@@ -65,6 +65,39 @@ export type UiSheetForm = "none" | "attached" | "detached";
  * `missing value`), `sheetForm` and `sheetDepth` bound.
  */
 export declare const AX_DIALOG_SHELL_SNIPPET = "\t\tset shellRef to missing value\n\t\tset sheetForm to \"none\"\n\t\tset sheetDepth to 0\n\t\ttry\n\t\t\t-- positional-ok: the one attached sheet a window can present, which is\n\t\t\t-- the BOTTOM of any stack; the walk below climbs to the top.\n\t\t\tset shellRef to sheet 1 of (first window whose subrole is \"AXStandardWindow\")\n\t\t\tset sheetForm to \"attached\"\n\t\t\tset sheetDepth to 1\n\t\tend try\n\t\tif shellRef is missing value then\n\t\t\ttry\n\t\t\t\tset dws to (windows whose subrole is \"AXUnknown\" and size is not {40, 40})\n\t\t\t\tif (count of dws) > 0 then\n\t\t\t\t\tset shellRef to item 1 of dws\n\t\t\t\t\tset sheetForm to \"detached\"\n\t\t\t\t\tset sheetDepth to 1\n\t\t\t\tend if\n\t\t\tend try\n\t\tend if\n\t\tif shellRef is not missing value then\n\t\t\trepeat 6 times\n\t\t\t\tset nested to missing value\n\t\t\t\ttry\n\t\t\t\t\tif (exists sheet 1 of shellRef) then set nested to sheet 1 of shellRef\n\t\t\t\tend try\n\t\t\t\tif nested is missing value then exit repeat\n\t\t\t\tset shellRef to nested\n\t\t\t\tset sheetDepth to sheetDepth + 1\n\t\t\tend repeat\n\t\tend if";
+/**
+ * The census's individually-budgeted probes, in the order they run. The first
+ * three are DECISION-CRITICAL — the guard, the drive preflight and the cleanup
+ * ladder all decide on them — and the last two are DECORATION for the refusal
+ * copy. That order is the point: everything a caller acts on is proven before a
+ * single unaddressed query is attempted.
+ *
+ *   - `running`  — is there a Things process at all (a name-keyed lookup);
+ *   - `frontmost` — `frontmost of process "Things3"`, ADDRESSED: the one fact a
+ *                   keystroke guard actually needs;
+ *   - `dialog`   — the dialog shell, its form, its stack depth and its control
+ *                   census, all addressed inside `process "Things3"`;
+ *   - `frontapp` — WHICH other application owns the screen. This is the whole
+ *                   process table enumerated (`first application process whose
+ *                   frontmost is true`), so it runs only when the addressed
+ *                   `frontmost` probe already said the answer is not Things, and
+ *                   only for the sentence that names the thief;
+ *   - `focus`    — the focused element's role, through
+ *                   `AXFocusedUIElement`. MEASURED at ~3.5x the cost of every
+ *                   addressed probe in this vector even on a bare clone
+ *                   (docs/lab/fgrd2-census-hardening.md §2), and it decides
+ *                   nothing — so it goes last, inside its own budget, and its
+ *                   absence costs a clause in a sentence.
+ */
+export type UiProbe = "running" | "frontmost" | "dialog" | "frontapp" | "focus";
+/**
+ * The transport deadline for one census hop — the backstop under the in-script
+ * budgets, not the mechanism. Deliberately far below the 15s step timeout that
+ * bounded the old single-shot script: nothing here may take this long, and if
+ * it does the caller must hear about it while the drive can still be aborted
+ * cleanly rather than after four of them have gone by.
+ */
+export declare const CENSUS_TIMEOUT_MS = 12000;
 /** Who owns keyboard focus. Role only — never the element's value or title (see PRIVACY). */
 export interface UiFocusOwner {
     /** The frontmost application's process name (e.g. "Things3"). */
@@ -105,9 +138,30 @@ export interface UiState {
      * of a SECURE SYSTEM MODAL (a macOS privacy/consent dialog), which belongs to
      * no application's Accessibility tree. Everything else in the census is then
      * "what could still be proven", never a guess.
+     *
+     * A probe that TIMED OUT does not set this: "macOS refused to describe the
+     * screen" and "the screen did not answer in time" are different facts with
+     * different remediations, and #629 is what conflating them costs.
      */
     inspectable: boolean;
+    /**
+     * The probes that did not answer within their budget. Non-empty means the
+     * corresponding fields are UNPROVEN, not false — every caller reads them that
+     * way, and a critical probe here aborts a drive instead of being retried.
+     */
+    stalledProbes: UiProbe[];
+    /**
+     * The probes that answered with an error rather than a value (the surface is
+     * there but would not describe itself — a secure modal, a process that exited
+     * between two reads). Reported for the same reason: what could not be proven
+     * is named, never guessed at.
+     */
+    failedProbes: UiProbe[];
 }
+/** Did a probe the caller has to DECIDE on fail to answer? */
+export declare function censusUnverifiable(state: UiState | null): boolean;
+/** Name the probes that did not answer, for a diagnostic someone has to act on. */
+export declare function describeUnprovenProbes(state: UiState): string;
 /** A recognizable token in the script so a test runner can key off the ui-state command. */
 export declare const UI_STATE_MARKER = "-- ui-state census (read-only)";
 /** The label every ui-state dispatch carries (one stable command shape). */
@@ -115,12 +169,78 @@ export declare const UI_STATE_LABEL = "read the window and focus state";
 /** The Things application's process name — the frontmost value that means "us". */
 export declare const THINGS_PROCESS = "Things3";
 /**
- * The census script. Every read is wrapped: a surface that will not answer
- * degrades that ONE field rather than failing the whole census, because the
- * cases this exists for — a foreign modal, an AX-blind session — are exactly
- * the cases where half the tree is unreadable.
+ * The census script — ADDRESSED probes, each on its own Apple-event budget
+ * (issue #629).
+ *
+ * WHAT CHANGED, AND WHY IT HAD TO. The 0.19.2 census was one unbounded script
+ * that opened with two UNADDRESSED queries: `first application process whose
+ * frontmost is true` (the entire process table enumerated) and `value of
+ * attribute "AXFocusedUIElement"` on whatever that returned (a system-wide
+ * focused-element resolution). Everything else the ui vector runs — every step
+ * the field incident's log shows succeeding, inside the very sheet the census
+ * could not describe — is addressed: `tell process "Things3" to …`. So the one
+ * script that stalled was the one script that left the addressed style, and it
+ * stalled on the critical path of BOTH the per-step guard and the cleanup that
+ * was supposed to recover from it. Rebuilt here so that:
+ *
+ *   - the decision-critical facts are ADDRESSED and are proven FIRST;
+ *   - every read carries `with timeout of ${PROBE_TIMEOUT_S} seconds`, so a
+ *     surface that will not answer costs seconds, not the caller's whole
+ *     deadline;
+ *   - a critical probe that does not answer STOPS the census then and there —
+ *     the remaining probes cannot change what the caller must now do (abort and
+ *     clean up), so waiting for them is pure latency;
+ *   - the two unaddressed queries survive only as DECORATION, last, skipped
+ *     entirely when the addressed probes already answered the question they
+ *     were there to answer.
+ *
+ * Every probe still degrades one field rather than failing the census, and what
+ * could not be proven is NAMED (`stalled=` / `failed=`) instead of silently
+ * reading as a clean "nothing is open".
  */
 export declare function axUiStateScript(): string;
+/** The stderr line prefix carrying a folded guard's census record. */
+export declare const GUARD_LOG_PREFIX = "#FGCENSUS ";
+/** The separator joining that record's fields on its single line. */
+export declare const GUARD_LOG_SEP = " ~|~ ";
+/**
+ * What a folded guard RAISES when it refuses. Deliberately a machine tag rather
+ * than a sentence: the refusal a caller reads is still built by
+ * {@link judgeFocusGuard} in TypeScript, from the census this same hop logged, so
+ * there is exactly ONE place the wording lives and the in-script judgement can
+ * never drift from it.
+ */
+export declare const GUARD_REFUSED_TAG = "#FGREFUSE";
+/**
+ * The census as the IN-SCRIPT PRELUDE of the hop it guards (DRVLAT1, issue #633).
+ *
+ * The per-step focus guard used to be its own osascript round-trip: census hop,
+ * then keystroke hop. That is both a hop of latency per typed control AND a
+ * TOCTOU window — the screen can change between the census that approved the
+ * keystroke and the keystroke itself. Prepending the census to the very script
+ * that types closes both: the probes and the input now run in one process, in
+ * order, with nothing dispatched in between.
+ *
+ * The prelude LOGS its census record (stderr, one line) and then judges it
+ * IN-SCRIPT, raising {@link GUARD_REFUSED_TAG} — a bare tag — when the input must
+ * not be sent. The caller recovers the logged record, parses it into the same
+ * {@link UiState} the stand-alone census yields, and asks {@link judgeFocusGuard}
+ * for the sentence. So the DECISION is made before the keystroke, in-script, and
+ * the WORDING is still single-sourced in TypeScript.
+ *
+ * `expectedSheet` is the dialog the drive has observed itself driving; pass null
+ * where no dialog invariant applies.
+ */
+export declare function axFocusGuardPrelude(expectedSheet: UiSheetKind | null): string;
+/**
+ * Recover a folded guard's census from the hop's stderr: the parsed state (null
+ * when no record was logged) and the stderr with that line removed, so a failure
+ * message a caller reads never carries the machinery.
+ */
+export declare function parseGuardLog(stderr: string): {
+    state: UiState | null;
+    stderr: string;
+};
 /**
  * Parse the census record into a {@link UiState}. Returns null when the output
  * carries none of the expected keys (a transport error, or a script that never
@@ -131,8 +251,11 @@ export declare function parseUiState(stdout: string): UiState | null;
  * Read the census through the injected runner. Returns null on a transport
  * failure — an UNKNOWN state, which every caller treats fail-closed (the guard
  * refuses; the cleanup path does not send a blind Escape).
+ *
+ * `timeoutMs` defaults to {@link CENSUS_TIMEOUT_MS}: a census is not a drive
+ * step and must not borrow a drive step's patience (issue #629).
  */
-export declare function readUiState(run: (command: UiCommand, timeoutMs: number) => Promise<UiRunResult>, timeoutMs: number): Promise<UiState | null>;
+export declare function readUiState(run: (command: UiCommand, timeoutMs: number) => Promise<UiRunResult>, timeoutMs?: number): Promise<UiState | null>;
 /**
  * How to name the surface that owns the screen, for a refusal someone has to
  * act on. Names the APPLICATION and the focused element's ROLE — never its
@@ -141,7 +264,14 @@ export declare function readUiState(run: (command: UiCommand, timeoutMs: number)
  * at the keyboard has to look at the screen themselves.
  */
 export declare function describeFocusOwner(state: UiState | null): string;
-/** A one-line human summary of the census, for a diagnostic line or a warning. */
+/**
+ * A one-line human summary of the census, for a diagnostic line or a warning.
+ *
+ * Reports WHAT EACH PROBE PROVED. A stalled probe leaves its clause reading
+ * "could not be determined" and is named at the end — never omitted, and never
+ * rendered as its default (issue #629: a census that could not see the open
+ * Repeat sheet used to report a clean screen).
+ */
 export declare function describeUiState(state: UiState): string;
 /**
  * The warning an OPEN Things dialog earns, wherever it is reported.