@miadi/stateloom-web 0.2.6 → 0.3.1

package/server/src/components/stage/StageLayer.tsx

@@ -0,0 +1,338 @@
+"use client";
+
+/**
+ * The stage on one board (Spec 83): mounted by each workspace beside its
+ * canvas, told the board's viewport and where its elements are.
+ *
+ * - What the step on stage lights in this drawing is drawn here, and the view
+ *   fits it (after the workspace has centred the step's focus, so the wider
+ *   view wins).
+ * - This drawing's marks: pinned on the board, listed in a panel, read and
+ *   answered in a thread. ✎ turns marking on — a tap marks an element, a drag
+ *   marks an area and what is inside it — and the composer asks what the agent
+ *   should know. Answer on the caption opens the composer on what is lit.
+ * - What the person is looking at goes back to the agents through the stage.
+ *
+ * The sidecar is written through /api/marks; the hub is told after.
+ */
+import { useCallback, useEffect, useMemo, useRef, useState, type RefObject } from "react";
+import { MarkComposer, MarkIcon, MarksIcon, MarkThread, MarksPanel, StageOverlay, type MarkDraft } from "@miadi/stateloom-canvas";
+import {
+  boxesOf,
+  fitToBoxes,
+  formatReview,
+  screenToWorld,
+  type DocKind,
+  type ElementBox,
+  type Mark,
+  type MarkKind,
+  type Viewport,
+} from "@miadi/stateloom-protocol";
+import { useStageContext } from "./StageProvider";
+import { urlParam } from "@/lib/systemParam";
+
+export interface StageLayerProps {
+  /** The drawing this board shows, absolute. Null until the workspace has read it. */
+  docPath: string | null;
+  kind: DocKind;
+  viewport: Viewport;
+  setViewport: (vp: Viewport) => void;
+  boxes: readonly ElementBox[];
+  boardRef: RefObject<HTMLElement | null>;
+  /** The element in hand (`focus=`). */
+  focus?: string | null;
+  /** The machine level on the board: the state whose children are drawn. */
+  level?: string;
+  /**
+   * The step lights something this board cannot see yet — a state on another
+   * level, a sequence shown as a list. The workspace brings it on.
+   */
+  onReveal?: (focuses: readonly string[]) => void;
+}
+
+const quietButton =
+  "flex h-9 min-w-9 items-center justify-center gap-1 rounded-lg border border-gray-700 bg-gray-900/90 px-2 text-sm text-gray-200 shadow-lg backdrop-blur hover:bg-gray-800";
+
+async function postMarks(docPath: string, body: unknown): Promise<{ marks: Mark[]; change: { action: "add" | "reply" | "resolve" | "reopen" | "remove"; id: string } }> {
+  const r = await fetch(`/api/marks?doc=${encodeURIComponent(docPath)}`, {
+    method: "POST",
+    headers: { "content-type": "application/json" },
+    body: JSON.stringify(body),
+  });
+  const data = await r.json().catch(() => ({}));
+  if (!r.ok) throw new Error(data?.error ?? `the marks could not be written (${r.status})`);
+  return data;
+}
+
+export default function StageLayer({ docPath, kind, viewport, setViewport, boxes, boardRef, focus = null, level, onReveal }: StageLayerProps) {
+  const stage = useStageContext();
+  const [marks, setMarks] = useState<Mark[]>([]);
+  const [marking, setMarking] = useState(false);
+  const [draft, setDraft] = useState<(MarkDraft & { listen?: boolean }) | null>(null);
+  const [selected, setSelected] = useState<string | null>(null);
+  const [panel, setPanel] = useState(false);
+  const [busy, setBusy] = useState(false);
+  const [error, setError] = useState<string | null>(null);
+  const [copied, setCopied] = useState(false);
+
+  // ── This drawing's marks ─────────────────────────────────────────────
+  const load = useCallback(() => {
+    if (!docPath) return;
+    fetch(`/api/marks?doc=${encodeURIComponent(docPath)}`, { cache: "no-store" })
+      .then((r) => (r.ok ? r.json() : null))
+      .then((data) => data && Array.isArray(data.marks) && setMarks(data.marks))
+      .catch(() => {});
+  }, [docPath]);
+  useEffect(() => {
+    setMarks([]);
+    setSelected(null);
+    setDraft(null);
+    load();
+    window.addEventListener("focus", load);
+    return () => window.removeEventListener("focus", load);
+  }, [load]);
+  useEffect(
+    () =>
+      stage?.onMarks((e) => {
+        if (docPath && e.docId === docPath && Array.isArray(e.marks)) setMarks(e.marks);
+      }),
+    [stage, docPath],
+  );
+
+  const write = async (body: unknown): Promise<boolean> => {
+    if (!docPath) return false;
+    setBusy(true);
+    setError(null);
+    try {
+      const r = await postMarks(docPath, body);
+      setMarks(r.marks);
+      stage?.sendMarks({ docId: docPath, marks: r.marks, change: r.change });
+      return true;
+    } catch (e) {
+      setError(e instanceof Error ? e.message : String(e));
+      return false;
+    } finally {
+      setBusy(false);
+    }
+  };
+
+  // ── What the step lights here ────────────────────────────────────────
+  const lit = stage?.lit ?? null;
+  const litHere = lit && (!lit.doc || lit.doc === docPath) ? lit : null;
+  const spotlight = litHere?.spotlight;
+  const region = litHere?.region ?? null;
+  const fitted = useRef(-1);
+  const revealed = useRef(-1);
+  const refit = useRef<ReturnType<typeof setTimeout> | null>(null);
+  const litBoxes = useMemo(() => (spotlight?.length ? boxesOf(boxes, spotlight) : []), [boxes, spotlight]);
+  useEffect(() => {
+    if (!litHere || fitted.current === litHere.nonce) return;
+    const targets = [...litBoxes, ...(region ? [region] : [])];
+    if (!targets.length) {
+      // Lit, but not drawn on this board as it stands: ask the workspace once.
+      if (spotlight?.length && revealed.current !== litHere.nonce) {
+        revealed.current = litHere.nonce;
+        onReveal?.(spotlight);
+      }
+      return;
+    }
+    fitted.current = litHere.nonce;
+    const fit = (): void => {
+      const rect = boardRef.current?.getBoundingClientRect();
+      if (!rect?.width) return;
+      // The caption covers the bottom of the board: fit into what it leaves.
+      const caption = document.querySelector(".stage-caption-host .slc-stage-caption")?.getBoundingClientRect();
+      const covered = caption && caption.top < rect.bottom ? Math.max(0, rect.bottom - caption.top + 8) : 0;
+      const height = Math.max(rect.height * 0.4, rect.height - covered);
+      setViewport(fitToBoxes(targets, rect.width, height, { padding: 48, maxScale: 1 }));
+    };
+    fit();
+    // Again after the workspace's own fit or centring has landed. Not cleared
+    // when the board's boxes move under it (a live update arrives just after a
+    // drawing opens) — only when the layer goes.
+    if (refit.current) clearTimeout(refit.current);
+    refit.current = setTimeout(fit, 520);
+  }, [litHere, litBoxes, region, spotlight, boardRef, setViewport, onReveal]);
+  useEffect(() => () => {
+    if (refit.current) clearTimeout(refit.current);
+  }, []);
+
+  // Answer on the caption: a composer on what is lit (or the element in hand).
+  const answered = useRef(stage?.answerNonce ?? 0);
+  useEffect(() => {
+    if (!stage || stage.answerNonce === answered.current) return;
+    answered.current = stage.answerNonce;
+    const elements = spotlight?.length ? [...spotlight] : litHere?.focus ? [litHere.focus] : focus ? [focus] : [];
+    setPanel(false);
+    setSelected(null);
+    setDraft({ elements, region: region ?? undefined, listen: !!stage.listener });
+  }, [stage, spotlight, litHere, focus, region]);
+
+  // ── What the person is looking at ────────────────────────────────────
+  const report = stage?.report;
+  useEffect(() => {
+    if (!report || !docPath) return;
+    const rect = boardRef.current?.getBoundingClientRect();
+    const a = screenToWorld(viewport, { x: 0, y: 0 });
+    const b = rect ? screenToWorld(viewport, { x: rect.width, y: rect.height }) : a;
+    report({
+      doc: docPath,
+      kind,
+      system: urlParam("system") ?? undefined,
+      focus,
+      ...(rect?.width ? { visible: { x: Math.round(a.x), y: Math.round(a.y), width: Math.round(b.x - a.x), height: Math.round(b.y - a.y) } } : {}),
+    });
+  }, [report, docPath, kind, focus, viewport, boardRef]);
+
+  const copy = (): void => {
+    if (!docPath) return;
+    const text = formatReview(stage?.lastReport() ?? null, [{ doc: docPath, marks: marks.filter((m) => m.status !== "resolved") }]);
+    navigator.clipboard?.writeText(text).then(() => {
+      setCopied(true);
+      setTimeout(() => setCopied(false), 2000);
+    });
+  };
+
+  if (!docPath) return null;
+  const waiting = marks.filter((m) => m.status === "open" && m.author.role === "person").length;
+  const questions = marks.filter((m) => m.status === "open" && m.author.role === "agent").length;
+  const selectedMark = marks.find((m) => m.id === selected) ?? null;
+
+  return (
+    <>
+      <StageOverlay
+        viewport={viewport}
+        boxes={boxes}
+        spotlight={spotlight}
+        region={region}
+        marks={marks}
+        selectedMark={selected}
+        onSelectMark={(id) => {
+          setDraft(null);
+          setPanel(false);
+          setSelected((s) => (s === id ? null : id));
+        }}
+        marking={marking}
+        onDraft={(d) => {
+          setMarking(false);
+          setSelected(null);
+          setPanel(false);
+          setDraft(d);
+        }}
+        draft={draft}
+      />
+
+      <div className="stage-board-controls">
+        <button
+          type="button"
+          className={`${quietButton} ${marking ? "!border-amber-400 !text-amber-300" : ""}`}
+          aria-pressed={marking}
+          onClick={() => {
+            setDraft(null);
+            setMarking((m) => !m);
+          }}
+          title={marking ? "Marking: tap an element, or drag around several. Tap ✎ again to stop." : "Mark something for the agent — tap an element or drag around several"}
+        >
+          <MarkIcon />
+          {marking && <span className="text-xs">marking</span>}
+        </button>
+        <button
+          type="button"
+          className={quietButton}
+          aria-expanded={panel}
+          onClick={() => {
+            setDraft(null);
+            setSelected(null);
+            setPanel((p) => !p);
+          }}
+          title="Marks on this drawing"
+        >
+          <MarksIcon />
+          {waiting + questions > 0 && <span className="text-xs text-amber-300">{waiting + questions}</span>}
+        </button>
+      </div>
+
+      {marking && !draft && (
+        <div className="stage-board-hint" role="status">
+          Tap an element, or drag around several, to say something about it.
+        </div>
+      )}
+
+      {(draft || selectedMark || panel) && (
+        <div className="stage-board-card">
+          {draft ? (
+            <MarkComposer
+              key={`${draft.elements.join(",")}|${draft.region ? JSON.stringify(draft.region) : ""}`}
+              elements={draft.elements}
+              region={draft.region}
+              author={stage?.author ?? ""}
+              onAuthorChange={stage?.setAuthor}
+              listener={stage?.listener}
+              listenAtOnce={!!draft.listen}
+              busy={busy}
+              error={error}
+              onCancel={() => {
+                setDraft(null);
+                setError(null);
+              }}
+              onSubmit={async ({ text, kind: markKind, author }: { text: string; kind: MarkKind; author: string }) => {
+                const name = author || "someone";
+                const ok = await write({
+                  action: "add",
+                  mark: { text, kind: markKind, elements: draft.elements, region: draft.region, level, author: { name } },
+                });
+                if (ok) setDraft(null);
+              }}
+            />
+          ) : selectedMark ? (
+            <MarkThread
+              mark={selectedMark}
+              number={marks.indexOf(selectedMark) + 1}
+              listener={stage?.listener}
+              busy={busy}
+              error={error}
+              onClose={() => setSelected(null)}
+              onReply={(text) => void write({ action: "reply", id: selectedMark.id, text, author: { name: stage?.author || "someone" } })}
+              onResolve={() => void write({ action: "resolve", id: selectedMark.id })}
+              onReopen={() => void write({ action: "reopen", id: selectedMark.id })}
+              onRemove={async () => {
+                if (await write({ action: "remove", id: selectedMark.id })) setSelected(null);
+              }}
+            />
+          ) : (
+            <MarksPanel
+              marks={marks}
+              selected={selected}
+              onSelect={(id) => {
+                setPanel(false);
+                setSelected(id);
+              }}
+              onCopy={copy}
+              copied={copied}
+              onClose={() => setPanel(false)}
+            />
+          )}
+        </div>
+      )}
+    </>
+  );
+}
+
+/**
+ * For a board that is not drawn right now (the sequence's list view): when the
+ * step on stage lights something in this drawing — a spotlight or an area, not
+ * a focus, which the list shows by itself — ask for the drawing.
+ */
+export function StageReveal({ docPath, onReveal }: { docPath: string | null; onReveal: () => void }) {
+  const stage = useStageContext();
+  const lit = stage?.lit ?? null;
+  const done = useRef(-1);
+  useEffect(() => {
+    if (!lit || done.current === lit.nonce) return;
+    if (lit.doc && lit.doc !== docPath) return;
+    if (!lit.spotlight?.length && !lit.region) return;
+    done.current = lit.nonce;
+    onReveal();
+  }, [lit, docPath, onReveal]);
+  return null;
+}

