@miadi/stateloom-web 0.2.5 → 0.3.0

package/server/src/components/sequence/SequenceReading.tsx

@@ -0,0 +1,186 @@
+"use client";
+
+/**
+ * A sequence read as a list — the view a phone opens on (Spec 81).
+ *
+ * A sequence with seven participants is wider than a phone at any size its
+ * words can be read at: the drawing shows two lifelines, and a message between
+ * two others is a line whose label sits off the screen (found 2026-10-01 on
+ * DiscussionFromChart). Here every message is a row in story order: who sends
+ * it to whom, what is said, and what it does (the event it fires, on which
+ * machine, the state it leaves, what it carries). Each fragment is a framed
+ * group under its heading. Nothing is cut, nothing needs panning, and each
+ * participant keeps one colour so a reader can follow who speaks.
+ *
+ * Read-only: tapping a row selects it, exactly as tapping it in the drawing
+ * does, and the host's panel edits it.
+ */
+import type { SequenceDefinition, SqdMessage } from "@miadi/stateloom-protocol";
+import { allMessages } from "@miadi/stateloom-protocol";
+import type { SequenceSelection } from "@miadi/stateloom-canvas";
+
+export interface ReadingIssue {
+  severity: "error" | "warning";
+  text: string;
+}
+
+/** Light tints, each above 4.5:1 on gray-900 and gray-950. */
+const SPEAKER_COLOURS = [
+  "text-sky-300",
+  "text-emerald-300",
+  "text-amber-300",
+  "text-rose-300",
+  "text-violet-300",
+  "text-cyan-300",
+  "text-lime-300",
+  "text-orange-300",
+];
+
+/** The element id a row carries, so a focus can scroll to it. */
+export const readingRowId = (target: SequenceSelection): string => `seq-read-${target.kind}-${target.id}`;
+
+export default function SequenceReading({
+  definition,
+  selection,
+  issues,
+  onSelect,
+  onShowInDiagram,
+}: {
+  definition: SequenceDefinition;
+  selection: SequenceSelection | null;
+  /** Check findings by focus string (`message:9`, `participant:Chart`). */
+  issues: ReadonlyMap<string, ReadingIssue[]>;
+  onSelect: (target: SequenceSelection) => void;
+  onShowInDiagram: (target: SequenceSelection) => void;
+}) {
+  const colourOf = new Map(definition.participants.map((p, i) => [p.name, SPEAKER_COLOURS[i % SPEAKER_COLOURS.length]]));
+  const messages = allMessages(definition);
+  const main = messages.filter((m) => m.fragment === null);
+  const fragments = (definition.fragments ?? []).map((f, fi) => ({ f, fi, rows: messages.filter((m) => m.fragment === fi) }));
+  const isSelected = (kind: SequenceSelection["kind"], id: string) => selection?.kind === kind && selection.id === id;
+
+  const name = (who: string) => <span className={`font-semibold ${colourOf.get(who) ?? "text-gray-300"}`}>{who || "?"}</span>;
+
+  const row = (ref: string, m: SqdMessage) => {
+    const target: SequenceSelection = { kind: "message", id: ref };
+    const found = issues.get(`message:${ref}`) ?? [];
+    const worst = found.some((i) => i.severity === "error") ? "error" : found.length ? "warning" : null;
+    const selected = isSelected("message", ref);
+    return (
+      <li key={ref} id={readingRowId(target)} className="scroll-mt-16 scroll-mb-24">
+        <div
+          role="button"
+          tabIndex={0}
+          aria-pressed={selected}
+          onClick={() => onSelect(target)}
+          onKeyDown={(e) => (e.key === "Enter" || e.key === " ") && (e.preventDefault(), onSelect(target))}
+          className={`flex gap-3 rounded-lg border-l-2 px-3 py-2.5 ${
+            selected ? "bg-blue-950/60 ring-1 ring-blue-500/60" : "hover:bg-gray-900"
+          } ${worst === "error" ? "border-red-500" : worst === "warning" ? "border-amber-400" : "border-transparent"}`}
+        >
+          <span className="mt-0.5 flex h-6 min-w-6 shrink-0 items-center justify-center rounded-full border border-gray-700 bg-gray-900 px-1 font-mono text-[11px] text-gray-300">
+            {ref}
+          </span>
+          <div className="min-w-0 flex-1">
+            <div className="text-[13px] leading-5 text-gray-400">
+              {name(m.from)}
+              {m.from === m.to ? (
+                <span> to itself</span>
+              ) : (
+                <>
+                  <span className="px-1.5 text-gray-500">{m.reply ? "⇠" : "→"}</span>
+                  {name(m.to)}
+                </>
+              )}
+              {m.reply && <span className="ml-2 text-[11px] text-gray-500">reply</span>}
+              {m.optional && <span className="ml-2 rounded border border-gray-700 px-1 text-[11px] text-gray-400">optional</span>}
+            </div>
+            <div className={`mt-0.5 break-words text-[15px] leading-6 ${m.reply ? "text-gray-300" : "text-gray-100"}`}>
+              {m.label || <span className="text-gray-500">no label</span>}
+            </div>
+            {(m.event || m.state || m.carries) && (
+              <div className="mt-1.5 flex flex-wrap items-center gap-x-2 gap-y-1 text-[12px] leading-5">
+                {m.event && (
+                  <span className="rounded border border-blue-500/50 bg-blue-950/50 px-1.5 font-mono text-blue-200">{m.event}</span>
+                )}
+                {m.event && m.machine && <span className="text-gray-400">on {m.machine}</span>}
+                {m.state && <span className="text-emerald-300">→ {m.state}</span>}
+                {m.carries && <span className="text-gray-400">carries {m.carries}</span>}
+              </div>
+            )}
+            {found.map((i, n) => (
+              <p key={n} className={`mt-1.5 text-[12px] leading-5 ${i.severity === "error" ? "text-red-300" : "text-amber-300"}`}>
+                {i.text}
+              </p>
+            ))}
+            {selected && (
+              <button
+                className="mt-2 rounded border border-gray-700 bg-gray-800 px-3 py-1.5 text-[12px] text-gray-200"
+                onClick={(e) => {
+                  e.stopPropagation();
+                  onShowInDiagram(target);
+                }}
+              >
+                Show in the diagram
+              </button>
+            )}
+          </div>
+        </div>
+      </li>
+    );
+  };
+
+  return (
+    <div className="h-full overflow-y-auto overscroll-contain">
+      <div className="mx-auto max-w-2xl px-4 pb-28 pt-10">
+        {definition.participants.length > 0 && (
+          <ul className="mb-4 flex flex-wrap gap-2" aria-label="Participants">
+            {definition.participants.map((p) => {
+              const target: SequenceSelection = { kind: "participant", id: p.name };
+              const kind = p.actor ? "actor" : p.object ? "object" : p.service ? "service" : "";
+              const found = issues.get(`participant:${p.name}`) ?? [];
+              return (
+                <li key={p.name} id={readingRowId(target)}>
+                  <button
+                    onClick={() => onSelect(target)}
+                    aria-pressed={isSelected("participant", p.name)}
+                    title={found.map((i) => i.text).join("\n") || undefined}
+                    className={`rounded-full border px-3 py-1 text-[13px] ${
+                      isSelected("participant", p.name) ? "border-blue-500 bg-blue-950/60" : "border-gray-700 bg-gray-900"
+                    } ${found.length ? "ring-1 ring-amber-400/70" : ""}`}
+                  >
+                    {name(p.name)}
+                    {kind && <span className="ml-1.5 text-[11px] text-gray-400">{kind}</span>}
+                  </button>
+                </li>
+              );
+            })}
+          </ul>
+        )}
+
+        {messages.length === 0 && (
+          <p className="text-sm text-gray-400">No messages yet — add them in the panel, or let an agent write the scenario.</p>
+        )}
+
+        <ol className="flex flex-col gap-1">{main.map(({ ref, message }) => row(ref, message))}</ol>
+
+        {fragments.map(({ f, fi, rows }) => (
+          <section key={fi} className="mt-5 rounded-xl border border-indigo-500/50 bg-indigo-950/20 p-1.5">
+            <header className="px-3 pb-1.5 pt-2">
+              <div className="text-[12px] text-indigo-200">
+                <span className="font-semibold uppercase tracking-wide">{f.kind}</span>
+                <span className="text-indigo-300"> · after {f.after}</span>
+              </div>
+              <div className="mt-0.5 break-words text-[14px] leading-5 text-gray-100">{f.label}</div>
+            </header>
+            {rows.length === 0 ? (
+              <p className="px-3 pb-2 text-[12px] text-gray-400">No messages in this fragment.</p>
+            ) : (
+              <ol className="flex flex-col gap-1">{rows.map(({ ref, message }) => row(ref, message))}</ol>
+            )}
+          </section>
+        ))}
+      </div>
+    </div>
+  );
+}

