@jxsuite/studio 0.34.0 → 0.35.0

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,
+  };
 }

package/src/services/import-client.ts

@@ -0,0 +1,134 @@
+/**
+ * Shared client for the /__studio/import-site NDJSON stream. Every platform's importSite is "a
+ * streaming fetch to some URL" — the dev server posts to its own origin, the desktop platforms post
+ * to their token-gated loopback servers — so the request/parse/settle logic lives here once.
+ *
+ * The endpoint emits one JSON object per line: `progress` lines (forwarded to onProgress),
+ * `heartbeat` keep-alives (ignored), and a terminal `done` ({root, config}) or `error` line.
+ */
+
+import type { ImportProgressEvent, ImportSiteOptions } from "../types";
+import type { ProjectConfig } from "@jxsuite/schema/types";
+
+interface StreamLine {
+  type: string;
+  phase?: string;
+  message?: string;
+  current?: number;
+  total?: number;
+  root?: string;
+  config?: ProjectConfig;
+  error?: string;
+}
+
+/**
+ * POST an import request and consume its NDJSON progress stream.
+ *
+ * @param {string} endpoint — the platform's import-site URL (may carry an auth token)
+ * @param {ImportSiteOptions} opts — the import request; `apiKey`/`baseUrl` travel as headers
+ * @param {(evt: ImportProgressEvent) => void} onProgress
+ * @param {AbortSignal} [signal]
+ */
+export async function streamImport(
+  endpoint: string,
+  opts: ImportSiteOptions,
+  onProgress: (evt: ImportProgressEvent) => void,
+  signal?: AbortSignal,
+): Promise<{ root: string; config: ProjectConfig }> {
+  const headers: Record<string, string> = { "Content-Type": "application/json" };
+  if (opts.apiKey) {
+    headers["X-Api-Key"] = opts.apiKey;
+  }
+  if (opts.baseUrl) {
+    headers["X-Api-Base-URL"] = opts.baseUrl;
+  }
+
+  const res = await fetch(endpoint, {
+    body: JSON.stringify({
+      url: opts.url,
+      directory: opts.directory,
+      depth: opts.depth,
+      maxPages: opts.maxPages,
+      aiComponents: opts.aiComponents,
+      ...(opts.model === undefined ? {} : { aiModel: opts.model }),
+    }),
+    headers,
+    method: "POST",
+    ...(signal === undefined ? {} : { signal }),
+  });
+
+  if (!res.ok) {
+    let message = `Import failed (${res.status})`;
+    try {
+      const body = (await res.json()) as { error?: string };
+      if (body.error) {
+        message = body.error;
+      }
+    } catch {
+      /* Non-JSON error body — keep the status message. */
+    }
+    throw new Error(message);
+  }
+  if (!res.body) {
+    throw new Error("Import stream had no response body");
+  }
+
+  const reader = res.body.getReader();
+  const decoder = new TextDecoder();
+  let buffer = "";
+  let result: { root: string; config: ProjectConfig } | null = null;
+
+  const handleLine = (line: string) => {
+    const trimmed = line.trim();
+    if (!trimmed) {
+      return;
+    }
+    let parsed: StreamLine;
+    try {
+      parsed = JSON.parse(trimmed) as StreamLine;
+    } catch {
+      return; // Tolerate a mangled line rather than killing the whole import.
+    }
+    if (parsed.type === "progress") {
+      onProgress({
+        phase: parsed.phase ?? "",
+        message: parsed.message ?? "",
+        ...(parsed.current === undefined ? {} : { current: parsed.current }),
+        ...(parsed.total === undefined ? {} : { total: parsed.total }),
+      });
+    } else if (parsed.type === "done" && parsed.root !== undefined && parsed.config) {
+      result = { root: parsed.root, config: parsed.config };
+    } else if (parsed.type === "error") {
+      throw new Error(parsed.error || "Import failed");
+    }
+    // Heartbeats and unknown line types are ignored.
+  };
+
+  try {
+    for (;;) {
+      const { done, value } = await reader.read();
+      if (done) {
+        break;
+      }
+      buffer += decoder.decode(value, { stream: true });
+      // Lines can split across chunks: keep the trailing partial in the buffer.
+      const lines = buffer.split("\n");
+      buffer = lines.pop() ?? "";
+      for (const line of lines) {
+        handleLine(line);
+      }
+    }
+    handleLine(buffer);
+  } finally {
+    try {
+      await reader.cancel();
+    } catch {
+      /* The stream is already closed (e.g. after an abort). */
+    }
+  }
+
+  if (!result) {
+    throw new Error("Import stream ended without a result");
+  }
+  return result;
+}

package/src/services/settings-store.ts

