@jxsuite/studio 0.33.0 → 0.35.0

package/src/services/ai-session-store.ts

@@ -0,0 +1,250 @@
+/// <reference lib="dom" />
+/**
+ * Ai-session-store.js — project-scoped multi-session chat history in localStorage.
+ *
+ * Pure storage CRUD for the assistant's conversations: a small index of session
+ * metadata plus one payload key per session, so per-send writes touch a single
+ * conversation. No reactivity and no chat-state knowledge — document-assistant
+ * owns the live session; this module only loads/saves plain message arrays.
+ *
+ * Cross-window note: multiple studio windows share these keys; index writes are
+ * last-write-wins, which is accepted for chat history.
+ *
+ * @license MIT
+ */
+
+const INDEX_KEY_PREFIX = "jx-ai-chat-sessions";
+const PAYLOAD_KEY_PREFIX = "jx-ai-chat-session";
+const LEGACY_KEY_PREFIX = "jx-ai-chat-history";
+
+/** Most sessions kept per project — oldest by updatedAt evicted beyond this. */
+export const MAX_SESSIONS = 20;
+/** Most messages persisted per session (matches the pre-session store's cap). */
+export const MAX_PERSIST_MESSAGES = 50;
+
+const DEFAULT_TITLE = "New chat";
+const MAX_TITLE_LENGTH = 60;
+
+export interface SessionMeta {
+  id: string;
+  title: string;
+  createdAt: number;
+  updatedAt: number;
+  messageCount: number;
+}
+
+interface SessionIndex {
+  version: 1;
+  activeId: string | null;
+  /** Sorted by updatedAt descending. */
+  sessions: SessionMeta[];
+}
+
+/** The persisted message shape — structurally the chat-state Message JSON. */
+export interface PersistedMessage {
+  id?: string;
+  role: string;
+  content: string;
+  toolCalls?: unknown[];
+  toolCallId?: string;
+  timestamp?: number;
+}
+
+// ─── Keys ───────────────────────────────────────────────────────────────────
+
+/** Project-scoped index key; falls back to a shared key when no project is open. */
+function indexKey(root: string) {
+  return root ? `${INDEX_KEY_PREFIX}:${root}` : INDEX_KEY_PREFIX;
+}
+
+function payloadKey(root: string, id: string) {
+  return root ? `${PAYLOAD_KEY_PREFIX}:${root}:${id}` : `${PAYLOAD_KEY_PREFIX}:${id}`;
+}
+
+function legacyKey(root: string) {
+  return root ? `${LEGACY_KEY_PREFIX}:${root}` : LEGACY_KEY_PREFIX;
+}
+
+// ─── Storage helpers (defensive: quota/unavailable/corrupt → absent) ────────
+
+function readJson<T>(key: string): T | null {
+  try {
+    const raw = globalThis.localStorage?.getItem(key);
+    return raw ? (JSON.parse(raw) as T) : null;
+  } catch {
+    return null;
+  }
+}
+
+function writeJson(key: string, value: unknown) {
+  try {
+    globalThis.localStorage?.setItem(key, JSON.stringify(value));
+  } catch {
+    // Storage full or unavailable — chat history is not critical.
+  }
+}
+
+function removeKey(key: string) {
+  try {
+    globalThis.localStorage?.removeItem(key);
+  } catch {
+    /* Ignore */
+  }
+}
+
+// ─── Index ──────────────────────────────────────────────────────────────────
+
+function emptyIndex(): SessionIndex {
+  return { version: 1, activeId: null, sessions: [] };
+}
+
+/**
+ * Read the session index for a project, migrating the pre-session single-conversation store
+ * (`jx-ai-chat-history:<root>`) into the first session on first access.
+ */
+function readIndex(root: string): SessionIndex {
+  const stored = readJson<SessionIndex>(indexKey(root));
+  if (stored && Array.isArray(stored.sessions)) {
+    return { ...emptyIndex(), ...stored };
+  }
+  return migrateLegacy(root) ?? emptyIndex();
+}
+
+function writeIndex(root: string, index: SessionIndex) {
+  index.sessions.sort((a, b) => b.updatedAt - a.updatedAt);
+  writeJson(indexKey(root), index);
+}
+
+/** Convert a legacy single-conversation store into a one-session index, if present. */
+function migrateLegacy(root: string): SessionIndex | null {
+  const msgs = readJson<PersistedMessage[]>(legacyKey(root));
+  removeKey(legacyKey(root));
+  if (!Array.isArray(msgs) || msgs.length === 0) {
+    return null;
+  }
+  const timestamps = msgs.map((m) => m.timestamp).filter((t): t is number => typeof t === "number");
+  const firstUser = msgs.find((m) => m.role === "user");
+  const meta: SessionMeta = {
+    id: newSessionId(),
+    title: deriveTitle(firstUser?.content ?? ""),
+    createdAt: timestamps.length > 0 ? Math.min(...timestamps) : Date.now(),
+    updatedAt: timestamps.length > 0 ? Math.max(...timestamps) : Date.now(),
+    messageCount: msgs.length,
+  };
+  writeJson(payloadKey(root, meta.id), msgs.slice(-MAX_PERSIST_MESSAGES));
+  const index: SessionIndex = { version: 1, activeId: meta.id, sessions: [meta] };
+  writeIndex(root, index);
+  return index;
+}
+
+// ─── Public API ─────────────────────────────────────────────────────────────
+
+function newSessionId() {
+  return `s_${Date.now()}_${Math.random().toString(36).slice(2, 9)}`;
+}
+
+/**
+ * Derive a session title from its first user message: first non-empty line, whitespace-collapsed,
+ * capped at {@link MAX_TITLE_LENGTH} characters.
+ *
+ * @param {string} text
+ * @returns {string}
+ */
+export function deriveTitle(text: string): string {
+  const line =
+    text
+      .split("\n")
+      .map((l) => l.replaceAll(/\s+/g, " ").trim())
+      .find((l) => l.length > 0) ?? "";
+  if (!line) {
+    return DEFAULT_TITLE;
+  }
+  return line.length > MAX_TITLE_LENGTH ? `${line.slice(0, MAX_TITLE_LENGTH - 1)}…` : line;
+}
+
+/** List a project's sessions, most recently updated first. */
+export function listSessions(root: string): SessionMeta[] {
+  return readIndex(root).sessions;
+}
+
+/** The session restored on startup, or null for a fresh unsaved chat. */
+export function getActiveSessionId(root: string): string | null {
+  return readIndex(root).activeId;
+}
+
+/** Point the index at the session to restore next startup (null = fresh chat). */
+export function setActiveSession(root: string, id: string | null) {
+  const index = readIndex(root);
+  index.activeId = id;
+  writeIndex(root, index);
+}
+
+/**
+ * Create a new session (as the active one), evicting the oldest sessions beyond
+ * {@link MAX_SESSIONS}. The title derives from the first user message when given.
+ */
+export function createSession(root: string, firstUserText?: string): SessionMeta {
+  const index = readIndex(root);
+  const now = Date.now();
+  const meta: SessionMeta = {
+    id: newSessionId(),
+    title: deriveTitle(firstUserText ?? ""),
+    createdAt: now,
+    updatedAt: now,
+    messageCount: 0,
+  };
+  index.sessions.unshift(meta);
+  while (index.sessions.length > MAX_SESSIONS) {
+    let oldest = 0;
+    for (let i = 1; i < index.sessions.length; i++) {
+      if (index.sessions[i]!.updatedAt < index.sessions[oldest]!.updatedAt) {
+        oldest = i;
+      }
+    }
+    const [evicted] = index.sessions.splice(oldest, 1);
+    removeKey(payloadKey(root, evicted!.id));
+  }
+  index.activeId = meta.id;
+  writeIndex(root, index);
+  return meta;
+}
+
+/** Load a session's messages, or null when it doesn't exist / is corrupt. */
+export function loadSession(root: string, id: string): PersistedMessage[] | null {
+  const msgs = readJson<PersistedMessage[]>(payloadKey(root, id));
+  return Array.isArray(msgs) ? msgs : null;
+}
+
+/**
+ * Persist a session's messages (trimmed to {@link MAX_PERSIST_MESSAGES}) and refresh its index
+ * entry (updatedAt, messageCount, and the title while still the default).
+ */
+export function saveSession(root: string, id: string, messages: PersistedMessage[]) {
+  const trimmed = messages.slice(-MAX_PERSIST_MESSAGES);
+  writeJson(payloadKey(root, id), trimmed);
+  const index = readIndex(root);
+  const meta = index.sessions.find((s) => s.id === id);
+  if (!meta) {
+    return;
+  }
+  meta.updatedAt = Date.now();
+  meta.messageCount = trimmed.length;
+  if (meta.title === DEFAULT_TITLE) {
+    const firstUser = trimmed.find((m) => m.role === "user");
+    if (firstUser) {
+      meta.title = deriveTitle(firstUser.content);
+    }
+  }
+  writeIndex(root, index);
+}
+
+/** Delete a session's payload and index entry; clears activeId when it was active. */
+export function deleteSession(root: string, id: string) {
+  removeKey(payloadKey(root, id));
+  const index = readIndex(root);
+  index.sessions = index.sessions.filter((s) => s.id !== id);
+  if (index.activeId === id) {
+    index.activeId = null;
+  }
+  writeIndex(root, index);
+}