package/server/src/components/stage/StageProvider.tsx

@@ -0,0 +1,257 @@
+"use client";
+
+/**
+ * The page's stage (Spec 83): one connection to the stage this designer
+ * presents on, whichever workspace is open.
+ *
+ * It joins `?stage=` (else the server's `STATELOOM_STAGE`, else `default`) and
+ * does what a shown step asks of the page as a whole: open the step's drawing
+ * (inside its system, when it names one) and focus its element — the same
+ * `openInSystem` an agent's `show` uses. What is lit inside the drawing — the
+ * spotlight, the area — is handed to whichever `StageLayer` the open
+ * workspace mounts, because only it knows where its elements are.
+ *
+ * It also holds what every layer shares: the caption and its controls, the
+ * voice the person may turn on, the ears a mark may be spoken into, the name
+ * marks are signed with, and the line back to the agents — what the person is
+ * looking at, and that a drawing's marks changed.
+ */
+import { createContext, useCallback, useContext, useEffect, useMemo, useRef, useState, type ReactNode } from "react";
+import { browserDictation, browserVoice, useStage, type StageShown, type UseStage } from "@miadi/stateloom-react";
+import { StageCaption, type ListenerLike } from "@miadi/stateloom-canvas";
+import { DEFAULT_STAGE, isStageName, type Box, type MarksEnvelope, type StageContext } from "@miadi/stateloom-protocol";
+import { loadRuntimeConfig } from "@/lib/runtimeConfig";
+import { requestedDoc } from "@/lib/docParam";
+import { FOCUS_REQUEST_EVENT, openInSystem, urlParam } from "@/lib/systemParam";
+import CompanionLayer from "./CompanionLayer";
+
+/** What the step on stage lights inside its drawing. `doc` absent: whatever drawing is open. */
+export interface Lit {
+  doc?: string;
+  focus?: string;
+  spotlight?: string[];
+  region?: Box;
+  nonce: number;
+}
+
+/** What a layer reports about the board it sits on. */
+export type BoardReport = Omit<StageContext, "stage" | "at" | "tour" | "who">;
+
+export interface StageValue {
+  stage: string;
+  connected: boolean;
+  lit: Lit | null;
+  author: string;
+  setAuthor: (name: string) => void;
+  listener: ListenerLike | null;
+  /** A layer asks to mark what is lit: moves when the person presses Answer on the caption. */
+  answerNonce: number;
+  report: (board: BoardReport) => void;
+  lastReport: () => StageContext | null;
+  sendMarks: (env: Omit<MarksEnvelope, "origin" | "stage">) => void;
+  onMarks: (cb: (e: MarksEnvelope) => void) => () => void;
+  /** What is on stage now: a live step, or a tour's step with its place. */
+  shown: StageShown | null;
+  /** Play a tour from this page in its own voice — a companion's reply (Spec 84). */
+  present: UseStage["present"];
+  pause: () => void;
+  stop: () => void;
+}
+
+const StageCtx = createContext<StageValue | null>(null);
+
+export function useStageContext(): StageValue | null {
+  return useContext(StageCtx);
+}
+
+const VOICE_KEY = "stateloom.stage.voice";
+const AUTHOR_KEY = "stateloom.author";
+
+function readLocal(key: string): string {
+  try {
+    return window.localStorage.getItem(key) ?? "";
+  } catch {
+    return "";
+  }
+}
+
+function writeLocal(key: string, value: string): void {
+  try {
+    window.localStorage.setItem(key, value);
+  } catch {
+    // Private mode: the choice holds for this page only.
+  }
+}
+
+/** Ask the open workspace to select and centre `focus` on the drawing already open. */
+function requestFocus(focus: string): void {
+  const url = new URL(window.location.href);
+  url.searchParams.set("focus", focus);
+  window.history.replaceState(window.history.state, "", url);
+  window.dispatchEvent(new Event(FOCUS_REQUEST_EVENT));
+}
+
+export default function StageProvider({ children }: { children: ReactNode }) {
+  const [config, setConfig] = useState<{ bridgeUrl: string | null; stage: string; companion: boolean; companionEpisode: string | null }>({
+    bridgeUrl: null,
+    stage: DEFAULT_STAGE,
+    companion: false,
+    companionEpisode: null,
+  });
+  useEffect(() => {
+    let live = true;
+    loadRuntimeConfig().then((c) => {
+      if (!live) return;
+      const asked = urlParam("stage");
+      const stage = isStageName(asked) ? asked : isStageName(c.stage) ? c.stage : DEFAULT_STAGE;
+      setConfig({ bridgeUrl: c.bridgeUrl, stage, companion: c.companion, companionEpisode: c.companionEpisode });
+    });
+    return () => {
+      live = false;
+    };
+  }, []);
+
+  // Read once from this browser. The provider mounts only after the page has
+  // read its URL (never in the server's render), so there is nothing to hydrate.
+  const [voiceOn, setVoiceOn] = useState(() => typeof window !== "undefined" && readLocal(VOICE_KEY) === "1");
+  const [author, setAuthorState] = useState(() => (typeof window !== "undefined" ? readLocal(AUTHOR_KEY) : ""));
+  const voice = useMemo(() => (voiceOn ? browserVoice() : null), [voiceOn]);
+  const listener = useMemo<ListenerLike | null>(() => (typeof window === "undefined" ? null : browserDictation()), []);
+
+  const [lit, setLit] = useState<Lit | null>(null);
+  const marksListeners = useRef(new Set<(e: MarksEnvelope) => void>());
+
+  const show = useCallback((shown: StageShown | null) => {
+    if (!shown) {
+      setLit(null);
+      return;
+    }
+    const { step } = shown;
+    const open = requestedDoc();
+    // A page opened on a drawing keeps it when it only catches up with what the stage held:
+    // the caption says what waits, and ▶ opens it. A step sent now always opens its drawing.
+    if (shown.caught && urlParam("doc")) {
+      setLit({ doc: step.doc, focus: step.focus, spotlight: step.spotlight, region: step.region, nonce: shown.nonce });
+      return;
+    }
+    if (step.doc && step.doc !== open) {
+      openInSystem({ doc: step.doc, system: step.system ?? undefined, focus: step.focus ?? null });
+    } else if (step.focus) {
+      if (step.system && urlParam("system") !== step.system && open) openInSystem({ doc: open, system: step.system, focus: step.focus });
+      else requestFocus(step.focus);
+    }
+    setLit({ doc: step.doc, focus: step.focus, spotlight: step.spotlight, region: step.region, nonce: shown.nonce });
+  }, []);
+
+  const stage = useStage({
+    url: config.bridgeUrl ?? "",
+    stage: config.stage,
+    name: "web-stage",
+    voice,
+    enabled: !!config.bridgeUrl,
+    onShow: show,
+    onMarks: (e) => {
+      for (const cb of [...marksListeners.current]) cb(e);
+    },
+  });
+
+  // What the person is looking at, told to the agents a moment after it settles.
+  const last = useRef<StageContext | null>(null);
+  const timer = useRef<ReturnType<typeof setTimeout> | null>(null);
+  const sendContext = stage.sendContext;
+  const report = useCallback(
+    (board: BoardReport) => {
+      const ctx: StageContext = { ...board, stage: config.stage, who: author || undefined, at: new Date().toISOString() };
+      last.current = ctx;
+      if (timer.current) clearTimeout(timer.current);
+      timer.current = setTimeout(() => sendContext({ ...board, who: author || undefined }), 400);
+    },
+    [config.stage, author, sendContext],
+  );
+  useEffect(() => () => {
+    if (timer.current) clearTimeout(timer.current);
+  }, []);
+  // A tour moving is news too: say it again with the tour's place.
+  useEffect(() => {
+    if (last.current) sendContext({ ...last.current, who: author || undefined });
+  }, [stage.index, stage.playing, stage.tour, sendContext, author]);
+
+  const [answerNonce, setAnswerNonce] = useState(0);
+
+  // How tall the caption stands, for what must sit above it on a phone (the Talk dock).
+  const captionUp = !!stage.shown;
+  useEffect(() => {
+    const root = document.documentElement;
+    const caption = captionUp ? document.querySelector<HTMLElement>(".stage-caption-host .slc-stage-caption") : null;
+    if (!caption || typeof ResizeObserver === "undefined") {
+      root.style.removeProperty("--stage-caption-h");
+      return;
+    }
+    const measure = () => root.style.setProperty("--stage-caption-h", `${Math.ceil(caption.getBoundingClientRect().height) + 12}px`);
+    const watch = new ResizeObserver(measure);
+    watch.observe(caption);
+    measure();
+    return () => {
+      watch.disconnect();
+      root.style.removeProperty("--stage-caption-h");
+    };
+  }, [captionUp]);
+
+  const value = useMemo<StageValue>(
+    () => ({
+      stage: config.stage,
+      connected: stage.status === "connected",
+      lit,
+      author,
+      setAuthor: (name: string) => {
+        setAuthorState(name);
+        writeLocal(AUTHOR_KEY, name);
+      },
+      listener,
+      answerNonce,
+      report,
+      lastReport: () => last.current,
+      sendMarks: stage.sendMarks,
+      onMarks: (cb) => {
+        marksListeners.current.add(cb);
+        return () => {
+          marksListeners.current.delete(cb);
+        };
+      },
+      shown: stage.shown,
+      present: stage.present,
+      pause: stage.pause,
+      stop: stage.stop,
+    }),
+    [config.stage, stage.status, stage.shown, stage.sendMarks, stage.present, stage.pause, stage.stop, lit, author, listener, answerNonce, report],
+  );
+
+  return (
+    <StageCtx.Provider value={value}>
+      {children}
+      {stage.shown && (
+        <div className="stage-caption-host">
+          <StageCaption
+            shown={stage.shown}
+            playing={stage.playing}
+            speaking={stage.speaking}
+            voice={stage.ownVoice ? undefined : voiceOn}
+            onToggleVoice={() => {
+              const next = !voiceOn;
+              setVoiceOn(next);
+              writeLocal(VOICE_KEY, next ? "1" : "0");
+            }}
+            onPlay={stage.play}
+            onPause={stage.pause}
+            onNext={stage.next}
+            onPrev={stage.prev}
+            onGoto={stage.goto}
+            onClose={stage.dismiss}
+            onAnswer={() => setAnswerNonce((n) => n + 1)}
+          />
+        </div>
+      )}
+      {config.companion && <CompanionLayer stage={value} defaultEpisode={config.companionEpisode} />}
+    </StageCtx.Provider>
+  );
+}

