@liebstoeckel/engine 0.3.5

package/src/HelpOverlay.tsx

@@ -0,0 +1,156 @@
+import { useEffect } from "react";
+import { AnimatePresence, motion } from "motion/react";
+import type { Role } from "@liebstoeckel/plugin-sdk";
+
+type Shortcut = { keys: string[]; label: string; presenterOnly?: boolean };
+
+/** Guide for recovering + editing a built deck (linked from the eject footer). */
+const EDIT_DOCS_URL = "https://docs.liebstoeckel.app/guides/editing-a-built-deck/";
+
+function Kbd({ children, dim }: { children: string; dim?: boolean }) {
+  return (
+    <kbd
+      className={`inline-flex min-w-[1.9rem] items-center justify-center rounded-md border px-2 py-1 font-mono text-sm shadow-sm ${
+        dim ? "border-border/50 bg-bg/40 text-muted" : "border-border bg-bg text-text"
+      }`}
+    >
+      {children}
+    </kbd>
+  );
+}
+
+export function HelpOverlay({
+  open,
+  onClose,
+  showBrand,
+  role,
+  ejectable,
+}: {
+  open: boolean;
+  onClose: () => void;
+  showBrand?: boolean;
+  /** live role; undefined = standalone (everything enabled) */
+  role?: Role;
+  /** this `.html` carries its own recoverable source → show the "edit this deck" hint */
+  ejectable?: boolean;
+}) {
+  useEffect(() => {
+    if (!open) return;
+    const onKey = (e: KeyboardEvent) => {
+      if (e.key === "Escape") onClose();
+    };
+    window.addEventListener("keydown", onKey);
+    return () => window.removeEventListener("keydown", onKey);
+  }, [open, onClose]);
+
+  const isViewer = role === "viewer";
+
+  const shortcuts: Shortcut[] = [
+    { keys: ["→", "Space"], label: "Next / reveal step", presenterOnly: true },
+    { keys: ["←"], label: "Previous / hide step", presenterOnly: true },
+    { keys: ["Home", "End"], label: "First / last slide", presenterOnly: true },
+    { keys: ["0-9", "↵"], label: "Jump to slide", presenterOnly: true },
+    { keys: ["O"], label: "Overview grid", presenterOnly: true },
+    { keys: ["F"], label: "Fullscreen" },
+    { keys: ["B"], label: "Blur screen" },
+    { keys: ["Q"], label: "Show join QR" },
+    { keys: ["P"], label: "Open presenter view", presenterOnly: true },
+    ...(showBrand ? [{ keys: ["T"], label: "Switch brand" }] : []),
+    { keys: ["?"], label: "Toggle this help" },
+    { keys: ["Esc"], label: "Close" },
+  ];
+
+  return (
+    <AnimatePresence>
+      {open && (
+        <motion.div
+          className="absolute inset-0 z-50 flex items-center justify-center"
+          initial={{ opacity: 0 }}
+          animate={{ opacity: 1 }}
+          exit={{ opacity: 0 }}
+          transition={{ duration: 0.18 }}
+        >
+          <div
+            className="absolute inset-0 bg-bg/70 backdrop-blur-md"
+            onClick={onClose}
+            onContextMenu={(e) => {
+              e.preventDefault();
+              onClose();
+            }}
+          />
+          <motion.div
+            initial={{ opacity: 0, scale: 0.96, y: 10 }}
+            animate={{ opacity: 1, scale: 1, y: 0 }}
+            exit={{ opacity: 0, scale: 0.97, y: 8 }}
+            transition={{ type: "spring", stiffness: 260, damping: 24 }}
+            className="relative w-[440px] rounded-2xl border border-border bg-surface/90 p-7 shadow-[0_30px_80px_-20px_rgba(0,0,0,0.85)]"
+          >
+            <div className="mb-5 flex items-baseline justify-between">
+              <span className="font-heading text-2xl font-semibold text-text">Shortcuts</span>
+              {role ? (
+                <span className="font-mono text-[11px] uppercase tracking-[0.25em] text-accent">
+                  ● live · {role}
+                </span>
+              ) : (
+                <span className="font-mono text-[11px] uppercase tracking-[0.3em] text-muted">keyboard</span>
+              )}
+            </div>
+            {isViewer && (
+              <p className="mb-4 font-body text-sm text-muted">
+                You're following as a <span className="text-text">viewer</span>, the presenter drives
+                navigation. You can still interact (e.g. vote).
+              </p>
+            )}
+            <ul className="space-y-3">
+              {shortcuts.map((s) => {
+                const disabled = isViewer && s.presenterOnly;
+                return (
+                  <li
+                    key={s.label}
+                    className={`flex items-center justify-between gap-4 ${disabled ? "opacity-40" : ""}`}
+                    title={disabled ? "Presenter only" : undefined}
+                  >
+                    <span className="font-body text-lg text-text/85">
+                      {s.label}
+                      {disabled && <span className="ml-2 font-mono text-[10px] uppercase tracking-wider text-muted">presenter</span>}
+                    </span>
+                    <span className="flex shrink-0 items-center gap-1.5">
+                      {s.keys.map((k, i) => (
+                        <span key={k} className="flex items-center gap-1.5">
+                          {i > 0 && <span className="font-mono text-xs text-muted">/</span>}
+                          <Kbd dim={disabled}>{k}</Kbd>
+                        </span>
+                      ))}
+                    </span>
+                  </li>
+                );
+              })}
+            </ul>
+            {ejectable && (
+              <div className="mt-6 border-t border-border pt-4">
+                <p className="font-body text-sm text-text/80">
+                  This deck embeds its own source, recover it with{" "}
+                  <code className="rounded bg-bg/60 px-1.5 py-0.5 font-mono text-[13px] text-text">
+                    liebstoeckel eject
+                  </code>{" "}
+                  to edit it by hand or with an agent.{" "}
+                  <a
+                    href={EDIT_DOCS_URL}
+                    target="_blank"
+                    rel="noreferrer"
+                    className="text-accent underline decoration-accent/40 underline-offset-2 hover:decoration-accent"
+                  >
+                    Learn how →
+                  </a>
+                </p>
+              </div>
+            )}
+            <div className="mt-6 border-t border-border pt-4 text-center font-mono text-[11px] uppercase tracking-[0.25em] text-muted">
+              right-click anywhere to toggle
+            </div>
+          </motion.div>
+        </motion.div>
+      )}
+    </AnimatePresence>
+  );
+}

