@miadi/stateloom-web 0.1.0

package/server/package.json

@@ -0,0 +1,31 @@
+{
+  "name": "stateloom-web",
+  "version": "0.1.0",
+  "private": true,
+  "scripts": {
+    "dev": "next dev -p ${PORT:-4598}",
+    "build": "next build",
+    "start": "next start -p ${PORT:-4598}",
+    "lint": "eslint"
+  },
+  "dependencies": {
+    "@miadi/stateloom-client": "file:../bridge-client",
+    "@miadi/stateloom-protocol": "file:../bridge-protocol",
+    "@miadi/stateloom-react": "file:../bridge-react",
+    "next": "16.1.6",
+    "react": "19.2.3",
+    "react-dom": "19.2.3",
+    "zustand": "^5.0.11"
+  },
+  "devDependencies": {
+    "@tailwindcss/postcss": "^4",
+    "@types/node": "^20",
+    "@types/react": "^19",
+    "@types/react-dom": "^19",
+    "babel-plugin-react-compiler": "1.0.0",
+    "eslint": "^9",
+    "eslint-config-next": "16.1.6",
+    "tailwindcss": "^4",
+    "typescript": "^5"
+  }
+}

package/server/postcss.config.mjs

@@ -0,0 +1,7 @@
+const config = {
+  plugins: {
+    "@tailwindcss/postcss": {},
+  },
+};
+
+export default config;

package/server/public/file.svg

@@ -0,0 +1 @@
+<svg fill="none" viewBox="0 0 16 16" xmlns="http://www.w3.org/2000/svg"><path d="M14.5 13.5V5.41a1 1 0 0 0-.3-.7L9.8.29A1 1 0 0 0 9.08 0H1.5v13.5A2.5 2.5 0 0 0 4 16h8a2.5 2.5 0 0 0 2.5-2.5m-1.5 0v-7H8v-5H3v12a1 1 0 0 0 1 1h8a1 1 0 0 0 1-1M9.5 5V2.12L12.38 5zM5.13 5h-.62v1.25h2.12V5zm-.62 3h7.12v1.25H4.5zm.62 3h-.62v1.25h7.12V11z" clip-rule="evenodd" fill="#666" fill-rule="evenodd"/></svg>

package/server/public/globe.svg

@@ -0,0 +1 @@
+<svg fill="none" xmlns="http://www.w3.org/2000/svg" viewBox="0 0 16 16"><g clip-path="url(#a)"><path fill-rule="evenodd" clip-rule="evenodd" d="M10.27 14.1a6.5 6.5 0 0 0 3.67-3.45q-1.24.21-2.7.34-.31 1.83-.97 3.1M8 16A8 8 0 1 0 8 0a8 8 0 0 0 0 16m.48-1.52a7 7 0 0 1-.96 0H7.5a4 4 0 0 1-.84-1.32q-.38-.89-.63-2.08a40 40 0 0 0 3.92 0q-.25 1.2-.63 2.08a4 4 0 0 1-.84 1.31zm2.94-4.76q1.66-.15 2.95-.43a7 7 0 0 0 0-2.58q-1.3-.27-2.95-.43a18 18 0 0 1 0 3.44m-1.27-3.54a17 17 0 0 1 0 3.64 39 39 0 0 1-4.3 0 17 17 0 0 1 0-3.64 39 39 0 0 1 4.3 0m1.1-1.17q1.45.13 2.69.34a6.5 6.5 0 0 0-3.67-3.44q.65 1.26.98 3.1M8.48 1.5l.01.02q.41.37.84 1.31.38.89.63 2.08a40 40 0 0 0-3.92 0q.25-1.2.63-2.08a4 4 0 0 1 .85-1.32 7 7 0 0 1 .96 0m-2.75.4a6.5 6.5 0 0 0-3.67 3.44 29 29 0 0 1 2.7-.34q.31-1.83.97-3.1M4.58 6.28q-1.66.16-2.95.43a7 7 0 0 0 0 2.58q1.3.27 2.95.43a18 18 0 0 1 0-3.44m.17 4.71q-1.45-.12-2.69-.34a6.5 6.5 0 0 0 3.67 3.44q-.65-1.27-.98-3.1" fill="#666"/></g><defs><clipPath id="a"><path fill="#fff" d="M0 0h16v16H0z"/></clipPath></defs></svg>

