screenhand 0.3.9 → 0.4.1

package/dist/src/playbook/mcp-recorder.js

@@ -28,18 +28,30 @@ const SKIP_TOOLS = new Set([
     "codex_monitor_start", "codex_monitor_status", "codex_monitor_add_task",
     "codex_monitor_tasks", "codex_monitor_assign_now", "codex_monitor_stop",
     "platform_learn", "platform_explore",
+    // Observation tools — not steps
+    "read_with_fallback", "locate_with_fallback", "execution_plan",
+    "browser_stealth",
+    // Observer/orchestrator lifecycle — not steps
+    "observer_start", "observer_stop", "observer_status", "observer_ocr_roi",
+    "orchestrator_start", "orchestrator_stop", "orchestrator_submit", "orchestrator_status",
+    // Ingestion/discovery — learning, not steps
+    "scan_menu_bar", "ingest_documentation", "ingest_tutorial",
+    "discover_features", "coverage_report",
 ]);
 /** Map MCP tool names to PlaybookStep actions */
 function mapToolToAction(toolName) {
     switch (toolName) {
-        case "browser_navigate": return "navigate";
+        case "browser_navigate":
+        case "browser_open": return "navigate";
         case "click":
         case "click_text":
         case "browser_click":
+        case "browser_human_click":
         case "click_with_fallback":
         case "ui_press": return "press";
         case "type_text":
         case "browser_type":
+        case "browser_fill_form":
         case "type_with_fallback": return "type_into";
         case "key": return "key";
         case "menu_click": return "menu_click";
@@ -50,6 +62,9 @@ function mapToolToAction(toolName) {
         case "screenshot_file": return "screenshot";
         case "browser_wait":
         case "wait_for_state": return "wait";
+        case "applescript": return "applescript";
+        case "ui_set_value": return "type_into";
+        case "select_with_fallback": return "press";
         case "focus":
         case "launch": return null; // useful context but not a step
         case "drag": return null; // drag is complex, skip for now
@@ -108,6 +123,10 @@ function buildStep(toolName, params, success) {
             step.ms = Number(params.timeout ?? params.ms ?? params.timeoutMs ?? 1000);
             step.description = `Wait ${step.ms}ms`;
             break;
+        case "applescript":
+            step.script = String(params.script ?? "");
+            step.description = `AppleScript: ${step.script.substring(0, 80)}${step.script.length > 80 ? "..." : ""}`;
+            break;
     }
     if (!success) {
         step.optional = true;
@@ -168,6 +187,7 @@ export class McpPlaybookRecorder {
             ...(typeof s.target === "string" ? { target: redactPII(s.target) } : {}),
             ...(s.url ? { url: redactPII(s.url) } : {}),
             ...(s.code ? { code: redactPII(s.code) } : {}),
+            ...(s.script ? { script: redactPII(s.script) } : {}),
             ...(s.description ? { description: redactPII(s.description) } : {}),
         }));
         const playbook = {

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

@@ -11,59 +11,59 @@ import { generateLadderFromReference } from "./ladder-generator.js";
 // Define what real users do at each level. Used to measure honest mastery.
 const BUILTIN_LADDERS = {
     "com.hnc.Discord": [
-        // ── Beginner: basic consumer actions (weight 1) ──
-        { id: "browse_channels", description: "Join servers and browse channels", level: "beginner", weight: 1, critical: false },
-        { id: "send_message", description: "Send messages, replies, emojis, and reactions", level: "beginner", weight: 1, critical: false },
-        { id: "direct_messages", description: "Direct messages and group chats", level: "beginner", weight: 1, critical: false },
-        { id: "voice_video", description: "Voice channels, video calls, and screen share", level: "beginner", weight: 1, critical: false },
-        // ── Pro: operational features (weight 2) ──
-        { id: "threads_forums", description: "Create and manage threads and forum channels", level: "pro", weight: 2, critical: false },
-        { id: "roles_permissions", description: "Configure roles, overrides, inheritance, hidden channels", level: "pro", weight: 2, critical: true },
-        { id: "events_stage", description: "Schedule events, run Stage channels, manage speakers", level: "pro", weight: 2, critical: false },
-        { id: "onboarding_funnel", description: "Build join flows: rules screening, role assignment, starter channels", level: "pro", weight: 2, critical: true },
-        { id: "notification_control", description: "Channel overrides, mention control, suppression settings", level: "pro", weight: 1, critical: false },
-        // ── Expert: system-level features (weight 2-3) ──
-        { id: "moderation_system", description: "Configure AutoMod, mod bots, alert flows, ban appeals, raid defense", level: "expert", weight: 3, critical: true },
-        { id: "bot_ecosystem", description: "Combine bots, slash commands, webhooks into coherent server OS", level: "expert", weight: 3, critical: true },
-        { id: "server_architecture", description: "Design categories, channel taxonomy, permissions, escalation paths", level: "expert", weight: 3, critical: true },
-        { id: "community_growth", description: "Events, role rewards, content loops, announcements, retention mechanics", level: "expert", weight: 2, critical: false },
-        { id: "analytics_health", description: "Track activity patterns, onboarding drop-off, channel usage, retention", level: "expert", weight: 2, critical: true },
-        // ── Grandmaster: mastery-level operations (weight 3) ──
-        { id: "monetization_membership", description: "Premium roles, gated channels, supporter tiers, creator monetization", level: "grandmaster", weight: 2, critical: false },
-        { id: "crisis_handling", description: "Handle raids, harassment, spam, leaks, impersonation, conflicts", level: "grandmaster", weight: 3, critical: true },
-        { id: "cross_platform", description: "Connect Discord with GitHub, Notion, Twitch, Stripe, Zapier, tools", level: "grandmaster", weight: 2, critical: false },
-        { id: "staff_system", description: "Structure mod roles, escalation, internal channels, review processes", level: "grandmaster", weight: 3, critical: true },
-        { id: "brand_culture", description: "Shape tone, rituals, norms, recognition systems, community identity", level: "grandmaster", weight: 2, critical: false },
-        { id: "governance_policy", description: "Define rules, enforcement, appeals, social boundaries that hold up", level: "grandmaster", weight: 3, critical: true },
+        // ── F tier: basic consumer actions (weight 1) ──
+        { id: "browse_channels", description: "Join servers and browse channels", level: "F", weight: 1, critical: false },
+        { id: "send_message", description: "Send messages, replies, emojis, and reactions", level: "F", weight: 1, critical: false },
+        { id: "direct_messages", description: "Direct messages and group chats", level: "F", weight: 1, critical: false },
+        { id: "voice_video", description: "Voice channels, video calls, and screen share", level: "F", weight: 1, critical: false },
+        // ── B tier: operational features (weight 2) ──
+        { id: "threads_forums", description: "Create and manage threads and forum channels", level: "B", weight: 2, critical: false },
+        { id: "roles_permissions", description: "Configure roles, overrides, inheritance, hidden channels", level: "B", weight: 2, critical: true },
+        { id: "events_stage", description: "Schedule events, run Stage channels, manage speakers", level: "B", weight: 2, critical: false },
+        { id: "onboarding_funnel", description: "Build join flows: rules screening, role assignment, starter channels", level: "B", weight: 2, critical: true },
+        { id: "notification_control", description: "Channel overrides, mention control, suppression settings", level: "B", weight: 1, critical: false },
+        // ── S tier: system-level features (weight 2-3) ──
+        { id: "moderation_system", description: "Configure AutoMod, mod bots, alert flows, ban appeals, raid defense", level: "S", weight: 3, critical: true },
+        { id: "bot_ecosystem", description: "Combine bots, slash commands, webhooks into coherent server OS", level: "S", weight: 3, critical: true },
+        { id: "server_architecture", description: "Design categories, channel taxonomy, permissions, escalation paths", level: "S", weight: 3, critical: true },
+        { id: "community_growth", description: "Events, role rewards, content loops, announcements, retention mechanics", level: "S", weight: 2, critical: false },
+        { id: "analytics_health", description: "Track activity patterns, onboarding drop-off, channel usage, retention", level: "S", weight: 2, critical: true },
+        // ── SSS tier: grandmaster operations (weight 3) ──
+        { id: "monetization_membership", description: "Premium roles, gated channels, supporter tiers, creator monetization", level: "SSS", weight: 2, critical: false },
+        { id: "crisis_handling", description: "Handle raids, harassment, spam, leaks, impersonation, conflicts", level: "SSS", weight: 3, critical: true },
+        { id: "cross_platform", description: "Connect Discord with GitHub, Notion, Twitch, Stripe, Zapier, tools", level: "SSS", weight: 2, critical: false },
+        { id: "staff_system", description: "Structure mod roles, escalation, internal channels, review processes", level: "SSS", weight: 3, critical: true },
+        { id: "brand_culture", description: "Shape tone, rituals, norms, recognition systems, community identity", level: "SSS", weight: 2, critical: false },
+        { id: "governance_policy", description: "Define rules, enforcement, appeals, social boundaries that hold up", level: "SSS", weight: 3, critical: true },
     ],
     "com.apple.Safari": [
-        { id: "browse_navigate", description: "Open URLs and navigate pages", level: "beginner", weight: 1, critical: false },
-        { id: "tabs_windows", description: "Manage tabs and windows", level: "beginner", weight: 1, critical: false },
-        { id: "bookmarks", description: "Bookmarks and reading list", level: "beginner", weight: 1, critical: false },
-        { id: "history_search", description: "History and search", level: "beginner", weight: 1, critical: false },
-        { id: "tab_groups", description: "Tab groups and profiles", level: "pro", weight: 2, critical: false },
-        { id: "extensions", description: "Install and use extensions", level: "pro", weight: 2, critical: false },
-        { id: "dev_tools", description: "Web Inspector and developer tools", level: "expert", weight: 2, critical: true },
-        { id: "privacy_settings", description: "Privacy, cookies, and content blockers", level: "expert", weight: 2, critical: false },
-        { id: "web_apps", description: "Add to Dock, web apps, notifications", level: "grandmaster", weight: 2, critical: false },
+        { id: "browse_navigate", description: "Open URLs and navigate pages", level: "F", weight: 1, critical: false },
+        { id: "tabs_windows", description: "Manage tabs and windows", level: "F", weight: 1, critical: false },
+        { id: "bookmarks", description: "Bookmarks and reading list", level: "F", weight: 1, critical: false },
+        { id: "history_search", description: "History and search", level: "F", weight: 1, critical: false },
+        { id: "tab_groups", description: "Tab groups and profiles", level: "B", weight: 2, critical: false },
+        { id: "extensions", description: "Install and use extensions", level: "B", weight: 2, critical: false },
+        { id: "dev_tools", description: "Web Inspector and developer tools", level: "S", weight: 2, critical: true },
+        { id: "privacy_settings", description: "Privacy, cookies, and content blockers", level: "S", weight: 2, critical: false },
+        { id: "web_apps", description: "Add to Dock, web apps, notifications", level: "SSS", weight: 2, critical: false },
     ],
     "com.apple.finder": [
-        { id: "browse_files", description: "Browse and open files/folders", level: "beginner", weight: 1, critical: false },
-        { id: "copy_move", description: "Copy, move, rename, delete files", level: "beginner", weight: 1, critical: false },
-        { id: "search", description: "Spotlight and Finder search", level: "beginner", weight: 1, critical: false },
-        { id: "views_sort", description: "Change views, sort, and organize", level: "pro", weight: 2, critical: false },
-        { id: "tags_favorites", description: "Tags, favorites, and sidebar", level: "pro", weight: 2, critical: false },
-        { id: "quick_actions", description: "Quick Look, Quick Actions, and Services", level: "expert", weight: 2, critical: true },
-        { id: "automator_scripts", description: "Automator, terminal, and scripting", level: "grandmaster", weight: 2, critical: false },
+        { id: "browse_files", description: "Browse and open files/folders", level: "F", weight: 1, critical: false },
+        { id: "copy_move", description: "Copy, move, rename, delete files", level: "F", weight: 1, critical: false },
+        { id: "search", description: "Spotlight and Finder search", level: "F", weight: 1, critical: false },
+        { id: "views_sort", description: "Change views, sort, and organize", level: "B", weight: 2, critical: false },
+        { id: "tags_favorites", description: "Tags, favorites, and sidebar", level: "B", weight: 2, critical: false },
+        { id: "quick_actions", description: "Quick Look, Quick Actions, and Services", level: "S", weight: 2, critical: true },
+        { id: "automator_scripts", description: "Automator, terminal, and scripting", level: "SSS", weight: 2, critical: false },
     ],
 };
 /** Generic fallback ladder — used when no builtin AND no reference-generated ladder exists. */
 const GENERIC_LADDER = [
-    { id: "basic_navigation", description: "Open, navigate, and browse the app", level: "beginner", weight: 1, critical: false },
-    { id: "core_action", description: "Perform the app's primary action", level: "beginner", weight: 1, critical: false },
-    { id: "settings", description: "Configure settings and preferences", level: "pro", weight: 2, critical: false },
-    { id: "advanced_features", description: "Use advanced/power-user features", level: "expert", weight: 2, critical: true },
-    { id: "automation", description: "Automate or customize workflows", level: "grandmaster", weight: 3, critical: true },
+    { id: "basic_navigation", description: "Open, navigate, and browse the app", level: "F", weight: 1, critical: false },
+    { id: "core_action", description: "Perform the app's primary action", level: "F", weight: 1, critical: false },
+    { id: "settings", description: "Configure settings and preferences", level: "B", weight: 2, critical: false },
+    { id: "advanced_features", description: "Use advanced/power-user features", level: "S", weight: 2, critical: true },
+    { id: "automation", description: "Automate or customize workflows", level: "SSS", weight: 3, critical: true },
 ];
 /** Redact an array of user-facing strings in place, returning a new array. */
 function redactStrings(strings) {
@@ -289,11 +289,11 @@ export class AppMap {
         if (discoveredCount >= 30)
             return null;
         // Assign level based on tool complexity
-        let level = "beginner";
+        let level = "F";
         if (toolName === "menu_click" || toolName === "key")
-            level = "pro";
+            level = "B";
         if (toolName === "applescript" || toolName === "browser_js")
-            level = "expert";
+            level = "S";
         const feature = {
             id: featureId,
             description: `[auto] ${target}`,
@@ -1435,9 +1435,14 @@ export class AppMap {
         let totalFailures = 0;
         let weightedScore = 0;
         // Tier-scoped critical floor: only check critical features at or below the target tier
-        const tierOrder = ["beginner", "pro", "expert", "grandmaster"];
-        const scopeIdx = tierScope ? tierOrder.indexOf(tierScope) : 3; // default: all tiers
-        const scopedLevels = new Set(tierOrder.slice(0, scopeIdx + 1));
+        // MasteryLevel (deprecated) maps to FeatureTier: beginner→F, pro→B, expert→S, grandmaster→SSS
+        const masteryToFeatureTier = {
+            beginner: "F", pro: "B", expert: "S", grandmaster: "SSS",
+        };
+        const featureTierOrder = ["F", "B", "S", "SSS"];
+        const scopedFeatureTier = tierScope ? masteryToFeatureTier[tierScope] : "SSS";
+        const scopeIdx = featureTierOrder.indexOf(scopedFeatureTier);
+        const scopedLevels = new Set(featureTierOrder.slice(0, scopeIdx + 1));
         let criticalMinDepth = 999;
         let hasScopedCritical = false;
         for (const feature of ladder) {

package/dist/src/state/ladder-generator.js

@@ -1,19 +1,19 @@
 // Copyright (C) 2025 Clazro Technology Private Limited
 // SPDX-License-Identifier: AGPL-3.0-only
-// ── Keyword sets for level assignment ────────────────────────────
-const BEGINNER_KEYWORDS = new Set([
+// ── Keyword sets for tier assignment (F=entry, B=proficient, S=expert, SSS=grandmaster) ──
+const F_KEYWORDS = new Set([
     "navigation", "browse", "basic", "search", "header", "page", "nav", "home",
     "page_header", "quick_find",
 ]);
-const PRO_KEYWORDS = new Set([
+const B_KEYWORDS = new Set([
     "settings", "create", "views", "sort", "filter", "template", "new", "sidebar",
     "create_new", "slash_commands", "notification", "preferences",
 ]);
-const EXPERT_KEYWORDS = new Set([
+const S_KEYWORDS = new Set([
     "database", "admin", "moderation", "permissions", "automation", "advanced",
     "server", "import", "export", "workflow", "security", "form",
 ]);
-const GRANDMASTER_KEYWORDS = new Set([
+const SSS_KEYWORDS = new Set([
     "ai", "api", "integration", "custom", "governance", "crisis", "identity",
     "billing", "orchestrat", "pipeline",
 ]);
@@ -32,8 +32,10 @@ export function generateLadderFromReference(ref) {
     const selectorGroups = ref.selectors ?? {};
     const flows = ref.flows ?? {};
     // Minimum threshold: need at least 2 meaningful selector groups
+    // (but website features can stand alone — they come from official sources)
     const meaningfulGroups = Object.keys(selectorGroups).filter(k => !SKIP_GROUPS.has(k));
-    if (meaningfulGroups.length < 2 && Object.keys(flows).length < 2) {
+    const hasWebsiteFeatures = (ref.websiteFeatures?.length ?? 0) > 0 || (ref.valueAddFeatures?.length ?? 0) > 0;
+    if (meaningfulGroups.length < 2 && Object.keys(flows).length < 2 && !hasWebsiteFeatures) {
         return { ladder: [], signals: {}, hash: computeHash(ref) };
     }
     // Track which flow names are already covered by selector groups
@@ -76,9 +78,53 @@ export function generateLadderFromReference(ref) {
         const keywords = extractKeywordsFromFlow(flowName, flow);
         signals[featureId] = keywords;
     }
+    // ── Step 2.5: Features from website extraction ─────────────────
+    if (ref.websiteFeatures) {
+        for (const wf of ref.websiteFeatures) {
+            const featureId = `web_${wf.id}`;
+            if (features.some((f) => f.id === featureId))
+                continue;
+            // Skip if an exact selector group or flow already covers this feature
+            // (use exact key match, not fuzzy flowNamesRelated — avoids false positives
+            // where a short website feature id like "export" matches "export_pdf_flow")
+            if (selectorGroups[wf.id] !== undefined || flows[wf.id] !== undefined)
+                continue;
+            const level = (["F", "B", "S", "SSS"].includes(wf.level)
+                ? wf.level
+                : "F");
+            const weight = assignWeight(wf.id, 0, level);
+            features.push({
+                id: featureId,
+                description: wf.description || wf.name,
+                level,
+                weight,
+                critical: false,
+            });
+            signals[featureId] = extractKeywordsFromName(wf.name);
+        }
+    }
+    // ── Step 2.6: ScreenHand value-add features ───────────────────
+    if (ref.valueAddFeatures) {
+        for (const va of ref.valueAddFeatures) {
+            const featureId = `va_${va.id}`;
+            if (features.some((f) => f.id === featureId))
+                continue;
+            const level = (["B", "S", "SSS"].includes(va.level)
+                ? va.level
+                : "S");
+            features.push({
+                id: featureId,
+                description: va.description,
+                level,
+                weight: 2,
+                critical: false,
+            });
+            signals[featureId] = extractKeywordsFromName(va.name);
+        }
+    }
     // ── Step 3: Sort by level progression ──────────────────────────
     const levelOrder = {
-        beginner: 0, pro: 1, expert: 2, grandmaster: 3,
+        F: 0, B: 1, S: 2, SSS: 3,
     };
     features.sort((a, b) => levelOrder[a.level] - levelOrder[b.level]);
     return { ladder: features, signals, hash: computeHash(ref) };
@@ -87,37 +133,37 @@ export function generateLadderFromReference(ref) {
 function assignLevel(name, selectorCount, isFlow, complexity) {
     const nameLower = name.toLowerCase();
     const parts = nameLower.split(/[_\s-]+/);
-    // Check grandmaster first (most specific)
-    if (parts.some(p => GRANDMASTER_KEYWORDS.has(p)))
-        return "grandmaster";
-    if (parts.some(p => EXPERT_KEYWORDS.has(p)))
-        return "expert";
-    if (parts.some(p => PRO_KEYWORDS.has(p)))
-        return "pro";
-    if (parts.some(p => BEGINNER_KEYWORDS.has(p)))
-        return "beginner";
+    // Check SSS first (most specific)
+    if (parts.some(p => SSS_KEYWORDS.has(p)))
+        return "SSS";
+    if (parts.some(p => S_KEYWORDS.has(p)))
+        return "S";
+    if (parts.some(p => B_KEYWORDS.has(p)))
+        return "B";
+    if (parts.some(p => F_KEYWORDS.has(p)))
+        return "F";
     // Fallback based on complexity
     if (isFlow) {
         if (complexity >= 8)
-            return "expert";
+            return "S";
         if (complexity >= 5)
-            return "pro";
-        return "beginner";
+            return "B";
+        return "F";
     }
     // Selector group: more selectors = more complex
     if (selectorCount >= 8)
-        return "expert";
+        return "S";
     if (selectorCount >= 4)
-        return "pro";
-    return "beginner";
+        return "B";
+    return "F";
 }
 // ── Weight assignment ────────────────────────────────────────────
 function assignWeight(name, complexity, level) {
-    if (level === "grandmaster")
+    if (level === "SSS")
         return 3;
-    if (level === "expert" && complexity >= 6)
+    if (level === "S" && complexity >= 6)
         return 3;
-    if (level === "expert" || level === "pro")
+    if (level === "S" || level === "B")
         return 2;
     return 1;
 }
@@ -204,6 +250,17 @@ function extractKeywordsFromFlow(flowName, flow) {
     }
     return deduplicateArray(keywords);
 }
+// ── Keyword extraction from feature name ──────────────────────
+function extractKeywordsFromName(name) {
+    const keywords = [];
+    for (const part of name.split(/[\s_-]+/)) {
+        const lower = part.toLowerCase().replace(/[^a-z0-9]/g, "");
+        if (lower.length > 2 && !STOP_WORDS.has(lower)) {
+            keywords.push(lower);
+        }
+    }
+    return deduplicateArray(keywords);
+}
 // ── Flow-to-selector group name matching ─────────────────────────
 function flowNamesRelated(groupName, flowName) {
     const gParts = new Set(groupName.split("_"));
@@ -222,6 +279,8 @@ function computeHash(ref) {
     const keys = [
         ...Object.keys(ref.selectors ?? {}).sort(),
         ...Object.keys(ref.flows ?? {}).sort(),
+        ...(ref.websiteFeatures ?? []).map((f) => f.id).sort(),
+        ...(ref.valueAddFeatures ?? []).map((f) => f.id).sort(),
     ].join("|");
     // Simple string hash (djb2)
     let hash = 5381;