@volter/editor-core 0.5.57

package/server/data-file-serialize.ts

@@ -0,0 +1,158 @@
+/**
+ * The `.data.json` DIFF CONTRACT, server-side and unforkable.
+ *
+ * A data asset's editor UI ships as a COPIED capability (`data-tables`), and a
+ * copy can be edited — which is the point, and also the reason none of this
+ * may live there. Key order and `$schema`-first serialization are the property
+ * that keeps a one-cell edit a one-line git diff; a project that reorganized
+ * its own table UI must not be able to reorganize the file's bytes with it. So
+ * the client posts PARSED VALUES for a path (`POST /__editor/data-file` with
+ * `values`) and this module owns the fold from those values to the exact text
+ * written to disk.
+ *
+ * Ported verbatim (behavior, not shape) from the editor-side data panel that
+ * used to own it. Two facts drive every line here:
+ *
+ * 1. `JSON.parse` REINDEXES integer-like keys. A JS object enumerates "1",
+ *    "2", "10" numerically-ascending no matter what order the file had, so
+ *    "the order this file has on disk" can only be recovered from the raw
+ *    TEXT, before parsing — {@link extractTopLevelKeyOrder}.
+ * 2. `JSON.stringify` of a spread-reordered object reindexes them again on the
+ *    way out, so the writer emits keys one at a time in the caller's order —
+ *    {@link serializeDataFile}.
+ */
+
+/** Scan a (valid-JSON) string literal starting at the opening quote; returns the index just past the closing quote. */
+function skipJsonString(text: string, i: number): number {
+  let j = i + 1;
+  while (j < text.length) {
+    const ch = text[j];
+    if (ch === '\\') {
+      j += 2;
+      continue;
+    }
+    if (ch === '"') return j + 1;
+    j++;
+  }
+  return j;
+}
+
+/** Scan one JSON value (string/object/array/number/bool/null) starting at `i`; returns the index just past it. Assumes well-formed JSON (only ever called on text `JSON.parse` already accepted). */
+function skipJsonValue(text: string, i: number): number {
+  const ch = text[i];
+  if (ch === '"') return skipJsonString(text, i);
+  if (ch === '{' || ch === '[') {
+    const close = ch === '{' ? '}' : ']';
+    let depth = 1;
+    let j = i + 1;
+    while (j < text.length && depth > 0) {
+      const c = text[j];
+      if (c === '"') {
+        j = skipJsonString(text, j);
+        continue;
+      }
+      if (c === '{' || c === '[') depth++;
+      else if (c === close || c === '}' || c === ']') depth--;
+      j++;
+    }
+    return j;
+  }
+  // number / true / false / null — run until a structural character.
+  let j = i;
+  while (j < text.length && !/[,}\]\s]/.test(text[j]!)) j++;
+  return j;
+}
+
+/**
+ * Read a top-level JSON object's key order straight off the SOURCE TEXT — see
+ * fact #1 in the module header. Only ever called with text `JSON.parse`
+ * already accepted, so this can assume well-formed JSON throughout.
+ */
+export function extractTopLevelKeyOrder(text: string): string[] {
+  const keys: string[] = [];
+  let i = 0;
+  const n = text.length;
+  const skipWs = () => {
+    while (i < n && /\s/.test(text[i]!)) i++;
+  };
+  skipWs();
+  if (text[i] !== '{') return keys;
+  i++;
+  skipWs();
+  while (i < n && text[i] !== '}') {
+    if (text[i] !== '"') break;
+    const keyEnd = skipJsonString(text, i);
+    const key = JSON.parse(text.slice(i, keyEnd)) as string;
+    if (!keys.includes(key)) keys.push(key);
+    i = keyEnd;
+    skipWs();
+    if (text[i] !== ':') break;
+    i++;
+    skipWs();
+    i = skipJsonValue(text, i);
+    skipWs();
+    if (text[i] === ',') {
+      i++;
+      skipWs();
+      continue;
+    }
+    break;
+  }
+  return keys;
+}
+
+/**
+ * Fold a commit's resulting keys into a stable order: `prevOrder` (the order
+ * the file currently has on disk) survives for every key still present, and
+ * any BRAND NEW key (add-row, a freshly-set nested field) is appended at the
+ * end in `Object.keys` order.
+ */
+export function nextKeyOrder(
+  prevOrder: string[] | undefined,
+  obj: Record<string, unknown>,
+): string[] {
+  const existing = prevOrder ?? Object.keys(obj);
+  const kept = [...new Set(existing)].filter((k) => k in obj);
+  const added = Object.keys(obj).filter((k) => !existing.includes(k));
+  return [...kept, ...added];
+}
+
+/**
+ * Serialize per the diff-minimal contract: `"$schema"` first, then every other
+ * key in `keyOrder` (falling back to `Object.keys(obj)` when the caller has
+ * none — a brand-new file), 2-space indent, trailing newline. Emitting the
+ * object key by key is deliberate; see fact #2 in the module header.
+ */
+export function serializeDataFile(obj: Record<string, unknown>, keyOrder?: string[]): string {
+  const hasSchema = '$schema' in obj;
+  const rest = (keyOrder ?? Object.keys(obj)).filter((k) => k !== '$schema' && k in obj);
+  const order = hasSchema ? ['$schema', ...rest] : rest;
+  if (order.length === 0) return '{}\n';
+  const lines = order.map((k) => {
+    const valueJson = JSON.stringify(obj[k], null, 2);
+    return `  ${JSON.stringify(k)}: ${valueJson.split('\n').join('\n  ')}`;
+  });
+  return `{\n${lines.join(',\n')}\n}\n`;
+}
+
+/**
+ * The whole server-side fold in one call: the file's CURRENT text (absent for
+ * a file that does not exist yet) plus the values the client posted, giving
+ * the exact bytes to write.
+ */
+export function foldDataFileText(
+  currentText: string | null,
+  values: Record<string, unknown>,
+): string {
+  let prevOrder: string[] | undefined;
+  if (currentText !== null) {
+    try {
+      JSON.parse(currentText);
+      prevOrder = extractTopLevelKeyOrder(currentText);
+    } catch {
+      // Unparseable file on disk — nothing to carry, so the posted values
+      // define the order. Never a reason to refuse the write.
+    }
+  }
+  return serializeDataFile(values, nextKeyOrder(prevOrder, values));
+}

