@miadi/stateloom-web 0.1.0 → 0.1.2

package/server/src/components/DocSwitcher.tsx

@@ -0,0 +1,84 @@
+"use client";
+
+import { useState } from "react";
+import { navigateToDoc, useRequestedDoc } from "@/lib/docParam";
+import { rememberedDocs } from "@/lib/layoutMemory";
+
+/**
+ * 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.
+ */
+export default function DocSwitcher() {
+  const requested = useRequestedDoc();
+  const [open, setOpen] = useState(false);
+  const [typed, setTyped] = useState("");
+
+  const go = (doc: string | null) => {
+    setOpen(false);
+    setTyped("");
+    navigateToDoc(doc);
+  };
+
+  const recents = open
+    ? rememberedDocs().filter((d) => d.startsWith("/") && d !== requested)
+    : [];
+
+  return (
+    <span className="relative inline-flex">
+      <button
+        onClick={() => setOpen((v) => !v)}
+        className="toolbar-btn"
+        title={requested ? `Document: ${requested}` : "Switch document"}
+      >
+        ⇄
+      </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="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>
+          ))}
+          <form
+            onSubmit={(e) => {
+              e.preventDefault();
+              if (typed.trim()) go(typed.trim());
+            }}
+            className="mt-1 flex gap-1"
+          >
+            <input
+              value={typed}
+              onChange={(e) => setTyped(e.target.value)}
+              placeholder="/absolute/path/to/doc.smdf.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>
+          </form>
+        </div>
+      )}
+    </span>
+  );
+}

package/server/src/components/SettingsPanel.tsx

