@mseep/clawdcursor 1.5.5

package/dist/core/sense/ui-map-geom.js

@@ -0,0 +1,16 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.iou = iou;
+/** Intersection-over-union of two [x,y,w,h] screen-space boxes. 0 when disjoint. */
+function iou(a, b) {
+    const [ax, ay, aw, ah] = a;
+    const [bx, by, bw, bh] = b;
+    const x1 = Math.max(ax, bx);
+    const y1 = Math.max(ay, by);
+    const x2 = Math.min(ax + aw, bx + bw);
+    const y2 = Math.min(ay + ah, by + bh);
+    const inter = Math.max(0, x2 - x1) * Math.max(0, y2 - y1);
+    const uni = aw * ah + bw * bh - inter;
+    return uni <= 0 ? 0 : inter / uni;
+}
+//# sourceMappingURL=ui-map-geom.js.map

package/dist/core/sense/ui-map-geom.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ui-map-geom.js","sourceRoot":"","sources":["../../../src/core/sense/ui-map-geom.ts"],"names":[],"mappings":";;AAGA,kBAUC;AAXD,oFAAoF;AACpF,SAAgB,GAAG,CAAC,CAAS,EAAE,CAAS;IACtC,MAAM,CAAC,EAAE,EAAE,EAAE,EAAE,EAAE,EAAE,EAAE,CAAC,GAAG,CAAC,CAAC;IAC3B,MAAM,CAAC,EAAE,EAAE,EAAE,EAAE,EAAE,EAAE,EAAE,CAAC,GAAG,CAAC,CAAC;IAC3B,MAAM,EAAE,GAAG,IAAI,CAAC,GAAG,CAAC,EAAE,EAAE,EAAE,CAAC,CAAC;IAC5B,MAAM,EAAE,GAAG,IAAI,CAAC,GAAG,CAAC,EAAE,EAAE,EAAE,CAAC,CAAC;IAC5B,MAAM,EAAE,GAAG,IAAI,CAAC,GAAG,CAAC,EAAE,GAAG,EAAE,EAAE,EAAE,GAAG,EAAE,CAAC,CAAC;IACtC,MAAM,EAAE,GAAG,IAAI,CAAC,GAAG,CAAC,EAAE,GAAG,EAAE,EAAE,EAAE,GAAG,EAAE,CAAC,CAAC;IACtC,MAAM,KAAK,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,EAAE,GAAG,EAAE,CAAC,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,EAAE,GAAG,EAAE,CAAC,CAAC;IAC1D,MAAM,GAAG,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,KAAK,CAAC;IACtC,OAAO,GAAG,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,KAAK,GAAG,GAAG,CAAC;AACpC,CAAC"}

package/dist/core/sense/ui-map-holder.d.ts

@@ -0,0 +1,58 @@
+/**
+ * Session-scoped cache of recently compiled UIMaps, enabling safe el_NN element
+ * references (resolve {snapshot_id, element_id} -> live element). Strict by
+ * design: only the CURRENT, non-invalidated, in-TTL map resolves. See
+ * docs/superpowers/specs/2026-06-07-ui-state-compiler-part2-design.md §2.
+ */
+import type { UIMap, MaxCost } from './ui-map-types';
+/**
+ * Wall-clock backstop for ref freshness. The PRIMARY staleness signal is
+ * event-driven (`invalidate()` after every screen-changing action) plus the
+ * resolve-time window guard (pid/title must still match) — the TTL only
+ * catches background drift no agent action caused. It must therefore be
+ * sized to SURVIVE an LLM round-trip: refs are advertised at the end of
+ * turn N and consumed on turn N+1, after prompt assembly + a full model
+ * call (45s timeout, backoff retries). The original 5s expired virtually
+ * every cross-turn ref (audit 2026-06-10, finding A2).
+ */
+export declare const TTL_MS = 60000;
+/** Perception-cost ordering for reuse decisions: cheap < ocr_ok < vision_ok. */
+export declare const COST_RANK: Record<MaxCost, number>;
+/** Keep the current map + one prior (diagnostics); only current resolves. */
+export declare const MAX_HELD = 2;
+type Resolution = {
+    ok: true;
+    map: UIMap;
+} | {
+    ok: false;
+    reason: 'unknown' | 'stale' | 'expired';
+};
+export declare class UIMapHolder {
+    private held;
+    private counter;
+    private invalidated;
+    /** Mint the next session-scoped id; caller passes it to compileUIMap. */
+    nextId(): string;
+    /** Store a compiled map as the new current; records the compiled max_cost
+     *  (for currentIfCost reuse); un-invalidates; bounds to MAX_HELD. */
+    put(map: UIMap, now: number, maxCost?: MaxCost): void;
+    /** Resolve a ref. Only the current, non-invalidated, in-TTL map is usable. */
+    resolve(snapshotId: string, now: number): Resolution;
+    /** Return the current map iff it resolves (fresh/in-TTL/not-invalidated) AND
+     *  was compiled at a cost >= requested. Else null (caller compiles fresh).
+     *  Correctness first, cost-reuse second. */
+    currentIfCost(requested: MaxCost, now: number): UIMap | null;
+    /** Mark all held maps invalid — called after any screen-changing action. */
+    invalidate(): void;
+    /** Re-stamp the current map's compiledAt — called when the loop re-ADVERTISES
+     *  an existing map to the model (§6b reuse branch), so the TTL clock runs
+     *  from the last advertisement, not the original compile. No-op unless the
+     *  id is the current, non-invalidated map (never resurrects stale maps). */
+    touch(snapshotId: string, now: number): void;
+    currentId(): string | undefined;
+    /** The latest held map (for rendering/inspection), or undefined. Unlike
+     *  resolve(), this ignores TTL/invalidation — callers that need a resolvable
+     *  map use resolve()/currentIfCost(). */
+    current(): UIMap | undefined;
+}
+export {};