@@ -0,0 +1,93 @@
+/// <reference lib="dom" />
+/**
+ * Settings-store.js — sync of user settings between localStorage and the platform backend.
+ *
+ * LocalStorage stays the synchronous source of truth for every consumer (ai-settings getters read
+ * it directly). On platforms with a backend user-settings store (desktop/chromium — where
+ * localStorage does not roam across browser profiles), the persisted keys are hydrated from the
+ * backend at boot and written through on every change. The dev server omits the platform methods
+ * and settings remain localStorage-only.
+ *
+ * @license MIT
+ */
+
+import { getPlatform, hasPlatform } from "../platform";
+
+/** The localStorage keys mirrored into the platform's user-settings store. */
+export const PERSISTED_SETTINGS_KEYS = ["jx.ai.openaiKey", "jx.ai.baseUrl", "jx.ai.model"] as const;
+
+/** Read a localStorage value defensively, treating unavailable/throwing storage as empty. */
+function readLocal(key: string): string {
+  try {
+    return globalThis.localStorage?.getItem(key) ?? "";
+  } catch {
+    return "";
+  }
+}
+
+/**
+ * Pull the persisted settings from the backend store into localStorage. Call once after the
+ * platform is registered; a no-op on platforms without a settings store (dev server).
+ *
+ * Migration: keys the backend does not know yet but localStorage does (an existing user upgrading
+ * from localStorage-only builds) are pushed back to the backend once, fire-and-forget.
+ */
+export async function hydrateSettings(): Promise<void> {
+  if (!hasPlatform()) {
+    return;
+  }
+  const platform = getPlatform();
+  if (!platform.getSettings) {
+    return;
+  }
+  let stored: Record<string, string>;
+  try {
+    stored = await platform.getSettings();
+  } catch {
+    return;
+  }
+  const merged: Record<string, string> = { ...stored };
+  let needsMigration = false;
+  for (const key of PERSISTED_SETTINGS_KEYS) {
+    const backendValue = stored[key];
+    if (backendValue) {
+      try {
+        globalThis.localStorage?.setItem(key, backendValue);
+      } catch {
+        /* Storage unavailable — consumers fall back to defaults. */
+      }
+    } else {
+      const localValue = readLocal(key);
+      if (localValue) {
+        merged[key] = localValue;
+        needsMigration = true;
+      }
+    }
+  }
+  if (needsMigration && platform.saveSettings) {
+    void platform.saveSettings(merged).catch(() => {});
+  }
+}
+
+/**
+ * Write the current values of the persisted keys through to the backend store, fire-and-forget.
+ * Call after mutating any of {@link PERSISTED_SETTINGS_KEYS} in localStorage; a no-op on platforms
+ * without a settings store (dev server).
+ */
+export function persistSettings(): void {
+  if (!hasPlatform()) {
+    return;
+  }
+  const platform = getPlatform();
+  if (!platform.saveSettings) {
+    return;
+  }
+  const settings: Record<string, string> = {};
+  for (const key of PERSISTED_SETTINGS_KEYS) {
+    const value = readLocal(key);
+    if (value) {
+      settings[key] = value;
+    }
+  }
+  void platform.saveSettings(settings).catch(() => {});
+}

package/src/studio.ts

@@ -80,6 +80,8 @@ import { startFsSync } from "./files/fs-events";
 import { renderImportsTemplate } from "./panels/imports-panel";
 import { renderHeadTemplate } from "./panels/head-panel";
 import { exportCemManifest as _exportCemManifest } from "./services/cem-export";
+import { installAutomationHook } from "./services/automation";
+import { openBrowseModal } from "./browse/browse-modal";
 
 import { getPlatform, hasPlatform, registerPlatform } from "./platform";
 import { parseMediaEntries } from "./utils/canvas-media";
@@ -90,6 +92,7 @@ import { defBadgeLabel, defCategory, renderSignalsTemplate } from "./panels/sign
 import { loadComponentRegistry } from "./files/components";
 import { ensureDependenciesInstalled } from "./packages/ensure-deps";
 import { maybePromptJxsuiteUpdate } from "./packages/jxsuite-update";
+import { autoSyncProjectOnOpen } from "./packages/pull-package-sync";
 
 import { html, render as litRender } from "lit-html";
 
@@ -124,6 +127,7 @@ import {
 import { initCssData } from "./panels/style-utils";
 import { initQuickSearch } from "./panels/quick-search";
 import { addRecentProject, hydrateRecentProjects, removeRecentProject } from "./recent-projects";
+import { hydrateSettings } from "./services/settings-store";
 import { initWelcome } from "./panels/welcome-screen";
 import { openNewProjectModal } from "./new-project/new-project-modal";
 import type { DocumentStackEntry, GitDiffState } from "./types";
@@ -342,6 +346,18 @@ if (!hasPlatform()) {
   registerPlatform(createDevServerPlatform());
 }
 
+// Screenshot/automation runners (scripts/screenshots/) await window.__jxAutomation right after
+// Navigation, so the gated hook must install before the async deep-link project load below.
+installAutomationHook({
+  getCanvasMode,
+  openBrowseModal,
+  openNewProjectModal,
+  render,
+  renderActivityBar,
+  setCanvasMode,
+  statusMessage,
+});
+
 mountResizeEdges();
 
 // ─── Render loop ──────────────────────────────────────────────────────────────
@@ -619,6 +635,7 @@ if (_projectParam) {
             selectedPath: siteCtx.fileRelPath || null,
           });
 
+          await autoSyncProjectOnOpen();
           await ensureDependenciesInstalled();
           await loadComponentRegistry();
 
@@ -727,6 +744,13 @@ void hydrateRecentProjects().then(() => {
   render();
 });
 
+// Hydrate user settings (AI connection parameters) from the backend store, then re-render so
+// Key-gated surfaces (assistant gate, New Project Import/Agent tabs) see the stored key.
+// oxlint-disable-next-line unicorn/prefer-top-level-await -- deliberate fire-and-forget: hydration must not block initial render
+void hydrateSettings().then(() => {
+  render();
+});
+
 // ─── Left panel: delegated to panels/left-panel.js ───────────────────────────
 
 function renderLeftPanel() {
@@ -787,6 +811,7 @@ async function openRecentProject(root: string) {
       selectedPath: null,
     });
 
+    await autoSyncProjectOnOpen();
     await ensureDependenciesInstalled();
     await loadDirectory(".");
     await loadComponentRegistry();