package/server/src/components/sequence/SequenceWorkspace.tsx

@@ -10,6 +10,10 @@
  * controls on the board, the panel a bottom sheet behind a dock on a phone and
  * a right column on a desktop.
  *
+ * On a phone it opens as a list (`SequenceReading`): a sequence wider than the
+ * screen cannot be read as a drawing there. List and Diagram switch in the
+ * header, and the choice is remembered in this browser.
+ *
  * Inside a system (`?system=` in the URL), the Issues tab adds the system's
  * findings for this scenario — the names it uses that no member defines, and
  * the replay of each path against the machines — and the fields that name an
@@ -65,14 +69,19 @@ import IssueIcon from "@/components/IssueIcon";
 import { NotesField } from "@/components/erd/ErdWorkspace";
 import { FieldForm, panelButton as button, panelHeading as heading, type FormValues } from "@/components/forms";
 import KindIcon from "@/components/system/KindIcon";
+import SequenceReading, { readingRowId, type ReadingIssue } from "@/components/sequence/SequenceReading";
 import { docQuery, useRequestedDoc } from "@/lib/docParam";
 import { loadRuntimeConfig } from "@/lib/runtimeConfig";
 import { useSheetDrag } from "@/lib/useSheetDrag";
 import { safely } from "@/lib/safely";
 import { stripNote, useFocusRequest, useUrlParam, writeFocus } from "@/lib/systemParam";
