@runsnative/mcp-server 0.5.0 → 0.6.0

package/dist/server.js

@@ -21,6 +21,7 @@ import { SET_THEME_TOOL, handleSetTheme } from './tools/set-theme.js';
 import { APPLY_INFERRED_THEME_TOOL, handleApplyInferredTheme } from './tools/apply-inferred-theme.js';
 import { NAVIGATE_TOOL, handleNavigate } from './tools/navigate.js';
 import { SET_INSTANCE_VARIANT_TOOL, handleSetInstanceVariant } from './tools/set-instance-variant.js';
+import { SPOTLIGHT_TOOL, handleSpotlight } from './tools/spotlight.js';
 import { GET_MARKER_CAPTURE_TOOL, handleGetMarkerCapture } from './tools/get-marker-capture.js';
 import { createProvider } from './provider.js';
 import { RemoteContentProvider } from './remote-provider.js';
@@ -64,6 +65,7 @@ export async function createRunsnativeServer() {
             APPLY_INFERRED_THEME_TOOL,
             NAVIGATE_TOOL,
             SET_INSTANCE_VARIANT_TOOL,
+            SPOTLIGHT_TOOL,
             GET_MARKER_CAPTURE_TOOL,
         ],
     }));
@@ -107,6 +109,8 @@ export async function createRunsnativeServer() {
                 return handleNavigate(request.params.arguments ?? {});
             case 'set_instance_variant':
                 return handleSetInstanceVariant(request.params.arguments ?? {});
+            case 'spotlight':
+                return handleSpotlight(request.params.arguments ?? {});
             case 'get_marker_capture':
                 return handleGetMarkerCapture(request.params.arguments ?? {});
             default:

package/dist/surface/gathering-card.js

@@ -72,6 +72,7 @@ const CARD_BODY = `
   </div>
   <div class="card-actions">
     <run-button id="view-btn" variant="primary" size="sm">View on Convene</run-button>
+    <run-button id="show-me-btn" variant="secondary" size="sm">Show me where</run-button>
   </div>
   <div class="card-status" id="card-status"></div>
 </article>
@@ -86,6 +87,17 @@ const { App } = globalThis.__MCP_APP_SDK__;
 const BRAND_ID = /^[a-z0-9][a-z0-9-]*$/;
 const ACCENT_HEX = /^#[0-9a-fA-F]{3,8}$/;
 
+// The current gathering's spotlight anchor, captured at render. The anchor
+// mirrors the data-tour="gathering-<id>" the Convene page (compare.js) puts on
+// each card. Sanitized to the safe attribute/URL charset so a hostile id can
+// never break out of the anchor or the deep-link query.
+let spotlightAnchor = null;
+
+function anchorFor(id) {
+  const safe = String(id == null ? '' : id).replace(/[^A-Za-z0-9_-]/g, '');
+  return safe ? 'gathering-' + safe : null;
+}
+
 function setText(id, value) {
   document.getElementById(id).textContent = value == null ? '' : String(value);
 }
@@ -94,6 +106,7 @@ function render(payload) {
   const g = payload && payload.gathering;
   if (!g) return;
   const card = document.getElementById('card');
+  spotlightAnchor = anchorFor(g.id);
 
   // Theme: landed brands get their token-engine CSS (scoped to
   // :where([data-run-theme="X"])); everything else falls back to the accent.
@@ -150,6 +163,32 @@ document.getElementById('view-btn').addEventListener('click', async () => {
   }
 });
 
+// Deixis (JUNE-621): point the linked tab at THIS gathering — navigate to
+// Convene and settle the spotlight ring on the user's own card. When no tab is
+// linked, degrade to a shareable "spotlight link" (independently valuable, the
+// same deep link a human hands another human).
+document.getElementById('show-me-btn').addEventListener('click', async () => {
+  const status = document.getElementById('card-status');
+  if (!spotlightAnchor) {
+    status.textContent = 'This gathering has no addressable anchor yet.';
+    return;
+  }
+  const target = '/compare/#' + spotlightAnchor;
+  const deepLink = 'https://runsnative.org/compare/?spotlight=' + encodeURIComponent(spotlightAnchor);
+  status.textContent = 'Pointing your tab at your gathering…';
+  try {
+    const result = await app.callServerTool({
+      name: 'spotlight',
+      arguments: { target: target, message: 'Here it is — your gathering, live on Convene.' },
+    });
+    status.textContent = result && result.isError
+      ? 'No linked tab — open your spotlight link: ' + deepLink
+      : 'Watch your linked tab — the ring is landing on your gathering.';
+  } catch (e) {
+    status.textContent = 'No linked tab — open your spotlight link: ' + deepLink;
+  }
+});
+
 await app.connect();
 `;
 export function buildGatheringCardHtml(assets) {

package/dist/test/validate.js

@@ -136,7 +136,7 @@ console.log('\nget_foundation');
 console.log('\nlistFoundations');
 {
     const foundations = await listFoundations();
-    check('returns 7 foundations', () => assert(foundations.length === 7, `expected 7 foundations, got ${foundations.length}`));
+    check('returns 8 foundations', () => assert(foundations.length === 8, `expected 8 foundations, got ${foundations.length}`));
     check('includes color', () => assert(foundations.some((f) => f.foundation === 'color'), 'missing color'));
     check('includes typography', () => assert(foundations.some((f) => f.foundation === 'typography'), 'missing typography'));
     check('each foundation has title and description', () => {
@@ -214,7 +214,7 @@ console.log('\nlist_exercises');
 {
     const ready = await listExerciseMeta(false);
     const all = await listExerciseMeta(true);
-    check('returns all three ready exercises', () => assert(ready.length === 3, `expected 3 ready exercises, got ${ready.length}`));
+    check('returns all four ready exercises', () => assert(ready.length === 4, `expected 4 ready exercises, got ${ready.length}`));
     check('each exercise has required fields', () => {
         for (const ex of ready) {
             assert(typeof ex.name === 'string' && ex.name.length > 0, `exercise missing name`);
@@ -284,6 +284,40 @@ console.log('\nget_step');
     });
 }
 // ---------------------------------------------------------------------------
+// Coached exercise slice — live-session binding (JUNE-625)
+//
+// migrate-to-runsnative step 5 gained a "Coached Mode" section that drives
+// the bridge's set_theme on the learner's own linked session; step 7
+// verifies the result via get_marker_capture. Regression guard: the coached
+// content must exist, name the correct bridge tools, and the exercise's
+// step count must have grown to 7 without disturbing steps 1-6.
+// ---------------------------------------------------------------------------
+console.log('\ncoached exercise slice (JUNE-625)');
+{
+    const detail = await getExerciseDetail('migrate-to-runsnative');
+    check('migrate-to-runsnative now has 7 steps', () => assert(detail.steps.length === 7, `expected 7 steps, got ${detail.steps.length}`));
+    const step5 = await getExerciseStep('migrate-to-runsnative', 5);
+    check('step 5 documents Coached Mode', () => assert(step5.content.includes('Coached Mode'), 'missing Coached Mode section'));
+    check('step 5 names set_theme', () => assert(step5.content.includes('set_theme'), 'missing set_theme reference'));
+    check('step 5 links to /ai/linked-session', () => assert(step5.content.includes('/ai/linked-session'), 'missing linked-session doc link'));
+    const step7 = await getExerciseStep('migrate-to-runsnative', 7);
+    check('step 7 returned with content', () => {
+        assert(step7.step === 7, `expected step 7, got ${step7.step}`);
+        assert(step7.title === 'Prove the live change (if linked)', `expected title match, got ${step7.title}`);
+    });
+    check('step 7 names get_marker_capture', () => assert(step7.content.includes('get_marker_capture'), 'missing get_marker_capture reference'));
+    check('step 7 is opt-in (skip guidance present)', () => assert(/skip/i.test(step7.content), 'missing skip-if-not-linked guidance'));
+    check('step 8 out-of-range throws RangeError', async () => {
+        try {
+            await getExerciseStep('migrate-to-runsnative', 8);
+            throw new Error('should have thrown');
+        }
+        catch (err) {
+            assert(err instanceof RangeError, `expected RangeError, got ${err.constructor.name}`);
+        }
+    });
+}
+// ---------------------------------------------------------------------------
 // Exercise ↔ live-site wiring (RUN-354)
 //
 // Regression guard for the RUN-326 defect class: exercises that referenced

package/dist/tools/apply-inferred-theme.js

@@ -19,11 +19,11 @@ export const APPLY_INFERRED_THEME_TOOL = {
         },
         required: ['brief'],
     },
-    // LSP §5.1 — session-targeting; the first entitlement:'paid' capability on
-    // the bridge (JUNE-650). `enactment` names the worker allow-list entry the
-    // command leg submits after the paid inference leg succeeds.
+    // Copresence Protocol §5.1 — session-targeting; the first entitlement:'paid'
+    // capability on the bridge (JUNE-650). `enactment` names the worker
+    // allow-list entry the command leg submits after the paid inference leg succeeds.
     _meta: {
-        lsp: {
+        copresence: {
             target: 'session',
             tier: 'reversible',
             consent: 'implicit',

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

@@ -13,12 +13,12 @@ export const GET_MARKER_CAPTURE_TOOL = {
         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).
+    // Copresence Protocol §5.1 (copresence-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: {
+        copresence: {
             target: 'session',
             tier: 'reversible',
             consent: 'implicit',

package/dist/tools/navigate.js

@@ -14,11 +14,11 @@ export const NAVIGATE_TOOL = {
         },
         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).
+    // Copresence Protocol §5.1 (copresence-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: {
+        copresence: {
             target: 'session',
             tier: 'reversible',
             consent: 'implicit',

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

@@ -23,11 +23,11 @@ export const SET_INSTANCE_VARIANT_TOOL = {
         },
         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).
+    // Copresence Protocol §5.1 (copresence-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: {
+        copresence: {
             target: 'session',
             tier: 'reversible',
             consent: 'implicit',

package/dist/tools/set-theme.js

@@ -14,11 +14,11 @@ export const SET_THEME_TOOL = {
         },
         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).
+    // Copresence Protocol §5.1 (copresence-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: {
+        copresence: {
             target: 'session',
             tier: 'reversible',
             consent: 'implicit',

package/dist/tools/spotlight.js

@@ -0,0 +1,85 @@
+import { McpError, ErrorCode } from '@modelcontextprotocol/sdk/types.js';
+import { postWorkerApi, getLinkedPairId } from '../bridge-client.js';
+export const SPOTLIGHT_TOOL = {
+    name: 'spotlight',
+    description: "Point at something on the user's linked runsnative.org tab — a spotlight ring settles on a named " +
+        'element while the rest of the page dims (non-modal, they can still interact). Use to SHOW rather than ' +
+        'describe: "show me where X lives", "highlight the Y control". The target is a contract anchor ' +
+        '(a data-tour name the design system maintains), optionally prefixed with a route to point across ' +
+        'pages: "/compare/#gathering-g-1" navigates the tab there first, "quick-start" points on the current ' +
+        'page. Optional message shows a small card by the ring. Requires an active linked session (call ' +
+        'link_session first); fully reversible — the ring dismisses on "Got it", Escape, or navigation.',
+    inputSchema: {
+        type: 'object',
+        properties: {
+            target: {
+                type: 'string',
+                description: 'Contract anchor to point at. Bare anchor ("quick-start") points on the current page; ' +
+                    '"/route#anchor" ("/compare/#gathering-g-1") points across pages, navigating there first.',
+            },
+            message: {
+                type: 'string',
+                description: 'Optional short text shown in a card beside the spotlight ring.',
+            },
+        },
+        required: ['target'],
+    },
+    // Copresence Protocol §5.1 (copresence-protocol-v0.1, mukadra repo) —
+    // session-targeting capability. `enactment` names the worker allow-list
+    // entry this tool submits.
+    _meta: {
+        copresence: {
+            target: 'session',
+            tier: 'reversible',
+            consent: 'implicit',
+            entitlement: 'free',
+            visibility: 'advertised',
+            enactment: 'tour.spotlight',
+        },
+    },
+};
+export async function handleSpotlight(args) {
+    const target = args['target'];
+    if (typeof target !== 'string' || !target.trim()) {
+        throw new McpError(ErrorCode.InvalidParams, 'target must be a non-empty string');
+    }
+    const message = args['message'];
+    if (message !== undefined && typeof message !== 'string') {
+        throw new McpError(ErrorCode.InvalidParams, 'message must be a string when present');
+    }
+    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 commandArgs = [target.trim()];
+    if (typeof message === 'string' && message.trim())
+        commandArgs.push(message.trim());
+    const res = await postWorkerApi('/tenant/command', {
+        pair_id: pairId,
+        capability: 'tour',
+        method: 'spotlight',
+        args: commandArgs,
+    });
+    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: `Spotlight command enqueued for "${target.trim()}". The tab will settle the ring within one poll interval.`,
+            },
+        ],
+    };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@runsnative/mcp-server",
-  "version": "0.5.0",
+  "version": "0.6.0",
   "type": "module",
   "files": [
     "dist/"