@liebstoeckel/engine 0.3.5

package/src/steps.tsx

@@ -0,0 +1,117 @@
+import { createContext, useContext, useId, useLayoutEffect, useState, type ReactNode } from "react";
+import { motion } from "motion/react";
+
+interface Entry {
+  id: string;
+  weight: number;
+}
+
+interface StepsApi {
+  step: number;
+  /** Claim `weight` consecutive reveal slots (default 1). Idempotent per id. */
+  register(id: string, weight?: number): void;
+  unregister(id: string): void;
+  /** 1-based index of the first slot this id occupies, or 0 until registered. */
+  startOf(id: string): number;
+}
+
+const StepsCtx = createContext<StepsApi | null>(null);
+
+/** The index of the slide a subtree belongs to. During the AnimatePresence overlap
+ *  the exiting slide still carries its own (old) index here, so descendants, e.g.
+ *  a persistent `<Slot>`, can tell whether they're on the *current* slide. -1
+ *  outside any slide. */
+export const SlideIndexContext = createContext(-1);
+
+/** Wraps the active slide; tracks the total reveal slots it contains (sum of each
+ *  consumer's weight) and the current reveal index. Reports `total` via onTotal
+ *  *with its slide index* so the deck can ignore a slide that's exiting (the
+ *  AnimatePresence overlap). Uses layout effects so `total` is set before any
+ *  keypress can advance the slide. */
+export function StepsProvider({
+  step,
+  slideIndex,
+  onTotal,
+  children,
+}: {
+  step: number;
+  slideIndex: number;
+  onTotal?: (slideIndex: number, total: number) => void;
+  children: ReactNode;
+}) {
+  const [entries, setEntries] = useState<Entry[]>([]);
+  const api: StepsApi = {
+    step,
+    register: (id, weight = 1) =>
+      setEntries((arr) => {
+        const i = arr.findIndex((e) => e.id === id);
+        if (i === -1) return [...arr, { id, weight }];
+        if (arr[i]!.weight === weight) return arr;
+        const copy = arr.slice();
+        copy[i] = { id, weight };
+        return copy;
+      }),
+    unregister: (id) => setEntries((arr) => arr.filter((e) => e.id !== id)),
+    startOf: (id) => {
+      let acc = 0;
+      for (const e of entries) {
+        if (e.id === id) return acc + 1;
+        acc += e.weight;
+      }
+      return 0;
+    },
+  };
+  const total = entries.reduce((s, e) => s + e.weight, 0);
+  useLayoutEffect(() => {
+    onTotal?.(slideIndex, total);
+  }, [total, slideIndex, onTotal]);
+  return (
+    <StepsCtx.Provider value={api}>
+      <SlideIndexContext.Provider value={slideIndex}>{children}</SlideIndexContext.Provider>
+    </StepsCtx.Provider>
+  );
+}
+
+/** A progressive reveal. Hidden until the deck's step reaches its slot (its
+ *  position among siblings). Outside a StepsProvider it's always shown. */
+export function Step({ children, className }: { children?: ReactNode; className?: string }) {
+  const ctx = useContext(StepsCtx);
+  const id = useId();
+  useLayoutEffect(() => {
+    ctx?.register(id, 1);
+    return () => ctx?.unregister(id);
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, []);
+  const start = ctx ? ctx.startOf(id) : 1;
+  const shown = !ctx ? true : start > 0 && ctx.step >= start;
+  return (
+    <motion.div
+      className={className}
+      initial={false}
+      animate={{ opacity: shown ? 1 : 0, y: shown ? 0 : 8 }}
+      transition={{ duration: 0.35, ease: [0.22, 1, 0.36, 1] }}
+      aria-hidden={!shown}
+    >
+      {children}
+    </motion.div>
+  );
+}
+
+/** For a multi-state reveal (e.g. animated code): claims `count - 1` reveal slots
+ *  and returns the active state index (0…count-1) as the deck steps through them.
+ *  Outside a provider (thumbnail capture / standalone) it resolves to the final
+ *  state so a static render shows the finished result. */
+export function useRevealState(count: number): number {
+  const ctx = useContext(StepsCtx);
+  const id = useId();
+  const weight = Math.max(0, count - 1);
+  useLayoutEffect(() => {
+    ctx?.register(id, weight);
+    return () => ctx?.unregister(id);
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [weight]);
+  if (!ctx) return Math.max(0, count - 1);
+  const start = ctx.startOf(id);
+  if (start === 0) return 0; // not registered on this render yet
+  return Math.max(0, Math.min(count - 1, ctx.step - start + 1));
+}

package/src/thumbnails.ts

@@ -0,0 +1,31 @@
+import { parseThumbnails, THUMBS_ATTR } from "./build/thumbnails";
+
+export interface ThumbnailSet {
+  w: number;
+  h: number;
+  /** data-URI for a slide, or undefined if not captured */
+  get(index: number): string | undefined;
+}
+
+let cache: ThumbnailSet | null | undefined;
+
+/** Read the thumbnails manifest embedded in the current document, if any.
+ *  Memoized (the manifest is static for a loaded deck). No DOM / no block → null,
+ *  so callers fall back to the live <DeckThumb>. */
+export function readThumbnails(): ThumbnailSet | null {
+  if (cache !== undefined) return cache;
+  cache = parse();
+  return cache;
+}
+
+function parse(): ThumbnailSet | null {
+  if (typeof document === "undefined") return null;
+  const el = document.querySelector(`script[${THUMBS_ATTR}]`);
+  if (!el?.textContent) return null;
+  try {
+    const m = parseThumbnails(el.textContent);
+    return { w: m.w, h: m.h, get: (i) => m.thumbs[i] };
+  } catch {
+    return null;
+  }
+}

package/src/transitions.ts

@@ -0,0 +1,88 @@
+import type { Transition, Variants } from "motion/react";
+
+/** Nav direction for a slide change: forward (next) or backward (prev). Fed to
+ *  the variants as Motion `custom`, so directional transitions mirror on back-nav. */
+export type SlideDirection = 1 | -1;
+
+/** A built-in preset name. */
+export type SlideTransitionName = "fade" | "blur" | "slide" | "zoom" | "none";
+
+/** A slide transition expressed as Motion variants (`enter`/`center`/`exit`) plus
+ *  base timing. A variant value may be `(dir: SlideDirection) => target` so the
+ *  transition can mirror on the navigation direction (see `slide`). */
+export interface SlideTransitionSpec {
+  variants: Variants;
+  transition?: Transition;
+}
+
+/** Either a built-in preset name or a custom spec. */
+export type SlideTransition = SlideTransitionName | SlideTransitionSpec;
+
+const EASE = [0.22, 1, 0.36, 1] as const;
+
+/** Built-in presets. `enter` is the off-state a slide animates *from*, `center`
+ *  is on-screen, `exit` is the off-state the leaving slide animates *to*. */
+export const TRANSITIONS: Record<SlideTransitionName, SlideTransitionSpec> = {
+  // Default: a light opacity cross-fade, no transform, no blur.
+  fade: {
+    variants: { enter: { opacity: 0 }, center: { opacity: 1 }, exit: { opacity: 0 } },
+    transition: { duration: 0.32, ease: "easeInOut" },
+  },
+  // The former default: opacity + a soft blur and a micro-scale.
+  blur: {
+    variants: {
+      enter: { opacity: 0, filter: "blur(10px)", scale: 1.015 },
+      center: { opacity: 1, filter: "blur(0px)", scale: 1 },
+      exit: { opacity: 0, filter: "blur(10px)", scale: 0.99 },
+    },
+    transition: { duration: 0.5, ease: EASE },
+  },
+  // Directional horizontal push; mirrors on back-nav via `custom`.
+  slide: {
+    variants: {
+      enter: (d: SlideDirection) => ({ x: d > 0 ? "100%" : "-100%", opacity: 1 }),
+      center: { x: 0, opacity: 1 },
+      exit: (d: SlideDirection) => ({ x: d > 0 ? "-100%" : "100%", opacity: 1 }),
+    },
+    transition: { duration: 0.55, ease: EASE },
+  },
+  // A gentle scale + fade "punch in".
+  zoom: {
+    variants: {
+      enter: { opacity: 0, scale: 0.92 },
+      center: { opacity: 1, scale: 1 },
+      exit: { opacity: 0, scale: 1.06 },
+    },
+    transition: { duration: 0.45, ease: EASE },
+  },
+  // Instant cut, no animation.
+  none: {
+    variants: { enter: { opacity: 1 }, center: { opacity: 1 }, exit: { opacity: 0 } },
+    transition: { duration: 0 },
+  },
+};
+
+/** `prefers-reduced-motion`: strip transforms/blur, keep only a tiny opacity fade. */
+const REDUCED: SlideTransitionSpec = {
+  variants: { enter: { opacity: 0 }, center: { opacity: 1 }, exit: { opacity: 0 } },
+  transition: { duration: 0.12 },
+};
+
+/** The transition used when neither the slide nor the deck sets one. */
+export const DEFAULT_TRANSITION: SlideTransitionName = "fade";
+
+/** Resolve a name / custom spec / `undefined` into a concrete spec. Reduced motion
+ *  always wins (accessibility); an unknown name falls back to the default. */
+export function resolveTransition(t: SlideTransition | undefined, reduceMotion = false): SlideTransitionSpec {
+  if (reduceMotion) return REDUCED;
+  if (t == null) return TRANSITIONS[DEFAULT_TRANSITION];
+  if (typeof t === "string") return TRANSITIONS[t] ?? TRANSITIONS[DEFAULT_TRANSITION];
+  return t;
+}
+
+/** On a coarse-pointer (mobile/touch) device, slide transitions are disabled by
+ *  default, they're janky on a heavily down-scaled stage and snappy cuts read
+ *  better there. Set `Present`'s `mobileTransitions` to opt back in. */
+export function mobileTransitionsDisabled(coarse: boolean, mobileTransitions = false): boolean {
+  return coarse && !mobileTransitions;
+}

package/src/useCoarsePointer.ts

@@ -0,0 +1,17 @@
+import { useEffect, useState } from "react";
+
+/** True on a coarse (touch) pointer. Used to upsize tap targets, swap the
+ *  keyboard help for the ⋮ menu, and (by default) drop slide transitions on
+ *  mobile. SSR / no-`matchMedia` safe (returns false). */
+export function useCoarsePointer(): boolean {
+  const [coarse, setCoarse] = useState(false);
+  useEffect(() => {
+    if (typeof matchMedia !== "function") return;
+    const mq = matchMedia("(pointer: coarse)");
+    const update = () => setCoarse(mq.matches);
+    update();
+    mq.addEventListener?.("change", update);
+    return () => mq.removeEventListener?.("change", update);
+  }, []);
+  return coarse;
+}

package/src/useDeckSync.ts

@@ -0,0 +1,85 @@
+import { useCallback, useEffect, useRef, useState } from "react";
+import { stepForward, stepBack } from "./delivery";
+
+// Cross-window sync over BroadcastChannel. The audience window and the presenter
+// window share { index, step, total, startedAt }; either can drive. On open, a new
+// window broadcasts a "request" and the others reply so it snaps to the live state.
+export type DeckState = { index: number; step: number; total: number; startedAt: number };
+type Msg = ({ type: "state" } & DeckState) | { type: "request" };
+
+const CHANNEL = "liebstoeckel";
+
+export function useDeckSync(count: number) {
+  const [state, setState] = useState<DeckState>(() => ({ index: 0, step: 0, total: 0, startedAt: Date.now() }));
+  const ref = useRef(state);
+  ref.current = state;
+  const chan = useRef<BroadcastChannel | null>(null);
+  const clamp = (n: number) => Math.min(Math.max(n, 0), Math.max(count - 1, 0));
+
+  useEffect(() => {
+    const ch = new BroadcastChannel(CHANNEL);
+    chan.current = ch;
+    ch.onmessage = (e: MessageEvent<Msg>) => {
+      const m = e.data;
+      if (m.type === "state") {
+        setState((s) =>
+          s.index === m.index && s.step === m.step && s.total === m.total && s.startedAt === m.startedAt
+            ? s
+            : { index: m.index, step: m.step, total: m.total, startedAt: m.startedAt },
+        );
+      } else if (m.type === "request") {
+        ch.postMessage({ type: "state", ...ref.current });
+      }
+    };
+    ch.postMessage({ type: "request" });
+    return () => ch.close();
+  }, []);
+
+  const commit = useCallback((patch: Partial<DeckState>) => {
+    setState((s) => {
+      const ns = { ...s, ...patch };
+      chan.current?.postMessage({ type: "state", ...ns });
+      return ns;
+    });
+  }, []);
+
+  const setIndex = useCallback(
+    (updater: number | ((n: number) => number)) =>
+      commit({ index: clamp(typeof updater === "function" ? updater(ref.current.index) : updater) }),
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+    [commit, count],
+  );
+  const setStep = useCallback((step: number) => commit({ step }), [commit]);
+  const setTotal = useCallback((total: number) => {
+    if (ref.current.total !== total) commit({ total });
+  }, [commit]);
+  const resetTimer = useCallback(() => commit({ startedAt: Date.now() }), [commit]);
+
+  // next/prev read the freshest state (ref) so rapid presses don't read stale step
+  const next = useCallback(() => {
+    const s = ref.current;
+    const r = stepForward(s.step, s.total);
+    commit(r.advanceSlide ? { index: clamp(s.index + 1), step: 0 } : { step: r.step });
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [commit, count]);
+  const prev = useCallback(() => {
+    const s = ref.current;
+    const r = stepBack(s.step);
+    commit(r.retreatSlide ? { index: clamp(s.index - 1), step: 0 } : { step: r.step });
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [commit, count]);
+
+  return {
+    index: state.index,
+    step: state.step,
+    total: state.total,
+    startedAt: state.startedAt,
+    canDrive: true,
+    setIndex,
+    setStep,
+    setTotal,
+    resetTimer,
+    next,
+    prev,
+  };
+}