@miadi/stateloom-web 0.1.9 → 0.2.0

package/server/src/lib/docParam.ts

@@ -11,7 +11,7 @@ import { useEffect, useState } from "react";
  * byte-identical to the old behavior.
  */
 
-const DOC_CHANGE_EVENT = "stateloom:doc-change";
+export const DOC_CHANGE_EVENT = "stateloom:doc-change";
 
 export function requestedDoc(): string | null {
   if (typeof window === "undefined") return null;
@@ -29,6 +29,9 @@ 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");
+  // A focus names an element of the document it was written for; it does not
+  // travel to another one. (`system=` does: the strip stays while you browse.)
+  url.searchParams.delete("focus");
   window.history.pushState({}, "", url);
   window.dispatchEvent(new Event(DOC_CHANGE_EVENT));
 }

package/server/src/lib/machineFocus.ts

@@ -0,0 +1,126 @@
+"use client";
+
+/**
+ * `focus=` for the state designer (Spec 82): `state:X` drills to X's level,
+ * selects it and centres it; `event:E` does the same for the first transition
+ * that fires E; `machine:*` (and anything else) leaves the board as it is.
+ *
+ * And the other way: when a person selects a state or a transition, the URL's
+ * focus follows, so the system strip can list what that element links to.
+ *
+ * Kept as one hook beside the store rather than inside it, so the state
+ * designer changes by the single line that mounts it.
+ */
+import { useEffect, useRef } from "react";
+import { fitToBoxes, parseFocus, type StateDef, type StateMachineDefinition } from "@miadi/stateloom-protocol";
+import { useDesignerStore } from "@/store/useDesignerStore";
+import { CANVAS_SVG_ID } from "@/lib/exportImage";
+import { urlParam, useFocusRequest, writeFocus } from "@/lib/systemParam";
+
+const kids = (s: StateDef): StateDef[] => (s.parallel ? s.parallel.states : (s.states ?? []));
+
+/** Names from the root down to `name`, inclusive; null when it is not in the tree. */
+function chainTo(root: StateDef | undefined, name: string): string[] | null {
+  if (!root) return null;
+  if (root.name === name) return [root.name];
+  for (const child of kids(root)) {
+    const below = chainTo(child, name);
+    if (below) return [root.name, ...below];
+  }
+  return null;
+}
+
+/** The first transition, in document order, that fires `event`. */
+function firstTransition(root: StateDef | undefined, event: string): { state: string; index: number } | null {
+  if (!root) return null;
+  const i = (root.transitions ?? []).findIndex((t) => t?.event === event);
+  if (i >= 0) return { state: root.name, index: i };
+  for (const child of kids(root)) {
+    const hit = firstTransition(child, event);
+    if (hit) return hit;
+  }
+  return null;
+}
+
+function transitionEvent(def: StateMachineDefinition, id: string): string | null {
+  const cut = id.lastIndexOf(":");
+  const chain = chainTo(def.state, id.slice(0, cut));
+  if (!chain) return null;
+  let s: StateDef | undefined = def.state;
+  for (const name of chain.slice(1)) s = kids(s!).find((k) => k.name === name);
+  return s?.transitions?.[Number(id.slice(cut + 1))]?.event ?? null;
+}
+
+export function useMachineFocus(): void {
+  const request = useFocusRequest();
+  const pending = useRef<{ focus: string; docAt: string | null; defAt: StateMachineDefinition } | null>(null);
+
+  useEffect(() => {
+    const tryApply = (): void => {
+      const p = pending.current;
+      if (!p) return;
+      const s = useDesignerStore.getState();
+      const doc = urlParam("doc");
+      // Not the requested document yet, or still its predecessor's definition.
+      if (doc && s.docPath !== doc) return;
+      if (p.docAt !== s.docPath && s.definition === p.defAt) return;
+      pending.current = null;
+
+      const f = parseFocus(p.focus);
+      if (!f) return;
+      let chain: string[] | null = null;
+      let select: { kind: "state" | "transition"; id: string } | null = null;
+      if (f.kind === "state") {
+        chain = chainTo(s.definition.state, f.name);
+        if (chain) select = { kind: "state", id: f.name };
+      } else if (f.kind === "event") {
+        const hit = firstTransition(s.definition.state, f.name);
+        if (hit) {
+          chain = chainTo(s.definition.state, hit.state);
+          select = { kind: "transition", id: `${hit.state}:${hit.index}` };
+        }
+      }
+      if (!chain || !select) return;
+      // The level that draws the element: its parent's children.
+      const level = chain.length > 1 ? chain.slice(0, -1) : chain;
+      useDesignerStore.setState({ navigationPath: level, currentParent: level[level.length - 1] });
+      s.select(select.kind, select.id);
+
+      const centre = (): void => {
+        const box = useDesignerStore.getState().layout.positions[chain![chain!.length - 1]];
+        const rect = document.getElementById(CANVAS_SVG_ID)?.getBoundingClientRect();
+        if (!box || !rect?.width) return;
+        const vp = fitToBoxes([box], rect.width, rect.height, { padding: 60, maxScale: 1 });
+        useDesignerStore.getState().setViewport(vp);
+      };
+      // Once when the board has drawn the level, and once more after this
+      // browser's remembered view has had its chance to land on top.
+      requestAnimationFrame(centre);
+      setTimeout(centre, 450);
+    };
+
+    if (request.nonce > 0) {
+      const s = useDesignerStore.getState();
+      pending.current = request.focus ? { focus: request.focus, docAt: s.docPath, defAt: s.definition } : null;
+      tryApply();
+    }
+    return useDesignerStore.subscribe(tryApply);
+  }, [request]);
+
+  // A person's selection becomes the focus. Clearing it leaves the last one in
+  // the URL: the strip keeps listing what was last in hand.
+  useEffect(
+    () =>
+      useDesignerStore.subscribe((state, prev) => {
+        if (state.selection === prev.selection || !state.selection.id) return;
+        const { kind, id } = state.selection;
+        if (kind === "state") writeFocus(`state:${id}`);
+        else if (kind === "event") writeFocus(`event:${id}`);
+        else if (kind === "transition") {
+          const event = transitionEvent(state.definition, id);
+          if (event) writeFocus(`event:${event}`);
+        }
+      }),
+    [],
+  );
+}

