@miadi/stateloom-web 0.1.8 → 0.1.9

package/server/src/app/page.tsx

@@ -1,6 +1,6 @@
 "use client";
 
-import { useEffect, useState, type CSSProperties } from "react";
+import { useEffect, useState, type CSSProperties, type ReactNode } from "react";
 import Canvas from "@/components/Canvas";
 import PropertiesPanel from "@/components/PropertiesPanel";
 import EventsPanel from "@/components/EventsPanel";
@@ -12,9 +12,11 @@ import DesignBridge from "@/components/DesignBridge";
 import UiScale from "@/components/UiScale";
 import { useDesignerStore } from "@/store/useDesignerStore";
 import ErdWorkspace from "@/components/erd/ErdWorkspace";
+import IssueIcon from "@/components/IssueIcon";
 import { isErdfPath } from "@miadi/stateloom-protocol";
 import { useRequestedDoc } from "@/lib/docParam";
 import { loadRuntimeConfig } from "@/lib/runtimeConfig";
+import { useSheetDrag } from "@/lib/useSheetDrag";
 
 type Tab = "properties" | "events" | "settings" | "validation";
 
@@ -78,6 +80,8 @@ function MachineDesigner() {
   // the entire screen, and at `md` and up the responsive classes pin it open as
   // the 320px right sidebar it has always been — this flag stops mattering.
   const [sheetOpen, setSheetOpen] = useState(false);
+  // The sheet's handle answers a thumb: pull down to close, up to grow, tap to toggle.
+  const sheet = useSheetDrag({ onClose: () => setSheetOpen(false), restVh: 70, tallVh: 92 });
   const errors = useDesignerStore((s) => s.errors);
   const contextMenu = useDesignerStore((s) => s.contextMenu);
   const hideContextMenu = useDesignerStore((s) => s.hideContextMenu);
@@ -86,11 +90,12 @@ function MachineDesigner() {
   const setDrawMode = useDesignerStore((s) => s.setDrawMode);
   const setDrawSource = useDesignerStore((s) => s.setDrawSource);
 
-  const tabs: { id: Tab; label: string; icon: string; badge?: number }[] = [
+  const tabs: { id: Tab; label: string; icon: ReactNode; badge?: number }[] = [
     { id: "properties", label: "Properties", icon: "🎛" },
     { id: "events", label: "Events", icon: "⚡" },
     { id: "settings", label: "Settings", icon: "⚙" },
-    { id: "validation", label: "Errors", icon: "⚠", badge: errors.length || undefined },
+    // Drawn, not typed: "⚠" is a bright yellow colour emoji on iOS. See IssueIcon.
+    { id: "validation", label: "Errors", icon: <IssueIcon />, badge: errors.length || undefined },
   ];
 
   const activeLabel = tabs.find((t) => t.id === activeTab)?.label ?? "";
@@ -99,7 +104,8 @@ function MachineDesigner() {
   // both switcher and dismiss control and no screen height is spent on a
   // separate close affordance.
   const toggleTab = (id: Tab) => {
-    setSheetOpen((wasOpen) => !(wasOpen && activeTab === id));
+    if (sheetOpen && activeTab === id) sheet.close();
+    else setSheetOpen(true);
     setActiveTab(id);
   };
 
@@ -125,7 +131,7 @@ function MachineDesigner() {
         {sheetOpen && (
           <div
             className="fixed inset-0 z-20 bg-black/50 md:hidden"
-            onClick={() => setSheetOpen(false)}
+            onClick={sheet.close}
             aria-hidden="true"
           />
         )}
@@ -136,21 +142,22 @@ function MachineDesigner() {
             declaration — position, height, width, transform, radius, border
             side — which is why the class list is long. */}
         <aside
-          className={`safe-x fixed inset-x-0 bottom-0 z-30 h-[70dvh] flex flex-col overflow-hidden rounded-t-2xl border-t border-gray-800 bg-gray-900 shadow-2xl transition-transform duration-200 ease-out ${
+          style={sheet.sheetStyle}
+          className={`safe-x fixed inset-x-0 bottom-0 z-30 h-[var(--sheet-h)] flex 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" : "translate-y-full pointer-events-none"
           } md:static md:z-auto md:h-auto md:w-80 md:translate-y-0 md:pointer-events-auto md:rounded-none md:border-t-0 md:border-l md:shadow-none md:transition-none`}
         >
           {/* Sheet header (phone). The grab handle reads as "this thing is a
               sheet"; the dock below already names the tabs, so repeating the
               tab bar here would only cost height. */}
-          <div className="md:hidden">
+          <div className="md:hidden" {...sheet.zoneProps}>
             <div className="flex justify-center pt-2 pb-1">
-              <span className="h-1 w-10 rounded-full bg-gray-700" />
+              <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">{activeLabel}</h2>
               <button
-                onClick={() => setSheetOpen(false)}
+                onClick={sheet.close}
                 className="-mr-2 px-3 py-2 text-lg text-gray-400"
                 aria-label="Close panel"
               >
@@ -215,7 +222,7 @@ function MachineDesigner() {
                 current ? "text-blue-400" : "text-gray-500"
               }`}
             >
-              <span className="text-base leading-none">{tab.icon}</span>
+              <span className="flex h-4 items-center text-base leading-none">{tab.icon}</span>
               <span>{tab.label}</span>
               {tab.badge !== undefined && tab.badge > 0 && (
                 <span className="absolute top-1 right-1/2 translate-x-4 rounded-full bg-red-600 px-1 text-[10px] leading-4 text-white min-w-[16px]">

package/server/src/components/IssueIcon.tsx

@@ -0,0 +1,28 @@
+/**
+ * A warning triangle drawn as an outline in the current text colour.
+ *
+ * The "⚠" character is a full-colour emoji on iOS: a saturated yellow sign in
+ * a dock of grey glyphs, pulling the eye whether or not there is anything to
+ * report. Drawn here instead, it is as quiet as its neighbours and takes the
+ * tab's own colour — grey at rest, the accent when its tab is open. The count
+ * badge beside it is what says there is something to look at.
+ */
+export default function IssueIcon({ size = 16 }: { size?: number }) {
+  return (
+    <svg
+      width={size}
+      height={size}
+      viewBox="0 0 24 24"
+      fill="none"
+      stroke="currentColor"
+      strokeWidth="1.6"
+      strokeLinecap="round"
+      strokeLinejoin="round"
+      aria-hidden="true"
+    >
+      <path d="M12 4.5 21 19.5H3Z" />
+      <path d="M12 10v4.5" />
+      <path d="M12 17.3v.01" />
+    </svg>
+  );
+}

package/server/src/components/LockIcon.tsx

@@ -0,0 +1,24 @@
+/**
+ * A padlock drawn as an outline in the current text colour — closed or open.
+ * Drawn rather than typed for the same reason as IssueIcon: the padlock
+ * characters are full-colour emoji on iOS, a gold lock on a board of grey.
+ */
+export default function LockIcon({ locked, size = 16 }: { locked: boolean; size?: number }) {
+  return (
+    <svg
+      width={size}
+      height={size}
+      viewBox="0 0 24 24"
+      fill="none"
+      stroke="currentColor"
+      strokeWidth="1.6"
+      strokeLinecap="round"
+      strokeLinejoin="round"
+      aria-hidden="true"
+    >
+      <rect x="5" y="11" width="14" height="9" rx="2" />
+      {/* The shackle: seated in the body when locked, swung clear of it when not. */}
+      <path d={locked ? "M8 11V8a4 4 0 0 1 8 0v3" : "M8 11V8a4 4 0 0 1 7.5-1.9"} />
+    </svg>
+  );
+}

package/server/src/components/PropertiesPanel.tsx

@@ -116,6 +116,16 @@ export default function PropertiesPanel() {
             onChange={(e) => updateState(selection.id!, { description: e.target.value || undefined })}
           />
         </label>
+        {/* Notes: what was said about this state, kept in the document for whoever opens it next. */}
+        <label className="block">
+          <span className="text-xs text-gray-500">Notes</span>
+          <textarea
+            className="w-full bg-gray-800 border border-gray-700 rounded px-2 py-1 text-xs text-gray-200 h-20"
+            placeholder="An open question, a decision, something to tell the agent…"
+            value={state.notes ?? ""}
+            onChange={(e) => updateState(selection.id!, { notes: e.target.value || undefined })}
+          />
+        </label>
 
         {/* onEntry actions */}
         <ActionEditor

package/server/src/components/SettingsPanel.tsx

@@ -38,6 +38,17 @@ export default function SettingsPanel() {
         />
       </label>
 
+      {/* Notes about the whole diagram, kept in the document for whoever opens it next. */}
+      <label className="block">
+        <span className="text-xs text-gray-500">Notes on this diagram</span>
+        <textarea
+          className="w-full bg-gray-800 border border-gray-700 rounded px-2 py-1 text-xs text-gray-200 h-24"
+          placeholder="What was discussed, what is still open, what to tell the agent…"
+          value={settings.notes ?? ""}
+          onChange={(e) => updateSettings({ notes: e.target.value || undefined })}
+        />
+      </label>
+
       <label className="flex items-center gap-2 text-sm text-gray-300">
         <input
           type="checkbox"

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

@@ -21,7 +21,7 @@
  * `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 {
@@ -42,6 +42,7 @@ import {
   removeRelationship,
   renderMermaidEr,
   updateEntity,
+  updateErdSettings,
   validateErd,
   type EntityRelationshipDefinition,
   type ErdCardinality,
@@ -52,11 +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" | "problems";
+type Tab = "entities" | "relations" | "notes" | "issues";
 type Edit = (def: EntityRelationshipDefinition) => EntityRelationshipDefinition;
 
 // The two notations give an entity different footprints, so each keeps its own
@@ -65,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 {
@@ -120,6 +140,8 @@ 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);
@@ -142,6 +164,8 @@ export default function ErdWorkspace() {
   // 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);
   // null: not checked. "none": checked, and no state machine sits beside the document.
   const [linkReport, setLinkReport] = useState<ErdValidationError[] | "none" | null>(null);
@@ -169,6 +193,7 @@ export default function ErdWorkspace() {
       setDocPath(path);
       setDef(loaded ?? emptyErd("Default", name));
       setNotation(preferred);
+      setLocked(readLocked());
       setMoved(readMoved(path, preferred));
       setSelection(null);
       setLinkReport(null);
@@ -287,7 +312,7 @@ export default function ErdWorkspace() {
     const machines = await siblingMachines(docPath);
     if (machines.length === 0) {
       setLinkReport("none");
-      setTab("problems");
+      setTab("issues");
       setSheetOpen(true);
       return setStatus("no .smdf.json beside this document to check against", "warn");
     }
@@ -296,8 +321,8 @@ export default function ErdWorkspace() {
     );
     found.push(...checkStateOf(def, machines.map((m) => m.def.settings?.name ?? "")));
     setLinkReport(found);
-    // The answer lives in the Problems tab, so go there — on a phone it is otherwise behind a closed sheet.
-    setTab("problems");
+    // 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");
@@ -314,6 +339,17 @@ export default function ErdWorkspace() {
     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 }));
@@ -326,13 +362,14 @@ export default function ErdWorkspace() {
     if (!box || !width) return;
     setViewport(fitToBoxes([box], width, height, { padding: 28, maxScale: 1.25 }));
     setSelection(name);
-    setSheetOpen(false);
+    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.
-    setSheetOpen((wasOpen) => !(wasOpen && tab === next));
+    if (sheetOpen && tab === next) sheet.close();
+    else setSheetOpen(true);
     setTab(next);
   };
 
@@ -340,10 +377,11 @@ export default function ErdWorkspace() {
   const fileName = docPath.split("/").pop() || "…";
   const linkProblems = Array.isArray(linkReport) ? linkReport : [];
   const problemCount = problems.length + linkProblems.length;
-  const tabs: { id: Tab; label: string; icon: string; badge?: number }[] = [
+  const tabs: { id: Tab; label: string; icon: ReactNode; badge?: number }[] = [
     { id: "entities", label: "Entities", icon: "▭" },
     { id: "relations", label: "Relations", icon: "⟷" },
-    { id: "problems", label: "Problems", icon: "⚠", badge: problemCount || undefined },
+    { 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");
 
@@ -455,6 +493,7 @@ export default function ErdWorkspace() {
               viewport={viewport}
               onViewportChange={setViewport}
               selection={selection}
+              readOnly={locked}
               errorElements={errorEntities}
               fitKey={fitKey}
               onSelect={setSelection}
@@ -485,6 +524,17 @@ export default function ErdWorkspace() {
 
           {/* 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)],
@@ -519,24 +569,25 @@ export default function ErdWorkspace() {
         </div>
 
         {sheetOpen && (
-          <div className="fixed inset-0 z-20 bg-black/50 md:hidden" onClick={() => setSheetOpen(false)} aria-hidden="true" />
+          <div className="fixed inset-0 z-20 bg-black/50 md:hidden" onClick={sheet.close} aria-hidden="true" />
         )}
 
         {def && (
           <aside
-            className={`safe-x fixed inset-x-0 bottom-0 z-30 flex h-[62dvh] flex-col overflow-hidden rounded-t-2xl border-t border-gray-800 bg-gray-900 shadow-2xl transition-transform duration-200 ease-out ${
+            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">
+            <div className="md:hidden" {...sheet.zoneProps}>
               <div className="flex justify-center pb-1 pt-2">
-                <span className="h-1 w-10 rounded-full bg-gray-700" />
+                <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={() => setSheetOpen(false)} className="-mr-2 px-3 py-2 text-lg text-gray-400" aria-label="Close panel">
+                <button onClick={sheet.close} className="-mr-2 px-3 py-2 text-lg text-gray-400" aria-label="Close panel">
                   ✕
                 </button>
               </div>
@@ -684,8 +735,51 @@ export default function ErdWorkspace() {
                 )}
               </section>
 
-              <section className={shown("problems")}>
-                <div className={`${heading} max-md:mt-0 ${problemCount === 0 && !linkReport ? "md:hidden" : ""}`}>Problems</div>
+              <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 }))}
+                />
+                {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}
@@ -714,7 +808,7 @@ export default function ErdWorkspace() {
         )}
       </div>
 
-      {/* Tab dock (phone). Three tabs one thumb-tap away, and the problem count is on screen at all times. */}
+      {/* 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;
@@ -727,10 +821,10 @@ export default function ErdWorkspace() {
                 current ? "text-blue-400" : "text-gray-500"
               }`}
             >
-              <span className="text-base leading-none">{t.icon}</span>
+              <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 bg-red-600 px-1 text-[10px] leading-4 text-white">
+                <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>
               )}
@@ -743,6 +837,60 @@ export default function ErdWorkspace() {
   );
 }
 
+/**
+ * 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;

package/server/src/lib/useSheetDrag.ts

@@ -0,0 +1,95 @@
+"use client";
+
+/**
+ * The phone sheet's grab handle, made to do what it looks like it does.
+ *
+ * The handle used to be decoration: it read as "this thing is a sheet" and
+ * answered no gesture, so a thumb pulling it down — the one thing a handle
+ * invites — got nothing. This hook gives the zone around it three answers:
+ *
+ *   drag down   the sheet follows the finger; past a threshold it closes
+ *               (from the tall size, a short pull returns to the resting size)
+ *   drag up     the sheet grows with the finger; past a threshold it stays tall
+ *   tap         toggles between the resting and the tall size
+ *
+ * Height is handed to the sheet as the `--sheet-h` custom property rather than
+ * an inline `height`, so the desktop rule (`md:h-auto`) still wins where the
+ * sheet is a sidebar and none of this applies. A press that starts on a button
+ * inside the zone (the ✕) is left to the button.
+ */
+import { useRef, useState, type CSSProperties, type PointerEvent as ReactPointerEvent } from "react";
+
+const CLOSE_AFTER = 80;
+const CLOSE_FROM_TALL_AFTER = 260;
+const GROW_AFTER = 50;
+const TAP_SLOP = 6;
+
+export interface SheetDrag {
+  /** Spread on the element that holds the handle. */
+  zoneProps: {
+    onPointerDown: (e: ReactPointerEvent<HTMLElement>) => void;
+    onPointerMove: (e: ReactPointerEvent<HTMLElement>) => void;
+    onPointerUp: (e: ReactPointerEvent<HTMLElement>) => void;
+    onPointerCancel: (e: ReactPointerEvent<HTMLElement>) => void;
+    style: CSSProperties;
+  };
+  /** Spread on the sheet itself, which sizes itself with `h-[var(--sheet-h)]`. */
+  sheetStyle: CSSProperties;
+  /** Close the sheet and return it to its resting size for next time. */
+  close: () => void;
+}
+
+export function useSheetDrag(opts: { onClose: () => void; restVh: number; tallVh: number }): SheetDrag {
+  const { onClose, restVh, tallVh } = opts;
+  const [tall, setTall] = useState(false);
+  const [dy, setDy] = useState<number | null>(null);
+  const press = useRef<{ y: number; id: number } | null>(null);
+
+  const close = (): void => {
+    setTall(false);
+    onClose();
+  };
+
+  const release = (e: ReactPointerEvent<HTMLElement>): void => {
+    const p = press.current;
+    if (!p || p.id !== e.pointerId) return;
+    press.current = null;
+    const d = e.clientY - p.y;
+    setDy(null);
+    if (Math.abs(d) < TAP_SLOP) return setTall((t) => !t);
+    if (d <= -GROW_AFTER) return setTall(true);
+    if (d >= CLOSE_AFTER) {
+      if (tall && d < CLOSE_FROM_TALL_AFTER) return setTall(false);
+      close();
+    }
+  };
+
+  const vh = tall ? tallVh : restVh;
+  const dragging = dy !== null;
+  const sheetStyle: CSSProperties & Record<"--sheet-h", string> = {
+    "--sheet-h": dragging && dy < 0 ? `min(calc(${vh}dvh + ${-dy}px), ${tallVh}dvh)` : `${vh}dvh`,
+    ...(dragging ? { transition: "none" } : {}),
+    ...(dragging && dy > 0 ? { transform: `translateY(${dy}px)` } : {}),
+  };
+
+  return {
+    zoneProps: {
+      onPointerDown: (e) => {
+        if ((e.target as HTMLElement).closest("button")) return;
+        press.current = { y: e.clientY, id: e.pointerId };
+        e.currentTarget.setPointerCapture(e.pointerId);
+        setDy(0);
+      },
+      onPointerMove: (e) => {
+        const p = press.current;
+        if (p && p.id === e.pointerId) setDy(e.clientY - p.y);
+      },
+      onPointerUp: release,
+      onPointerCancel: release,
+      // The zone is a gesture surface: the browser must not scroll or pan with it.
+      style: { touchAction: "none", cursor: "grab" },
+    },
+    sheetStyle,
+    close,
+  };
+}

package/server/src/types/definition.ts

@@ -21,6 +21,8 @@ export interface SettingsModel {
   namespace: string;
   name?: string;
   description?: string;
+  /** Working notes about the whole diagram — saved in the document, ignored by engines and codegen. */
+  notes?: string;
   asynchronous: boolean;
   /**
    * Objects the generated context is constructed with. `ObjectRef` is what
@@ -97,6 +99,8 @@ export interface StateDef {
   name: string;
   kind?: StateKindType;
   description?: string;
+  /** Working notes about this state: the conversation about it, where `description` says what it is. */
+  notes?: string;
   onEntry?: { actions: ActionDef[] };
   onExit?: { actions: ActionDef[] };
   transitions?: TransitionDef[];

package/server/stateloom-web.json

@@ -1,5 +1,5 @@
 {
-  "package": "0.1.8",
-  "designer": "0.1.8",
+  "package": "0.1.9",
+  "designer": "0.1.9",
   "next": "16.1.6"
 }