screenhand 0.2.0 → 0.3.1

package/dist/src/runtime/accessibility-adapter.js

@@ -14,12 +14,14 @@
 //
 // You should have received a copy of the GNU Affero General Public License
 // along with ScreenHand. If not, see <https://www.gnu.org/licenses/>.
+import { randomUUID } from "node:crypto";
 import { toAXRole } from "./ax-role-map.js";
 const POLL_INTERVAL_MS = 100;
 export class AccessibilityAdapter {
     bridge;
     sessions = new Map();
     sessionsByProfile = new Map();
+    lastPidRefresh = 0;
     constructor(bridge) {
         this.bridge = bridge;
     }
@@ -35,7 +37,7 @@ export class AccessibilityAdapter {
             throw new Error("Accessibility permission not granted. Go to System Settings → Privacy & Security → Accessibility and enable this app.");
         }
         const info = {
-            sessionId: reuseSessionId ?? `ax_session_${profile}_${Date.now()}`,
+            sessionId: reuseSessionId ?? `ax_session_${profile}_${Date.now()}_${randomUUID().slice(0, 8)}`,
             profile,
             createdAt: new Date().toISOString(),
             adapterType: "accessibility",
@@ -122,6 +124,7 @@ export class AccessibilityAdapter {
     }
     async click(sessionId, element) {
         const state = this.requireSession(sessionId);
+        await this.refreshPidIfNeeded(state);
         const elementPath = this.parseElementPath(element.handleId);
         if (elementPath) {
             await this.bridge.call("ax.performAction", {
@@ -134,7 +137,7 @@ export class AccessibilityAdapter {
             // Fallback to coordinate click
             const cx = element.coordinates.x + element.coordinates.width / 2;
             const cy = element.coordinates.y + element.coordinates.height / 2;
-            await this.bridge.call("cg.mouseClick", { x: cx, y: cy });
+            await this.bridge.call("cg.mouseClick", { x: cx, y: cy, targetPid: state.pid });
         }
         else {
             throw new Error("Cannot click: no element path or coordinates");
@@ -142,6 +145,7 @@ export class AccessibilityAdapter {
     }
     async setValue(sessionId, element, text, clear) {
         const state = this.requireSession(sessionId);
+        await this.refreshPidIfNeeded(state);
         const elementPath = this.parseElementPath(element.handleId);
         if (clear && elementPath) {
             // Try AX value set first
@@ -158,13 +162,15 @@ export class AccessibilityAdapter {
             }
         }
         // Fallback: click to focus, select all if clearing, then type
+        // Use PID-targeted events to prevent keystrokes going to wrong app
+        const targetPid = state.pid;
         await this.click(sessionId, element);
         await sleep(50);
         if (clear) {
-            await this.bridge.call("cg.keyCombo", { keys: ["cmd", "a"] });
+            await this.bridge.call("cg.keyCombo", { keys: ["cmd", "a"], targetPid });
             await sleep(50);
         }
-        await this.bridge.call("cg.typeText", { text });
+        await this.bridge.call("cg.typeText", { text, targetPid });
     }
     async getValue(sessionId, element) {
         const state = this.requireSession(sessionId);
@@ -246,16 +252,18 @@ export class AccessibilityAdapter {
     async focusApp(sessionId, bundleId) {
         const state = this.requireSession(sessionId);
         await this.bridge.call("app.focus", { bundleId });
-        // Update PID if different app
-        if (bundleId !== state.bundleId) {
-            const apps = await this.bridge.call("app.list");
-            const app = apps.find((a) => a.bundleId === bundleId);
-            if (app) {
-                state.pid = app.pid;
-                state.bundleId = bundleId;
-                state.appName = app.name;
-            }
+        // Verify focus was achieved by checking frontmost app
+        let frontmost = await this.bridge.call("app.frontmost");
+        // If focus didn't take, retry once
+        if (frontmost.bundleId !== bundleId) {
+            await this.bridge.call("app.focus", { bundleId });
+            frontmost = await this.bridge.call("app.frontmost");
         }
+        // Update state based on actual frontmost app, not optimistic assumption
+        state.pid = frontmost.pid;
+        state.bundleId = frontmost.bundleId;
+        state.appName = frontmost.name;
+        this.lastPidRefresh = Date.now();
     }
     async listApps(_sessionId) {
         return this.bridge.call("app.list");
@@ -265,10 +273,12 @@ export class AccessibilityAdapter {
     }
     async menuClick(sessionId, menuPath) {
         const state = this.requireSession(sessionId);
+        await this.refreshPidIfNeeded(state);
         await this.bridge.call("ax.menuClick", { pid: state.pid, menuPath });
     }
-    async keyCombo(_sessionId, keys) {
-        await this.bridge.call("cg.keyCombo", { keys });
+    async keyCombo(sessionId, keys) {
+        const state = this.requireSession(sessionId);
+        await this.bridge.call("cg.keyCombo", { keys, targetPid: state.pid });
     }
     async elementTree(sessionId, maxDepth, _root) {
         const state = this.requireSession(sessionId);
@@ -285,9 +295,10 @@ export class AccessibilityAdapter {
         const fromY = from.coordinates.y + from.coordinates.height / 2;
         const toX = to.coordinates.x + to.coordinates.width / 2;
         const toY = to.coordinates.y + to.coordinates.height / 2;
-        await this.bridge.call("cg.mouseDrag", { fromX, fromY, toX, toY });
+        const state = this.requireSession(sessionId);
+        await this.bridge.call("cg.mouseDrag", { fromX, fromY, toX, toY, targetPid: state.pid });
     }
-    async scroll(_sessionId, direction, amount, element) {
+    async scroll(sessionId, direction, amount, element) {
         let x = 500;
         let y = 400;
         if (element?.coordinates) {
@@ -301,9 +312,35 @@ export class AccessibilityAdapter {
             right: { deltaX: amount, deltaY: 0 },
         };
         const delta = deltaMap[direction];
-        await this.bridge.call("cg.scroll", { x, y, ...delta });
+        const state = this.requireSession(sessionId);
+        await this.bridge.call("cg.scroll", { x, y, ...delta, targetPid: state.pid });
+    }
+    async isFrontmost() {
+        // Check if *any* session's bundleId matches the current frontmost app.
+        // Used by the executor to verify focus before acting.
+        const frontmost = await this.bridge.call("app.frontmost");
+        for (const state of this.sessions.values()) {
+            if (state.bundleId === frontmost.bundleId) {
+                return true;
+            }
+        }
+        return false;
     }
     // ── Private helpers ──
+    async refreshPidIfNeeded(state) {
+        if (Date.now() - this.lastPidRefresh < 500)
+            return;
+        try {
+            const frontmost = await this.bridge.call("app.frontmost");
+            if (frontmost.bundleId === state.bundleId) {
+                state.pid = frontmost.pid;
+                this.lastPidRefresh = Date.now();
+            }
+        }
+        catch {
+            // Best-effort refresh; don't break the caller
+        }
+    }
     requireSession(sessionId) {
         const state = this.sessions.get(sessionId);
         if (!state)

package/dist/src/runtime/applescript-adapter.js

@@ -15,6 +15,7 @@
 // You should have received a copy of the GNU Affero General Public License
 // along with ScreenHand. If not, see <https://www.gnu.org/licenses/>.
 import { execFile } from "node:child_process";
+import { randomUUID } from "node:crypto";
 import { promisify } from "node:util";
 const execFileAsync = promisify(execFile);
 const POLL_INTERVAL_MS = 100;
@@ -49,7 +50,7 @@ export class AppleScriptAdapter {
         if (existing)
             return existing.info;
         const info = {
-            sessionId: reuseSessionId ?? `as_session_${profile}_${Date.now()}`,
+            sessionId: reuseSessionId ?? `as_session_${profile}_${Date.now()}_${randomUUID().slice(0, 8)}`,
             profile,
             createdAt: new Date().toISOString(),
             adapterType: "applescript",
@@ -291,7 +292,12 @@ export class AppleScriptAdapter {
         throw new Error(`AppleScript adapter does not support target type: ${target.type}`);
     }
     escapeAS(str) {
-        return str.replace(/\\/g, "\\\\").replace(/"/g, '\\"');
+        return str
+            .replace(/\\/g, "\\\\")
+            .replace(/"/g, '\\"')
+            .replace(/\n/g, "\\n")
+            .replace(/\r/g, "\\r")
+            .replace(/\0/g, "");
     }
 }
 function sleep(ms) {

package/dist/src/runtime/cdp-chrome-adapter.js

@@ -47,7 +47,7 @@ export class CdpChromeAdapter {
         const client = await CDP({ port: chrome.port, target: targetId });
         await Promise.all([client.Page.enable(), client.Runtime.enable()]);
         const info = {
-            sessionId: reuseSessionId ?? `cdp_session_${profile}_${Date.now()}`,
+            sessionId: reuseSessionId ?? `cdp_session_${profile}_${Date.now()}_${randomUUID().slice(0, 8)}`,
             profile,
             createdAt: new Date().toISOString(),
             adapterType: "cdp",

package/dist/src/runtime/executor.js

@@ -37,6 +37,14 @@ export class Executor {
                 const locateResult = await this.locateWithBudget(input.sessionId, siteKey, actionKey, input.target, budget.locateMs, retry > 0);
                 attempts.push(...locateResult.attempts);
                 telemetry.locateMs += locateResult.attempts.reduce((sum, attempt) => sum + attempt.timeoutMs, 0);
+                // Re-validate focus before acting — app may have lost focus during locate
+                if (this.adapter.isFrontmost) {
+                    const front = await this.adapter.isFrontmost();
+                    if (!front && this.adapter.focusApp) {
+                        const ctx = await this.adapter.getAppContext(input.sessionId);
+                        await this.adapter.focusApp(input.sessionId, ctx.bundleId);
+                    }
+                }
                 await this.timed(budget.actMs, async () => {
                     await this.adapter.click(input.sessionId, locateResult.element);
                 }, "ACTION_FAILED");
@@ -68,6 +76,14 @@ export class Executor {
             const locateResult = await this.locateWithBudget(input.sessionId, siteKey, actionKey, input.target, budget.locateMs, false);
             attempts.push(...locateResult.attempts);
             telemetry.locateMs += budget.locateMs;
+            // Re-validate focus before acting — app may have lost focus during locate
+            if (this.adapter.isFrontmost) {
+                const front = await this.adapter.isFrontmost();
+                if (!front && this.adapter.focusApp) {
+                    const ctx = await this.adapter.getAppContext(input.sessionId);
+                    await this.adapter.focusApp(input.sessionId, ctx.bundleId);
+                }
+            }
             await this.timed(budget.actMs, async () => {
                 await this.adapter.setValue(input.sessionId, locateResult.element, input.text, input.clear ?? true);
             }, "ACTION_FAILED");
@@ -171,7 +187,7 @@ export class Executor {
                     // URL parsing failed, use bundleId + windowTitle
                 }
             }
-            return `${ctx.bundleId}::${ctx.windowTitle}`;
+            return ctx.bundleId;
         }
         catch {
             // Fallback to page meta
@@ -191,15 +207,19 @@ export class Executor {
         };
     }
     async timed(timeoutMs, operation, errorCode) {
+        let timerId;
         const timeout = new Promise((_, reject) => {
-            setTimeout(() => {
+            timerId = setTimeout(() => {
                 reject(this.runtimeError("TIMEOUT", `Timed out after ${timeoutMs}ms.`));
             }, timeoutMs);
         });
         try {
-            return await Promise.race([operation(), timeout]);
+            const result = await Promise.race([operation(), timeout]);
+            clearTimeout(timerId);
+            return result;
         }
         catch (error) {
+            clearTimeout(timerId);
             if (this.isRuntimeError(error)) {
                 throw error;
             }

package/dist/src/runtime/locator-cache.js

@@ -16,13 +16,35 @@
 // along with ScreenHand. If not, see <https://www.gnu.org/licenses/>.
 export class LocatorCache {
     store = new Map();
+    learningEngine = null;
+    /**
+     * Inject the learning engine for fallback on cache miss.
+     * Called after both are constructed to avoid circular dependencies.
+     */
+    setLearningEngine(engine) {
+        this.learningEngine = engine;
+    }
     get(siteKey, actionKey) {
-        return this.store.get(this.key(siteKey, actionKey));
+        // 1. Check in-memory cache first
+        const cached = this.store.get(this.key(siteKey, actionKey));
+        if (cached)
+            return cached;
+        // 2. Fallback: ask learning engine for a proven locator
+        if (this.learningEngine) {
+            const learned = this.learningEngine.recommendLocator(siteKey, actionKey);
+            if (learned) {
+                // Promote to cache for fast subsequent lookups
+                this.store.set(this.key(siteKey, actionKey), learned.locator);
+                return learned.locator;
+            }
+        }
+        return undefined;
     }
     set(siteKey, actionKey, locator) {
         this.store.set(this.key(siteKey, actionKey), locator);
     }
     key(siteKey, actionKey) {
-        return `${siteKey}::${actionKey}`;
+        // Use length-prefixed format to avoid collision when keys contain the separator
+        return `${siteKey.length}:${siteKey}\0${actionKey}`;
     }
 }

package/dist/src/runtime/service.js

@@ -23,20 +23,57 @@ export class AutomationRuntimeService {
     logger;
     sessions;
     executor;
+    worldModel = null;
     constructor(adapter, logger, cache = new LocatorCache()) {
         this.adapter = adapter;
         this.logger = logger;
         this.sessions = new SessionManager(adapter);
         this.executor = new Executor(adapter, cache, logger);
     }
+    /**
+     * Inject the WorldModel so runtime actions update shared state.
+     */
+    setWorldModel(model) {
+        this.worldModel = model;
+    }
     async sessionStart(profile = DEFAULT_PROFILE) {
         return this.sessions.sessionStart(profile);
     }
+    /**
+     * Ensure session exists (re-attaches if lost after MCP restart).
+     * Also reloads the world model from disk when re-attaching so world
+     * state survives across MCP server restarts.
+     */
+    async ensureSession(sessionId) {
+        const hadSession = !!this.sessions.getSession(sessionId);
+        const session = await this.sessions.requireSessionResilent(sessionId);
+        // If we had to re-attach, reload persisted world state
+        if (!hadSession && this.worldModel) {
+            this.worldModel.init(sessionId);
+        }
+        return session;
+    }
+    // L2-74 fix: Centralized URL protocol validation for all navigate paths
+    static BLOCKED_URL_PROTOCOLS = ["javascript:", "data:", "blob:", "vbscript:"];
     async navigate(input) {
         const telemetry = this.logger.start("navigate", input.sessionId);
         try {
-            await this.sessions.requireSessionResilent(input.sessionId);
+            // L2-74 fix: Block dangerous URL protocols at the service level
+            const urlLower = input.url.trim().toLowerCase();
+            for (const proto of AutomationRuntimeService.BLOCKED_URL_PROTOCOLS) {
+                if (urlLower.startsWith(proto)) {
+                    throw new Error(`Blocked: "${proto}" URLs are not allowed for security reasons`);
+                }
+            }
+            await this.ensureSession(input.sessionId);
             const page = await this.adapter.navigate(input.sessionId, input.url, input.timeoutMs ?? DEFAULT_NAVIGATE_TIMEOUT_MS);
+            // Feed navigation result to world model for domain state tracking
+            if (this.worldModel) {
+                const bundleId = this.worldModel.getState().focusedApp?.bundleId;
+                if (bundleId) {
+                    this.worldModel.ingestCDPSnapshot(bundleId, input.url, page.title ?? "");
+                }
+            }
             return {
                 ok: true,
                 data: page,
@@ -57,7 +94,7 @@ export class AutomationRuntimeService {
     async waitFor(input) {
         const telemetry = this.logger.start("wait_for", input.sessionId);
         try {
-            await this.sessions.requireSessionResilent(input.sessionId);
+            await this.ensureSession(input.sessionId);
             const matched = await this.adapter.waitFor(input.sessionId, input.condition, input.timeoutMs ?? DEFAULT_WAIT_TIMEOUT_MS);
             return {
                 ok: true,
@@ -77,17 +114,17 @@ export class AutomationRuntimeService {
         }
     }
     async press(input) {
-        await this.sessions.requireSessionResilent(input.sessionId);
+        await this.ensureSession(input.sessionId);
         return this.executor.press(input);
     }
     async typeInto(input) {
-        await this.sessions.requireSessionResilent(input.sessionId);
+        await this.ensureSession(input.sessionId);
         return this.executor.typeInto(input);
     }
     async extract(input) {
         const telemetry = this.logger.start("extract", input.sessionId);
         try {
-            await this.sessions.requireSessionResilent(input.sessionId);
+            await this.ensureSession(input.sessionId);
             const data = await this.adapter.extract(input.sessionId, input.target, input.format);
             return {
                 ok: true,
@@ -109,7 +146,7 @@ export class AutomationRuntimeService {
     async screenshot(input) {
         const telemetry = this.logger.start("screenshot", input.sessionId);
         try {
-            await this.sessions.requireSessionResilent(input.sessionId);
+            await this.ensureSession(input.sessionId);
             const path = await this.adapter.screenshot(input.sessionId, input.region);
             return {
                 ok: true,
@@ -132,11 +169,12 @@ export class AutomationRuntimeService {
     async appLaunch(input) {
         const telemetry = this.logger.start("app_launch", input.sessionId);
         try {
-            await this.sessions.requireSessionResilent(input.sessionId);
+            await this.ensureSession(input.sessionId);
             if (!this.adapter.launchApp) {
                 throw new Error("Adapter does not support launchApp");
             }
             const ctx = await this.adapter.launchApp(input.sessionId, input.bundleId);
+            this.worldModel?.updateFocusedApp(ctx);
             return {
                 ok: true,
                 data: ctx,
@@ -157,11 +195,17 @@ export class AutomationRuntimeService {
     async appFocus(input) {
         const telemetry = this.logger.start("app_focus", input.sessionId);
         try {
-            await this.sessions.requireSessionResilent(input.sessionId);
+            await this.ensureSession(input.sessionId);
             if (!this.adapter.focusApp) {
                 throw new Error("Adapter does not support focusApp");
             }
             await this.adapter.focusApp(input.sessionId, input.bundleId);
+            this.worldModel?.updateFocusedApp({
+                bundleId: input.bundleId,
+                appName: input.bundleId,
+                pid: 0,
+                windowTitle: "",
+            });
             return {
                 ok: true,
                 data: undefined,
@@ -182,7 +226,7 @@ export class AutomationRuntimeService {
     async appList(sessionId) {
         const telemetry = this.logger.start("app_list", sessionId);
         try {
-            await this.sessions.requireSessionResilent(sessionId);
+            await this.ensureSession(sessionId);
             if (!this.adapter.listApps) {
                 throw new Error("Adapter does not support listApps");
             }
@@ -207,7 +251,7 @@ export class AutomationRuntimeService {
     async windowList(sessionId) {
         const telemetry = this.logger.start("window_list", sessionId);
         try {
-            await this.sessions.requireSessionResilent(sessionId);
+            await this.ensureSession(sessionId);
             if (!this.adapter.listWindows) {
                 throw new Error("Adapter does not support listWindows");
             }
@@ -232,7 +276,7 @@ export class AutomationRuntimeService {
     async menuClick(input) {
         const telemetry = this.logger.start("menu_click", input.sessionId);
         try {
-            await this.sessions.requireSessionResilent(input.sessionId);
+            await this.ensureSession(input.sessionId);
             if (!this.adapter.menuClick) {
                 throw new Error("Adapter does not support menuClick");
             }
@@ -257,7 +301,7 @@ export class AutomationRuntimeService {
     async keyCombo(input) {
         const telemetry = this.logger.start("key_combo", input.sessionId);
         try {
-            await this.sessions.requireSessionResilent(input.sessionId);
+            await this.ensureSession(input.sessionId);
             if (!this.adapter.keyCombo) {
                 throw new Error("Adapter does not support keyCombo");
             }
@@ -282,7 +326,7 @@ export class AutomationRuntimeService {
     async elementTree(input) {
         const telemetry = this.logger.start("element_tree", input.sessionId);
         try {
-            await this.sessions.requireSessionResilent(input.sessionId);
+            await this.ensureSession(input.sessionId);
             if (!this.adapter.elementTree) {
                 throw new Error("Adapter does not support elementTree");
             }
@@ -307,7 +351,7 @@ export class AutomationRuntimeService {
     async drag(input) {
         const telemetry = this.logger.start("drag", input.sessionId);
         try {
-            await this.sessions.requireSessionResilent(input.sessionId);
+            await this.ensureSession(input.sessionId);
             if (!this.adapter.drag) {
                 throw new Error("Adapter does not support drag");
             }
@@ -337,7 +381,7 @@ export class AutomationRuntimeService {
     async scroll(input) {
         const telemetry = this.logger.start("scroll", input.sessionId);
         try {
-            await this.sessions.requireSessionResilent(input.sessionId);
+            await this.ensureSession(input.sessionId);
             if (!this.adapter.scroll) {
                 throw new Error("Adapter does not support scroll");
             }

package/dist/src/runtime/session-manager.js

@@ -50,7 +50,10 @@ export class SessionManager {
         const existing = this.getSession(sessionId);
         if (existing)
             return existing;
-        const match = sessionId.match(/^(?:ax|cdp|as|vision|composite)_session_(.+)_\d+$/);
+        // Session IDs: {prefix}_session_{profile}_{timestamp}_{random8} (new)
+        // or legacy:   {prefix}_session_{profile}_{timestamp}
+        // Use greedy .+ so profiles with digits (e.g. "user_1234567890") capture fully
+        const match = sessionId.match(/^(?:ax|cdp|as|vision|composite)_session_(.+)_\d{13,}(?:_[a-f0-9]{8})?$/);
         const profile = match?.[1] ?? "automation";
         const created = await this.adapter.attach(profile, sessionId);
         this.sessionsByProfile.set(profile, created);

package/dist/src/runtime/vision-adapter.js

@@ -14,6 +14,7 @@
 //
 // You should have received a copy of the GNU Affero General Public License
 // along with ScreenHand. If not, see <https://www.gnu.org/licenses/>.
+import { randomUUID } from "node:crypto";
 const POLL_INTERVAL_MS = 200;
 /**
  * Vision-based adapter for apps with poor/no accessibility support.
@@ -33,7 +34,7 @@ export class VisionAdapter {
         await this.bridge.start();
         const frontmost = await this.bridge.call("app.frontmost");
         const info = {
-            sessionId: reuseSessionId ?? `vision_session_${profile}_${Date.now()}`,
+            sessionId: reuseSessionId ?? `vision_session_${profile}_${Date.now()}_${randomUUID().slice(0, 8)}`,
             profile,
             createdAt: new Date().toISOString(),
             adapterType: "vision",

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

@@ -0,0 +1,72 @@
+// Copyright (C) 2025 Clazro Technology Private Limited
+// SPDX-License-Identifier: AGPL-3.0-only
+// ── Rating System (F → 0) ──────────────────────────────────────────
+//
+// Game-style rating: F E D C B A S SS SSS 0
+// Each grade has 3 sub-tiers: e.g. B1 (entry), B2 (mid), B3 (top)
+// Graded by 10 weighted factors scored 0-100
+//
+// Years-equivalent mapping:
+//   F   = just opened the app
+//   E   = ~1 week user
+//   D   = ~1-3 months
+//   C   = ~6-12 months
+//   B   = ~1-3 years (consistent daily user)
+//   A   = ~3-5 years (power user / team lead)
+//   S   = ~5-10 years (department architect)
+//   SS  = ~10-20 years (platform expert, builds systems)
+//   SSS = ~20+ years (framework builder, trains others)
+//   0   = Class Zero — transcendent mastery, all 10 factors maxed
+/** Rating grades from lowest to highest */
+export const RATING_GRADES = ["F", "E", "D", "C", "B", "A", "S", "SS", "SSS", "0"];
+/** Factor weights — hard-to-fake signals dominate (57%), session-gated evidence (43%) */
+export const RATING_FACTOR_WEIGHTS = {
+    consistency: 20, // THE core signal — can't fake showing up 50+ times
+    platformKnowledge: 15, // shortcuts, deep features — proves real knowledge
+    edgeCaseHandling: 12, // surviving unexpected states — proves resilience
+    teachingAbility: 10, // exporting playbooks — proves codifiable mastery
+    featureCoverage: 10, // breadth of features used (session-gated)
+    workflowDepth: 8, // multi-step workflows completed (session-gated)
+    outcomeVerification: 8, // verified outcomes (session-gated)
+    errorRecovery: 7, // healing from failures — honest if it happens
+    crossFeatureChains: 5, // combining features end-to-end
+    speedEfficiency: 5, // repeat mastery across sessions
+};
+export const DEFAULT_APP_MAP_CONFIG = {
+    mapsDir: "",
+    staleThresholdDays: 7,
+    versionDecayFactor: 0.5,
+    pruneSessionThreshold: 10,
+    maxZonesPerApp: 50,
+    maxElementsPerZone: 100,
+    maxEdges: 200,
+    maxHistoryEntries: 100,
+    maxHierarchyEntriesPerZone: 50,
+    maxContractsPerZone: 30,
+    maxOutcomesPerContract: 5,
+    maxStateDimensions: 30,
+    maxStateTransitions: 100,
+    maxVisibilityConditions: 200,
+    maxTimingProfiles: 100,
+    maxReadySignals: 50,
+};
+// ── Rating Utility ──────────────────────────────────────────────────
+/** Convert Rating to display string: "B2", "SS3", "0" */
+export function ratingToString(r) {
+    if (r.grade === "0")
+        return "0"; // Class Zero has no sub-tier display
+    return `${r.grade}${r.subTier}`;
+}
+/** Grade thresholds: weighted score needed for each grade (0-100 scale) */
+export const GRADE_THRESHOLDS = [
+    { grade: "0", minScore: 97 }, // Class Zero — near-perfect across all factors
+    { grade: "SSS", minScore: 90 }, // 20+ years equivalent
+    { grade: "SS", minScore: 82 }, // 10-20 years
+    { grade: "S", minScore: 73 }, // 5-10 years
+    { grade: "A", minScore: 62 }, // 3-5 years
+    { grade: "B", minScore: 50 }, // 1-3 years
+    { grade: "C", minScore: 38 }, // 6-12 months
+    { grade: "D", minScore: 25 }, // 1-3 months
+    { grade: "E", minScore: 12 }, // ~1 week
+    { grade: "F", minScore: 0 }, // just opened the app
+];