package/server/public/next.svg

@@ -0,0 +1 @@
+<svg xmlns="http://www.w3.org/2000/svg" fill="none" viewBox="0 0 394 80"><path fill="#000" d="M262 0h68.5v12.7h-27.2v66.6h-13.6V12.7H262V0ZM149 0v12.7H94v20.4h44.3v12.6H94v21h55v12.6H80.5V0h68.7zm34.3 0h-17.8l63.8 79.4h17.9l-32-39.7 32-39.6h-17.9l-23 28.6-23-28.6zm18.3 56.7-9-11-27.1 33.7h17.8l18.3-22.7z"/><path fill="#000" d="M81 79.3 17 0H0v79.3h13.6V17l50.2 62.3H81Zm252.6-.4c-1 0-1.8-.4-2.5-1s-1.1-1.6-1.1-2.6.3-1.8 1-2.5 1.6-1 2.6-1 1.8.3 2.5 1a3.4 3.4 0 0 1 .6 4.3 3.7 3.7 0 0 1-3 1.8zm23.2-33.5h6v23.3c0 2.1-.4 4-1.3 5.5a9.1 9.1 0 0 1-3.8 3.5c-1.6.8-3.5 1.3-5.7 1.3-2 0-3.7-.4-5.3-1s-2.8-1.8-3.7-3.2c-.9-1.3-1.4-3-1.4-5h6c.1.8.3 1.6.7 2.2s1 1.2 1.6 1.5c.7.4 1.5.5 2.4.5 1 0 1.8-.2 2.4-.6a4 4 0 0 0 1.6-1.8c.3-.8.5-1.8.5-3V45.5zm30.9 9.1a4.4 4.4 0 0 0-2-3.3 7.5 7.5 0 0 0-4.3-1.1c-1.3 0-2.4.2-3.3.5-.9.4-1.6 1-2 1.6a3.5 3.5 0 0 0-.3 4c.3.5.7.9 1.3 1.2l1.8 1 2 .5 3.2.8c1.3.3 2.5.7 3.7 1.2a13 13 0 0 1 3.2 1.8 8.1 8.1 0 0 1 3 6.5c0 2-.5 3.7-1.5 5.1a10 10 0 0 1-4.4 3.5c-1.8.8-4.1 1.2-6.8 1.2-2.6 0-4.9-.4-6.8-1.2-2-.8-3.4-2-4.5-3.5a10 10 0 0 1-1.7-5.6h6a5 5 0 0 0 3.5 4.6c1 .4 2.2.6 3.4.6 1.3 0 2.5-.2 3.5-.6 1-.4 1.8-1 2.4-1.7a4 4 0 0 0 .8-2.4c0-.9-.2-1.6-.7-2.2a11 11 0 0 0-2.1-1.4l-3.2-1-3.8-1c-2.8-.7-5-1.7-6.6-3.2a7.2 7.2 0 0 1-2.4-5.7 8 8 0 0 1 1.7-5 10 10 0 0 1 4.3-3.5c2-.8 4-1.2 6.4-1.2 2.3 0 4.4.4 6.2 1.2 1.8.8 3.2 2 4.3 3.4 1 1.4 1.5 3 1.5 5h-5.8z"/></svg>

package/server/public/vercel.svg

@@ -0,0 +1 @@
+<svg fill="none" xmlns="http://www.w3.org/2000/svg" viewBox="0 0 1155 1000"><path d="m577.3 0 577.4 1000H0z" fill="#fff"/></svg>

package/server/public/window.svg

@@ -0,0 +1 @@
+<svg fill="none" xmlns="http://www.w3.org/2000/svg" viewBox="0 0 16 16"><path fill-rule="evenodd" clip-rule="evenodd" d="M1.5 2.5h13v10a1 1 0 0 1-1 1h-11a1 1 0 0 1-1-1zM0 1h16v11.5a2.5 2.5 0 0 1-2.5 2.5h-11A2.5 2.5 0 0 1 0 12.5zm3.75 4.5a.75.75 0 1 0 0-1.5.75.75 0 0 0 0 1.5M7 4.75a.75.75 0 1 1-1.5 0 .75.75 0 0 1 1.5 0m1.75.75a.75.75 0 1 0 0-1.5.75.75 0 0 0 0 1.5" fill="#666"/></svg>

