@liebstoeckel/engine 0.3.5

package/src/live/breakout.tsx

@@ -0,0 +1,235 @@
+import { createContext, useContext, useEffect, useState, type CSSProperties, type ReactNode } from "react";
+import { createPortal } from "react-dom";
+import { motion } from "motion/react";
+import { StageScaleContext } from "../Stage";
+import { useCoarsePointer } from "../useCoarsePointer";
+import { breakoutEligible } from "../mobile";
+
+/** Set false to suppress the touch breakout for plugins in a subtree (e.g. the
+ *  presenter's non-interactive slide preview). */
+export const BreakoutAllowedContext = createContext(true);
+
+/** Whether a plugin should offer tap-to-expand instead of inline interaction. */
+export function useBreakoutEligible(interactive: boolean): boolean {
+  const scale = useContext(StageScaleContext);
+  const allowed = useContext(BreakoutAllowedContext);
+  const coarse = useCoarsePointer();
+  return breakoutEligible({ allowed, coarse, scale, interactive });
+}
+
+/** A pulsing brand-accent ring + "tap to interact" pill around a (non-interactive)
+ *  plugin preview. Tapping anywhere opens the full-size breakout. */
+export function GlowTap({ label, onOpen, children }: { label: string; onOpen: () => void; children: ReactNode }) {
+  return (
+    <div
+      role="button"
+      tabIndex={0}
+      aria-label={`${label}, tap to interact`}
+      data-pi-no-nav
+      onClick={onOpen}
+      onKeyDown={(e) => {
+        if (e.key === "Enter" || e.key === " ") {
+          e.preventDefault();
+          onOpen();
+        }
+      }}
+      style={{ position: "relative", cursor: "pointer", borderRadius: "1.1rem", display: "inline-block", maxWidth: "100%" }}
+    >
+      <motion.span
+        aria-hidden
+        style={{
+          position: "absolute",
+          inset: "-3px",
+          borderRadius: "1.2rem",
+          border: "1px solid var(--brand-accent, #e0c580)",
+          boxShadow: "0 0 26px -4px var(--brand-accent, #e0c580)",
+          pointerEvents: "none",
+        }}
+        animate={{ opacity: [0.45, 1, 0.45] }}
+        transition={{ duration: 2.2, repeat: Infinity, ease: "easeInOut" }}
+      />
+      <div style={{ pointerEvents: "none" }}>{children}</div>
+      <span
+        style={{
+          position: "absolute",
+          bottom: "-0.7rem",
+          left: "50%",
+          transform: "translateX(-50%)",
+          whiteSpace: "nowrap",
+          padding: "0.25rem 0.7rem",
+          borderRadius: "999px",
+          background: "var(--brand-accent, #e0c580)",
+          color: "var(--brand-on-primary, #10140e)",
+          fontFamily: "var(--brand-font-mono, monospace)",
+          fontSize: "0.7rem",
+          letterSpacing: "0.12em",
+          textTransform: "uppercase",
+          fontWeight: 600,
+          pointerEvents: "none",
+        }}
+      >
+        tap to interact ↗
+      </span>
+    </div>
+  );
+}
+
+/** True on a short viewport (landscape phone / small window), switch the breakout
+ *  from a full-width bottom sheet to a centered, height-capped card so its content
+ *  doesn't overflow off the bottom. */
+function useShortViewport(): boolean {
+  const [short, setShort] = useState(false);
+  useEffect(() => {
+    if (typeof matchMedia !== "function") return;
+    const mq = matchMedia("(max-height: 600px)");
+    const update = () => setShort(mq.matches);
+    update();
+    mq.addEventListener?.("change", update);
+    return () => mq.removeEventListener?.("change", update);
+  }, []);
+  return short;
+}
+
+/** Track the **visual viewport**, the region NOT covered by the on-screen keyboard.
+ *  On mobile the keyboard overlays the layout viewport (`100vh`/`inset:0` don't shrink),
+ *  so a bottom-anchored sheet ends up behind it. Pinning to `visualViewport` keeps the
+ *  sheet in the visible area. Returns null when unsupported (desktop / SSR) → caller
+ *  falls back to full-viewport. */
+function useVisualViewport(): { height: number; offsetTop: number } | null {
+  const [vp, setVp] = useState<{ height: number; offsetTop: number } | null>(null);
+  useEffect(() => {
+    const vv = typeof window !== "undefined" ? window.visualViewport : undefined;
+    if (!vv) return;
+    const update = () => setVp({ height: vv.height, offsetTop: vv.offsetTop });
+    update();
+    vv.addEventListener("resize", update);
+    vv.addEventListener("scroll", update);
+    return () => {
+      vv.removeEventListener("resize", update);
+      vv.removeEventListener("scroll", update);
+    };
+  }, []);
+  return vp;
+}
+
+/** A full-size breakout portaled OUTSIDE the scaled stage, so the plugin's real
+ *  controls render at device scale with proper tap targets. Same Yjs state. A
+ *  bottom sheet on tall viewports; a centered, scrollable card on short/landscape
+ *  ones so the content never runs off-screen. */
+export function BreakoutSheet({ label, onClose, children }: { label: string; onClose: () => void; children: ReactNode }) {
+  const short = useShortViewport();
+  const vp = useVisualViewport();
+  useEffect(() => {
+    const onKey = (e: KeyboardEvent) => {
+      if (e.key === "Escape") onClose();
+    };
+    window.addEventListener("keydown", onKey);
+    const prev = document.body.style.overflow;
+    document.body.style.overflow = "hidden";
+    return () => {
+      window.removeEventListener("keydown", onKey);
+      document.body.style.overflow = prev;
+    };
+  }, [onClose]);
+
+  if (typeof document === "undefined") return null;
+
+  return createPortal(
+    <motion.div
+      onClick={onClose}
+      initial={{ opacity: 0 }}
+      animate={{ opacity: 1 }}
+      exit={{ opacity: 0 }}
+      style={{
+        // pin to the visual viewport so the on-screen keyboard can't bury the sheet
+        // (it overlays the layout viewport; `inset:0` would sit behind it). ADR 0037.
+        position: "fixed",
+        left: 0,
+        right: 0,
+        top: vp ? vp.offsetTop : 0,
+        height: vp ? vp.height : "100%",
+        zIndex: 9999,
+        display: "flex",
+        flexDirection: "column",
+        justifyContent: short ? "center" : "flex-end",
+        alignItems: "center",
+        padding: short ? "max(env(safe-area-inset-top), 0.75rem) 0.75rem" : 0,
+        background: "color-mix(in srgb, var(--brand-bg, #10140e) 60%, transparent)",
+        backdropFilter: "blur(6px)",
+      }}
+    >
+      <motion.div
+        data-pi-breakout
+        onClick={(e) => e.stopPropagation()}
+        initial={{ y: short ? 24 : "100%", opacity: short ? 0 : 1 }}
+        animate={{ y: 0, opacity: 1 }}
+        exit={{ y: short ? 24 : "100%", opacity: short ? 0 : 1 }}
+        transition={{ type: "spring", stiffness: 320, damping: 36 }}
+        style={{
+          width: "100%",
+          maxWidth: short ? "560px" : "720px",
+          marginInline: "auto",
+          maxHeight: short ? "100%" : "min(88vh, 100%)",
+          overflow: "auto",
+          padding: short
+            ? "0 1.1rem 1.1rem"
+            : "0 1.25rem calc(1.5rem + env(safe-area-inset-bottom))",
+          borderRadius: short ? "1.2rem" : "1.4rem 1.4rem 0 0",
+          background: "var(--brand-surface, #1a2014)",
+          border: short
+            ? "1px solid var(--brand-border, color-mix(in srgb, var(--brand-text, #e9e6d7) 14%, transparent))"
+            : "none",
+          borderTop: "1px solid var(--brand-border, color-mix(in srgb, var(--brand-text, #e9e6d7) 14%, transparent))",
+          boxShadow: "0 -24px 60px -20px rgba(0,0,0,0.7)",
+        }}
+      >
+        {/* sticky header so the close button stays reachable while the body scrolls */}
+        <div
+          style={{
+            position: "sticky",
+            top: 0,
+            zIndex: 1,
+            display: "flex",
+            alignItems: "center",
+            justifyContent: "space-between",
+            padding: "1.1rem 0 0.9rem",
+            marginBottom: "0.4rem",
+            background: "var(--brand-surface, #1a2014)",
+          }}
+        >
+          <span
+            style={{
+              fontFamily: "var(--brand-font-mono, monospace)",
+              fontSize: "0.7rem",
+              letterSpacing: "0.22em",
+              textTransform: "uppercase",
+              color: "var(--brand-muted, #9da28c)",
+            }}
+          >
+            {label}
+          </span>
+          <button
+            onClick={onClose}
+            aria-label="close"
+            style={{
+              appearance: "none",
+              cursor: "pointer",
+              border: "none",
+              background: "transparent",
+              color: "var(--brand-muted, #9da28c)",
+              fontSize: "1.2rem",
+              lineHeight: 1,
+              padding: "0.25rem 0.5rem",
+            }}
+          >
+            ✕
+          </button>
+        </div>
+        {/* shrink the plugin's content a touch on short viewports so it fits with
+            less scrolling (zoom reflows, unlike transform) */}
+        <div style={short ? ({ zoom: 0.85 } as CSSProperties) : undefined}>{children}</div>
+      </motion.div>
+    </motion.div>,
+    document.body,
+  );
+}

