vantage-peers-mcp 2.3.5 → 2.4.0

package/CHANGELOG.md

@@ -1,5 +1,109 @@
 # Changelog
 
+## [2.4.0] — 2026-05-28 — M3 iframeEmbedSessions + __VP_TOOL_RESULT__ stream marker + ack-checklist
+
+**Mission instance** : `sigma-vantage-peers-mcp-gui-iframe-embed-v1` (k5730xct6rvrwkvxhy5t5js12d87jwfw).
+**Pi sign-off** : PI_AUTHORIZED_TASK_ID=`k1793m1qgn0zaay6r87dhvsh7187kwya` (PROD-DEPLOY-AUTHORIZED).
+**Eta sign-off** : ETA_APPROVED_TASK_ID=`k171ep964sxabbrgmb21fk9axd87ka1n` at commit `338a7b9e6130ce69dc5fe7f3e2e9ecc4648b4f6a` (Day 79 SHA-pinned).
+**Merge** : PR #545 squash `f509c8d92f0b142bc063a0e9dd070e1993cc729b`.
+
+M3 delivers the session registry and stream-marker protocol that connects the VP MCP server
+to the Gen UI iframe bridge. All marker emission is gated behind `VP_EMIT_UI_MARKERS=1`
+so production behaviour is unchanged until the bridge is deployed.
+
+### Convex schema — `iframeEmbedSessions` table
+
+NEW table `iframeEmbedSessions` in `convex/schema.ts` :
+- Fields : `sessionId` (string), `tenantId` (optional string), `origin` (string),
+  `userId` (optional string), `createdAt` (number), `lastSeenAt` (number),
+  `expiresAt` (number), `revoked` (boolean).
+- Indexes : `by_session_id` on `["sessionId"]`, `by_origin_expires` on `["origin", "expiresAt"]`.
+
+NEW `convex/iframeEmbedSessions.ts` — 4 operations :
+- `createSession` mutation — inserts a new session row.
+- `getSession` query — returns session or null (null for expired / revoked).
+- `touchSession` mutation — bumps `lastSeenAt` to now; returns bool.
+- `revokeSession` mutation — sets `revoked=true`; returns bool.
+
+### Stream marker — `mcp-server/src/ui-resources/stream-marker.ts`
+
+NEW `MARKER_START = "__VP_TOOL_RESULT__"`, `MARKER_END = "__END__"`.
+
+NEW `wrapToolResult(payload: VpToolResult): string` :
+- Validates via `VpToolResultSchema`, throws `TypeError` on schema failure.
+- Returns `__VP_TOOL_RESULT__<json>__END__`.
+
+NEW `parseToolResult(text: string): VpToolResult | null` :
+- Extracts marker substring (handles bare, embedded, surrounding text).
+- Returns validated `VpToolResult` or null on any failure (no-throw contract).
+
+### MCP tools — marker emission gated by `VP_EMIT_UI_MARKERS=1`
+
+`mcp-server/src/tools.ts` — 6 tools now append `wrapToolResult(...)` after the JSON payload
+when `VP_EMIT_UI_MARKERS=1` (default OFF) :
+
+| Tool                  | kind               |
+|-----------------------|--------------------|
+| `list_tasks`          | `tasks-table`      |
+| `list_messages`       | `messages-feed`    |
+| `get_diary`           | `diary-entry`      |
+| `list_missions`       | `mission-timeline` |
+| `list_briefing_notes` | `briefing-note`    |
+| `list_memories`       | `memory-quote`     |
+
+Change is surgical — existing return shape is preserved; marker is appended as a new line.
+
+### Ack checklist
+
+NEW `docs/M3-ACK-CHECKLIST.md` — bilingual FR/EN post-deploy verification checklist
+for Marie + Ismaël. Covers: package install, primitive reads, Shadow DOM scoping,
+stream marker emit + parse, bilingual spot check, WCAG AA (contrast + role attrs),
+default-OFF guard.
+
+### Tests
+
+15+ new vitest cases (≥264 total after M3, baseline 253 after M2) :
+- `mcp-server/src/__tests__/m3-stream-marker.test.ts` — 14 cases:
+  `wrapToolResult` ×6 valid kinds, ×2 throws on invalid, `parseToolResult` roundtrip,
+  non-marker text ×2, embedded text, malformed JSON ×2, schema rejects unknown kind ×2.
+- `convex/iframeEmbedSessions.test.ts` — 7 cases:
+  create+get, optional fields, getSession unknown, expired session null,
+  touchSession updates lastSeenAt, touchSession unknown false,
+  revokeSession marks revoked (getSession null), revokeSession unknown false.
+
+0 regression on M1+M2 suites (253/253 baseline).
+
+---
+
+## [Unreleased] — M1 SEP-1865 ui:// resources backend + M2 primitives + Zod schemas
+
+**Mission instance** : `sigma-vantage-peers-mcp-gui-iframe-embed-v1` (k5730xct6rvrwkvxhy5t5js12d87jwfw).
+**Template VR consumed** : `gui-iframe-embed-v1` v1.0.0 (jx7bzk0x1086tgwgj2zrssk2pn87k1ga).
+
+M1 Foundation (adapted MCP-pure paradigm per Pi arbitrage Day 84) :
+- NEW `mcp-server/src/ui-resources/index.ts` : URI parser `ui://vp/v1/<primitive>?<query>` + primitive registry + handler factory.
+- NEW `mcp-server/src/ui-resources/primitives/tasks-table.ts` : M1 MVP primitive returning HTML inline (Shadow DOM scoped CSS) — WCAG AA + bilingual FR+EN.
+- `mcp-server/server-http.ts` : wired `ListResourcesRequestSchema` + `ReadResourceRequestSchema` MCP handlers on the existing McpServer instance.
+
+Tests : 14 new vitest cases (`src/__tests__/ui-resources-sep-1865.test.ts`) — URI parsing, primitive registry, render variants (empty, populated, FR), backend arg forwarding, XSS escape, error fallback, limit clamping, unknown primitive rejection. 0 regression on existing suites.
+
+### M2 — Resolve 5 Gaps + Bearer sha256 hardening (adapted MCP-pure paradigm)
+
+5 new ui:// primitives :
+- `messages-feed` (`messages:listMessages` backend — channel filter applied client-side)
+- `diary-entry` (`diary:get` single-entry + `diary:list` multi-entry backend)
+- `mission-timeline` (`missions:list` backend with fields=lite)
+- `briefing-note` (`briefingNotes:get` by noteId OR `briefingNotes:list` by topic backend)
+- `memory-quote` (`memories:listMemories` backend — supports both plain-array and paginated result shapes)
+
+Zod discriminated union schemas : `mcp-server/src/ui-resources/schemas.ts` exports `VpTaskPayloadSchema` + `VpMessagePayloadSchema` + `VpDiaryEntryPayloadSchema` + `VpMissionPayloadSchema` + `VpBriefingNotePayloadSchema` + `VpMemoryPayloadSchema` + `VpToolResultSchema` (discriminated union by `kind`). Cross-fleet ready for Mu vantage-bridge sidepanel S3 consumer.
+
+Bearer sha256 validation : Already in place since v2.3.4 DCR security fix. `mcp-server/src/auth.ts` line 275 calls `sha256Hex(token)` before every Convex lookup (layers 2 and 4). Raw token never reaches Convex. No further hardening needed in M2.
+
+Tests : 42 new vitest cases in `src/__tests__/ui-resources-m2-primitives.test.ts` (target was ≥22). Covers : PRIMITIVES registry (6 entries), each of 5 new primitives (empty + populated + FR labels + XSS escape + error fallback = 5 cases each), Zod schema roundtrip (VpToolResultSchema all 6 variants accepted, malformed rejected, individual payload schema validations). 0 regression on M1 17 cases + 194 other MCP tests (253/253 total).
+
+M3 next : Registry json-render + `__VP_TOOL_RESULT__<json>` stream marker + smoke E2E + ack-checklist + PI-SIGNED Convex prod deploy + visual ack Marie/Ismaël.
+
 ## v2.3.5 — 2026-05-28
 
 **Critical hotfix** — v2.3.3 (PR #539) shipped the backend filters `createdBy` + `updatedSince` and the Zod schema exports but did NOT wire those params into the 4 list MCP tool args blocks. Pi pull-cycle quickstart `list_tasks createdBy="pi" status="review" fields="lite"` was silently dropping `createdBy` at the MCP boundary and returning all visible tasks. Auto-clamp safeguard (Day 83) also could not trigger because Zod `.default(50)` / `.default(20)` on `limit` overrode the absent-value signal before it reached the backend.

package/dist/server-http.js

@@ -25,13 +25,14 @@
  *   NODE_ENV              — set to "production" on Railway
  */
 import { readFileSync } from "node:fs";
-import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { McpServer, ResourceTemplate, } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { WebStandardStreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/webStandardStreamableHttp.js";
 import { ConvexHttpClient } from "convex/browser";
 import { Hono } from "hono";
 import { cors } from "hono/cors";
 import { bearerAuthMiddleware, internalClient, masterOnlyMiddleware, sha256Base64Url, sha256Hex, } from "./src/auth.js";
 import { registerTools } from "./src/tools.js";
+import { listUiResources, readUiResource } from "./src/ui-resources/index.js";
 let pkg;
 try {
     // Source mode: server-http.ts → ./package.json = mcp-server/package.json
@@ -563,6 +564,31 @@ app.all("/mcp", bearerAuthMiddleware(), async (c) => {
         version: pkg.version,
     });
     registerTools(server, convex, oauthCtx);
+    // SEP-1865 ui:// resources for Generative UI primitives
+    // Uses McpServer.resource() high-level API with a ResourceTemplate so that
+    // resources/list (via listCallback) and resources/read both work.
+    // URI pattern: ui://vp/v1/{primitive}  — query params read from the URL object.
+    const uiResourceTemplate = new ResourceTemplate("ui://vp/v1/{primitive}", {
+        list: async () => ({ resources: listUiResources() }),
+    });
+    server.resource("vp-ui", uiResourceTemplate, {
+        description: "SEP-1865 VantagePeers Generative UI primitives (HTML inline, Shadow DOM scoped)",
+    }, async (uri) => {
+        const fetchConvex = async (functionName, args) => {
+            // biome-ignore lint/suspicious/noExplicitAny: Convex string API
+            return convex.query(functionName, args);
+        };
+        const resource = await readUiResource(uri.toString(), fetchConvex);
+        return {
+            contents: [
+                {
+                    uri: resource.uri,
+                    mimeType: resource.mimeType,
+                    text: resource.text,
+                },
+            ],
+        };
+    });
     const transport = new WebStandardStreamableHTTPServerTransport();
     await server.connect(transport);
     return transport.handleRequest(c.req.raw);

package/dist/src/tools.js

@@ -10,6 +10,36 @@
 import { ErrorCode, McpError } from "@modelcontextprotocol/sdk/types.js";
 import { z } from "zod";
 import { checkFromAllowed, checkNamespaceRead, checkNamespaceWrite, isMasterScope, } from "./auth.js";
+import { wrapToolResult } from "./ui-resources/stream-marker.js";
+// ─────────────────────────────────────────────────────────────────────────────
+// VP_EMIT_UI_MARKERS gate
+//
+// When VP_EMIT_UI_MARKERS=1 the 6 list/get tools that have a matching
+// ui:// primitive append a __VP_TOOL_RESULT__<json>__END__ marker after the
+// existing JSON payload. The Gen UI iframe bridge detects this marker and
+// renders the structured primitive inline. Default is OFF so prod behaviour
+// is unchanged.
+// ─────────────────────────────────────────────────────────────────────────────
+const UI_MARKERS_ENABLED = process.env.VP_EMIT_UI_MARKERS === "1" ||
+    process.env.VP_EMIT_UI_MARKERS === "true";
+/**
+ * Append a stream marker to a text response when UI markers are enabled.
+ * `buildPayload` is called only when the flag is ON to avoid any overhead.
+ */
+function appendMarkerIfEnabled(text, buildPayload) {
+    if (!UI_MARKERS_ENABLED)
+        return text;
+    try {
+        const payload = buildPayload();
+        if (payload === null)
+            return text;
+        return `${text}\n${wrapToolResult(payload)}`;
+    }
+    catch {
+        // Never break the primary response — marker emission is best-effort.
+        return text;
+    }
+}
 // ─────────────────────────────────────────────────────────────────────────────
 // Pre-flight content size guard
 //
@@ -746,13 +776,24 @@ export function registerTools(server, convex, oauthCtx) {
                 type,
                 limit: limit ?? 20,
             });
+            const rawList = Array.isArray(memories)
+                ? memories
+                : Array.isArray(memories?.page)
+                    ? memories.page
+                    : [];
+            const baseText = JSON.stringify(memories, null, 2);
+            const text = appendMarkerIfEnabled(baseText, () => ({
+                kind: "memory-quote",
+                items: rawList.map((m) => ({
+                    _id: m._id,
+                    namespace: m.namespace,
+                    type: m.type,
+                    content: m.content,
+                    score: m.score,
+                })),
+            }));
             return {
-                content: [
-                    {
-                        type: "text",
-                        text: JSON.stringify(memories, null, 2),
-                    },
-                ],
+                content: [{ type: "text", text }],
             };
         }
         catch (error) {
@@ -1025,13 +1066,21 @@ export function registerTools(server, convex, oauthCtx) {
                 from,
                 limit: limit ?? 100,
             });
+            const baseText = JSON.stringify(messages, null, 2);
+            const text = appendMarkerIfEnabled(baseText, () => ({
+                kind: "messages-feed",
+                items: Array.isArray(messages)
+                    ? messages.map((m) => ({
+                        _id: m._id,
+                        from: m.from,
+                        channel: m.channel,
+                        content: m.content,
+                        createdAt: m.createdAt,
+                    }))
+                    : [],
+            }));
             return {
-                content: [
-                    {
-                        type: "text",
-                        text: JSON.stringify(messages, null, 2),
-                    },
-                ],
+                content: [{ type: "text", text }],
             };
         }
         catch (error) {
@@ -1169,13 +1218,22 @@ export function registerTools(server, convex, oauthCtx) {
                 createdBy,
                 updatedSince,
             });