package/server/server.js

@@ -0,0 +1,38 @@
+const path = require('path')
+
+const dir = path.join(__dirname)
+
+process.env.NODE_ENV = 'production'
+process.chdir(__dirname)
+
+const currentPort = parseInt(process.env.PORT, 10) || 3000
+const hostname = process.env.HOSTNAME || '0.0.0.0'
+
+let keepAliveTimeout = parseInt(process.env.KEEP_ALIVE_TIMEOUT, 10)
+const nextConfig = {"env":{},"webpack":null,"typescript":{"ignoreBuildErrors":false},"typedRoutes":false,"distDir":"./.next","cleanDistDir":true,"assetPrefix":"","cacheMaxMemorySize":52428800,"configOrigin":"next.config.ts","useFileSystemPublicRoutes":true,"generateEtags":true,"pageExtensions":["tsx","ts","jsx","js"],"poweredByHeader":true,"compress":true,"images":{"deviceSizes":[640,750,828,1080,1200,1920,2048,3840],"imageSizes":[32,48,64,96,128,256,384],"path":"/_next/image","loader":"default","loaderFile":"","domains":[],"disableStaticImages":false,"minimumCacheTTL":14400,"formats":["image/webp"],"maximumRedirects":3,"maximumResponseBody":50000000,"dangerouslyAllowLocalIP":false,"dangerouslyAllowSVG":false,"contentSecurityPolicy":"script-src 'none'; frame-src 'none'; sandbox;","contentDispositionType":"attachment","localPatterns":[{"pathname":"**","search":""}],"remotePatterns":[],"qualities":[75],"unoptimized":false},"devIndicators":{"position":"bottom-left"},"onDemandEntries":{"maxInactiveAge":60000,"pagesBufferLength":5},"basePath":"","sassOptions":{},"trailingSlash":false,"i18n":null,"productionBrowserSourceMaps":false,"excludeDefaultMomentLocales":true,"reactProductionProfiling":false,"reactStrictMode":null,"reactMaxHeadersLength":6000,"httpAgentOptions":{"keepAlive":true},"logging":{},"compiler":{},"expireTime":31536000,"staticPageGenerationTimeout":60,"output":"standalone","modularizeImports":{"@mui/icons-material":{"transform":"@mui/icons-material/{{member}}"},"lodash":{"transform":"lodash/{{member}}"}},"outputFileTracingRoot":"/workspace/repos/jgwill/smcraft","cacheComponents":false,"cacheLife":{"default":{"stale":300,"revalidate":900,"expire":4294967294},"seconds":{"stale":30,"revalidate":1,"expire":60},"minutes":{"stale":300,"revalidate":60,"expire":3600},"hours":{"stale":300,"revalidate":3600,"expire":86400},"days":{"stale":300,"revalidate":86400,"expire":604800},"weeks":{"stale":300,"revalidate":604800,"expire":2592000},"max":{"stale":300,"revalidate":2592000,"expire":31536000}},"cacheHandlers":{},"experimental":{"useSkewCookie":false,"cssChunking":true,"multiZoneDraftMode":false,"appNavFailHandling":false,"prerenderEarlyExit":true,"serverMinification":true,"linkNoTouchStart":false,"caseSensitiveRoutes":false,"dynamicOnHover":false,"preloadEntriesOnStart":true,"clientRouterFilter":true,"clientRouterFilterRedirects":false,"fetchCacheKeyPrefix":"","proxyPrefetch":"flexible","optimisticClientCache":true,"manualClientBasePath":false,"cpus":11,"memoryBasedWorkersCount":false,"imgOptConcurrency":null,"imgOptTimeoutInSeconds":7,"imgOptMaxInputPixels":268402689,"imgOptSequentialRead":null,"imgOptSkipMetadata":null,"isrFlushToDisk":true,"workerThreads":false,"optimizeCss":false,"nextScriptWorkers":false,"scrollRestoration":false,"externalDir":false,"disableOptimizedLoading":false,"gzipSize":true,"craCompat":false,"esmExternals":true,"fullySpecified":false,"swcTraceProfiling":false,"forceSwcTransforms":false,"largePageDataBytes":128000,"typedEnv":false,"parallelServerCompiles":false,"parallelServerBuildTraces":false,"ppr":false,"authInterrupts":false,"webpackMemoryOptimizations":false,"optimizeServerReact":true,"viewTransition":false,"removeUncaughtErrorAndRejectionListeners":false,"validateRSCRequestHeaders":false,"staleTimes":{"dynamic":0,"static":300},"reactDebugChannel":false,"serverComponentsHmrCache":true,"staticGenerationMaxConcurrency":8,"staticGenerationMinPagesPerWorker":25,"transitionIndicator":false,"inlineCss":false,"useCache":false,"globalNotFound":false,"browserDebugInfoInTerminal":false,"lockDistDir":true,"isolatedDevBuild":true,"proxyClientMaxBodySize":10485760,"hideLogsAfterAbort":false,"mcpServer":true,"turbopackFileSystemCacheForDev":true,"turbopackFileSystemCacheForBuild":false,"turbopackInferModuleSideEffects":false,"optimizePackageImports":["lucide-react","date-fns","lodash-es","ramda","antd","react-bootstrap","ahooks","@ant-design/icons","@headlessui/react","@headlessui-float/react","@heroicons/react/20/solid","@heroicons/react/24/solid","@heroicons/react/24/outline","@visx/visx","@tremor/react","rxjs","@mui/material","@mui/icons-material","recharts","react-use","effect","@effect/schema","@effect/platform","@effect/platform-node","@effect/platform-browser","@effect/platform-bun","@effect/sql","@effect/sql-mssql","@effect/sql-mysql2","@effect/sql-pg","@effect/sql-sqlite-node","@effect/sql-sqlite-bun","@effect/sql-sqlite-wasm","@effect/sql-sqlite-react-native","@effect/rpc","@effect/rpc-http","@effect/typeclass","@effect/experimental","@effect/opentelemetry","@material-ui/core","@material-ui/icons","@tabler/icons-react","mui-core","react-icons/ai","react-icons/bi","react-icons/bs","react-icons/cg","react-icons/ci","react-icons/di","react-icons/fa","react-icons/fa6","react-icons/fc","react-icons/fi","react-icons/gi","react-icons/go","react-icons/gr","react-icons/hi","react-icons/hi2","react-icons/im","react-icons/io","react-icons/io5","react-icons/lia","react-icons/lib","react-icons/lu","react-icons/md","react-icons/pi","react-icons/ri","react-icons/rx","react-icons/si","react-icons/sl","react-icons/tb","react-icons/tfi","react-icons/ti","react-icons/vsc","react-icons/wi"],"trustHostHeader":false,"isExperimentalCompile":false},"htmlLimitedBots":"[\\w-]+-Google|Google-[\\w-]+|Chrome-Lighthouse|Slurp|DuckDuckBot|baiduspider|yandex|sogou|bitlybot|tumblr|vkShare|quora link preview|redditbot|ia_archiver|Bingbot|BingPreview|applebot|facebookexternalhit|facebookcatalog|Twitterbot|LinkedInBot|Slackbot|Discordbot|WhatsApp|SkypeUriPreview|Yeti|googleweblight","bundlePagesRouterDependencies":false,"configFileName":"next.config.ts","outputFileTracingExcludes":{"*":["**/node_modules/typescript/**","**/node_modules/@img/**","**/node_modules/sharp/**"]},"turbopack":{"root":"/workspace/repos/jgwill/smcraft"},"transpilePackages":["@miadi/stateloom-protocol","@miadi/stateloom-client","@miadi/stateloom-react"],"distDirRoot":".next"}
+
+process.env.__NEXT_PRIVATE_STANDALONE_CONFIG = JSON.stringify(nextConfig)
+
+require('next')
+const { startServer } = require('next/dist/server/lib/start-server')
+
+if (
+  Number.isNaN(keepAliveTimeout) ||
+  !Number.isFinite(keepAliveTimeout) ||
+  keepAliveTimeout < 0
+) {
+  keepAliveTimeout = undefined
+}
+
+startServer({
+  dir,
+  isDev: false,
+  config: nextConfig,
+  hostname,
+  port: currentPort,
+  allowRetry: false,
+  keepAliveTimeout,
+}).catch((err) => {
+  console.error(err);
+  process.exit(1);
+});