@@ -55,11 +55,13 @@ export default function SettingsPanel() {
         <span className="text-xs text-gray-500">Context Class</span>
         <input
           className="w-full bg-gray-800 border border-gray-700 rounded px-2 py-1 text-xs text-gray-200"
-          value={context?.className ?? ""}
+          value={context?.class ?? ""}
           placeholder="e.g. MyStateMachineContext"
           onChange={(e) =>
             updateSettings({
-              context: { ...context, className: e.target.value || undefined },
+              // `class`, not `className`: the generator names the context from
+              // `settings.context?.class`, and nothing has ever read the other.
+              context: { ...context, class: e.target.value || undefined },
             })
           }
         />
@@ -97,15 +99,18 @@ export default function SettingsPanel() {
       <h4 className="text-xs font-semibold text-gray-500">Object References</h4>
       <textarea
         className="w-full bg-gray-800 border border-gray-700 rounded px-2 py-1 text-xs text-gray-200 h-12 font-mono"
-        value={(settings.objects ?? []).map((o) => `${o.name}: ${o.type}`).join("\n")}
-        placeholder="name: type (one per line)"
+        value={(settings.objects ?? []).map((o) => `${o.instance}: ${o.class}`).join("\n")}
+        placeholder="instance: Class (one per line)"
         onChange={(e) => {
+          // `instance: Class` — the pair the generator constructs the context
+          // with. Written as `{ name, type }` until now, which is a shape
+          // `codegen.ts` has never read.
           const objects = e.target.value
             .split("\n")
             .filter((l) => l.includes(":"))
             .map((l) => {
-              const [name, type] = l.split(":").map((s) => s.trim());
-              return { name, type };
+              const [instance, cls] = l.split(":").map((s) => s.trim());
+              return { instance, class: cls };
             });
           updateSettings({ objects });
         }}

package/server/src/components/SocketBridgeProvider.tsx

@@ -11,6 +11,7 @@ import {
   type StateMachineDefinition,
 } from "@miadi/stateloom-protocol";
 import { useDesignerStore } from "@/store/useDesignerStore";
+import { docQuery, useRequestedDoc } from "@/lib/docParam";
 
 const OUTBOUND_DEBOUNCE_MS = 60;
 
@@ -26,6 +27,9 @@ const OUTBOUND_DEBOUNCE_MS = 60;
  */
 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();
 
   useEffect(() => {
     if (!url) return;
@@ -42,7 +46,7 @@ export default function SocketBridgeProvider({ url }: { url: string }) {
       // Learn the docId (the resolved project-file path) from the file API.
       let docId = "";
       try {
-        const r = await fetch("/api/file", { cache: "no-store" });
+        const r = await fetch(`/api/file${docQuery(requested)}`, { cache: "no-store" });
         if (r.ok) docId = (await r.json())?.path ?? "";
       } catch {
         // Connect anyway; the hub keys the doc by whatever id we send.
@@ -115,9 +119,12 @@ export default function SocketBridgeProvider({ url }: { url: string }) {
       if (unsub) unsub();
       if (session) session.disconnect();
     };
-    // Re-run when the URL arrives: DesignBridge resolves it asynchronously from
-    // /api/config, so the first render can legitimately have a different value.
-  }, [url]);
+    // Re-run when the URL arrives (DesignBridge resolves it asynchronously from
+    // /api/config) AND when the requested document changes (step 3): the
+    // cleanup disconnects the old session, the new run joins the new room —
+    // switching needs no reload. applyRemote already rebuilds everything from
+    // an arbitrary definition, so the arriving full-def repaints the canvas.
+  }, [url, requested]);
 
   if (presence.length === 0) return null;
 

package/server/src/components/Toolbar.tsx

@@ -9,6 +9,8 @@ import {
   type ExportFormat,
 } from "@/lib/exportImage";
 import type { StateDef } from "@/types/definition";
+import DocSwitcher from "./DocSwitcher";
+import { docQuery, useRequestedDoc } from "@/lib/docParam";
 
 export default function Toolbar() {
   const definition = useDesignerStore((s) => s.definition);
@@ -36,6 +38,11 @@ export default function Toolbar() {
   const setRemoteMtime = useDesignerStore((s) => s.setRemoteMtime);
   const applyRemote = useDesignerStore((s) => s.applyRemote);
 
+  // Save and reload must follow the SAME document the page is viewing —
+  // without this, 💾 on a switched document would silently write the default
+  // file (the exact mismatch the allowlist exists to prevent).
+  const requested = useRequestedDoc();
+
   const fileInputRef = useRef<HTMLInputElement>(null);
   const [addingState, setAddingState] = useState(false);
   const [newStateName, setNewStateName] = useState("");
@@ -63,7 +70,7 @@ export default function Toolbar() {
     const json = exportJson();
     setSaving(true);
     try {
-      const r = await fetch("/api/file", {
+      const r = await fetch(`/api/file${docQuery(requested)}`, {
         method: "PUT",
         headers: { "Content-Type": "application/json" },
         body: JSON.stringify({ content: json }),
@@ -115,7 +122,7 @@ export default function Toolbar() {
 
   const handleReloadFromDisk = async () => {
     try {
-      const r = await fetch("/api/file", { cache: "no-store" });
+      const r = await fetch(`/api/file${docQuery(requested)}`, { cache: "no-store" });
       if (!r.ok) {
         setRemoteStatus("error", "Reload failed");
         return;
@@ -198,11 +205,12 @@ export default function Toolbar() {
           className="hidden"
         />
 
-        {/* File name + bridge status */}
+        {/* File name + document switcher + bridge status */}
         <span className="text-xs text-gray-400 mr-1 truncate max-w-[50vw] md:max-w-none">
           {fileName ?? "untitled.smdf.json"}
           {dirty && <span className="text-yellow-500 ml-0.5">●</span>}
         </span>
+        <DocSwitcher />
         {remoteStatus === "synced" && (
           <span className="text-[10px] text-emerald-500" title="In sync with disk">⌁ synced</span>
         )}

package/server/src/lib/docParam.ts

@@ -0,0 +1,51 @@
+"use client";
+
+import { useEffect, useState } from "react";
+
+/**
+ * The one client-side source of the requested document (chart steps 2/3/6 of
+ * chart_1785683010290): the `?doc=` URL parameter. The browser only ever
+ * PASSES the request through — resolution and the root allowlist live on the
+ * server (lib/projectFile.ts), and the browser learns the resolved path from
+ * the API response exactly as before. No parameter → the default document,
+ * byte-identical to the old behavior.
+ */
+
+const DOC_CHANGE_EVENT = "stateloom:doc-change";
+
+export function requestedDoc(): string | null {
+  if (typeof window === "undefined") return null;
+  return new URLSearchParams(window.location.search).get("doc");
+}
+
+/** Query-string tail for API calls: "?doc=…" or "". */
+export function docQuery(doc: string | null): string {
+  return doc ? `?doc=${encodeURIComponent(doc)}` : "";
+}
+
+/** Switch documents without a reload (step 6): rewrite the URL, tell the
+ *  providers. History gets an entry so back/forward walk documents too. */
+export function navigateToDoc(doc: string | null): void {
+  const url = new URL(window.location.href);
+  if (doc) url.searchParams.set("doc", doc);
+  else url.searchParams.delete("doc");
+  window.history.pushState({}, "", url);
+  window.dispatchEvent(new Event(DOC_CHANGE_EVENT));
+}
+
+/** The requested doc as reactive state: updates on picker navigation and on
+ *  back/forward. Server render sees null; the first client effect corrects. */
+export function useRequestedDoc(): string | null {
+  const [doc, setDoc] = useState<string | null>(null);
+  useEffect(() => {
+    const update = () => setDoc(requestedDoc());
+    update();
+    window.addEventListener("popstate", update);
+    window.addEventListener(DOC_CHANGE_EVENT, update);
+    return () => {
+      window.removeEventListener("popstate", update);
+      window.removeEventListener(DOC_CHANGE_EVENT, update);
+    };
+  }, []);
+  return doc;
+}

package/server/src/lib/layoutMemory.ts

@@ -36,6 +36,21 @@ export interface LayoutMemory {
   viewport: Viewport;
 }
 
+/** Documents this browser holds layout memory for — the picker's recents
+ *  (chart_1785683062725: presentation over state that already exists). */
+export function rememberedDocs(): string[] {
+  try {
+    const docs: string[] = [];
+    for (let i = 0; i < window.localStorage.length; i++) {
+      const k = window.localStorage.key(i);
+      if (k?.startsWith(KEY_PREFIX)) docs.push(k.slice(KEY_PREFIX.length));
+    }
+    return docs.sort();
+  } catch {
+    return [];
+  }
+}
+
 export function memoryKey(docId: string): string {
   return `${KEY_PREFIX}${docId}`;
 }
@@ -108,10 +123,13 @@ export function writeMemory(
   }
 }
 
-/** The document this browser is remembering for: the resolved project path. */
+/** The document this browser is remembering for: the resolved project path.
+ *  The requested `?doc=` rides along (step 2) so memory keys follow the
+ *  document the page actually asked for, not always the default. */
 async function resolveDocId(): Promise<string> {
   try {
-    const r = await fetch("/api/file", { cache: "no-store" });
+    const { requestedDoc, docQuery } = await import("./docParam");
+    const r = await fetch(`/api/file${docQuery(requestedDoc())}`, { cache: "no-store" });
     if (r.ok) {
       const path = (await r.json())?.path;
       if (typeof path === "string" && path.length > 0) return path;

package/server/src/lib/projectFile.ts

@@ -1,6 +1,73 @@
-import { resolve } from "path";
+import { existsSync, realpathSync } from "fs";
+import { dirname, isAbsolute, resolve, sep } from "path";
 import { envAlias } from "@miadi/stateloom-protocol";
 
 export function getProjectFilePath(): string {
   return resolve(envAlias("PROJECT_FILE") ?? "./statemachine.smdf.json");
 }
+
+/**
+ * Optional-document resolution for the file API (chart chart_1785683022927).
+ *
+ * The guard is not deferrable and ships in the same change as the parameter:
+ * the canvas binds beyond loopback and PUT /api/file writes to disk, so an
+ * unconstrained path parameter would be arbitrary file write across the
+ * tailnet. A `doc` is admitted only when it is an absolute `.json` path whose
+ * real location sits under an allowed root.
+ *
+ * Roots come from STATELOOM_DOC_ROOTS (SMCRAFT_ twin honored), colon-
+ * separated absolute paths. Unset, the allowlist is exactly the directory of
+ * the default project file — the pre-parameter surface, unchanged.
+ */
+export function allowedDocRoots(): string[] {
+  const raw = envAlias("DOC_ROOTS");
+  const roots = raw
+    ? raw.split(":").map((r) => r.trim()).filter(Boolean)
+    : [dirname(getProjectFilePath())];
+  const real: string[] = [];
+  for (const root of roots) {
+    try {
+      real.push(realpathSync(resolve(root)));
+    } catch {
+      // A configured root that does not exist admits nothing — skipped, not fatal.
+    }
+  }
+  return real;
+}
+
+export type DocResolution =
+  | { ok: true; path: string }
+  | { ok: false; error: string };
+
+/** Resolve an optional `doc` request parameter to an admitted absolute path.
+ *  No doc → the default project file, byte-identical to the old behavior. */
+export function resolveDocPath(doc: string | null | undefined): DocResolution {
+  if (!doc) return { ok: true, path: getProjectFilePath() };
+
+  if (!isAbsolute(doc)) {
+    return { ok: false, error: "doc must be an absolute path" };
+  }
+  if (!doc.endsWith(".json")) {
+    return { ok: false, error: "doc must name a .json document" };
+  }
+
+  const lexical = resolve(doc);
+  // Realpath the file itself when it exists (GET/PUT of a known doc), else its
+  // parent (PUT may create the file) — symlinks cannot smuggle a path outside
+  // the allowlist either way. A doc whose parent does not exist is refused.
+  let anchored: string;
+  try {
+    anchored = existsSync(lexical)
+      ? realpathSync(lexical)
+      : resolve(realpathSync(dirname(lexical)), lexical.slice(lexical.lastIndexOf(sep) + 1));
+  } catch {
+    return { ok: false, error: "doc directory does not exist" };
+  }
+
+  for (const root of allowedDocRoots()) {
+    if (anchored === root || anchored.startsWith(root + sep)) {
+      return { ok: true, path: anchored };
+    }
+  }
+  return { ok: false, error: "doc is outside the allowed roots" };
+}

package/server/src/types/definition.ts

@@ -10,8 +10,11 @@ export interface ObjectRef {
 }
 
 export interface ContextConfig {
+  /** The generated context's class name — what `ts/src/codegen.ts` reads. */
   class?: string;
   instance?: string;
+  /** The designer's own extra: a base the generated context extends. */
+  baseClass?: string;
 }
 
 export interface SettingsModel {
@@ -19,8 +22,15 @@ export interface SettingsModel {
   name?: string;
   description?: string;
   asynchronous: boolean;
-  objects?: { name: string; type: string }[];
-  context?: { className?: string; baseClass?: string };
+  /**
+   * Objects the generated context is constructed with. `ObjectRef` is what
+   * `ts/src/codegen.ts` actually reads (`obj.instance`, `obj.class`); the
+   * `{ name, type }` pair this field used to carry was a shape no generator
+   * could consume, so an "Object References" line typed into the designer was
+   * silently dropped on the way to code.
+   */
+  objects?: ObjectRef[];
+  context?: ContextConfig;
   imports?: string[];
   using?: string[];
   targetLanguage?: string;

package/server/stateloom-web.json

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