@miadi/stateloom-web 0.1.2 → 0.1.4

package/server/package-lock.json

@@ -1,12 +1,12 @@
 {
-  "name": "stateloom-web",
-  "version": "0.1.1",
+  "name": "@miadi/stateloom-web-source",
+  "version": "0.1.4",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
-      "name": "stateloom-web",
-      "version": "0.1.1",
+      "name": "@miadi/stateloom-web-source",
+      "version": "0.1.4",
       "dependencies": {
         "@miadi/stateloom-canvas": "file:../bridge-canvas",
         "@miadi/stateloom-client": "file:../bridge-client",

package/server/package.json

@@ -1,7 +1,21 @@
 {
-  "name": "stateloom-web",
-  "version": "0.1.2",
+  "name": "@miadi/stateloom-web-source",
+  "version": "0.1.4",
   "private": true,
+  "//": [
+    "This is the designer's SOURCE and is never published — hence private: true.",
+    "What ships is its BUILD: `next build` (output: standalone) produces",
+    ".next/standalone, which web-dist/scripts/sync-web.mjs assembles into",
+    "web-dist/server/ and publishes as @miadi/stateloom-web. So `npx -y",
+    "@miadi/stateloom-web` runs this app without a Next.js toolchain anywhere.",
+    "",
+    "Until 2026-08-16 this package was also called `stateloom-web`, and two",
+    "different things answering to one name is why it kept looking as though the",
+    "designer was the one package nobody had published.",
+    "",
+    "The version here is the DESIGNER's version, reported by `stateloom-web",
+    "--version` as `designer`. Bump it with web-dist's when the canvas changes."
+  ],
   "scripts": {
     "dev": "next dev -p ${PORT:-4598}",
     "build": "next build",

package/server/src/app/api/docs/route.ts

@@ -0,0 +1,31 @@
+/**
+ * GET /api/docs — the documents this server would let you open.
+ *
+ * The `?doc=` parameter and its allowlist shipped together; the way to SEE what
+ * the allowlist admits did not, so the switcher was a path prompt with no
+ * autocomplete and the paths it wanted were the server's, not the human's. In a
+ * container those differ — your `~/diagrams` is the server's `/data` — which
+ * made "switch diagrams" a thing you had to already know how to do.
+ *
+ * Enumeration is bounded in lib/projectFile.ts (depth, count, no dotfiles) and
+ * confined to the same roots `resolveDocPath` enforces, so this endpoint can
+ * never reveal a path the file API would refuse to serve.
+ */
+import { NextResponse } from "next/server";
+import { allowedDocRoots, getProjectFilePath, listDocuments } from "@/lib/projectFile";
+
+export const dynamic = "force-dynamic";
+export const revalidate = 0;
+
+export async function GET(): Promise<Response> {
+  const { docs, truncated } = listDocuments();
+  return NextResponse.json(
+    {
+      roots: allowedDocRoots(),
+      current: getProjectFilePath(),
+      docs,
+      truncated,
+    },
+    { headers: { "cache-control": "no-store" } },
+  );
+}

package/server/src/app/globals.css

@@ -108,15 +108,10 @@ body {
   }
 }
 
-/* Presence chips ride the top-right corner. Under `viewport-fit=cover` that
-   corner can be beneath a notch or the status bar, so the offset is measured
-   from the safe area rather than the raw viewport edge. */
-.presence-dock {
-  position: fixed;
-  top: calc(env(safe-area-inset-top) + 0.5rem);
-  right: calc(env(safe-area-inset-right) + 1rem);
-  z-index: 50;
-}
+/* `.presence-dock` lived here: a fixed top-right rail of one pill per peer.
+   It grew with the room and painted itself across the toolbar's own controls,
+   so presence moved into the toolbar flow as a single fixed-width control —
+   see components/PresenceChips.tsx. Nothing floats over the navigation now. */
 
 /* The way back. A pinch on the chrome moves the root font size, and every length
    in this stylesheet is a multiple of it — so at 175% the app is legible but the

package/server/src/components/DocSwitcher.tsx

@@ -1,20 +1,60 @@
 "use client";
 
-import { useState } from "react";
+import { useEffect, useState } from "react";
 import { navigateToDoc, useRequestedDoc } from "@/lib/docParam";
 import { rememberedDocs } from "@/lib/layoutMemory";
 
+interface DocEntry {
+  path: string;
+  name: string;
+  dir: string;
+  mtime: number;
+}
+
 /**
  * A human switches diagrams without an agent and without a terminal
- * (chart_1785683062725). Presentation over state that already exists: recents
- * are the documents this browser holds layout memory for, plus a free path
- * field. Choosing navigates via `?doc=` — the providers re-key (step 3), the
- * server allowlist guards (step 1), no reload, no new transport.
+ * (chart_1785683062725). Choosing navigates via `?doc=` — the providers re-key
+ * (step 3), the server allowlist guards (step 1), no reload, no new transport.
+ *
+ * The list comes from `GET /api/docs`, which enumerates exactly what that
+ * allowlist admits. Before it existed this was a free-text field over this
+ * browser's layout memory — empty on first use — so switching required knowing
+ * the server's path for a directory you were looking at under a different name,
+ * and typing it by hand every time. In a container that is `/data`, which is
+ * not a thing anyone can guess. The field stays, for a path the walk did not
+ * reach; it is no longer the only way in.
  */
 export default function DocSwitcher() {
   const requested = useRequestedDoc();
   const [open, setOpen] = useState(false);
   const [typed, setTyped] = useState("");
+  const [docs, setDocs] = useState<DocEntry[] | null>(null);
+  const [roots, setRoots] = useState<string[]>([]);
+  const [error, setError] = useState<string | null>(null);
+
+  // Fetched on each open, not once: an agent creating a document while the
+  // panel is shut is the normal case, and a stale list is the whole complaint.
+  useEffect(() => {
+    if (!open) return;
+    let live = true;
+    setError(null);
+    fetch("/api/docs", { cache: "no-store" })
+      .then((r) => (r.ok ? r.json() : Promise.reject(new Error(`HTTP ${r.status}`))))
+      .then((body: { docs?: DocEntry[]; roots?: string[] }) => {
+        if (!live) return;
+        setDocs(body.docs ?? []);
+        setRoots(body.roots ?? []);
+      })
+      .catch((e: Error) => {
+        if (!live) return;
+        // An older server has no /api/docs. Recents and the field still work.
+        setDocs([]);
+        setError(e.message);
+      });
+    return () => {
+      live = false;
+    };
+  }, [open]);
 
   const go = (doc: string | null) => {
     setOpen(false);
@@ -22,10 +62,22 @@ export default function DocSwitcher() {
     navigateToDoc(doc);
   };
 
+  // Layout memory still contributes: a document reached once and since deleted,
+  // or one outside the walk's depth, is worth keeping in reach.
+  const listed = new Set((docs ?? []).map((d) => d.path));
   const recents = open
-    ? rememberedDocs().filter((d) => d.startsWith("/") && d !== requested)
+    ? rememberedDocs().filter((d) => d.startsWith("/") && d !== requested && !listed.has(d))
     : [];
 
+  const available = (docs ?? []).filter((d) => d.path !== requested);
+  const filter = typed.trim().toLowerCase();
+  const shown = filter
+    ? available.filter((d) => d.path.toLowerCase().includes(filter))
+    : available;
+
+  const rowClass =
+    "block w-full truncate rounded px-1.5 py-1 text-left text-xs text-gray-300 hover:bg-gray-800";
+
   return (
     <span className="relative inline-flex">
       <button
@@ -36,47 +88,83 @@ export default function DocSwitcher() {
         ⇄
       </button>
       {open && (
-        <div className="absolute left-0 top-full z-50 mt-1 w-72 rounded border border-gray-700 bg-gray-900 p-2 shadow-lg">
+        <div className="absolute left-0 top-full z-50 mt-1 w-80 rounded border border-gray-700 bg-gray-900 p-2 shadow-lg">
           <div className="mb-1 text-[10px] uppercase tracking-wide text-gray-500">
             switch document
           </div>
-          {requested && (
-            <button
-              onClick={() => go(null)}
-              className="block w-full truncate rounded px-1.5 py-1 text-left text-xs text-gray-300 hover:bg-gray-800"
-              title="Return to the default project file"
-            >
-              ⌂ default document
-            </button>
-          )}
-          {recents.map((d) => (
-            <button
-              key={d}
-              onClick={() => go(d)}
-              className="block w-full truncate rounded px-1.5 py-1 text-left text-xs text-gray-300 hover:bg-gray-800"
-              title={d}
-            >
-              {d.split("/").pop()}
-              <span className="ml-1 text-[10px] text-gray-600">{d}</span>
-            </button>
-          ))}
+
+          {/* Doubles as filter and as free-text path — one field, because with a
+              list present the typing is almost always narrowing, not addressing. */}
           <form
             onSubmit={(e) => {
               e.preventDefault();
-              if (typed.trim()) go(typed.trim());
+              const value = typed.trim();
+              if (!value) return;
+              // A single match means the human already chose it by narrowing.
+              if (shown.length === 1) return go(shown[0]!.path);
+              if (value.startsWith("/")) return go(value);
             }}
-            className="mt-1 flex gap-1"
+            className="mb-1 flex gap-1"
           >
             <input
               value={typed}
               onChange={(e) => setTyped(e.target.value)}
-              placeholder="/absolute/path/to/doc.smdf.json"
+              placeholder={docs === null ? "loading…" : "filter, or /absolute/path.json"}
               className="min-w-0 flex-1 rounded border border-gray-700 bg-gray-950 px-1.5 py-1 text-xs text-gray-200 placeholder:text-gray-600"
             />
-            <button type="submit" className="toolbar-btn" title="Open this document">
+            <button type="submit" className="toolbar-btn" title="Open">
               →
             </button>
           </form>
+
+          <div className="max-h-64 overflow-y-auto">
+            {requested && (
+              <button onClick={() => go(null)} className={rowClass} title="Return to the default project file">
+                ⌂ default document
+              </button>
+            )}
+
+            {shown.map((d) => (
+              <button key={d.path} onClick={() => go(d.path)} className={rowClass} title={d.path}>
+                {d.name}
+                <span className="ml-1 text-[10px] text-gray-600">{d.dir}</span>
+              </button>
+            ))}
+
+            {recents.length > 0 && (
+              <div className="mt-1 border-t border-gray-800 pt-1">
+                <div className="px-1.5 pb-0.5 text-[10px] uppercase tracking-wide text-gray-600">
+                  recent
+                </div>
+                {recents.map((d) => (
+                  <button key={d} onClick={() => go(d)} className={rowClass} title={d}>
+                    {d.split("/").pop()}
+                    <span className="ml-1 text-[10px] text-gray-600">{d}</span>
+                  </button>
+                ))}
+              </div>
+            )}
+
+            {docs !== null && shown.length === 0 && recents.length === 0 && (
+              <div className="px-1.5 py-1 text-[11px] text-gray-500">
+                {filter ? "nothing matches" : "no other documents here"}
+              </div>
+            )}
+          </div>
+
+          {/* The server's view of where documents live. In a container this is
+              /data, and saying so is the difference between a refusal that
+              reads as a bug and one that reads as an instruction. */}
+          {roots.length > 0 && (
+            <div className="mt-1 truncate border-t border-gray-800 pt-1 text-[10px] text-gray-600">
+              paths are as the server sees them: {roots.join(", ")}
+            </div>
+          )}
+          {error && (
+            <div className="mt-1 text-[10px] text-gray-600">
+              this server does not list documents ({error}) — type a path
+            </div>
+          )}
         </div>
       )}
     </span>

package/server/src/components/PresenceChips.tsx

@@ -0,0 +1,77 @@
+"use client";
+
+import { useState } from "react";
+import { colorFor } from "@miadi/stateloom-protocol";
+import { useDesignerStore } from "@/store/useDesignerStore";
+
+/** Enough dots to read "several peers" at a glance; the count carries the rest. */
+const MAX_DOTS = 4;
+
+/**
+ * Who else is on this board. It used to float over the top-right corner as one
+ * pill per peer — which on a busy room meant a dozen chips painted across the
+ * toolbar's own controls, hiding Validate/Generate/RISE behind a colour bar
+ * nobody could dismiss. `pointer-events-none` kept the buttons clickable but
+ * you could no longer see what you were clicking.
+ *
+ * So presence stops floating: it is a toolbar control like any other, laid out
+ * in the flow beside the document identity it describes. Fixed width regardless
+ * of how many peers join — a stack of colour dots and a count — with the full
+ * roster one click away. Nothing can be covered by a room that grows.
+ */
+export default function PresenceChips() {
+  const presence = useDesignerStore((s) => s.presence);
+  const [open, setOpen] = useState(false);
+
+  if (presence.length === 0) return null;
+
+  const byRole = new Map<string, number>();
+  for (const p of presence) byRole.set(p.role, (byRole.get(p.role) ?? 0) + 1);
+  const summary = [...byRole]
+    .map(([role, n]) => (n > 1 ? `${role} ×${n}` : role))
+    .join(" · ");
+
+  return (
+    <span className="relative inline-flex">
+      <button
+        onClick={() => setOpen((v) => !v)}
+        className="toolbar-btn inline-flex items-center gap-1.5"
+        title={`Connected: ${summary}`}
+        aria-expanded={open}
+        aria-label={`${presence.length} connected: ${summary}`}
+      >
+        <span className="flex -space-x-1">
+          {presence.slice(0, MAX_DOTS).map((p) => (
+            <span
+              key={p.clientId}
+              className="inline-block h-2 w-2 rounded-full ring-1 ring-gray-900"
+              style={{ backgroundColor: p.color ?? colorFor(p.clientId) }}
+            />
+          ))}
+        </span>
+        <span className="tabular-nums">{presence.length}</span>
+      </button>
+      {open && (
+        <div className="absolute left-0 top-full z-50 mt-1 max-h-64 w-56 overflow-y-auto rounded border border-gray-700 bg-gray-900 p-2 shadow-lg">
+          <div className="mb-1 text-[10px] uppercase tracking-wide text-gray-500">
+            connected · {summary}
+          </div>
+          {presence.map((p) => (
+            <div
+              key={p.clientId}
+              className="flex items-center gap-1.5 rounded px-1 py-1 text-xs text-gray-300"
+              title={p.clientId}
+            >
+              <span
+                className="inline-block h-2 w-2 shrink-0 rounded-full"
+                style={{ backgroundColor: p.color ?? colorFor(p.clientId) }}
+              />
+              <span className="shrink-0">{p.role}</span>
+              {p.name && <span className="truncate text-gray-500">{p.name}</span>}
+            </div>
+          ))}
+        </div>
+      )}
+    </span>
+  );
+}

package/server/src/components/SocketBridgeProvider.tsx

@@ -7,7 +7,6 @@ import {
 } from "@miadi/stateloom-react";
 import {
   diffDefinition,
-  colorFor,
   type StateMachineDefinition,
 } from "@miadi/stateloom-protocol";
 import { useDesignerStore } from "@/store/useDesignerStore";
@@ -24,9 +23,13 @@ const OUTBOUND_DEBOUNCE_MS = 60;
  * Rendered only once a bridge URL is known — see DesignBridge, which resolves
  * it from the serving process at runtime so a published build carries nobody's
  * URL baked in.
+ *
+ * Transport only — it paints nothing. Presence lands in the store and the
+ * toolbar draws it (PresenceChips); the floating corner dock this used to
+ * render grew one pill per peer and ended up covering the toolbar it hovered
+ * over.
  */
 export default function SocketBridgeProvider({ url }: { url: string }) {
-  const presence = useDesignerStore((s) => s.presence);
   // The requested `?doc=` (step 2): passed through to the file API, which
   // resolves and guards it; the join below keys the room by the RESOLVED path.
   const requested = useRequestedDoc();
@@ -126,24 +129,5 @@ export default function SocketBridgeProvider({ url }: { url: string }) {
     // an arbitrary definition, so the arriving full-def repaints the canvas.
   }, [url, requested]);
 
-  if (presence.length === 0) return null;
-
-  return (
-    // `presence-dock` replaces the raw `top-2 right-4`: with viewport-fit=cover
-    // that corner can sit under a notch or the status bar, so the offset is
-    // measured from the safe-area inset instead. Still pointer-events-none, so
-    // it never competes with the toolbar it floats over.
-    <div className="presence-dock flex gap-1 pointer-events-none">
-      {presence.map((p) => (
-        <span
-          key={p.clientId}
-          title={`${p.role}${p.name ? ` · ${p.name}` : ""}`}
-          className="text-[10px] leading-none px-2 py-1 rounded-full text-white/95 shadow font-medium"
-          style={{ backgroundColor: p.color ?? colorFor(p.clientId) }}
-        >
-          {p.role}
-        </span>
-      ))}
-    </div>
-  );
+  return null;
 }

package/server/src/components/Toolbar.tsx

@@ -10,6 +10,7 @@ import {
 } from "@/lib/exportImage";
 import type { StateDef } from "@/types/definition";
 import DocSwitcher from "./DocSwitcher";
+import PresenceChips from "./PresenceChips";
 import { docQuery, useRequestedDoc } from "@/lib/docParam";
 
 export default function Toolbar() {
@@ -224,6 +225,10 @@ export default function Toolbar() {
           <span className="text-[10px] text-gray-600" title={remoteMessage ?? "No file bound"}>○ no disk</span>
         )}
 
+        {/* Who else is on the board. In the flow, next to the document it
+            describes — it used to float over this toolbar and cover it. */}
+        <PresenceChips />
+
         <div className="flex-1" />
       </div>
 

package/server/src/lib/projectFile.ts

@@ -1,5 +1,5 @@
-import { existsSync, realpathSync } from "fs";
-import { dirname, isAbsolute, resolve, sep } from "path";
+import { existsSync, readdirSync, realpathSync, statSync } from "fs";
+import { basename, dirname, isAbsolute, join, resolve, sep } from "path";
 import { envAlias } from "@miadi/stateloom-protocol";
 
 export function getProjectFilePath(): string {
@@ -61,13 +61,114 @@ export function resolveDocPath(doc: string | null | undefined): DocResolution {
       ? realpathSync(lexical)
       : resolve(realpathSync(dirname(lexical)), lexical.slice(lexical.lastIndexOf(sep) + 1));
   } catch {
-    return { ok: false, error: "doc directory does not exist" };
+    // Almost always a host path handed to a containerised server: the directory
+    // exists where the human is looking and not where the server is.
+    return { ok: false, error: outsideRootsMessage(doc, allowedDocRoots()) };
   }
 
-  for (const root of allowedDocRoots()) {
+  const roots = allowedDocRoots();
+  for (const root of roots) {
     if (anchored === root || anchored.startsWith(root + sep)) {
       return { ok: true, path: anchored };
     }
   }
-  return { ok: false, error: "doc is outside the allowed roots" };
+  return { ok: false, error: outsideRootsMessage(doc, roots) };
+}
+
+/**
+ * A refusal that is true from the READER's side.
+ *
+ * "doc is outside the allowed roots" and "doc directory does not exist" are both
+ * accurate from the server's point of view and both false from the human's: in a
+ * container they are looking straight at the directory, on the host, where it
+ * plainly does exist. What they are missing is that the server sees it somewhere
+ * else. So the message names the roots and, when they differ from the path being
+ * asked for, says what the translation is.
+ */
+function outsideRootsMessage(doc: string, roots: string[]): string {
+  const where = roots.length ? roots.join(", ") : "(no readable root is configured)";
+  const hint =
+    roots.length === 1 && roots[0] === "/data"
+      ? " — this server is in a container, and it sees your mounted directory as /data," +
+        ` so ask for /data/${basename(doc)}`
+      : "";
+  return `${doc} is not under the permitted document root${roots.length === 1 ? "" : "s"} ${where}${hint}`;
+}
+
+export interface DocEntry {
+  /** Absolute path as the SERVER sees it — the value `?doc=` wants. */
+  path: string;
+  /** Basename, for display. */
+  name: string;
+  /** Directory, for display when two documents share a name. */
+  dir: string;
+  size: number;
+  mtime: number;
+}
+
+/**
+ * Every document the allowlist would admit, so the switcher can be a switcher.
+ *
+ * Both the compose file and `.env.docker.example` promised that other documents
+ * in the mounted directory are "reachable from the canvas's document switcher".
+ * That was true of the ALLOWLIST and false of the UI: recents came from this
+ * browser's layout memory, empty on first use, and nothing enumerated the
+ * directory — so switching meant knowing the container sees your folder as
+ * /data and typing the path by hand, every time. (Found in review.)
+ *
+ * Bounded deliberately: depth and count caps, no dotfiles, no node_modules. A
+ * mount pointed at a home directory must not turn a dropdown into a filesystem
+ * crawl.
+ */
+export function listDocuments(limit = 300, maxDepth = 4): { docs: DocEntry[]; truncated: boolean } {
+  const docs: DocEntry[] = [];
+  const seen = new Set<string>();
+  let truncated = false;
+
+  const walk = (dir: string, depth: number): void => {
+    if (docs.length >= limit) {
+      truncated = true;
+      return;
+    }
+    let entries: string[];
+    try {
+      entries = readdirSync(dir);
+    } catch {
+      return; // unreadable directory is not an error, it is just not listed
+    }
+    for (const entry of entries) {
+      if (entry.startsWith(".") || entry === "node_modules") continue;
+      const full = join(dir, entry);
+      let stat;
+      try {
+        stat = statSync(full);
+      } catch {
+        continue; // a broken symlink lists as nothing, not as a crash
+      }
+      if (stat.isDirectory()) {
+        if (depth < maxDepth) walk(full, depth + 1);
+        continue;
+      }
+      if (!entry.endsWith(".json")) continue;
+      if (docs.length >= limit) {
+        truncated = true;
+        return;
+      }
+      if (seen.has(full)) continue;
+      seen.add(full);
+      docs.push({ path: full, name: entry, dir, size: stat.size, mtime: stat.mtimeMs });
+    }
+  };
+
+  for (const root of allowedDocRoots()) walk(root, 0);
+
+  // `.smdf.json` first — the rest are `.json` files the allowlist tolerates but
+  // nobody came here looking for — then most recently touched.
+  docs.sort((a, b) => {
+    const aSmdf = a.name.endsWith(".smdf.json") ? 0 : 1;
+    const bSmdf = b.name.endsWith(".smdf.json") ? 0 : 1;
+    return aSmdf - bSmdf || b.mtime - a.mtime || a.path.localeCompare(b.path);
+  });
+
+  return { docs, truncated };
 }

package/server/stateloom-web.json

@@ -1,5 +1,5 @@
 {
-  "package": "0.1.2",
-  "designer": "0.1.2",
+  "package": "0.1.4",
+  "designer": "0.1.4",
   "next": "16.1.6"
 }