screenhand 0.3.2 → 0.3.4

package/dist/src/state/app-map.js

@@ -80,6 +80,31 @@ function redactStrings(strings) {
  * Atomic writes via writeFileAtomicSync + readJsonWithRecovery for
  * crash safety.
  */
+// Max page:: zones per app (separate from maxZonesPerApp to prevent title explosion)
+const MAX_PAGE_ZONES = 20;
+/**
+ * Normalize dynamic page context strings to prevent zone explosion.
+ * Collapses UUIDs, timestamps, numeric IDs, file extensions, and hashes
+ * into stable placeholders so similar pages share a zone.
+ */
+function normalizePageContext(ctx) {
+    return ctx
+        // UUIDs: 8-4-4-4-12 hex
+        .replace(/[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}/gi, "<id>")
+        // Long hex hashes (8+ chars)
+        .replace(/\b[0-9a-f]{8,}\b/gi, "<hash>")
+        // ISO timestamps
+        .replace(/\d{4}-\d{2}-\d{2}[T ]\d{2}:\d{2}(:\d{2})?/g, "<time>")
+        // Date-like patterns
+        .replace(/\d{4}[-/]\d{2}[-/]\d{2}/g, "<date>")
+        // Standalone numeric IDs (3+ digits)
+        .replace(/\b\d{3,}\b/g, "<num>")
+        // File extensions at the end
+        .replace(/\.\w{1,5}$/, "")
+        // Collapse whitespace
+        .replace(/\s+/g, " ")
+        .trim();
+}
 export class AppMap {
     config;
     cache = new Map();
@@ -87,6 +112,8 @@ export class AppMap {
     saveTimer = null;
     /** Cache of auto-generated ladders (from reference files) */
     generatedLadderCache = new Map();
+    /** Wire #11: TopologyPolicy reference for Bayesian edge scoring */
+    topologyPolicy = null;
     constructor(config) {
         this.config = {
             ...DEFAULT_APP_MAP_CONFIG,
@@ -98,6 +125,10 @@ export class AppMap {
     init() {
         fs.mkdirSync(this.config.mapsDir, { recursive: true });
     }
+    /** Wire #11: Connect TopologyPolicy for Bayesian edge scoring */
+    setTopologyPolicy(tp) {
+        this.topologyPolicy = tp;
+    }
     // ── Load / Save ───────────────────────────────────────────────────
     load(bundleId) {
         const cached = this.cache.get(bundleId);
@@ -285,6 +316,131 @@ export class AppMap {
         this.save(data);
         return data;
     }
+    /**
+     * Wire #12: L6→L7 — Bootstrap pre-built zones from a MenuScanner result.
+     * Creates toolbar zone + per-menu sub-zones so new apps start with structure.
+     * Only bootstraps if no map exists yet — never overwrites existing data.
+     * Capped at 10 zones to prevent menu-heavy apps from flooding.
+     */
+    bootstrapFromMenuScan(bundleId, appName, scanResult) {
+        // Only bootstrap if no menu_bar zone exists yet — perception may have
+        // auto-created other zones, but menu structure is separate
+        const existing = this.load(bundleId);
+        if (existing?.zones["menu_bar"])
+            return false;
+        const data = existing ?? this.createEmpty(bundleId, appName);
+        const now = new Date().toISOString();
+        // Filter out Apple menu, empty titles, and disabled items
+        const topMenus = scanResult.menuTree.filter((m) => m.title && m.title !== "Apple" && m.enabled !== false);
+        let zoneCount = 0;
+        // Sanitize a menu title for use as zone key or element label
+        const sanitize = (title) => redactPII(title)
+            .replace(/[\x00-\x1f\x7f-\x9f\u200b-\u200f\u202a-\u202e\ufeff]/g, "")
+            .slice(0, 100);
+        // 1. Create toolbar zone with top-level menu names as elements
+        const toolbarElements = [];
+        for (let i = 0; i < topMenus.length && i < 15; i++) {
+            const menu = topMenus[i];
+            const safeTitle = sanitize(menu.title);
+            if (!safeTitle)
+                continue;
+            toolbarElements.push({
+                label: safeTitle,
+                relativeX: Math.min(0.95, 0.02 + i * 0.08),
+                relativeY: 0.02,
+                anchor: "top-left",
+                ocrBackup: safeTitle,
+                successCount: 0,
+                failCount: 0,
+                lastInteracted: now,
+                sessionsSinceUse: 0,
+            });
+        }
+        data.zones["menu_bar"] = {
+            relativePosition: { top: 0, left: 0, width: 1, height: 0.04 },
+            type: "toolbar",
+            elements: toolbarElements,
+            verified: false,
+            lastSeen: now,
+        };
+        zoneCount++;
+        // 2. Create per-menu sub-zones with child items as elements
+        const seenZoneKeys = new Set();
+        for (let i = 0; i < topMenus.length && zoneCount < 10; i++) {
+            const menu = topMenus[i];
+            if (!menu.children || menu.children.length === 0)
+                continue;
+            // Filter disabled children
+            const enabledChildren = menu.children.filter((c) => c.title && c.enabled !== false);
+            if (enabledChildren.length === 0)
+                continue;
+            const menuElements = [];
+            for (let j = 0; j < enabledChildren.length && j < 20; j++) {
+                const child = enabledChildren[j];
+                const safeChildTitle = sanitize(child.title);
+                if (!safeChildTitle)
+                    continue;
+                menuElements.push({
+                    label: safeChildTitle,
+                    relativeX: Math.min(0.95, 0.02 + i * 0.08),
+                    relativeY: Math.min(0.95, 0.06 + j * 0.03),
+                    anchor: "top-left",
+                    ocrBackup: safeChildTitle,
+                    successCount: 0,
+                    failCount: 0,
+                    lastInteracted: now,
+                    sessionsSinceUse: 0,
+                });
+            }
+            // Sanitize zone key and deduplicate
+            const baseKey = `menu::${sanitize(menu.title).toLowerCase().replace(/\s+/g, "_")}`;
+            let zoneKey = baseKey;
+            if (seenZoneKeys.has(zoneKey)) {
+                zoneKey = `${baseKey}_${i}`;
+            }
+            seenZoneKeys.add(zoneKey);
+            // Skip if zone already exists (perception may have built it with verified data)
+            if (data.zones[zoneKey]) {
+                seenZoneKeys.add(zoneKey);
+                continue;
+            }
+            data.zones[zoneKey] = {
+                relativePosition: {
+                    top: 0.04,
+                    left: Math.min(0.9, i * 0.08),
+                    width: 0.15,
+                    height: Math.min(0.5, enabledChildren.length * 0.03 + 0.02),
+                },
+                type: "menu",
+                elements: menuElements,
+                verified: false,
+                lastSeen: now,
+            };
+            zoneCount++;
+        }
+        // 3. Record initial feature mastery at depth 2 for menu-derived features
+        const featureMap = {
+            file: "file_management", edit: "editing", view: "view_control",
+            window: "window_management", help: "help_usage",
+        };
+        for (const menu of topMenus) {
+            const featureId = featureMap[menu.title.toLowerCase()];
+            if (featureId && !data.featureMastery[featureId]) {
+                data.featureMastery[featureId] = {
+                    depth: 2,
+                    confidence: 0.3,
+                    repeatCount: 0,
+                    workflowCount: 0,
+                    healingCount: 0,
+                    failCount: 0,
+                    lastSeen: now,
+                    lastVerified: null,
+                };
+            }
+        }
+        this.save(data);
+        return true;
+    }
     // ── Zone Operations ───────────────────────────────────────────────
     addZone(bundleId, zoneKey, zone) {
         const data = this.ensureLoaded(bundleId);
@@ -417,7 +573,7 @@ export class AppMap {
         let zone = data.zones[zoneKey];
         if (!zone && zoneKey === "auto") {
             const targetZoneKey = pageContext
-                ? `page::${pageContext}`
+                ? `page::${normalizePageContext(pageContext)}`
                 : "auto_discovered";
             // When page context is known, prefer the page-specific zone
             // This ensures elements migrate OUT of auto_discovered into proper page zones
@@ -428,9 +584,9 @@ export class AppMap {
                     zone = pageZone;
                 }
                 else {
-                    // Element might be in auto_discovered — that's OK, we'll create a new
-                    // entry in the page zone to gradually migrate elements to proper zones
-                    if (Object.keys(data.zones).length >= this.config.maxZonesPerApp) {
+                    // Check page:: zone count separately to prevent title explosion
+                    const pageZoneCount = Object.keys(data.zones).filter((k) => k.startsWith("page::")).length;
+                    if (Object.keys(data.zones).length >= this.config.maxZonesPerApp || pageZoneCount >= MAX_PAGE_ZONES) {
                         // At zone limit — fall back to auto_discovered
                         zone = data.zones["auto_discovered"];
                         if (!zone) {
@@ -491,8 +647,8 @@ export class AppMap {
                 return;
             el = {
                 label,
-                relativeX: 0,
-                relativeY: 0,
+                relativeX: -1,
+                relativeY: -1,
                 anchor: "top-left",
                 ocrBackup: label,
                 successCount: 0,
@@ -620,16 +776,17 @@ export class AppMap {
     }
     /**
      * Find the contract for an element across all zones.
-     * Returns the first matching contract (by elementLabel), or null.
+     * When action is provided, only returns contracts matching that action type.
+     * Falls back to any-action match when action is omitted.
      */
-    getContract(bundleId, elementLabel) {
+    getContract(bundleId, elementLabel, action) {
         const data = this.ensureLoaded(bundleId);
         if (!data)
             return null;
         for (const [zoneKey, zone] of Object.entries(data.zones)) {
             if (!zone.contracts)
                 continue;
-            const contract = zone.contracts.find((c) => c.elementLabel === elementLabel);
+            const contract = zone.contracts.find((c) => c.elementLabel === elementLabel && (action == null || c.action === action));
             if (contract)
                 return { zone: zoneKey, contract };
         }
@@ -750,12 +907,28 @@ export class AppMap {
         // V2: Redact PII from page names before persistence
         fromPage = redactPII(fromPage);
         toPage = redactPII(toPage);
-        // Re-check after redaction in case both pages redact to the same string
-        if (fromPage === toPage)
+        // Sanitize: strip control chars, cap length to prevent zone key explosion
+        const sanitizeTitle = (t) => t.replace(/[\x00-\x1f\x7f-\x9f\u200b-\u200f\u202a-\u202e\ufeff]/g, "").slice(0, 100);
+        fromPage = sanitizeTitle(fromPage);
+        toPage = sanitizeTitle(toPage);
+        // Re-check after sanitization in case both pages redact/truncate to the same string
+        if (!fromPage || !toPage || fromPage === toPage)
             return;
         const data = this.ensureLoaded(bundleId);
         if (!data)
             return;
+        // Handle initial page entry (first page after app launch)
+        if (fromPage === "__initial__") {
+            // Just ensure the initial page node exists — no edge from __initial__
+            if (!data.navigationGraph.nodes[toPage]) {
+                data.navigationGraph.nodes[toPage] = {
+                    type: "window",
+                    description: toPage,
+                };
+                this.save(data);
+            }
+            return;
+        }
         // Find existing edge with same from/action/to
         const existing = data.navigationGraph.edges.find((e) => e.from === fromPage && e.action === action && e.to === toPage);
         if (existing) {
@@ -846,8 +1019,41 @@ export class AppMap {
             edge.failCount++;
         }
         edge.lastUsed = new Date().toISOString();
+        // Wire #11: stamp Bayesian score from TopologyPolicy if available
+        if (this.topologyPolicy) {
+            const entries = this.topologyPolicy.query(bundleId, from);
+            const match = entries.find((e) => e.action === action && e.toNode === to);
+            if (match) {
+                edge.topologyScore = match.score;
+            }
+        }
         this.save(data);
     }
+    /**
+     * Wire #11: Get reliability score for a nav edge.
+     * Prefers TopologyPolicy Bayesian score when available,
+     * falls back to simple success ratio from AppMap edge data.
+     */
+    getEdgeScore(bundleId, from, action, to) {
+        // Prefer live TopologyPolicy score
+        if (this.topologyPolicy) {
+            const entries = this.topologyPolicy.query(bundleId, from);
+            const match = entries.find((e) => e.action === action && e.toNode === to);
+            if (match)
+                return match.score;
+        }
+        // Fallback to AppMap edge data
+        const data = this.load(bundleId);
+        if (!data)
+            return null;
+        const edge = data.navigationGraph.edges.find((e) => e.from === from && e.action === action && e.to === to);
+        if (!edge)
+            return null;
+        if (edge.topologyScore !== undefined)
+            return edge.topologyScore;
+        const total = edge.successCount + edge.failCount;
+        return total > 0 ? edge.successCount / total : null;
+    }
     // ── Hierarchy ────────────────────────────────────────────────────
     /**
      * Record a parent/child containment relationship within a zone.
@@ -1082,7 +1288,7 @@ export class AppMap {
     }
     resolvePosition(bundleId, label, windowBounds) {
         const found = this.findElement(bundleId, label);
-        if (!found || found.element.relativeX === 0 && found.element.relativeY === 0)
+        if (!found || (found.element.relativeX === -1 && found.element.relativeY === -1))
             return null;
         return {
             x: Math.round(windowBounds.x + found.element.relativeX * windowBounds.width),
@@ -1299,6 +1505,7 @@ export class AppMap {
      * Recompute tier and confidence from current feature mastery state.
      */
     recomputeTier(data) {
+        const prevTier = data.masteryLevel;
         const metrics = this.computeMetrics(data);
         data.masteryMetrics = metrics;
         data.confidence = this.computeConfidence(data);
@@ -1307,7 +1514,16 @@ export class AppMap {
         const factors = this.computeRatingFactors(data);
         data.ratingFactors = factors;
         data.rating = this.computeRating(factors);
-        data.lastValidated = new Date().toISOString();
+        // Use lastRecomputed — lastValidated is reserved for perception coordinator
+        data.lastRecomputed = new Date().toISOString();
+        // Urgent flush when mastery tier changes — write ONLY this app immediately
+        if (prevTier !== data.masteryLevel) {
+            try {
+                writeFileAtomicSync(this.filePath(data.app), JSON.stringify(data, null, 2) + "\n");
+                this.dirty.delete(data.app); // Only remove the one we just wrote
+            }
+            catch { /* non-fatal — will be picked up by next debounced save */ }
+        }
     }
     refreshMastery(bundleId) {
         const data = this.ensureLoaded(bundleId);
@@ -1511,8 +1727,9 @@ export class AppMap {
                 }
             }
         }
-        // Remove features that no longer exist in builtin (if using builtin ladder)
-        if (builtinIds.size > 0) {
+        // Remove features that no longer exist in builtin (only if app has a handcrafted ladder)
+        const hasBuiltinLadder = !!BUILTIN_LADDERS[data.app];
+        if (hasBuiltinLadder && builtinIds.size > 0) {
             // Migrate renamed features: old ID → closest new ID by mastery data
             const OLD_TO_NEW = {
                 roles_notifications: "roles_permissions",
@@ -1567,7 +1784,7 @@ export class AppMap {
             return;
         data.version = newVersion;
         data.confidence *= this.config.versionDecayFactor;
-        data.masteryLevel = this.computeMasteryLevel(data.confidence);
+        this.recomputeTier(data);
         // Unverify all edges on version change
         for (const edge of data.navigationGraph.edges) {
             edge.verified = false;
@@ -1579,7 +1796,7 @@ export class AppMap {
         if (!data)
             return;
         data.confidence = this.computeConfidence(data);
-        data.masteryLevel = this.computeMasteryLevel(data.confidence);
+        this.recomputeTier(data);
         this.save(data);
     }
     // ── Pruning ───────────────────────────────────────────────────────
@@ -1940,6 +2157,79 @@ export class AppMap {
         }
         return maxTypical;
     }
+    /**
+     * Wire #15: Check if an element is well-known and recently verified.
+     * Returns true if the element has 3+ successes and was interacted with
+     * within maxAgeMs (default 5 minutes). Used by Executor to skip verify.
+     */
+    isElementVerified(bundleId, label, maxAgeMs = 300_000) {
+        const data = this.ensureLoaded(bundleId);
+        if (!data)
+            return false;
+        const now = Date.now();
+        for (const zone of Object.values(data.zones)) {
+            for (const el of zone.elements) {
+                if (el.label === label && el.successCount >= 3) {
+                    const lastTime = new Date(el.lastInteracted).getTime();
+                    const elapsed = now - lastTime;
+                    // Guard: elapsed must be non-negative (rejects future dates from clock skew)
+                    // and within the staleness window
+                    if (elapsed >= 0 && elapsed <= maxAgeMs) {
+                        return true;
+                    }
+                }
+            }
+        }
+        return false;
+    }
+    /**
+     * Wire F9: Import element knowledge from a community playbook.
+     * Creates the app entry if it doesn't exist, then records each step's
+     * target as a successful element interaction.
+     */
+    importFromPlaybook(bundleId, appName, steps) {
+        let data = this.ensureLoaded(bundleId);
+        if (!data) {
+            data = this.createEmpty(bundleId, appName);
+            this.save(data); // Persist to cache + disk so recordElementOutcome can find it
+        }
+        for (const step of steps) {
+            const label = (step.params?.text ?? step.params?.title ?? step.params?.target ?? step.description);
+            if (!label || typeof label !== "string")
+                continue;
+            this.recordElementOutcome(bundleId, "auto", label, true);
+        }
+    }
+    /**
+     * List all known app bundleIds by scanning the maps directory.
+     * Returns bundleIds derived from filenames (excludes .ladder.json files).
+     */
+    listKnownApps() {
+        try {
+            const dirents = fs.readdirSync(this.config.mapsDir, { withFileTypes: true });
+            const bundleIds = [];
+            for (const dirent of dirents) {
+                // Skip symlinks and directories — only read regular files
+                if (!dirent.isFile())
+                    continue;
+                const file = dirent.name;
+                if (file.endsWith(".json") && !file.endsWith(".ladder.json")) {
+                    const stem = file.slice(0, -5);
+                    // Load the file and use data.app (canonical bundleId) instead of
+                    // filename stem, which may differ from the original bundleId due
+                    // to filesystem sanitization in filePath()
+                    const data = this.ensureLoaded(stem);
+                    if (data?.app) {
+                        bundleIds.push(data.app);
+                    }
+                }
+            }
+            return bundleIds;
+        }
+        catch {
+            return [];
+        }
+    }
     // ── Internals ─────────────────────────────────────────────────────
     ensureLoaded(bundleId) {
         return this.cache.get(bundleId) ?? this.load(bundleId);

package/dist/src/util/atomic-write.js

@@ -36,14 +36,22 @@ export function writeFileAtomicSync(filePath, data) {
     try {
         fs.writeFileSync(tmp, data, { mode: 0o644 });
         // Back up current file before overwriting (ignore if it doesn't exist yet)
-        // V3: Check for symlinks before backup to prevent data exfiltration
+        // V4: Check for symlinks on BOTH primary and .bak to prevent data exfiltration
         try {
             const stat = fs.lstatSync(filePath);
             if (stat.isSymbolicLink()) {
-                // Target is a symlink — skip backup and remove the symlink before writing
+                // Primary is a symlink — remove it before writing
                 fs.unlinkSync(filePath);
             }
             else {
+                // Check .bak target for symlinks before copying
+                try {
+                    const bakStat = fs.lstatSync(filePath + ".bak");
+                    if (bakStat.isSymbolicLink()) {
+                        fs.unlinkSync(filePath + ".bak"); // Remove symlink, then copy
+                    }
+                }
+                catch { /* .bak doesn't exist yet — fine */ }
                 fs.copyFileSync(filePath, filePath + ".bak");
             }
         }
@@ -57,7 +65,10 @@ export function writeFileAtomicSync(filePath, data) {
         try {
             fs.unlinkSync(tmp);
         }
-        catch { /* ignore */ }
+        catch {
+            // Temp file could not be cleaned up — log so it can be investigated
+            console.error(`[atomic-write] WARN: Failed to clean up temp file: ${tmp}`);
+        }
         throw err;
     }
 }
@@ -78,13 +89,20 @@ export function writeFileAtomic(filePath, data, callback) {
             return;
         }
         // Back up current file (best-effort, sync is fine for a copy)
-        // V3: Check for symlinks before backup to prevent data exfiltration
+        // V4: Check for symlinks on BOTH primary and .bak
         try {
             const stat = fs.lstatSync(filePath);
             if (stat.isSymbolicLink()) {
                 fs.unlinkSync(filePath);
             }
             else {
+                try {
+                    const bakStat = fs.lstatSync(filePath + ".bak");
+                    if (bakStat.isSymbolicLink()) {
+                        fs.unlinkSync(filePath + ".bak");
+                    }
+                }
+                catch { /* .bak doesn't exist — fine */ }
                 fs.copyFileSync(filePath, filePath + ".bak");
             }
         }
@@ -113,6 +131,7 @@ export function readJsonWithRecovery(filePath) {
     // Primary is missing or corrupt — try backup
     const backup = tryParseJsonFile(filePath + ".bak");
     if (backup !== null) {
+        console.error(`[atomic-write] WARN: Primary file corrupt, recovered from backup: ${filePath}`);
         // Restore backup as primary so next read is fast
         try {
             fs.copyFileSync(filePath + ".bak", filePath);
@@ -120,6 +139,8 @@ export function readJsonWithRecovery(filePath) {
         catch { /* ignore */ }
         return backup;
     }
+    // Both primary and backup are missing or corrupt — log warning so data loss is visible
+    console.error(`[atomic-write] WARN: Both primary and backup corrupt for ${filePath}, returning null`);
     return null;
 }
 function tryParseJsonFile(filePath) {

package/dist-references/reddit.json

@@ -52,7 +52,7 @@
       "downvote": "shreddit-post >> shadowRoot >> button:has-text('Downvote')",
       "comments": "shreddit-post >> shadowRoot >> button:has-text('Go to comments')",
       "share": "shreddit-post >> shadowRoot >> button:has-text('Share')",
-      "note": "These selectors are conceptual — use JS to access shadow roots: post.shadowRoot.querySelectorAll('button')"
+      "_note": "These selectors are conceptual — use JS to access shadow roots: post.shadowRoot.querySelectorAll('button')"
     },
     "comment": {
       "composer": "shreddit-composer",
@@ -71,7 +71,7 @@
       "type_text": "[type='TEXT']",
       "type_link": "[type='LINK']",
       "type_image": "[type='IMAGE']",
-      "note": "Title textarea is inside shadow root of faceplate-textarea-input — use native value setter via JS"
+      "_note": "Title textarea is inside shadow root of faceplate-textarea-input — use native value setter via JS"
     },
     "subreddit": {
       "header": "shreddit-subreddit-header",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "screenhand",
-  "version": "0.3.2",
+  "version": "0.3.4",
   "mcpName": "io.github.manushi4/screenhand",
   "description": "Give AI eyes and hands on your desktop. ScreenHand is an open-source MCP server that lets Claude and other AI agents see your screen, click buttons, type text, and control any app on macOS and Windows.",
   "homepage": "https://screenhand.com",