@vgai/live 0.5.20 → 0.5.21

package/dist/session.js

@@ -92,21 +92,61 @@ function readProjectSession(projectRoot) {
         return null;
     }
 }
-async function verifyProjectSession(hint, projectRoot) {
+/**
+ * WHICH PROJECT a `/__editor/project` body says its server is serving, and the
+ * reason it cannot describe it.
+ *
+ * `serving` is the server's own statement of "I AM serving this project, I
+ * just cannot describe it" — its manifest is unparseable or fails strict
+ * validation. The route added it because a bare `{ project: null }` there is
+ * indistinguishable from "no project open"; reading only `project.path`
+ * reproduces that collapse on this side, and the cost is the worst kind of
+ * wrong answer: this door refused a session that WAS open on the caller's
+ * project with "no live editor session found … (N other live session(s) found,
+ * but none open this project)" — sending the operator to start an editor that
+ * was already running, with the real defect (their own manifest) never named.
+ */
+function servedProject(body) {
+    const b = body;
+    return {
+        path: b.project?.path ?? b.serving?.path ?? null,
+        manifestError: b.project ? null : (b.serving?.error ?? null),
+    };
+}
+/**
+ * What the server on `port` says it serves — `undefined` when it did not
+ * answer at all. One probe: the manifest failure arrives with the path, so
+ * neither the hint path nor the refusal path pays a second round trip.
+ */
+async function probeServedProject(port) {
     try {
-        const response = await fetch(`http://127.0.0.1:${hint.port}/__editor/project`, {
+        const response = await fetch(`http://127.0.0.1:${port}/__editor/project`, {
             signal: AbortSignal.timeout(EDITOR_SESSION_DISCOVERY_TIMEOUT_MS),
         });
         if (!response.ok)
-            return false;
-        const body = (await response.json());
-        const servedProject = body.project?.path;
-        return (servedProject !== undefined && canonicalPath(servedProject) === canonicalPath(projectRoot));
+            return undefined;
+        return servedProject(await response.json());
     }
     catch {
-        return false;
+        return undefined;
     }
 }
+/**
+ * The refusal for a session that IS this project's and cannot be driven,
+ * because the project's manifest does not load.
+ *
+ * A refusal, not an attach: with no readable manifest the editor page itself
+ * renders its startup-error screen, so there is no editor and no game behind
+ * this door to bind `{ editor, game, page, tools, session }` to. What changed
+ * is only that it now says the true thing — the failing file and key — instead
+ * of "no live editor session found", which sent operators to start an editor
+ * that was already running while their actual defect went unnamed.
+ */
+function manifestRefusal(projectRoot, manifestError) {
+    return new Error(`@vgai/live: the editor session for ${projectRoot} is live, but its vgai.project.json does ` +
+        'not load, so there is no editor or game to drive — the editor page is showing this same ' +
+        `error. Fix the manifest and retry; the session recovers on save, no restart needed.\n${manifestError}`);
+}
 /**
  * Resolve `projectDir` (default `process.cwd()`) to the port of its already-
  * running `vgai edit` session. Throws a descriptive error (never hangs
@@ -127,9 +167,24 @@ export async function resolveSession(projectDir = process.cwd(), deps = {}) {
     // deadline. The live probe remains authoritative, so a stale file cannot
     // attach us to the wrong project or port.
     const localHint = (deps.readProjectSession ?? readProjectSession)(projectRoot);
-    if (localHint &&
-        (await (deps.verifyProjectSession ?? verifyProjectSession)(localHint, projectRoot))) {
-        return { port: localHint.port, projectRoot };
+    if (localHint) {
+        // `deps.verifyProjectSession` is the test-only override and keeps its
+        // boolean meaning: "this hint is this project's session, and healthy".
+        // With no override we read the probe ourselves, because the same response
+        // carries WHY a served project cannot be described.
+        if (deps.verifyProjectSession) {
+            if (await deps.verifyProjectSession(localHint, projectRoot)) {
+                return { port: localHint.port, projectRoot };
+            }
+        }
+        else {
+            const served = await probeServedProject(localHint.port);
+            if (served?.path != null && canonicalPath(served.path) === canonicalPath(projectRoot)) {
+                if (served.manifestError !== null)
+                    throw manifestRefusal(projectRoot, served.manifestError);
+                return { port: localHint.port, projectRoot };
+            }
+        }
     }
     let sessions;
     try {
@@ -150,5 +205,7 @@ export async function resolveSession(projectDir = process.cwd(), deps = {}) {
                     'never silently attaches to a different project.)'
                 : ''));
     }
+    if (match.manifestError != null)
+        throw manifestRefusal(projectRoot, match.manifestError);
     return { port: match.port, projectRoot };
 }

package/package.json

@@ -2,7 +2,7 @@
   "name": "@vgai/live",
   "author": "Volter AI, Inc.",
   "license": "Apache-2.0",
-  "version": "0.5.20",
+  "version": "0.5.21",
   "type": "module",
   "repository": {
     "type": "git",
@@ -32,8 +32,8 @@
     "prepack": "npm run build"
   },
   "dependencies": {
-    "@vgai/editor-sdk": "0.5.20",
-    "@vgai/sdk": "0.5.20"
+    "@vgai/editor-sdk": "0.5.21",
+    "@vgai/sdk": "0.5.21"
   },
   "peerDependencies": {
     "@playwright/test": ">=1.58.2 <2"

package/src/session.ts

@@ -130,25 +130,69 @@ function readProjectSession(projectRoot: string): ProjectSessionHint | null {
   }
 }
 
-async function verifyProjectSession(
-  hint: ProjectSessionHint,
-  projectRoot: string,
-): Promise<boolean> {
+/**
+ * WHICH PROJECT a `/__editor/project` body says its server is serving, and the
+ * reason it cannot describe it.
+ *
+ * `serving` is the server's own statement of "I AM serving this project, I
+ * just cannot describe it" — its manifest is unparseable or fails strict
+ * validation. The route added it because a bare `{ project: null }` there is
+ * indistinguishable from "no project open"; reading only `project.path`
+ * reproduces that collapse on this side, and the cost is the worst kind of
+ * wrong answer: this door refused a session that WAS open on the caller's
+ * project with "no live editor session found … (N other live session(s) found,
+ * but none open this project)" — sending the operator to start an editor that
+ * was already running, with the real defect (their own manifest) never named.
+ */
+function servedProject(body: unknown): { path: string | null; manifestError: string | null } {
+  const b = body as {
+    project?: { path?: string } | null;
+    serving?: { path?: string; error?: string } | null;
+  };
+  return {
+    path: b.project?.path ?? b.serving?.path ?? null,
+    manifestError: b.project ? null : (b.serving?.error ?? null),
+  };
+}
+
+/**
+ * What the server on `port` says it serves — `undefined` when it did not
+ * answer at all. One probe: the manifest failure arrives with the path, so
+ * neither the hint path nor the refusal path pays a second round trip.
+ */
+async function probeServedProject(
+  port: number,
+): Promise<{ path: string | null; manifestError: string | null } | undefined> {
   try {
-    const response = await fetch(`http://127.0.0.1:${hint.port}/__editor/project`, {
+    const response = await fetch(`http://127.0.0.1:${port}/__editor/project`, {
       signal: AbortSignal.timeout(EDITOR_SESSION_DISCOVERY_TIMEOUT_MS),
     });
-    if (!response.ok) return false;
-    const body = (await response.json()) as { project?: { path?: string } | null };
-    const servedProject = body.project?.path;
-    return (
-      servedProject !== undefined && canonicalPath(servedProject) === canonicalPath(projectRoot)
-    );
+    if (!response.ok) return undefined;
+    return servedProject(await response.json());
   } catch {
-    return false;
+    return undefined;
   }
 }
 
+/**
+ * The refusal for a session that IS this project's and cannot be driven,
+ * because the project's manifest does not load.
+ *
+ * A refusal, not an attach: with no readable manifest the editor page itself
+ * renders its startup-error screen, so there is no editor and no game behind
+ * this door to bind `{ editor, game, page, tools, session }` to. What changed
+ * is only that it now says the true thing — the failing file and key — instead
+ * of "no live editor session found", which sent operators to start an editor
+ * that was already running while their actual defect went unnamed.
+ */
+function manifestRefusal(projectRoot: string, manifestError: string): Error {
+  return new Error(
+    `@vgai/live: the editor session for ${projectRoot} is live, but its vgai.project.json does ` +
+      'not load, so there is no editor or game to drive — the editor page is showing this same ' +
+      `error. Fix the manifest and retry; the session recovers on save, no restart needed.\n${manifestError}`,
+  );
+}
+
 /**
  * Resolve `projectDir` (default `process.cwd()`) to the port of its already-
  * running `vgai edit` session. Throws a descriptive error (never hangs
@@ -176,11 +220,22 @@ export async function resolveSession(
   // deadline. The live probe remains authoritative, so a stale file cannot
   // attach us to the wrong project or port.
   const localHint = (deps.readProjectSession ?? readProjectSession)(projectRoot);
-  if (
-    localHint &&
-    (await (deps.verifyProjectSession ?? verifyProjectSession)(localHint, projectRoot))
-  ) {
-    return { port: localHint.port, projectRoot };
+  if (localHint) {
+    // `deps.verifyProjectSession` is the test-only override and keeps its
+    // boolean meaning: "this hint is this project's session, and healthy".
+    // With no override we read the probe ourselves, because the same response
+    // carries WHY a served project cannot be described.
+    if (deps.verifyProjectSession) {
+      if (await deps.verifyProjectSession(localHint, projectRoot)) {
+        return { port: localHint.port, projectRoot };
+      }
+    } else {
+      const served = await probeServedProject(localHint.port);
+      if (served?.path != null && canonicalPath(served.path) === canonicalPath(projectRoot)) {
+        if (served.manifestError !== null) throw manifestRefusal(projectRoot, served.manifestError);
+        return { port: localHint.port, projectRoot };
+      }
+    }
   }
 
   let sessions: EditorSessionInfo[];
@@ -209,5 +264,7 @@ export async function resolveSession(
     );
   }
 
+  if (match.manifestError != null) throw manifestRefusal(projectRoot, match.manifestError);
+
   return { port: match.port, projectRoot };
 }