npm - madarx - Versions diffs - 2.18.0 → 2.21.0 - Mend

madarx 2.18.0 → 2.21.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (1274) hide show

package/lib/delegation-contracts.js CHANGED Viewed

@@ -72,6 +72,7 @@ export const LIVE_EVENT_TYPES = [
   'agent.run.status',
   'agent.run.event',
   'agent.run.log',
+  'chat_turn',
 ];
 const LEGAL_TASK_TRANSITIONS = {

package/lib/higgsfield-media-card.js ADDED Viewed

@@ -0,0 +1,221 @@
+/**
+ * Deterministic, madarX-branded card for Higgsfield generation results.
+ * Rendered into the canvas when higgsfield_generate_image / _video succeeds, so
+ * the user sees the generated media in the space instead of a raw tool JSON blob.
+ *
+ * Brand: Onyx / Bone / Graphite with a single Mars-red accent. No emojis; the
+ * media itself is the focal element.
+ */
+function esc(value) {
+  return String(value ?? '')
+    .replace(/&/g, '&amp;')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;')
+    .replace(/"/g, '&quot;');
+}
+/**
+ * Gallery variant: embed one or more generated media items directly, with an
+ * optional caption and a collapsible spec/report block below. Used by the
+ * sub-agent path so a delegated generation shows the actual image on the canvas
+ * instead of a markdown document that merely links to it.
+ *
+ * @param {Array<{url:string, kind?:'image'|'video', thumbnail?:string}>} media
+ * @param {object} opts { title?, caption?, reportHtml? }
+ * @returns {string} full HTML document
+ */
+export function buildHiggsfieldGalleryHtml(media = [], opts = {}) {
+  const items = (Array.isArray(media) ? media : []).filter((m) => m && m.url);
+  const title = esc(opts.title || 'Higgsfield');
+  const caption = esc(opts.caption || '');
+  const tiles = items.map((m) => {
+    const url = esc(m.url);
+    return (m.kind === 'video')
+      ? `<video class="media" src="${url}" controls loop muted playsinline poster="${esc(m.thumbnail || '')}"></video>`
+      : `<a class="frame" href="${url}" target="_blank" rel="noopener"><img class="media" src="${url}" alt="${caption || 'Generated media'}" loading="lazy" /></a>`;
+  }).join('\n');
+  return `<!DOCTYPE html>
+<html lang="en">
+<head>
+<meta charset="utf-8" />
+<meta name="viewport" content="width=device-width, initial-scale=1" />
+<title>${title}</title>
+<style>
+  :root { --onyx:#0f0f10; --graphite:#1b1b1e; --bone:#f4f1ea; --muted:#9a968d; --mars:#d4452f; --line:#2a2a2e; }
+  * { box-sizing:border-box; margin:0; padding:0; }
+  body { background:radial-gradient(120% 100% at 50% 0%, #161618 0%, var(--onyx) 60%); color:var(--bone);
+    font-family:ui-sans-serif,-apple-system,"SF Pro Text","Segoe UI",system-ui,sans-serif; min-height:100vh;
+    padding:clamp(20px,4vw,48px); display:flex; flex-direction:column; align-items:center; gap:18px; }
+  .head { width:min(960px,100%); display:flex; align-items:baseline; justify-content:space-between; gap:16px; }
+  .brand { font-size:12px; letter-spacing:.18em; text-transform:uppercase; color:var(--muted); }
+  .brand b { color:var(--bone); font-weight:600; }
+  .grid { width:min(960px,100%); display:grid; gap:14px;
+    grid-template-columns:repeat(auto-fit,minmax(280px,1fr)); }
+  .frame { display:block; border:1px solid var(--line); border-radius:16px; overflow:hidden; background:#0b0b0c;
+    box-shadow:0 30px 80px -45px rgba(0,0,0,.9); }
+  .media { display:block; width:100%; height:auto; max-height:78vh; object-fit:contain; background:#0b0b0c; }
+  .cap { width:min(960px,100%); font-size:14px; line-height:1.5; color:#d9d5cc; }
+  .report { width:min(960px,100%); border-top:1px solid var(--line); padding-top:16px; }
+  .report summary { cursor:pointer; color:var(--muted); font-size:12px; letter-spacing:.08em; text-transform:uppercase; }
+  .report-body { margin-top:12px; font-size:13.5px; line-height:1.55; color:#cfcabf; }
+  .report-body table { border-collapse:collapse; width:100%; margin:8px 0; }
+  .report-body td, .report-body th { border:1px solid var(--line); padding:6px 9px; text-align:left; }
+</style>
+</head>
+<body>
+  <header class="head"><span class="brand"><b>Higgsfield</b> &middot; ${title}</span></header>
+  <div class="grid">${tiles || '<p class="cap">No media returned.</p>'}</div>
+  ${caption ? `<p class="cap">${caption}</p>` : ''}
+  ${opts.reportHtml ? `<details class="report"><summary>Design spec &amp; notes</summary><div class="report-body">${opts.reportHtml}</div></details>` : ''}
+</body>
+</html>`;
+}
+/**
+ * @param {object} result   The adapter output: { ok, status, url, thumbnail, job_set_id }
+ * @param {object} meta      { kind: 'image'|'video', prompt?: string }
+ * @returns {string} full HTML document
+ */
+export function buildHiggsfieldMediaHtml(result = {}, meta = {}) {
+  const kind = meta.kind === 'video' ? 'video' : 'image';
+  const url = esc(result.url || '');
+  const prompt = esc(meta.prompt || '');
+  const status = esc(result.status || 'completed');
+  const label = kind === 'video' ? 'Video' : 'Image';
+  const media = kind === 'video'
+    ? `<video class="media" src="${url}" controls autoplay loop muted playsinline poster="${esc(result.thumbnail || '')}"></video>`
+    : `<img class="media" src="${url}" alt="${prompt || 'Generated image'}" />`;
+  const promptBlock = prompt
+    ? `<p class="prompt">${prompt}</p>`
+    : '';
+  return `<!DOCTYPE html>
+<html lang="en">
+<head>
+<meta charset="utf-8" />
+<meta name="viewport" content="width=device-width, initial-scale=1" />
+<title>Higgsfield ${label}</title>
+<style>
+  :root {
+    --onyx: #0f0f10;
+    --graphite: #1b1b1e;
+    --bone: #f4f1ea;
+    --muted: #9a968d;
+    --mars: #d4452f;
+    --line: #2a2a2e;
+  }
+  * { box-sizing: border-box; margin: 0; padding: 0; }
+  body {
+    background: radial-gradient(120% 100% at 50% 0%, #161618 0%, var(--onyx) 60%);
+    color: var(--bone);
+    font-family: ui-sans-serif, -apple-system, "SF Pro Text", "Segoe UI", system-ui, sans-serif;
+    min-height: 100vh;
+    display: flex;
+    align-items: center;
+    justify-content: center;
+    padding: clamp(20px, 5vw, 56px);
+  }
+  .card {
+    width: min(880px, 100%);
+    background: var(--graphite);
+    border: 1px solid var(--line);
+    border-radius: 18px;
+    overflow: hidden;
+    box-shadow: 0 30px 80px -40px rgba(0,0,0,0.9);
+  }
+  .head {
+    display: flex;
+    align-items: baseline;
+    justify-content: space-between;
+    gap: 16px;
+    padding: 18px 22px;
+    border-bottom: 1px solid var(--line);
+  }
+  .brand {
+    font-size: 12px;
+    letter-spacing: 0.18em;
+    text-transform: uppercase;
+    color: var(--muted);
+  }
+  .brand b { color: var(--bone); font-weight: 600; }
+  .status {
+    font-size: 11px;
+    letter-spacing: 0.12em;
+    text-transform: uppercase;
+    color: var(--mars);
+    display: inline-flex;
+    align-items: center;
+    gap: 7px;
+  }
+  .status::before {
+    content: "";
+    width: 7px; height: 7px; border-radius: 50%;
+    background: var(--mars);
+  }
+  .stage {
+    background: #0b0b0c;
+    display: flex;
+    align-items: center;
+    justify-content: center;
+    padding: 0;
+  }
+  .media {
+    display: block;
+    width: 100%;
+    max-height: 70vh;
+    object-fit: contain;
+    background: #0b0b0c;
+  }
+  .foot { padding: 18px 22px 22px; }
+  .prompt {
+    font-size: 15px;
+    line-height: 1.55;
+    color: #d9d5cc;
+  }
+  .meta {
+    margin-top: 14px;
+    display: flex;
+    flex-wrap: wrap;
+    gap: 10px;
+  }
+  .pill {
+    font-size: 12px;
+    color: var(--muted);
+    border: 1px solid var(--line);
+    border-radius: 999px;
+    padding: 5px 11px;
+  }
+  .open {
+    margin-top: 16px;
+    display: inline-block;
+    font-size: 13px;
+    color: var(--bone);
+    text-decoration: none;
+    border-bottom: 1px solid var(--mars);
+    padding-bottom: 2px;
+  }
+</style>
+</head>
+<body>
+  <main class="card">
+    <header class="head">
+      <span class="brand"><b>Higgsfield</b> &middot; ${label}</span>
+      <span class="status">${status}</span>
+    </header>
+    <div class="stage">${media}</div>
+    <div class="foot">
+      ${promptBlock}
+      <div class="meta">
+        <span class="pill">Source: Higgsfield AI</span>
+        <span class="pill">Type: ${label}</span>
+      </div>
+      ${url ? `<a class="open" href="${url}" target="_blank" rel="noopener">Open original</a>` : ''}
+    </div>
+  </main>
+</body>
+</html>`;
+}

package/lib/marketplace-seeds.js CHANGED Viewed

@@ -310,6 +310,87 @@ function buildBusinessSkillSeed(s) {
   };
 }
+// ── Higgsfield AI skills (github bundle) ─────────────────────────────────────
+// MIT-licensed image/video generation skill pack from higgsfield-ai/skills.
+// Each skill drives the Higgsfield AI generation API, so they are external-write
+// capable and require a Higgsfield API key — NOT default-on.
+const HIGGSFIELD_SKILLS = [
+  {
+    slug: 'higgsfield-generate', title: 'Higgsfield — Generate',
+    invocation: '/higgsfield:generate', upstream: 'higgsfield-generate',
+    description: 'Generate images and videos across 30+ models (Flux, Kling, Veo, etc.), with Marketing Studio for branded ads and a Virality Predictor for scoring.',
+    trigger_examples: ['generate an image', 'make a video with kling', 'predict virality'],
+    uses_tools: ['higgsfield_generate_image', 'higgsfield_generate_video'],
+  },
+  {
+    slug: 'higgsfield-soul-id', title: 'Higgsfield — Soul ID',
+    invocation: '/higgsfield:soul-id', upstream: 'higgsfield-soul-id',
+    description: 'Train reusable, face-faithful identity models and return reference IDs for use in later generation tasks.',
+    trigger_examples: ['train a soul id', 'create a face identity model', 'reusable avatar identity'],
+    uses_tools: ['higgsfield_generate_image'],
+  },
+  {
+    slug: 'higgsfield-product-photoshoot', title: 'Higgsfield — Product Photoshoot',
+    invocation: '/higgsfield:product-photoshoot', upstream: 'higgsfield-product-photoshoot',
+    description: 'Create brand-quality product imagery in 10 modes — studio, lifestyle, Pinterest, hero banner, ad packs, virtual try-on, and more.',
+    trigger_examples: ['product photoshoot', 'studio shots of this product', 'lifestyle product images'],
+    uses_tools: ['higgsfield_product_photoshoot', 'higgsfield_generate_image'],
+  },
+  {
+    slug: 'higgsfield-marketplace-cards', title: 'Higgsfield — Marketplace Cards',
+    invocation: '/higgsfield:marketplace-cards', upstream: 'higgsfield-marketplace-cards',
+    description: 'Generate marketplace product cards with compliant images and A+ style modules.',
+    trigger_examples: ['marketplace product card', 'a+ content module', 'listing card images'],
+    uses_tools: ['higgsfield_generate_image'],
+  },
+];
+function buildHiggsfieldSkillSeed(s) {
+  return {
+    slug: s.slug,
+    title: s.title,
+    description: s.description,
+    category: 'media',
+    author: 'higgsfield-ai',
+    source_kind: 'github',
+    source_url: `https://github.com/higgsfield-ai/skills/tree/main/${s.upstream}`,
+    version: null,
+    risk_summary: 'Calls the external Higgsfield AI generation API and requires a Higgsfield API key. Generation is an external write — keep approval-gated.',
+    tags: ['design', 'media', 'image-generation', 'video-generation', 'higgsfield', 'mit'],
+    manifest: {
+      invocation: s.invocation,
+      upstream_slug: s.upstream,
+      trigger_examples: s.trigger_examples,
+      uses_tools: s.uses_tools,
+      requires_connection: 'higgsfield',
+    },
+  };
+}
+const HIGGSFIELD_BUNDLE = {
+  slug: 'higgsfield',
+  title: 'Higgsfield AI Skills',
+  description:
+    'MIT-licensed image and video generation pack from higgsfield-ai/skills: generate across 30+ models, train Soul ID identities, run product photoshoots, and build marketplace cards.',
+  category: 'media',
+  author: 'higgsfield-ai',
+  source_kind: 'github',
+  source_url: 'https://github.com/higgsfield-ai/skills',
+  version: null,
+  risk_summary:
+    'External generation bundle — every skill calls the Higgsfield AI API and needs a Higgsfield API key. No code executes locally, but generation is an external write; keep approval-gated.',
+  tags: ['design', 'media', 'image-generation', 'video-generation', 'higgsfield', 'mit'],
+  manifest: {
+    item_refs: HIGGSFIELD_SKILLS.map(s => `skill:${s.slug}`),
+    published_count: HIGGSFIELD_SKILLS.length,
+    license: 'MIT',
+    requires_connection: 'higgsfield',
+    unlocks_tool_slugs: ['higgsfield_generate_image', 'higgsfield_product_photoshoot', 'higgsfield_generate_video'],
+    install_hint: 'npx skills add higgsfield-ai/skills',
+    note: 'Requires a Higgsfield API key. Connect Higgsfield (Connections) to add your key, then the generate image/video tools are usable.',
+  },
+};
 const BUNDLE_SEEDS = [
   {
     slug: 'gstack',
@@ -487,6 +568,8 @@ export function seedMarketplaceItems(db) {
     for (const s of BUSINESS_SKILL_SEEDS) upsertItem(db, 'skill', buildBusinessSkillSeed(s));
     for (const s of BUSINESS_SUITE_SKILL_SEEDS) upsertItem(db, 'skill', buildSuiteSkillSeed(s));
     for (const seed of SKILL_SEEDS) upsertItem(db, 'skill', seed);
+    for (const s of HIGGSFIELD_SKILLS) upsertItem(db, 'skill', buildHiggsfieldSkillSeed(s));
+    upsertItem(db, 'bundle', HIGGSFIELD_BUNDLE);
     for (const seed of BUNDLE_SEEDS) upsertItem(db, 'bundle', seed);
     for (const curated of OPEN_DESIGN_CURATED_SKILLS) {
       upsertItem(db, 'skill', buildOpenDesignSkillSeed(curated));
@@ -547,5 +630,7 @@ export const BUSINESS_SUITE_SKILL_SLUGS = BUSINESS_SUITE_SKILL_SEEDS.map(s => s.
 export { BUSINESS_SUITE_MODULE_SEED };
 export const PHASE1_SKILL_SLUGS = SKILL_SEEDS.map(s => s.slug);
 export const PHASE1_BUNDLE_SLUGS = BUNDLE_SEEDS.map(s => s.slug);
+export const HIGGSFIELD_SKILL_SLUGS = HIGGSFIELD_SKILLS.map(s => s.slug);
+export const HIGGSFIELD_BUNDLE_SLUG = HIGGSFIELD_BUNDLE.slug;
 export const OPEN_DESIGN_SKILL_SLUGS = OPEN_DESIGN_CURATED_SKILLS.map(s => `open-design-${s.slug}`);
 export const OPEN_DESIGN_BUNDLE_SLUG = OPEN_DESIGN_BUNDLE.slug;

package/lib/marketplace.js CHANGED Viewed

@@ -148,6 +148,9 @@ function shapeNonToolItem(row, installRow) {
         : (Array.isArray(manifest.item_refs) ? manifest.item_refs.length : 0),
       license: manifest.license || null,
       note: manifest.note || null,
+      requires_connection: manifest.requires_connection || null,
+      unlocks_tool_slugs: Array.isArray(manifest.unlocks_tool_slugs) ? manifest.unlocks_tool_slugs : [],
+      install_hint: manifest.install_hint || null,
     };
   } else if (row.kind === 'workflow') {
     // Workflow templates ship a `source_spec_json` payload — the same shape
@@ -350,11 +353,7 @@ export function setItemInstalled(id, installed) {
   }
   if (item.kind === 'bundle') {
-    return {
-      status: 'deferred',
-      reason: 'Bundle install lands in Phase 2 (GitHub importer).',
-      item,
-    };
+    return setBundleInstalled(item, installed);
   }
   if (item.kind === 'connection') {
@@ -403,6 +402,59 @@ export function setItemInstalled(id, installed) {
   return getItem(id);
 }
+/**
+ * Install or uninstall a bundle.
+ *
+ * A bundle is a curated set of skills/tools referenced by `manifest.item_refs`
+ * (e.g. "skill:higgsfield-generate", "skill:design-shotgun"). Installing a
+ * bundle installs each referenced item through the same single write path
+ * (setItemInstalled), then flags the bundle row itself. Uninstall reverses it.
+ *
+ * If the bundle declares `manifest.requires_connection`, the result carries a
+ * `requires_connection` hint so the UI can prompt the user to add the API key —
+ * the bundle still installs (skills become available); generation just needs the
+ * connection before it can run.
+ */
+function setBundleInstalled(item, installed) {
+  const refs = Array.isArray(item.bundle?.item_refs) ? item.bundle.item_refs : [];
+  const results = [];
+  for (const ref of refs) {
+    // Refs are full item ids ("skill:slug" / "tool:slug"). Skip bundle refs to
+    // avoid recursion; only leaf items install here.
+    if (typeof ref !== 'string' || ref.startsWith('bundle:')) continue;
+    const child = getItem(ref);
+    if (!child) continue;
+    try {
+      setItemInstalled(child.id, installed);
+      results.push({ id: child.id, ok: true });
+    } catch (err) {
+      results.push({ id: child.id, ok: false, error: String(err?.message || err) });
+    }
+  }
+  // Flag the bundle row in marketplace_installations.
+  const db = getDb();
+  const now = nowIso();
+  const existing = db
+    .prepare('SELECT item_id FROM marketplace_installations WHERE item_id=?')
+    .get(item.id);
+  if (existing) {
+    db.prepare('UPDATE marketplace_installations SET installed=?, installed_at=? WHERE item_id=?')
+      .run(installed ? 1 : 0, installed ? now : null, item.id);
+  } else {
+    db.prepare('INSERT INTO marketplace_installations (item_id, installed, installed_at) VALUES (?, ?, ?)')
+      .run(item.id, installed ? 1 : 0, installed ? now : null);
+  }
+  const requiresConnection = item.bundle?.requires_connection || item.manifest?.requires_connection || null;
+  return {
+    status: installed ? 'installed' : 'uninstalled',
+    item: getItem(item.id),
+    installed_items: results,
+    requires_connection: installed ? requiresConnection : null,
+  };
+}
 /**
  * Install or uninstall a marketplace workflow template.
  *

package/lib/orchestrator-broadcast.js ADDED Viewed

@@ -0,0 +1,126 @@
+// Phase 2 of chat live continuity: a process-local broadcaster that decouples a
+// running orchestrator turn from the HTTP request that started it.
+//
+// While a turn streams, the route mirrors every SSE event here via `publish`.
+// A client that navigates away and back (or opens a second tab) reconnects to
+// `/api/orchestrator/stream/attach`, which `subscribe`s with the last sequence
+// it saw: the broadcaster replays the buffered tail, then streams live events
+// until the turn ends. On `endTurn` the entry is retained briefly so a client
+// reconnecting right at the finish still gets the terminal `__end`.
+//
+// Local-first / single-process: state is in-memory, keyed off globalThis so it
+// survives Next.js HMR. If the process restarts mid-turn the buffer is lost —
+// Phase 1's persisted per-turn messages + TTL flag are the durable fallback.
+const RETENTION_MS = Number(process.env.MADARX_TURN_BUFFER_RETENTION_MS) || 30000;
+const MAX_BUFFER = Number(process.env.MADARX_TURN_BUFFER_MAX) || 1000;
+// Per-session live-subscriber cap. Single-user local-first app: a handful of
+// tabs is the realistic ceiling. Guards against a client loop opening unbounded
+// attach connections. Mirrors the MAX_SUBSCRIBERS discipline in events/stream.
+const MAX_SUBSCRIBERS = Number(process.env.MADARX_TURN_MAX_SUBSCRIBERS) || 8;
+function registry() {
+  if (!globalThis.__madarxTurnBroadcast) {
+    globalThis.__madarxTurnBroadcast = new Map(); // session_id -> turn
+  }
+  return globalThis.__madarxTurnBroadcast;
+}
+// Fan a control/event frame out to every subscriber. Subscribers receive
+// { seq, event, data } where event '__end' is the terminal frame.
+function fanout(turn, frame) {
+  for (const cb of turn.subscribers) {
+    try { cb(frame); } catch { /* one bad subscriber can't break the turn */ }
+  }
+}
+// Begin (or replace) the live turn for a session. If a prior turn is still
+// live for this session it is ended first so its subscribers detach cleanly.
+export function beginTurn(sessionId, turnId) {
+  if (!sessionId || !turnId) return;
+  const reg = registry();
+  const existing = reg.get(sessionId);
+  if (existing && existing.status === 'live' && existing.turnId !== turnId) {
+    endTurn(sessionId, existing.turnId);
+  }
+  reg.set(sessionId, {
+    turnId,
+    seq: 0,
+    buffer: [],
+    subscribers: new Set(),
+    status: 'live',
+    cleanupTimer: null,
+  });
+}
+// Mirror one SSE event into the turn buffer + live subscribers. `data` is kept
+// in its raw form (string or object) exactly as the route's emit() passes it,
+// so attach can re-serialise it identically.
+export function publish(sessionId, turnId, event, data) {
+  const turn = registry().get(sessionId);
+  if (!turn || turn.turnId !== turnId || turn.status !== 'live') return;
+  const frame = { seq: ++turn.seq, event, data };
+  turn.buffer.push(frame);
+  if (turn.buffer.length > MAX_BUFFER) turn.buffer.shift();
+  fanout(turn, frame);
+}
+// End the live turn. Emits a terminal `__end` frame, then schedules the entry
+// for deletion after RETENTION_MS (idempotent; a new turn cancels it).
+export function endTurn(sessionId, turnId) {
+  const reg = registry();
+  const turn = reg.get(sessionId);
+  if (!turn || turn.turnId !== turnId) return;
+  if (turn.status === 'live') {
+    turn.status = 'done';
+    const frame = { seq: ++turn.seq, event: '__end', data: {} };
+    turn.buffer.push(frame);
+    fanout(turn, frame);
+    turn.subscribers.clear();
+  }
+  if (turn.cleanupTimer) clearTimeout(turn.cleanupTimer);
+  turn.cleanupTimer = setTimeout(() => {
+    const cur = reg.get(sessionId);
+    if (cur && cur.turnId === turnId) reg.delete(sessionId);
+  }, RETENTION_MS);
+  if (typeof turn.cleanupTimer?.unref === 'function') turn.cleanupTimer.unref();
+}
+// Snapshot of the active turn for a session, or null. `lastSeq` lets a caller
+// decide whether it already has everything.
+export function getActiveTurn(sessionId) {
+  const turn = registry().get(sessionId);
+  if (!turn) return null;
+  return { turnId: turn.turnId, status: turn.status, lastSeq: turn.seq };
+}
+// Subscribe to a turn, replaying buffered frames with seq > fromSeq first, then
+// streaming live ones. Returns an unsubscribe fn. If the turn is already done,
+// replays the tail (incl. `__end`) and does not register a live listener.
+export function subscribe(sessionId, fromSeq, cb) {
+  const turn = registry().get(sessionId);
+  if (!turn) return () => {};
+  const from = Number.isFinite(fromSeq) ? fromSeq : 0;
+  for (const frame of turn.buffer) {
+    if (frame.seq > from) {
+      try { cb(frame); } catch { /* ignore */ }
+    }
+  }
+  if (turn.status !== 'live') return () => {};
+  if (turn.subscribers.size >= MAX_SUBSCRIBERS) {
+    // At capacity: the caller still got the buffered replay above; it just
+    // won't receive live tail frames. Better than leaking unbounded listeners.
+    return () => {};
+  }
+  turn.subscribers.add(cb);
+  return () => { turn.subscribers.delete(cb); };
+}
+// Test helper — wipe all turns.
+export function __resetTurnBroadcast() {
+  const reg = registry();
+  for (const turn of reg.values()) {
+    if (turn.cleanupTimer) clearTimeout(turn.cleanupTimer);
+  }
+  reg.clear();
+}