@runsnative/mcp-server 0.1.5 → 0.3.0

package/dist/bridge-client.js

@@ -0,0 +1,25 @@
+// Module-level pair state — lives for the lifetime of the MCP server process.
+let _linkedPairId = null;
+export function getLinkedPairId() { return _linkedPairId; }
+export function setLinkedPairId(id) { _linkedPairId = id; }
+export function clearLinkedPairId() { _linkedPairId = null; }
+// trim(): trailing whitespace from setx/cmd wrappers silently corrupts the
+// Authorization header (KUKAMANGA-wide env-read rule).
+const BASE_URL = (process.env['RUNSNATIVE_API_URL'] ?? 'https://api.runsnative.org/mcp').trim();
+const TOKEN = process.env['RUNSNATIVE_TENANT_TOKEN']?.trim();
+export async function postWorkerApi(path, body) {
+    const headers = { 'Content-Type': 'application/json' };
+    if (TOKEN)
+        headers['Authorization'] = `Bearer ${TOKEN}`;
+    return fetch(`${BASE_URL}${path}`, {
+        method: 'POST',
+        headers,
+        body: JSON.stringify(body),
+    });
+}
+export async function getWorkerApi(path) {
+    const headers = {};
+    if (TOKEN)
+        headers['Authorization'] = `Bearer ${TOKEN}`;
+    return fetch(`${BASE_URL}${path}`, { method: 'GET', headers });
+}

package/dist/http-server.js

@@ -116,8 +116,14 @@ async function handler(req, res) {
         }
         const targetUrl = body['url'];
         const result = await runInferencePipeline(targetUrl);
