@liebstoeckel/engine 0.3.5

package/src/code/diff.ts

@@ -0,0 +1,61 @@
+import type { CodeToken, KeyedStep, TokenizedStep } from "./types";
+
+const lineText = (tokens: CodeToken[]): string => tokens.map((t) => t.content).join("");
+
+/** For each line in `cur`, the index of the line it matches in `prev` (or null).
+ *  Standard LCS over line text, biased to keep the longest common run aligned so
+ *  unchanged lines around an edit keep their identity. */
+export function matchLines(prev: string[], cur: string[]): (number | null)[] {
+  const m = prev.length;
+  const n = cur.length;
+  const dp: number[][] = Array.from({ length: m + 1 }, () => new Array<number>(n + 1).fill(0));
+  for (let i = m - 1; i >= 0; i--) {
+    for (let j = n - 1; j >= 0; j--) {
+      dp[i]![j] = prev[i] === cur[j] ? dp[i + 1]![j + 1]! + 1 : Math.max(dp[i + 1]![j]!, dp[i]![j + 1]!);
+    }
+  }
+  const match = new Array<number | null>(n).fill(null);
+  let i = 0;
+  let j = 0;
+  while (i < m && j < n) {
+    if (prev[i] === cur[j]) {
+      match[j] = i;
+      i++;
+      j++;
+    } else if (dp[i + 1]![j]! >= dp[i]![j + 1]!) {
+      i++;
+    } else {
+      j++;
+    }
+  }
+  return match;
+}
+
+/** Assign every line in every step a key that is stable for the "same" line across
+ *  consecutive steps (matched by LCS, chained). Lines that persist keep their key
+ *  → Motion morphs their position; new keys enter, dropped keys exit. */
+export function keySteps(steps: TokenizedStep[]): KeyedStep[] {
+  const out: KeyedStep[] = [];
+  let counter = 0;
+  let prevKeys: string[] = [];
+  let prevText: string[] = [];
+
+  for (let s = 0; s < steps.length; s++) {
+    const lines = steps[s]!.lines;
+    const texts = lines.map(lineText);
+    let keys: string[];
+    if (s === 0) {
+      keys = texts.map(() => `l${counter++}`);
+    } else {
+      const match = matchLines(prevText, texts);
+      keys = texts.map((_, idx) => {
+        const p = match[idx];
+        return p != null ? prevKeys[p]! : `l${counter++}`;
+      });
+    }
+    out.push({ lines: lines.map((tokens, idx) => ({ key: keys[idx]!, tokens })) });
+    prevKeys = keys;
+    prevText = texts;
+  }
+  return out;
+}

package/src/code/macro.ts

@@ -0,0 +1,24 @@
+// Bun macro entrypoint. Import it with `with { type: "macro" }` from a deck so the
+// code is tokenized at BUILD time and the result inlined as a literal, no Shiki,
+// grammars, or WASM ship to the browser. Pass string literals so the bundler can
+// evaluate the call statically.
+//
+//   import { codeStory } from "@liebstoeckel/engine/code" with { type: "macro" };
+//   <CodeMagic steps={codeStory([{ code: `const a = 1`, lang: "ts" }, …])} />
+import { tokenizeStep } from "./tokenize";
+import type { TokenizedStep } from "./types";
+
+export interface CodeInput {
+  code: string;
+  lang?: string;
+}
+
+/** Tokenize a sequence of code states for <CodeMagic>. */
+export async function codeStory(steps: CodeInput[]): Promise<TokenizedStep[]> {
+  return Promise.all(steps.map((s) => tokenizeStep(s.code, s.lang)));
+}
+
+/** Tokenize a single code state (a one-step story). */
+export async function code(src: string, lang = "ts"): Promise<TokenizedStep> {
+  return tokenizeStep(src, lang);
+}

package/src/code/tokenize.ts

