@miadi/stateloom-web 0.1.3 → 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.3",
+  "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/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/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.3",
-  "designer": "0.1.3",
+  "package": "0.1.4",
+  "designer": "0.1.4",
   "next": "16.1.6"
 }