package/dist/core/sense/ui-map-holder.js

@@ -0,0 +1,87 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.UIMapHolder = exports.MAX_HELD = exports.COST_RANK = exports.TTL_MS = void 0;
+/**
+ * Wall-clock backstop for ref freshness. The PRIMARY staleness signal is
+ * event-driven (`invalidate()` after every screen-changing action) plus the
+ * resolve-time window guard (pid/title must still match) — the TTL only
+ * catches background drift no agent action caused. It must therefore be
+ * sized to SURVIVE an LLM round-trip: refs are advertised at the end of
+ * turn N and consumed on turn N+1, after prompt assembly + a full model
+ * call (45s timeout, backoff retries). The original 5s expired virtually
+ * every cross-turn ref (audit 2026-06-10, finding A2).
+ */
+exports.TTL_MS = 60_000;
+/** Perception-cost ordering for reuse decisions: cheap < ocr_ok < vision_ok. */
+exports.COST_RANK = { cheap: 0, ocr_ok: 1, vision_ok: 2 };
+/** Keep the current map + one prior (diagnostics); only current resolves. */
+exports.MAX_HELD = 2;
+class UIMapHolder {
+    held = [];
+    counter = 0;
+    invalidated = false;
+    /** Mint the next session-scoped id; caller passes it to compileUIMap. */
+    nextId() {
+        this.counter += 1;
+        return `obs_${this.counter}`;
+    }
+    /** Store a compiled map as the new current; records the compiled max_cost
+     *  (for currentIfCost reuse); un-invalidates; bounds to MAX_HELD. */
+    put(map, now, maxCost) {
+        this.held.push({ map, compiledAt: now, maxCost });
+        if (this.held.length > exports.MAX_HELD)
+            this.held.shift();
+        this.invalidated = false;
+    }
+    /** Resolve a ref. Only the current, non-invalidated, in-TTL map is usable. */
+    resolve(snapshotId, now) {
+        const current = this.held[this.held.length - 1];
+        if (!current || current.map.snapshot_id !== snapshotId) {
+            const heldOlder = this.held.some(h => h.map.snapshot_id === snapshotId);
+            return { ok: false, reason: heldOlder ? 'stale' : 'unknown' };
+        }
+        if (this.invalidated)
+            return { ok: false, reason: 'stale' };
+        if (now - current.compiledAt > exports.TTL_MS)
+            return { ok: false, reason: 'expired' };
+        return { ok: true, map: current.map };
+    }
+    /** Return the current map iff it resolves (fresh/in-TTL/not-invalidated) AND
+     *  was compiled at a cost >= requested. Else null (caller compiles fresh).
+     *  Correctness first, cost-reuse second. */
+    currentIfCost(requested, now) {
+        const current = this.held[this.held.length - 1];
+        if (!current)
+            return null;
+        if (this.resolve(current.map.snapshot_id, now).ok !== true)
+            return null;
+        if (current.maxCost === undefined)
+            return null; // unknown cost → don't reuse
+        return exports.COST_RANK[current.maxCost] >= exports.COST_RANK[requested] ? current.map : null;
+    }
+    /** Mark all held maps invalid — called after any screen-changing action. */
+    invalidate() {
+        this.invalidated = true;
+    }
+    /** Re-stamp the current map's compiledAt — called when the loop re-ADVERTISES
+     *  an existing map to the model (§6b reuse branch), so the TTL clock runs
+     *  from the last advertisement, not the original compile. No-op unless the
+     *  id is the current, non-invalidated map (never resurrects stale maps). */
+    touch(snapshotId, now) {
+        const current = this.held[this.held.length - 1];
+        if (!current || current.map.snapshot_id !== snapshotId || this.invalidated)
+            return;
+        current.compiledAt = now;
+    }
+    currentId() {
+        return this.held[this.held.length - 1]?.map.snapshot_id;
+    }
+    /** The latest held map (for rendering/inspection), or undefined. Unlike
+     *  resolve(), this ignores TTL/invalidation — callers that need a resolvable
+     *  map use resolve()/currentIfCost(). */
+    current() {
+        return this.held[this.held.length - 1]?.map;
+    }
+}
+exports.UIMapHolder = UIMapHolder;
+//# sourceMappingURL=ui-map-holder.js.map