@@ -0,0 +1,72 @@
+// BUILD-TIME ONLY. Tokenizes code with Shiki using its css-variables theme, so
+// every token's color is a `var(--shiki-token-*)` string that the theme binds to
+// the active brand at runtime. Imported only from the `code` macro (stripped from
+// the browser bundle) and from build tooling, never from the deck runtime.
+import {
+  createCssVariablesTheme,
+  createHighlighter,
+  type BundledLanguage,
+  type Highlighter,
+  type SpecialLanguage,
+} from "shiki";
+import type { CodeToken, TokenizedStep } from "./types";
+
+const THEME = createCssVariablesTheme({ name: "brand", variablePrefix: "--shiki-", fontStyle: true });
+
+// A pragmatic default language set; build-time cost only.
+const LANGS = [
+  "typescript",
+  "tsx",
+  "javascript",
+  "jsx",
+  "json",
+  "bash",
+  "html",
+  "css",
+  "python",
+  "rust",
+  "go",
+  "sql",
+  "yaml",
+  "markdown",
+  "diff",
+] as const;
+
+let hl: Promise<Highlighter> | null = null;
+function highlighter(): Promise<Highlighter> {
+  if (!hl) hl = createHighlighter({ themes: [THEME], langs: LANGS as unknown as string[] });
+  return hl;
+}
+
+function aliasLang(lang: string): string {
+  const l = lang.toLowerCase();
+  return (
+    {
+      ts: "typescript",
+      js: "javascript",
+      mjs: "javascript",
+      sh: "bash",
+      shell: "bash",
+      zsh: "bash",
+      md: "markdown",
+      yml: "yaml",
+      py: "python",
+      rs: "rust",
+    }[l] ?? l
+  );
+}
+
+/** Tokenize one code state. Unknown languages fall back to plain text. */
+export async function tokenizeStep(code: string, lang = "ts"): Promise<TokenizedStep> {
+  const h = await highlighter();
+  const resolved = aliasLang(lang);
+  const useLang = (h.getLoadedLanguages().includes(resolved) ? resolved : "text") as
+    | BundledLanguage
+    | SpecialLanguage;
+  const src = code.replace(/\n+$/, "");
+  const { tokens } = h.codeToTokens(src, { lang: useLang, theme: "brand" });
+  const lines: CodeToken[][] = tokens.map((line) =>
+    line.map((t) => ({ content: t.content, color: t.color, fontStyle: t.fontStyle })),
+  );
+  return { lang: resolved, lines };
+}

package/src/code/types.ts

@@ -0,0 +1,24 @@
+// Build-time tokenized code, shaped to be macro-serializable (plain JSON).
+// `fontStyle` is Shiki's FontStyle bitfield: 1=italic, 2=bold, 4=underline.
+
+export interface CodeToken {
+  content: string;
+  color?: string;
+  fontStyle?: number;
+}
+
+/** One code state: lines of colored tokens, produced by Shiki at build time. */
+export interface TokenizedStep {
+  lang: string;
+  lines: CodeToken[][];
+}
+
+export interface KeyedLine {
+  /** stable across steps for the "same" line, so it FLIP-animates between states */
+  key: string;
+  tokens: CodeToken[];
+}
+
+export interface KeyedStep {
+  lines: KeyedLine[];
+}

package/src/delivery.ts

@@ -0,0 +1,32 @@
+// Pure helpers for live-delivery controls (fullscreen, numeric jump, step nav).
+
+export const clampIndex = (n: number, count: number) => Math.min(Math.max(n, 0), Math.max(count - 1, 0));
+
+export function fullscreenAction(isFullscreen: boolean): "enter" | "exit" {
+  return isFullscreen ? "exit" : "enter";
+}
+
+export async function toggleFullscreen(el: Element): Promise<void> {
+  if (typeof document === "undefined") return;
+  if (document.fullscreenElement) await document.exitFullscreen();
+  else await (el as HTMLElement).requestFullscreen?.();
+}
+
+/** Accumulate digit keys into a buffer; Enter commits a 1-based slide number,
+ *  Escape clears. Returns the next buffer and a committed (0-based) index | null. */
+export function accumulateDigits(buffer: string, key: string): { buffer: string; commit: number | null } {
+  if (/^[0-9]$/.test(key)) return { buffer: (buffer + key).slice(0, 3), commit: null };
+  if (key === "Enter" && buffer) return { buffer: "", commit: parseInt(buffer, 10) - 1 };
+  if (key === "Escape") return { buffer: "", commit: null };
+  return { buffer, commit: null };
+}
+
+/** Advance within a slide's steps; once past the last step, signal a slide change. */
+export function stepForward(step: number, total: number): { step: number; advanceSlide: boolean } {
+  return step < total ? { step: step + 1, advanceSlide: false } : { step: 0, advanceSlide: true };
+}
+
+/** Retreat a step; at the first step, signal a slide change. */
+export function stepBack(step: number): { step: number; retreatSlide: boolean } {
+  return step > 0 ? { step: step - 1, retreatSlide: false } : { step: 0, retreatSlide: true };
+}

package/src/index.ts

