@liebstoeckel/engine 0.3.5

package/src/CodeMagic.tsx

@@ -0,0 +1,76 @@
+import { useMemo, type CSSProperties } from "react";
+import { AnimatePresence, motion } from "motion/react";
+import { keySteps } from "./code/diff";
+import type { TokenizedStep } from "./code/types";
+import { useRevealState } from "./steps";
+
+// Shiki FontStyle bitfield → CSS.
+function styleOf(color?: string, fontStyle?: number): CSSProperties {
+  return {
+    color,
+    fontStyle: fontStyle && fontStyle & 1 ? "italic" : undefined,
+    fontWeight: fontStyle && fontStyle & 2 ? 700 : undefined,
+    textDecoration: fontStyle && fontStyle & 4 ? "underline" : undefined,
+  };
+}
+
+/** Animated code that morphs between states. Each state is pre-tokenized at build
+ *  time (see the `code` macro). Consecutive states are line-diffed so unchanged
+ *  lines keep identity and FLIP to their new position while edits fade in/out. The
+ *  deck's reveal steps drive which state shows (via `useRevealState`); in a static
+ *  render (thumbnail/standalone) it shows the final state. */
+export function CodeMagic({
+  steps,
+  title,
+  lang,
+}: {
+  steps: TokenizedStep[];
+  title?: string;
+  lang?: string;
+}) {
+  const keyed = useMemo(() => keySteps(steps), [steps]);
+  const state = useRevealState(steps.length);
+  const active = keyed[Math.max(0, Math.min(keyed.length - 1, state))] ?? { lines: [] };
+  const language = lang ?? steps[0]?.lang;
+
+  return (
+    <div className="pi-code" data-code>
+      <div className="pi-code-bar">
+        <span className="pi-code-dots" aria-hidden>
+          <i />
+          <i />
+          <i />
+        </span>
+        {title && <span className="pi-code-title">{title}</span>}
+        {language && <span className="pi-code-lang">{language}</span>}
+      </div>
+      <pre className="pi-codemagic">
+        <code>
+          <AnimatePresence mode="popLayout" initial={false}>
+            {active.lines.map((line) => (
+              <motion.div
+                key={line.key}
+                layout
+                className="pi-code-line"
+                initial={{ opacity: 0, x: -10 }}
+                animate={{ opacity: 1, x: 0 }}
+                exit={{ opacity: 0, x: 10 }}
+                transition={{ type: "spring", stiffness: 320, damping: 34 }}
+              >
+                {line.tokens.length === 0 ? (
+                  <span>{" "}</span>
+                ) : (
+                  line.tokens.map((tok, i) => (
+                    <span key={i} style={styleOf(tok.color, tok.fontStyle)}>
+                      {tok.content}
+                    </span>
+                  ))
+                )}
+              </motion.div>
+            ))}
+          </AnimatePresence>
+        </code>
+      </pre>
+    </div>
+  );
+}

package/src/Deck.tsx