package/dist/core/sense/ui-map-holder.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ui-map-holder.js","sourceRoot":"","sources":["../../../src/core/sense/ui-map-holder.ts"],"names":[],"mappings":"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"}

package/dist/core/sense/ui-map-normalize.d.ts

@@ -0,0 +1,19 @@
+import type { Role, Source } from './ui-map-types';
+/** Map a UIA/AX control type (e.g. "ControlType.Button", "Edit", "TextField") to a Role. */
+export declare function normalizeRole(controlType?: string): Role;
+/** Trim, lowercase, collapse internal whitespace. */
+export declare function normText(text?: string): string;
+/**
+ * Capability flags. role describes WHAT it is; these describe WHAT YOU CAN DO.
+ * a11y elements carry pattern intent via role + enabled; OCR-only elements have
+ * no pattern info, so they're read-only text unless a later source corroborates.
+ */
+export declare function inferCapabilities(opts: {
+    role: Role;
+    source: Source;
+    enabled?: boolean;
+}): {
+    clickable: boolean;
+    editable: boolean;
+    actionable: boolean;
+};

package/dist/core/sense/ui-map-normalize.js

@@ -0,0 +1,65 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.normalizeRole = normalizeRole;
+exports.normText = normText;
+exports.inferCapabilities = inferCapabilities;
+// Canonical roles keyed by BOTH Windows UIA control-type strings and macOS AX
+// role strings (after the platform adapters strip "ControlType."/"AX"). The map
+// was originally UIA-only, which meant macOS AX inputs ("TextField"/"TextArea")
+// and links ("Link") fell through to 'unknown' → editable/clickable both false →
+// the entire el_NN find_field/find_action/{element_id}-fill + link-click surface
+// was DEAD on macOS (audit 2026-06-11, M1). AX synonyms below restore parity.
+const ROLE_MAP = {
+    // buttons
+    button: 'button', splitbutton: 'button', menuitem: 'button',
+    menubutton: 'button', popupbutton: 'button', // AX
+    // text inputs
+    edit: 'input', document: 'input', combobox: 'input', spinner: 'input',
+    textfield: 'input', textarea: 'input', securetextfield: 'input', // AX
+    passwordfield: 'input', searchfield: 'input', incrementor: 'input', // AX
+    // static text
+    text: 'text', statictext: 'text',
+    // links
+    hyperlink: 'link', link: 'link', // link (UIA), AXLink
+    // toggles
+    checkbox: 'checkbox', radiobutton: 'checkbox',
+    checkboxcell: 'checkbox', radiobuttoncell: 'checkbox', // AX cells
+    // lists
+    list: 'list', listbox: 'list', table: 'list', outline: 'list', // AX table/outline
+    listitem: 'listitem', treeitem: 'listitem', row: 'listitem', cell: 'listitem',
+    // tabs
+    tab: 'tab', tabitem: 'tab', radiobuttongroup: 'tab',
+    // images
+    image: 'image',
+};
+/** Map a UIA/AX control type (e.g. "ControlType.Button", "Edit", "TextField") to a Role. */
+function normalizeRole(controlType) {
+    if (!controlType)
+        return 'unknown';
+    // Strip the UIA "ControlType." prefix AND any residual macOS "AX" prefix
+    // (the adapter usually strips it, but be defensive so "AXTextField" maps too).
+    const key = controlType
+        .replace(/^ControlType\./, '')
+        .replace(/^AX/, '')
+        .trim().toLowerCase();
+    return ROLE_MAP[key] ?? 'unknown';
+}
+/** Trim, lowercase, collapse internal whitespace. */
+function normText(text) {
+    return (text ?? '').trim().toLowerCase().replace(/\s+/g, ' ');
+}
+const CLICKABLE_ROLES = new Set(['button', 'link', 'checkbox', 'listitem', 'tab']);
+/**
+ * Capability flags. role describes WHAT it is; these describe WHAT YOU CAN DO.
+ * a11y elements carry pattern intent via role + enabled; OCR-only elements have
+ * no pattern info, so they're read-only text unless a later source corroborates.
+ */
+function inferCapabilities(opts) {
+    const fromA11y = opts.source === 'a11y';
+    const clickable = fromA11y && CLICKABLE_ROLES.has(opts.role);
+    const editable = fromA11y && opts.role === 'input';
+    const enabled = opts.enabled !== false;
+    const actionable = (clickable || editable) && enabled;
+    return { clickable, editable, actionable };
+}
+//# sourceMappingURL=ui-map-normalize.js.map

