@liebstoeckel/engine 0.3.5

package/src/live/participant.ts

@@ -0,0 +1,41 @@
+const KEY = "liebstoeckel:pid";
+
+type Store = Pick<Storage, "getItem" | "setItem">;
+
+// crypto.randomUUID only exists in secure contexts (https/localhost). Live decks
+// are served over http on a LAN IP, so fall back to a non-crypto random id.
+function uuid(): string {
+  if (typeof crypto !== "undefined" && typeof crypto.randomUUID === "function") return crypto.randomUUID();
+  return `p-${Math.random().toString(36).slice(2)}${Date.now().toString(36)}`;
+}
+
+/** sessionStorage, or undefined if it isn't usable. Merely *accessing* the
+ *  property throws ("Access is denied") in an opaque origin, a sandboxed deck
+ *  (relay's `CSP: sandbox`) or a `setContent`/`data:` document (thumbnail capture)
+ * , so the access itself must be guarded, not just a typeof check. */
+function safeSessionStorage(): Store | undefined {
+  try {
+    const s = sessionStorage;
+    return s ?? undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+/** Stable id for this browser session (one session = one participant). Persists
+ *  in sessionStorage so a reload keeps identity (no double-counting votes). When
+ *  storage is denied (opaque origin), falls back to an ephemeral per-load id, *  navigation still works; identity just doesn't survive a reload there. */
+export function getParticipantId(storage?: Store): string {
+  const store = storage ?? safeSessionStorage();
+  if (!store) return uuid();
+  try {
+    let id = store.getItem(KEY);
+    if (!id) {
+      id = uuid();
+      store.setItem(KEY, id);
+    }
+    return id;
+  } catch {
+    return uuid();
+  }
+}

package/src/live/presenterPanel.tsx

@@ -0,0 +1,281 @@
+import { useEffect, useMemo, useState, type ComponentType, type ReactNode } from "react";
+import { LayoutGroup } from "motion/react";
+import { observePluginIndex, readPluginInstances, type ClientProps, type PluginDef } from "@liebstoeckel/plugin-sdk";
+import { useLive, usePluginProps, type LiveContextValue } from "./Plugin";
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+type Inst = { type: string; instance: string; title?: string; def: PluginDef<any> };
+
+type Variant = "desktop" | "mobile";
+
+const ikey = (i: Inst) => `${i.type} ${i.instance}`;
+
+/** Live list of placed instances whose type exposes a presenter console, discovered from
+ *  the doc index (ADR 0033) and kept current as `<Plugin>`s mount across the session. */
+function usePresenterInstances(ctx: LiveContextValue | null): Inst[] {
+  const [list, setList] = useState<Inst[]>([]);
+  useEffect(() => {
+    if (!ctx?.live) {
+      setList([]);
+      return;
+    }
+    const read = () =>
+      setList(
+        readPluginInstances(ctx.doc)
+          .map((e) => ({ type: e.type, instance: e.instance, title: e.title, def: ctx.plugins[e.type]! }))
+          .filter((e) => e.def?.client.presenter),
+      );
+    read();
+    return observePluginIndex(ctx.doc, read);
+  }, [ctx?.live, ctx?.doc, ctx?.plugins]);
+  return list;
+}
+
+// Notes container, matches the panel the presenter view used before tabs existed, so a
+// deck with no presenter instances looks the same (ADR 0031).
+const NOTES_CLASS: Record<Variant, string> = {
+  desktop:
+    "presenter-notes min-h-0 min-w-0 flex-1 overflow-auto rounded-2xl border border-border bg-surface/40 p-6 text-xl leading-relaxed text-text/90",
+  mobile: "presenter-notes min-h-0 flex-1 overflow-auto px-5 py-4 text-2xl leading-relaxed text-text/90",
+};
+
+function NotesLabel() {
+  return <div className="flex items-center gap-2 font-mono text-[11px] uppercase tracking-[0.3em] text-muted">Speaker notes</div>;
+}
+
+function tabClass(variant: Variant, selected: boolean): string {
+  const base = "flex shrink-0 items-center gap-2 rounded-lg border font-mono uppercase tracking-wider transition";
+  const size = variant === "mobile" ? "px-3 py-2 text-[11px]" : "px-3 py-1.5 text-xs";
+  const state = selected
+    ? "border-primary bg-primary/10 text-primary"
+    : variant === "mobile"
+      ? "border-border text-muted active:border-text active:text-text"
+      : "border-border text-muted hover:border-text hover:text-text";
+  return `${base} ${size} ${state}`;
+}
+
+function Badge({ value }: { value: number | string }) {
+  return <span className="rounded-full bg-accent px-1.5 py-px text-[10px] font-semibold text-on-primary tabular-nums">{value}</span>;
+}
+
+/** One **per-type** strip tab (ADR 0033/0035): one "Poll" tab regardless of how many poll
+ *  instances exist. Its badge is the instance count when there are several, else the lone
+ *  instance's own badge. Subscribes to the first instance for that live badge. */
+function TypeTab({ ctx, group, selected, variant, onSelect }: { ctx: LiveContextValue; group: Inst[]; selected: boolean; variant: Variant; onSelect: () => void }) {
+  const first = group[0]!;
+  const props = usePluginProps(ctx, first.type, first.def, {}, first.instance);
+  const surface = first.def.client.presenter!;
+  const multi = group.length > 1;
+  const badge = multi ? group.length : surface.badge?.(props.snapshot);
+  const show = badge !== undefined && badge !== 0 && badge !== "";
+  return (
+    <button onClick={onSelect} className={tabClass(variant, selected)}>
+      {surface.icon != null && <span aria-hidden>{surface.icon as ReactNode}</span>}
+      <span>{surface.label}</span>
+      {show && <Badge value={badge!} />}
+    </button>
+  );
+}
+
+/** The instance's live label: its title (e.g. the poll question), then placement title,
+ *  then the instance id, then the type label as a last resort. */
+function instLabel(inst: Inst, snapshot: unknown): string {
+  const s = inst.def.client.presenter!;
+  return s.title?.(snapshot as never) || inst.title || inst.instance || s.label;
+}
+
+/** Dropdown trigger, shows the selected instance's label on one truncated line. */
+function InstanceTrigger({ ctx, inst, open, onToggle, variant }: { ctx: LiveContextValue; inst: Inst; open: boolean; onToggle: () => void; variant: Variant }) {
+  const props = usePluginProps(ctx, inst.type, inst.def, {}, inst.instance);
+  return (
+    <button
+      onClick={onToggle}
+      aria-haspopup="listbox"
+      aria-expanded={open}
+      className={`flex w-full items-center justify-between gap-2 rounded-lg border px-3 ${variant === "mobile" ? "py-2.5 text-base" : "py-2 text-sm"} text-left transition ${
+        open ? "border-primary text-text" : "border-border text-text/90 hover:border-text"
+      }`}
+    >
+      <span className="min-w-0 flex-1 truncate">{instLabel(inst, props.snapshot)}</span>
+      <svg className={`shrink-0 transition-transform ${open ? "rotate-180" : ""}`} width="14" height="14" viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="2" strokeLinecap="round" strokeLinejoin="round">
+        <path d="M6 9l6 6 6-6" />
+      </svg>
+    </button>
+  );
+}
+
+/** One row in the open instance menu, full label (wraps), check when selected, + badge. */
+function InstanceMenuItem({ ctx, inst, selected, onPick }: { ctx: LiveContextValue; inst: Inst; selected: boolean; onPick: () => void }) {
+  const props = usePluginProps(ctx, inst.type, inst.def, {}, inst.instance);
+  const surface = inst.def.client.presenter!;
+  const badge = surface.badge?.(props.snapshot);
+  const show = badge !== undefined && badge !== 0 && badge !== "";
+  return (
+    <button
+      role="option"
+      aria-selected={selected}
+      onClick={onPick}
+      className={`flex w-full items-start gap-2 px-3 py-2 text-left text-sm transition hover:bg-primary/10 ${selected ? "text-primary" : "text-text/90"}`}
+    >
+      <span className="w-3 shrink-0 pt-0.5">{selected ? "✓" : ""}</span>
+      <span className="min-w-0 flex-1">{instLabel(inst, props.snapshot)}</span>
+      {show && <span className="pt-0.5"><Badge value={badge!} /></span>}
+    </button>
+  );
+}
+
+/** Instance switcher for a multi-instance type (ADR 0035): a compact dropdown in the
+ *  console header. The trigger shows the current instance (truncated); the menu lists
+ *  every instance with its full label (wrapping) so long poll questions never overflow. */
+function InstanceDropdown({ ctx, group, selectedKey, onPick, variant }: { ctx: LiveContextValue; group: Inst[]; selectedKey: string; onPick: (key: string) => void; variant: Variant }) {
+  const [open, setOpen] = useState(false);
+  const sel = group.find((i) => ikey(i) === selectedKey) ?? group[0]!;
+  return (
+    <div className={`relative shrink-0 ${variant === "mobile" ? "px-4" : ""}`}>
+      <InstanceTrigger ctx={ctx} inst={sel} open={open} onToggle={() => setOpen((o) => !o)} variant={variant} />
+      {open && (
+        <>
+          <div className="fixed inset-0 z-20" aria-hidden onClick={() => setOpen(false)} />
+          <div role="listbox" className={`absolute top-full z-30 mt-1 max-h-64 overflow-auto rounded-lg border border-border bg-surface shadow-2xl ${variant === "mobile" ? "left-4 right-4" : "left-0 right-0"}`}>
+            {group.map((i) => (
+              <InstanceMenuItem key={ikey(i)} ctx={ctx} inst={i} selected={ikey(i) === ikey(sel)} onPick={() => { onPick(ikey(i)); setOpen(false); }} />
+            ))}
+          </div>
+        </>
+      )}
+    </div>
+  );
+}
+
+/** The selected instance's console, mounted with its live state. */
+function Console({ ctx, inst, variant }: { ctx: LiveContextValue; inst: Inst; variant: Variant }) {
+  const props = usePluginProps(ctx, inst.type, inst.def, {}, inst.instance);
+  const C = inst.def.client.presenter!.Console as ComponentType<ClientProps<unknown>>;
+  // Mobile is edge-to-edge, so the bordered console insets itself; desktop fills the column.
+  const box = variant === "mobile" ? "mx-4 mb-3 p-4" : "p-5";
+  // Namespace the console's Motion layout tree so a plugin whose UI uses `layoutId`
+  // (e.g. Q&A's ranked rows) doesn't share layout identity with the SAME slide rendered
+  // live in the presenter's preview Thumb, which sits inside the ScaledStage's
+  // `transform`. Without this, Motion treats the two as one shared element and morphs
+  // across the scale boundary (the ADR 0026 hazard).
+  return (
+    <div className={`min-h-0 min-w-0 flex-1 overflow-auto rounded-2xl border border-border bg-surface/40 ${box}`}>
+      <LayoutGroup id={`presenter-console-${ikey(inst)}`}>
+        <C {...props} />
+      </LayoutGroup>
+    </div>
+  );
+}
+
+/** The maximize ⤢ / restore ⤡ button + the "focused" affordance (ADR 0032). */
+function FocusControl({ focused, onToggle }: { focused: boolean; onToggle: () => void }) {
+  return (
+    <div className="ml-auto flex shrink-0 items-center gap-2 pl-2">
+      {focused && <span className="font-mono text-[10px] uppercase tracking-[0.2em] text-accent">focused · Esc</span>}
+      <button
+        onClick={onToggle}
+        aria-label={focused ? "Restore layout" : "Maximize pane"}
+        title={focused ? "Restore (Esc)" : "Maximize (z)"}
+        className="flex h-7 w-7 items-center justify-center rounded-lg border border-border text-muted transition hover:border-text hover:text-text"
+      >
+        <svg width="14" height="14" viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="2" strokeLinecap="round" strokeLinejoin="round">
+          {focused ? (
+            <path d="M8 3v3a2 2 0 0 1-2 2H3M21 8h-3a2 2 0 0 1-2-2V3M16 21v-3a2 2 0 0 1 2-2h3M3 16h3a2 2 0 0 1 2 2v3" />
+          ) : (
+            <path d="M8 3H5a2 2 0 0 0-2 2v3M21 8V5a2 2 0 0 0-2-2h-3M16 21h3a2 2 0 0 0 2-2v-3M3 16v3a2 2 0 0 0 2 2h3" />
+          )}
+        </svg>
+      </button>
+    </div>
+  );
+}
+
+/** The presenter view's dominant content region: a tab strip switching between the
+ *  speaker **Notes** (default) and **one tab per plugin type** that exposes a presenter
+ *  surface (ADR 0031/0033). A type with several instances exposes them through a compact
+ *  dropdown in the console header, not one tab each (ADR 0035). Plus a maximize toggle (ADR 0032).
+ *  Identical structure desktop/mobile; with no instances the strip is just the notes label. */
+export function PresenterPanel({
+  notes,
+  variant,
+  focused = false,
+  onToggleFocus,
+}: {
+  notes: ReactNode;
+  variant: Variant;
+  focused?: boolean;
+  onToggleFocus?: () => void;
+}) {
+  const ctx = useLive();
+  const instances = usePresenterInstances(ctx);
+  // group by type, preserving first-seen order
+  const groups = useMemo(() => {
+    const m = new Map<string, Inst[]>();
+    for (const i of instances) {
+      const g = m.get(i.type);
+      if (g) g.push(i);
+      else m.set(i.type, [i]);
+    }
+    return [...m.values()];
+  }, [instances]);
+
+  const [tab, setTab] = useState<string>("notes"); // "notes" | `t:<type>`
+  const [pick, setPick] = useState<Record<string, string>>({}); // type → chosen ikey
+
+  const selectedGroup = groups.find((g) => `t:${g[0]!.type}` === tab) ?? null;
+  const showingNotes = !selectedGroup;
+  const selectedInst = selectedGroup ? selectedGroup.find((i) => ikey(i) === pick[selectedGroup[0]!.type]) ?? selectedGroup[0]! : null;
+  const pickerFor = selectedGroup && selectedGroup.length > 1 ? selectedGroup : null;
+  const stripPad = variant === "mobile" ? "px-4 pt-2 pb-1" : "pb-0.5";
+
+  return (
+    <>
+      <div className={`flex shrink-0 items-center gap-1.5 overflow-x-auto ${stripPad}`}>
+        {groups.length === 0 ? (
+          <NotesLabel />
+        ) : (
+          <>
+            <button onClick={() => setTab("notes")} className={tabClass(variant, showingNotes)}>
+              Notes
+            </button>
+            {ctx &&
+              groups.map((g) => (
+                <TypeTab
+                  key={g[0]!.type}
+                  ctx={ctx}
+                  group={g}
+                  variant={variant}
+                  selected={tab === `t:${g[0]!.type}`}
+                  onSelect={() => setTab(`t:${g[0]!.type}`)}
+                />
+              ))}
+          </>
+        )}
+        {/* focus toggle is desktop-only: the mobile panel is already full-bleed (ADR 0032/0027) */}
+        {onToggleFocus && variant === "desktop" && <FocusControl focused={focused} onToggle={onToggleFocus} />}
+      </div>
+
+      {/* instance switcher (dropdown) for the selected multi-instance type, keeps long
+          poll questions out of the strip (ADR 0035) */}
+      {ctx && pickerFor && (
+        <InstanceDropdown
+          ctx={ctx}
+          group={pickerFor}
+          selectedKey={pick[pickerFor[0]!.type] ?? ikey(pickerFor[0]!)}
+          onPick={(k) => setPick((p) => ({ ...p, [pickerFor![0]!.type]: k }))}
+          variant={variant}
+        />
+      )}
+
+      {/* key by selection: switching reuses this slot, but each instance's state may have a
+          different shape, without a remount the console would render one frame with the
+          previous instance's snapshot (e.g. a poll snapshot reaching the Q&A console) and
+          throw. The key forces a fresh mount → correct initial snapshot. */}
+      {showingNotes ? (
+        <div className={NOTES_CLASS[variant]}>{notes}</div>
+      ) : (
+        ctx && selectedInst && <Console key={ikey(selectedInst)} ctx={ctx} inst={selectedInst} variant={variant} />
+      )}
+    </>
+  );
+}

package/src/live/ui.ts

@@ -0,0 +1,8 @@
+import type { ComponentType } from "react";
+
+type CMap = Record<string, ComponentType<Record<string, unknown>>>;
+
+/** Merge author surface overrides over plugin defaults (overrides win). */
+export function mergeUi(base: CMap, over?: CMap): CMap {
+  return { ...base, ...(over ?? {}) };
+}

package/src/mobile.ts

@@ -0,0 +1,59 @@
+// Pure helpers for the mobile/touch behaviours (Featureset 5). Kept free of React
+// and the DOM so the decision logic is unit-testable; the hooks/components consume
+// these.
+
+/** Below this stage scale, controls inside the scaled canvas are too small to tap
+ *  comfortably, plugins offer a full-size breakout instead. */
+export const BREAKOUT_SCALE_MAX = 0.6;
+
+/** Should a plugin offer tap-to-expand rather than inline interaction?
+ *  Only on a coarse pointer (touch) with a shrunk stage, when allowed (not a
+ *  presenter preview) and the plugin actually takes input. */
+export function breakoutEligible(opts: {
+  allowed: boolean;
+  coarse: boolean;
+  scale: number;
+  interactive: boolean;
+}): boolean {
+  const { allowed, coarse, scale, interactive } = opts;
+  return allowed && coarse && interactive && scale > 0 && scale < BREAKOUT_SCALE_MAX;
+}
+
+export type TouchNav = "next" | "prev" | null;
+
+export interface TouchGesture {
+  dx: number; // end.x - start.x
+  dy: number; // end.y - start.y
+  /** tap x position (px) and the viewport width, for edge tap-zones */
+  x: number;
+  width: number;
+  /** did the gesture start on an interactive element? (then never navigate) */
+  onInteractive: boolean;
+}
+
+/** Resolve a finished touch into a slide move. A horizontal swipe wins; otherwise a
+ *  near-stationary tap in the outer edge zones advances/retreats. Returns null for
+ *  anything ambiguous or on interactive content. */
+export function resolveTouchGesture(g: TouchGesture, opts: { swipeMin?: number; tapMax?: number; edge?: number } = {}): TouchNav {
+  const swipeMin = opts.swipeMin ?? 50;
+  const tapMax = opts.tapMax ?? 10;
+  const edge = opts.edge ?? 0.25;
+  if (g.onInteractive) return null;
+
+  // horizontal swipe
+  if (Math.abs(g.dx) > swipeMin && Math.abs(g.dx) > Math.abs(g.dy)) {
+    return g.dx < 0 ? "next" : "prev";
+  }
+  // edge tap (only when essentially stationary)
+  if (Math.abs(g.dx) <= tapMax && Math.abs(g.dy) <= tapMax && g.width > 0) {
+    const frac = g.x / g.width;
+    if (frac <= edge) return "prev";
+    if (frac >= 1 - edge) return "next";
+  }
+  return null;
+}
+
+/** Selector for elements that own their own taps, touch nav ignores gestures here. */
+export const NO_NAV_SELECTOR = "button, a, input, textarea, select, [role=button], [data-pi-no-nav]";
+
+export const isPortrait = (w: number, h: number): boolean => h > w;

package/src/nav.ts

@@ -0,0 +1,149 @@
+import { useEffect } from "react";
+import { resolveTouchGesture, NO_NAV_SELECTOR } from "./mobile";
+
+/** Touch navigation: horizontal swipe + edge tap-zones, resolved by the pure
+ *  `resolveTouchGesture`. Reuses `onNext`/`onPrev` so step-reveals still run before
+ *  a slide change. Enable only where navigation is the user's job (standalone +
+ *  presenter), a live viewer follows the presenter. Gestures on interactive
+ *  elements (buttons, the plugin region) are ignored. */
+export function useTouchNav(opts: { enabled: boolean; onNext: () => void; onPrev: () => void }) {
+  const { enabled, onNext, onPrev } = opts;
+  useEffect(() => {
+    if (!enabled || typeof window === "undefined") return;
+    let sx = 0;
+    let sy = 0;
+    let onInteractive = false;
+    const onStart = (e: TouchEvent) => {
+      const t = e.changedTouches[0];
+      if (!t) return;
+      sx = t.clientX;
+      sy = t.clientY;
+      const el = e.target as Element | null;
+      onInteractive = !!el?.closest?.(NO_NAV_SELECTOR);
+    };
+    const onEnd = (e: TouchEvent) => {
+      const t = e.changedTouches[0];
+      if (!t) return;
+      const move = resolveTouchGesture({
+        dx: t.clientX - sx,
+        dy: t.clientY - sy,
+        x: sx,
+        width: window.innerWidth,
+        onInteractive,
+      });
+      if (move === "next") onNext();
+      else if (move === "prev") onPrev();
+    };
+    window.addEventListener("touchstart", onStart, { passive: true });
+    window.addEventListener("touchend", onEnd, { passive: true });
+    return () => {
+      window.removeEventListener("touchstart", onStart);
+      window.removeEventListener("touchend", onEnd);
+    };
+  }, [enabled, onNext, onPrev]);
+}
+
+/** True when a key event originates from a text-editable element. Typing in a
+ *  plugin's input (e.g. the Q&A question box) must NOT trigger the global deck
+ *  shortcuts, otherwise `f`/`o`/space/arrows/Enter drive the deck while you type.
+ *  Duck-typed (reads `tagName`/`isContentEditable`) so it's unit-testable without a
+ *  DOM. */
+export function isEditableTarget(target: EventTarget | null): boolean {
+  const el = target as (Partial<HTMLElement> & { tagName?: string }) | null;
+  if (!el) return false;
+  if (el.isContentEditable) return true;
+  switch (el.tagName) {
+    case "INPUT":
+    case "TEXTAREA":
+    case "SELECT":
+      return true;
+    default:
+      return false;
+  }
+}
+
+// Keyboard navigation. `onNext`/`onPrev` let the deck intercept for step reveals;
+// they fall back to slide nav. Slide index lives in the deck controller (synced).
+export function useDeckNav(opts: {
+  count: number;
+  setIndex: (updater: (n: number) => number | number) => void;
+  onNext?: () => void;
+  onPrev?: () => void;
+  onToggleBrand?: () => void;
+  onOpenPresenter?: () => void;
+  onToggleHelp?: () => void;
+  onFullscreen?: () => void;
+  onBlur?: () => void;
+  onOverview?: () => void;
+  onQr?: () => void;
+  onDigit?: (key: string) => void;
+}) {
+  const {
+    count,
+    setIndex,
+    onNext,
+    onPrev,
+    onToggleBrand,
+    onOpenPresenter,
+    onToggleHelp,
+    onFullscreen,
+    onBlur,
+    onOverview,
+    onQr,
+    onDigit,
+  } = opts;
+
+  useEffect(() => {
+    const next = onNext ?? (() => setIndex((n: number) => Math.min(n + 1, count - 1)));
+    const prev = onPrev ?? (() => setIndex((n: number) => Math.max(n - 1, 0)));
+    const onKey = (e: KeyboardEvent) => {
+      // don't hijack typing in a plugin's input (Q&A box, etc.)
+      if (isEditableTarget(e.target)) return;
+      switch (e.key) {
+        case "ArrowRight":
+        case " ":
+        case "PageDown":
+          e.preventDefault();
+          next();
+          break;
+        case "ArrowLeft":
+        case "PageUp":
+          e.preventDefault();
+          prev();
+          break;
+        case "Home":
+          setIndex(() => 0);
+          break;
+        case "End":
+          setIndex(() => count - 1);
+          break;
+        case "t":
+          onToggleBrand?.();
+          break;
+        case "p":
+          onOpenPresenter?.();
+          break;
+        case "f":
+          onFullscreen?.();
+          break;
+        case "b":
+          onBlur?.();
+          break;
+        case "o":
+          onOverview?.();
+          break;
+        case "q":
+          onQr?.();
+          break;
+        case "?":
+        case "h":
+          onToggleHelp?.();
+          break;
+        default:
+          if (onDigit && (/^[0-9]$/.test(e.key) || e.key === "Enter" || e.key === "Escape")) onDigit(e.key);
+      }
+    };
+    window.addEventListener("keydown", onKey);
+    return () => window.removeEventListener("keydown", onKey);
+  }, [count, setIndex, onNext, onPrev, onToggleBrand, onOpenPresenter, onToggleHelp, onFullscreen, onBlur, onOverview, onQr, onDigit]);
+}

package/src/slides.ts

@@ -0,0 +1,19 @@
+import type { ComponentType, ReactNode } from "react";
+import type { SlideTransition } from "./transitions";
+
+// A slide is either a bare component, or a module namespace with optional
+// `notes` (MDX: `export const notes = ...`; TSX: `export const notes`) and an
+// optional per-slide `transition` override (`export const transition = "slide"`).
+export type SlideInput =
+  | ComponentType
+  | { default: ComponentType; notes?: ReactNode; transition?: SlideTransition };
+
+export type NormalizedSlide = { Component: ComponentType; notes?: ReactNode; transition?: SlideTransition };
+
+export function normalizeSlides(slides: SlideInput[]): NormalizedSlide[] {
+  return slides.map((s) =>
+    typeof s === "function"
+      ? { Component: s }
+      : { Component: s.default, notes: s.notes, transition: s.transition },
+  );
+}

package/src/source.ts

@@ -0,0 +1,9 @@
+import { SOURCE_ATTR } from "./build/source-attr";
+
+/** True when the loaded deck embeds its own recoverable source (the default build), *  i.e. `liebstoeckel eject` would work on this file. Lets runtime UI offer an
+ *  "edit this deck" affordance only when it'll actually succeed (a deck built
+ *  `--no-inline-package` carries no source). No DOM (capture / SSR) → false. */
+export function hasEmbeddedSource(): boolean {
+  if (typeof document === "undefined") return false;
+  return !!document.querySelector(`script[${SOURCE_ATTR}]`);
+}