Supersede older widget instances

import { registerAppTool } from "@modelcontextprotocol/ext-apps/server";
import { z } from "zod";

let callSeq = 0;

registerAppTool(
  server,
  "show_cart",
  {
    title: "Show cart",
    description: "Render the user's shopping cart as an interactive widget.",
    inputSchema: { items: z.array(z.string()).optional() },
    _meta: { ui: { resourceUri: "ui://cart-demo/cart.html" } },
  },
  async ({ items }) => {
    const list = items ?? [];
    const seq = ++callSeq;
    const createdAt = Date.now();
    return {
      content: [{ type: "text", text: `Cart rendered with ${list.length} item(s).` }],
      // The election key travels with the tool result in the transcript,
      // so rehydrated widgets on any device recover the same ordering.
      structuredContent: { items: list, seq, createdAt },
    };
  },
);

import { App } from "@modelcontextprotocol/ext-apps";

type CartResult = { items?: string[]; createdAt?: number; seq?: number };

const app = new App({ name: "cart-demo", version: "1.0.0" });

let superseded = false;
let keyFinalized = false;
let orderKey: number | undefined;
let seq: number | undefined;
let items: string[] = [];

app.addEventListener("toolresult", (params) => {
  const sc = params.structuredContent as CartResult | undefined;
  if (sc?.items) items = sc.items;
  if (sc && Number.isFinite(sc.createdAt)) {
    orderKey = sc.createdAt;
    seq = Number.isFinite(sc.seq) ? sc.seq : undefined;
    keyFinalized = true;
    announce(); // defined in "Broadcast and compare on a shared channel" below
  }
});

await app.connect();
const hostContext = app.getHostContext();
const instanceId = hostContext?.toolInfo?.id ?? crypto.randomUUID();

const channel = new BroadcastChannel("my-app-cart-supersede");
const peers = new Map<string, { orderKey: number; seq?: number; instanceId: string }>();

function isYounger(other: { orderKey: number; seq?: number; instanceId: string }) {
  // keyFinalized guards every call site, so orderKey is set by the time this runs.
  if (other.orderKey !== orderKey) return other.orderKey > orderKey!;
  if (other.seq != null && seq != null && other.seq !== seq) return other.seq > seq;
  return String(other.instanceId) > String(instanceId);
}

function recompute() {
  superseded = [...peers.values()].some(isYounger);
  render(); // defined in "Reflect the state in the UI" below
}

channel.onmessage = (ev) => {
  const msg = ev.data;
  if (!msg || msg.instanceId === instanceId) return;
  if (!keyFinalized) return;
  if (msg.type === "hello") {
    channel.postMessage({ type: "born", instanceId, orderKey, seq });
  }
  peers.set(msg.instanceId, msg);
  recompute();
};

function announce() {
  channel.postMessage({ type: "hello", instanceId, orderKey, seq });
  channel.postMessage({ type: "born", instanceId, orderKey, seq });
}

// addButton, card, badge: elements in your widget's DOM.
// pickRandomItem: your own helper that returns a string.

function updateModelContext() {
  if (superseded) return;
  app.updateModelContext({
    content: [{ type: "text", text: `Cart has ${items.length} item(s): ${items.join(", ")}.` }],
  });
}

addButton.onclick = () => {
  if (superseded) return;
  items.push(pickRandomItem());
  render();
  updateModelContext();
};

function render() {
  card.classList.toggle("superseded", superseded);
  badge.textContent = superseded ? "Superseded" : "Live";
  addButton.disabled = superseded;
}

let resolveServerKey!: (k: { orderKey: number; seq?: number }) => void;
const serverKeyReady = new Promise<{ orderKey: number; seq?: number }>(
  (r) => (resolveServerKey = r),
);

// Replaces the toolresult listener from the first widget snippet.
app.addEventListener("toolresult", (params) => {
  const sc = params.structuredContent as CartResult | undefined;
  if (sc?.items) items = sc.items;
  if (sc && Number.isFinite(sc.createdAt)) {
    resolveServerKey({ orderKey: sc.createdAt!, seq: sc.seq });
  }
});

// Place after the announce() definition in the broadcast snippet,
// so channel is initialized before announce() runs.
const serverKey = await Promise.race([
  serverKeyReady,
  new Promise<null>((r) => setTimeout(() => r(null), 1000)),
]);
orderKey = serverKey?.orderKey ?? Date.now();
seq = serverKey?.seq;
keyFinalized = true;
announce();

type KeySource = "server" | "client";
let keySource: KeySource = "client";

function isYounger(other: { orderKey: number; seq?: number; instanceId: string; keySource: KeySource }) {
  if ((other.keySource === "server") !== (keySource === "server")) return false;
  // keyFinalized guards every call site, so orderKey is set by the time this runs.
  if (other.orderKey !== orderKey) return other.orderKey > orderKey!;
  if (other.seq != null && seq != null && other.seq !== seq) return other.seq > seq;
  return String(other.instanceId) > String(instanceId);
}