package/dist/core/sense/ui-map-normalize.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ui-map-normalize.js","sourceRoot":"","sources":["../../../src/core/sense/ui-map-normalize.ts"],"names":[],"mappings":";;AAiCA,sCASC;AAGD,4BAEC;AASD,8CASC;AA/DD,8EAA8E;AAC9E,gFAAgF;AAChF,gFAAgF;AAChF,iFAAiF;AACjF,iFAAiF;AACjF,8EAA8E;AAC9E,MAAM,QAAQ,GAAyB;IACrC,UAAU;IACV,MAAM,EAAE,QAAQ,EAAE,WAAW,EAAE,QAAQ,EAAE,QAAQ,EAAE,QAAQ;IAC3D,UAAU,EAAE,QAAQ,EAAE,WAAW,EAAE,QAAQ,EAAE,KAAK;IAClD,cAAc;IACd,IAAI,EAAE,OAAO,EAAE,QAAQ,EAAE,OAAO,EAAE,QAAQ,EAAE,OAAO,EAAE,OAAO,EAAE,OAAO;IACrE,SAAS,EAAE,OAAO,EAAE,QAAQ,EAAE,OAAO,EAAE,eAAe,EAAE,OAAO,EAAQ,KAAK;IAC5E,aAAa,EAAE,OAAO,EAAE,WAAW,EAAE,OAAO,EAAE,WAAW,EAAE,OAAO,EAAK,KAAK;IAC5E,cAAc;IACd,IAAI,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM;IAChC,QAAQ;IACR,SAAS,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAwC,qBAAqB;IAC5F,UAAU;IACV,QAAQ,EAAE,UAAU,EAAE,WAAW,EAAE,UAAU;IAC7C,YAAY,EAAE,UAAU,EAAE,eAAe,EAAE,UAAU,EAAkB,WAAW;IAClF,QAAQ;IACR,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAU,mBAAmB;IAC1F,QAAQ,EAAE,UAAU,EAAE,QAAQ,EAAE,UAAU,EAAE,GAAG,EAAE,UAAU,EAAE,IAAI,EAAE,UAAU;IAC7E,OAAO;IACP,GAAG,EAAE,KAAK,EAAE,OAAO,EAAE,KAAK,EAAE,gBAAgB,EAAE,KAAK;IACnD,SAAS;IACT,KAAK,EAAE,OAAO;CACf,CAAC;AAEF,4FAA4F;AAC5F,SAAgB,aAAa,CAAC,WAAoB;IAChD,IAAI,CAAC,WAAW;QAAE,OAAO,SAAS,CAAC;IACnC,yEAAyE;IACzE,+EAA+E;IAC/E,MAAM,GAAG,GAAG,WAAW;SACpB,OAAO,CAAC,gBAAgB,EAAE,EAAE,CAAC;SAC7B,OAAO,CAAC,KAAK,EAAE,EAAE,CAAC;SAClB,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC;IACxB,OAAO,QAAQ,CAAC,GAAG,CAAC,IAAI,SAAS,CAAC;AACpC,CAAC;AAED,qDAAqD;AACrD,SAAgB,QAAQ,CAAC,IAAa;IACpC,OAAO,CAAC,IAAI,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC,OAAO,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;AAChE,CAAC;AAED,MAAM,eAAe,GAAG,IAAI,GAAG,CAAO,CAAC,QAAQ,EAAE,MAAM,EAAE,UAAU,EAAE,UAAU,EAAE,KAAK,CAAC,CAAC,CAAC;AAEzF;;;;GAIG;AACH,SAAgB,iBAAiB,CAAC,IAAuD;IAGvF,MAAM,QAAQ,GAAG,IAAI,CAAC,MAAM,KAAK,MAAM,CAAC;IACxC,MAAM,SAAS,GAAG,QAAQ,IAAI,eAAe,CAAC,GAAG,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IAC7D,MAAM,QAAQ,GAAG,QAAQ,IAAI,IAAI,CAAC,IAAI,KAAK,OAAO,CAAC;IACnD,MAAM,OAAO,GAAG,IAAI,CAAC,OAAO,KAAK,KAAK,CAAC;IACvC,MAAM,UAAU,GAAG,CAAC,SAAS,IAAI,QAAQ,CAAC,IAAI,OAAO,CAAC;IACtD,OAAO,EAAE,SAAS,EAAE,QAAQ,EAAE,UAAU,EAAE,CAAC;AAC7C,CAAC"}

