@miadi/stateloom-web 0.3.3 → 0.3.4

package/server/src/components/stage/StageLayer.tsx

@@ -23,20 +23,43 @@
  *   the answer shows one line by the controls for a few seconds ("Mia answered
  *   mark 3"), which opens the thread when tapped. Nothing takes focus and no
  *   card opens by itself.
+ * - Pins: on opening a drawing with open marks and nothing lit, the view frames
+ *   the marks (never below a legible scale); pins stay inside the board, fan out
+ *   when they share a point, and never sit under the board's buttons or under the
+ *   caption (the phone's sheet), where they could not be tapped.
+ * - On a phone the cards open in the sheet at the bottom of the board, in the
+ *   caption's place (StageProvider); the Talk conversation and a card take turns.
+ * - Elements are named as the person sees them; a board that knows words only it
+ *   can give (a sequence's messages) passes `labels`.
+ * - The Talk dock's list of marks opens a mark here (`requestMark`): the thread
+ *   opens and the view frames its mark.
  *
  * The sidecar is written through /api/marks; the hub is told after.
  */
 import { useCallback, useEffect, useMemo, useRef, useState, type RefObject } from "react";
-import { MarkComposer, MarkIcon, MarkNotice, MarksIcon, MarkThread, MarksPanel, StageOverlay, useMarksRead, type MarkDraft } from "@miadi/stateloom-canvas";
+import { createPortal } from "react-dom";
+import {
+  fitLegibly,
+  markAnchor,
+  MarkComposer,
+  MarkIcon,
+  MarkNotice,
+  MarksIcon,
+  MarkThread,
+  MarksPanel,
+  StageOverlay,
+  useMarksRead,
+  type MarkDraft,
+} from "@miadi/stateloom-canvas";
 import {
   agentWordIn,
   agentWordText,
   boxesOf,
   markCounts,
   unreadMarks,
-  fitToBoxes,
   formatReview,
   screenToWorld,
+  type Box,
   type DocKind,
   type ElementBox,
   type Mark,
@@ -47,6 +70,7 @@ import { useStageContext } from "./StageProvider";
 import { episodeOf } from "./CompanionLayer";
 import { presenceLine, useEpisodePresence } from "./useEpisodePresence";
 import { urlParam } from "@/lib/systemParam";
+import { MARK_REQUEST_EVENT, clearMarkRequest, markRequested } from "@/lib/markRequest";
 
 export interface StageLayerProps {
   /** The drawing this board shows, absolute. Null until the workspace has read it. */
@@ -65,13 +89,25 @@ export interface StageLayerProps {
    * level, a sequence shown as a list. The workspace brings it on.
    */
   onReveal?: (focuses: readonly string[]) => void;
+  /** Words for elements only this board can name (a sequence's messages), by focus key. */
+  labels?: Readonly<Record<string, string>>;
 }
 
 /** How long the line that says an agent answered stays by the controls. */
 const NOTICE_MS = 7000;
 
 const quietButton =
-  "flex h-9 min-w-9 items-center justify-center gap-1 rounded-lg border border-gray-700 bg-gray-900/90 px-2 text-sm text-gray-200 shadow-lg backdrop-blur hover:bg-gray-800";
+  "stage-quiet-btn flex h-9 min-w-9 items-center justify-center gap-1 rounded-lg border border-gray-700 bg-gray-900/90 px-2 text-sm text-gray-200 shadow-lg backdrop-blur hover:bg-gray-800";
+
+/** How much of the board's bottom the caption, or the phone's sheet, covers. */
+function coveredBottom(rect: DOMRect): number {
+  let top = Infinity;
+  for (const sel of [".stage-sheet", ".stage-caption-host .slc-stage-caption"]) {
+    const r = document.querySelector(sel)?.getBoundingClientRect();
+    if (r && r.height > 0 && r.top < rect.bottom) top = Math.min(top, r.top);
+  }
+  return top === Infinity ? 0 : Math.max(0, rect.bottom - top + 8);
+}
 
 async function postMarks(docPath: string, body: unknown): Promise<{ marks: Mark[]; change: { action: "add" | "reply" | "resolve" | "reopen" | "remove"; id: string } }> {
   const r = await fetch(`/api/marks?doc=${encodeURIComponent(docPath)}`, {
@@ -84,7 +120,7 @@ async function postMarks(docPath: string, body: unknown): Promise<{ marks: Mark[
   return data;
 }
 
-export default function StageLayer({ docPath, kind, viewport, setViewport, boxes, boardRef, focus = null, level, onReveal }: StageLayerProps) {
+export default function StageLayer({ docPath, kind, viewport, setViewport, boxes, boardRef, focus = null, level, onReveal, labels }: StageLayerProps) {
   const stage = useStageContext();
   const [marks, setMarks] = useState<Mark[]>([]);
   const [marking, setMarking] = useState(false);
@@ -100,6 +136,26 @@ export default function StageLayer({ docPath, kind, viewport, setViewport, boxes
   selectedRef.current = selected;
   const { read, markRead } = useMarksRead(docPath);
 
+  // ── The drawing on this board, for the caption ──────────────────────
+  const setBoard = stage?.setBoard;
+  useEffect(() => {
+    if (!setBoard || !docPath) return;
+    setBoard(docPath);
+    return () => setBoard(null);
+  }, [setBoard, docPath]);
+
+  /** Frame `targets` in what the caption (or the phone's sheet) leaves of the board, legibly. */
+  const frame = useCallback(
+    (targets: readonly Box[], opts: { floor?: number } = {}) => {
+      const rect = boardRef.current?.getBoundingClientRect();
+      if (!rect?.width || !targets.length) return;
+      const covered = coveredBottom(rect);
+      const height = Math.max(rect.height * 0.4, rect.height - covered);
+      setViewport(fitLegibly(targets, rect.width, height, { padding: 48, maxScale: 1, floor: opts.floor ?? 0.2 }));
+    },
+    [boardRef, setViewport],
+  );
+
   // ── This drawing's marks ─────────────────────────────────────────────
   const load = useCallback(() => {
     if (!docPath) return;
@@ -175,26 +231,62 @@ export default function StageLayer({ docPath, kind, viewport, setViewport, boxes
       return;
     }
     fitted.current = litHere.nonce;
-    const fit = (): void => {
-      const rect = boardRef.current?.getBoundingClientRect();
-      if (!rect?.width) return;
-      // The caption covers the bottom of the board: fit into what it leaves.
-      const caption = document.querySelector(".stage-caption-host .slc-stage-caption")?.getBoundingClientRect();
-      const covered = caption && caption.top < rect.bottom ? Math.max(0, rect.bottom - caption.top + 8) : 0;
-      const height = Math.max(rect.height * 0.4, rect.height - covered);
-      setViewport(fitToBoxes(targets, rect.width, height, { padding: 48, maxScale: 1 }));
-    };
+    // The caption covers the bottom of the board: fit into what it leaves.
+    const fit = (): void => frame(targets);
     fit();
     // Again after the workspace's own fit or centring has landed. Not cleared
     // when the board's boxes move under it (a live update arrives just after a
     // drawing opens) — only when the layer goes.
     if (refit.current) clearTimeout(refit.current);
     refit.current = setTimeout(fit, 520);
-  }, [litHere, litBoxes, region, spotlight, boardRef, setViewport, onReveal]);
+  }, [litHere, litBoxes, region, spotlight, frame, onReveal]);
   useEffect(() => () => {
     if (refit.current) clearTimeout(refit.current);
   }, []);
 
+  // ── Opening a drawing with marks: the view frames them ──────────────
+  // Once per drawing, when nothing is lit here (a lit step decides the view): what the marks
+  // point at on this level, and the element in hand. Looked at again after the workspace's
+  // own first view and this browser's remembered view have landed, and framed again only
+  // if that view hides some of them.
+  const marksFramed = useRef<string | null>(null);
+  const marksRefit = useRef<ReturnType<typeof setTimeout>[]>([]);
+  const viewportRef = useRef(viewport);
+  viewportRef.current = viewport;
+  useEffect(() => {
+    if (!docPath || marksFramed.current === docPath) return;
+    if (litHere) {
+      marksFramed.current = docPath;
+      return;
+    }
+    const open = marks.filter((m) => m.status !== "resolved" && (!m.level || !level || m.level === level));
+    if (!open.length || !boxes.length) return;
+    // Marks that name elements wait for the board to draw them (a board still showing the
+    // layout it had before this drawing arrived draws none of them); an area stands alone.
+    const named = open.filter((m) => m.elements?.length);
+    const drawn = named.filter((m) => boxesOf(boxes, m.elements!).length > 0);
+    if (named.length && !drawn.length) return;
+    const anchors = [...drawn, ...open.filter((m) => !m.elements?.length)].map((m) => markAnchor(m, boxes)).filter((b): b is Box => !!b);
+    marksFramed.current = docPath;
+    if (!anchors.length) return;
+    const targets = [...anchors, ...(focus ? boxesOf(boxes, [focus]) : [])];
+    const fitIfHidden = (): void => {
+      const rect = boardRef.current?.getBoundingClientRect();
+      if (!rect?.width) return;
+      const vp = viewportRef.current;
+      const a = screenToWorld(vp, { x: 0, y: 0 });
+      const b = screenToWorld(vp, { x: rect.width, y: rect.height - coveredBottom(rect) });
+      const seen = targets.every((t) => t.x >= a.x && t.y >= a.y && t.x + t.width <= b.x && t.y + t.height <= b.y);
+      if (!seen) frame(targets, { floor: 0.55 });
+    };
+    fitIfHidden();
+    for (const t of marksRefit.current) clearTimeout(t);
+    marksRefit.current = [setTimeout(fitIfHidden, 520), setTimeout(fitIfHidden, 1400)];
+  }, [docPath, marks, boxes, litHere, level, focus, frame, boardRef]);
+  useEffect(() => () => {
+    for (const t of marksRefit.current) clearTimeout(t);
+  }, []);
+
   // Answer on the caption: a composer on what is lit (or the element in hand).
   const answered = useRef(stage?.answerNonce ?? 0);
   useEffect(() => {
@@ -246,13 +338,101 @@ export default function StageLayer({ docPath, kind, viewport, setViewport, boxes
     if (selectedMark) markRead(selectedMark);
     // eslint-disable-next-line react-hooks/exhaustive-deps
   }, [selectedMark?.id, selectedReplies, markRead]);
-  const openThread = (id: string): void => {
+  const openThread = useCallback((id: string): void => {
     setDraft(null);
     setPanel(false);
     setMarking(false);
     setSelected(id);
     setNotice(null);
-  };
+  }, []);
+
+  // ── A mark asked for from outside the board (the Talk dock's list) ──
+  useEffect(() => {
+    const take = (): void => {
+      const id = markRequested(docPath);
+      const mark = id ? marks.find((m) => m.id === id) : null;
+      if (!mark) return;
+      clearMarkRequest();
+      openThread(mark.id);
+      const at = markAnchor(mark, boxes);
+      if (at) setTimeout(() => frame([at], { floor: 0.55 }), 60);
+    };
+    take();
+    window.addEventListener(MARK_REQUEST_EVENT, take);
+    return () => window.removeEventListener(MARK_REQUEST_EVENT, take);
+  }, [docPath, marks, boxes, openThread, frame]);
+
+  // ── The phone's sheet: a card holds it in the caption's place ───────
+  const cardOpen = !!(draft || selectedMark || panel);
+  const claimSheet = stage?.claimSheet;
+  const releaseSheet = stage?.releaseSheet;
+  useEffect(() => {
+    if (cardOpen) claimSheet?.("card");
+    else releaseSheet?.("card");
+  }, [cardOpen, claimSheet, releaseSheet]);
+  useEffect(() => () => releaseSheet?.("card"), [releaseSheet]);
+  // The conversation took the sheet: the card gives way to it.
+  const narrow = !!stage?.narrow;
+  const sheetOwner = stage?.sheet ?? null;
+  const [seenOwner, setSeenOwner] = useState(sheetOwner);
+  if (seenOwner !== sheetOwner) {
+    setSeenOwner(sheetOwner);
+    if (narrow && sheetOwner === "talk") {
+      setDraft(null);
+      setSelected(null);
+      setPanel(false);
+    }
+  }
+
+  // ── The board's buttons: no pin sits under them ─────────────────────
+  const controlsRef = useRef<HTMLDivElement | null>(null);
+  const [controlsBox, setControlsBox] = useState<Box | null>(null);
+  useEffect(() => {
+    const el = controlsRef.current;
+    if (!el) return;
+    const measure = (): void => {
+      const next = { x: el.offsetLeft, y: el.offsetTop, width: el.offsetWidth, height: el.offsetHeight };
+      setControlsBox((b) => (b && b.x === next.x && b.y === next.y && b.width === next.width && b.height === next.height ? b : next));
+    };
+    measure();
+    window.addEventListener("resize", measure);
+    if (typeof ResizeObserver === "undefined") return () => window.removeEventListener("resize", measure);
+    const watch = new ResizeObserver(measure);
+    watch.observe(el);
+    return () => {
+      watch.disconnect();
+      window.removeEventListener("resize", measure);
+    };
+  }, [docPath]);
+  // ── And none under the caption, or the phone's sheet: what it covers of the board ──
+  const [coverBox, setCoverBox] = useState<Box | null>(null);
+  const shownNow = stage?.shown ?? null;
+  useEffect(() => {
+    const board = boardRef.current;
+    if (!board) return;
+    const find = () => document.querySelector(".stage-sheet") ?? document.querySelector(".stage-caption-host .slc-stage-caption");
+    let frameId = 0;
+    const measure = (): void => {
+      cancelAnimationFrame(frameId);
+      frameId = requestAnimationFrame(() => {
+        const b = board.getBoundingClientRect();
+        const r = find()?.getBoundingClientRect();
+        const next = r && r.height > 0 && r.top < b.bottom ? { x: r.left - b.left, y: r.top - b.top, width: r.width, height: Math.min(r.bottom, b.bottom) - r.top } : null;
+        setCoverBox((c) => (c && next && c.x === next.x && c.y === next.y && c.width === next.width && c.height === next.height ? c : next));
+      });
+    };
+    measure();
+    const el = find();
+    const watch = el && typeof ResizeObserver !== "undefined" ? new ResizeObserver(measure) : null;
+    if (el) watch?.observe(el);
+    window.addEventListener("resize", measure);
+    return () => {
+      cancelAnimationFrame(frameId);
+      watch?.disconnect();
+      window.removeEventListener("resize", measure);
+    };
+  }, [boardRef, shownNow, cardOpen, sheetOwner, narrow, docPath]);
+  const avoid = useMemo(() => [controlsBox, coverBox].filter((b): b is Box => !!b), [controlsBox, coverBox]);
 
   if (!docPath) return null;
 
@@ -280,9 +460,10 @@ export default function StageLayer({ docPath, kind, viewport, setViewport, boxes
           setDraft(d);
         }}
         draft={draft}
+        avoid={avoid}
       />
 
-      <div className="stage-board-controls">
+      <div className="stage-board-controls" ref={controlsRef}>
         {notice && (
           <MarkNotice className="stage-board-notice" onOpen={() => openThread(notice.id)} onDismiss={() => setNotice(null)}>
             {notice.text}
@@ -330,9 +511,8 @@ export default function StageLayer({ docPath, kind, viewport, setViewport, boxes
         </div>
       )}
 
-      {(draft || selectedMark || panel) && (
-        <div className="stage-board-card">
-          {draft ? (
+      {cardOpen && (() => {
+        const card = draft ? (
             <MarkComposer
               key={`${draft.elements.join(",")}|${draft.region ? JSON.stringify(draft.region) : ""}`}
               elements={draft.elements}
@@ -344,6 +524,7 @@ export default function StageLayer({ docPath, kind, viewport, setViewport, boxes
               busy={busy}
               error={error}
               note={note}
+              labels={labels}
               onCancel={() => {
                 setDraft(null);
                 setError(null);
@@ -365,6 +546,7 @@ export default function StageLayer({ docPath, kind, viewport, setViewport, boxes
               busy={busy}
               error={error}
               note={note}
+              labels={labels}
               onClose={() => setSelected(null)}
               onReply={(text) => void write({ action: "reply", id: selectedMark.id, text, author: { name: stage?.author || "someone" } })}
               onResolve={() => void write({ action: "resolve", id: selectedMark.id })}
@@ -385,11 +567,12 @@ export default function StageLayer({ docPath, kind, viewport, setViewport, boxes
               onCopy={copy}
               copied={copied}
               note={note}
+              labels={labels}
               onClose={() => setPanel(false)}
             />
-          )}
-        </div>
-      )}
+          );
+        return narrow && stage?.sheetBody ? createPortal(card, stage.sheetBody) : <div className="stage-board-card">{card}</div>;
+      })()}
     </>
   );
 }

package/server/src/components/stage/StageProvider.tsx

@@ -15,14 +15,29 @@
  * voice the person may turn on, the ears a mark may be spoken into, the name
  * marks are signed with, and the line back to the agents — what the person is
  * looking at, and that a drawing's marks changed.
+ *
+ * The caption's heading is the step's own title. When the step is about a
+ * drawing that is not the one on the board (a page opened on another drawing
+ * caught up with a tour the stage holds), the caption names that drawing,
+ * offers "Open and play", and has no Answer: a mark would land on the wrong
+ * drawing.
+ *
+ * On a phone (below 600 px) the bottom of the board holds one sheet: the Talk
+ * dock's bar as its handle, then one of the caption, a mark's card (composer,
+ * thread, list) or the Talk conversation. A card or the conversation takes the
+ * caption's place while it is open, and the caption comes back when it closes.
+ * Layers claim the sheet (`claimSheet`) and render into its slots
+ * (`sheetHandle`, `sheetBody`); on a wider screen there is no sheet and each
+ * keeps its own corner.
  */
 import { createContext, useCallback, useContext, useEffect, useMemo, useRef, useState, type ReactNode } from "react";
 import { browserDictation, browserVoice, useStage, type StageShown, type UseStage } from "@miadi/stateloom-react";
 import { StageCaption, type ListenerLike } from "@miadi/stateloom-canvas";
-import { DEFAULT_STAGE, isStageName, type Box, type MarksEnvelope, type StageContext } from "@miadi/stateloom-protocol";
+import { DEFAULT_STAGE, isStageName, isSysdfPath, type Box, type MarksEnvelope, type StageContext } from "@miadi/stateloom-protocol";
 import { loadRuntimeConfig } from "@/lib/runtimeConfig";
 import { requestedDoc } from "@/lib/docParam";
 import { FOCUS_REQUEST_EVENT, openInSystem, urlParam } from "@/lib/systemParam";
+import { useNarrow } from "@/lib/useNarrow";
 import CompanionLayer from "./CompanionLayer";
 
 /** What the step on stage lights inside its drawing. `doc` absent: whatever drawing is open. */
@@ -37,6 +52,9 @@ export interface Lit {
 /** What a layer reports about the board it sits on. */
 export type BoardReport = Omit<StageContext, "stage" | "at" | "tour" | "who">;
 
+/** Who holds the phone's sheet in place of the caption: a mark's card, or the Talk conversation. */
+export type SheetOwner = "card" | "talk";
+
 export interface StageValue {
   stage: string;
   connected: boolean;
@@ -58,6 +76,18 @@ export interface StageValue {
   companion: boolean;
   pause: () => void;
   stop: () => void;
+  /** The drawing on the board now (absolute), as its layer says; null on the system map. */
+  board: string | null;
+  setBoard: (doc: string | null) => void;
+  /** Below 600 px: the caption, the cards and the conversation share one sheet. */
+  narrow: boolean;
+  /** Who holds the sheet instead of the caption. */
+  sheet: SheetOwner | null;
+  claimSheet: (owner: SheetOwner) => void;
+  releaseSheet: (owner: SheetOwner) => void;
+  /** The sheet's slots on a phone: the handle (the Talk bar), and the body (a card, the conversation). */
+  sheetHandle: HTMLElement | null;
+  sheetBody: HTMLElement | null;
 }
 
 const StageCtx = createContext<StageValue | null>(null);
@@ -85,6 +115,24 @@ function writeLocal(key: string, value: string): void {
   }
 }
 
+/** The drawing's own name (settings.name), read once per drawing; its file name meanwhile. */
+const drawingTitles = new Map<string, Promise<string | null>>();
+function drawingTitle(doc: string): Promise<string | null> {
+  let found = drawingTitles.get(doc);
+  if (!found) {
+    found = fetch(`/api/file?doc=${encodeURIComponent(doc)}`, { cache: "no-store" })
+      .then((r) => (r.ok ? r.json() : null))
+      .then((data: { content?: string } | null) => {
+        const def = data?.content ? JSON.parse(data.content) : null;
+        const name = (def?.settings ?? def?.stateMachine?.settings)?.name;
+        return typeof name === "string" && name ? name : null;
+      })
+      .catch(() => null);
+    drawingTitles.set(doc, found);
+  }
+  return found;
+}
+
 /** Ask the open workspace to select and centre `focus` on the drawing already open. */
 function requestFocus(focus: string): void {
   const url = new URL(window.location.href);
@@ -122,6 +170,16 @@ export default function StageProvider({ children }: { children: ReactNode }) {
 
   const [lit, setLit] = useState<Lit | null>(null);
   const marksListeners = useRef(new Set<(e: MarksEnvelope) => void>());
+  // The drawing on the board, and the one the stage just asked the page to open — asked
+  // while `from` was on the board, so it counts only until the board changes.
+  const [board, setBoardState] = useState<string | null>(null);
+  const [opening, setOpeningState] = useState<{ doc: string; from: string | null } | null>(null);
+  const boardNow = useRef<string | null>(null);
+  const setOpening = useCallback((doc: string) => setOpeningState({ doc, from: boardNow.current }), []);
+  const setBoard = useCallback((doc: string | null) => {
+    boardNow.current = doc;
+    setBoardState(doc);
+  }, []);
 
   const show = useCallback((shown: StageShown | null) => {
     if (!shown) {
@@ -137,13 +195,14 @@ export default function StageProvider({ children }: { children: ReactNode }) {
       return;
     }
     if (step.doc && step.doc !== open) {
+      setOpening(step.doc);
       openInSystem({ doc: step.doc, system: step.system ?? undefined, focus: step.focus ?? null });
     } else if (step.focus) {
       if (step.system && urlParam("system") !== step.system && open) openInSystem({ doc: open, system: step.system, focus: step.focus });
       else requestFocus(step.focus);
     }
     setLit({ doc: step.doc, focus: step.focus, spotlight: step.spotlight, region: step.region, nonce: shown.nonce });
-  }, []);
+  }, [setOpening]);
 
   const stage = useStage({
     url: config.bridgeUrl ?? "",
@@ -180,8 +239,49 @@ export default function StageProvider({ children }: { children: ReactNode }) {
 
   const [answerNonce, setAnswerNonce] = useState(0);
 
-  // How tall the caption stands, for what must sit above it on a phone (the Talk dock).
-  const captionUp = !!stage.shown;
+  // ── The phone's sheet ────────────────────────────────────────────────
+  const narrow = useNarrow();
+  const [sheet, setSheet] = useState<SheetOwner | null>(null);
+  const claimSheet = useCallback((owner: SheetOwner) => setSheet(owner), []);
+  const releaseSheet = useCallback((owner: SheetOwner) => setSheet((s) => (s === owner ? null : s)), []);
+  const [sheetHandle, setSheetHandle] = useState<HTMLElement | null>(null);
+  const [sheetBody, setSheetBody] = useState<HTMLElement | null>(null);
+
+  // ── A step about a drawing that is not on the board ─────────────────
+  const shownStep = stage.shown?.step ?? null;
+  // Until the board's layer has said which drawing it shows, the page's `?doc=` stands for it.
+  const asked = urlParam("doc");
+  const onBoard = board ?? (asked && !isSysdfPath(asked) ? asked : null);
+  const openingDoc = opening && opening.from === board ? opening.doc : null;
+  const heldDoc = shownStep?.doc && shownStep.doc !== onBoard && shownStep.doc !== openingDoc ? shownStep.doc : null;
+  const [heldTitle, setHeldTitle] = useState<{ doc: string; title: string | null } | null>(null);
+  useEffect(() => {
+    if (!heldDoc) return;
+    let live = true;
+    void drawingTitle(heldDoc).then((title) => live && setHeldTitle({ doc: heldDoc, title }));
+    return () => {
+      live = false;
+    };
+  }, [heldDoc]);
+  const play = stage.play;
+  const held = useMemo(() => {
+    if (!heldDoc || !shownStep) return null;
+    const title = heldTitle?.doc === heldDoc ? heldTitle.title : null;
+    const drawing = title ?? (heldDoc.split("/").pop() ?? heldDoc).replace(/\.(smdf|erdf|sqdf|sysdf)\.json$/i, "").replace(/\.json$/i, "");
+    const inTour = stage.shown?.index !== null && stage.shown?.index !== undefined;
+    return {
+      drawing,
+      label: inTour ? "Open and play" : "Open the drawing",
+      onOpen: () => {
+        setOpening(heldDoc);
+        openInSystem({ doc: heldDoc, system: shownStep.system ?? undefined, focus: shownStep.focus ?? null });
+        if (inTour) play();
+      },
+    };
+  }, [heldDoc, heldTitle, shownStep, stage.shown?.index, play, setOpening]);
+
+  // How tall the caption stands, for what must sit above it beside the board (the Talk dock).
+  const captionUp = !!stage.shown && !narrow;
   useEffect(() => {
     const root = document.documentElement;
     const caption = captionUp ? document.querySelector<HTMLElement>(".stage-caption-host .slc-stage-caption") : null;
@@ -225,34 +325,55 @@ export default function StageProvider({ children }: { children: ReactNode }) {
       companion: config.companion,
       pause: stage.pause,
       stop: stage.stop,
+      board,
+      setBoard,
+      narrow,
+      sheet,
+      claimSheet,
+      releaseSheet,
+      sheetHandle,
+      sheetBody,
     }),
-    [config.stage, config.companion, stage.status, stage.shown, stage.sendMarks, stage.present, stage.pause, stage.stop, lit, author, listener, answerNonce, report],
+    [
+      config.stage, config.companion, stage.status, stage.shown, stage.sendMarks, stage.present, stage.pause, stage.stop, lit, author, listener, answerNonce, report,
+      board, setBoard, narrow, sheet, claimSheet, releaseSheet, sheetHandle, sheetBody,
+    ],
   );
 
+  const caption = stage.shown ? (
+    <StageCaption
+      shown={stage.shown}
+      playing={stage.playing}
+      speaking={stage.speaking}
+      voice={stage.ownVoice ? undefined : voiceOn}
+      onToggleVoice={() => {
+        const next = !voiceOn;
+        setVoiceOn(next);
+        writeLocal(VOICE_KEY, next ? "1" : "0");
+      }}
+      onPlay={stage.play}
+      onPause={stage.pause}
+      onNext={stage.next}
+      onPrev={stage.prev}
+      onGoto={stage.goto}
+      onClose={stage.dismiss}
+      onAnswer={() => setAnswerNonce((n) => n + 1)}
+      held={held}
+    />
+  ) : null;
+
   return (
     <StageCtx.Provider value={value}>
       {children}
-      {stage.shown && (
-        <div className="stage-caption-host">
-          <StageCaption
-            shown={stage.shown}
-            playing={stage.playing}
-            speaking={stage.speaking}
-            voice={stage.ownVoice ? undefined : voiceOn}
-            onToggleVoice={() => {
-              const next = !voiceOn;
-              setVoiceOn(next);
-              writeLocal(VOICE_KEY, next ? "1" : "0");
-            }}
-            onPlay={stage.play}
-            onPause={stage.pause}
-            onNext={stage.next}
-            onPrev={stage.prev}
-            onGoto={stage.goto}
-            onClose={stage.dismiss}
-            onAnswer={() => setAnswerNonce((n) => n + 1)}
-          />
+      {narrow ? (
+        // One sheet at the bottom of the board: the handle, then the caption or what took its place.
+        <div className="stage-sheet">
+          <div className="stage-sheet-handle" ref={setSheetHandle} />
+          <div className="stage-sheet-body" ref={setSheetBody} />
+          {!sheet && caption && <div className="stage-sheet-caption">{caption}</div>}
         </div>
+      ) : (
+        caption && <div className="stage-caption-host">{caption}</div>
       )}
       {config.companion && <CompanionLayer stage={value} defaultEpisode={config.companionEpisode} />}
     </StageCtx.Provider>

package/server/src/components/system/SystemWorkspace.tsx

@@ -9,7 +9,9 @@
  * A card opens its member inside the system (`?doc=<member>&system=<this>`),
  * where the strip keeps every drawing one tap away.
  *
- * The panel: Members (what each is, and the links between each pair), Checks
+ * The panel: Members (what each is, and the links between each pair; a member's
+ * note shows when it has words, and an empty one waits behind "Add a note" so the
+ * panel opens on what the system holds, not on empty boxes), Checks
  * (`checkSystem` grouped by rule, errors first, then the replay of every path
  * of every scenario, and the reconcile mode with the changes the scenarios
  * imply), and Notes. Same shell as the other workspaces: one header row, the
@@ -109,6 +111,8 @@ export default function SystemWorkspace() {
   const [menuOpen, setMenuOpen] = useState(false);
   const [panelHidden, setPanelHidden] = useState(false);
   const [pair, setPair] = useState<string | null>(null);
+  // Members whose empty note the person asked to write.
+  const [noting, setNoting] = useState<ReadonlySet<string>>(() => new Set());
   const [status, setStatusState] = useState<{ text: string; tone: "ok" | "warn" }>({ text: "loading…", tone: "ok" });
   const setStatus = useCallback((text: string, tone: "ok" | "warn" = "ok") => setStatusState({ text, tone }), []);
   const [busy, setBusy] = useState(false);
@@ -530,16 +534,26 @@ export default function SystemWorkspace() {
                       </span>
                       <span className="shrink-0 text-[11px] text-gray-500">open ›</span>
                     </button>
-                    {/* The system's note about this member — kept in the .sysdf.json, not in the member. */}
-                    <div className="px-2 pb-2 [&_label]:mt-0">
-                      <NotesField
-                        key={`member:${m}`}
-                        label="Note on this member, in the system"
-                        value={note ?? ""}
-                        placeholder={`Why ${memberTitle(system, m)} is part of this system, what is open…`}
-                        onSave={(notes) => void writeSystem(updateMember(def, m, { notes }), "saved")}
-                      />
-                    </div>
+                    {/* The system's note about this member — kept in the .sysdf.json, not in the member.
+                        Shown when it has words; an empty one opens on request. */}
+                    {note || noting.has(m) ? (
+                      <div className="px-2 pb-2 [&_label]:mt-0">
+                        <NotesField
+                          key={`member:${m}`}
+                          label="Note on this member, in the system"
+                          value={note ?? ""}
+                          placeholder={`Why ${memberTitle(system, m)} is part of this system, what is open…`}
+                          onSave={(notes) => void writeSystem(updateMember(def, m, { notes }), "saved")}
+                        />
+                      </div>
+                    ) : (
+                      <button
+                        className="mx-2 mb-1.5 text-[11px] text-gray-500 hover:text-gray-300"
+                        onClick={() => setNoting((n) => new Set(n).add(m))}
+                      >
+                        Add a note on this member
+                      </button>
+                    )}
                     </div>
                   );
                 })}
@@ -553,7 +567,7 @@ export default function SystemWorkspace() {
                       onClick={() => setPair(pair === key ? null : key)}
                     >
                       <span className="truncate">
-                        {memberTitle(system, p.a)} ↔ {memberTitle(system, p.b)}
+                        {memberTitle(system, p.a)} {"\u2194\uFE0E"} {memberTitle(system, p.b)}
                       </span>
                       <span className="shrink-0 text-gray-500">{p.links.length}</span>
                     </button>