-        if (!result.ok)
-            return sendJson(res, 422, { error: result.error.message, code: result.error.code });
+        if (!result.ok) {
+            return sendJson(res, 422, {
+                error: result.error.message,
+                code: result.error.code,
+                reason: result.error.reason,
+                ...('status' in result.error && result.error.status ? { status: result.error.status } : {}),
+            });
+        }
         return sendJson(res, 200, result.result);
     }
     if (method === 'POST' && url === '/api/config') {

package/dist/index.js

@@ -15,6 +15,13 @@ import { GET_STEP_TOOL, handleGetStep } from './tools/get-step.js';
 import { SURFACE_PREVIEW_TOOL, handleSurfacePreview } from './tools/surface-preview.js';
 import { LIST_COMPOSITION_PATTERNS_TOOL, handleListCompositionPatterns } from './tools/list-composition-patterns.js';
 import { GET_COMPOSITION_PATTERN_TOOL, handleGetCompositionPattern } from './tools/get-composition-pattern.js';
+import { GET_EMPHASIS_SCALE_TOOL, handleGetEmphasisScale } from './tools/get-emphasis-scale.js';
+import { GET_COMPLETENESS_MAP_TOOL, handleGetCompletenessMap } from './tools/get-completeness-map.js';
+import { LINK_SESSION_TOOL, handleLinkSession } from './tools/link-session.js';
+import { SET_THEME_TOOL, handleSetTheme } from './tools/set-theme.js';
+import { NAVIGATE_TOOL, handleNavigate } from './tools/navigate.js';
+import { SET_INSTANCE_VARIANT_TOOL, handleSetInstanceVariant } from './tools/set-instance-variant.js';
+import { GET_MARKER_CAPTURE_TOOL, handleGetMarkerCapture } from './tools/get-marker-capture.js';
 import { createProvider } from './provider.js';
 import { RemoteContentProvider } from './remote-provider.js';
 // Create the content provider — LocalContentProvider if content tree is present,
@@ -43,6 +50,13 @@ server.setRequestHandler(ListToolsRequestSchema, async () => ({
         SURFACE_PREVIEW_TOOL,
         LIST_COMPOSITION_PATTERNS_TOOL,
         GET_COMPOSITION_PATTERN_TOOL,
+        GET_EMPHASIS_SCALE_TOOL,
+        GET_COMPLETENESS_MAP_TOOL,
+        LINK_SESSION_TOOL,
+        SET_THEME_TOOL,
+        NAVIGATE_TOOL,
+        SET_INSTANCE_VARIANT_TOOL,
+        GET_MARKER_CAPTURE_TOOL,
     ],
 }));
 server.setRequestHandler(CallToolRequestSchema, async (request) => {
@@ -71,6 +85,20 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
             return handleListCompositionPatterns(provider, request.params.arguments ?? {});
         case 'get_composition_pattern':
             return handleGetCompositionPattern(provider, request.params.arguments ?? {});
+        case 'get_emphasis_scale':
+            return handleGetEmphasisScale();
+        case 'get_completeness_map':
+            return handleGetCompletenessMap();
+        case 'link_session':
+            return handleLinkSession(request.params.arguments ?? {});
+        case 'set_theme':
+            return handleSetTheme(request.params.arguments ?? {});
+        case 'navigate':
+            return handleNavigate(request.params.arguments ?? {});
+        case 'set_instance_variant':
+            return handleSetInstanceVariant(request.params.arguments ?? {});
+        case 'get_marker_capture':
+            return handleGetMarkerCapture(request.params.arguments ?? {});
         default:
             throw new Error(`Unknown tool: ${request.params.name}`);
     }

package/dist/inferrer/contrast.js

@@ -0,0 +1,28 @@
+/** WCAG 2.2 relative luminance (https://www.w3.org/TR/WCAG22/#dfn-relative-luminance). */
+export function relativeLuminance([r, g, b]) {
+    const linear = (channel) => {
+        const s = channel / 255;
+        return s <= 0.03928 ? s / 12.92 : ((s + 0.055) / 1.055) ** 2.4;
+    };
+    return 0.2126 * linear(r) + 0.7152 * linear(g) + 0.0722 * linear(b);
+}
+/** WCAG 2.2 contrast ratio. Symmetric: argument order does not matter. */
+export function contrastRatio(a, b) {
+    const la = relativeLuminance(a);
+    const lb = relativeLuminance(b);
+    const lighter = Math.max(la, lb);
+    const darker = Math.min(la, lb);
+    return (lighter + 0.05) / (darker + 0.05);
+}
+export function assessContrast(foreground, background, backgroundHex) {
+    const raw = contrastRatio(foreground, background);
+    return {
+        // Thresholds test the unrounded ratio: a true 4.497 displays as 4.5 but does not pass AA.
+        ratio: Math.round(raw * 100) / 100,
+        backgroundColor: backgroundHex,
+        aa: raw >= 4.5,
+        aaLarge: raw >= 3,
+        aaa: raw >= 7,
+        aaaLarge: raw >= 4.5,
+    };
+}

package/dist/inferrer/image-extractor.js

@@ -10,6 +10,34 @@ async function loadSharp() {
 }
 const MAX_PIXELS = 10_000;
 const MAX_ITER = 20;
+/**
+ * k-means++ needs randomness, but Math.random() made this a different answer for the
+ * same bytes on every call. Seeding from the pixels keeps the clustering stochastic
+ * across images while making extractImageColors a pure function of its input.
+ *
+ * This buys reproducibility per *image*, not per *URL*: a live page can paint a
+ * different screenshot on each fetch (lazy content, animation), and no seeding fixes
+ * that. Re-analysing a stored screenshot, however, now always agrees with itself.
+ */
+function mulberry32(seed) {
+    let a = seed >>> 0;
+    return () => {
+        a = (a + 0x6d2b79f5) >>> 0;
+        let t = Math.imul(a ^ (a >>> 15), 1 | a);
+        t = (t + Math.imul(t ^ (t >>> 7), 61 | t)) ^ t;
+        return ((t ^ (t >>> 14)) >>> 0) / 4294967296;
+    };
+}
+/** FNV-1a over the sampled pixels. */
+function seedFromPixels(pixels) {
+    let h = 0x811c9dc5;
+    for (const [r, g, b] of pixels) {
+        h = Math.imul(h ^ r, 0x01000193);
+        h = Math.imul(h ^ g, 0x01000193);
+        h = Math.imul(h ^ b, 0x01000193);
+    }
+    return h >>> 0;
+}
 function toHex(r, g, b) {
     return '#' + [r, g, b]
         .map(v => Math.max(0, Math.min(255, Math.round(v))).toString(16).padStart(2, '0'))
@@ -36,12 +64,13 @@ export async function extractImageColors(buffer, sourceType, k = 5) {
         pixels.push([data[i], data[i + 1], data[i + 2]]);
     }
     // k-means++ initialisation
+    const random = mulberry32(seedFromPixels(pixels));
     const centroids = [];
-    centroids.push([...pixels[Math.floor(Math.random() * pixels.length)]]);
+    centroids.push([...pixels[Math.floor(random() * pixels.length)]]);
     for (let c = 1; c < k; c++) {
         const dists = pixels.map(p => Math.min(...centroids.map(cen => sqDist(p[0], p[1], p[2], cen[0], cen[1], cen[2]))));
         const total = dists.reduce((s, d) => s + d, 0);
-        let rnd = Math.random() * total;
+        let rnd = random() * total;
         let chosen = pixels.length - 1;
         for (let i = 0; i < dists.length; i++) {
             rnd -= dists[i];

package/dist/inferrer/page-fetcher.js

@@ -1,3 +1,4 @@
+import { extractStylesFromPage } from './style-extractor.js';
 export async function loadChromium() {
     try {
         const playwright = await import('playwright');
@@ -7,17 +8,56 @@ export async function loadChromium() {
         return null;
     }
 }
+/**
+ * Map a Chromium/Playwright navigation error string to a user-meaningful reason. Signatures
+ * verified against live failures: ecolab.com → ERR_HTTP2_PROTOCOL_ERROR (bot-block),
+ * a dead domain → ERR_NAME_NOT_RESOLVED, badssl.com → ERR_CERT_*, port 1 → ERR_UNSAFE_PORT.
+ */
+export function classifyNavError(cause) {
+    const c = cause.toUpperCase();
+    if (/\bTIMEOUT\b|EXCEEDED/.test(c))
+        return 'timeout';
+    if (c.includes('ERR_NAME_NOT_RESOLVED') || c.includes('ERR_NAME_RESOLUTION_FAILED'))
+        return 'not_found';
+    if (c.includes('ERR_CERT'))
+        return 'tls';
+    // Connection reset / HTTP2 protocol errors on the initial navigation are the fingerprint of
+    // a WAF/bot wall fingerprinting headless Chromium (verified: ecolab.com). ERR_ACCESS_DENIED
+    // and ERR_BLOCKED_BY_* are the explicit forms.
+    if (c.includes('ERR_HTTP2_PROTOCOL_ERROR') || c.includes('ERR_CONNECTION_RESET') ||
+        c.includes('ERR_ACCESS_DENIED') || c.includes('ERR_BLOCKED'))
+        return 'blocked';
+    if (c.includes('ERR_CONNECTION_REFUSED') || c.includes('ERR_CONNECTION_TIMED_OUT') ||
+        c.includes('ERR_ADDRESS_UNREACHABLE') || c.includes('ERR_UNSAFE_PORT') ||
+        c.includes('ERR_CONNECTION_CLOSED') || c.includes('ERR_EMPTY_RESPONSE') ||
+        c.includes('ERR_SOCKET_NOT_CONNECTED'))
+        return 'unreachable';
+    return 'unknown';
+}
 const VIEWPORT = { width: 1280, height: 800 };
+// Navigation timing. `domcontentloaded` is the hard gate; `networkidle` is a bounded bonus.
+const GOTO_TIMEOUT_MS = 25_000; // hard cap on the initial document navigation
+const NETWORK_IDLE_TIMEOUT_MS = 4_000; // best-effort quiesce; a busy site just skips it
+const SETTLE_MS = 800; // final paint after the DOM is ready
+const SCREENSHOT_TIMEOUT_MS = 8_000; // best-effort; empty buffer on a page that won't settle
+/**
+ * Navigates once and harvests everything the page can tell us before the browser closes:
+ * the screenshot, the serialized DOM, and the computed styles.
+ *
+ * Style extraction happens *here*, on the live page, rather than by re-rendering
+ * `renderedHtml` in a second browser — that resolves the document against about:blank and
+ * silently drops relatively-linked stylesheets, yielding an unstyled measurement.
+ */
 export async function fetchAndRender(url) {
     let parsed;
     try {
         parsed = new URL(url);
     }
     catch {
-        return { ok: false, error: { code: 'FETCH_ERROR', message: 'Invalid URL', url } };
+        return { ok: false, error: { code: 'FETCH_ERROR', message: 'Invalid URL', reason: 'invalid_url', url } };
     }
     if (parsed.protocol !== 'http:' && parsed.protocol !== 'https:') {
-        return { ok: false, error: { code: 'FETCH_ERROR', message: `Unsupported scheme: ${parsed.protocol}`, url } };
+        return { ok: false, error: { code: 'FETCH_ERROR', message: `Unsupported scheme: ${parsed.protocol}`, reason: 'invalid_url', url } };
     }
     const chromium = await loadChromium();
     if (chromium === null) {
@@ -26,6 +66,7 @@ export async function fetchAndRender(url) {
             error: {
                 code: 'FETCH_ERROR',
                 message: 'playwright is not installed — infer_brand_theme requires it. Install playwright, or use infer_theme for HTML-only analysis.',
+                reason: 'unknown',
                 url,
             },
         };
@@ -34,18 +75,62 @@ export async function fetchAndRender(url) {
     try {
         const page = await browser.newPage();
         await page.setViewportSize(VIEWPORT);
-        const response = await page.goto(url, { waitUntil: 'networkidle' });
+        // Wait for the DOM, then give the network a *bounded* chance to quiesce. Real sites —
+        // anything with analytics, a chat widget, or long-poll — never reach `networkidle`, so
+        // using it as the goto gate turned a renderable page into a 30s timeout (airbnb.com was
+        // a 30s failure; with this it renders in ~6s). `domcontentloaded` returns as soon as the
+        // markup+CSS are parsed; the short best-effort `networkidle` catches late-injected styles
+        // on calmer sites without holding the busy ones hostage; the settle covers a final paint.
+        const response = await page.goto(url, { waitUntil: 'domcontentloaded', timeout: GOTO_TIMEOUT_MS });
         if (!response) {
-            return { ok: false, error: { code: 'FETCH_ERROR', message: 'Navigation returned no response', url } };
+            return { ok: false, error: { code: 'FETCH_ERROR', message: 'Navigation returned no response', reason: 'unreachable', url } };
+        }
+        // A 4xx/5xx status still returns a rendered body, so goto does NOT throw — without this
+        // check we would infer a theme from an "Access Denied" or "Not Found" page. 403/429 read
+        // as a bot-block (the message a person needs); other 4xx/5xx as a plain HTTP error.
+        const status = response.status();
+        if (status >= 400) {
+            const reason = status === 403 || status === 429 ? 'blocked' : 'http_error';
+            return { ok: false, error: { code: 'FETCH_ERROR', message: `Page returned HTTP ${status}`, reason, url, status } };
+        }
+        try {
+            await page.waitForLoadState('networkidle', { timeout: NETWORK_IDLE_TIMEOUT_MS });
+        }
+        catch {
+            // Busy site — the network never idled. Proceed with what has painted.
         }
+        await page.waitForTimeout(SETTLE_MS);
         const htmlSource = await response.text();
         const renderedHtml = await page.content();
-        const screenshot = await page.screenshot({ fullPage: true });
+        // Best-effort, bounded. A `fullPage` screenshot waits for in-flight requests to settle,
+        // so on a page that never idles (the same busy sites the navigation change rescues) it
+        // would hang until its own 30s timeout and fail the whole inference. The screenshot only
+        // feeds screenshot-colour extraction, which the pipeline already treats as optional
+        // (extractImageColors is try/caught) — the styles are the primary signal. So cap it and,
+        // on timeout, proceed with an empty buffer rather than sink the request.
+        let screenshot;
+        try {
+            screenshot = await page.screenshot({ fullPage: true, timeout: SCREENSHOT_TIMEOUT_MS });
+        }
+        catch {
+            screenshot = Buffer.alloc(0);
+        }
         const title = await page.title();
+        const resolvedUrl = page.url();
+        // Returned from inside the try so the outer catch cannot relabel an extraction
+        // failure as a FETCH_ERROR; `finally` still closes the browser.
+        let evidence;
+        try {
+            evidence = await extractStylesFromPage(page, resolvedUrl);
+        }
+        catch (err) {
+            const cause = err instanceof Error ? err.message : String(err);
+            return { ok: false, error: { code: 'EXTRACTION_ERROR', message: 'Style extraction failed', reason: 'unreadable', url, cause } };
+        }
         return {
             ok: true,
             snapshot: {
-                url: page.url(),
+                url: resolvedUrl,
                 htmlSource,
                 renderedHtml,
                 screenshot,
@@ -53,11 +138,12 @@ export async function fetchAndRender(url) {
                 title,
                 fetchedAt: new Date().toISOString(),
             },
+            evidence,
         };
     }
     catch (err) {
         const cause = err instanceof Error ? err.message : String(err);
-        return { ok: false, error: { code: 'FETCH_ERROR', message: 'Headless render failed', url, cause } };
+        return { ok: false, error: { code: 'FETCH_ERROR', message: 'Headless render failed', reason: classifyNavError(cause), url, cause } };
     }
     finally {
         await browser.close();

package/dist/inferrer/pipeline.js

@@ -1,12 +1,13 @@
 import { fetchAndRender } from './page-fetcher.js';
-import { extractStyles } from './style-extractor.js';
 import { extractImageColors } from './image-extractor.js';
 import { inferTheme } from './theme-inferrer.js';
 export async function runInferencePipeline(url) {
+    // One navigation yields both the screenshot and the computed styles — the styles are
+    // read on the live page, where its stylesheets actually loaded.
     const fetchResult = await fetchAndRender(url);
     if (!fetchResult.ok)
         return { ok: false, error: fetchResult.error };
-    const { snapshot } = fetchResult;
+    const { snapshot, evidence } = fetchResult;
     let imageEvidence = undefined;
     try {
         imageEvidence = await extractImageColors(snapshot.screenshot, 'screenshot');
@@ -14,14 +15,6 @@ export async function runInferencePipeline(url) {
     catch {
         // Image extraction is best-effort — proceed without it.
     }
-    let evidence;
-    try {
-        evidence = await extractStyles(snapshot);
-    }
-    catch (err) {
-        const cause = err instanceof Error ? err.message : String(err);
-        return { ok: false, error: { code: 'EXTRACTION_ERROR', message: 'Style extraction failed', url: snapshot.url, cause } };
-    }
     const result = inferTheme(evidence, imageEvidence);
     return { ok: true, result };
 }

package/dist/inferrer/style-extractor.js

@@ -1,79 +1,134 @@
-import { loadChromium } from './page-fetcher.js';
 const SAMPLE_SELECTORS = 'body,h1,h2,h3,h4,h5,h6,p,a,button,input,select,textarea,' +
     'div,span,header,footer,nav,main,section,article,aside,ul,ol,li';
 const MAX_ELEMENTS = 200;
-export async function extractStyles(snapshot) {
-    const chromium = await loadChromium();
-    if (chromium === null) {
-        throw new Error('playwright is not installed — style extraction requires it.');
-    }
-    const browser = await chromium.launch({ headless: true });
-    try {
-        const page = await browser.newPage();
-        await page.setViewportSize({ width: 1280, height: 800 });
-        await page.setContent(snapshot.renderedHtml, { waitUntil: 'domcontentloaded' });
-        const raw = await page.evaluate(({ selectors, maxElements }) => {
-            const elements = Array.from(document.querySelectorAll(selectors)).slice(0, maxElements);
-            const colors = new Set();
-            const fontFamilies = new Set();
-            const fontSizes = new Set();
-            const borderRadii = new Set();
-            const shadows = new Set();
-            const spacings = new Set();
-            for (const el of elements) {
-                const cs = window.getComputedStyle(el);
-                for (const prop of [
-                    'color', 'background-color', 'border-top-color',
-                    'border-right-color', 'border-bottom-color', 'border-left-color', 'outline-color',
-                ]) {
-                    const v = cs.getPropertyValue(prop);
-                    if (v && v !== 'rgba(0, 0, 0, 0)')
-                        colors.add(v);
+/**
+ * Reads computed styles from a page that has already navigated to the real URL.
+ *
+ * It must be the live page. Re-rendering `page.content()` into a blank page via
+ * setContent() resolves the document against about:blank, so a site whose CSS lives in a
+ * relatively-linked stylesheet is measured completely unstyled — dembrandt.com reported a
+ * white background (it is black), zero radii, zero shadows and zero durations, all at
+ * "high" confidence. The styles must be read where the stylesheets actually loaded.
+ */
+export async function extractStylesFromPage(page, sourceUrl) {
+    const raw = await page.evaluate(({ selectors, maxElements }) => {
+        const TRANSPARENT = 'rgba(0, 0, 0, 0)';
+        // Split a comma-separated CSS list without cutting inside cubic-bezier(...).
+        const splitCssList = (value) => {
+            const parts = [];
+            let depth = 0;
+            let current = '';
+            for (const ch of value) {
+                if (ch === '(')
+                    depth++;
+                else if (ch === ')')
+                    depth--;
+                if (ch === ',' && depth === 0) {
+                    parts.push(current.trim());
+                    current = '';
                 }
-                const ff = cs.getPropertyValue('font-family');
-                if (ff)
-                    fontFamilies.add(ff);
-                const fs = cs.getPropertyValue('font-size');
-                if (fs && fs !== '0px')
-                    fontSizes.add(fs);
-                for (const prop of [
-                    'border-top-left-radius', 'border-top-right-radius',
-                    'border-bottom-right-radius', 'border-bottom-left-radius',
-                ]) {
-                    const v = cs.getPropertyValue(prop);
-                    if (v && v !== '0px')
-                        borderRadii.add(v);
-                }
-                for (const prop of ['box-shadow', 'text-shadow']) {
-                    const v = cs.getPropertyValue(prop);
-                    if (v && v !== 'none')
-                        shadows.add(v);
-                }
-                for (const prop of [
-                    'margin-top', 'margin-right', 'margin-bottom', 'margin-left',
-                    'padding-top', 'padding-right', 'padding-bottom', 'padding-left',
-                ]) {
-                    const v = cs.getPropertyValue(prop);
-                    if (v && v !== '0px')
-                        spacings.add(v);
+                else {
+                    current += ch;
                 }
             }
-            return {
-                colors: [...colors],
-                fontFamilies: [...fontFamilies],
-                fontSizes: [...fontSizes],
-                borderRadii: [...borderRadii],
-                shadows: [...shadows],
-                spacings: [...spacings],
-            };
-        }, { selectors: SAMPLE_SELECTORS, maxElements: MAX_ELEMENTS });
+            if (current.trim())
+                parts.push(current.trim());
+            return parts;
+        };
+        const durationMs = (value) => {
+            const m = /^([\d.]+)(ms|s)$/.exec(value);
+            if (!m)
+                return null;
+            const n = parseFloat(m[1]);
+            return m[2] === 's' ? n * 1000 : n;
+        };
+        const elements = Array.from(document.querySelectorAll(selectors)).slice(0, maxElements);
+        const colors = new Set();
+        const fontFamilies = new Set();
+        const fontSizes = new Set();
+        const borderRadii = new Set();
+        const shadows = new Set();
+        const spacings = new Set();
+        const motionDurations = new Set();
+        const motionEasings = new Set();
+        // CSS cycles the shorter list against the longer one, so a timing function is
+        // only meaningful next to the duration it is actually paired with.
+        const collectMotion = (cs, durationProp, easingProp) => {
+            const durations = splitCssList(cs.getPropertyValue(durationProp) || '');
+            const easings = splitCssList(cs.getPropertyValue(easingProp) || '');
+            if (easings.length === 0)
+                return;
+            durations.forEach((d, i) => {
+                const ms = durationMs(d);
+                if (ms === null || ms <= 0)
+                    return;
+                motionDurations.add(d);
+                motionEasings.add(easings[i % easings.length]);
+            });
+        };
+        for (const el of elements) {
+            const cs = window.getComputedStyle(el);
+            for (const prop of [
+                'color', 'background-color', 'border-top-color',
+                'border-right-color', 'border-bottom-color', 'border-left-color', 'outline-color',
+            ]) {
+                const v = cs.getPropertyValue(prop);
+                if (v && v !== TRANSPARENT)
+                    colors.add(v);
+            }
+            const ff = cs.getPropertyValue('font-family');
+            if (ff)
+                fontFamilies.add(ff);
+            const fs = cs.getPropertyValue('font-size');
+            if (fs && fs !== '0px')
+                fontSizes.add(fs);
+            for (const prop of [
+                'border-top-left-radius', 'border-top-right-radius',
+                'border-bottom-right-radius', 'border-bottom-left-radius',
+            ]) {
+                const v = cs.getPropertyValue(prop);
+                if (v && v !== '0px')
+                    borderRadii.add(v);
+            }
+            for (const prop of ['box-shadow', 'text-shadow']) {
+                const v = cs.getPropertyValue(prop);
+                if (v && v !== 'none')
+                    shadows.add(v);
+            }
+            for (const prop of [
+                'margin-top', 'margin-right', 'margin-bottom', 'margin-left',
+                'padding-top', 'padding-right', 'padding-bottom', 'padding-left',
+            ]) {
+                const v = cs.getPropertyValue(prop);
+                if (v && v !== '0px')
+                    spacings.add(v);
+            }
+            collectMotion(cs, 'transition-duration', 'transition-timing-function');
+            collectMotion(cs, 'animation-duration', 'animation-timing-function');
+        }
+        // Neither <body> nor <html> painting a background means the CSS canvas shows
+        // through, which a default-scheme Chromium renders white.
+        const surface = document.body ?? document.documentElement;
+        const bodyBg = surface ? window.getComputedStyle(surface).getPropertyValue('background-color') : '';
+        const htmlBg = window.getComputedStyle(document.documentElement).getPropertyValue('background-color');
+        const backgroundColor = bodyBg && bodyBg !== TRANSPARENT ? bodyBg
+            : htmlBg && htmlBg !== TRANSPARENT ? htmlBg
+                : 'rgb(255, 255, 255)';
         return {
-            ...raw,
-            sourceUrl: snapshot.url,
-            extractedAt: new Date().toISOString(),
+            colors: [...colors],
+            fontFamilies: [...fontFamilies],
+            fontSizes: [...fontSizes],
+            borderRadii: [...borderRadii],
+            shadows: [...shadows],
+            spacings: [...spacings],
+            motionDurations: [...motionDurations],
+            motionEasings: [...motionEasings],
+            backgroundColor,
         };
-    }
-    finally {
-        await browser.close();
-    }
+    }, { selectors: SAMPLE_SELECTORS, maxElements: MAX_ELEMENTS });
+    return {
+        ...raw,
+        sourceUrl,
+        extractedAt: new Date().toISOString(),
+    };
 }

package/dist/inferrer/theme-inferrer.js

@@ -1,9 +1,21 @@
+import { assessContrast } from './contrast.js';
+// Colours closer than this in RGB space read as the same surface.
+const BACKGROUND_MATCH_DISTANCE = 40;
+// A secondary must be visibly distinct from the primary, not a shade of it.
+const SECONDARY_MIN_DISTANCE = 60;
 function parseCssColor(css) {
     const m = /rgba?\(\s*(\d+)\s*,\s*(\d+)\s*,\s*(\d+)/.exec(css);
     if (!m)
         return null;
     return [parseInt(m[1], 10), parseInt(m[2], 10), parseInt(m[3], 10)];
 }
+function hexToRgb(hex) {
+    const m = /^#?([0-9a-f]{6})$/i.exec(hex.trim());
+    if (!m)
+        return null;
+    const n = parseInt(m[1], 16);
+    return [(n >> 16) & 255, (n >> 8) & 255, n & 255];
+}
 function rgbToHex(r, g, b) {
     const ch = (v) => Math.max(0, Math.min(255, Math.round(v))).toString(16).padStart(2, '0');
     return `#${ch(r)}${ch(g)}${ch(b)}`;
@@ -11,10 +23,34 @@ function rgbToHex(r, g, b) {
 function rgbRange(r, g, b) {
     return Math.max(r, g, b) - Math.min(r, g, b);
 }
+function colorDistance(a, b) {
+    return Math.sqrt((a[0] - b[0]) ** 2 + (a[1] - b[1]) ** 2 + (a[2] - b[2]) ** 2);
+}
 function parsePx(value) {
     const m = /^([\d.]+)px$/.exec(value.trim());
     return m ? parseFloat(m[1]) : null;
 }
+function parseDurationMs(value) {
+    const m = /^([\d.]+)(ms|s)$/.exec(value.trim());
+    if (!m)
+        return null;
+    const n = parseFloat(m[1]);
+    return m[2] === 's' ? n * 1000 : n;
+}
+/**
+ * A cubic-bezier whose control-point Y values escape [0,1] overshoots its target and
+ * springs back — the signature of a playful motion system rather than a functional one.
+ */
+function isOvershooting(easing) {
+    const m = /^cubic-bezier\(([^)]+)\)$/.exec(easing.trim());
+    if (!m)
+        return false;
+    const parts = m[1].split(',').map(p => parseFloat(p.trim()));
+    if (parts.length !== 4 || parts.some(Number.isNaN))
+        return false;
+    const [, y1, , y2] = parts;
+    return y1 < 0 || y1 > 1 || y2 < 0 || y2 > 1;
+}
 function median(values) {
     if (values.length === 0)
         return null;
@@ -24,15 +60,27 @@ function median(values) {
         ? (sorted[mid - 1] + sorted[mid]) / 2
         : sorted[mid];
 }
-function inferPrimaryColor(evidence, imageEvidence) {
+function isBackground(rgb, background) {
+    return background !== null && colorDistance(rgb, background) <= BACKGROUND_MATCH_DISTANCE;
+}
+function inferPrimaryColor(evidence, background, imageEvidence) {
     if (imageEvidence && imageEvidence.dominantColors.length > 0) {
-        return { value: imageEvidence.dominantColors[0].hex, confidence: 'high' };
+        // dominantColors is frequency-sorted, so [0] is whatever covers the most pixels —
+        // on a typical page that is the background, not the brand colour.
+        for (const dc of imageEvidence.dominantColors) {
+            const rgb = hexToRgb(dc.hex);
+            if (rgb && !isBackground(rgb, background)) {
+                return { value: dc.hex, confidence: 'high' };
+            }
+        }
+        // Every cluster sits on the background: a monochrome page offers nothing to prefer.
+        return { value: imageEvidence.dominantColors[0].hex, confidence: 'medium' };
     }
     let bestHex = '';
     let bestRange = -1;
     for (const css of evidence.colors) {
         const rgb = parseCssColor(css);
-        if (!rgb)
+        if (!rgb || isBackground(rgb, background))
             continue;
         const range = rgbRange(rgb[0], rgb[1], rgb[2]);
         if (range > bestRange) {
@@ -45,6 +93,33 @@ function inferPrimaryColor(evidence, imageEvidence) {
     }
     return { value: '#3b82f6', confidence: 'low' };
 }
+function inferSecondaryColor(primaryHex, evidence, background, imageEvidence) {
+    const primary = hexToRgb(primaryHex);
+    const isCandidate = (rgb) => !isBackground(rgb, background) &&
+        (primary === null || colorDistance(rgb, primary) >= SECONDARY_MIN_DISTANCE);
+    if (imageEvidence) {
+        for (const dc of imageEvidence.dominantColors) {
+            const rgb = hexToRgb(dc.hex);
+            if (rgb && isCandidate(rgb))
+                return { value: dc.hex, confidence: 'high' };
+        }
+    }
+    let bestHex = '';
+    let bestRange = -1;
+    for (const css of evidence.colors) {
+        const rgb = parseCssColor(css);
+        if (!rgb || !isCandidate(rgb))
+            continue;
+        const range = rgbRange(rgb[0], rgb[1], rgb[2]);
+        if (range > bestRange) {
+            bestRange = range;
+            bestHex = rgbToHex(rgb[0], rgb[1], rgb[2]);
+        }
+    }
+    if (bestHex)
+        return { value: bestHex, confidence: 'medium' };
+    return { value: 'auto', confidence: 'low' };
+}
 function inferTypography(fontFamilies) {
     const haystack = fontFamilies.join(' ').toLowerCase();
     if (!haystack.trim())
@@ -59,6 +134,12 @@ function inferTypography(fontFamilies) {
         [/merriweather|lora|ibm plex|source serif|humanist|charter|utopia/, 'humanist'],
         [/helvetica|avenir|gill sans|calibri|myriad|aktiv|graphik|haas/, 'minimal'],
         [/corporate|arial|verdana|trebuchet/, 'corporate'],
+        // Each pairing's own faces, per TYPOGRAPHY_FONT_FAMILIES in the token engine
+        // (components/shared/other-dimensions.js). Without these two rules 'startup' and
+        // 'creative' were unreachable — dead entries in a twelve-value contract enum.
+        // They sit above 'modern' so its broad system-font net cannot swallow them.
+        [/outfit/, 'startup'],
+        [/sora|rubik/, 'creative'],
         [/inter|roboto|system-ui|segoe|sf pro|apple system|blinkmacsystem|-apple-system/, 'modern'],
     ];
     for (const [pattern, preset] of rules) {
@@ -103,31 +184,57 @@ function inferDensity(spacings) {
         return { value: 'comfortable', confidence: 'medium' };
     return { value: 'spacious', confidence: 'medium' };
 }
+function inferMotion(durations, easings) {
+    const ms = durations
+        .map(parseDurationMs)
+        .filter((v) => v !== null && v > 0);
+    if (ms.length === 0) {
+        // Transitions declared only under :hover / :focus never surface in a base-state
+        // computed-style sample, so their absence is suggestive rather than conclusive.
+        return { value: 'instant', confidence: 'medium' };
+    }
+    if (easings.some(isOvershooting))
+        return { value: 'playful', confidence: 'high' };
+    const med = median(ms);
+    if (med < 150)
+        return { value: 'snappy', confidence: 'high' };
+    if (med <= 400)
+        return { value: 'smooth', confidence: 'high' };
+    return { value: 'playful', confidence: 'medium' };
+}
 export function inferTheme(evidence, imageEvidence) {
-    const primary = inferPrimaryColor(evidence, imageEvidence);
+    const background = evidence.backgroundColor ? parseCssColor(evidence.backgroundColor) : null;
+    const primary = inferPrimaryColor(evidence, background, imageEvidence);
+    const secondary = inferSecondaryColor(primary.value, evidence, background, imageEvidence);
     const typography = inferTypography(evidence.fontFamilies);
     const radius = inferBorderRadius(evidence.borderRadii);
     const elevation = inferElevation(evidence.shadows);
     const density = inferDensity(evidence.spacings);
+    const motion = inferMotion(evidence.motionDurations, evidence.motionEasings);
+    const primaryRgb = hexToRgb(primary.value);
+    const contrast = background && primaryRgb
+        ? assessContrast(primaryRgb, background, rgbToHex(background[0], background[1], background[2]))
+        : null;
     return {
         theme: {
             primaryColor: primary.value,
-            secondaryColor: 'auto',
+            secondaryColor: secondary.value,
             typography: typography.value,
             density: density.value,
             borderRadius: radius.value,
             elevation: elevation.value,
-            motion: 'smooth',
+            motion: motion.value,
         },
         confidence: {
             primaryColor: primary.confidence,
-            secondaryColor: 'medium',
+            secondaryColor: secondary.confidence,
             typography: typography.confidence,
             density: density.confidence,
             borderRadius: radius.confidence,
             elevation: elevation.confidence,
-            motion: 'low',
+            motion: motion.confidence,
         },
+        contrast,
         sourceUrl: evidence.sourceUrl,
         inferredAt: new Date().toISOString(),
     };

package/dist/tools/get-completeness-map.js

@@ -0,0 +1,24 @@
+import { readFileSync } from 'node:fs';
+import { resolve, dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+export const GET_COMPLETENESS_MAP_TOOL = {
+    name: 'get_completeness_map',
+    description: 'Returns the RunsNative component completeness map: which semantic UI slots have a real ' +
+        'run-* component vs raw-HTML fallback. Used by the emphasis allocation skill to know the ' +
+        'honest vocabulary boundary when assigning roles.',
+    inputSchema: {
+        type: 'object',
+        properties: {},
+        required: [],
+    },
+};
+export function handleGetCompletenessMap() {
+    // In dist/, __dirname resolves to dist/tools/; map is at ../../content/scf/.
+    const mapPath = resolve(__dirname, '../../content/scf/completeness-map.json');
+    const raw = readFileSync(mapPath, 'utf8');
+    return {
+        content: [{ type: 'text', text: raw }],
+    };
+}

package/dist/tools/get-emphasis-scale.js

@@ -0,0 +1,55 @@
+// Mirrors DEFAULT_EMPHASIS_SCALE from
+// packages/engine/src/mukadra/tools/pm_agent/emphasis_policy_schema.py.
+// Vocabulary is methodology-fixed; weights are not brand-configurable at this layer.
+const EMPHASIS_SCALE = [
+    {
+        treatment: 'focal',
+        loudness_weight: 10,
+        description: 'Loudest element in scope — primary CTA, hero heading. Exactly one per scope.',
+    },
+    {
+        treatment: 'accent',
+        loudness_weight: 5,
+        description: 'Secondary highlight — section heading, secondary CTA, badge.',
+    },
+    {
+        treatment: 'link',
+        loudness_weight: 2,
+        description: 'Navigation and inline links. Multiple allowed.',
+    },
+    {
+        treatment: 'supporting',
+        loudness_weight: 1,
+        description: 'Body copy, labels, captions. Neutral presence.',
+    },
+    {
+        treatment: 'ambient',
+        loudness_weight: 0,
+        description: 'Decorative or invisible to budget — dividers, icons used as decoration.',
+    },
+];
+export const GET_EMPHASIS_SCALE_TOOL = {
+    name: 'get_emphasis_scale',
+    description: 'Returns the canonical SCF emphasis treatment vocabulary: the five treatment levels ' +
+        '(focal → ambient), their loudness weights, and plain-language descriptions. ' +
+        'Used by the emphasis role-allocation skill to know what treatments exist and what focal costs.',
+    inputSchema: {
+        type: 'object',
+        properties: {},
+        required: [],
+    },
+};
+export function handleGetEmphasisScale() {
+    return {
+        content: [
+            {
+                type: 'text',
+                text: JSON.stringify({
+                    treatments: EMPHASIS_SCALE,
+                    methodology_note: 'Loudness weights are additive across a scope. The ceiling (brand_disposition × page_type) ' +
+                        'constrains weighted_spend = sum(weight × count). Exactly one focal per scope is the marketing rule.',
+                }, null, 2),
+            },
+        ],
+    };
+}

package/dist/tools/get-marker-capture.js

@@ -0,0 +1,91 @@
+import { McpError, ErrorCode } from '@modelcontextprotocol/sdk/types.js';
+import { getWorkerApi, getLinkedPairId } from '../bridge-client.js';
+const CROP_PREFIX = 'data:image/png;base64,';
+export const GET_MARKER_CAPTURE_TOOL = {
+    name: 'get_marker_capture',
+    description: 'Fetch pending marker captures from the linked runsnative.org tab — regions the user circled ' +
+        'with the marker overlay. Use when the user says they marked, circled, or pointed at something ' +
+        'on the site, or asks "can you see what I selected?". Each capture carries the resolved ' +
+        'component-instance address (usable with set_instance_variant), its render inputs, an optional ' +
+        'user note, and the pixel crop as an image so you see exactly what they saw. Single delivery: a ' +
+        'capture is returned once. Requires an active linked session (call link_session first).',
+    inputSchema: {
+        type: 'object',
+        properties: {},
+    },
+    // LSP §5.1 (linked-session-protocol-v0.1, mukadra repo) — session-targeting,
+    // but the READ leg of the bridge: it drains the session's capture queue
+    // rather than enacting a command, so there is no allow-list `enactment`
+    // (the field is optional per §5.1).
+    _meta: {
+        lsp: {
+            target: 'session',
+            tier: 'reversible',
+            consent: 'implicit',
+            entitlement: 'free',
+            visibility: 'advertised',
+        },
+    },
+};
+export async function handleGetMarkerCapture(_args) {
+    const pairId = getLinkedPairId();
+    if (!pairId) {
+        throw new McpError(ErrorCode.InvalidParams, 'No linked session. Call link_session with the pairing code first, or open runsnative.org and start the pairing flow.');
+    }
+    const res = await getWorkerApi(`/session/${pairId}/captures`);
+    if (res.status === 404) {
+        throw new McpError(ErrorCode.InvalidParams, 'Linked session not found or expired. Re-link with link_session.');
+    }
+    if (res.status === 410) {
+        throw new McpError(ErrorCode.InvalidParams, 'Linked session revoked or expired. Re-link with link_session.');
+    }
+    if (res.status === 409) {
+        throw new McpError(ErrorCode.InvalidParams, 'No live tab detected. Open runsnative.org, ensure the tab is active, then retry.');
+    }
+    if (!res.ok) {
+        const body = await res.text().catch(() => '');
+        throw new McpError(ErrorCode.InternalError, `Worker error ${res.status}: ${body}`);
+    }
+    const data = await res.json();
+    const captures = data.captures ?? [];
+    if (captures.length === 0) {
+        return {
+            content: [
+                {
+                    type: 'text',
+                    text: 'No pending marker captures. Ask the user to arm the marker overlay and circle a region on the linked tab.',
+                },
+            ],
+        };
+    }
+    const content = [];
+    for (const cap of captures) {
+        content.push({
+            type: 'text',
+            text: JSON.stringify({
+                capture_id: cap.capture_id,
+                address: cap.address,
+                inputs: cap.inputs,
+                note: cap.note,
+                created_at: cap.created_at,
+            }, null, 2),
+        });
+        // The pixel crop is co-equal with the structural address (design doc
+        // §3.4) — deliver it as an image block so the agent SEES the region,
+        // not a reference to it.
+        if (cap.crop && cap.crop.startsWith(CROP_PREFIX)) {
+            content.push({
+                type: 'image',
+                data: cap.crop.slice(CROP_PREFIX.length),
+                mimeType: 'image/png',
+            });
+        }
+    }
+    if (data.truncated) {
+        content.push({
+            type: 'text',
+            text: 'More pending captures remain on the worker — call get_marker_capture again to fetch them.',
+        });
+    }
+    return { content };
+}

package/dist/tools/link-session.js

@@ -0,0 +1,35 @@
+import { McpError, ErrorCode } from '@modelcontextprotocol/sdk/types.js';
+import { postWorkerApi, setLinkedPairId } from '../bridge-client.js';
+export const LINK_SESSION_TOOL = {
+    name: 'link_session',
+    description: 'Redeem a pairing code to link this MCP session to an open runsnative.org tab. ' +
+        'The user generates the code in their browser; pass it here to establish the link. ' +
+        'Required before set_brand or navigate will work.',
+    inputSchema: {
+        type: 'object',
+        properties: {
+            code: { type: 'string', description: 'Six-character pairing code shown in the browser.' },
+        },
+        required: ['code'],
+    },
+};
+export async function handleLinkSession(args) {
+    const code = args['code'];
+    if (typeof code !== 'string' || !code.trim()) {
+        throw new McpError(ErrorCode.InvalidParams, 'code must be a non-empty string');
+    }
+    const res = await postWorkerApi('/pair/redeem', { code: code.trim() });
+    if (res.status === 403) {
+        throw new McpError(ErrorCode.InvalidParams, 'Pairing code belongs to a different tenant — cannot link.');
+    }
+    if (res.status === 404) {
+        throw new McpError(ErrorCode.InvalidParams, 'Pairing code not found or already expired. Ask the user to generate a fresh code.');
+    }
+    if (!res.ok) {
+        const body = await res.text().catch(() => '');
+        throw new McpError(ErrorCode.InternalError, `Worker error ${res.status}: ${body}`);
+    }
+    const data = await res.json();
+    setLinkedPairId(data.pair_id);
+    return { content: [{ type: 'text', text: `Session linked. pair_id: ${data.pair_id}` }] };
+}

package/dist/tools/navigate.js

@@ -0,0 +1,61 @@
+import { McpError, ErrorCode } from '@modelcontextprotocol/sdk/types.js';
+import { postWorkerApi, getLinkedPairId } from '../bridge-client.js';
+export const NAVIGATE_TOOL = {
+    name: 'navigate',
+    description: "Send the user's linked runsnative.org tab to a different page. Use when the user asks to see, open, or go to " +
+        'something on the site — a component page, a docs section, the gallery — so they watch their own tab move ' +
+        'instead of following a pasted link. The command is enqueued and the tab navigates within one poll interval. ' +
+        'Reversible — the user can navigate back. Requires an active linked session (call link_session first). ' +
+        'Slash shim: /rn-go <path>.',
+    inputSchema: {
+        type: 'object',
+        properties: {
+            path: { type: 'string', description: 'Absolute path to navigate to, e.g. "/components/button".' },
+        },
+        required: ['path'],
+    },
+    // LSP §5.1 (linked-session-protocol-v0.1, mukadra repo) — marks this as a
+    // session-targeting capability. `enactment` names the worker allow-list
+    // entry this tool submits (JUNE-626).
+    _meta: {
+        lsp: {
+            target: 'session',
+            tier: 'reversible',
+            consent: 'implicit',
+            entitlement: 'free',
+            visibility: 'advertised',
+            enactment: 'navigation.navigate',
+        },
+    },
+};
+export async function handleNavigate(args) {
+    const path = args['path'];
+    if (typeof path !== 'string' || !path.trim()) {
+        throw new McpError(ErrorCode.InvalidParams, 'path must be a non-empty string');
+    }
+    const pairId = getLinkedPairId();
+    if (!pairId) {
+        throw new McpError(ErrorCode.InvalidParams, 'No linked session. Call link_session with the pairing code first, or open runsnative.org and start the pairing flow.');
+    }
+    const res = await postWorkerApi('/tenant/command', {
+        pair_id: pairId,
+        capability: 'navigation',
+        method: 'navigate',
+        args: [path.trim()],
+    });
+    if (res.status === 404) {
+        throw new McpError(ErrorCode.InvalidParams, 'Linked session not found or expired. Re-link with link_session.');
+    }
+    if (res.status === 422) {
+        const body = await res.json().catch(() => ({}));
+        throw new McpError(ErrorCode.InvalidParams, body.error ?? 'Command rejected by allow-list.');
+    }
+    if (res.status === 409) {
+        throw new McpError(ErrorCode.InvalidParams, 'No live tab detected. Open runsnative.org, ensure the tab is active, then retry.');
+    }
+    if (!res.ok) {
+        const body = await res.text().catch(() => '');
+        throw new McpError(ErrorCode.InternalError, `Worker error ${res.status}: ${body}`);
+    }
+    return { content: [{ type: 'text', text: `Navigate command enqueued: ${path.trim()}. The tab will navigate within one poll interval.` }] };
+}

package/dist/tools/set-instance-variant.js

@@ -0,0 +1,85 @@
+import { McpError, ErrorCode } from '@modelcontextprotocol/sdk/types.js';
+import { postWorkerApi, getLinkedPairId } from '../bridge-client.js';
+/** Mirrors the `variant` enum in `run-button.js` and the worker allow-list. */
+const RUN_BUTTON_VARIANTS = ['primary', 'secondary', 'outline', 'ghost', 'danger', 'link'];
+export const SET_INSTANCE_VARIANT_TOOL = {
+    name: 'set_instance_variant',
+    description: 'Restyle ONE specific run-button on the linked runsnative.org tab — the instance the user circled with the ' +
+        'marker overlay — leaving every other element untouched. Use after get_marker_capture hands you an ' +
+        'address.instanceId and the user wants that exact button tried in a different variant. The command is enqueued ' +
+        'and the tab applies it within one poll interval, if the instance is still on the page. Reversible — set it ' +
+        'back at any time. Requires an active linked session (call link_session first). Slash shim: /rn-set-variant.',
+    inputSchema: {
+        type: 'object',
+        properties: {
+            instance_id: {
+                type: 'string',
+                description: 'Instance handle from a marker-capture bundle (address.instanceId).',
+            },
+            variant: {
+                type: 'string',
+                description: `One of: ${RUN_BUTTON_VARIANTS.join(', ')}.`,
+            },
+        },
+        required: ['instance_id', 'variant'],
+    },
+    // LSP §5.1 (linked-session-protocol-v0.1, mukadra repo) — marks this as a
+    // session-targeting capability. `enactment` names the worker allow-list
+    // entry this tool submits (JUNE-626).
+    _meta: {
+        lsp: {
+            target: 'session',
+            tier: 'reversible',
+            consent: 'implicit',
+            entitlement: 'free',
+            visibility: 'advertised',
+            enactment: 'instance.setVariant',
+        },
+    },
+};
+export async function handleSetInstanceVariant(args) {
+    const instanceId = args['instance_id'];
+    if (typeof instanceId !== 'string' || !instanceId.trim()) {
+        throw new McpError(ErrorCode.InvalidParams, 'instance_id must be a non-empty string');
+    }
+    const variant = args['variant'];
+    if (typeof variant !== 'string' || !RUN_BUTTON_VARIANTS.includes(variant.trim())) {
+        throw new McpError(ErrorCode.InvalidParams, `variant must be one of: ${RUN_BUTTON_VARIANTS.join(', ')}`);
+    }
+    const pairId = getLinkedPairId();
+    if (!pairId) {
+        throw new McpError(ErrorCode.InvalidParams, 'No linked session. Call link_session with the pairing code first, or open runsnative.org and start the pairing flow.');
+    }
+    const res = await postWorkerApi('/tenant/command', {
+        pair_id: pairId,
+        capability: 'instance',
+        method: 'setVariant',
+        args: [variant.trim()],
+        instance_id: instanceId.trim(),
+    });
+    if (res.status === 404) {
+        throw new McpError(ErrorCode.InvalidParams, 'Linked session not found or expired. Re-link with link_session.');
+    }
+    if (res.status === 422) {
+        const body = await res.json().catch(() => ({}));
+        throw new McpError(ErrorCode.InvalidParams, body.error ?? 'Command rejected by allow-list.');
+    }
+    if (res.status === 409) {
+        throw new McpError(ErrorCode.InvalidParams, 'No live tab detected. Open runsnative.org, ensure the tab is active, then retry.');
+    }
+    if (!res.ok) {
+        const body = await res.text().catch(() => '');
+        throw new McpError(ErrorCode.InternalError, `Worker error ${res.status}: ${body}`);
+    }
+    // A handle that no longer resolves in the tab is dropped client-side, by design —
+    // the worker cannot resolve DOM, so enqueue success is not delivery confirmation.
+    return {
+        content: [
+            {
+                type: 'text',
+                text: `Variant command enqueued: ${variant.trim()} → instance ${instanceId.trim()}. ` +
+                    `The tab will apply it within one poll interval if that instance is still on the page.`,
+            },
+        ],
+    };
+}

package/dist/tools/set-theme.js

@@ -0,0 +1,61 @@
+import { McpError, ErrorCode } from '@modelcontextprotocol/sdk/types.js';
+import { postWorkerApi, getLinkedPairId } from '../bridge-client.js';
+export const SET_THEME_TOOL = {
+    name: 'set_theme',
+    description: "Restyle the user's linked runsnative.org tab with a named theme — colors, surfaces, and typography change live " +
+        'in their browser. Use when the user asks to change how the site looks, try a different brand feel, or compare ' +
+        'palettes. The command is enqueued and the tab applies it within one poll interval; nothing is saved — fully ' +
+        'reversible, switch again or back at any time. Requires an active linked session (call link_session first). ' +
+        'Slash shim: /rn-theme <theme>.',
+    inputSchema: {
+        type: 'object',
+        properties: {
+            theme: { type: 'string', description: 'Theme identifier, e.g. "ocean-depths" or "kehribar".' },
+        },
+        required: ['theme'],
+    },
+    // LSP §5.1 (linked-session-protocol-v0.1, mukadra repo) — marks this as a
+    // session-targeting capability. `enactment` names the worker allow-list
+    // entry this tool submits (JUNE-626).
+    _meta: {
+        lsp: {
+            target: 'session',
+            tier: 'reversible',
+            consent: 'implicit',
+            entitlement: 'free',
+            visibility: 'advertised',
+            enactment: 'theme.setTheme',
+        },
+    },
+};
+export async function handleSetTheme(args) {
+    const theme = args['theme'];
+    if (typeof theme !== 'string' || !theme.trim()) {
+        throw new McpError(ErrorCode.InvalidParams, 'theme must be a non-empty string');
+    }
+    const pairId = getLinkedPairId();
+    if (!pairId) {
+        throw new McpError(ErrorCode.InvalidParams, 'No linked session. Call link_session with the pairing code first, or open runsnative.org and start the pairing flow.');
+    }
+    const res = await postWorkerApi('/tenant/command', {
+        pair_id: pairId,
+        capability: 'theme',
+        method: 'setTheme',
+        args: [theme.trim()],
+    });
+    if (res.status === 404) {
+        throw new McpError(ErrorCode.InvalidParams, 'Linked session not found or expired. Re-link with link_session.');
+    }
+    if (res.status === 422) {
+        const body = await res.json().catch(() => ({}));
+        throw new McpError(ErrorCode.InvalidParams, body.error ?? 'Command rejected by allow-list.');
+    }
+    if (res.status === 409) {
+        throw new McpError(ErrorCode.InvalidParams, 'No live tab detected. Open runsnative.org, ensure the tab is active, then retry.');
+    }
+    if (!res.ok) {
+        const body = await res.text().catch(() => '');
+        throw new McpError(ErrorCode.InternalError, `Worker error ${res.status}: ${body}`);
+    }
+    return { content: [{ type: 'text', text: `Theme command enqueued: ${theme.trim()}. The tab will apply it within one poll interval.` }] };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@runsnative/mcp-server",
-  "version": "0.1.5",
+  "version": "0.3.0",
   "type": "module",
   "files": [
     "dist/"
@@ -20,7 +20,8 @@
     "start": "node dist/index.js",
     "http-server": "node dist/http-server.js",
     "validate": "node dist/test/validate.js",
-    "test": "vitest run"
+    "test": "vitest run",
+    "prepublishOnly": "npm run build"
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.0.0"