@@ -0,0 +1,286 @@
+import { useCallback, useEffect, useMemo, useRef, useState } from "react";
+import { AnimatePresence, motion, useReducedMotion } from "motion/react";
+import { MDXProvider } from "@mdx-js/react";
+import { mdxComponents } from "@liebstoeckel/components";
+import * as Y from "yjs";
+import type { PluginDef } from "@liebstoeckel/plugin-sdk";
+import { useDeckNav, useTouchNav } from "./nav";
+import { PortraitHint } from "./MobileHint";
+import { useDeckSync } from "./useDeckSync";
+import { useLive } from "./live/Plugin";
+import { useLiveDeck } from "./live/deckIndex";
+import { PersistentProvider, PersistentLayer, type PersistentItem } from "./PersistentLayer";
+import { ScaledStage, SlideFrame } from "./Stage";
+import { DeckThumb } from "./Thumb";
+import { readThumbnails } from "./thumbnails";
+import { hasEmbeddedSource } from "./source";
+import { HelpOverlay } from "./HelpOverlay";
+import { QrOverlay } from "./QrOverlay";
+import { PluginOverlays } from "./live/globalChrome";
+import { DeckChrome } from "./DeckChrome";
+import { StepsProvider } from "./steps";
+import { accumulateDigits, toggleFullscreen } from "./delivery";
+import { normalizeSlides, type SlideInput } from "./slides";
+import { resolveTransition, mobileTransitionsDisabled, type SlideDirection, type SlideTransition } from "./transitions";
+import type { Theme } from "@liebstoeckel/theme";
+import { useCoarsePointer } from "./useCoarsePointer";
+
+export type DeckProps = {
+  slides: SlideInput[];
+  persistent?: PersistentItem[];
+  brands?: string[];
+  title?: string;
+  /** Deck-wide default slide transition. A slide can override it with its own
+   *  `export const transition`. Defaults to a light `"fade"`. */
+  transition?: SlideTransition;
+  /** Deck-defined brand themes. Each is injected as a `[data-brand]` CSS block, so a
+   *  deck can ship its own brand(s) without editing the theme package, reference
+   *  them by `name` in `brands`. (Built-in brand names work via the theme styles
+   *  with no entry here.) */
+  brandThemes?: Theme[];
+  /** Allow slide transitions on mobile (coarse-pointer) devices. Off by default, *  transitions are dropped there for snappier, jank-free navigation. Set true to
+   *  opt back in. */
+  mobileTransitions?: boolean;
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  plugins?: PluginDef<any>[];
+};
+
+function openPresenter() {
+  // preserve the query (incl. ?t=<token>) so a live presenter window authenticates
+  const url = location.origin + location.pathname + location.search + "#presenter";
+  // window.open can throw (relay sandbox without allow-popups) or return null (a
+  // popup blocker), never let that bubble up as an uncaught DOMException.
+  try {
+    const w = window.open(url, "liebstoeckel-presenter", "width=1366,height=860");
+    if (!w) console.warn("[liebstoeckel] presenter pop-out was blocked (popup blocker or sandbox).");
+  } catch (err) {
+    console.warn("[liebstoeckel] presenter pop-out is unavailable in this context:", err);
+  }
+}
+
+export function Deck({ slides, persistent = [], brands = ["default"], transition: deckTransition, mobileTransitions }: DeckProps) {
+  const norm = useMemo(() => normalizeSlides(slides), [slides]);
+  const count = norm.length;
+  // Pre-rendered overview thumbnails (build-time), if the deck embedded them.
+  const thumbs = useMemo(() => readThumbnails(), []);
+
+  // Index/step source: shared Yjs doc in a live session (viewers follow), else
+  // BroadcastChannel across local windows. Both hooks run; we select one.
+  const liveCtx = useLive();
+  const fallbackDoc = useMemo(() => new Y.Doc(), []);
+  const sync = useDeckSync(count);
+  const liveDeck = useLiveDeck(liveCtx?.doc ?? fallbackDoc, count, liveCtx?.role !== "viewer");
+  const isLive = !!liveCtx?.live;
+  const role = isLive ? liveCtx?.role : undefined;
+  // A live viewer follows the presenter, overview + the presenter pop-out are
+  // presenter-only (they'd reach the confidence monitor / drive nav). Standalone
+  // (no live role) drives its own deck, so canDrive is true (ADR 0070).
+  const canDrive = role !== "viewer";
+  const ctrl = isLive ? liveDeck : sync;
+  const { index, step, total } = ctrl;
+
+  // Gate total-reporting by the current slide so the *exiting* slide (during the
+  // AnimatePresence overlap) can't clobber the entering slide's step count.
+  const indexRef = useRef(index);
+  indexRef.current = index;
+  const onTotal = useCallback(
+    (slideIndex: number, n: number) => {
+      if (slideIndex === indexRef.current) ctrl.setTotal(n);
+    },
+    [ctrl],
+  );
+
+  const [brandIdx, setBrandIdx] = useState(0);
+  const [help, setHelp] = useState(false);
+  // Static for the loaded document; resolve once for the help overlay's eject hint.
+  const ejectable = useMemo(() => hasEmbeddedSource(), []);
+  const [blurred, setBlurred] = useState(false);
+  const [overview, setOverview] = useState(false);
+  const [qr, setQr] = useState(false);
+  const [jump, setJump] = useState("");
+  const brand = brands[brandIdx % brands.length];
+
+  useEffect(() => {
+    document.body.dataset.brand = brand;
+  }, [brand]);
+
+  useEffect(() => {
+    const onCtx = (e: MouseEvent) => {
+      e.preventDefault();
+      setHelp((v) => !v);
+    };
+    window.addEventListener("contextmenu", onCtx);
+    return () => window.removeEventListener("contextmenu", onCtx);
+  }, []);
+
+  const onDigit = useCallback(
+    (key: string) => {
+      const r = accumulateDigits(jump, key);
+      setJump(r.buffer);
+      if (r.commit != null) ctrl.setIndex(r.commit);
+    },
+    [jump, ctrl],
+  );
+
+  useDeckNav({
+    count,
+    setIndex: ctrl.setIndex,
+    onNext: ctrl.next,
+    onPrev: ctrl.prev,
+    onToggleBrand: brands.length > 1 ? () => setBrandIdx((n) => n + 1) : undefined,
+    onOpenPresenter: canDrive ? openPresenter : undefined,
+    onToggleHelp: () => setHelp((v) => !v),
+    onFullscreen: () => void toggleFullscreen(document.documentElement),
+    onBlur: () => setBlurred((v) => !v),
+    onOverview: canDrive ? () => setOverview((v) => !v) : undefined,
+    onQr: () => setQr((v) => !v),
+    onDigit,
+  });
+
+  // Touch nav for everyone who drives their own deck (standalone + presenter); a
+  // live viewer follows the presenter, so it isn't bound for them.
+  useTouchNav({ enabled: role !== "viewer", onNext: ctrl.next, onPrev: ctrl.prev });
+
+  const Current = norm[index]?.Component ?? (() => null);
+
+  // Slide transition: per-slide `transition` export wins over the deck default
+  // (which defaults to "fade"). `direction` mirrors directional presets on
+  // back-nav; reduced-motion collapses everything to a tiny opacity fade.
+  const reduceMotion = useReducedMotion();
+  const coarse = useCoarsePointer();
+  const prevIndexRef = useRef(index);
+  const direction: SlideDirection = index >= prevIndexRef.current ? 1 : -1;
+  useEffect(() => {
+    prevIndexRef.current = index;
+  }, [index]);
+  // Mobile (coarse pointer) drops transitions by default, opt back in with
+  // `mobileTransitions`. Otherwise: per-slide override → deck default → "fade".
+  const requested = mobileTransitionsDisabled(coarse, mobileTransitions)
+    ? "none"
+    : (norm[index]?.transition ?? deckTransition);
+  const slideTransition = resolveTransition(requested, !!reduceMotion);
+
+  return (
+    <MDXProvider components={mdxComponents}>
+      <PersistentProvider>
+       {/* 100dvh (dynamic viewport), NOT 100vh: on mobile the browser's address
+           bar makes 100vh taller than the visible area, which would push the slide
+           bottom + the viewport-pinned chrome below the fold. */}
+       <div className="relative h-dvh w-screen overflow-hidden bg-bg">
+        <ScaledStage className="absolute inset-0">
+          <div data-deck-root className="absolute inset-0">
+            <AnimatePresence custom={direction}>
+              <motion.div
+                key={index}
+                custom={direction}
+                className="absolute inset-0"
+                variants={slideTransition.variants}
+                initial="enter"
+                animate="center"
+                exit="exit"
+                transition={slideTransition.transition}
+              >
+                <SlideFrame>
+                  <StepsProvider step={step} slideIndex={index} onTotal={onTotal}>
+                    <Current />
+                  </StepsProvider>
+                </SlideFrame>
+              </motion.div>
+            </AnimatePresence>
+
+            <PersistentLayer items={persistent} currentIndex={index} />
+
+            {/* deck-wide plugin overlays (e.g. reactions floaters), over the
+                slide, below chrome; non-interactive (live only, see ADR 0021) */}
+            <PluginOverlays />
+
+            {/* jump-to-number buffer */}
+            <AnimatePresence>
+              {jump && (
+                <motion.div
+                  initial={{ opacity: 0, scale: 0.9 }}
+                  animate={{ opacity: 1, scale: 1 }}
+                  exit={{ opacity: 0 }}
+                  className="absolute left-1/2 top-8 -translate-x-1/2 rounded-xl border border-border bg-surface/80 px-5 py-2 font-mono text-2xl text-text backdrop-blur"
+                >
+                  → {jump}
+                </motion.div>
+              )}
+            </AnimatePresence>
+
+            <HelpOverlay open={help} onClose={() => setHelp(false)} showBrand={brands.length > 1} role={role} ejectable={ejectable} />
+            <PortraitHint />
+          </div>
+
+          {/* blur-screen overlay */}
+          <AnimatePresence>
+            {blurred && (
+              <motion.div
+                className="absolute inset-0 flex items-center justify-center backdrop-blur-2xl"
+                style={{ background: "color-mix(in srgb, var(--brand-bg) 55%, transparent)" }}
+                initial={{ opacity: 0 }}
+                animate={{ opacity: 1 }}
+                exit={{ opacity: 0 }}
+                onClick={() => setBlurred(false)}
+              >
+                <svg width="84" height="84" viewBox="0 0 24 24" fill="none" stroke="var(--brand-muted)" strokeWidth="1.4" opacity="0.5">
+                  <path d="M2 12s3.5-6 10-6 10 6 10 6" strokeLinecap="round" />
+                  <path d="M2 12s3.5 4 10 4 10-4 10-4" strokeLinecap="round" />
+                </svg>
+              </motion.div>
+            )}
+          </AnimatePresence>
+        </ScaledStage>
+
+        {/* QR + overview render OUTSIDE the scaled canvas (device scale) so they're
+            full-size on a phone, the touch ⋮ menu opens them. */}
+        <QrOverlay open={qr} url={liveCtx?.viewerUrl} onClose={() => setQr(false)} />
+        <AnimatePresence>
+          {overview && (
+            <motion.div
+              className="absolute inset-0 z-40 overflow-auto bg-bg/95 p-[4%] backdrop-blur-xl"
+              initial={{ opacity: 0 }}
+              animate={{ opacity: 1 }}
+              exit={{ opacity: 0 }}
+            >
+              <div className="mb-6 font-mono text-sm uppercase tracking-[0.3em] text-muted">Overview · tap or type a number</div>
+              <div className="grid grid-cols-2 gap-4 sm:grid-cols-3 lg:grid-cols-4 lg:gap-5">
+                {norm.map((s, i) => (
+                  <button
+                    key={i}
+                    onClick={() => {
+                      ctrl.setIndex(i);
+                      setOverview(false);
+                    }}
+                    className={`relative aspect-video overflow-hidden rounded-xl border text-left transition ${
+                      i === index ? "border-primary" : "border-border hover:border-text"
+                    }`}
+                  >
+                    <DeckThumb Component={s.Component} src={thumbs?.get(i)} alt={`Slide ${i + 1}`} />
+                    <span className="absolute bottom-1 right-2 font-mono text-xs text-muted">{i + 1}</span>
+                  </button>
+                ))}
+              </div>
+            </motion.div>
+          )}
+        </AnimatePresence>
+
+        {/* chrome at DEVICE scale, pinned to the real viewport (outside the scaled
+            canvas) so the help + plugin buttons stay tappable on a phone. On touch
+            the help affordance becomes a ⋮ action menu (fullscreen, overview, …). */}
+        <DeckChrome
+          index={index}
+          count={count}
+          isLive={isLive}
+          role={role}
+          canDrive={canDrive}
+          viewerUrl={liveCtx?.viewerUrl}
+          onHelp={() => setHelp(true)}
+          onOverview={() => setOverview((v) => !v)}
+          onQr={() => setQr((v) => !v)}
+        />
+       </div>
+      </PersistentProvider>
+    </MDXProvider>
+  );
+}