package/server/src/app/api/config/route.ts

@@ -0,0 +1,29 @@
+/**
+ * GET /api/config — the browser's runtime configuration.
+ *
+ * `NEXT_PUBLIC_*` is inlined into the client bundle at BUILD time, which is
+ * fine when every operator builds their own copy and was the reason this app
+ * could not be published: a prebuilt bundle would carry whoever-built-it's
+ * bridge URL, baked in and unchangeable.
+ *
+ * So the client asks the server instead. This route is evaluated per request on
+ * the operator's own machine, reads their `STATELOOM_BRIDGE_URL`, and hands it
+ * back. The build-time value stays as a fallback so a locally built dev copy
+ * behaves exactly as it always has.
+ */
+import { envAlias } from "@miadi/stateloom-protocol";
+
+// Never cached and never statically evaluated: the whole point is that this
+// answer comes from the environment of the process serving the request.
+export const dynamic = "force-dynamic";
+export const revalidate = 0;
+
+export async function GET(): Promise<Response> {
+  return Response.json(
+    {
+      bridgeUrl: envAlias("BRIDGE_URL") ?? null,
+      projectFile: envAlias("PROJECT_FILE") ?? null,
+    },
+    { headers: { "cache-control": "no-store" } }
+  );
+}

package/server/src/app/api/file/route.ts

