@miadi/stateloom-web 0.1.7 → 0.1.9

package/server/src/components/erd/ErdWorkspace.tsx

@@ -8,18 +8,27 @@
  * What it shares is everything underneath — the same `?doc=` parameter and file
  * API, the same hub room keyed by the resolved path, the same canvas package.
  *
+ * Layout. The board is the point, so it gets the screen: the header is one
+ * row, the view controls (zoom, fit) float on the board, and status is a line
+ * laid over its corner rather than a row of its own. On a phone the panel is a
+ * bottom sheet that starts closed, behind a three-tab dock — the same shape the
+ * state designer uses — and on a desktop it is the right column, which can be
+ * folded away.
+ *
  * Every edit is written to disk and then pushed to the room whole. Disk first,
  * because the agent's MCP tools read the file before each of their own edits:
  * a change that lived only in the browser would be overwritten by the next
  * `add_entity`. The edits are the protocol's pure functions, the same ones the
  * MCP tools call, so a hand and an agent make identical changes.
  */
-import { useCallback, useEffect, useMemo, useRef, useState } from "react";
+import { useCallback, useEffect, useMemo, useRef, useState, type ReactNode } from "react";
 import { EntityRelationshipCanvas } from "@miadi/stateloom-canvas";
 import { createBridgeSession, type BridgeSession } from "@miadi/stateloom-react";
 import {
   IDENTITY_VIEWPORT,
   ERD_CARDINALITIES,
+  fitToBoxes,
+  zoomAt,
   addAttribute,
   addEntity,
   addRelationship,
@@ -33,6 +42,7 @@ import {
   removeRelationship,
   renderMermaidEr,
   updateEntity,
+  updateErdSettings,
   validateErd,
   type EntityRelationshipDefinition,
   type ErdCardinality,
@@ -43,10 +53,14 @@ import {
   type Viewport,
 } from "@miadi/stateloom-protocol";
 import DocSwitcher from "@/components/DocSwitcher";
+import IssueIcon from "@/components/IssueIcon";
+import LockIcon from "@/components/LockIcon";
 import { docQuery, navigateToDoc, useRequestedDoc } from "@/lib/docParam";
 import { loadRuntimeConfig } from "@/lib/runtimeConfig";
+import { useSheetDrag } from "@/lib/useSheetDrag";
 
 type Moved = Record<string, { x: number; y: number }>;
+type Tab = "entities" | "relations" | "notes" | "issues";
 type Edit = (def: EntityRelationshipDefinition) => EntityRelationshipDefinition;
 
 // The two notations give an entity different footprints, so each keeps its own
@@ -55,6 +69,22 @@ const layoutKey = (docPath: string, notation: ErdNotation): string =>
   notation === "chen" ? `stateloom:erd-layout:chen:${docPath}` : `stateloom:erd-layout:${docPath}`;
 
 const NOTATION_KEY = "stateloom:erd-notation";
+const LOCK_KEY = "stateloom:erd-lock";
+
+/**
+ * Whether shapes start locked in place. A stored choice wins; without one, a
+ * touch screen starts locked — there a drag is almost always "move the view",
+ * and a shape that slides away under the thumb is the accident, not the intent.
+ */
+function readLocked(): boolean {
+  try {
+    const stored = localStorage.getItem(LOCK_KEY);
+    if (stored !== null) return stored === "1";
+    return window.matchMedia("(pointer: coarse)").matches;
+  } catch {
+    return false;
+  }
+}
 
 function readMoved(docPath: string, notation: ErdNotation): Moved {
   try {
@@ -110,12 +140,35 @@ export default function ErdWorkspace() {
   const [def, setDef] = useState<EntityRelationshipDefinition | null>(null);
   const [moved, setMoved] = useState<Moved>({});
   const [notation, setNotation] = useState<ErdNotation>("crowsfoot");
+  // Locked: a drag that starts on a shape pans the board instead of moving the shape. A tap still selects.
+  const [locked, setLocked] = useState(false);
   const [viewport, setViewport] = useState<Viewport>({ ...IDENTITY_VIEWPORT });
   const [fitKey, setFitKey] = useState(0);
   const [selection, setSelection] = useState<string | null>(null);
-  const [status, setStatus] = useState("loading…");
+  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 }), []);
+  // Routine news ("saved", "updated live") steps back to its dot after a moment,
+  // so it is never what covers a corner of the diagram. A warning stays.
+  const [statusQuiet, setStatusQuiet] = useState(false);
+  useEffect(() => {
+    const timer = setTimeout(() => setStatusQuiet(true), 4000);
+    return () => {
+      clearTimeout(timer);
+      setStatusQuiet(false);
+    };
+  }, [status]);
+  const [tab, setTab] = useState<Tab>("entities");
+  // Phone only: the sheet starts closed so the board owns the screen.
+  const [sheetOpen, setSheetOpen] = useState(false);
+  const [menuOpen, setMenuOpen] = useState(false);
+  // Desktop only: the right column can be folded away.
+  const [panelHidden, setPanelHidden] = useState(false);
+  const boardRef = useRef<HTMLDivElement | null>(null);
+  // The sheet's handle answers a thumb: pull down to close, up to grow, tap to toggle.
+  const sheet = useSheetDrag({ onClose: () => setSheetOpen(false), restVh: 62, tallVh: 92 });
   const [peers, setPeers] = useState(0);
-  const [linkReport, setLinkReport] = useState<ErdValidationError[] | null>(null);
+  // null: not checked. "none": checked, and no state machine sits beside the document.
+  const [linkReport, setLinkReport] = useState<ErdValidationError[] | "none" | null>(null);
   const sessionRef = useRef<BridgeSession | null>(null);
 
   // Load the document, then join its room.
@@ -125,7 +178,7 @@ export default function ErdWorkspace() {
     (async () => {
       const body = await (await fetch(`/api/file${docQuery(requested)}`, { cache: "no-store" })).json();
       if (cancelled) return;
-      if (body.error) return setStatus(body.error);
+      if (body.error) return setStatus(body.error, "warn");
       const path: string = body.path ?? "";
       let loaded: EntityRelationshipDefinition | null = null;
       try {
@@ -134,12 +187,13 @@ export default function ErdWorkspace() {
       } catch {
         // Falls through to the unreadable-document message below.
       }
-      if (body.exists && !loaded) return setStatus(`${path} is not a readable ERD definition`);
+      if (body.exists && !loaded) return setStatus(`${path} is not a readable ERD definition`, "warn");
       const name = (path.split("/").pop() ?? "Untitled").replace(/\.erdf\.json$/i, "");
       const preferred = readNotation();
       setDocPath(path);
       setDef(loaded ?? emptyErd("Default", name));
       setNotation(preferred);
+      setLocked(readLocked());
       setMoved(readMoved(path, preferred));
       setSelection(null);
       setLinkReport(null);
@@ -165,13 +219,13 @@ export default function ErdWorkspace() {
       });
       sessionRef.current = session;
       session.connect();
-    })().catch((e) => !cancelled && setStatus(String(e)));
+    })().catch((e) => !cancelled && setStatus(String(e), "warn"));
     return () => {
       cancelled = true;
       sessionRef.current = null;
       session?.disconnect();
     };
-  }, [requested]);
+  }, [requested, setStatus]);
 
   const positions = useMemo<Record<string, LayoutBox>>(() => {
     if (!def) return {};
@@ -195,7 +249,7 @@ export default function ErdWorkspace() {
       try {
         next = edit(def);
       } catch (e) {
-        return setStatus(e instanceof Error ? e.message : String(e));
+        return setStatus(e instanceof Error ? e.message : String(e), "warn");
       }
       setDef(next);
       setLinkReport(null);
@@ -209,10 +263,10 @@ export default function ErdWorkspace() {
         sessionRef.current?.emitFull(next as unknown as StateMachineDefinition);
         setStatus("saved");
       } catch (e) {
-        setStatus(`not saved: ${e instanceof Error ? e.message : String(e)}`);
+        setStatus(`not saved: ${e instanceof Error ? e.message : String(e)}`, "warn");
       }
     },
-    [def, docPath],
+    [def, docPath, setStatus],
   );
 
   const moveEntity = useCallback(
@@ -257,40 +311,100 @@ export default function ErdWorkspace() {
     setStatus("checking links…");
     const machines = await siblingMachines(docPath);
     if (machines.length === 0) {
-      setLinkReport([]);
-      return setStatus("no .smdf.json beside this document to check against");
+      setLinkReport("none");
+      setTab("issues");
+      setSheetOpen(true);
+      return setStatus("no .smdf.json beside this document to check against", "warn");
     }
     const found = machines.flatMap((m) =>
       checkLinks(m.def, def).map((e) => ({ ...e, message: `${m.def.settings?.name ?? m.path}: ${e.message}` })),
     );
     found.push(...checkStateOf(def, machines.map((m) => m.def.settings?.name ?? "")));
     setLinkReport(found);
-    setStatus(`checked ${machines.length} machine(s): ${found.length} problem(s)`);
+    // The answer lives in the Issues tab, so go there — on a phone it is otherwise behind a closed sheet.
+    setTab("issues");
+    setSheetOpen(true);
+    setPanelHidden(false);
+    setStatus(`checked ${machines.length} machine(s): ${found.length} problem(s)`, found.length ? "warn" : "ok");
   };
 
   const openMachine = async (machine: string): Promise<void> => {
     const hit = (await siblingMachines(docPath)).find((m) => m.def.settings?.name === machine);
     if (hit) navigateToDoc(hit.path);
-    else setStatus(`no .smdf.json beside this document defines '${machine}'`);
+    else setStatus(`no .smdf.json beside this document defines '${machine}'`, "warn");
+  };
+
+  const boardSize = (): { width: number; height: number } => {
+    const rect = boardRef.current?.getBoundingClientRect();
+    return { width: rect?.width ?? 0, height: rect?.height ?? 0 };
+  };
+
+  const toggleLock = (): void => {
+    const next = !locked;
+    setLocked(next);
+    try {
+      localStorage.setItem(LOCK_KEY, next ? "1" : "0");
+    } catch {
+      // The choice then lasts for this visit only.
+    }
+    setStatus(next ? "shapes locked — a drag anywhere moves the view" : "shapes unlocked — drag one to move it");
+  };
+
+  const zoomBy = (factor: number): void => {
+    const { width, height } = boardSize();
+    setViewport((vp) => zoomAt(vp, factor, { x: width / 2, y: height / 2 }));
+  };
+
+  /** Bring one entity to the middle of the board at a size its rows can be read at. */
+  const showOnBoard = (name: string): void => {
+    const box = positions[name];
+    const { width, height } = boardSize();
+    if (!box || !width) return;
+    setViewport(fitToBoxes([box], width, height, { padding: 28, maxScale: 1.25 }));
+    setSelection(name);
+    sheet.close();
+  };
+
+  const openTab = (next: Tab): void => {
+    // Tapping the tab you are already reading closes the sheet, so the dock is
+    // both switcher and dismiss control.
+    if (sheetOpen && tab === next) sheet.close();
+    else setSheetOpen(true);
+    setTab(next);
   };
 
   const selected = def?.entities.find((e) => e.name === selection) ?? null;
   const fileName = docPath.split("/").pop() || "…";
+  const linkProblems = Array.isArray(linkReport) ? linkReport : [];
+  const problemCount = problems.length + linkProblems.length;
+  const tabs: { id: Tab; label: string; icon: ReactNode; badge?: number }[] = [
+    { id: "entities", label: "Entities", icon: "▭" },
+    { id: "relations", label: "Relations", icon: "⟷" },
+    { id: "notes", label: "Notes", icon: "✎", badge: undefined },
+    { id: "issues", label: "Issues", icon: <IssueIcon />, badge: problemCount || undefined },
+  ];
+  const shown = (id: Tab): string => (tab === id ? "" : "hidden md:block");
+
+  const copyMermaid = (): void => {
+    if (def) navigator.clipboard?.writeText(renderMermaidEr(def)).then(() => setStatus("mermaid copied"));
+  };
 
   return (
-    <div className="app-shell flex flex-col overflow-hidden bg-gray-950 text-gray-200">
-      <header className="flex flex-wrap items-center gap-2 border-b border-gray-800 bg-gray-900 px-3 py-2 text-xs">
+    <div
+      className="app-shell dock-offset flex flex-col overflow-hidden bg-gray-950 text-gray-200"
+      onClick={() => menuOpen && setMenuOpen(false)}
+    >
+      {/* One row at every width. What does not fit a phone goes behind ⋯, never onto a second line. */}
+      <header className="relative z-40 flex items-center gap-2 border-b border-gray-800 bg-gray-900 px-2 py-1.5 text-xs md:px-3 md:py-2">
         <span className="font-semibold text-blue-300">ERD</span>
         <DocSwitcher />
-        <span className="text-gray-400" title={docPath}>
-          {def?.settings.name ?? ""} · {fileName}
-        </span>
-        <span className="ml-auto text-gray-500">
-          {status}
-          {peers > 1 ? ` · ${peers} in the room` : ""}
+        <span className="min-w-0 flex-1 truncate text-gray-400" title={docPath}>
+          {def?.settings.name ?? fileName}
+          <span className="hidden text-gray-600 lg:inline"> · {fileName}</span>
         </span>
+
         {/* Same document, two drawings. The choice is this browser's; it is never written to the file. */}
-        <span className="inline-flex overflow-hidden rounded border border-gray-700" role="group" aria-label="Notation">
+        <span className="inline-flex shrink-0 overflow-hidden rounded border border-gray-700" role="group" aria-label="Notation">
           {(
             [
               ["crowsfoot", "▤", "Crow's foot — attributes listed inside the entity box"],
@@ -303,7 +417,7 @@ export default function ErdWorkspace() {
               aria-label={title}
               aria-pressed={notation === id}
               onClick={() => chooseNotation(id)}
-              className={`px-2 py-1 text-sm leading-none ${
+              className={`px-2.5 py-1.5 text-sm leading-none md:px-2 md:py-1 ${
                 notation === id ? "bg-blue-900/60 text-blue-200" : "bg-gray-800 text-gray-400 hover:bg-gray-700"
               }`}
             >
@@ -311,25 +425,66 @@ export default function ErdWorkspace() {
             </button>
           ))}
         </span>
-        <button className={button} onClick={arrange} title="Forget the dragged positions and lay the board out again">
-          ⤢ Arrange
-        </button>
-        <button className={button} onClick={() => setFitKey((k) => k + 1)}>
-          Fit
-        </button>
-        <button className={button} onClick={runLinkCheck} title="Check the state machines beside this document against it">
-          Check links
-        </button>
-        <button
-          className={button}
-          onClick={() => def && navigator.clipboard?.writeText(renderMermaidEr(def)).then(() => setStatus("mermaid copied"))}
-        >
-          Copy mermaid
-        </button>
+
+        <div className="hidden shrink-0 items-center gap-2 md:flex">
+          <button className={button} onClick={arrange} title="Forget the dragged positions and lay the board out again">
+            ⤢ Arrange
+          </button>
+          <button className={button} onClick={runLinkCheck} title="Check the state machines beside this document against it">
+            Check links
+          </button>
+          <button className={button} onClick={copyMermaid}>
+            Copy mermaid
+          </button>
+          <button
+            className={button}
+            onClick={() => setPanelHidden((h) => !h)}
+            aria-pressed={!panelHidden}
+            title={panelHidden ? "Show the panel" : "Hide the panel — the board takes the full width"}
+          >
+            {panelHidden ? "⟨ Panel" : "Panel ⟩"}
+          </button>
+        </div>
+
+        <div className="relative shrink-0 md:hidden">
+          <button
+            className="rounded border border-gray-700 bg-gray-800 px-3 py-1.5 text-sm leading-none text-gray-200"
+            aria-label="More actions"
+            aria-expanded={menuOpen}
+            onClick={(e) => {
+              e.stopPropagation();
+              setMenuOpen((o) => !o);
+            }}
+          >
+            ⋯
+          </button>
+          {menuOpen && (
+            <div className="absolute right-0 top-full z-50 mt-1 w-56 overflow-hidden rounded-lg border border-gray-700 bg-gray-900 py-1 shadow-xl">
+              {(
+                [
+                  ["⤢ Arrange the board", arrange],
+                  ["Check links to the machines", runLinkCheck],
+                  ["Copy as mermaid", copyMermaid],
+                ] as const
+              ).map(([label, run]) => (
+                <button
+                  key={label}
+                  className="block w-full px-4 py-3 text-left text-sm text-gray-200 hover:bg-gray-800"
+                  onClick={() => {
+                    setMenuOpen(false);
+                    run();
+                  }}
+                >
+                  {label}
+                </button>
+              ))}
+            </div>
+          )}
+        </div>
       </header>
 
-      <div className="flex min-h-0 flex-1 flex-col md:flex-row">
-        <div className="min-h-[45dvh] flex-1 overflow-hidden">
+      <div className="relative flex min-h-0 flex-1">
+        <div ref={boardRef} className="relative min-w-0 flex-1 overflow-hidden">
           {def && (
             <EntityRelationshipCanvas
               definition={def}
@@ -338,6 +493,7 @@ export default function ErdWorkspace() {
               viewport={viewport}
               onViewportChange={setViewport}
               selection={selection}
+              readOnly={locked}
               errorElements={errorEntities}
               fitKey={fitKey}
               onSelect={setSelection}
@@ -347,158 +503,394 @@ export default function ErdWorkspace() {
               emptyHint="No entities yet — add one in the panel, or let an agent call add_entity."
             />
           )}
+
+          {/* Status costs no layout: it is a line over the board's corner. */}
+          <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] ${
+              status.tone === "warn" ? "text-amber-300" : "text-gray-500"
+            }`}
+            role="status"
+          >
+            <span className={`h-1.5 w-1.5 shrink-0 rounded-full ${status.tone === "warn" ? "bg-amber-400" : "bg-emerald-500"}`} />
+            <span
+              className={`truncate transition-opacity duration-500 ${
+                statusQuiet && status.tone === "ok" ? "opacity-0" : "opacity-100"
+              }`}
+            >
+              {status.text}
+              {peers > 1 ? ` · ${peers} in the room` : ""}
+            </span>
+          </div>
+
+          {/* View controls live on the board they act on. */}
+          <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">
+            <button
+              title={locked ? "Shapes are locked: dragging moves the view. Tap to unlock." : "Lock the shapes in place, so dragging only moves the view"}
+              aria-label="Lock shapes in place"
+              aria-pressed={locked}
+              onClick={toggleLock}
+              className={`flex h-10 w-10 items-center justify-center border-b border-gray-800 hover:bg-gray-800 md:h-8 md:w-8 ${
+                locked ? "bg-blue-950/60 text-blue-300" : "text-gray-400"
+              }`}
+            >
+              <LockIcon locked={locked} />
+            </button>
+            {(
+              [
+                ["＋", "Zoom in", () => zoomBy(1.25)],
+                ["−", "Zoom out", () => zoomBy(0.8)],
+                ["⛶", "Fit the whole diagram", () => setFitKey((k) => k + 1)],
+              ] as const
+            ).map(([glyph, title, run]) => (
+              <button
+                key={title}
+                title={title}
+                aria-label={title}
+                onClick={run}
+                className="h-10 w-10 border-b border-gray-800 text-base leading-none text-gray-200 last:border-b-0 hover:bg-gray-800 md:h-8 md:w-8 md:text-sm"
+              >
+                {glyph}
+              </button>
+            ))}
+          </div>
+
+          {/* Phone: the way from a tapped entity to its details, without the sheet opening by itself over the board. */}
+          {selected && !sheetOpen && (
+            <button
+              className="absolute bottom-3 left-1/2 max-w-[60%] -translate-x-1/2 truncate rounded-full border border-blue-500/60 bg-gray-900/95 px-4 py-2 text-sm text-blue-200 shadow-lg md:hidden"
+              onClick={() => {
+                setTab("entities");
+                setSheetOpen(true);
+              }}
+            >
+              ✎ {selected.name}
+            </button>
+          )}
         </div>
 
+        {sheetOpen && (
+          <div className="fixed inset-0 z-20 bg-black/50 md:hidden" onClick={sheet.close} aria-hidden="true" />
+        )}
+
         {def && (
-          <aside className="touch-targets w-full overflow-y-auto border-t border-gray-800 bg-gray-900 p-3 md:w-80 md:border-l md:border-t-0">
-            <div className={heading} style={{ marginTop: 0 }}>
-              Entities
-            </div>
-            <div className="flex flex-wrap gap-1">
-              {def.entities.map((e) => (
-                <button
-                  key={e.name}
-                  className={`${button} ${selection === e.name ? "border-blue-500 text-blue-300" : ""}`}
-                  onClick={() => setSelection(e.name)}
-                >
-                  {e.name}
+          <aside
+            style={sheet.sheetStyle}
+            className={`safe-x fixed inset-x-0 bottom-0 z-30 flex h-[var(--sheet-h)] flex-col overflow-hidden rounded-t-2xl border-t border-gray-800 bg-gray-900 shadow-2xl transition-[transform,height] duration-200 ease-out ${
+              sheetOpen ? "translate-y-0" : "pointer-events-none translate-y-full"
+            } md:pointer-events-auto md:static md:z-auto md:h-auto md:w-80 md:translate-y-0 md:rounded-none md:border-l md:border-t-0 md:shadow-none md:transition-none ${
+              panelHidden ? "md:hidden" : ""
+            }`}
+          >
+            <div className="md:hidden" {...sheet.zoneProps}>
+              <div className="flex justify-center pb-1 pt-2">
+                <span className="h-1.5 w-12 rounded-full bg-gray-600" />
+              </div>
+              <div className="flex items-center justify-between border-b border-gray-800 px-4 pb-2">
+                <h2 className="text-sm font-semibold text-gray-300">{tabs.find((t) => t.id === tab)?.label}</h2>
+                <button onClick={sheet.close} className="-mr-2 px-3 py-2 text-lg text-gray-400" aria-label="Close panel">
+                  ✕
                 </button>
-              ))}
+              </div>
             </div>
-            <InlineForm
-              fields={[{ name: "name", placeholder: "new entity" }]}
-              submit="＋ Entity"
-              onSubmit={(v) => {
-                apply((d) => addEntity(d, { name: v.name.trim() }));
-                setSelection(v.name.trim());
-              }}
-            />
 
-            {selected && (
-              <>
-                <div className={heading}>{selected.name}</div>
-                <label
-                  className="mb-1 flex items-center gap-2 text-[11px] text-gray-400"
-                  title="Exists only through another entity (an order line, without its order). Chen draws it as a double rectangle."
-                >
-                  <input
-                    type="checkbox"
-                    checked={!!selected.weak}
-                    onChange={(e) => apply((d) => updateEntity(d, selected.name, { weak: e.target.checked }))}
-                  />
-                  weak entity
-                </label>
-                {(selected.attributes ?? []).map((a) => (
-                  <div key={a.name} className="flex items-center justify-between gap-2 py-0.5 font-mono text-[11px]">
-                    <span className={a.stateOf ? "text-blue-300" : "text-gray-300"}>
-                      {a.name} : {a.type}
-                      <span className="text-gray-500">
-                        {a.key ? ` ${a.key.toUpperCase()}` : ""}
-                        {a.references ? ` → ${a.references}` : ""}
-                        {a.stateOf ? ` ◉ ${[a.stateOf].flat().join(", ")}` : ""}
-                      </span>
+            <div className="touch-targets dock-offset flex-1 overflow-y-auto overscroll-contain p-3">
+              <section className={shown("entities")}>
+                <div className={heading} style={{ marginTop: 0 }}>
+                  Entities
+                </div>
+                <div className="flex flex-wrap gap-1">
+                  {def.entities.map((e) => (
+                    <button
+                      key={e.name}
+                      className={`${button} ${selection === e.name ? "border-blue-500 text-blue-300" : ""}`}
+                      onClick={() => setSelection(e.name)}
+                    >
+                      {e.name}
+                    </button>
+                  ))}
+                </div>
+                <InlineForm
+                  fields={[{ name: "name", placeholder: "new entity" }]}
+                  submit="＋ Entity"
+                  onSubmit={(v) => {
+                    apply((d) => addEntity(d, { name: v.name.trim() }));
+                    setSelection(v.name.trim());
+                  }}
+                />
+
+                {selected && (
+                  <>
+                    <div className={`${heading} flex items-center justify-between gap-2`}>
+                      <span className="truncate text-sm normal-case tracking-normal text-gray-200">{selected.name}</span>
+                      <button
+                        className={`${button} normal-case tracking-normal`}
+                        onClick={() => showOnBoard(selected.name)}
+                        title="Bring this entity to the middle of the board at a readable size"
+                      >
+                        ◎ Show on board
+                      </button>
+                    </div>
+                    <label
+                      className="mb-1 flex items-center gap-2 text-[11px] text-gray-400"
+                      title="Exists only through another entity (an order line, without its order). Chen draws it as a double rectangle."
+                    >
+                      <input
+                        type="checkbox"
+                        checked={!!selected.weak}
+                        onChange={(e) => apply((d) => updateEntity(d, selected.name, { weak: e.target.checked }))}
+                      />
+                      weak entity
+                    </label>
+                    {(selected.attributes ?? []).map((a) => (
+                      <div key={a.name} className="flex items-center justify-between gap-2 py-0.5 font-mono text-[11px]">
+                        <span className={a.stateOf ? "text-blue-300" : "text-gray-300"}>
+                          {a.name} : {a.type}
+                          <span className="text-gray-500">
+                            {a.key ? ` ${a.key.toUpperCase()}` : ""}
+                            {a.references ? ` → ${a.references}` : ""}
+                            {a.stateOf ? ` ◉ ${[a.stateOf].flat().join(", ")}` : ""}
+                          </span>
+                        </span>
+                        <button
+                          className="text-gray-500 hover:text-red-400"
+                          aria-label={`Remove ${a.name}`}
+                          onClick={() => apply((d) => removeAttribute(d, selected.name, a.name))}
+                        >
+                          ✕
+                        </button>
+                      </div>
+                    ))}
+                    <InlineForm
+                      fields={[
+                        { name: "name", placeholder: "attribute" },
+                        { name: "type", placeholder: "type", initial: "string" },
+                        { name: "key", options: ["", "pk", "uk"] },
+                        { name: "references", placeholder: "references Entity.attr" },
+                        { name: "stateOf", placeholder: "stateOf Machine" },
+                      ]}
+                      submit="＋ Attribute"
+                      onSubmit={(v) =>
+                        apply((d) =>
+                          addAttribute(d, selected.name, {
+                            name: v.name.trim(),
+                            type: v.type.trim() || "string",
+                            key: v.key === "pk" || v.key === "uk" ? v.key : undefined,
+                            references: v.references.trim() || undefined,
+                            stateOf: v.stateOf.trim() || undefined,
+                          }),
+                        )
+                      }
+                    />
+                    <button
+                      className={`${button} mt-2 text-red-300`}
+                      onClick={() => {
+                        apply((d) => removeEntity(d, selected.name));
+                        setSelection(null);
+                      }}
+                    >
+                      🗑 Delete {selected.name}
+                    </button>
+                  </>
+                )}
+              </section>
+
+              <section className={shown("relations")}>
+                <div className={`${heading} max-md:mt-0`}>Relationships</div>
+                {def.relationships.length === 0 && <div className="py-0.5 text-[11px] text-gray-600">None yet.</div>}
+                {def.relationships.map((r, i) => (
+                  <div key={i} className="flex items-center justify-between gap-2 py-0.5 text-[11px] text-gray-300">
+                    <span>
+                      {r.from} <span className="text-gray-500">{r.cardinality}</span> {r.to}
+                      {r.label ? <span className="text-gray-500"> : {r.label}</span> : null}
                     </span>
                     <button
                       className="text-gray-500 hover:text-red-400"
-                      aria-label={`Remove ${a.name}`}
-                      onClick={() => apply((d) => removeAttribute(d, selected.name, a.name))}
+                      aria-label="Remove relationship"
+                      onClick={() => apply((d) => removeRelationship(d, r.from, r.to, r.label))}
                     >
                       ✕
                     </button>
                   </div>
                 ))}
-                <InlineForm
-                  fields={[
-                    { name: "name", placeholder: "attribute" },
-                    { name: "type", placeholder: "type", initial: "string" },
-                    { name: "key", options: ["", "pk", "uk"] },
-                    { name: "references", placeholder: "references Entity.attr" },
-                    { name: "stateOf", placeholder: "stateOf Machine" },
-                  ]}
-                  submit="＋ Attribute"
-                  onSubmit={(v) =>
-                    apply((d) =>
-                      addAttribute(d, selected.name, {
-                        name: v.name.trim(),
-                        type: v.type.trim() || "string",
-                        key: v.key === "pk" || v.key === "uk" ? v.key : undefined,
-                        references: v.references.trim() || undefined,
-                        stateOf: v.stateOf.trim() || undefined,
-                      }),
-                    )
-                  }
+                {def.entities.length > 0 && (
+                  <InlineForm
+                    fields={[
+                      { name: "from", options: def.entities.map((e) => e.name) },
+                      { name: "cardinality", options: [...ERD_CARDINALITIES], initial: "1:N" },
+                      { name: "to", options: def.entities.map((e) => e.name) },
+                      { name: "label", placeholder: "label (a verb)" },
+                    ]}
+                    submit="＋ Relationship"
+                    onSubmit={(v) =>
+                      apply((d) =>
+                        addRelationship(d, {
+                          from: v.from,
+                          to: v.to,
+                          cardinality: v.cardinality as ErdCardinality,
+                          label: v.label.trim() || undefined,
+                        }),
+                      )
+                    }
+                  />
+                )}
+              </section>
+
+              <section className={shown("notes")}>
+                <div className={`${heading} max-md:mt-0`}>Notes</div>
+                <p className="mb-1 text-[11px] text-gray-600">
+                  Saved in the document, for whoever opens it next — you, or an agent (it reads them with get_notes).
+                </p>
+                <NotesField
+                  key="diagram"
+                  label="On this diagram"
+                  value={def.settings.notes ?? ""}
+                  placeholder="What was discussed, what is still open…"
+                  onSave={(notes) => apply((d) => updateErdSettings(d, { notes }))}
                 />
-                <button
-                  className={`${button} mt-2 text-red-300`}
-                  onClick={() => {
-                    apply((d) => removeEntity(d, selected.name));
-                    setSelection(null);
-                  }}
-                >
-                  🗑 Delete {selected.name}
-                </button>
-              </>
-            )}
-
-            <div className={heading}>Relationships</div>
-            {def.relationships.map((r, i) => (
-              <div key={i} className="flex items-center justify-between gap-2 py-0.5 text-[11px] text-gray-300">
-                <span>
-                  {r.from} <span className="text-gray-500">{r.cardinality}</span> {r.to}
-                  {r.label ? <span className="text-gray-500"> : {r.label}</span> : null}
-                </span>
-                <button
-                  className="text-gray-500 hover:text-red-400"
-                  aria-label="Remove relationship"
-                  onClick={() => apply((d) => removeRelationship(d, r.from, r.to, r.label))}
-                >
-                  ✕
-                </button>
-              </div>
-            ))}
-            {def.entities.length > 0 && (
-              <InlineForm
-                fields={[
-                  { name: "from", options: def.entities.map((e) => e.name) },
-                  { name: "cardinality", options: [...ERD_CARDINALITIES], initial: "1:N" },
-                  { name: "to", options: def.entities.map((e) => e.name) },
-                  { name: "label", placeholder: "label (a verb)" },
-                ]}
-                submit="＋ Relationship"
-                onSubmit={(v) =>
-                  apply((d) =>
-                    addRelationship(d, {
-                      from: v.from,
-                      to: v.to,
-                      cardinality: v.cardinality as ErdCardinality,
-                      label: v.label.trim() || undefined,
-                    }),
-                  )
-                }
-              />
-            )}
-
-            {(problems.length > 0 || linkReport) && <div className={heading}>Problems</div>}
-            {problems.map((p, i) => (
-              <div key={`p${i}`} className="py-0.5 text-[11px] text-red-300">
-                [{p.ruleId}] {p.message}
-              </div>
-            ))}
-            {linkReport?.length === 0 && problems.length === 0 && (
-              <div className="py-0.5 text-[11px] text-green-400">Every name the machines use resolves.</div>
-            )}
-            {linkReport?.map((p, i) => (
-              <div key={`l${i}`} className="py-0.5 text-[11px] text-amber-300">
-                [{p.ruleId}] {p.message}
-              </div>
-            ))}
+                {selected ? (
+                  <NotesField
+                    key={`entity:${selected.name}`}
+                    label={`On ${selected.name}`}
+                    value={selected.notes ?? ""}
+                    placeholder={`A question or a decision about ${selected.name}…`}
+                    onSave={(notes) => apply((d) => updateEntity(d, selected.name, { notes }))}
+                  />
+                ) : (
+                  <p className="mt-2 text-[11px] text-gray-600">Select an entity to leave a note on it.</p>
+                )}
+                {def.entities.some((e) => e.notes?.trim()) && (
+                  <>
+                    <div className={heading}>Entities with notes</div>
+                    <div className="flex flex-wrap gap-1">
+                      {def.entities
+                        .filter((e) => e.notes?.trim())
+                        .map((e) => (
+                          <button
+                            key={e.name}
+                            className={`${button} ${selection === e.name ? "border-blue-500 text-blue-300" : ""}`}
+                            onClick={() => setSelection(e.name)}
+                          >
+                            {e.name}
+                          </button>
+                        ))}
+                    </div>
+                  </>
+                )}
+              </section>
+
+              <section className={shown("issues")}>
+                <div className={`${heading} max-md:mt-0 ${problemCount === 0 && !linkReport ? "md:hidden" : ""}`}>Issues</div>
+                {problems.map((p, i) => (
+                  <div key={`p${i}`} className="py-0.5 text-[11px] text-red-300">
+                    [{p.ruleId}] {p.message}
+                  </div>
+                ))}
+                {linkProblems.map((p, i) => (
+                  <div key={`l${i}`} className="py-0.5 text-[11px] text-amber-300">
+                    [{p.ruleId}] {p.message}
+                  </div>
+                ))}
+                {linkReport === "none" && (
+                  <div className="py-0.5 text-[11px] text-amber-300">
+                    No state machine (.smdf.json) sits beside this document, so there was nothing to check it against.
+                  </div>
+                )}
+                {problemCount === 0 && linkReport !== "none" && (
+                  <div className={`py-0.5 text-[11px] ${linkReport ? "text-green-400" : "text-gray-600 md:hidden"}`}>
+                    {linkReport
+                      ? "Every name the machines use resolves."
+                      : "The document is valid. “Check links” (⋯) holds the state machines beside it against it."}
+                  </div>
+                )}
+              </section>
+            </div>
           </aside>
         )}
       </div>
+
+      {/* Tab dock (phone). Three tabs one thumb-tap away, and the issue count is on screen at all times. */}
+      <nav className="dock-safe safe-x fixed inset-x-0 bottom-0 z-40 flex border-t border-gray-800 bg-gray-900/95 backdrop-blur-md md:hidden">
+        {tabs.map((t) => {
+          const current = sheetOpen && tab === t.id;
+          return (
+            <button
+              key={t.id}
+              onClick={() => openTab(t.id)}
+              aria-pressed={current}
+              className={`relative flex h-14 flex-1 flex-col items-center justify-center gap-0.5 text-[11px] transition-colors ${
+                current ? "text-blue-400" : "text-gray-500"
+              }`}
+            >
+              <span className="flex h-4 items-center text-base leading-none">{t.icon}</span>
+              <span>{t.label}</span>
+              {t.badge !== undefined && (
+                <span className="absolute right-1/2 top-1 min-w-[16px] translate-x-5 rounded-full border border-red-900/80 bg-red-950/80 px-1 text-[10px] leading-4 text-red-200">
+                  {t.badge}
+                </span>
+              )}
+              {current && <span className="absolute inset-x-4 top-0 h-0.5 rounded-full bg-blue-400" />}
+            </button>
+          );
+        })}
+      </nav>
     </div>
   );
 }
 
+/**
+ * A notes box that saves by itself: shortly after the typing stops, and when
+ * focus leaves it. Each save is a whole-document write, so it is not done per
+ * keystroke. When the saved text changes underneath — an agent's set_notes,
+ * for instance — the box takes it, unless someone is typing in it: a save of
+ * their own words coming back must never pull the text out from under them.
+ */
+function NotesField({
+  label,
+  value,
+  placeholder,
+  onSave,
+}: {
+  label: string;
+  value: string;
+  placeholder: string;
+  onSave: (notes: string) => void;
+}) {
+  const [draft, setDraft] = useState(value);
+  const [seen, setSeen] = useState(value);
+  const [focused, setFocused] = useState(false);
+  if (value !== seen) {
+    setSeen(value);
+    if (!focused) setDraft(value);
+  }
+  const timer = useRef<ReturnType<typeof setTimeout> | null>(null);
+  const save = (text: string): void => {
+    if (timer.current) clearTimeout(timer.current);
+    timer.current = null;
+    if (text !== value) onSave(text);
+  };
+  return (
+    <label className="mt-2 block">
+      <span className="text-[11px] text-gray-500">{label}</span>
+      <textarea
+        className={`${input} h-24 resize-y leading-snug`}
+        placeholder={placeholder}
+        value={draft}
+        onChange={(e) => {
+          const text = e.target.value;
+          setDraft(text);
+          if (timer.current) clearTimeout(timer.current);
+          timer.current = setTimeout(() => save(text), 900);
+        }}
+        onFocus={() => setFocused(true)}
+        onBlur={() => {
+          setFocused(false);
+          save(draft);
+        }}
+      />
+    </label>
+  );
+}
+
 interface Field {
   name: string;
   placeholder?: string;
@@ -559,7 +951,7 @@ function InlineForm({
           />
         ),
       )}
-      <button type="submit" className={`${button} col-span-2`}>
+      <button type="submit" className={`${button} ${fields.length === 1 ? "" : "col-span-2"}`}>
         {submit}
       </button>
     </form>