@@ -0,0 +1,55 @@
+export { Present } from "./Present";
+export { Deck, type DeckProps } from "./Deck";
+export { PresenterView } from "./PresenterView";
+export { ScaledStage, SlideFrame, STAGE_W, STAGE_H } from "./Stage";
+export { HelpOverlay } from "./HelpOverlay";
+export { useDeckSync } from "./useDeckSync";
+export { useDeckNav } from "./nav";
+export { normalizeSlides, type SlideInput } from "./slides";
+export {
+  resolveTransition,
+  TRANSITIONS,
+  DEFAULT_TRANSITION,
+  type SlideTransition,
+  type SlideTransitionName,
+  type SlideTransitionSpec,
+  type SlideDirection,
+} from "./transitions";
+export { CaptureView } from "./CaptureView";
+export { PrintView } from "./PrintView";
+export { readThumbnails, type ThumbnailSet } from "./thumbnails";
+export { hasEmbeddedSource } from "./source";
+export { Step, StepsProvider, useRevealState } from "./steps";
+export { CodeMagic } from "./CodeMagic";
+export type { TokenizedStep, CodeToken } from "./code/types";
+export {
+  fullscreenAction,
+  toggleFullscreen,
+  accumulateDigits,
+  stepForward,
+  stepBack,
+  clampIndex,
+} from "./delivery";
+export {
+  PersistentProvider,
+  PersistentLayer,
+  Slot,
+  type PersistentItem,
+} from "./PersistentLayer";
+export { Magic, Atmosphere } from "@liebstoeckel/components";
+export {
+  Plugin,
+  LiveProvider,
+  useLive,
+  detectLive,
+  getParticipantId,
+  connectLive,
+  getDeckIndex,
+  setDeckIndex,
+  useLiveDeck,
+  mergeUi,
+  type LiveInfo,
+  type LiveConnection,
+  type LiveContextValue,
+  type DeckController,
+} from "./live";

package/src/live/Plugin.tsx

@@ -0,0 +1,160 @@
+import { createContext, useContext, useEffect, useMemo, useState, type ComponentType, type ReactNode } from "react";
+import { AnimatePresence, LayoutGroup } from "motion/react";
+import type * as Y from "yjs";
+import { pluginState, registerPluginInstance, type ClientProps, type PluginDef, type Role, type ThemeTokens } from "@liebstoeckel/plugin-sdk";
+import { mergeUi } from "./ui";
+import { GlowTap, BreakoutSheet, useBreakoutEligible } from "./breakout";
+import { PluginBoundary } from "./PluginBoundary";
+
+export interface LiveContextValue {
+  live: boolean;
+  role: Role;
+  participant: string;
+  doc: Y.Doc;
+  theme: ThemeTokens;
+  /** read-only follow-along link, for the in-deck QR (live only) */
+  viewerUrl?: string;
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  plugins: Record<string, PluginDef<any>>;
+}
+
+const LiveCtx = createContext<LiveContextValue | null>(null);
+export const useLive = (): LiveContextValue | null => useContext(LiveCtx);
+
+export function LiveProvider({ value, children }: { value: LiveContextValue; children: ReactNode }) {
+  return <LiveCtx.Provider value={value}>{children}</LiveCtx.Provider>;
+}
+
+/** Subscribe to a plugin's slice of the shared doc and assemble its `ClientProps`.
+ *  The single piece of plumbing behind `<Plugin>`, the global surfaces, and the
+ *  presenter console, so every surface reads the same live state identically. */
+export function usePluginProps(
+  ctx: LiveContextValue,
+  id: string,
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  def: PluginDef<any>,
+  props: Record<string, unknown> = {},
+  instance = "",
+): ClientProps<unknown> {
+  const state = useMemo(() => pluginState(ctx.doc, id, def.state, instance), [ctx.doc, id, def, instance]);
+  const [snap, setSnap] = useState<unknown>(() => state.snapshot());
+  useEffect(() => {
+    setSnap(state.snapshot());
+    return state.subscribe(setSnap);
+  }, [state]);
+  return {
+    doc: ctx.doc,
+    state,
+    snapshot: snap,
+    role: ctx.role,
+    live: ctx.live,
+    participantId: ctx.participant,
+    theme: ctx.theme,
+    ui: mergeUi({}, {}),
+    props,
+    instance,
+  };
+}
+
+/** Place a plugin in a slide. Renders the plugin's `Slide` when a server is
+ *  connected, else its `fallback`. Subscribes to the shared state snapshot. */
+export function Plugin({
+  id,
+  instance = "",
+  title,
+  props = {},
+  components = {},
+}: {
+  id: string;
+  /** instance discriminator (ADR 0033); omit for the default slice. Two placements with
+   *  the same (id, instance) share state, that's how you intentionally mirror one. */
+  instance?: string;
+  /** optional human label for this instance, used in the presenter tabs to tell
+   *  sibling instances apart (a plugin's `presenter.title(snapshot)` takes precedence). */
+  title?: string;
+  props?: Record<string, unknown>;
+  components?: Record<string, ComponentType<Record<string, unknown>>>;
+}) {
+  const ctx = useContext(LiveCtx);
+  const def = ctx?.plugins[id];
+  const state = useMemo(
+    () => (ctx && def ? pluginState(ctx.doc, id, def.state, instance) : null),
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+    [ctx?.doc, id, def, instance],
+  );
+  const [snap, setSnap] = useState<unknown>(() => state?.snapshot());
+  const [open, setOpen] = useState(false);
+  // hooks run unconditionally (before any early return)
+  const interactive = def?.client.interactive !== false;
+  const eligible = useBreakoutEligible(interactive);
+
+  useEffect(() => {
+    if (!state) return;
+    setSnap(state.snapshot());
+    return state.subscribe(setSnap);
+  }, [state]);
+
+  // Register this instance so the presenter console / server can discover it (ADR 0033).
+  useEffect(() => {
+    if (ctx?.live && def) registerPluginInstance(ctx.doc, id, instance, { title });
+  }, [ctx?.live, ctx?.doc, def, id, instance, title]);
+
+  // Inside a <Present> but the id isn't in its `plugins={[…]}` — a very common authoring
+  // slip. Without this the component silently renders nothing (no fallback, no error),
+  // leaving a baffling blank slide. Warn so the mistake explains itself.
+  useEffect(() => {
+    if (ctx && !def) {
+      console.warn(
+        `[liebstoeckel] <Plugin id="${id}"> is not registered — add its plugin to ` +
+          `<Present plugins={[…]}> or it renders nothing.`,
+      );
+    }
+  }, [ctx, def, id]);
+
+  if (!ctx || !def || !state) return null;
+
+  if (!ctx.live) {
+    const Fb = def.client.fallback;
+    return Fb ? <Fb snapshot={snap as never} props={props} /> : null;
+  }
+
+  const Slide = def.client.Slide;
+  // Isolate each surface's Motion layout tree: a plugin's `layoutId` (e.g. Q&A's ranked
+  // rows) is also rendered by other live surfaces of the same plugin, the global panel,
+  // the presenter console, the mobile breakout. Sharing one `layoutId` across them makes
+  // Motion morph one into another (rows "disappear" from the slide). A per-surface
+  // LayoutGroup namespaces the ids so intra-surface animation still works but they never
+  // collide across surfaces (the ADR 0026 hazard, generalised).
+  const slide = (key: string) => (
+    <LayoutGroup key={key} id={`plugin:${id}:${instance}:${key}`}>
+      <PluginBoundary resetKey={snap}>
+        <Slide
+          doc={ctx.doc}
+          state={state}
+          snapshot={snap as never}
+          role={ctx.role}
+          live={ctx.live}
+          participantId={ctx.participant}
+          theme={ctx.theme}
+          ui={mergeUi({}, components)}
+          props={props}
+          instance={instance}
+        />
+      </PluginBoundary>
+    </LayoutGroup>
+  );
+
+  // Desktop / fine pointer: inline, as today.
+  if (!eligible) return slide("inline");
+
+  // Touch + shrunk stage: a tappable glowing preview (non-interactive) that opens
+  // the same plugin full-size in a sheet outside the scaled canvas.
+  return (
+    <>
+      <GlowTap label={id} onOpen={() => setOpen(true)}>
+        {slide("preview")}
+      </GlowTap>
+      <AnimatePresence>{open && <BreakoutSheet label={id} onClose={() => setOpen(false)}>{slide("sheet")}</BreakoutSheet>}</AnimatePresence>
+    </>
+  );
+}