package/dist/core/sense/ui-map-render.d.ts

@@ -0,0 +1,4 @@
+import type { UIMap } from './ui-map-types';
+export declare function renderUIMap(map: UIMap, opts?: {
+    max?: number;
+}): string;

package/dist/core/sense/ui-map-render.js

@@ -0,0 +1,34 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.renderUIMap = renderUIMap;
+const DEFAULT_MAX = 120;
+/** Rank: actionable first, then by confidence. */
+function rankScore(e) {
+    return (e.actionable ? 1000 : 0) + e.confidence * 100;
+}
+function line(e) {
+    const flags = [];
+    if (e.state?.focused)
+        flags.push('focused');
+    if (e.clickable)
+        flags.push('clickable');
+    if (e.editable)
+        flags.push('editable');
+    if (e.state?.enabled === false)
+        flags.push('disabled');
+    const [x, y, w, h] = e.bounds;
+    const conf = e.confidence.toFixed(2);
+    const flagStr = flags.length ? ` {${flags.join(',')}}` : '';
+    const val = e.state?.value ? ` = "${e.state.value.length > 60 ? e.state.value.slice(0, 59) + '…' : e.state.value}"` : '';
+    return `${e.id} [${e.role}] "${e.text ?? e.normalized_text ?? ''}"${val} (${conf} ${e.sources.join(',')}) @${x},${y} ${w}x${h}${flagStr}`;
+}
+function renderUIMap(map, opts = {}) {
+    const max = opts.max ?? DEFAULT_MAX;
+    const ranked = [...map.elements].sort((a, b) => rankScore(b) - rankScore(a));
+    const shown = ranked.slice(0, max);
+    const body = shown.map(line).join('\n');
+    const context = `${map.active_app} — "${map.window_title}" [${map.snapshot_id}] (${map.sources_used.join('+')})`;
+    const trunc = ranked.length > max ? `\n… ${max} of ${ranked.length} shown` : '';
+    return `${body}${trunc}\n${context}`;
+}
+//# sourceMappingURL=ui-map-render.js.map