package/server/src/lib/projectFile.ts

@@ -1,6 +1,6 @@
 import { closeSync, constants, lstatSync, openSync, readdirSync, readlinkSync, realpathSync, statSync, writeSync } from "fs";
 import { basename, dirname, isAbsolute, join, resolve, sep } from "path";
-import { envAlias } from "@miadi/stateloom-protocol";
+import { envAlias, isLoomSidecar } from "@miadi/stateloom-protocol";
 
 export function getProjectFilePath(): string {
   return resolve(envAlias("PROJECT_FILE") ?? "./statemachine.smdf.json");
@@ -262,6 +262,8 @@ export function listDocuments(limit = 300, maxDepth = 4): { docs: DocEntry[]; tr
         continue;
       }
       if (!entry.endsWith(".json") || !real.endsWith(".json")) continue;
+      // A drawing's marks and a tour are the loom's, but they are not drawings (Spec 83).
+      if (isLoomSidecar(entry)) continue;
       if (docs.length >= limit) {
         truncated = true;
         return;
@@ -298,7 +300,7 @@ export function listDocuments(limit = 300, maxDepth = 4): { docs: DocEntry[]; tr
         continue; // no diagrams/ folder: nothing of this episode is admitted
       }
       for (const file of files) {
-        if (file.startsWith(".") || !file.endsWith(".json")) continue;
+        if (file.startsWith(".") || !file.endsWith(".json") || isLoomSidecar(file)) continue;
         const full = join(dir, file);
         let real: string;
         let stat;

package/server/src/lib/runtimeConfig.ts

@@ -17,6 +17,12 @@
 export interface RuntimeConfig {
   bridgeUrl: string | null;
   projectFile: string | null;
+  /** The stage agents present on (Spec 83), when the server names one. */
+  stage: string | null;
+  /** A companion answers behind `/api/companion` (Spec 84). */
+  companion: boolean;
+  /** The episode the Talk dock speaks in when the page names none. */
+  companionEpisode: string | null;
 }
 
 /**
@@ -47,12 +53,15 @@ export function loadRuntimeConfig(): Promise<RuntimeConfig> {
           // build — it just has nothing to add.
           bridgeUrl: body.bridgeUrl || fallback,
           projectFile: body.projectFile ?? null,
+          stage: body.stage ?? null,
+          companion: body.companion === true,
+          companionEpisode: body.companionEpisode ?? null,
         };
       }
     } catch {
       // Older server, or none reachable: fall back to whatever the build knew.
     }
-    return { bridgeUrl: fallback, projectFile: null };
+    return { bridgeUrl: fallback, projectFile: null, stage: null, companion: false, companionEpisode: null };
   })();
   return pending;
 }

package/server/stateloom-web.json

@@ -1,5 +1,5 @@
 {
-  "package": "0.2.6",
-  "designer": "0.2.6",
+  "package": "0.3.1",
+  "designer": "0.3.1",
   "next": "16.1.6"
 }