package/src/live/connect.ts

@@ -0,0 +1,149 @@
+import * as Y from "yjs";
+import type { LiveInfo } from "./detect";
+
+export interface LiveConnection {
+  doc: Y.Doc;
+  onStatus(cb: (connected: boolean) => void): void;
+  close(): void;
+}
+
+export interface ConnectOptions {
+  WS?: typeof WebSocket;
+  /** base reconnect delay (ms); backs off exponentially, capped */
+  reconnectBaseMs?: number;
+  reconnectMaxMs?: number;
+  /** force-reconnect if no frame (incl. server keepalives) arrives within this
+   *  window, detects half-open sockets the browser won't `close`. 0 = disabled. */
+  staleMs?: number;
+  /** After this many consecutive failed (re)connect attempts the session is likely
+   *  *gone* (re-provisioned to a new relay session) rather than a transient blip, so
+   *  retrying the same URL will 403 forever (ADR 0071 §5 / ticket 0018). Fire
+   *  `onUnrecoverable` once to recover via the stable link. 0 = never (default). */
+  reloadAfterAttempts?: number;
+  /** Recovery action when the session looks gone. Default: reload the page (which
+   *  re-resolves the stable `/live/:slug` → the new relay session) where possible. */
+  onUnrecoverable?: () => void;
+}
+
+/** Connect a Yjs doc to the live server over WebSocket, with auto-reconnect and a
+ *  liveness watchdog. On (re)open it pushes local state up and the server replies
+ *  with the full session state; thereafter updates flow both ways. Survives
+ *  network blips and silently-dead (half-open) connections. */
+export function connectLive(info: LiveInfo, participant: string, opts: ConnectOptions = {}): LiveConnection {
+  const WS = opts.WS ?? WebSocket;
+  const baseMs = opts.reconnectBaseMs ?? 1000;
+  const maxMs = opts.reconnectMaxMs ?? 15000;
+  const staleMs = opts.staleMs ?? 60000;
+  const reloadAfter = opts.reloadAfterAttempts ?? 0;
+  const onUnrecoverable =
+    opts.onUnrecoverable ??
+    (() => {
+      if (typeof location !== "undefined") location.reload();
+    });
+  let escalated = false;
+  const doc = new Y.Doc();
+  const sep = info.ws.includes("?") ? "&" : "?";
+  const url = `${info.ws}${sep}p=${encodeURIComponent(participant)}`;
+  const statusCbs: Array<(c: boolean) => void> = [];
+  const emit = (c: boolean) => statusCbs.forEach((cb) => cb(c));
+
+  let ws: WebSocket | null = null;
+  let closed = false;
+  let attempt = 0;
+  let timer: ReturnType<typeof setTimeout> | undefined;
+  let lastMsgAt = Date.now();
+  let watchdog: ReturnType<typeof setInterval> | undefined;
+
+  const onUpdate = (update: Uint8Array, origin: unknown) => {
+    if (origin !== "remote" && ws && ws.readyState === ws.OPEN) ws.send(new Uint8Array(update));
+  };
+  doc.on("update", onUpdate);
+
+  const schedule = () => {
+    if (closed) return;
+    // Persistent failure → the session is likely gone (re-provisioned). Stop hammering
+    // the dead URL and escalate to stable-link recovery exactly once (ticket 0018).
+    if (reloadAfter > 0 && attempt >= reloadAfter && !escalated) {
+      escalated = true;
+      onUnrecoverable();
+      return;
+    }
+    const delay = Math.min(baseMs * 2 ** attempt, maxMs);
+    attempt++;
+    timer = setTimeout(open, delay);
+  };
+
+  // watchdog: if the socket is OPEN but we've heard nothing within staleMs, the
+  // connection is likely half-open, drop it so `close` triggers a reconnect.
+  if (staleMs > 0) {
+    const period = Math.min(Math.max(Math.floor(staleMs / 3), 20), 30000);
+    watchdog = setInterval(() => {
+      if (closed || !ws || ws.readyState !== ws.OPEN) return;
+      if (Date.now() - lastMsgAt > staleMs) {
+        try {
+          ws.close();
+        } catch {
+          /* close handler reconnects */
+        }
+      }
+    }, period);
+    (watchdog as { unref?: () => void }).unref?.();
+  }
+
+  function open() {
+    if (closed) return;
+    const sock = new WS(url);
+    ws = sock;
+    sock.binaryType = "arraybuffer";
+    sock.addEventListener("open", () => {
+      attempt = 0;
+      lastMsgAt = Date.now();
+      try {
+        sock.send(new Uint8Array(Y.encodeStateAsUpdate(doc)));
+      } catch {
+        /* ignore */
+      }
+      emit(true);
+    });
+    sock.addEventListener("message", (e: MessageEvent) => {
+      lastMsgAt = Date.now(); // any frame (update or keepalive) proves liveness
+      try {
+        Y.applyUpdate(doc, new Uint8Array(e.data as ArrayBuffer), "remote");
+      } catch {
+        /* ignore malformed frame */
+      }
+    });
+    sock.addEventListener("close", () => {
+      emit(false);
+      schedule();
+    });
+    sock.addEventListener("error", () => {
+      try {
+        sock.close();
+      } catch {
+        /* the close handler will reconnect */
+      }
+    });
+  }
+
+  open();
+
+  return {
+    doc,
+    onStatus(cb) {
+      statusCbs.push(cb);
+    },
+    close() {
+      closed = true;
+      if (timer) clearTimeout(timer);
+      if (watchdog) clearInterval(watchdog);
+      doc.off("update", onUpdate);
+      try {
+        ws?.close();
+      } catch {
+        /* ignore */
+      }
+      doc.destroy();
+    },
+  };
+}