package/dist/core/sense/ui-map-render.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ui-map-render.js","sourceRoot":"","sources":["../../../src/core/sense/ui-map-render.ts"],"names":[],"mappings":";;AAsBA,kCAQC;AA5BD,MAAM,WAAW,GAAG,GAAG,CAAC;AAExB,kDAAkD;AAClD,SAAS,SAAS,CAAC,CAAY;IAC7B,OAAO,CAAC,CAAC,CAAC,UAAU,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,UAAU,GAAG,GAAG,CAAC;AACxD,CAAC;AAED,SAAS,IAAI,CAAC,CAAY;IACxB,MAAM,KAAK,GAAa,EAAE,CAAC;IAC3B,IAAI,CAAC,CAAC,KAAK,EAAE,OAAO;QAAE,KAAK,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC;IAC5C,IAAI,CAAC,CAAC,SAAS;QAAE,KAAK,CAAC,IAAI,CAAC,WAAW,CAAC,CAAC;IACzC,IAAI,CAAC,CAAC,QAAQ;QAAE,KAAK,CAAC,IAAI,CAAC,UAAU,CAAC,CAAC;IACvC,IAAI,CAAC,CAAC,KAAK,EAAE,OAAO,KAAK,KAAK;QAAE,KAAK,CAAC,IAAI,CAAC,UAAU,CAAC,CAAC;IACvD,MAAM,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC,MAAM,CAAC;IAC9B,MAAM,IAAI,GAAG,CAAC,CAAC,UAAU,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC;IACrC,MAAM,OAAO,GAAG,KAAK,CAAC,MAAM,CAAC,CAAC,CAAC,KAAK,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC;IAC5D,MAAM,GAAG,GAAG,CAAC,CAAC,KAAK,EAAE,KAAK,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,KAAK,CAAC,KAAK,CAAC,MAAM,GAAG,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC,GAAG,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,KAAK,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC;IACzH,OAAO,GAAG,CAAC,CAAC,EAAE,KAAK,CAAC,CAAC,IAAI,MAAM,CAAC,CAAC,IAAI,IAAI,CAAC,CAAC,eAAe,IAAI,EAAE,IAAI,GAAG,KAAK,IAAI,IAAI,CAAC,CAAC,OAAO,CAAC,IAAI,CAAC,GAAG,CAAC,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,OAAO,EAAE,CAAC;AAC5I,CAAC;AAED,SAAgB,WAAW,CAAC,GAAU,EAAE,OAAyB,EAAE;IACjE,MAAM,GAAG,GAAG,IAAI,CAAC,GAAG,IAAI,WAAW,CAAC;IACpC,MAAM,MAAM,GAAG,CAAC,GAAG,GAAG,CAAC,QAAQ,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,SAAS,CAAC,CAAC,CAAC,GAAG,SAAS,CAAC,CAAC,CAAC,CAAC,CAAC;IAC7E,MAAM,KAAK,GAAG,MAAM,CAAC,KAAK,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC;IACnC,MAAM,IAAI,GAAG,KAAK,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IACxC,MAAM,OAAO,GAAG,GAAG,GAAG,CAAC,UAAU,OAAO,GAAG,CAAC,YAAY,MAAM,GAAG,CAAC,WAAW,MAAM,GAAG,CAAC,YAAY,CAAC,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC;IACjH,MAAM,KAAK,GAAG,MAAM,CAAC,MAAM,GAAG,GAAG,CAAC,CAAC,CAAC,OAAO,GAAG,OAAO,MAAM,CAAC,MAAM,QAAQ,CAAC,CAAC,CAAC,EAAE,CAAC;IAChF,OAAO,GAAG,IAAI,GAAG,KAAK,KAAK,OAAO,EAAE,CAAC;AACvC,CAAC"}

package/dist/core/sense/ui-map-resolve.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Shared resolve + gate + dispatch-plan for el_NN element refs on
+ * invoke_element / set_field_value. Pure (no platform calls) — the caller
+ * passes the live active window so this stays unit-testable. See the Part 2
+ * spec section 5.
+ */
+import type { UIElement, Bounds } from './ui-map-types';
+import type { UIMapHolder } from './ui-map-holder';
+/** Below this, an el_NN ref is too uncertain to act on. */
+export declare const REF_MIN_CONFIDENCE = 0.5;
+export type RefIntent = 'click' | 'fill';
+interface ActiveWindow {
+    processId: number;
+    processName: string;
+    title: string;
+    bounds: {
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+    };
+}
+export type RefPlan = {
+    ok: true;
+    via: 'name';
+    name: string;
+    element: UIElement;
+} | {
+    ok: true;
+    via: 'bounds';
+    bounds: Bounds;
+    element: UIElement;
+} | {
+    ok: false;
+    error: string;
+};
+export declare function resolveRef(ref: {
+    element_id?: string;
+    snapshot_id?: string;
+}, holder: UIMapHolder | undefined, now: number, intent: RefIntent, activeWindow: ActiveWindow | null): RefPlan;
+export {};

package/dist/core/sense/ui-map-resolve.js