@@ -0,0 +1,29 @@
+import { NextResponse } from "next/server";
+import { existsSync, readFileSync, writeFileSync, statSync } from "fs";
+import { getProjectFilePath } from "@/lib/projectFile";
+
+export const dynamic = "force-dynamic";
+
+export async function GET() {
+  const path = getProjectFilePath();
+  if (!existsSync(path)) {
+    return NextResponse.json({ path, content: null, mtime: 0, exists: false });
+  }
+  const content = readFileSync(path, "utf8");
+  const mtime = statSync(path).mtimeMs;
+  return NextResponse.json({ path, content, mtime, exists: true });
+}
+
+export async function PUT(req: Request) {
+  const path = getProjectFilePath();
+  const body = await req.json();
+  if (typeof body?.content !== "string") {
+    return NextResponse.json(
+      { error: "Body must be { content: string }" },
+      { status: 400 }
+    );
+  }
+  writeFileSync(path, body.content, "utf8");
+  const mtime = statSync(path).mtimeMs;
+  return NextResponse.json({ path, mtime, ok: true });
+}

package/server/src/app/api/generate/route.ts

@@ -0,0 +1,52 @@
+import { NextRequest, NextResponse } from "next/server";
+import { execFileSync } from "child_process";
+import { writeFileSync, readFileSync, mkdtempSync, rmSync } from "fs";
+import { join } from "path";
+import { tmpdir } from "os";
+
+export async function POST(request: NextRequest) {
+  try {
+    const { definition, language } = await request.json();
+    const lang = language === "typescript" ? "typescript" : "python";
+
+    // Parse the definition (may be wrapped in { stateMachine: ... })
+    const parsed = typeof definition === "string" ? JSON.parse(definition) : definition;
+    const def = parsed.stateMachine ?? parsed.StateMachine ?? parsed;
+    // Ensure settings has required fields for smcg CLI
+    if (!def.settings) def.settings = {};
+    if (!def.settings.name) def.settings.name = def.state?.name ?? "machine";
+    if (!def.settings.namespace) def.settings.namespace = def.settings.name.toLowerCase().replace(/[^a-z0-9_]/g, "_");
+    const name = def.settings.name;
+
+    const tmpDir = mkdtempSync(join(tmpdir(), "smcraft-web-"));
+    // Sanitize the input filename — `name` derives from the request body.
+    const safeName = String(name).replace(/[^A-Za-z0-9_.-]/g, "_");
+    const inputFile = join(tmpDir, `${safeName}.smdf.json`);
+    const outputDir = join(tmpDir, "output");
+
+    try {
+      writeFileSync(inputFile, JSON.stringify(def, null, 2));
+      // execFileSync (no shell) — `name` from the request body cannot inject.
+      execFileSync("smcg", [inputFile, "-l", lang, "-o", outputDir], {
+        encoding: "utf-8",
+        timeout: 30000,
+      });
+
+      const ext = lang === "python" ? "py" : "ts";
+      // smcg outputs snake_case filenames (e.g. TestMachine -> test_machine_fsm.py)
+      const snakeName = name.replace(/([A-Z])/g, (m: string, p1: string, offset: number) => (offset ? "_" : "") + p1.toLowerCase()).replace(/[^a-z0-9_]/g, "_");
+      const outputFile = join(outputDir, `${snakeName}_fsm.${ext}`);
+      const code = readFileSync(outputFile, "utf-8");
+
+      return NextResponse.json({ code, language: lang });
+    } finally {
+      try { rmSync(tmpDir, { recursive: true, force: true }); } catch {}
+    }
+  } catch (error) {
+    const message = error instanceof Error ? error.message : "Code generation failed";
+    return NextResponse.json(
+      { error: message },
+      { status: 500 }
+    );
+  }
+}