package/src/MobileHint.tsx

@@ -0,0 +1,71 @@
+import { useEffect, useState } from "react";
+import { createPortal } from "react-dom";
+import { AnimatePresence, motion } from "motion/react";
+
+/** A brief, dismissable "rotate for a bigger view" toast shown on a portrait phone
+ *  (coarse pointer). Portaled to <body> so it renders at device scale, not inside
+ *  the scaled canvas. Auto-hides; tap to dismiss. */
+export function PortraitHint() {
+  const [portrait, setPortrait] = useState(false);
+  const [dismissed, setDismissed] = useState(false);
+
+  useEffect(() => {
+    if (typeof matchMedia !== "function") return;
+    const coarse = matchMedia("(pointer: coarse)");
+    const orient = matchMedia("(orientation: portrait)");
+    const update = () => setPortrait(coarse.matches && orient.matches);
+    update();
+    coarse.addEventListener?.("change", update);
+    orient.addEventListener?.("change", update);
+    return () => {
+      coarse.removeEventListener?.("change", update);
+      orient.removeEventListener?.("change", update);
+    };
+  }, []);
+
+  useEffect(() => {
+    if (!portrait) return;
+    const t = setTimeout(() => setDismissed(true), 6000);
+    return () => clearTimeout(t);
+  }, [portrait]);
+
+  if (typeof document === "undefined") return null;
+  const show = portrait && !dismissed;
+
+  return createPortal(
+    <AnimatePresence>
+      {show && (
+        <motion.button
+          onClick={() => setDismissed(true)}
+          initial={{ opacity: 0, y: 12 }}
+          animate={{ opacity: 1, y: 0 }}
+          exit={{ opacity: 0, y: 12 }}
+          style={{
+            position: "fixed",
+            left: "50%",
+            bottom: "calc(1.25rem + env(safe-area-inset-bottom))",
+            transform: "translateX(-50%)",
+            zIndex: 9998,
+            display: "flex",
+            alignItems: "center",
+            gap: "0.5rem",
+            padding: "0.55rem 0.95rem",
+            borderRadius: "999px",
+            border: "1px solid var(--brand-border, color-mix(in srgb, var(--brand-text, #e9e6d7) 14%, transparent))",
+            background: "color-mix(in srgb, var(--brand-surface, #1a2014) 88%, transparent)",
+            color: "var(--brand-muted, #9da28c)",
+            fontFamily: "var(--brand-font-mono, monospace)",
+            fontSize: "0.72rem",
+            letterSpacing: "0.04em",
+            backdropFilter: "blur(8px)",
+            cursor: "pointer",
+          }}
+        >
+          <span aria-hidden style={{ fontSize: "0.9rem" }}>⤾</span>
+          Rotate for a bigger view
+        </motion.button>
+      )}
+    </AnimatePresence>,
+    document.body,
+  );
+}