@@ -0,0 +1,59 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.REF_MIN_CONFIDENCE = void 0;
+exports.resolveRef = resolveRef;
+/** Below this, an el_NN ref is too uncertain to act on. */
+exports.REF_MIN_CONFIDENCE = 0.5;
+function boundsInside(b, w) {
+    const [x, y, bw, bh] = b;
+    return x >= w.x && y >= w.y && x + bw <= w.x + w.width && y + bh <= w.y + w.height;
+}
+function resolveRef(ref, holder, now, intent, activeWindow) {
+    const hasId = typeof ref.element_id === 'string' && ref.element_id !== '';
+    const hasSnap = typeof ref.snapshot_id === 'string' && ref.snapshot_id !== '';
+    if (hasId !== hasSnap)
+        return { ok: false, error: 'provide element_id and snapshot_id together, or neither (use name)' };
+    if (!holder)
+        return { ok: false, error: 'no UIMap holder on this context' };
+    const r = holder.resolve(ref.snapshot_id, now);
+    if (!r.ok) {
+        const msg = r.reason === 'unknown' ? `unknown snapshot ${ref.snapshot_id} — call compile_ui first`
+            : r.reason === 'expired' ? 'snapshot expired — call compile_ui again'
+                : 'stale snapshot — the screen changed; call compile_ui again';
+        return { ok: false, error: msg };
+    }
+    const map = r.map;
+    const element = map.elements.find(e => e.id === ref.element_id);
+    if (!element)
+        return { ok: false, error: `element ${ref.element_id} not in snapshot ${ref.snapshot_id}` };
+    if (element.confidence < exports.REF_MIN_CONFIDENCE)
+        return { ok: false, error: `element ${element.id} confidence too low to act on — recompile / re-find` };
+    if (intent === 'click' && (!element.actionable || element.state?.enabled === false))
+        return { ok: false, error: `element ${element.id} is not actionable (disabled?)` };
+    if (intent === 'fill' && !element.editable)
+        return { ok: false, error: `element ${element.id} is not editable` };
+    // The map's window must STILL be the active window — for BOTH dispatch paths
+    // (a unique name is no safer than bounds if the window changed under us).
+    if (!activeWindow)
+        return { ok: false, error: 'cannot verify active window — call compile_ui again' };
+    // A zero/empty pid means the adapter couldn't read it (macOS unixId read can
+    // fail → normalizeWindow defaults to 0; Windows shares the `?? 0` pattern), so
+    // treat it as UNKNOWN and fall back to the title instead of comparing against a
+    // bogus 0 — which would spuriously reject (or, if both sides are 0, falsely
+    // accept) (audit 2026-06-11, M6).
+    const pidKnown = map.process_id !== undefined && map.process_id !== '' && map.process_id !== '0';
+    const sameWin = pidKnown
+        ? String(activeWindow.processId) === map.process_id // pid is authoritative when known
+        : activeWindow.title === map.window_title; // fall back to title only when pid unknown
+    if (!sameWin)
+        return { ok: false, error: 'window changed since compile — call compile_ui again' };
+    // Prefer the reliable a11y path when the name is unique; else disambiguate by bounds.
+    const name = element.normalized_text ?? '';
+    const uniqueName = name !== '' && map.elements.filter(e => e.normalized_text === name).length === 1;
+    if (uniqueName)
+        return { ok: true, via: 'name', name, element };
+    if (!boundsInside(element.bounds, activeWindow.bounds))
+        return { ok: false, error: 'element is off the active window — call compile_ui again' };
+    return { ok: true, via: 'bounds', bounds: element.bounds, element };
+}
+//# sourceMappingURL=ui-map-resolve.js.map

package/dist/core/sense/ui-map-resolve.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ui-map-resolve.js","sourceRoot":"","sources":["../../../src/core/sense/ui-map-resolve.ts"],"names":[],"mappings":"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"}

package/dist/core/sense/ui-map-types.d.ts