package/src/DeckChrome.tsx

@@ -0,0 +1,240 @@
+import { useEffect, useState, type ReactNode } from "react";
+import { AnimatePresence } from "motion/react";
+import { usePluginChrome } from "./live/globalChrome";
+import { BreakoutSheet } from "./live/breakout";
+import { useCoarsePointer } from "./useCoarsePointer";
+import { toggleFullscreen } from "./delivery";
+
+function useIsFullscreen(): boolean {
+  const [fs, setFs] = useState(false);
+  useEffect(() => {
+    const h = () => setFs(typeof document !== "undefined" && !!document.fullscreenElement);
+    h();
+    document.addEventListener("fullscreenchange", h);
+    return () => document.removeEventListener("fullscreenchange", h);
+  }, []);
+  return fs;
+}
+
+const ICON = {
+  more: (
+    <svg width="18" height="18" viewBox="0 0 24 24" fill="currentColor">
+      <circle cx="12" cy="5" r="1.8" /><circle cx="12" cy="12" r="1.8" /><circle cx="12" cy="19" r="1.8" />
+    </svg>
+  ),
+  enterFs: (
+    <svg width="20" height="20" viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="2" strokeLinecap="round" strokeLinejoin="round">
+      <path d="M4 9V5a1 1 0 0 1 1-1h4M20 9V5a1 1 0 0 0-1-1h-4M4 15v4a1 1 0 0 0 1 1h4M20 15v4a1 1 0 0 1-1 1h-4" />
+    </svg>
+  ),
+  exitFs: (
+    <svg width="20" height="20" viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="2" strokeLinecap="round" strokeLinejoin="round">
+      <path d="M9 4v3a2 2 0 0 1-2 2H4M15 4v3a2 2 0 0 0 2 2h3M9 20v-3a2 2 0 0 0-2-2H4M15 20v-3a2 2 0 0 1 2-2h3" />
+    </svg>
+  ),
+  grid: (
+    <svg width="20" height="20" viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="2" strokeLinecap="round" strokeLinejoin="round">
+      <rect x="3" y="3" width="7" height="7" rx="1" /><rect x="14" y="3" width="7" height="7" rx="1" />
+      <rect x="3" y="14" width="7" height="7" rx="1" /><rect x="14" y="14" width="7" height="7" rx="1" />
+    </svg>
+  ),
+  share: (
+    <svg width="20" height="20" viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="2" strokeLinecap="round" strokeLinejoin="round">
+      <rect x="3" y="3" width="7" height="7" rx="1" /><rect x="14" y="14" width="7" height="7" rx="1" />
+      <path d="M14 3h7v7M3 14h4v4M10 14h0M14 10h0" />
+    </svg>
+  ),
+  theme: (
+    <svg width="20" height="20" viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="2" strokeLinecap="round" strokeLinejoin="round">
+      <path d="M12 3a9 9 0 1 0 0 18 2.5 2.5 0 0 0 0-5h-1a2 2 0 0 1 0-4h3a4 4 0 0 0 4-4 5 5 0 0 0-9-3Z" />
+    </svg>
+  ),
+  notes: (
+    <svg width="20" height="20" viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="2" strokeLinecap="round" strokeLinejoin="round">
+      <rect x="3" y="4" width="18" height="14" rx="1.5" />
+      <path d="M7 9h10M7 13h6" />
+    </svg>
+  ),
+} as const;
+
+interface MenuAction {
+  key: string;
+  label: string;
+  icon: ReactNode;
+  onClick: () => void;
+}
+
+function MenuRow({ action, onDone }: { action: MenuAction; onDone: () => void }) {
+  return (
+    <button
+      onClick={() => {
+        action.onClick();
+        onDone();
+      }}
+      style={{
+        appearance: "none",
+        cursor: "pointer",
+        display: "flex",
+        alignItems: "center",
+        gap: "0.9rem",
+        width: "100%",
+        padding: "0.95rem 0.5rem",
+        border: "none",
+        borderTop: "1px solid color-mix(in srgb, var(--brand-text, #e9e6d7) 8%, transparent)",
+        background: "transparent",
+        color: "var(--brand-text, #e9e6d7)",
+        fontFamily: "var(--brand-font-body, sans-serif)",
+        fontSize: "1.05rem",
+        textAlign: "left",
+      }}
+    >
+      <span style={{ color: "var(--brand-muted, #9da28c)", display: "flex" }}>{action.icon}</span>
+      {action.label}
+    </button>
+  );
+}
+
+/** Touch action menu: a `⋮` button opening a sheet of tappable deck actions. */
+function DeckMenu({ actions }: { actions: MenuAction[] }) {
+  const [open, setOpen] = useState(false);
+  return (
+    <>
+      <button
+        onClick={() => setOpen(true)}
+        aria-label="Menu"
+        className="flex h-7 w-7 items-center justify-center rounded-full border border-border text-muted/70 transition hover:border-text hover:text-text"
+      >
+        {ICON.more}
+      </button>
+      <AnimatePresence>
+        {open && (
+          <BreakoutSheet label="Menu" onClose={() => setOpen(false)}>
+            <div style={{ display: "flex", flexDirection: "column" }}>
+              {actions.map((a) => (
+                <MenuRow key={a.key} action={a} onDone={() => setOpen(false)} />
+              ))}
+            </div>
+          </BreakoutSheet>
+        )}
+      </AnimatePresence>
+    </>
+  );
+}
+
+/** Deck chrome rendered at DEVICE scale, pinned to the real viewport, outside the
+ *  scaled 1280×720 canvas, so the buttons stay tappable on a phone. Carries the
+ *  progress bar, the slide counter, the help/menu affordance, and any plugin-
+ *  registered global controls (ADR 0021). On a coarse pointer the rail is upsized
+ *  and the keyboard-shortcut help is swapped for a tappable `⋮` action menu. */
+export function DeckChrome({
+  index,
+  count,
+  isLive,
+  role,
+  canDrive,
+  viewerUrl,
+  onHelp,
+  onOverview,
+  onQr,
+}: {
+  index: number;
+  count: number;
+  isLive: boolean;
+  role: string | undefined;
+  canDrive: boolean;
+  viewerUrl: string | undefined;
+  onHelp: () => void;
+  onOverview: () => void;
+  onQr: () => void;
+}) {
+  const coarse = useCoarsePointer();
+  const fs = useIsFullscreen();
+  const inset = "max(env(safe-area-inset-left), 1rem)";
+  // plugin global controls: pinned ones sit in the rail; the rest overflow into the ⋮
+  // menu on touch so the rail can't run off-screen (ADR 0038). Panels are hosted here.
+  const { rail: pluginRail, menuActions: pluginMenu, panels: pluginPanels } = usePluginChrome();
+
+  // Switch this window to the presenter view (ADR 0027), the touch counterpart to
+  // the desktop `P` pop-out. `Present` selects the view by the #presenter hash at
+  // mount, so set the hash and reload.
+  const openPresenterView = () => {
+    if (typeof location === "undefined") return;
+    location.hash = "presenter";
+    location.reload();
+  };
+
+  // Note: no "Cycle theme" here, brand cycling stays the desktop `t` shortcut
+  // (a niche preview/showcase affordance), not a touch action.
+  const actions: MenuAction[] = [
+    {
+      key: "fullscreen",
+      label: fs ? "Exit fullscreen" : "Fullscreen",
+      icon: fs ? ICON.exitFs : ICON.enterFs,
+      onClick: () => void toggleFullscreen(document.documentElement),
+    },
+    ...(canDrive ? [{ key: "overview", label: "Overview", icon: ICON.grid, onClick: onOverview }] : []),
+    // Presenter view (notes-first confidence monitor), drivers only, never viewers.
+    ...(canDrive ? [{ key: "presenter", label: "Presenter view", icon: ICON.notes, onClick: openPresenterView }] : []),
+    ...(isLive && viewerUrl ? [{ key: "share", label: "Share / QR", icon: ICON.share, onClick: onQr }] : []),
+    ...pluginMenu, // overflowed (unpinned) plugin controls, touch only
+  ];
+
+  return (
+    <>
+      {/* progress + counter pinned to the viewport bottom */}
+      <div className="pointer-events-none absolute inset-x-0 bottom-0 z-30 h-[3px] bg-border/40">
+        <div
+          className="h-full bg-primary transition-[width] duration-500 ease-out"
+          style={{ width: `${((index + 1) / count) * 100}%` }}
+        />
+      </div>
+      <div
+        className="pointer-events-none absolute z-30 font-mono text-sm tracking-wide text-muted"
+        style={{ bottom: "calc(0.9rem + env(safe-area-inset-bottom))", right: "max(env(safe-area-inset-right), 1.25rem)" }}
+      >
+        {String(index + 1).padStart(2, "0")} / {String(count).padStart(2, "0")}
+      </div>
+
+      {/* chrome rail: help (desktop) or ⋮ menu (touch) + plugin global controls */}
+      <div
+        className="absolute z-30 flex items-center gap-2"
+        style={{
+          bottom: "calc(0.75rem + env(safe-area-inset-bottom))",
+          left: inset,
+          transform: coarse ? "scale(1.6)" : "none",
+          transformOrigin: "bottom left",
+        }}
+      >
+        {coarse ? (
+          <DeckMenu actions={actions} />
+        ) : (
+          <button
+            onClick={onHelp}
+            title={isLive ? `${role} · shortcuts (? or right-click)` : "Shortcuts (? or right-click)"}
+            className={`flex h-7 w-7 items-center justify-center rounded-full border transition ${
+              isLive
+                ? "border-accent/50 text-accent opacity-80 hover:opacity-100"
+                : "border-border text-muted/50 opacity-60 hover:border-text hover:text-text hover:opacity-100"
+            }`}
+          >
+            {!isLive ? (
+              <span className="font-mono text-xs">?</span>
+            ) : role === "viewer" ? (
+              <svg width="15" height="15" viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="2" strokeLinecap="round" strokeLinejoin="round">
+                <path d="M2 12s3.5-7 10-7 10 7 10 7-3.5 7-10 7-10-7-10-7Z" />
+                <circle cx="12" cy="12" r="3" />
+              </svg>
+            ) : (
+              <svg width="15" height="15" viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="2" strokeLinecap="round" strokeLinejoin="round">
+                <rect x="3" y="4" width="18" height="13" rx="1.5" />
+                <path d="M12 17v3M8.5 20h7" />
+              </svg>
+            )}
+          </button>
+        )}
+        {pluginRail}
+      </div>
+      {pluginPanels}
+    </>
+  );
+}