package/src/PersistentLayer.tsx

@@ -0,0 +1,168 @@
+import {
+  createContext,
+  useCallback,
+  useContext,
+  useLayoutEffect,
+  useRef,
+  useState,
+  type ReactNode,
+} from "react";
+import { motion } from "motion/react";
+import { StageScaleContext } from "./Stage";
+import { SlideIndexContext } from "./steps";
+
+export type PersistentItem = { id: string; render: () => ReactNode };
+type Rect = { top: number; left: number; width: number; height: number };
+
+// Per element id, the measured slot rect for each slide index that mounts one.
+type SlotMap = Record<string, Record<number, Rect>>;
+
+type Ctx = {
+  set: (id: string, slide: number, rect: Rect) => void;
+  clear: (id: string, slide: number) => void;
+  slots: SlotMap;
+};
+const PersistentCtx = createContext<Ctx | null>(null);
+const usePersistent = () => {
+  const c = useContext(PersistentCtx);
+  if (!c) throw new Error("Slot/PersistentLayer must be used inside <PersistentProvider>");
+  return c;
+};
+
+const same = (a: Rect | undefined, b: Rect) =>
+  a && a.top === b.top && a.left === b.left && a.width === b.width && a.height === b.height;
+
+/** Holds each persistent element's slot rect **per slide index**. Visibility is
+ *  decided by the layer from the *current* slide index (not by ref-counting mounted
+ *  slots), so when navigating to a slide that has no slot, the element hides at the
+ *  index change, in step with the transition, instead of lingering until the old
+ *  slide finishes its exit. When the incoming slide also has a slot, its rect is
+ *  present for the new index and the element travels to it. */
+export function PersistentProvider({ children }: { children: ReactNode }) {
+  const [slots, setSlots] = useState<SlotMap>({});
+
+  const set = useCallback((id: string, slide: number, rect: Rect) => {
+    setSlots((p) => {
+      if (same(p[id]?.[slide], rect)) return p;
+      return { ...p, [id]: { ...(p[id] ?? {}), [slide]: rect } };
+    });
+  }, []);
+
+  const clear = useCallback((id: string, slide: number) => {
+    setSlots((p) => {
+      if (!p[id] || !(slide in p[id]!)) return p;
+      const next = { ...p[id] };
+      delete next[slide];
+      return { ...p, [id]: next };
+    });
+  }, []);
+
+  return <PersistentCtx.Provider value={{ set, clear, slots }}>{children}</PersistentCtx.Provider>;
+}
+
+/** Reserves space inside a slide and reports its box (per slide index) to the
+ *  persistent layer. Drop the same `id` on multiple slides to make the element
+ *  travel between them. */
+export function Slot({ id, className }: { id: string; className?: string }) {
+  const { set, clear } = usePersistent();
+  const slide = useContext(SlideIndexContext);
+  const scale = useContext(StageScaleContext);
+  const ref = useRef<HTMLDivElement>(null);
+
+  useLayoutEffect(() => {
+    const el = ref.current!;
+    const root = (el.closest("[data-deck-root]") as HTMLElement) ?? document.body;
+    // getBoundingClientRect is post-transform (device px), but the persistent layer
+    // positions inside the stage's LOGICAL 1280×720 space, divide the stage scale
+    // back out, else the element is mis-placed whenever the stage isn't at 1:1.
+    const s = scale || 1;
+    const measure = (): Rect => {
+      const r = el.getBoundingClientRect();
+      const base = root.getBoundingClientRect();
+      return { top: (r.top - base.top) / s, left: (r.left - base.left) / s, width: r.width / s, height: r.height / s };
+    };
+    set(id, slide, measure());
+    const ro = new ResizeObserver(() => set(id, slide, measure()));
+    ro.observe(el);
+    ro.observe(root);
+    const onResize = () => set(id, slide, measure());
+    window.addEventListener("resize", onResize);
+    return () => {
+      ro.disconnect();
+      window.removeEventListener("resize", onResize);
+      clear(id, slide);
+    };
+  }, [id, slide, set, clear, scale]);
+
+  return <div ref={ref} data-slot={id} className={className} />;
+}
+
+const SPRING = { type: "spring", stiffness: 200, damping: 26 } as const;
+// Appear: snap the box into place (no positional tween) and only fade opacity in,
+// so the element doesn't fly in from a previous slot's position or the origin.
+const APPEAR = {
+  top: { duration: 0 },
+  left: { duration: 0 },
+  width: { duration: 0 },
+  height: { duration: 0 },
+  opacity: SPRING,
+} as const;
+
+/** Renders each persistent element ONCE (never unmounts → internal state kept),
+ *  positioning it onto the slot on the **current** slide. Animates the box props
+ *  (top/left/width/height) directly rather than Motion `layout` FLIP, whose
+ *  projection mis-positions under the stage's scaled ancestor. Coordinates are the
+ *  slot's LOGICAL rect. When the current slide has no slot the element fades out in
+ *  place. The positional spring runs only for consecutive slot→slot travel; an
+ *  appearance (first show, or coming from a slot-less slide) snaps + fades in.
+ *  `currentIndex` is omitted only for standalone use (then any slot shows). */
+export function PersistentLayer({ items, currentIndex }: { items: PersistentItem[]; currentIndex?: number }) {
+  const { slots } = usePersistent();
+  const last = useRef<Record<string, Rect>>({});
+
+  // Track the index we navigated FROM. Updated in render but ONLY when the index
+  // actually changes, so the transient re-renders that land the incoming slot's
+  // rect (same currentIndex) keep reporting the real previous slide. Robust against
+  // effect-flush timing, unlike a useEffect-updated ref.
+  const nav = useRef<{ current?: number; from?: number }>({ current: currentIndex, from: currentIndex });
+  if (nav.current.current !== currentIndex) {
+    nav.current = { current: currentIndex, from: nav.current.current };
+  }
+  const cameFrom = nav.current.from;
+
+  const resolved = items.map((it) => {
+    const perSlide = slots[it.id];
+    const active = perSlide ? (currentIndex != null ? perSlide[currentIndex] : Object.values(perSlide)[0]) : undefined;
+    if (active) last.current[it.id] = active;
+    const r = active ?? last.current[it.id];
+    const show = !!active;
+    // Travel only if the slide we came FROM also had this slot; otherwise (first
+    // show, or from a slot-less slide) snap + fade in instead of flying across.
+    const cameFromSlot = perSlide != null && cameFrom != null && perSlide[cameFrom] != null;
+    const appearing = show && !cameFromSlot;
+    return { it, r, show, appearing };
+  });
+
+  return (
+    <div className="pointer-events-none absolute inset-0">
+      {resolved.map(({ it, r, show, appearing }) => (
+        <motion.div
+          key={it.id}
+          data-persistent={it.id}
+          initial={false}
+          animate={{
+            top: r?.top ?? 0,
+            left: r?.left ?? 0,
+            width: r?.width ?? 0,
+            height: r?.height ?? 0,
+            opacity: show ? 1 : 0,
+          }}
+          transition={appearing ? APPEAR : SPRING}
+          style={{ position: "absolute", pointerEvents: show ? "auto" : "none" }}
+        >
+          {it.render()}
+        </motion.div>
+      ))}
+    </div>
+  );
+}