package/src/live/deckIndex.ts

@@ -0,0 +1,77 @@
+import * as Y from "yjs";
+import { useEffect, useState } from "react";
+import { stepForward, stepBack } from "../delivery";
+
+const clampN = (n: number, count: number) => Math.min(Math.max(n, 0), Math.max(count - 1, 0));
+
+export const getDeckIndex = (doc: Y.Doc): number => (doc.getMap("deck").get("index") as number) ?? 0;
+export const setDeckIndex = (doc: Y.Doc, n: number): void => {
+  doc.getMap("deck").set("index", n);
+};
+
+export interface DeckController {
+  index: number;
+  step: number;
+  total: number;
+  canDrive: boolean;
+  setIndex(u: number | ((n: number) => number)): void;
+  setStep(step: number): void;
+  setTotal(total: number): void;
+  next(): void;
+  prev(): void;
+}
+
+/** Deck nav state backed by the shared doc: viewers follow, only `canDrive` (the
+ *  presenter role) writes. Carries index + step + total so reveals follow too. */
+export function useLiveDeck(doc: Y.Doc, count: number, canDrive: boolean): DeckController {
+  const map = doc.getMap<number>("deck");
+  const read = () => ({
+    index: (map.get("index") as number) ?? 0,
+    step: (map.get("step") as number) ?? 0,
+    total: (map.get("total") as number) ?? 0,
+  });
+  const [s, setS] = useState(read);
+  useEffect(() => {
+    const handler = () => setS(read());
+    map.observe(handler);
+    handler();
+    return () => map.unobserve(handler);
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [doc]);
+
+  const setIndexTo = (n: number) =>
+    doc.transact(() => {
+      map.set("index", clampN(n, count));
+      map.set("step", 0);
+    });
+
+  return {
+    ...s,
+    canDrive,
+    setIndex(u) {
+      if (!canDrive) return;
+      setIndexTo(typeof u === "function" ? u(read().index) : u);
+    },
+    setStep(step) {
+      if (canDrive) map.set("step", step);
+    },
+    setTotal(total) {
+      if (canDrive && read().total !== total) map.set("total", total);
+    },
+    // read freshest doc state so rapid presses don't act on a stale step
+    next() {
+      if (!canDrive) return;
+      const cur = read();
+      const r = stepForward(cur.step, cur.total);
+      if (r.advanceSlide) setIndexTo(cur.index + 1);
+      else map.set("step", r.step);
+    },
+    prev() {
+      if (!canDrive) return;
+      const cur = read();
+      const r = stepBack(cur.step);
+      if (r.retreatSlide) setIndexTo(cur.index - 1);
+      else map.set("step", r.step);
+    },
+  };
+}

package/src/live/detect.ts

@@ -0,0 +1,17 @@
+import type { Role } from "@liebstoeckel/plugin-sdk";
+
+export interface LiveInfo {
+  ws: string;
+  session: string;
+  role: Role;
+  token: string;
+  participant?: string;
+  /** read-only follow-along link, for the in-deck QR */
+  viewer?: string;
+}
+
+/** Read the bootstrap the live server injects. Absent → standalone (.html). */
+export function detectLive(): LiveInfo | null {
+  const g = globalThis as { __LIEBSTOECKEL_LIVE__?: LiveInfo };
+  return g.__LIEBSTOECKEL_LIVE__ ?? null;
+}

package/src/live/globalChrome.tsx

@@ -0,0 +1,185 @@
+import { useEffect, useState, type ComponentType, type ReactNode } from "react";
+import { createPortal } from "react-dom";
+import { AnimatePresence, LayoutGroup, motion } from "motion/react";
+import { ChromeButton } from "@liebstoeckel/plugin-ui";
+import { type ClientProps, type GlobalProps, type PluginDef } from "@liebstoeckel/plugin-sdk";
+import { useLive, usePluginProps, type LiveContextValue } from "./Plugin";
+import { PluginBoundary } from "./PluginBoundary";
+import { BreakoutSheet } from "./breakout";
+import { useCoarsePointer } from "../useCoarsePointer";
+import { globalPlugins } from "./globals";
+
+/** A row in the touch `⋮` menu (matches DeckChrome's MenuAction). */
+export interface PluginMenuAction {
+  key: string;
+  label: string;
+  icon: ReactNode;
+  onClick: () => void;
+}
+
+interface PanelController {
+  open: boolean;
+  toggle: () => void;
+  close: () => void;
+}
+
+/** A lightweight popover for a global plugin Panel, portaled to device scale and
+ *  anchored just above the chrome rail (bottom-left), with a transparent outside-
+ *  click catcher and NO backdrop blur/dim. Unlike the focus-stealing `BreakoutSheet`
+ *  (used for full interactive breakouts like Q&A), a quick, frequent action such as
+ *  reacting shouldn't blur the whole deck behind it (ADR 0023). */
+function ChromePopover({ onClose, children }: { onClose: () => void; children: ReactNode }) {
+  useEffect(() => {
+    const onKey = (e: KeyboardEvent) => {
+      if (e.key === "Escape") onClose();
+    };
+    window.addEventListener("keydown", onKey);
+    return () => window.removeEventListener("keydown", onKey);
+  }, [onClose]);
+
+  if (typeof document === "undefined") return null;
+
+  return createPortal(
+    <>
+      {/* transparent catcher: outside-tap closes, but the deck stays fully visible */}
+      <div onClick={onClose} style={{ position: "fixed", inset: 0, zIndex: 9998, background: "transparent" }} />
+      <motion.div
+        data-pi-panel
+        onClick={(e) => e.stopPropagation()}
+        initial={{ opacity: 0, y: 10, scale: 0.98 }}
+        animate={{ opacity: 1, y: 0, scale: 1 }}
+        exit={{ opacity: 0, y: 10, scale: 0.98 }}
+        transition={{ type: "spring", stiffness: 420, damping: 32 }}
+        style={{
+          position: "fixed",
+          zIndex: 9999,
+          left: "max(env(safe-area-inset-left), 1rem)",
+          bottom: "calc(3.6rem + env(safe-area-inset-bottom))",
+          maxWidth: "min(22rem, calc(100vw - 2rem))",
+          padding: "1rem 1.15rem 1.15rem",
+          borderRadius: "1rem",
+          background: "var(--brand-surface, #11141b)",
+          border: "1px solid var(--brand-border, #222734)",
+          boxShadow: "0 18px 50px -18px rgba(0,0,0,0.7)",
+        }}
+      >
+        {children}
+      </motion.div>
+    </>,
+    document.body,
+  );
+}
+
+/** One plugin's ambient overlay (e.g. reactions floaters), inside the shared
+ *  `pointer-events:none` layer. */
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+function OverlayItem({ ctx, id, def }: { ctx: LiveContextValue; id: string; def: PluginDef<any> }) {
+  const props = usePluginProps(ctx, id, def);
+  const Overlay = def.client.global?.Overlay as ComponentType<ClientProps<unknown>> | undefined;
+  // This overlay is mounted deck-wide on every slide: if it throws, it would unmount the
+  // whole deck. Contain it so a bad audience-written value can't white-screen everyone.
+  return Overlay ? (
+    <PluginBoundary resetKey={props.snapshot}>
+      <Overlay {...props} />
+    </PluginBoundary>
+  ) : null;
+}
+
+/** Deck-wide overlay layer. Mounted as a child of `[data-deck-root]` so its
+ *  contents are positioned over the slide; non-interactive by default. */
+export function PluginOverlays() {
+  const ctx = useLive();
+  if (!ctx?.live) return null;
+  const entries = globalPlugins(ctx.plugins).filter((e) => e.def.client.global?.Overlay);
+  if (entries.length === 0) return null;
+  return (
+    <div className="pointer-events-none absolute inset-0" aria-hidden>
+      {entries.map(({ id, def }) => (
+        <OverlayItem key={id} ctx={ctx} id={id} def={def} />
+      ))}
+    </div>
+  );
+}
+
+/** A plugin's rail trigger: its custom `Control` if it has one, else a `ChromeButton`
+ *  built from `icon` + `label`. Toggles the shared panel open-state. */
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+function RailTrigger({ ctx, id, def, panel }: { ctx: LiveContextValue; id: string; def: PluginDef<any>; panel: PanelController }) {
+  const base = usePluginProps(ctx, id, def);
+  const g = def.client.global!;
+  const Control = g.Control as ComponentType<GlobalProps<unknown>> | undefined;
+  if (Control) return <Control {...base} panel={panel} />;
+  return (
+    <ChromeButton onClick={panel.toggle} active={panel.open} title={g.label} ariaLabel={g.label}>
+      {g.icon}
+    </ChromeButton>
+  );
+}
+
+/** A plugin's panel, hosted centrally so it survives the `⋮` sheet closing and so its
+ *  open-state can be driven from either the rail or a menu row. A `"sheet"` panel opens
+ *  full-viewport on touch (keyboard-friendly, ADR 0037); otherwise a popover. */
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+function PanelHost({ ctx, id, def, open, onClose, coarse }: { ctx: LiveContextValue; id: string; def: PluginDef<any>; open: boolean; onClose: () => void; coarse: boolean }) {
+  const base = usePluginProps(ctx, id, def);
+  const Panel = def.client.global?.Panel as ComponentType<GlobalProps<unknown>> | undefined;
+  const gprops: GlobalProps<unknown> = { ...base, panel: { open, toggle: onClose, close: onClose } };
+  const sheet = def.client.global?.panelMode === "sheet" && coarse;
+  return (
+    <AnimatePresence>
+      {open &&
+        Panel &&
+        (sheet ? (
+          <BreakoutSheet label={def.client.global?.label ?? id} onClose={onClose}>
+            <LayoutGroup id={`plugin-panel:${id}`}>
+              <PluginBoundary resetKey={base.snapshot}>
+                <Panel {...gprops} />
+              </PluginBoundary>
+            </LayoutGroup>
+          </BreakoutSheet>
+        ) : (
+          <ChromePopover onClose={onClose}>
+            <LayoutGroup id={`plugin-panel:${id}`}>
+              <PluginBoundary resetKey={base.snapshot}>
+                <Panel {...gprops} />
+              </PluginBoundary>
+            </LayoutGroup>
+          </ChromePopover>
+        ))}
+    </AnimatePresence>
+  );
+}
+
+/** Wires the global plugin controls into the chrome (ADR 0038). Returns the rail
+ *  triggers (pinned + custom on touch, all on desktop), the `⋮` menu rows for the rest
+ *  (touch only, the rail can't overflow), and the centrally-hosted panels. One panel
+ *  open at a time. */
+export function usePluginChrome(): { rail: ReactNode; menuActions: PluginMenuAction[]; panels: ReactNode } {
+  const ctx = useLive();
+  const coarse = useCoarsePointer();
+  const [openId, setOpenId] = useState<string | null>(null);
+  if (!ctx?.live) return { rail: null, menuActions: [], panels: null };
+
+  const entries = globalPlugins(ctx.plugins).filter((e) => e.def.client.global?.Panel || e.def.client.global?.Control);
+  // desktop: everything inline. touch: pinned (or a custom Control) inline, the rest → ⋮.
+  const inRail = (def: (typeof entries)[number]["def"]) => !coarse || !!def.client.global?.pinned || !!def.client.global?.Control;
+  const ctrl = (id: string): PanelController => ({
+    open: openId === id,
+    toggle: () => setOpenId((v) => (v === id ? null : id)),
+    close: () => setOpenId(null),
+  });
+
+  const rail = entries
+    .filter((e) => inRail(e.def))
+    .map(({ id, def }) => <RailTrigger key={id} ctx={ctx} id={id} def={def} panel={ctrl(id)} />);
+
+  const menuActions: PluginMenuAction[] = entries
+    .filter((e) => !inRail(e.def))
+    .map(({ id, def }) => ({ key: `plugin:${id}`, label: def.client.global?.label ?? id, icon: def.client.global?.icon ?? null, onClick: () => setOpenId(id) }));
+
+  const panels = entries.map(({ id, def }) => (
+    <PanelHost key={id} ctx={ctx} id={id} def={def} open={openId === id} onClose={() => setOpenId(null)} coarse={coarse} />
+  ));
+
+  return { rail, menuActions, panels };
+}

package/src/live/globals.ts

@@ -0,0 +1,15 @@
+import type { PluginDef } from "@liebstoeckel/plugin-sdk";
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+type Registry = Record<string, PluginDef<any>>;
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export type GlobalEntry = { id: string; def: PluginDef<any> };
+
+/** The registered plugins that expose a deck-wide `client.global` namespace, in
+ *  registration order (the order the deck listed them in `plugins={[…]}`). The
+ *  engine mounts one set of global surfaces per entry. See ADR 0021. */
+export function globalPlugins(registry: Registry): GlobalEntry[] {
+  return Object.entries(registry)
+    .filter(([, def]) => def.client.global)
+    .map(([id, def]) => ({ id, def }));
+}

package/src/live/index.ts

@@ -0,0 +1,7 @@
+export { detectLive, type LiveInfo } from "./detect";
+export { getParticipantId } from "./participant";
+export { connectLive, type LiveConnection } from "./connect";
+export { getDeckIndex, setDeckIndex, useLiveDeck, type DeckController } from "./deckIndex";
+export { mergeUi } from "./ui";
+export { Plugin, LiveProvider, useLive, type LiveContextValue } from "./Plugin";
+export { BreakoutAllowedContext } from "./breakout";