package/server/src/lib/projectFile.ts

@@ -1,4 +1,4 @@
-import { existsSync, readdirSync, realpathSync, statSync } from "fs";
+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";
 
@@ -35,6 +35,44 @@ export function allowedDocRoots(): string[] {
   return real;
 }
 
+/**
+ * The chronicle's diagrams (D2, approved by Guillaume 2026-09-30 — the narrow
+ * rule). A chronicle root, from STATELOOM_CHRONICLE_ROOT (SMCRAFT_ twin), admits
+ * exactly one shape of path and nothing else under it:
+ *
+ *     <chronicleRoot>/<episode>/diagrams/<file>.json
+ *
+ * One episode directory, then `diagrams/`, then the file — not the episode's
+ * other files, not the root's own files, nothing deeper. The shape is checked on
+ * the REAL path, so a symlink in the episode or in `diagrams/` cannot lead out
+ * of it; and since the real path of the parent is required, a new file can be
+ * created only where `diagrams/` already exists. Nothing here makes a directory.
+ */
+export function chronicleRoot(): string | null {
+  const raw = envAlias("CHRONICLE_ROOT");
+  if (!raw) return null;
+  try {
+    return realpathSync(resolve(raw));
+  } catch {
+    return null; // a chronicle root that does not exist admits nothing
+  }
+}
+
+/** Is this real path `<root>/<episode>/diagrams/<file>.json`, with `diagrams/` a real directory? */
+export function isChronicleDiagram(real: string, root: string): boolean {
+  if (!real.startsWith(root + sep)) return false;
+  const parts = real.slice(root.length + 1).split(sep);
+  if (parts.length !== 3) return false;
+  const [episode, folder, file] = parts;
+  if (!episode || episode.startsWith(".") || folder !== "diagrams") return false;
+  if (!file || file.startsWith(".") || !file.endsWith(".json")) return false;
+  try {
+    return statSync(join(root, episode, folder)).isDirectory();
+  } catch {
+    return false;
+  }
+}
+
 export type DocResolution =
   | { ok: true; path: string }
   | { ok: false; error: string };
@@ -51,21 +89,60 @@ export function resolveDocPath(doc: string | null | undefined): DocResolution {
     return { ok: false, error: "doc must name a .json document" };
   }
 
+  if (doc.includes("\0")) {
+    return { ok: false, error: "doc must not contain a NUL byte" };
+  }
+
   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.