package/src/services/ai-settings.ts

@@ -9,6 +9,8 @@
  * @license MIT
  */
 
+import { persistSettings } from "./settings-store";
+
 const KEY_STORAGE = "jx.ai.openaiKey";
 const BASE_URL_STORAGE = "jx.ai.baseUrl";
 const MODEL_STORAGE = "jx.ai.model";
@@ -36,6 +38,7 @@ export function setOpenAiKey(key: string) {
     } else {
       globalThis.localStorage?.removeItem(KEY_STORAGE);
     }
+    persistSettings();
   } catch {
     /* LocalStorage unavailable — settings are not persisted. */
   }
@@ -71,6 +74,7 @@ export function setBaseUrl(url: string) {
     } else {
       globalThis.localStorage?.removeItem(BASE_URL_STORAGE);
     }
+    persistSettings();
   } catch {
     /* LocalStorage unavailable — settings are not persisted. */
   }
@@ -101,6 +105,7 @@ export function setModel(modelId: string) {
     } else {
       globalThis.localStorage?.removeItem(MODEL_STORAGE);
     }
+    persistSettings();
   } catch {
     /* LocalStorage unavailable — settings are not persisted. */
   }

package/src/services/automation.ts

@@ -0,0 +1,140 @@
+/// <reference lib="dom" />
+/**
+ * Automation hook — a small, gated scripting surface for driving Studio from a browser-automation
+ * runner (see scripts/screenshots/ at the repo root). Installed as `window.__jxAutomation` only
+ * when the page URL carries `?automation=1`; without the flag production behavior is untouched.
+ *
+ * The API mutates the same reactive state the real UI mutates (canvas mode, activity tab,
+ * selection, inspector tab, function editor) instead of clicking through Spectrum shadow DOM, so
+ * shot definitions stay stable across chrome refactors.
+ */
+
+import { renderOnly, updateUi } from "../store";
+import { activeTab, workspace } from "../workspace/workspace";
+import { applyPanelCollapse, view } from "../view";
+import type { JxPath } from "../state";
+
+/** Callbacks injected from studio.ts (module-local helpers or imports kept out of this module). */
+export interface AutomationDeps {
+  getCanvasMode: () => string;
+  openBrowseModal: () => void;
+  openNewProjectModal: () => void;
+  render: () => void;
+  renderActivityBar: () => void;
+  setCanvasMode: (mode: string) => void;
+  statusMessage: (text: string) => void;
+}
+
+export interface AutomationApi {
+  editDef: (defName: string) => void;
+  editFunction: (path: JxPath, eventKey: string) => void;
+  openBrowse: () => void;
+  openNewProject: () => void;
+  getState: () => {
+    activeTabId: string | null;
+    canvasMode: string;
+    canvasStatus: string | null;
+    leftTab: string;
+  };
+  select: (path: JxPath | null) => void;
+  setActivity: (tab: string) => void;
+  setCanvasMode: (mode: string) => void;
+  setRightTab: (tab: string) => void;
+  setStatus: (text: string) => void;
+  setTheme: (color: string) => void;
+  setZoom: (zoom: number) => void;
+  waitForCanvasReady: (timeoutMs?: number) => Promise<void>;
+}
+
+/** The hook is opt-in per page load: only `?automation=1` installs it. */
+export function shouldInstallAutomation(search: string): boolean {
+  return new URLSearchParams(search).get("automation") === "1";
+}
+
+export function createAutomationApi(deps: AutomationDeps): AutomationApi {
+  return {
+    editDef(defName: string) {
+      updateUi("editingFunction", { defName, type: "def" });
+      deps.render();
+    },
+    editFunction(path: JxPath, eventKey: string) {
+      updateUi("editingFunction", { eventKey, path, type: "event" });
+      deps.render();
+    },
+    openBrowse() {
+      deps.openBrowseModal();
+    },
+    openNewProject() {
+      deps.openNewProjectModal();
+    },
+    getState() {
+      return {
+        activeTabId: workspace.activeTabId,
+        canvasMode: deps.getCanvasMode(),
+        canvasStatus: activeTab.value?.session.canvas.status ?? null,
+        leftTab: view.leftTab,
+      };
+    },
+    select(path: JxPath | null) {
+      const tab = activeTab.value;
+      if (tab) {
+        tab.session.selection = path;
+      }
+      deps.render();
+    },
+    setActivity(tab: string) {
+      view.leftTab = tab;
+      view.leftPanelCollapsed = false;
+      applyPanelCollapse();
+      renderOnly("leftPanel");
+      deps.renderActivityBar();
+    },
+    setCanvasMode(mode: string) {
+      deps.setCanvasMode(mode);
+      deps.render();
+    },
+    setRightTab(tab: string) {
+      updateUi("rightTab", tab);
+      deps.render();
+    },
+    setStatus(text: string) {
+      deps.statusMessage(text);
+    },
+    setTheme(color: string) {
+      document.querySelector("sp-theme")?.setAttribute("color", color);
+    },
+    setZoom(zoom: number) {
+      updateUi("zoom", zoom);
+      deps.render();
+    },
+    waitForCanvasReady(timeoutMs = 30_000) {
+      return new Promise((resolve, reject) => {
+        const started = Date.now();
+        const tick = () => {
+          if (activeTab.value?.session.canvas.status === "ready") {
+            resolve();
+            return;
+          }
+          if (Date.now() - started > timeoutMs) {
+            reject(new Error(`canvas not ready after ${timeoutMs}ms`));
+            return;
+          }
+          setTimeout(tick, 50);
+        };
+        tick();
+      });
+    },
+  };
+}
+
+/**
+ * Install the hook on globalThis when the current URL opts in. Returns whether it installed, so
+ * callers (and tests) can assert the gate.
+ */
+export function installAutomationHook(deps: AutomationDeps): boolean {
+  if (!shouldInstallAutomation(location.search)) {
+    return false;
+  }
+  (globalThis as Record<string, unknown>).__jxAutomation = createAutomationApi(deps);
+  return true;
+}

