@unoverse-platform/studio 0.1.4 → 0.1.6

package/screens/SourceView.tsx

@@ -0,0 +1,784 @@
+/**
+ * THE EDITOR: the files behind the definition on screen, with the familiar affordances.
+ *
+ * Local Studio is where a developer works, so this is an editor rather than a viewer:
+ * tabs with a dirty marker, save on Cmd+S, find on Cmd+F, undo history, folding, and
+ * diagnostics in the gutter beside the line that caused them.
+ *
+ * ONE LINTER, and it is not in here. The squiggles come from the host
+ * (`/local/lint/draft`), which hands the developer's UNSAVED text to the shared rule
+ * library as an overlay. So a squiggle is the same rule that will block a save, block a
+ * publish, and fail CI. Nothing in this file decides whether anything is valid.
+ *
+ * IT RENDERS NOTHING WITHOUT THE HOST CAPABILITY. `hasSourceAccess` is false on the Canvas
+ * host, whose universe serves definitions and not the files behind them. A shared screen
+ * must never branch on which app it runs in, so the host answers instead (the same seam
+ * `hasAuth` uses).
+ *
+ * Installed assets open read-only. An edit to one is invisible to every other machine and
+ * lost on the next install, and the design system is what keeps the token contract stable.
+ * The verdict is the host's, never a rule reimplemented here.
+ *
+ * See docs/architecture/LOCAL_STUDIO.md §Authoring in Studio.
+ */
+import { useCallback, useEffect, useMemo, useRef, useState } from "react";
+import { Compartment, EditorState } from "@codemirror/state";
+import { EditorView, keymap, lineNumbers, highlightActiveLine, highlightActiveLineGutter } from "@codemirror/view";
+import { defaultKeymap, history, historyKeymap, indentWithTab } from "@codemirror/commands";
+// NOT `defaultHighlightStyle`: it is tuned for a LIGHT background, and over the dark theme
+// it won the cascade for property names, rendering them dark blue on near-black. The dark
+// theme's OWN highlight style is applied instead, explicitly, because dropping the light
+// one on its own left every token the same colour.
+import { bracketMatching, foldGutter, foldKeymap, indentUnit, syntaxHighlighting } from "@codemirror/language";
+import { autocompletion, closeBrackets, closeBracketsKeymap, completionKeymap } from "@codemirror/autocomplete";
+import { linter, lintGutter, lintKeymap, type Diagnostic } from "@codemirror/lint";
+import { search, searchKeymap, highlightSelectionMatches } from "@codemirror/search";
+import { json } from "@codemirror/lang-json";
+import { yaml } from "@codemirror/lang-yaml";
+import { markdown } from "@codemirror/lang-markdown";
+import { javascript } from "@codemirror/lang-javascript";
+import { oneDark, oneDarkHighlightStyle } from "@codemirror/theme-one-dark";
+import { authedFetch, hasSourceAccess } from "studio-host";
+import { hideSchemaLine, unoverseCompletion, type Vocabulary } from "./source/completion";
+import { parseDocument } from "yaml";
+import { FileTree, stateOf, type SourceFile } from "./source/FileTree";
+import { locateSubtree, nodeRanges, pathAtOffset, stampPaths } from "./source/inspect";
+import { clearHighlight, highlightRendered } from "./source/highlight";
+import { buildSourceMap, deepElementFromPoint, stampedAncestor } from "./source/picker";
+
+export type { SourceFile };
+
+/** A finding, exactly as the shared rule library reports it. */
+export interface LintFinding {
+  level?: string;
+  line?: number;
+  msg?: string;
+}
+
+function languageFor(rel: string) {
+  if (/\.ya?ml$/.test(rel)) return [yaml()];
+  if (/\.jsonc?$/.test(rel)) return [json()];
+  if (/\.md$/.test(rel)) return [markdown()];
+  if (/\.m?js$/.test(rel)) return [javascript()];
+  return [];
+}
+
+function readOnlyNote(reason?: string): string {
+  if (reason === "installed") return "installed, read-only";
+  if (reason === "outside-project") return "outside project, read-only";
+  return "read-only";
+}
+
+/** `layouts/course-detail.yaml` reads as its filename, with the folder as the quiet part. */
+function splitRel(rel: string): { dir: string; name: string } {
+  const i = rel.lastIndexOf("/");
+  return i === -1 ? { dir: "", name: rel } : { dir: rel.slice(0, i + 1), name: rel.slice(i + 1) };
+}
+
+export function SourceView({
+  uri,
+  path,
+  accent,
+  layoutOrder,
+  activeState,
+  onSaved,
+  onPickState,
+}: {
+  uri?: string;
+  path?: string;
+  accent?: string;
+  /** The component's faces, in declared order, so layouts list in that order. */
+  layoutOrder?: string[];
+  /** The face currently on the preview. Its layout file is the one opened. */
+  activeState?: string;
+  /** Fired after a save the host accepted, so the preview can refresh itself. */
+  onSaved?: () => void;
+  /** Opening a layout switches the preview to that face. */
+  onPickState?: (state: string) => void;
+}) {
+  const [files, setFiles] = useState<SourceFile[]>([]);
+  const [active, setActive] = useState<SourceFile | null>(null);
+  const [loaded, setLoaded] = useState("");
+  const [draft, setDraft] = useState("");
+  const [error, setError] = useState<string | null>(null);
+  const [saving, setSaving] = useState(false);
+  const [problems, setProblems] = useState<LintFinding[]>([]);
+  const [savedAt, setSavedAt] = useState<number | null>(null);
+  const [host, setHost] = useState<HTMLDivElement | null>(null);
+  const [vocab, setVocab] = useState<Vocabulary | null>(null);
+  /** The composed tree the renderer received, carrying each node's `$id`. */
+  const [composedRoot, setComposedRoot] = useState<unknown>(null);
+  /** How many elements the cursor's node rendered. Null when there is nothing to say. */
+  const [matches, setMatches] = useState<number | null>(null);
+  const viewRef = useRef<EditorView | null>(null);
+  /** This pane, so the picker can tell its own chrome from the preview. */
+  const rootRef = useRef<HTMLDivElement | null>(null);
+  /** The last view the editor followed, so it follows a CHANGE rather than every render. */
+  const syncedState = useRef<string | undefined>(undefined);
+  const dirty = draft !== loaded;
+  /**
+   * The vocabulary, read through a ref by the completion source.
+   *
+   * The editor is built once per file and its extensions close over whatever exists at that
+   * moment. Reading `vocab` directly meant an editor built before `/local/vocabulary`
+   * answered captured null and offered NOTHING for the life of that file.
+   */
+  const vocabRef = useRef<Vocabulary | null>(null);
+  useEffect(() => {
+    vocabRef.current = vocab;
+  }, [vocab]);
+  /** Armed by the header button: hover the preview, click to land on the line. */
+  const [picking, setPicking] = useState(false);
+  /** The closed primitive set, which is what tells a node apart from a prop. */
+  const primitives = useMemo(() => new Set(vocab?.primitives ?? []), [vocab]);
+
+  const target = uri ? `uri=${encodeURIComponent(uri)}` : path ? `path=${encodeURIComponent(path)}` : null;
+
+  /**
+   * The composed tree, stamped with the same `$id`s the renderer drew. Re-read after every
+   * save, because the tree it describes has just changed.
+   */
+  useEffect(() => {
+    if (!uri) return;
+    let live = true;
+    authedFetch(`/local/definition?uri=${encodeURIComponent(uri)}`)
+      .then((r) => r.json())
+      .then((d) => {
+        if (!live) return;
+        const root = (d as { root?: unknown }).root;
+        stampPaths(root, "root");
+        setComposedRoot(root ?? null);
+      })
+      .catch(() => live && setComposedRoot(null));
+    return () => {
+      live = false;
+    };
+  }, [uri, savedAt]);
+
+  /**
+   * A CHANGED VIEW INVALIDATES THE BOX.
+   *
+   * The overlay is drawn from an element's rect at one instant. Switch face or step and
+   * that element is re-rendered, moved, or gone, leaving a box sitting over whatever now
+   * occupies the space, which is worse than showing nothing. Clearing on a view change
+   * costs one click to ask again.
+   */
+  useEffect(() => {
+    clearHighlight();
+    setMatches(null);
+  }, [activeState, savedAt]);
+
+  // The boxes are absolutely positioned, so they go stale the moment anything moves.
+  useEffect(() => {
+    const drop = () => {
+      clearHighlight();
+      setMatches(null);
+    };
+    window.addEventListener("resize", drop);
+    window.addEventListener("scroll", drop, true);
+    return () => {
+      window.removeEventListener("resize", drop);
+      window.removeEventListener("scroll", drop, true);
+      clearHighlight();
+    };
+  }, []);
+
+  // The closed vocabulary, once. It changes only when the project's tokens do.
+  useEffect(() => {
+    if (!hasSourceAccess) return;
+    let live = true;
+    authedFetch("/local/vocabulary")
+      .then((r) => r.json())
+      .then((v) => live && setVocab(v))
+      .catch(() => {
+        /* completion is an affordance; the editor works without it */
+      });
+    return () => {
+      live = false;
+    };
+  }, []);
+
+  useEffect(() => {
+    if (!hasSourceAccess || !target) return;
+    let live = true;
+    setError(null);
+    authedFetch(`/local/source?${target}`)
+      .then((r) => r.json())
+      .then((d) => {
+        if (!live) return;
+        const list: SourceFile[] = d.files ?? [];
+        setFiles(list);
+        setActive((prev) => list.find((f) => f.path === prev?.path) ?? list[0] ?? null);
+        if (!list.length) setError(d.error ?? "no source files found");
+      })
+      .catch((e) => live && setError(String(e?.message ?? e)));
+    return () => {
+      live = false;
+    };
+  }, [target]);
+
+  useEffect(() => {
+    setProblems([]);
+    setSavedAt(null);
+    if (!active) {
+      setLoaded("");
+      setDraft("");
+      return;
+    }
+    let live = true;
+    authedFetch(`/local/source/file?path=${encodeURIComponent(active.path)}`)
+      .then((r) => r.json())
+      .then((d) => {
+        if (!live) return;
+        setLoaded(d.text ?? "");
+        setDraft(d.text ?? "");
+      })
+      .catch((e) => live && setError(String(e?.message ?? e)));
+    return () => {
+      live = false;
+    };
+  }, [active]);
+
+  /**
+   * DIAGNOSTICS from the one linter, over the wire.
+   *
+   * CodeMirror debounces this for us and cancels in flight work when typing resumes. A
+   * finding the library reports without a line (structural rules report the file, not the
+   * position) is anchored to line 1 and is also listed in the problems strip, so it is
+   * never invisible.
+   */
+  const lintSource = useCallback(
+    async (view: EditorView): Promise<Diagnostic[]> => {
+      const file = active;
+      if (!file) return [];
+      const text = view.state.doc.toString();
+      try {
+        const res = await authedFetch("/local/lint/draft", {
+          method: "POST",
+          headers: { "content-type": "application/json" },
+          body: JSON.stringify({ path: file.path, text }),
+        });
+        const d = await res.json();
+        const findings: LintFinding[] = d.findings ?? [];
+        setProblems(findings);
+        return findings.map((f) => {
+          const line = view.state.doc.line(Math.min(Math.max(f.line ?? 1, 1), view.state.doc.lines));
+          return {
+            from: line.from,
+            to: line.to,
+            severity: f.level === "error" ? "error" : f.level === "warn" ? "warning" : "info",
+            message: f.msg ?? "",
+          } as Diagnostic;
+        });
+      } catch {
+        return [];
+      }
+    },
+    [active],
+  );
+
+  // The lint source closes over the active file, so it is swapped through a compartment
+  // rather than by rebuilding the editor, which would cost the cursor on every file load.
+  const lintCompartment = useMemo(() => new Compartment(), []);
+  useEffect(() => {
+    viewRef.current?.dispatch({
+      effects: lintCompartment.reconfigure(linter(lintSource, { delay: 400 })),
+    });
+  }, [lintSource, lintCompartment]);
+
+  const saveRef = useRef<() => void>(() => {});
+
+  useEffect(() => {
+    if (!host || !active) return;
+    const editable = active.writable;
+    const view = new EditorView({
+      parent: host,
+      state: EditorState.create({
+        doc: loaded,
+        extensions: [
+          lineNumbers(),
+          foldGutter(),
+          lintGutter(),
+          highlightActiveLine(),
+          highlightActiveLineGutter(),
+          highlightSelectionMatches(),
+          bracketMatching(),
+          closeBrackets(),
+          indentUnit.of("  "),
+          history(),
+          search({ top: true }),
+          hideSchemaLine,
+          ...languageFor(active.rel),
+          oneDarkHighlightStyle ? syntaxHighlighting(oneDarkHighlightStyle) : [],
+          autocompletion({ override: [unoverseCompletion(() => vocabRef.current)], activateOnTyping: true }),
+          lintCompartment.of(linter(lintSource, { delay: 400 })),
+          keymap.of([
+            // Save first, so it wins over any default binding on the same chord.
+            { key: "Mod-s", preventDefault: true, run: () => (saveRef.current(), true) },
+            ...closeBracketsKeymap,
+            ...completionKeymap,
+            ...searchKeymap,
+            ...lintKeymap,
+            ...foldKeymap,
+            ...historyKeymap,
+            ...defaultKeymap,
+            indentWithTab,
+          ]),
+          EditorState.readOnly.of(!editable),
+          EditorView.editable.of(editable),
+          EditorView.updateListener.of((u) => {
+            if (u.docChanged) setDraft(u.state.doc.toString());
+            // The cursor moving is what asks "what is this?", so inspect on selection too.
+            if (u.docChanged || u.selectionSet) inspectAt(u.state.doc.toString(), u.state.selection.main.head);
+          }),
+          // WRAP. Definitions carry prose in `default:` values (a course description, a
+          // markdown body), and truncating those at the pane edge hides the thing being
+          // edited. Wrapping also stops a long line widening the pane.
+          EditorView.lineWrapping,
+          EditorView.theme(
+            {
+              "&": { fontSize: "12px", height: "100%" },
+              ".cm-scroller": { overflow: "auto", fontFamily: "ui-monospace, SFMono-Regular, Menlo, monospace", lineHeight: "1.45" },
+              ".cm-gutters": { fontSize: "11px", background: "transparent", border: "none" },
+              ".cm-content": { paddingBottom: "40vh" },
+              // A wrapped continuation lines up under the text, not under the gutter.
+              ".cm-line": { paddingLeft: "2px" },
+
+              /**
+               * THE COMPLETION POPUP, on the dark editor.
+               *
+               * CodeMirror styles the tooltip from its base theme, and the light variant
+               * put near-white text on white: every option except the selected one was
+               * unreadable. The `dark` flag below is half the fix (it selects the dark
+               * base styles); these rules are the other half, because the popup carries
+               * three kinds of text and each needs its own weight.
+               */
+              ".cm-tooltip.cm-tooltip-autocomplete": {
+                background: "#1f262f",
+                border: "1px solid #384151",
+                borderRadius: "4px",
+                boxShadow: "0 8px 24px rgba(0,0,0,.45)",
+              },
+              ".cm-tooltip.cm-tooltip-autocomplete > ul": {
+                fontFamily: "ui-monospace, SFMono-Regular, Menlo, monospace",
+                fontSize: "12px",
+                maxHeight: "16em",
+              },
+              ".cm-tooltip.cm-tooltip-autocomplete > ul > li": { padding: "2px 8px", color: "#c9d3e0" },
+              ".cm-tooltip.cm-tooltip-autocomplete > ul > li[aria-selected]": { background: "#2f4f7a", color: "#ffffff" },
+              // The typed prefix, so you can see WHY an option matched.
+              ".cm-completionMatchedText": { color: "#7dd3a0", textDecoration: "none", fontWeight: "600" },
+              // "colour token", "primitive", "space step": the quiet half of the line.
+              ".cm-completionDetail": { color: "#7d8899", fontStyle: "normal", marginLeft: "0.75em" },
+              ".cm-completionIcon": { color: "#7d8899", opacity: "0.8", marginRight: "0.4em" },
+            },
+            // Without this the editor reports itself as LIGHT, and the popup above was the
+            // visible consequence.
+            { dark: true },
+          ),
+        ],
+      }),
+    });
+    viewRef.current = view;
+    return () => {
+      view.destroy();
+      viewRef.current = null;
+    };
+    // `loaded` seeds the document; `draft` deliberately does not, or every keystroke would
+    // rebuild the editor and drop the cursor.
+    // `loaded` is deliberately absent: it changes on every save, and rebuilding here
+    // destroyed the editor mid-session, taking the undo history and the cursor with it.
+    // An externally changed file is applied as a transaction below instead.
+  }, [host, active?.path, lintCompartment]);
+
+  /**
+   * Text that arrived from disk, applied WITHOUT rebuilding.
+   *
+   * Skipped when the document already matches, which is the case after our own save, so a
+   * save is invisible to the editor rather than a reset.
+   */
+  useEffect(() => {
+    const view = viewRef.current;
+    if (!view || view.state.doc.toString() === loaded) return;
+    view.dispatch({ changes: { from: 0, to: view.state.doc.length, insert: loaded } });
+  }, [loaded]);
+
+  /**
+   * INSPECT: box the rendered element the cursor is inside.
+   *
+   * Three hops, each of which can legitimately come up empty:
+   *   the cursor's node WITHIN this file  (YAML ranges from the parser)
+   *   where this file sits in the COMPOSED tree  (a layout is included into a face)
+   *   the elements that node rendered  (none if hidden, many under an `Each`)
+   *
+   * Anything that fails clears the overlay rather than guessing, and `matches` reports what
+   * happened so the editor can say "not currently rendered" instead of looking broken.
+   */
+  const inspectAt = useCallback(
+    (text: string, offset: number) => {
+      if (!composedRoot || !primitives.size || !active?.rel.match(/\.(ya?ml)$/)) {
+        clearHighlight();
+        setMatches(null);
+        return;
+      }
+      try {
+        const doc = parseDocument(text);
+        const inFile = pathAtOffset(nodeRanges(doc, primitives), offset);
+        if (!inFile) {
+          clearHighlight();
+          setMatches(null);
+          return;
+        }
+        /**
+         * TWO FILE SHAPES, TWO WAYS IN.
+         *
+         * An ENVELOPE (`coursecard.yaml`) holds its tree under `root:`, and that tree IS
+         * the composed root, so the file path maps by dropping one level. A PARTIAL (a
+         * layout) is a bare node included somewhere inside the composed tree, so it has to
+         * be found first. Treating everything as a partial meant an envelope never matched
+         * and every line in it read as "not rendered".
+         */
+        const js = doc.toJS() as Record<string, unknown> | null;
+        const isEnvelope = !!js && typeof js === "object" && !js.type && !!js.root;
+        let id: string | null = null;
+        if (isEnvelope) {
+          id = inFile === "root" ? null : `root${inFile.slice("root.root".length)}`;
+        } else {
+          const prefix = locateSubtree(composedRoot, js);
+          id = prefix ? `${prefix}${inFile.slice("root".length)}` : null;
+        }
+        setMatches(highlightRendered(id, accent));
+      } catch {
+        // Mid-keystroke the document often does not parse. Nothing to show, no error.
+        clearHighlight();
+        setMatches(null);
+      }
+    },
+    [composedRoot, active, accent, primitives],
+  );
+
+  /**
+   * THE ELEMENT PICKER, armed from the header.
+   *
+   * Hover the preview to box what is under the pointer, click to open the file that drew it
+   * with the cursor on the node. The map from a rendered element back to a line is built
+   * once when the picker is armed: a component has a dozen files and a hover has a frame.
+   */
+  useEffect(() => {
+    if (!picking) return;
+    let map: Map<string, { path: string; from: number }> | null = null;
+
+    void Promise.all(
+      files
+        .filter((f) => /\.ya?ml$/.test(f.rel))
+        .map(async (f) => ({
+          ...f,
+          text: await authedFetch(`/local/source/file?path=${encodeURIComponent(f.path)}`)
+            .then((r) => r.json())
+            .then((d) => d.text ?? ""),
+        })),
+    ).then((withText) => {
+      map = buildSourceMap(withText, composedRoot, primitives, parseDocument, nodeRanges, locateSubtree, (d: any) => d.toJS());
+    });
+
+    const onMove = (e: MouseEvent) => {
+      // Over this pane there is nothing to inspect, so drop the box rather than leaving the
+      // last one hanging while the pointer is somewhere unrelated.
+      if (rootRef.current?.contains(e.target as Node)) return void highlightRendered(null, accent);
+      const hit = stampedAncestor(deepElementFromPoint(e.clientX, e.clientY));
+      highlightRendered(hit?.id ?? null, accent);
+    };
+    const onClick = (e: MouseEvent) => {
+      /**
+       * SWALLOW CLICKS ON THE PREVIEW, AND ONLY THOSE.
+       *
+       * While picking, a click on the preview is a question about the UI, never a use of
+       * it, so it must not reach the component's own `action`. But swallowing every click
+       * in the window also ate the one on the pick button, so the picker could not be
+       * turned off, and the file rail stopped responding. Clicks inside this pane are the
+       * editor's own and pass straight through.
+       */
+      if (rootRef.current?.contains(e.target as Node)) return;
+      e.preventDefault();
+      e.stopPropagation();
+      const hit = stampedAncestor(deepElementFromPoint(e.clientX, e.clientY));
+      const found = hit && map?.get(hit.id);
+      if (!found) return;
+      setPicking(false);
+      clearHighlight();
+      const file = files.find((f) => f.path === found.path);
+      /**
+       * TELL THE HOST WHAT WAS PICKED, so a connected agent can answer "make this bigger".
+       * The pointing happens in the UI and the instruction arrives in a terminal, so the
+       * selection has to live somewhere both can reach.
+       */
+      void authedFetch("/local/selection", {
+        method: "POST",
+        headers: { "content-type": "application/json" },
+        body: JSON.stringify({ uri, nodeId: hit.id, file: found.path, offset: found.from, tag: hit.el.tagName.toLowerCase() }),
+      }).catch(() => {
+        /* an agent may not be connected; picking still works */
+      });
+      if (file && file.path !== active?.path) setActive(file);
+      // The document may be about to swap, so place the cursor once it has.
+      setTimeout(() => {
+        const view = viewRef.current;
+        if (!view) return;
+        const pos = Math.min(found.from, view.state.doc.length);
+        // CENTRED, not merely visible: `scrollIntoView: true` stops as soon as the line is
+        // on screen, which lands it against whichever edge it came from and hides the
+        // surrounding lines that give it meaning.
+        view.dispatch({ selection: { anchor: pos }, effects: EditorView.scrollIntoView(pos, { y: "center" }) });
+        view.focus();
+      }, file && file.path !== active?.path ? 250 : 0);
+    };
+    const onKey = (e: KeyboardEvent) => e.key === "Escape" && setPicking(false);
+
+    window.addEventListener("mousemove", onMove, true);
+    window.addEventListener("click", onClick, true);
+    window.addEventListener("keydown", onKey);
+    return () => {
+      window.removeEventListener("mousemove", onMove, true);
+      window.removeEventListener("click", onClick, true);
+      window.removeEventListener("keydown", onKey);
+      clearHighlight();
+    };
+  }, [picking, files, composedRoot, primitives, accent, active?.path]);
+
+  /** Cmd+Shift+C arms the picker, the same chord DevTools uses for the same job. */
+  useEffect(() => {
+    const onKey = (e: KeyboardEvent) => {
+      if ((e.metaKey || e.ctrlKey) && e.shiftKey && e.key.toLowerCase() === "c") {
+        e.preventDefault();
+        setPicking((p) => !p);
+      }
+    };
+    window.addEventListener("keydown", onKey);
+    return () => window.removeEventListener("keydown", onKey);
+  }, []);
+
+  const copy = useCallback(() => {
+    void navigator.clipboard?.writeText(draft);
+  }, [draft]);
+
+  const save = useCallback(async () => {
+    if (!active?.writable || !dirty || saving) return;
+    setSaving(true);
+    setError(null);
+    try {
+      const res = await authedFetch("/local/source/file", {
+        method: "POST",
+        headers: { "content-type": "application/json" },
+        body: JSON.stringify({ path: active.path, text: draft }),
+      });
+      const d = await res.json();
+      if (d.saved) {
+        setLoaded(draft);
+        setSavedAt(Date.now());
+        setProblems(d.findings ?? []);
+        onSaved?.();
+      } else {
+        setError(d.error === "lint errors" ? "not saved: fix the errors below" : (d.error ?? "save refused"));
+        setProblems(d.findings ?? []);
+      }
+    } catch (e) {
+      setError(String((e as Error)?.message ?? e));
+    } finally {
+      setSaving(false);
+    }
+  }, [active, draft, dirty, saving, onSaved]);
+
+  // The editor's Mod-s binding calls through this, so the keymap never goes stale.
+  useEffect(() => {
+    saveRef.current = () => void save();
+  }, [save]);
+
+  /** Put the cursor on a finding's line, the way a problems list is expected to behave. */
+  /**
+   * LIVE PREVIEW: a clean edit saves itself, and the preview follows.
+   *
+   * Editing a token and then reaching for Cmd+S to find out what it looks like is a round
+   * trip the developer should not have to make. The preview renders what is ON DISK, so
+   * "render it" and "save it" are the same act here.
+   *
+   * ONLY WHEN THE LINTER IS HAPPY. `problems` is the shared library's verdict on the draft,
+   * so a file mid-keystroke or carrying an error is never written. That also means this
+   * adds no new write path: it presses the same lint-gated save the button does, which can
+   * still refuse, in which case nothing reaches disk.
+   */
+  useEffect(() => {
+    if (!dirty || saving || !active?.writable) return;
+    if (problems.some((p) => p.level === "error")) return;
+    const t = setTimeout(() => void save(), 700);
+    return () => clearTimeout(t);
+  }, [dirty, saving, active, problems, save]);
+
+  const goToLine = useCallback((line?: number) => {
+    const view = viewRef.current;
+    if (!view || !line) return;
+    const l = view.state.doc.line(Math.min(Math.max(line, 1), view.state.doc.lines));
+    view.dispatch({ selection: { anchor: l.from }, effects: EditorView.scrollIntoView(l.from, { y: "center" }) });
+    view.focus();
+  }, []);
+
+  if (!hasSourceAccess) return null;
+
+  const errorCount = problems.filter((p) => p.level === "error").length;
+  const warnCount = problems.filter((p) => p.level === "warn").length;
+
+  const dirtyPaths = useMemo(
+    () => (active && dirty ? new Set([active.path]) : new Set<string>()),
+    [active, dirty],
+  );
+
+  /**
+   * OPENING A LAYOUT SWITCHES THE FACE.
+   *
+   * A layout's filename is its state name, so opening `layouts/course-detail.yaml` and
+   * putting the preview into `course-detail` are the same intent. Reading a face's
+   * definition beside a preview of a DIFFERENT face is a trap the rail would otherwise
+   * set for you every time.
+   */
+  const pickFile = useCallback(
+    (f: SourceFile) => {
+      setActive(f);
+      if (f.rel.startsWith("layouts/")) onPickState?.(stateOf(f.rel));
+    },
+    [onPickState],
+  );
+
+  /**
+   * And the reverse: change the face anywhere else and its layout opens here.
+   *
+   * IT MUST NOT OVERRIDE A FILE ALREADY SHOWING THAT FACE. `activeState` is the FACE only,
+   * and a face's steps live in their own layouts (`course` → `course-detail`). Matching on
+   * the face alone pulled the editor off `course-detail.yaml` and back to `course.yaml` the
+   * instant you opened it, so the rail could not open a step at all. A layout belonging to
+   * the active face, at any depth, is left alone.
+   *
+   * Skipped while the file has unsaved edits: swapping a document out from under a draft
+   * loses work.
+   */
+  useEffect(() => {
+    if (!activeState || dirty) return;
+    /**
+     * ONLY WHEN THE VIEW ACTUALLY CHANGES.
+     *
+     * Reacting to the open file as well meant every click in the rail was immediately
+     * undone: open `manifest.yaml`, the effect re-ran, and it pulled you back to the live
+     * layout. You could never read anything but the layout being rendered. The state is
+     * remembered instead, so the editor follows a NEW view and otherwise leaves you alone.
+     */
+    if (syncedState.current === activeState) return;
+    syncedState.current = activeState;
+    const layout = (name: string) => files.find((f) => f.rel.startsWith("layouts/") && stateOf(f.rel) === name);
+    /**
+     * `activeState` is the DEEPEST view (`course-detail`), so try it first. A step with no
+     * layout of its own is drawn by its face's file, so fall back along the name:
+     * `course-detail` → `course`. Anything with no layout at all leaves the editor alone.
+     */
+    let match = layout(activeState);
+    for (let name = activeState; !match && name.includes("-"); ) {
+      name = name.slice(0, name.lastIndexOf("-"));
+      match = layout(name);
+    }
+    if (match) setActive(match);
+  }, [activeState, files, dirty]);
+
+  return (
+    // min-w-0 all the way down. A flex child defaults to min-width:auto, so a long line in
+    // the editor pushes the whole split wider than its container and squeezes the preview
+    // off the screen instead of scrolling inside its own pane.
+    <div ref={rootRef} className="flex min-h-0 min-w-0 flex-1 bg-[#1c222b] text-gray-200">
+      <FileTree
+        files={files}
+        active={active}
+        dirtyPaths={dirtyPaths}
+        accent={accent}
+        layoutOrder={layoutOrder}
+        liveState={activeState}
+        onPick={pickFile}
+      />
+
+      <div className="flex min-h-0 min-w-0 flex-1 flex-col">
+        {/* One slim header: where you are on the left, what you can do on the right. */}
+        <div className="flex shrink-0 items-center gap-2 border-b border-gray-800 px-2 py-1 text-[10px]">
+          <span className="min-w-0 flex-1 truncate text-gray-500" title={active?.path}>
+            {active ? splitRel(active.rel).dir : ""}
+            <span className="text-gray-300">{active ? splitRel(active.rel).name : ""}</span>
+          </span>
+          {/* What the cursor is pointing at on the right. Zero is worth saying: the node is
+              real but not drawn right now (an inactive Switch case, a false visibleWhen). */}
+          {matches !== null && (
+            <span className="shrink-0" style={{ color: matches > 0 ? (accent ?? "#3b82f6") : "#7d8899" }}>
+              {matches === 0 ? "not rendered" : matches === 1 ? "1 element" : `${matches} elements`}
+            </span>
+          )}
+          {errorCount > 0 && <span className="shrink-0 text-red-400">{errorCount} error{errorCount > 1 ? "s" : ""}</span>}
+          {errorCount === 0 && warnCount > 0 && <span className="shrink-0 text-amber-400">{warnCount} warning{warnCount > 1 ? "s" : ""}</span>}
+          {errorCount === 0 && warnCount === 0 && dirty && <span className="shrink-0 text-amber-400">edited</span>}
+          {errorCount === 0 && warnCount === 0 && !dirty && savedAt && <span className="shrink-0 text-emerald-400">saved</span>}
+          {active && !active.writable && (
+            <span className="shrink-0 rounded border border-gray-700 px-1.5 py-0.5 text-gray-500">{readOnlyNote(active.reason)}</span>
+          )}
+          {/* PICK: hover the preview to box an element, click to land on its line. */}
+          <button
+            onClick={() => setPicking((p) => !p)}
+            aria-pressed={picking}
+            title="Pick an element in the preview  (Cmd+Shift+C, Esc to cancel)"
+            className="flex shrink-0 items-center gap-1 rounded border px-1.5 py-0.5"
+            style={{
+              borderColor: picking ? "transparent" : "#374151",
+              background: picking ? (accent ?? "#3b82f6") : "transparent",
+              color: picking ? "#fff" : "#9ca3af",
+            }}
+          >
+            {/* The DevTools glyph: a pointer inside a frame. */}
+            <svg width="12" height="12" viewBox="0 0 16 16" fill="none" aria-hidden="true">
+              <path d="M2 5.5V3a1 1 0 0 1 1-1h2.5M14 5.5V3a1 1 0 0 0-1-1h-2.5M2 10.5V13a1 1 0 0 0 1 1h2" stroke="currentColor" strokeWidth="1.3" strokeLinecap="round" />
+              <path d="m8 7 5 5-2 .4L9.8 15 8 7Z" fill="currentColor" />
+            </svg>
+            pick
+          </button>
+          <button onClick={copy} className="shrink-0 rounded border border-gray-700 px-1.5 py-0.5 text-gray-400 hover:bg-white/5">
+            copy
+          </button>
+          {active?.writable && (
+            <button
+              onClick={() => void save()}
+              disabled={!dirty || saving}
+              title="Save (Cmd+S). Lint runs; a failing save is rolled back."
+              className="shrink-0 rounded border px-1.5 py-0.5 disabled:opacity-40"
+              style={{ borderColor: dirty ? (accent ?? "#10b981") : "#374151", color: dirty ? (accent ?? "#10b981") : "#9ca3af" }}
+            >
+              {saving ? "saving" : "save"}
+            </button>
+          )}
+        </div>
+
+        {error && <div className="shrink-0 px-2 py-1 text-[11px] text-amber-400">{error}</div>}
+
+        <div ref={setHost} className="min-h-0 min-w-0 flex-1 overflow-hidden" />
+
+        {/* PROBLEMS. Findings the library reports without a position live only here, so the
+            strip is the complete list and the gutter is the located subset of it. */}
+        {problems.length > 0 && (
+          <div className="max-h-24 shrink-0 overflow-auto border-t border-gray-800 bg-black/25">
+            {problems.map((p, i) => (
+              <button
+                key={i}
+                onClick={() => goToLine(p.line)}
+                className="block w-full px-2 py-0.5 text-left text-[11px] hover:bg-white/5"
+              >
+                <span className={p.level === "error" ? "text-red-400" : "text-amber-400"}>
+                  {p.line ? p.line : "file"}
+                </span>
+                <span className="ml-2 text-gray-300">{p.msg}</span>
+              </button>
+            ))}
+          </div>
+        )}
+      </div>
+    </div>
+  );
+}