+import StageLayer, { StageReveal } from "@/components/stage/StageLayer";
+import { sequenceElementBoxes } from "@miadi/stateloom-protocol";
 import { memberOfDoc, notifySystemChanged, reconcileNow, systemVocabulary, useSystem } from "@/lib/systemLoad";
 
 type Tab = "participants" | "messages" | "notes" | "issues";
+type ViewMode = "diagram" | "list";
+const VIEW_KEY = "stateloom.sequence.view";
 type Edit = (def: SequenceDefinition) => SequenceDefinition;
 
 const KINDS = ["", "actor", "service", "object"] as const;
@@ -124,6 +133,30 @@ export default function SequenceWorkspace() {
   const [sheetOpen, setSheetOpen] = useState(false);
   const [menuOpen, setMenuOpen] = useState(false);
   const [panelHidden, setPanelHidden] = useState(false);
+  // Diagram until the browser says otherwise: a remembered choice, else a list on a phone.
+  const [mode, setModeState] = useState<ViewMode>("diagram");
+  const modeRef = useRef<ViewMode>("diagram");
+  useEffect(() => {
+    let remembered: string | null = null;
+    try {
+      remembered = window.localStorage.getItem(VIEW_KEY);
+    } catch {
+      // Storage refused (a private window): fall back to the screen width.
+    }
+    const next: ViewMode =
+      remembered === "list" || remembered === "diagram" ? remembered : window.matchMedia("(max-width: 767px)").matches ? "list" : "diagram";
+    modeRef.current = next;
+    setModeState(next);
+  }, []);
+  const setMode = useCallback((next: ViewMode) => {
+    modeRef.current = next;
+    setModeState(next);
+    try {
+      window.localStorage.setItem(VIEW_KEY, next);
+    } catch {
+      // Not remembered; the switch still works.
+    }
+  }, []);
   const boardRef = useRef<HTMLDivElement | null>(null);
   const sheet = useSheetDrag({ onClose: () => setSheetOpen(false), restVh: 62, tallVh: 92 });
   const [peers, setPeers] = useState(0);
@@ -184,6 +217,8 @@ export default function SequenceWorkspace() {
   // shows what it can). Edits still go through the protocol on `def` itself.
   const view = useMemo(() => (def ? drawableSequence(def) : null), [def]);
   const layout = useMemo(() => (view ? sequenceLayout(view) : null), [view]);
+  const stageBoxes = useMemo(() => (view && layout ? safely(() => sequenceElementBoxes(view, layout), []) : []), [view, layout]);
+  const stageFocus = useUrlParam("focus");
   // A malformed document is reported as one issue, not a crash.
   const problems = useMemo<SqdValidationError[]>(() => {
     if (!def) return [];
@@ -224,6 +259,24 @@ export default function SequenceWorkspace() {
     [memberIssues],
   );
 
+  // The same findings, by focus string, for the list to print under each row.
+  const readingIssues = useMemo(() => {
+    const out = new Map<string, ReadingIssue[]>();
+    const add = (element: string | undefined, issue: ReadingIssue) => {
+      const key = !element
+        ? ""
+        : /^(message|participant):/.test(element)
+          ? element
+          : view?.participants.some((p) => p.name === element)
+            ? `participant:${element}`
+            : "";
+      if (key) out.set(key, [...(out.get(key) ?? []), issue]);
+    };
+    problems.forEach((p) => add(p.element, { severity: "error", text: p.message }));
+    memberIssues.forEach((i) => add(i.element, { severity: i.severity === "error" ? "error" : "warning", text: i.message }));
+    return out;
+  }, [problems, memberIssues, view]);
+
   const boardSize = (): { width: number; height: number } => {
     const rect = boardRef.current?.getBoundingClientRect();
     return { width: rect?.width ?? 0, height: rect?.height ?? 0 };
@@ -262,6 +315,17 @@ export default function SequenceWorkspace() {
     [layout, centreOn],
   );
 
+  /** Bring a target into view in whichever view is showing. */
+  const reveal = useCallback(
+    (target: SequenceSelection) => {
+      if (modeRef.current === "diagram") return showSelection(target);
+      requestAnimationFrame(() =>
+        document.getElementById(readingRowId(target))?.scrollIntoView({ block: "center", behavior: "smooth" }),
+      );
+    },
+    [showSelection],
+  );
+
   const select = useCallback((target: SequenceSelection | null) => {
     setSelection(target);
     if (target) writeFocus(`${target.kind}:${target.id}`);
@@ -279,21 +343,21 @@ export default function SequenceWorkspace() {
     if (!target) return setStatus(`${focusRequest.focus} is not in this sequence`, "warn");
     firstView.current = false;
     setSelection(target);
-    showSelection(target);
-  }, [def, view, layout, focusRequest, showSelection, setStatus]);
+    reveal(target);
+  }, [def, view, layout, focusRequest, reveal, setStatus]);
 
   // The first view: the whole drawing when it can be read that way, else its
   // top-left corner at a readable size (a phone showing seven lifelines at a
   // quarter of their size shows nothing).
   useEffect(() => {
-    if (!layout || !firstView.current) return;
+    if (!layout || !firstView.current || mode !== "diagram") return;
     const { width, height } = boardSize();
     if (!width) return;
     firstView.current = false;
     const fit = Math.min((width - 32) / layout.width, (height - 32) / layout.height);
     if (fit >= 0.5 || layout.participants.length === 0) setFitKey((k) => (k ?? 0) + 1);
     else setViewport({ x: 8, y: 8, scale: 0.6 });
-  }, [layout]);
+  }, [layout, mode]);
 
   const apply = useCallback(
     async (edit: Edit) => {
@@ -361,7 +425,7 @@ export default function SequenceWorkspace() {
     if (!f || (f.kind !== "message" && f.kind !== "participant")) return;
     const target: SequenceSelection = { kind: f.kind, id: f.name };
     select(target);
-    showSelection(target);
+    reveal(target);
     sheet.close();
   };
 
@@ -420,6 +484,29 @@ export default function SequenceWorkspace() {
           {def?.settings.name ?? fileName}
           <span className="hidden text-gray-600 lg:inline"> · {fileName}</span>
         </span>
+        <div className="flex shrink-0 overflow-hidden rounded border border-gray-700 text-[12px] leading-none" role="group" aria-label="View">
+          {(
+            [
+              ["list", "List", "Read the messages in order, one under the other"],
+              ["diagram", "Diagram", "The lifelines and arrows"],
+            ] as const
+          ).map(([id, label, title]) => (
+            <button
+              key={id}
+              title={title}
+              aria-pressed={mode === id}
+              onClick={() => {
+                if (mode === id) return;
+                if (selection) firstView.current = false;
+                setMode(id);
+                if (selection) requestAnimationFrame(() => reveal(selection));
+              }}
+              className={`px-2.5 py-1.5 ${mode === id ? "bg-gray-700 text-gray-100" : "bg-gray-800 text-gray-400 hover:text-gray-200"}`}
+            >
+              {label}
+            </button>
+          ))}
+        </div>
         <div className="hidden shrink-0 items-center gap-2 md:flex">
           <button className={button} onClick={copyMermaid}>
             Copy mermaid
@@ -463,7 +550,23 @@ export default function SequenceWorkspace() {
 
       <div className="relative flex min-h-0 flex-1">
         <div ref={boardRef} className="relative min-w-0 flex-1 overflow-hidden">
-          {def && layout && (
+          {def && layout && mode === "list" && view && (
+            <BoardBoundary what="sequence" resetKey={def}>
+              <SequenceReading
+                definition={view}
+                selection={selection}
+                issues={readingIssues}
+                onSelect={(target) => select(target)}
+                onShowInDiagram={(target) => {
+                  // The message is the first view, not the drawing's corner.
+                  firstView.current = false;
+                  setMode("diagram");
+                  requestAnimationFrame(() => showSelection(target));
+                }}
+              />
+            </BoardBoundary>
+          )}
+          {def && layout && mode === "diagram" && (
             <BoardBoundary what="sequence" resetKey={def}>
             <SequenceCanvas
               definition={view!}
@@ -480,11 +583,17 @@ export default function SequenceWorkspace() {
             />
             </BoardBoundary>
           )}
+          {/* The stage (Spec 83). In the list view nothing is drawn to light, so a
+              step that lights something here brings the diagram back. */}
+          {def && layout && mode === "diagram" && (
+            <StageLayer docPath={docPath || null} kind="sequence" viewport={viewport} setViewport={setViewport} boxes={stageBoxes} boardRef={boardRef} focus={stageFocus} />
+          )}
+          {def && layout && mode === "list" && <StageReveal docPath={docPath} onReveal={() => setMode("diagram")} />}
 
           <div
-            className={`pointer-events-none absolute left-2 top-2 flex max-w-[75%] items-center gap-1.5 rounded bg-gray-950/70 px-1.5 py-0.5 text-[11px] ${
+            className={`pointer-events-none absolute left-2 top-2 max-w-[75%] items-center gap-1.5 rounded bg-gray-950/70 px-1.5 py-0.5 text-[11px] ${
               status.tone === "warn" ? "text-amber-300" : "text-gray-500"
-            }`}
+            } ${mode === "list" && statusQuiet && status.tone === "ok" ? "hidden" : "flex"}`}
             role="status"
           >
             <span className={`h-1.5 w-1.5 shrink-0 rounded-full ${status.tone === "warn" ? "bg-amber-400" : "bg-emerald-500"}`} />
@@ -494,7 +603,11 @@ export default function SequenceWorkspace() {
             </span>
           </div>
 
-          <div className="absolute bottom-3 right-3 flex flex-col overflow-hidden rounded-lg border border-gray-700 bg-gray-900/90 shadow-lg backdrop-blur">
+          <div
+            className={`absolute bottom-3 right-3 flex-col overflow-hidden rounded-lg border border-gray-700 bg-gray-900/90 shadow-lg backdrop-blur ${
+              mode === "diagram" ? "flex" : "hidden"
+            }`}
+          >
             {(
               [
                 ["＋", "Zoom in", () => zoomBy(1.25)],
@@ -582,7 +695,7 @@ export default function SequenceWorkspace() {
                       className={`${button} ${selection?.kind === "participant" && selection.id === p.name ? "border-blue-500 text-blue-300" : ""}`}
                       onClick={() => {
                         select({ kind: "participant", id: p.name });
-                        showSelection({ kind: "participant", id: p.name });
+                        reveal({ kind: "participant", id: p.name });
                       }}
                       title={participantKind(p) || "participant"}
                     >
@@ -620,7 +733,7 @@ export default function SequenceWorkspace() {
                   <>
                     <div className={`${heading} flex items-center justify-between gap-2`}>
                       <span className="truncate text-sm normal-case tracking-normal text-gray-200">{selectedParticipant.name}</span>
-                      <button className={`${button} normal-case tracking-normal`} onClick={() => showSelection({ kind: "participant", id: selectedParticipant.name })}>
+                      <button className={`${button} normal-case tracking-normal`} onClick={() => reveal({ kind: "participant", id: selectedParticipant.name })}>
                         ◎ Show on board
                       </button>
                     </div>
@@ -720,7 +833,7 @@ export default function SequenceWorkspace() {
                           }`}
                           onClick={() => {
                             select({ kind: "message", id: ref });
-                            showSelection({ kind: "message", id: ref });
+                            reveal({ kind: "message", id: ref });
                           }}
                           title={`${m.from} → ${m.to}: ${m.label}`}
                         >
@@ -767,7 +880,7 @@ export default function SequenceWorkspace() {
                             </button>
                           </>
                         )}
-                        <button className={button} onClick={() => showSelection(selection!)}>
+                        <button className={button} onClick={() => reveal(selection!)}>
                           ◎ Show
                         </button>
                       </span>