@@ -0,0 +1,66 @@
+/**
+ * UI State Compiler (Layer A) data model. See
+ * docs/superpowers/specs/2026-06-07-ui-state-compiler-design.md.
+ */
+import type { Platform } from './types';
+/** Perception sources, ordered cheap → expensive. Array (not enum) for runtime checks. */
+export declare const SOURCES: readonly ["window", "a11y", "ocr", "vision", "dom", "cursor"];
+export type Source = typeof SOURCES[number];
+/** Normalized UI roles. Array (not enum) for runtime validation via ROLES.includes(). */
+export declare const ROLES: readonly ["button", "input", "text", "link", "checkbox", "list", "listitem", "tab", "image", "unknown"];
+export type Role = typeof ROLES[number];
+export type Bounds = [number, number, number, number];
+export interface ElementRef {
+    id: string;
+    role: Role;
+    normalized_text?: string;
+}
+export interface UIElement {
+    id: string;
+    role: Role;
+    text?: string;
+    normalized_text?: string;
+    bounds: Bounds;
+    confidence: number;
+    sources: Source[];
+    actionable?: boolean;
+    clickable?: boolean;
+    editable?: boolean;
+    state?: {
+        focused?: boolean;
+        enabled?: boolean;
+        selected?: boolean;
+        expanded?: boolean;
+        value?: string;
+    };
+}
+export interface UIMap {
+    snapshot_id: string;
+    platform: Platform;
+    active_app: string;
+    process_id?: string;
+    window_id?: string;
+    window_title: string;
+    window_bounds: Bounds;
+    display_id?: string;
+    coordinate_space: 'screen';
+    scale_factor?: number;
+    compiled_at: string;
+    sources_used: Source[];
+    elements: UIElement[];
+    anchors: {
+        focused?: ElementRef;
+        primary_action_candidate?: ElementRef;
+    };
+    truncation?: {
+        total_elements: number;
+        returned_elements: number;
+    };
+}
+export type MaxCost = 'cheap' | 'ocr_ok' | 'vision_ok';
+/** Caller knobs for compileUIMap. */
+export interface CompileHints {
+    purpose?: 'general' | 'find_text' | 'act';
+    target_text?: string;
+    max_cost?: MaxCost;
+}

package/dist/core/sense/ui-map-types.js

@@ -0,0 +1,11 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ROLES = exports.SOURCES = void 0;
+/** Perception sources, ordered cheap → expensive. Array (not enum) for runtime checks. */
+exports.SOURCES = ['window', 'a11y', 'ocr', 'vision', 'dom', 'cursor'];
+/** Normalized UI roles. Array (not enum) for runtime validation via ROLES.includes(). */
+exports.ROLES = [
+    'button', 'input', 'text', 'link', 'checkbox',
+    'list', 'listitem', 'tab', 'image', 'unknown',
+];
+//# sourceMappingURL=ui-map-types.js.map

package/dist/core/sense/ui-map-types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ui-map-types.js","sourceRoot":"","sources":["../../../src/core/sense/ui-map-types.ts"],"names":[],"mappings":";;;AAMA,0FAA0F;AAC7E,QAAA,OAAO,GAAG,CAAC,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,QAAQ,EAAE,KAAK,EAAE,QAAQ,CAAU,CAAC;AAGrF,yFAAyF;AAC5E,QAAA,KAAK,GAAG;IACnB,QAAQ,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,UAAU;IAC7C,MAAM,EAAE,UAAU,EAAE,KAAK,EAAE,OAAO,EAAE,SAAS;CACrC,CAAC"}

package/dist/core/sense/ui-map.d.ts

@@ -0,0 +1,29 @@
+/**
+ * UI State Compiler (Layer A). Fuses a11y + OCR + (lazy) vision + window/display
+ * metadata into one UIMap. Pure orchestration over injected sources so it is
+ * unit-testable with no real UIA/OCR. See the design spec
+ * docs/superpowers/specs/2026-06-07-ui-state-compiler-design.md.
+ */
+import type { PlatformAdapter, ScreenshotResult } from '../../platform/types';
+import type { Snapshot } from './types';
+import type { OcrResult } from '../../platform/ocr-engine';
+import type { UIMap, CompileHints } from './ui-map-types';
+export interface CompileDeps {
+    /** a11y spine — defaults to captureSnapshot(adapter) in production. */
+    captureSnapshot: () => Promise<Snapshot>;
+    /** OCR puller — defaults to () => new OcrEngine().recognizeScreen(). */
+    ocr: () => Promise<OcrResult>;
+    /** Vision puller — defaults to adapter.screenshot(). */
+    vision: () => Promise<ScreenshotResult>;
+    getScreenSize: PlatformAdapter['getScreenSize'];
+    getFocusedElement: PlatformAdapter['getFocusedElement'];
+    /** Previous turn's anchors, for cross-turn continuity (optional). */
+    prevAnchors?: UIMap['anchors'];
+    /** Caller-passed clock + id (pure: no Date.now in this module). */
+    now: number;
+    snapshotId: string;
+}
+export declare function compileUIMap(deps: CompileDeps, hints: CompileHints): Promise<UIMap>;
+/** Production deps wired to a real adapter. now/snapshotId are caller-passed
+ *  (the agent loop owns the clock + the obs_N counter). */
+export declare function defaultCompileDeps(adapter: PlatformAdapter, now: number, snapshotId: string, prevAnchors?: UIMap['anchors']): CompileDeps;