+            const baseText = JSON.stringify(tasks, null, 2);
+            const text = appendMarkerIfEnabled(baseText, () => ({
+                kind: "tasks-table",
+                items: Array.isArray(tasks)
+                    ? tasks.map((t) => ({
+                        _id: t._id,
+                        title: t.title,
+                        status: t.status,
+                        priority: t.priority,
+                        assignedTo: t.assignedTo,
+                        _creationTime: t._creationTime,
+                    }))
+                    : [],
+            }));
             return {
-                content: [
-                    {
-                        type: "text",
-                        text: JSON.stringify(tasks, null, 2),
-                    },
-                ],
+                content: [{ type: "text", text }],
             };
         }
         catch (error) {
@@ -1598,13 +1656,23 @@ export function registerTools(server, convex, oauthCtx) {
                 fields,
                 updatedSince,
             });
+            const baseText = JSON.stringify(missions, null, 2);
+            const text = appendMarkerIfEnabled(baseText, () => ({
+                kind: "mission-timeline",
+                items: Array.isArray(missions)
+                    ? missions.map((m) => ({
+                        _id: m._id,
+                        name: m.name,
+                        project: m.project,
+                        status: m.status,
+                        pilot: m.pilot,
+                        priority: m.priority,
+                        progress: m.progress,
+                    }))
+                    : [],
+            }));
             return {
-                content: [
-                    {
-                        type: "text",
-                        text: JSON.stringify(missions, null, 2),
-                    },
-                ],
+                content: [{ type: "text", text }],
             };
         }
         catch (error) {
@@ -1759,13 +1827,24 @@ export function registerTools(server, convex, oauthCtx) {
                 date,
                 orchestrator,
             });