+  // Where the request really lands, symlinks followed:
+  // - an existing file (or a live link): its realpath;
+  // - a DANGLING link: the path it points at — the write would follow it there,
+  //   so that is what the roots must admit (the parent realpathed, as for a
+  //   new file). A link that points at another link is refused outright.
+  // - a new file: its realpathed parent plus its name.
+  // A doc whose parent does not exist is refused; nothing here makes a directory.
   let anchored: string;
   try {
-    anchored = existsSync(lexical)
-      ? realpathSync(lexical)
-      : resolve(realpathSync(dirname(lexical)), lexical.slice(lexical.lastIndexOf(sep) + 1));
+    let link: ReturnType<typeof lstatSync> | null = null;
+    try {
+      link = lstatSync(lexical);
+    } catch {
+      link = null;
+    }
+    if (link?.isSymbolicLink()) {
+      try {
+        anchored = realpathSync(lexical);
+      } catch {
+        const target = resolve(dirname(lexical), readlinkSync(lexical));
+        let chained = false;
+        try {
+          chained = lstatSync(target).isSymbolicLink();
+        } catch {
+          chained = false;
+        }
+        if (chained) return { ok: false, error: `${doc} is a link to a link, which is not followed` };
+        anchored = resolve(realpathSync(dirname(target)), basename(target));
+      }
+    } else if (link) {
+      anchored = realpathSync(lexical);
+    } else {
+      anchored = resolve(realpathSync(dirname(lexical)), basename(lexical));
+    }
   } catch {
     // 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()) };
   }
 