package/src/live/PluginBoundary.tsx

@@ -0,0 +1,34 @@
+import { Component, type ErrorInfo, type ReactNode } from "react";
+
+// Contain a single plugin surface's render failure. A live deck shares its state with
+// an untrusted audience, so a malformed remote value could otherwise throw during render
+// (e.g. React refusing a non-string child) and unmount the *whole* deck — a deck-wide
+// overlay that throws white-screens the presentation for everyone. State is sanitized
+// upstream so this should never fire, but it's the last line of defense: a failing plugin
+// degrades to its fallback (nothing by default) and the rest of the deck keeps rendering.
+// It auto-recovers when `resetKey` changes (e.g. the offending state entry is replaced).
+export class PluginBoundary extends Component<
+  { children: ReactNode; fallback?: ReactNode; resetKey?: unknown },
+  { failed: boolean }
+> {
+  state = { failed: false };
+
+  static getDerivedStateFromError(): { failed: boolean } {
+    return { failed: true };
+  }
+
+  componentDidUpdate(prev: Readonly<{ resetKey?: unknown }>) {
+    if (this.state.failed && prev.resetKey !== this.props.resetKey) {
+      this.setState({ failed: false });
+    }
+  }
+
+  componentDidCatch(err: Error, info: ErrorInfo) {
+    // eslint-disable-next-line no-console
+    console.error("[liebstoeckel] plugin render error (contained):", err, info.componentStack);
+  }
+
+  render() {
+    return this.state.failed ? (this.props.fallback ?? null) : this.props.children;
+  }
+}