-            return {
-                content: [
-                    {
-                        type: "text",
-                        text: JSON.stringify(entry, null, 2),
+            const baseText = JSON.stringify(entry, null, 2);
+            const text = appendMarkerIfEnabled(baseText, () => {
+                if (!entry)
+                    return null;
+                return {
+                    kind: "diary-entry",
+                    item: {
+                        _id: entry._id,
+                        date: entry.date,
+                        orchestrator: entry.orchestrator,
+                        content: entry.content,
+                        highlights: entry.highlights,
+                        blockers: entry.blockers,
                     },
-                ],
+                };
+            });
+            return {
+                content: [{ type: "text", text }],
             };
         }
         catch (error) {
@@ -1931,13 +2010,27 @@ export function registerTools(server, convex, oauthCtx) {
                 fields,
                 updatedSince,
             });
-            return {
-                content: [
-                    {
-                        type: "text",
-                        text: JSON.stringify(notes, null, 2),
+            const baseText = JSON.stringify(notes, null, 2);
+            const text = appendMarkerIfEnabled(baseText, () => {
+                const items = Array.isArray(notes) ? notes : [];
+                if (items.length === 0)
+                    return null;
+                // Emit the first note as a briefing-note item for the primitive renderer.
+                const first = items[0];
+                return {
+                    kind: "briefing-note",
+                    item: {
+                        _id: first._id,
+                        topic: first.topic,
+                        title: first.title,
+                        participants: first.participants,
+                        content: first.content,
+                        createdBy: first.createdBy,
                     },
-                ],
+                };
+            });
+            return {
+                content: [{ type: "text", text }],
             };
         }
         catch (error) {

package/dist/src/ui-resources/index.d.ts

@@ -0,0 +1,36 @@
+/**
+ * SEP-1865 ui:// resources for VantagePeers Generative UI.
+ *
+ * URI pattern : ui://vp/v1/<primitive>?<query>
+ * Examples :
+ *   ui://vp/v1/tasks-table?assignedTo=pi&status=review&fields=lite&limit=10
+ *   ui://vp/v1/messages-feed?recipient=sigma&limit=20
+ *
+ * M1 scope : 1 primitive (tasks-table) — proves the pipeline.
+ * M2 scope : ≥6 primitives (tasks/messages/diary/missions/briefingNotes/memories).
+ *
+ * Pattern Hybrid 60% static lit-ui + 11% Gen UI + 27% Hybrid (cf vp-gui-views-research-2026-05-28.md).
+ * Returns HTML inline with embedded JS + CSS Shadow DOM scoped.
+ *
+ * Reference instance Theta : theta-vantage-crm-gui-iframe-embed-v1 (blissful-gopher-531).
+ * Mission Sigma : sigma-vantage-peers-mcp-gui-iframe-embed-v1 (k5730xct6rvrwkvxhy5t5js12d87jwfw).
+ */
+export type UiResourceParsed = {
+    primitive: string;
+    query: URLSearchParams;
+};
+export declare function parseUiUri(uri: string): UiResourceParsed | null;
+export declare const PRIMITIVES: readonly ["tasks-table", "messages-feed", "diary-entry", "mission-timeline", "briefing-note", "memory-quote"];
+export type Primitive = (typeof PRIMITIVES)[number];
+export declare const PRIMITIVE_DESCRIPTIONS: Record<Primitive, string>;
+export declare function listUiResources(): Array<{
+    uri: string;
+    name: string;
+    description: string;
+    mimeType: string;
+}>;
+export declare function readUiResource(uri: string, fetchConvex: (functionName: string, args: Record<string, unknown>) => Promise<unknown>): Promise<{
+    uri: string;
+    mimeType: string;
+    text: string;
+}>;

package/dist/src/ui-resources/index.js

@@ -0,0 +1,100 @@
+/**
+ * SEP-1865 ui:// resources for VantagePeers Generative UI.
+ *
+ * URI pattern : ui://vp/v1/<primitive>?<query>
+ * Examples :
+ *   ui://vp/v1/tasks-table?assignedTo=pi&status=review&fields=lite&limit=10
+ *   ui://vp/v1/messages-feed?recipient=sigma&limit=20
+ *
+ * M1 scope : 1 primitive (tasks-table) — proves the pipeline.
+ * M2 scope : ≥6 primitives (tasks/messages/diary/missions/briefingNotes/memories).
+ *
+ * Pattern Hybrid 60% static lit-ui + 11% Gen UI + 27% Hybrid (cf vp-gui-views-research-2026-05-28.md).
+ * Returns HTML inline with embedded JS + CSS Shadow DOM scoped.
+ *
+ * Reference instance Theta : theta-vantage-crm-gui-iframe-embed-v1 (blissful-gopher-531).
+ * Mission Sigma : sigma-vantage-peers-mcp-gui-iframe-embed-v1 (k5730xct6rvrwkvxhy5t5js12d87jwfw).
+ */
+import { renderBriefingNote } from "./primitives/briefing-note.js";
+import { renderDiaryEntry } from "./primitives/diary-entry.js";
+import { renderMemoryQuote } from "./primitives/memory-quote.js";
+import { renderMessagesFeed } from "./primitives/messages-feed.js";
+import { renderMissionTimeline } from "./primitives/mission-timeline.js";
+import { renderTasksTable } from "./primitives/tasks-table.js";
+// URI parser : ui://vp/v1/<primitive>?<query>
+const UI_URI_RE = /^ui:\/\/vp\/v1\/([a-z][a-z0-9-]*)(?:\?(.*))?$/;
+export function parseUiUri(uri) {
+    const match = UI_URI_RE.exec(uri);
+    if (!match)
+        return null;
+    const primitive = match[1];
+    const queryString = match[2] ?? "";
+    return {
+        primitive,
+        query: new URLSearchParams(queryString),
+    };
+}
+// Primitive registry — M1 ships 1 (tasks-table). M2 adds 5 more.
+export const PRIMITIVES = [
+    "tasks-table",
+    "messages-feed",
+    "diary-entry",
+    "mission-timeline",
+    "briefing-note",
+    "memory-quote",
+];
+export const PRIMITIVE_DESCRIPTIONS = {
+    "tasks-table": "Render a compact table of tasks. Query params: assignedTo, status, fields=lite|full, limit. Mirrors list_tasks tool semantics.",
+    "messages-feed": "Render a chronological feed of VantagePeers messages. Query params: from, channel, limit, lang.",
+    "diary-entry": "Render a single diary entry or list of recent entries. Query params: date (YYYY-MM-DD), orchestrator, limit, lang.",
+    "mission-timeline": "Render a missions timeline. Query params: pilot, project, status, limit, lang.",
+    "briefing-note": "Render briefing note details. Query params: noteId or (topic + limit), lang.",
+    "memory-quote": "Render memory quotes from a namespace. Query params: namespace, type, limit, lang.",
+};
+// Resource list — returned by resources/list MCP handler
+export function listUiResources() {
+    return PRIMITIVES.map((p) => ({
+        uri: `ui://vp/v1/${p}`,
+        name: p,
+        description: PRIMITIVE_DESCRIPTIONS[p],
+        mimeType: "text/html",
+    }));
+}
+// Resource read — dispatched by primitive name. Returns HTML inline.
+export async function readUiResource(uri, fetchConvex) {
+    const parsed = parseUiUri(uri);
+    if (!parsed) {
+        throw new Error(`[VP UI Resources] Invalid ui:// URI: ${uri}`);
+    }
+    if (!PRIMITIVES.includes(parsed.primitive)) {
+        throw new Error(`[VP UI Resources] Unknown primitive: ${parsed.primitive}. Available: ${PRIMITIVES.join(", ")}`);
+    }
+    let html;
+    switch (parsed.primitive) {
+        case "tasks-table":
+            html = await renderTasksTable(parsed.query, fetchConvex);
+            break;
+        case "messages-feed":
+            html = await renderMessagesFeed(parsed.query, fetchConvex);
+            break;
+        case "diary-entry":
+            html = await renderDiaryEntry(parsed.query, fetchConvex);
+            break;
+        case "mission-timeline":
+            html = await renderMissionTimeline(parsed.query, fetchConvex);
+            break;
+        case "briefing-note":
+            html = await renderBriefingNote(parsed.query, fetchConvex);
+            break;
+        case "memory-quote":
+            html = await renderMemoryQuote(parsed.query, fetchConvex);
+            break;
+        default:
+            throw new Error(`[VP UI Resources] Unimplemented primitive: ${parsed.primitive}`);
+    }
+    return {
+        uri,
+        mimeType: "text/html",
+        text: html,
+    };
+}

package/dist/src/ui-resources/primitives/briefing-note.d.ts

@@ -0,0 +1,18 @@
+/**
+ * briefing-note primitive — SEP-1865 ui:// resource.
+ * Renders a briefing note detail card or list of recent notes.
+ *
+ * Query params :
+ *   noteId   : Convex ID for a specific note (optional)
+ *   topic    : topic filter — used when noteId not provided (optional)
+ *   limit    : 1-100 (default 20) — used when noteId not provided
+ *   lang     : "en" (default) | "fr"
+ *
+ * Backend :
+ *   briefingNotes:get  — when noteId provided
+ *   briefingNotes:list — when topic or no params
+ *
+ * Output : HTML card(s) wrapped in <div class="vp-briefing-note"> with embedded CSS.
+ * WCAG AA + bilingual FR+EN labels.
+ */
+export declare function renderBriefingNote(query: URLSearchParams, fetchConvex: (functionName: string, args: Record<string, unknown>) => Promise<unknown>): Promise<string>;

package/dist/src/ui-resources/primitives/briefing-note.js

@@ -0,0 +1,126 @@
+/**
+ * briefing-note primitive — SEP-1865 ui:// resource.
+ * Renders a briefing note detail card or list of recent notes.
+ *
+ * Query params :
+ *   noteId   : Convex ID for a specific note (optional)
+ *   topic    : topic filter — used when noteId not provided (optional)
+ *   limit    : 1-100 (default 20) — used when noteId not provided
+ *   lang     : "en" (default) | "fr"
+ *
+ * Backend :
+ *   briefingNotes:get  — when noteId provided
+ *   briefingNotes:list — when topic or no params
+ *
+ * Output : HTML card(s) wrapped in <div class="vp-briefing-note"> with embedded CSS.
+ * WCAG AA + bilingual FR+EN labels.
+ */
+// Minimal escape — avoid XSS in injected content
+function esc(s) {
+    return s.replace(/[&<>"']/g, (c) => {
+        switch (c) {
+            case "&":
+                return "&amp;";
+            case "<":
+                return "&lt;";
+            case ">":
+                return "&gt;";
+            case '"':
+                return "&quot;";
+            case "'":
+                return "&#39;";
+            default:
+                return c;
+        }
+    });
+}
+function renderNoteCard(note, lang) {
+    const participantsLabel = lang === "fr" ? "Participants" : "Participants";
+    const byLabel = lang === "fr" ? "Par" : "By";
+    const participantsHtml = note.participants && note.participants.length > 0
+        ? `<div class="vp-briefing-participants">
+      <span class="vp-briefing-label">${esc(participantsLabel)} :</span>
+      ${note.participants.map((p) => `<span class="vp-briefing-pill">${esc(p)}</span>`).join(" ")}
+    </div>`
+        : "";
+    const createdByHtml = note.createdBy
+        ? `<div class="vp-briefing-meta">${esc(byLabel)}: ${esc(note.createdBy)}</div>`
+        : "";
+    const contentHtml = note.content
+        ? `<div class="vp-briefing-content">${esc(note.content)}</div>`
+        : "";
+    return `<article class="vp-briefing-card" aria-label="${esc(note.title)}">
+  <header class="vp-briefing-header">
+    <span class="vp-briefing-topic">${esc(note.topic)}</span>
+    <h3 class="vp-briefing-title">${esc(note.title)}</h3>
+  </header>
+  ${participantsHtml}
+  ${contentHtml}
+  ${createdByHtml}
+</article>`;
+}
+export async function renderBriefingNote(query, fetchConvex) {
+    const noteId = query.get("noteId") ?? undefined;
+    const topic = query.get("topic") ?? undefined;
+    const limitRaw = query.get("limit");
+    const limitParsed = limitRaw !== null ? Number.parseInt(limitRaw, 10) : Number.NaN;
+    const limit = Number.isNaN(limitParsed)
+        ? 20
+        : Math.min(100, Math.max(1, limitParsed));
+    const lang = (query.get("lang") ?? "en").toLowerCase();
+    const heading = lang === "fr"
+        ? "Notes de briefing VantagePeers"
+        : "VantagePeers Briefing Notes";
+    const emptyLabel = lang === "fr"
+        ? "Aucune note de briefing trouvée."
+        : "No briefing notes found.";
+    let notes = [];
+    try {
+        if (noteId) {
+            const result = (await fetchConvex("briefingNotes:get", {
+                noteId,
+            }));
+            notes = result ? [result] : [];
+        }
+        else {
+            const args = { limit };
+            if (topic)
+                args.topic = topic;
+            const result = (await fetchConvex("briefingNotes:list", args));
+            notes = Array.isArray(result) ? result : [];
+        }
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        return `<div class="vp-briefing-note-error" role="alert">${esc(msg)}</div>`;
+    }
+    const style = `<style>
+    .vp-briefing-note { font-family: system-ui, -apple-system, sans-serif; font-size: 13px; color: #1f2328; }
+    .vp-briefing-card { border: 1px solid #d0d7de; border-radius: 8px; padding: 16px; margin-bottom: 12px; background: #fff; }
+    .vp-briefing-header { margin-bottom: 10px; }
+    .vp-briefing-topic { display: inline-block; padding: 2px 8px; border-radius: 12px; font-size: 11px; font-weight: 500; background: #ddf4ff; color: #0969da; margin-bottom: 6px; }
+    .vp-briefing-title { font-size: 14px; font-weight: 600; margin: 0; }
+    .vp-briefing-participants { margin-top: 8px; display: flex; flex-wrap: wrap; align-items: center; gap: 4px; }
+    .vp-briefing-label { color: #656d76; }
+    .vp-briefing-pill { display: inline-block; padding: 2px 8px; border-radius: 12px; font-size: 11px; background: #f6f8fa; border: 1px solid #d0d7de; }
+    .vp-briefing-content { margin-top: 10px; line-height: 1.6; white-space: pre-wrap; word-break: break-word; }
+    .vp-briefing-meta { margin-top: 8px; color: #656d76; font-size: 12px; }
+    .vp-briefing-count { color: #656d76; font-size: 12px; margin-top: 8px; }
+    .vp-briefing-empty { color: #656d76; padding: 12px 0; }
+  </style>`;
+    if (notes.length === 0) {
+        return `<div class="vp-briefing-note" role="region" aria-label="${esc(heading)}">
+  ${style}
+  <p class="vp-briefing-empty">${esc(emptyLabel)}</p>
+</div>`;
+    }
+    const cards = notes.map((n) => renderNoteCard(n, lang)).join("\n");
+    const countLabel = lang === "fr"
+        ? `${notes.length} note${notes.length === 1 ? "" : "s"}`
+        : `${notes.length} note${notes.length === 1 ? "" : "s"}`;
+    return `<div class="vp-briefing-note" role="region" aria-label="${esc(heading)}">
+  ${style}
+  ${cards}
+  <div class="vp-briefing-count" aria-live="polite">${esc(countLabel)}</div>
+</div>`;
+}