+  // Under the chronicle root only the chronicle rule decides — even when a doc
+  // root contains it, or is it — so the narrow rule cannot be widened by a
+  // broader root.
+  const chronicle = chronicleRoot();
+  if (chronicle && (anchored === chronicle || anchored.startsWith(chronicle + sep))) {
+    return isChronicleDiagram(anchored, chronicle)
+      ? { ok: true, path: anchored }
+      : { ok: false, error: outsideRootsMessage(doc, allowedDocRoots()) };
+  }
   const roots = allowedDocRoots();
   for (const root of roots) {
     if (anchored === root || anchored.startsWith(root + sep)) {
@@ -75,6 +152,22 @@ export function resolveDocPath(doc: string | null | undefined): DocResolution {
   return { ok: false, error: outsideRootsMessage(doc, roots) };
 }
 
+/**
+ * Write a resolved document without following a link at the destination:
+ * `O_NOFOLLOW` fails on a symlink in the last component, so a link placed there
+ * after `resolveDocPath` looked cannot redirect the write. The parent was
+ * realpathed by `resolveDocPath`. The file keeps its inode, so watchers and
+ * hard links see an ordinary change.
+ */
+export function writeDocFile(path: string, content: string): void {
+  const fd = openSync(path, constants.O_WRONLY | constants.O_CREAT | constants.O_TRUNC | constants.O_NOFOLLOW, 0o666);
+  try {
+    writeSync(fd, content, 0, "utf8");
+  } finally {
+    closeSync(fd);
+  }
+}
+
 /**
  * A refusal that is true from the READER's side.
  *
@@ -86,7 +179,10 @@ export function resolveDocPath(doc: string | null | undefined): DocResolution {
  * 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 chronicle = chronicleRoot();
+  const where =
+    (roots.length ? roots.join(", ") : "(no readable root is configured)") +
+    (chronicle ? `, nor a chronicle diagram (${chronicle}/<episode>/diagrams/<file>.json, in an existing diagrams/ folder)` : "");
   const hint =
     roots.length === 1 && roots[0] === "/data"
       ? " — this server is in a container, and it sees your mounted directory as /data," +
@@ -95,6 +191,10 @@ function outsideRootsMessage(doc: string, roots: string[]): string {
   return `${doc} is not under the permitted document root${roots.length === 1 ? "" : "s"} ${where}${hint}`;
 }
 
+/** How many episode folders, newest name first, and how many chronicle files the listing reads. */
+const CHRONICLE_EPISODE_LIMIT = 400;
+const CHRONICLE_FILE_LIMIT = 200;
+
 export interface DocEntry {
   /** Absolute path as the SERVER sees it — the value `?doc=` wants. */
   path: string;
@@ -125,7 +225,13 @@ export function listDocuments(limit = 300, maxDepth = 4): { docs: DocEntry[]; tr
   const seen = new Set<string>();
   let truncated = false;
 
-  const walk = (dir: string, depth: number): void => {
+  // Nothing under the chronicle root is listed by a doc root's walk: only the
+  // chronicle rule admits there, and it is listed on its own below.
+  const chronicle = chronicleRoot();
+  const underChronicle = (real: string): boolean =>
+    !!chronicle && (real === chronicle || real.startsWith(chronicle + sep));
+
+  const walk = (dir: string, depth: number, root: string): void => {
     if (docs.length >= limit) {
       truncated = true;
       return;
@@ -139,33 +245,87 @@ export function listDocuments(limit = 300, maxDepth = 4): { docs: DocEntry[]; tr
     for (const entry of entries) {
       if (entry.startsWith(".") || entry === "node_modules") continue;
       const full = join(dir, entry);
+      let real: string;
       let stat;
       try {
-        stat = statSync(full);
+        real = realpathSync(full);
+        stat = statSync(real);
       } catch {
         continue; // a broken symlink lists as nothing, not as a crash
       }
+      // A link out of the root is neither listed nor descended: the listing
+      // never names a path the file API would refuse.
+      if (real !== root && !real.startsWith(root + sep)) continue;
+      if (underChronicle(real)) continue;
       if (stat.isDirectory()) {
-        if (depth < maxDepth) walk(full, depth + 1);
+        if (depth < maxDepth) walk(real, depth + 1, root);
         continue;
       }
-      if (!entry.endsWith(".json")) continue;
+      if (!entry.endsWith(".json") || !real.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 });
+      if (seen.has(real)) continue;
+      seen.add(real);
+      docs.push({ path: real, name: basename(real), dir: dirname(real), size: stat.size, mtime: stat.mtimeMs });
     }
   };
 
-  for (const root of allowedDocRoots()) walk(root, 0);
+  for (const root of allowedDocRoots()) walk(root, 0, root);
+
+  // The chronicle's diagrams: `<episode>/diagrams/*.json` only, as the rule
+  // admits them, and bounded on its own so a long chronicle neither crowds the
+  // roots out of the list nor turns it into a crawl of every episode.
+  if (chronicle) {
+    let listed = 0;
+    let episodes: string[] = [];
+    try {
+      episodes = readdirSync(chronicle).filter((e) => !e.startsWith(".")).sort().reverse().slice(0, CHRONICLE_EPISODE_LIMIT);
+    } catch {
+      episodes = [];
+    }
+    for (const episode of episodes) {
+      if (listed >= CHRONICLE_FILE_LIMIT) {
+        truncated = true;
+        break;
+      }
+      const dir = join(chronicle, episode, "diagrams");
+      let files: string[];
+      try {
+        files = readdirSync(dir);
+      } catch {
+        continue; // no diagrams/ folder: nothing of this episode is admitted
+      }
+      for (const file of files) {
+        if (file.startsWith(".") || !file.endsWith(".json")) continue;
+        const full = join(dir, file);
+        let real: string;
+        let stat;
+        try {
+          real = realpathSync(full);
+          stat = statSync(real);
+        } catch {
+          continue;
+        }
+        // Listed only where the file API would serve it: never a path it refuses.
+        if (!stat.isFile() || !isChronicleDiagram(real, chronicle) || seen.has(real)) continue;
+        if (listed >= CHRONICLE_FILE_LIMIT) {
+          truncated = true;
+          break;
+        }
+        seen.add(real);
+        docs.push({ path: real, name: file, dir: dirname(real), size: stat.size, mtime: stat.mtimeMs });
+        listed += 1;
+      }
+    }
+  }
 
-  // The loom's own documents first (`.smdf.json` machines, `.erdf.json` ERDs) —
-  // the rest are `.json` files the allowlist tolerates but nobody came here
-  // looking for — then most recently touched.
-  const rank = (name: string): number => (/\.(smdf|erdf)\.json$/i.test(name) ? 0 : 1);
+  // The loom's own documents first (`.smdf.json` machines, `.erdf.json` ERDs,
+  // `.sqdf.json` sequences, `.sysdf.json` systems) — the rest are `.json` files
+  // the allowlist tolerates but nobody came here looking for — then most
+  // recently touched.
+  const rank = (name: string): number => (/\.(smdf|erdf|sqdf|sysdf)\.json$/i.test(name) ? 0 : 1);
   docs.sort((a, b) => rank(a.name) - rank(b.name) || b.mtime - a.mtime || a.path.localeCompare(b.path));
 
   return { docs, truncated };

package/server/src/lib/safely.ts

@@ -0,0 +1,16 @@
+/**
+ * Run a check or a derivation over a document that may be malformed, and fall
+ * back instead of throwing: a hand- or agent-written file is not always the
+ * shape the types say, and one bad field must not take the page down. The
+ * error is kept for whoever asks (`onError`) and logged once.
+ */
+export function safely<T>(run: () => T, fallback: T, onError?: (message: string) => void): T {
+  try {
+    return run();
+  } catch (e) {
+    const message = e instanceof Error ? e.message : String(e);
+    console.warn("[stateloom] skipped on a malformed document:", message);
+    onError?.(message);
+    return fallback;
+  }
+}