package/src/Present.tsx

@@ -0,0 +1,113 @@
+import { useEffect, useMemo, useState } from "react";
+import * as Y from "yjs";
+import { useTheme } from "@liebstoeckel/plugin-ui";
+import { themeToCss, type Theme } from "@liebstoeckel/theme";
+import { registerPluginInstance, type PluginDef } from "@liebstoeckel/plugin-sdk";
+import { Deck, type DeckProps } from "./Deck";
+import { PresenterView } from "./PresenterView";
+import { CaptureView } from "./CaptureView";
+import { PrintView } from "./PrintView";
+import { LiveProvider, type LiveContextValue } from "./live/Plugin";
+import { detectLive } from "./live/detect";
+import { connectLive } from "./live/connect";
+import { getParticipantId } from "./live/participant";
+import { captureRequest, printRequest } from "./build/capture-protocol";
+
+/** Concatenate deck-defined brand themes into one CSS string of `[data-brand]`
+ *  blocks (empty when none). Pure, unit-testable without a DOM. */
+export function brandThemesCss(themes?: Theme[]): string {
+  return (themes ?? []).map(themeToCss).join("\n");
+}
+
+/** Whether to render the presenter confidence monitor: the `#presenter` hash asks
+ *  for it, but a live **viewer** must never reach it (it exposes speaker notes and
+ *  the plugin presenter consoles). Standalone (`role === undefined`) keeps the
+ *  hash-gate as the presenter mechanism (ADR 0027/0070). Pure, DOM-free. */
+export function presenterViewRequested(hash: string, role?: string): boolean {
+  return hash.includes("presenter") && role !== "viewer";
+}
+
+// Single entry point for a presentation. Detects a live server (the bootstrap the
+// server injects), connects the shared Yjs doc, and provides plugin context. Falls
+// back to the standalone deck (BroadcastChannel presenter view via the P key).
+export function Present(props: DeckProps) {
+  // Build-time thumbnail capture short-circuits everything else: no live connect,
+  // no nav, no presenter, just a motionless slide for the headless screenshotter.
+  // Gate the live connection on it (hooks still run unconditionally).
+  const [capture] = useState(() => captureRequest());
+  const [print] = useState(() => printRequest());
+  const info = useMemo(() => (capture || print ? null : detectLive()), [capture, print]);
+  const participant = useMemo(() => getParticipantId(), []);
+  const theme = useTheme();
+  const registry = useMemo(
+    () =>
+      Object.fromEntries((props.plugins ?? []).map((p) => [p.id, p])) as Record<
+        string,
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        PluginDef<any>
+      >,
+    [props.plugins],
+  );
+  const conn = useMemo(() => (info ? connectLive(info, participant) : null), [info, participant]);
+  const doc = useMemo(() => conn?.doc ?? new Y.Doc(), [conn]);
+
+  // A plugin with global surfaces + a presenter console (e.g. Q&A) can be used without an
+  // on-slide placement, so register its default instance in the doc index, otherwise the
+  // presenter console, which discovers instances from placements (ADR 0033), wouldn't find
+  // it. Runs in both the Deck and the presenter window, so it doesn't depend on a viewer
+  // being connected. (ADR 0036)
+  useEffect(() => {
+    if (!info) return;
+    for (const [id, def] of Object.entries(registry)) {
+      if (def.client.presenter && def.client.global) registerPluginInstance(doc, id, "");
+    }
+  }, [info, registry, doc]);
+
+  const value: LiveContextValue = {
+    live: !!info,
+    role: info?.role ?? "presenter",
+    participant,
+    doc,
+    theme,
+    viewerUrl: info?.viewer,
+    plugins: registry,
+  };
+
+  // The presenter confidence monitor is selected by the #presenter hash, but in a
+  // live session a *viewer* must never reach it (it leaks speaker notes + presenter
+  // consoles). Standalone (no live role) keeps the hash-gate (ADR 0027/0070).
+  const [isPresenterWindow] = useState(
+    () => typeof location !== "undefined" && presenterViewRequested(location.hash, info?.role),
+  );
+
+  // Deck-defined brands → an injected `[data-brand]` stylesheet (so a deck can ship
+  // its own brand without editing the theme package). Rendered in every view.
+  const css = brandThemesCss(props.brandThemes);
+  const brandStyle = css ? <style data-brand-themes>{css}</style> : null;
+
+  if (capture)
+    return (
+      <>
+        {brandStyle}
+        <CaptureView {...props} />
+      </>
+    );
+
+  if (print)
+    return (
+      <>
+        {brandStyle}
+        <PrintView {...props} />
+      </>
+    );
+
+  // The confidence monitor (#presenter) works standalone (BroadcastChannel) and
+  // live (shared Yjs doc), it reads the same controller as the audience Deck.
+  const view = isPresenterWindow ? <PresenterView {...props} /> : <Deck {...props} />;
+  return (
+    <LiveProvider value={value}>
+      {brandStyle}
+      {view}
+    </LiveProvider>
+  );
+}