package/server/src/app/api/rispec/route.ts

@@ -0,0 +1,223 @@
+import { NextResponse } from "next/server";
+import { existsSync, readFileSync } from "fs";
+import { resolve } from "path";
+import { getProjectFilePath } from "@/lib/projectFile";
+
+export const dynamic = "force-dynamic";
+
+interface SourceMeta {
+  pdeId?: string;
+  pdeFolder?: string;
+  originalPrompt?: string;
+}
+
+interface Definition {
+  settings: {
+    namespace: string;
+    name: string;
+    asynchronous: boolean;
+    _source?: SourceMeta;
+  };
+  events: Array<{ name: string; events: Array<{ id: string; description?: string }> }>;
+  state: StateDef;
+}
+
+interface StateDef {
+  name: string;
+  kind?: string;
+  description?: string;
+  transitions?: Array<{ event: string; nextState?: string; condition?: string }>;
+  states?: StateDef[];
+}
+
+interface PdeSource {
+  prompt?: string;
+  result?: {
+    primary?: { action?: string; target?: string };
+    directions?: { east?: Array<{ text: string }>; south?: Array<{ text: string }>; west?: Array<{ text: string }>; north?: Array<{ text: string }> };
+    actionStack?: Array<{ text: string; direction?: string }>;
+    ambiguities?: Array<{ text: string; suggestion?: string }>;
+  };
+}
+
+function loadPde(filePath: string, def: Definition): PdeSource | null {
+  const folder = def.settings._source?.pdeFolder;
+  const id = def.settings._source?.pdeId;
+  if (!folder || !id) return null;
+  const root = resolve(filePath, "..");
+  const candidates = [resolve(root, folder, `pde-${id}.json`), resolve(folder, `pde-${id}.json`)];
+  for (const p of candidates) {
+    if (!existsSync(p)) continue;
+    try {
+      return JSON.parse(readFileSync(p, "utf8"));
+    } catch {
+      /* try next */
+    }
+  }
+  return null;
+}
+
+function collectAll(s: StateDef): StateDef[] {
+  const out = [s];
+  for (const c of s.states ?? []) out.push(...collectAll(c));
+  return out;
+}
+
+function depth(s: StateDef, d = 0): number {
+  if (!s.states?.length) return d;
+  return Math.max(...s.states.map((c) => depth(c, d + 1)));
+}
+
+function countTransitions(s: StateDef): number {
+  let n = s.transitions?.length ?? 0;
+  for (const c of s.states ?? []) n += countTransitions(c);
+  return n;
+}
+
+function collectTransitions(s: StateDef): Array<{ from: string; event: string; next?: string; condition?: string }> {
+  const out: Array<{ from: string; event: string; next?: string; condition?: string }> = [];
+  for (const t of s.transitions ?? []) out.push({ from: s.name, event: t.event, next: t.nextState, condition: t.condition });
+  for (const c of s.states ?? []) out.push(...collectTransitions(c));
+  return out;
+}
+
+function renderStateSpec(s: StateDef, lines: string[], depthLevel: number): void {
+  const indent = "  ".repeat(depthLevel);
+  const kind = s.kind && s.kind !== "normal" ? ` *(${s.kind})*` : "";
+  lines.push(`${indent}- **${s.name}**${kind}${s.description ? ` — ${s.description}` : ""}`);
+  for (const t of s.transitions ?? []) {
+    lines.push(`${indent}  - on \`${t.event}\` ${t.nextState ? `→ \`${t.nextState}\`` : "(internal)"}`);
+  }
+  for (const c of s.states ?? []) renderStateSpec(c, lines, depthLevel + 1);
+}
+
+function glyph(d: string): string {
+  return { South: "🔥", East: "🌅", North: "❄️", West: "🌊" }[d] ?? "•";
+}
+
+function generateRispec(def: Definition, pde: PdeSource | null, intent: string | null, projectFile: string): string {
+  const lines: string[] = [];
+  const states = def.state.states ?? [];
+  const tagline = intent ?? pde?.result?.primary?.target ?? def.settings._source?.originalPrompt ?? `${def.settings.name} state machine`;
+
+  lines.push(`# ${def.settings.name} — RISE rispec`);
+  lines.push("");
+  lines.push(`> ${tagline}`);
+  lines.push("");
+  lines.push(`**Namespace:** \`${def.settings.namespace}\` · **Async:** ${def.settings.asynchronous}`);
+  if (def.settings._source?.pdeId) lines.push(`**Source PDE:** \`${def.settings._source.pdeId}\``);
+  lines.push("");
+  lines.push("---");
+  lines.push("");
+
+  const stateCount = collectAll(def.state).length - 1;
+  const eventCount = def.events.flatMap((s) => s.events ?? []).length;
+  lines.push("## R — Reverse Engineering");
+  lines.push("");
+  lines.push(`${def.settings.name} is modeled with ${stateCount} non-root states across ${depth(def.state)} level(s) of composition. Events: ${eventCount}. Transitions: ${countTransitions(def.state)}.`);
+  lines.push("");
+  if (pde?.prompt) {
+    lines.push("Originating prompt:");
+    lines.push("");
+    lines.push(`> ${pde.prompt}`);
+    lines.push("");
+  }
+
+  lines.push("## I — Intent");
+  lines.push("");
+  lines.push("**Desired Outcome**");
+  lines.push("");
+  lines.push(intent ?? pde?.result?.primary?.target ?? "_(no intent supplied)_");
+  lines.push("");
+  if (pde?.result?.directions?.east?.length) {
+    lines.push("**Vision (🌅 East)**");
+    lines.push("");
+    for (const v of pde.result.directions.east) lines.push(`- ${v.text}`);
+    lines.push("");
+  }
+  lines.push("**Structural Tension**");
+  lines.push("");
+  const hasFinal = collectAll(def.state).some((s) => s.kind === "final");
+  lines.push(`- *Current:* ${def.settings.name} ${hasFinal ? "is designed; terminal state reachable in principle." : "is partially modeled; no terminal state declared."}`);
+  lines.push(`- *Desired:* ${intent ?? pde?.result?.primary?.target ?? `${def.settings.name} runs end-to-end and reaches its terminal state.`}`);
+  lines.push("");
+
+  lines.push("## S — Specifications");
+  lines.push("");
+  lines.push("### States");
+  lines.push("");
+  for (const s of states) renderStateSpec(s, lines, 0);
+  lines.push("");
+
+  lines.push("### Events");
+  lines.push("");
+  for (const src of def.events) {
+    if (!src.events?.length) continue;
+    lines.push(`**${src.name}**`);
+    for (const e of src.events) lines.push(`- \`${e.id}\`${e.description ? ` — ${e.description}` : ""}`);
+    lines.push("");
+  }
+
+  lines.push("### Transitions (flat)");
+  lines.push("");
+  for (const t of collectTransitions(def.state)) {
+    lines.push(`- \`${t.from}\` --[${t.event}]-- ${t.next ? `→ ${t.next}` : "→ (internal)"}${t.condition ? ` *(when: ${t.condition})*` : ""}`);
+  }
+  lines.push("");
+
+  const mw = states.filter((s) => ["East", "South", "West", "North"].includes(s.name));
+  if (mw.length || pde?.result?.actionStack?.length) {
+    lines.push("### Action Steps");
+    lines.push("");
+    if (mw.length) {
+      for (const dirName of ["South", "East", "North", "West"]) {
+        const dir = states.find((s) => s.name === dirName);
+        if (!dir) continue;
+        lines.push(`**${glyph(dirName)} ${dirName}** — ${dir.description ?? ""}`);
+        for (const c of dir.states ?? []) lines.push(`1. ${c.description ?? c.name}`);
+        lines.push("");
+      }
+    } else if (pde?.result?.actionStack?.length) {
+      for (const a of pde.result.actionStack) {
+        lines.push(`- *(${a.direction ?? "?"})* ${a.text}`);
+      }
+      lines.push("");
+    }
+  }
+
+  if (pde?.result?.ambiguities?.length) {
+    lines.push("### Open Questions");
+    lines.push("");
+    for (const a of pde.result.ambiguities) lines.push(`- ${a.text}${a.suggestion ? `  \n  → *${a.suggestion}*` : ""}`);
+    lines.push("");
+  }
+
+  lines.push("## E — Exportation");
+  lines.push("");
+  lines.push("- Code: smcg / `generate_code` mcp tool (python | typescript)");
+  lines.push(`- Visual: this file is bound to \`${projectFile}\` via STATELOOM_PROJECT_FILE`);
+  lines.push("- SMDF: the canonical JSON is the file above");
+  lines.push("");
+
+  return lines.join("\n");
+}
+
+export async function POST(req: Request) {
+  const path = getProjectFilePath();
+  if (!existsSync(path)) {
+    return NextResponse.json({ error: `No file at ${path}` }, { status: 404 });
+  }
+  let intent: string | null = null;
+  try {
+    const body = await req.json();
+    if (typeof body?.intent === "string") intent = body.intent;
+  } catch {
+    /* no body */
+  }
+  const raw = readFileSync(path, "utf8");
+  const parsed = JSON.parse(raw);
+  const def: Definition = parsed.stateMachine ?? parsed.StateMachine ?? parsed;
+  const pde = loadPde(path, def);
+  const md = generateRispec(def, pde, intent, path);
+  return NextResponse.json({ rispec: md, projectFile: path });
+}

package/server/src/app/api/watch/route.ts

@@ -0,0 +1,68 @@
+import { existsSync, statSync, watch } from "fs";
+import { getProjectFilePath } from "@/lib/projectFile";
+
+export const dynamic = "force-dynamic";
+export const runtime = "nodejs";
+
+export async function GET() {
+  const path = getProjectFilePath();
+  const encoder = new TextEncoder();
+
+  const stream = new ReadableStream({
+    start(controller) {
+      const send = (event: string, data: unknown) => {
+        controller.enqueue(
+          encoder.encode(`event: ${event}\ndata: ${JSON.stringify(data)}\n\n`)
+        );
+      };
+
+      const initialMtime = existsSync(path) ? statSync(path).mtimeMs : 0;
+      send("hello", { path, mtime: initialMtime });
+
+      let watcher: ReturnType<typeof watch> | null = null;
+      try {
+        watcher = watch(path, { persistent: false }, () => {
+          if (!existsSync(path)) return;
+          const mtime = statSync(path).mtimeMs;
+          send("change", { path, mtime });
+        });
+      } catch {
+        send("error", { message: `Cannot watch ${path}` });
+      }
+
+      const ping = setInterval(() => {
+        try {
+          controller.enqueue(encoder.encode(`: ping\n\n`));
+        } catch {
+          /* stream closed */
+        }
+      }, 15000);
+
+      const cleanup = () => {
+        clearInterval(ping);
+        watcher?.close();
+        try {
+          controller.close();
+        } catch {
+          /* already closed */
+        }
+      };
+
+      // Closed by client → AbortController fires on the request
+      // Next.js handles it via cancel() below
+      (controller as unknown as { _cleanup?: () => void })._cleanup = cleanup;
+    },
+    cancel() {
+      const c = this as unknown as { _cleanup?: () => void };
+      c._cleanup?.();
+    },
+  });
+
+  return new Response(stream, {
+    headers: {
+      "Content-Type": "text/event-stream",
+      "Cache-Control": "no-cache, no-transform",
+      Connection: "keep-alive",
+    },
+  });
+}