package/src/services/document-assistant.ts

@@ -22,20 +22,16 @@ import { getBaseUrl, getModel, getOpenAiKey } from "./ai-settings";
 import { trimContext } from "./context-manager";
 import { renderCheck } from "./render-critic";
 import { openFileInTab } from "../files/files";
-
-const PERSIST_KEY_PREFIX = "jx-ai-chat-history";
-const MAX_PERSIST_MESSAGES = 50;
+import * as sessionStore from "./ai-session-store";
 
 /**
- * Project-scoped localStorage key (uses the project root) so conversations don't bleed across
- * projects (ADR §11.5 / §14.2). Falls back to a shared key when no project is open.
+ * Project root scoping the session store (ADR §11.5 / §14.2 — conversations don't bleed across
+ * projects). Falls back to a shared unscoped store when no project is open.
  *
  * @returns {string}
  */
-function persistKey() {
-  return workspace.projectRoot
-    ? `${PERSIST_KEY_PREFIX}:${workspace.projectRoot}`
-    : PERSIST_KEY_PREFIX;
+function projectRoot() {
+  return workspace.projectRoot || "";
 }
 
 /**
@@ -46,6 +42,10 @@ function persistKey() {
  *   sendMessage: (text: string) => Promise<void>;
  *   stop: () => void;
  *   newChat: () => void;
+ *   listSessions: () => import("./ai-session-store").SessionMeta[];
+ *   openSession: (id: string) => void;
+ *   deleteSession: (id: string) => void;
+ *   activeSessionId: () => string | null;
  * }}
  */
 export function createDocumentAssistant() {
@@ -69,6 +69,9 @@ export function createDocumentAssistant() {
 
   let controller: AbortController | null = null;
 
+  /** The persisted session backing the live chat; null = fresh unsaved chat. */
+  let sessionId: string | null = null;
+
   function buildPrompt() {
     const tab = activeTab.value;
     return buildSystemPrompt({
@@ -84,6 +87,12 @@ export function createDocumentAssistant() {
       return;
     }
 
+    // Lazily create the backing session on the first message so empty "New Chat"
+    // Clicks never pollute the session list.
+    if (!sessionId) {
+      sessionId = sessionStore.createSession(projectRoot(), text).id;
+    }
+
     chatState.sendMessage(text);
 
     // Trim context before streaming to keep the conversation within token limits.
@@ -93,7 +102,7 @@ export function createDocumentAssistant() {
     }
 
     // Persist after trimming so the saved history reflects what's actually sent.
-    persistChat(chatState);
+    persistChat();
 
     try {
       const plat = getPlatform();
@@ -127,6 +136,9 @@ export function createDocumentAssistant() {
       chatState.setError(error instanceof Error ? error.message : String(error));
     } finally {
       controller = null;
+      // Persist again once the stream settled so the completed reply (or the state
+      // After an error/abort cleanup) survives a reload without another send.
+      persistChat();
     }
   }
 
@@ -138,46 +150,94 @@ export function createDocumentAssistant() {
   function newChat() {
     stop();
     chatState.clearChat();
-    persistChat(chatState);
+    sessionId = null;
+    sessionStore.setActiveSession(projectRoot(), null);
+  }
+
+  // ── Sessions ──────────────────────────────────────────────────────────
+
+  /** The project's persisted sessions, most recently updated first. */
+  function listSessions() {
+    return sessionStore.listSessions(projectRoot());
+  }
+
+  /** Replace the live chat with a persisted session's messages. */
+  function openSession(id: string) {
+    const msgs = sessionStore.loadSession(projectRoot(), id);
+    if (!msgs) {
+      return;
+    }
+    stop();
+    chatState.clearChat();
+    pushRestoredMessages(msgs);
+    sessionId = id;
+    sessionStore.setActiveSession(projectRoot(), id);
+  }
+
+  /** Delete a persisted session; deleting the open one leaves a fresh unsaved chat. */
+  function deleteSession(id: string) {
+    sessionStore.deleteSession(projectRoot(), id);
+    if (sessionId === id) {
+      stop();
+      chatState.clearChat();
+      sessionId = null;
+    }
+  }
+
+  function activeSessionId() {
+    return sessionId;
   }
 
   // ── Persistence ───────────────────────────────────────────────────────
 
-  /** Persist recent messages to localStorage (non-blocking). */
-  function persistChat(cs: ReturnType<typeof createChatState>) {
-    try {
-      const msgs = cs.messages.slice(-MAX_PERSIST_MESSAGES);
-      localStorage.setItem(persistKey(), JSON.stringify(msgs));
-    } catch {
-      // Storage full or unavailable — not critical.
+  /** Persist the live conversation into its backing session (non-blocking). */
+  function persistChat() {
+    if (!sessionId) {
+      return;
     }
+    // Skip a still-empty streaming placeholder so reloads don't restore blank bubbles.
+    const msgs = chatState.messages.filter(
+      (m) => m.role !== "assistant" || m.content || (m.toolCalls?.length ?? 0) > 0,
+    );
+    sessionStore.saveSession(projectRoot(), sessionId, msgs);
   }
 
-  /** Restore messages from a previous session, if any. */
+  /** Push persisted messages into chat state, synthesizing ids where missing. */
+  function pushRestoredMessages(msgs: sessionStore.PersistedMessage[]) {
+    for (const m of msgs) {
+      chatState.messages.push({
+        ...m,
+        id: m.id || `restored_${Date.now()}_${Math.random().toString(36).slice(2, 9)}`,
+      } as (typeof chatState.messages)[number]);
+    }
+  }
+
+  /** Restore the last-active session once on creation, if any. */
   function restoreChat() {
-    try {
-      const raw = localStorage.getItem(persistKey());
-      if (!raw) {
-        return;
-      }
-      const msgs = JSON.parse(raw) as typeof chatState.messages;
-      if (!Array.isArray(msgs) || msgs.length === 0) {
-        return;
-      }
-      // Push into chat state (skips streaming state)
-      for (const m of msgs) {
-        chatState.messages.push({
-          ...m,
-          id: m.id || `restored_${Date.now()}_${Math.random().toString(36).slice(2, 9)}`,
-        });
-      }
-    } catch {
-      // Corrupt or empty — ignore.
+    const root = projectRoot();
+    const activeId = sessionStore.getActiveSessionId(root);
+    if (!activeId) {
+      return;
+    }
+    const msgs = sessionStore.loadSession(root, activeId);
+    if (!msgs || msgs.length === 0) {
+      return;
     }
+    pushRestoredMessages(msgs);
+    sessionId = activeId;
   }
 
   // Restore once on creation.
   restoreChat();
 
-  return { chatState, sendMessage, stop, newChat };
+  return {
+    chatState,
+    sendMessage,
+    stop,
+    newChat,
+    listSessions,
+    openSession,
+    deleteSession,
+    activeSessionId,
+  };
 }