package/server/editor-brand-html.ts

@@ -0,0 +1,72 @@
+import {
+  EDITOR_BRAND,
+  editorAppIconSvg,
+  editorDocumentTitle,
+} from '@volter/editor-sdk/session/editor-brand';
+
+function escapeHtml(value: string): string {
+  return value.replace(
+    /[&<>"']/g,
+    (character) =>
+      ({
+        '&': '&amp;',
+        '<': '&lt;',
+        '>': '&gt;',
+        '"': '&quot;',
+        "'": '&#39;',
+      })[character] ?? character,
+  );
+}
+
+export interface EditorBrandPageOptions {
+  readonly subject?: string;
+  readonly description: string;
+  /** Trusted, server-owned markup rendered inside the brand card. */
+  readonly contentHtml: string;
+  /** Trusted, server-owned script body. */
+  readonly scriptHtml?: string;
+  readonly socialPreview?: boolean;
+}
+
+/**
+ * Render the editor's small server-owned HTML surfaces (auth, share, yield).
+ * These pages intentionally stay dependency-free because they also appear
+ * while the main editor bundle is unavailable.
+ */
+export function renderEditorBrandPage(options: EditorBrandPageOptions): string {
+  const title = editorDocumentTitle(options.subject);
+  const favicon = `data:image/svg+xml,${encodeURIComponent(editorAppIconSvg())}`;
+  const social = options.socialPreview
+    ? `<meta property="og:type" content="website">
+<meta property="og:site_name" content="${escapeHtml(EDITOR_BRAND.name)}">
+<meta property="og:title" content="${escapeHtml(title)}">
+<meta property="og:description" content="${escapeHtml(options.description)}">
+
+<meta name="twitter:card" content="summary">
+<meta name="twitter:title" content="${escapeHtml(title)}">
+<meta name="twitter:description" content="${escapeHtml(options.description)}">
+`
+    : '';
+  const script = options.scriptHtml ? `<script>${options.scriptHtml}</script>` : '';
+  return `<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width,initial-scale=1">
+<meta name="theme-color" content="${EDITOR_BRAND.themeColor}">
+<meta name="robots" content="noindex,nofollow">
+<meta name="description" content="${escapeHtml(options.description)}">
+<link rel="icon" href="${favicon}" type="image/svg+xml">
+<title>${escapeHtml(title)}</title>
+${social}
+<style>
+:root{color-scheme:dark;font-family:Inter,ui-sans-serif,system-ui,-apple-system,BlinkMacSystemFont,"Segoe UI",sans-serif;background:${EDITOR_BRAND.themeColor};color:#e8edf3}
+*{box-sizing:border-box}body{margin:0;min-height:100vh;display:grid;place-items:center;padding:24px;background:radial-gradient(circle at 50% 30%,#1c2a3a 0,${EDITOR_BRAND.themeColor} 52%,#0b0e13 100%)}
+.brand-card{width:min(440px,100%);padding:34px;text-align:center;border:1px solid rgba(255,255,255,.1);border-radius:20px;background:rgba(23,28,35,.92);box-shadow:0 22px 60px rgba(0,0,0,.38)}
+.brand-mark{width:68px;height:68px;margin:0 auto 20px}.brand-mark svg{display:block;width:100%;height:100%}h1{margin:0 0 10px;font-size:22px;line-height:1.25;color:#f4f6f8}p{margin:0;color:#aeb9c6;font-size:14px;line-height:1.6}
+button,a.brand-action{display:inline-block;margin-top:20px;padding:9px 17px;border:1px solid #3a526c;border-radius:8px;background:#20354c;color:#eaf3ff;font:600 14px inherit;text-decoration:none;cursor:pointer}button:hover,a.brand-action:hover{background:#294561;border-color:${EDITOR_BRAND.accentColor}}
+</style>
+</head>
+<body><main class="brand-card"><div class="brand-mark">${editorAppIconSvg()}</div>${options.contentHtml}</main>${script}</body>
+</html>`;
+}

package/server/editor-control-socket.ts

@@ -0,0 +1,366 @@
+/**
+ * The editor tab's duplex control socket — a WebSocket upgrade on the SAME
+ * path as the SSE stream (`/__editor/events`), carrying the SAME named events
+ * downstream and the tab's control replies upstream.
+ *
+ * Why it exists (measured 2026-08-09): a cold editor boot blocked a real
+ * tab's main thread for 60-100s. A blocked main thread can neither issue nor
+ * answer a `fetch`, so every receipt/result/state POST stopped — and the
+ * relay, which could only see silence, refused five plays that all executed
+ * later. Two things fix that here:
+ *
+ *  - Upstream control traffic rides the ALREADY-OPEN socket instead of
+ *    opening new HTTP requests, so it never queues behind a module flood in
+ *    the browser's per-origin connection pool.
+ *  - Liveness stops being a guess. The browser's NETWORK stack answers
+ *    protocol pings while the main thread is blocked, and the page's INLINE
+ *    bootstrap (index.html, attached before any module loads) answers a
+ *    `control-echo`. Pong-fresh + echo-silent is "alive but busy" as a
+ *    measured fact; an unanswered echo can never mean "the listener was not
+ *    wired up yet", because the responder exists before the module graph does.
+ *
+ * Deliberately no frame-rate or rendering signal: games legitimately run
+ * `frameloop: 'never'` and the engine hidden-pauses loops in a background
+ * tab, so anything rAF-shaped would read a healthy tab as dead.
+ */
+
+import type { Server as HttpServer, IncomingMessage } from 'node:http';
+import type { Duplex } from 'node:stream';
+import {
+  type EditorControlLifecycle,
+  parseEditorControlLifecycle,
+} from '@volter/editor-sdk/session/editor-control-lifecycle';
+import { type WebSocket, WebSocketServer } from 'ws';
+import type { EditorSocketClient } from './editor-sse';
+
+/** The one path both transports answer on. */
+export const EDITOR_EVENTS_PATH = '/__editor/events';
+
+/**
+ * Protocol-ping cadence. Short enough that a pong age reported in a refusal
+ * is meaningful evidence ("answered 3s ago" = the socket is genuinely live),
+ * long enough to be invisible next to the keepalive it replaces.
+ */
+export const CONTROL_PING_INTERVAL_MS = 10_000;
+
+/** How long the main-thread echo gets before it counts as unanswered. */
+export const CONTROL_ECHO_TIMEOUT_MS = 1_000;
+
+/**
+ * The socket ENDED WITH NO CLOSE FRAME — RFC 6455's 1006, which no endpoint is
+ * allowed to send and only an observer can synthesize. It is the shape a
+ * KILLED browser renderer process leaves behind (a tab that closes normally
+ * sends a frame), so it is also the discriminator the tab-death profile keys
+ * off. One owner of the literal: this file synthesizes it below,
+ * `editor-server.ts` reads it.
+ */
+export const ABNORMAL_SOCKET_CLOSE = 1006;
+
+/**
+ * The capability frame. Sent ONLY over a native socket, never on the SSE
+ * stream — the share tunnel's gateway bridges the SSE stream into its own
+ * WebSocket, and that socket does NOT accept upstream control frames. A tab
+ * behind the tunnel therefore never sees this and keeps POSTing, which is
+ * exactly right.
+ */
+const DUPLEX_READY_EVENT = 'control-duplex';
+
+export interface EditorControlConnection {
+  /** The pool handle for this socket. */
+  readonly client: EditorSocketClient;
+  /** The upgrade request's URL, for query parameters. */
+  readonly url: URL;
+  /** The raw upgrade request, for header-derived identity. */
+  readonly request: IncomingMessage;
+  /** Deliver one framed event before the client is pooled. */
+  send(event: string, data: string, id?: string): void;
+  /** Close the socket with a reason (rejected identity, session end). */
+  close(code: number, reason: string): void;
+}
+
+/**
+ * Another WebSocket path this session owns (the tab heartbeat).
+ *
+ * It rides the control socket's ONE `upgrade` listener rather than adding a
+ * second, because the fallthrough branch below has to know whether ANY editor
+ * path claimed the socket before it destroys it — and `listenerCount` cannot
+ * answer that once two of our own listeners are competing to say "not mine".
+ */
+export interface RawSocketRoute {
+  readonly path: string;
+  /** Same shape as the control socket's own gate; a string refuses with 403. */
+  authorize(request: IncomingMessage, url: URL): string | null;
+  open(socket: WebSocket, url: URL, request: IncomingMessage): void;
+}
+
+export interface EditorControlSocketOptions {
+  /**
+   * Reject the upgrade BEFORE the handshake. Return an error string to
+   * refuse (sent as a plain 403 body, the same shape the SSE route answers
+   * with), or null to accept.
+   */
+  authorize(request: IncomingMessage, url: URL): string | null;
+  /**
+   * Register the open socket; the returned function runs once on close, and
+   * is handed the WebSocket close code/reason. Those two are the only honest
+   * answer to "why did this tab's channel go away" — the journal quotes them
+   * verbatim rather than inferring a story from the silence.
+   */
+  open(connection: EditorControlConnection): (close?: { code: number; reason: string }) => void;
+  /** The duplex capability was granted to this socket (journalling hook). */
+  duplexGranted?(connection: EditorControlConnection): void;
+  /** One upstream control frame from the tab. */
+  message(
+    type: string,
+    payload: Record<string, unknown>,
+    connection: EditorControlConnection,
+    lifecycle: EditorControlLifecycle | null,
+    lifecycleMalformed: boolean,
+  ): void;
+  /** Other WebSocket paths this one upgrade listener also routes. */
+  extraRoutes?: readonly RawSocketRoute[] | undefined;
+}
+
+export interface EditorControlSocketServer {
+  /**
+   * Handle `upgrade` on this HTTP server.
+   *
+   * Routes by PATHNAME and passes every other upgrade through untouched —
+   * Vite's HMR socket may share this server. When this is the only `upgrade`
+   * listener there is nobody to pass to, so the socket is destroyed, which is
+   * exactly what Node does by default with no listener at all.
+   */
+  attach(server: HttpServer): void;
+  /** Close every live control socket (server shutdown). */
+  close(): void;
+}
+
+/**
+ * One upstream `{ type, payload }` frame, or null if it is not one. A
+ * malformed frame is dropped, never partially read.
+ *
+ * The discriminator and the payload live in SEPARATE keys, and that
+ * separation is load-bearing in both directions. Flattened
+ * (`{ type, ...payload }`) the envelope leaked its own `type` into the state
+ * the server stored, so `vgai status` printed a field the tab never
+ * reported — on the exact seam this transport promises the POST route
+ * cannot drift from. And a payload key named `type` (a state snapshot is an
+ * open-ended object) would have overwritten the discriminator on the way
+ * out, turning a routine state report into an unknown control frame:
+ * dropped silently, health left stale, and the next refusal quoting a
+ * silence the tab never chose.
+ */
+function parseControlFrame(raw: unknown): {
+  type: string;
+  payload: Record<string, unknown>;
+  lifecycle: EditorControlLifecycle | null;
+  lifecycleMalformed: boolean;
+} | null {
+  let frame: unknown;
+  try {
+    frame = JSON.parse(String(raw));
+  } catch {
+    return null;
+  }
+  if (!frame || typeof frame !== 'object') return null;
+  const type = (frame as Record<string, unknown>)['type'];
+  if (typeof type !== 'string') return null;
+  const body = (frame as Record<string, unknown>)['payload'];
+  const rawLifecycle = (frame as Record<string, unknown>)['lifecycle'];
+  const lifecycle = parseEditorControlLifecycle(rawLifecycle);
+  return {
+    type,
+    payload: body && typeof body === 'object' ? (body as Record<string, unknown>) : {},
+    lifecycle,
+    lifecycleMalformed: rawLifecycle !== undefined && lifecycle === null,
+  };
+}
+
+export function createEditorControlSocket(
+  options: EditorControlSocketOptions,
+): EditorControlSocketServer {
+  const sockets = new WebSocketServer({ noServer: true });
+
+  const onUpgrade = (
+    server: HttpServer,
+    request: IncomingMessage,
+    socket: Duplex,
+    head: Buffer,
+  ): void => {
+    let url: URL;
+    try {
+      url = new URL(request.url ?? '/', 'http://editor.local');
+    } catch {
+      return;
+    }
+    const extra = (options.extraRoutes ?? []).find((route) => route.path === url.pathname);
+    if (extra) {
+      const extraRefusal = extra.authorize(request, url);
+      if (extraRefusal !== null) {
+        socket.end(
+          `HTTP/1.1 403 Forbidden\r\nConnection: close\r\nContent-Type: text/plain\r\n\r\n${extraRefusal}`,
+        );
+        return;
+      }
+      sockets.handleUpgrade(request, socket, head, (ws) => extra.open(ws, url, request));
+      return;
+    }
+    if (url.pathname !== EDITOR_EVENTS_PATH) {
+      // Not ours. Another listener (Vite HMR, the share gateway) owns it — or
+      // nobody does, in which case leaving the socket open would leak it.
+      if (server.listenerCount('upgrade') <= 1) socket.destroy();
+      return;
+    }
+    const refusal = options.authorize(request, url);
+    if (refusal !== null) {
+      socket.end(
+        `HTTP/1.1 403 Forbidden\r\nConnection: close\r\nContent-Type: text/plain\r\n\r\n${refusal}`,
+      );
+      return;
+    }
+    sockets.handleUpgrade(request, socket, head, (ws) => {
+      let closed = false;
+      let lastPongAt: number | null = null;
+      let echoSequence = 0;
+      const pendingEchoes = new Map<string, (answered: boolean) => void>();
+
+      const sendFrame = (event: string, data: string, id?: string): boolean => {
+        if (closed || ws.readyState !== ws.OPEN) return false;
+        try {
+          ws.send(JSON.stringify(id === undefined ? { event, data } : { event, data, id }));
+          return true;
+        } catch {
+          return false;
+        }
+      };
+
+      const client: EditorSocketClient = {
+        kind: 'socket',
+        sendFrame,
+        isClosed: () => closed || ws.readyState !== ws.OPEN,
+        lastPongAgeMs: () => (lastPongAt === null ? null : Date.now() - lastPongAt),
+        echo: (timeoutMs) =>
+          new Promise<boolean>((resolve) => {
+            if (closed || ws.readyState !== ws.OPEN) {
+              resolve(false);
+              return;
+            }
+            const id = `echo-${++echoSequence}`;
+            const timer = setTimeout(() => {
+              pendingEchoes.delete(id);
+              resolve(false);
+            }, timeoutMs);
+            timer.unref?.();
+            pendingEchoes.set(id, (answered) => {
+              clearTimeout(timer);
+              resolve(answered);
+            });
+            if (!sendFrame('control-echo', id)) {
+              pendingEchoes.delete(id);
+              clearTimeout(timer);
+              resolve(false);
+            }
+          }),
+        close: (code, reason) => {
+          try {
+            ws.close(code, reason);
+          } catch {
+            /* The close event owns teardown if the socket is still alive. */
+          }
+        },
+      };
+
+      const connection: EditorControlConnection = {
+        client,
+        url,
+        request,
+        send: (event, data, id) => {
+          sendFrame(event, data, id);
+        },
+        close: (code, reason) => {
+          try {
+            ws.close(code, reason);
+          } catch {
+            /* already gone */
+          }
+        },
+      };
+
+      const dispose = options.open(connection);
+
+      // Tell the page this socket takes upstream control frames. Only the
+      // native transport ever emits this (see DUPLEX_READY_EVENT).
+      if (sendFrame(DUPLEX_READY_EVENT, JSON.stringify({ ok: true }))) {
+        options.duplexGranted?.(connection);
+      }
+
+      // Ping immediately so the first refusal in this connection's life can
+      // still quote a real pong age, then on the standing cadence.
+      ws.on('pong', () => {
+        lastPongAt = Date.now();
+      });
+      const ping = () => {
+        if (closed || ws.readyState !== ws.OPEN) return;
+        try {
+          ws.ping();
+        } catch {
+          /* the close handler owns teardown */
+        }
+      };
+      ping();
+      const pingTimer = setInterval(ping, CONTROL_PING_INTERVAL_MS);
+      pingTimer.unref?.();
+
+      ws.on('message', (raw) => {
+        const frame = parseControlFrame(raw);
+        if (!frame) return;
+        if (frame.type === 'echo-reply') {
+          const id = frame.payload['id'];
+          if (typeof id !== 'string') return;
+          pendingEchoes.get(id)?.(true);
+          pendingEchoes.delete(id);
+          return;
+        }
+        options.message(
+          frame.type,
+          frame.payload,
+          connection,
+          frame.lifecycle,
+          frame.lifecycleMalformed,
+        );
+      });
+
+      const onClosed = (code?: number, reason?: Buffer | string) => {
+        if (closed) return;
+        closed = true;
+        clearInterval(pingTimer);
+        for (const settle of [...pendingEchoes.values()]) settle(false);
+        pendingEchoes.clear();
+        dispose({
+          code: typeof code === 'number' ? code : ABNORMAL_SOCKET_CLOSE,
+          reason: reason === undefined ? '' : String(reason),
+        });
+      };
+      ws.on('close', onClosed);
+      ws.on('error', () => onClosed());
+    });
+  };
+
+  return {
+    attach(server) {
+      server.on('upgrade', (request, socket, head) =>
+        onUpgrade(server, request, socket as Duplex, head),
+      );
+    },
+    close() {
+      for (const ws of sockets.clients) {
+        try {
+          ws.close(1001, 'editor session ended');
+        } catch {
+          /* best effort */
+        }
+      }
+      sockets.close();
+    },
+  };
+}