@miadi/stateloom-web 0.3.1 → 0.3.4

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;
@@ -54,8 +72,22 @@ export interface StageValue {
   shown: StageShown | null;
   /** Play a tour from this page in its own voice — a companion's reply (Spec 84). */
   present: UseStage["present"];
+  /** A companion answers behind `/api/companion` (Spec 84): the mark cards say who answers. */
+  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);
@@ -83,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);
@@ -120,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) {
@@ -135,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 ?? "",
@@ -178,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;
@@ -220,36 +322,58 @@ export default function StageProvider({ children }: { children: ReactNode }) {
       },
       shown: stage.shown,
       present: stage.present,
+      companion: config.companion,
       pause: stage.pause,
       stop: stage.stop,
+      board,
+      setBoard,
+      narrow,
+      sheet,
+      claimSheet,
+      releaseSheet,
+      sheetHandle,
+      sheetBody,
     }),
-    [config.stage, 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/stage/useEpisodePresence.ts

@@ -0,0 +1,71 @@
+"use client";
+
+/**
+ * Whether a Mia seat listens in the episode a drawing belongs to (Spec 83, Spec 84),
+ * for the line the mark cards show under what a person writes and reads.
+ *
+ * Read from the companion's thread through this designer's proxy
+ * (`/api/companion/thread?episode=`), the same presence the Talk dock shows: listening,
+ * answering, answered, away. Polled every 10 s while a mark card is open and the page is
+ * visible; what was last read is kept while the cards are closed, so a card opens with
+ * its line. Null when there is no episode, before the first answer, and when the
+ * companion does not answer.
+ */
+import { useEffect, useState } from "react";
+import type { CompanionPresence } from "@miadi/stateloom-react";
+
+export type PresenceState = CompanionPresence["state"];
+
+const EVERY_MS = 10_000;
+
+export function useEpisodePresence(episode: string | null, active: boolean): PresenceState | null {
+  const [seen, setSeen] = useState<{ episode: string; state: PresenceState | null } | null>(null);
+
+  useEffect(() => {
+    if (!episode || !active) return;
+    let live = true;
+    const read = async (): Promise<void> => {
+      if (typeof document !== "undefined" && document.visibilityState !== "visible") return;
+      try {
+        const r = await fetch(`/api/companion/thread?episode=${encodeURIComponent(episode)}`, { cache: "no-store" });
+        const body = (await r.json()) as { success?: boolean; presence?: CompanionPresence | null };
+        if (live) setSeen({ episode, state: body.success ? (body.presence?.state ?? null) : null });
+      } catch {
+        if (live) setSeen({ episode, state: null });
+      }
+    };
+    void read();
+    const t = setInterval(() => void read(), EVERY_MS);
+    return () => {
+      live = false;
+      clearInterval(t);
+    };
+  }, [episode, active]);
+
+  return seen && seen.episode === episode ? seen.state : null;
+}
+
+/** "2026-10-19-episode-412-the-loom" → 412. */
+export function episodeNumber(episode: string): number | null {
+  const m = episode.match(/-episode-(\d+)-/);
+  return m ? Number(m[1]) : null;
+}
+
+/** The line under the mark cards: who answers a mark left on a drawing of `episode`. */
+export function presenceLine(state: PresenceState | null, episode: string | null): string | null {
+  if (!state || !episode) return null;
+  const n = episodeNumber(episode);
+  const where = n === null ? "this episode" : `episode ${n}`;
+  switch (state) {
+    case "listening":
+      return `Mia is listening in ${where}: she answers here`;
+    case "answering":
+      return "Mia is answering";
+    case "answered":
+      return `Mia has answered in ${where}: your mark waits until she listens again`;
+    case "away":
+      return `No seat is listening in ${where}: your mark waits until one does`;
+    default:
+      return null;
+  }
+}

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>

package/server/src/lib/markRequest.ts

@@ -0,0 +1,24 @@
+"use client";
+
+/**
+ * "Open that mark": something outside the board (the Talk dock's list of marks) asks the
+ * board showing `doc` to open the thread of mark `id`. The request waits here until that
+ * board has read its marks — the drawing may still be opening — and is taken once.
+ */
+export const MARK_REQUEST_EVENT = "stateloom:mark-request";
+
+let pending: { doc: string; id: string } | null = null;
+
+export function requestMark(doc: string, id: string): void {
+  pending = { doc, id };
+  window.dispatchEvent(new Event(MARK_REQUEST_EVENT));
+}
+
+/** The mark asked for on `doc`, if any; it stays asked until `clearMarkRequest`. */
+export function markRequested(doc: string | null): string | null {
+  return doc && pending?.doc === doc ? pending.id : null;
+}
+
+export function clearMarkRequest(): void {
+  pending = null;
+}

package/server/src/lib/useNarrow.ts

@@ -0,0 +1,30 @@
+"use client";
+
+import { useEffect, useState } from "react";
+
+/**
+ * A phone held upright: below 600 px the stage's caption, a mark's card and the Talk
+ * conversation share one sheet at the bottom of the board (Spec 83, lane U finding U2).
+ */
+export const NARROW_QUERY = "(max-width: 599px)";
+
+function matches(query: string): boolean {
+  try {
+    return typeof window !== "undefined" && typeof window.matchMedia === "function" && window.matchMedia(query).matches;
+  } catch {
+    return false;
+  }
+}
+
+export function useNarrow(query = NARROW_QUERY): boolean {
+  const [narrow, setNarrow] = useState(() => matches(query));
+  useEffect(() => {
+    if (typeof window.matchMedia !== "function") return;
+    const mq = window.matchMedia(query);
+    const update = () => setNarrow(mq.matches);
+    update();
+    mq.addEventListener("change", update);
+    return () => mq.removeEventListener("change", update);
+  }, [query]);
+  return narrow;
+}

package/server/stateloom-web.json

@@ -1,5 +1,5 @@
 {
-  "package": "0.3.1",
-  "designer": "0.3.1",
+  "package": "0.3.4",
+  "designer": "0.3.4",
   "next": "16.1.6"
 }