@jxsuite/studio 0.34.0 → 0.36.0

package/src/services/agent-seed.ts

@@ -0,0 +1,91 @@
+/// <reference lib="dom" />
+/**
+ * Agent-seed.ts — cross-window handoff of a pending AI assistant prompt.
+ *
+ * The New Project flow stores the user's project brief here; the Studio window that opens the
+ * project consumes it and seeds the Assistant tab. localStorage (not module state) is deliberate:
+ * on desktop the new project opens in a NEW window, and the per-root localStorage key is the
+ * cross-window channel (precedent: the chat-history key `jx-ai-chat-history:<root>`).
+ *
+ * @license MIT
+ */
+
+const PENDING_PROMPT_PREFIX = "jx.ai.pendingAgentPrompt";
+
+/** Entries older than this are considered stale and dropped on read. */
+const MAX_AGE_MS = 15 * 60 * 1000;
+
+function storageKey(root: string) {
+  return `${PENDING_PROMPT_PREFIX}:${root}`;
+}
+
+/**
+ * Read the pending entry for a project root, dropping stale or malformed entries.
+ *
+ * @param {string} root
+ * @returns {{ prompt: string; ts: number } | null}
+ */
+function readEntry(root: string): { prompt: string; ts: number } | null {
+  try {
+    const raw = globalThis.localStorage?.getItem(storageKey(root));
+    if (!raw) {
+      return null;
+    }
+    const parsed = JSON.parse(raw) as { prompt?: unknown; ts?: unknown };
+    const valid =
+      typeof parsed.prompt === "string" &&
+      typeof parsed.ts === "number" &&
+      Date.now() - parsed.ts <= MAX_AGE_MS;
+    if (!valid) {
+      // Stale or malformed — remove so it never seeds a later session.
+      globalThis.localStorage?.removeItem(storageKey(root));
+      return null;
+    }
+    return { prompt: parsed.prompt as string, ts: parsed.ts as number };
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Store a pending assistant prompt for the project at `root`.
+ *
+ * @param {string} root
+ * @param {string} prompt
+ */
+export function setPendingAgentPrompt(root: string, prompt: string): void {
+  try {
+    globalThis.localStorage?.setItem(storageKey(root), JSON.stringify({ prompt, ts: Date.now() }));
+  } catch {
+    /* LocalStorage unavailable — the prompt is simply not handed off. */
+  }
+}
+
+/**
+ * Whether a fresh (younger than 15 min) pending prompt exists for `root`.
+ *
+ * @param {string} root
+ */
+export function hasPendingAgentPrompt(root: string): boolean {
+  return readEntry(root) !== null;
+}
+
+/**
+ * Read AND delete the pending prompt for `root` (consume-on-read keeps repeated renders
+ * idempotent). Returns null when there is no fresh entry.
+ *
+ * @param {string} root
+ * @returns {string | null}
+ */
+export function consumePendingAgentPrompt(root: string): string | null {
+  const entry = readEntry(root);
+  if (!entry) {
+    return null;
+  }
+  try {
+    globalThis.localStorage?.removeItem(storageKey(root));
+  } catch {
+    /* LocalStorage unavailable — nothing to delete. */
+  }
+  return entry.prompt;
+}

package/src/services/ai-models.ts

@@ -0,0 +1,93 @@
+/// <reference lib="dom" />
+/**
+ * Ai-models.js — available-model listing from the studio AI proxy.
+ *
+ * Fetches the proxy's /models endpoint (the chat endpoint's sibling), forwarding the
+ * stored API key as X-Api-Key and the endpoint override as X-Api-Base-URL so the proxy
+ * lists models from the user's chosen provider. Shared by the credentials form and the
+ * chat composer's model picker; results are cached module-wide until invalidated (e.g.
+ * after credentials change).
+ *
+ * @license MIT
+ */
+
+import type { AiModelsResponse } from "@jxsuite/protocol";
+import { getPlatform } from "../platform";
+import { getBaseUrl, getOpenAiKey } from "./ai-settings";
+
+export interface AiModel {
+  id: string;
+  name: string;
+}
+
+let cache: AiModel[] | null = null;
+let proxyConfigured = false;
+let proxyManaged = false;
+let proxyDefaultModel = "";
+
+/** Drop the cached model list (call after credentials/endpoint changes). */
+export function invalidateModelCache() {
+  cache = null;
+  proxyConfigured = false;
+  proxyManaged = false;
+  proxyDefaultModel = "";
+}
+
+/**
+ * Whether the proxy reported itself configured on the last fetch — true when the backend holds
+ * credentials (managed platforms, OPENAI_API_KEY env), so the assistant works without a locally
+ * stored key.
+ */
+export function isProxyConfigured(): boolean {
+  return proxyConfigured;
+}
+
+/** Whether the platform manages AI credentials itself (cloud Workers AI). */
+export function isManagedProxy(): boolean {
+  return proxyManaged;
+}
+
+/** The proxy's preferred model id ("" when it does not declare one). */
+export function getProxyDefaultModel(): string {
+  return proxyDefaultModel;
+}
+
+/**
+ * Fetch the models available through the AI proxy. Returns the cached list when present unless
+ * `force` is set; throws on HTTP/network failure (callers surface the error).
+ *
+ * @param {{ apiKey?: string; baseUrl?: string; force?: boolean }} [opts] - Credential overrides for
+ *   drafts not yet saved to ai-settings.
+ * @returns {Promise<AiModel[]>}
+ */
+export async function fetchAvailableModels(
+  opts: { apiKey?: string; baseUrl?: string; force?: boolean } = {},
+): Promise<AiModel[]> {
+  if (cache && !opts.force) {
+    return cache;
+  }
+  const plat = getPlatform();
+  const chatUrl = await Promise.resolve(plat.aiChatUrl());
+  const modelsUrl = chatUrl.replace(/\/chat$/, "/models");
+
+  const headers: Record<string, string> = {};
+  const apiKey = opts.apiKey || getOpenAiKey();
+  if (apiKey) {
+    headers["X-Api-Key"] = apiKey;
+  }
+  const baseUrl = opts.baseUrl || getBaseUrl();
+  if (baseUrl) {
+    headers["X-Api-Base-URL"] = baseUrl;
+  }
+
+  const resp = await fetch(modelsUrl, { headers });
+  if (!resp.ok) {
+    throw new Error(`HTTP ${resp.status}`);
+  }
+  const data = (await resp.json()) as Partial<AiModelsResponse>;
+  proxyConfigured = data.configured === true;
+  proxyManaged = data.managed === true;
+  proxyDefaultModel = data.defaultModel ?? "";
+  cache = (data.models || []).map((m) => ({ id: m.id, name: m.name || m.id }));
+  return cache;
+}

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/cf-settings.ts

@@ -0,0 +1,58 @@
+/// <reference lib="dom" />
+/**
+ * Cf-settings — local persistence for the Cloudflare publish connection on
+ * platforms without a hosted OAuth broker (dev server, desktop). The API
+ * token is stored like the AI key: localStorage first, mirrored through the
+ * platform settings backend where one exists. It only ever leaves the machine
+ * to the same-origin `/__studio/cf/proxy`, which forwards it as a bearer to
+ * api.cloudflare.com (not CORS-enabled, hence the proxy).
+ *
+ * @license MIT
+ */
+
+import { persistSettings } from "./settings-store";
+
+const TOKEN_STORAGE = "jx.cf.token";
+const ACCOUNT_STORAGE = "jx.cf.accountId";
+
+function read(key: string): string {
+  try {
+    return globalThis.localStorage?.getItem(key) ?? "";
+  } catch {
+    return "";
+  }
+}
+
+function write(key: string, value: string): void {
+  try {
+    const trimmed = (value || "").trim();
+    if (trimmed) {
+      globalThis.localStorage?.setItem(key, trimmed);
+    } else {
+      globalThis.localStorage?.removeItem(key);
+    }
+  } catch {
+    // Storage unavailable (private mode) — the connection just won't persist.
+  }
+  persistSettings();
+}
+
+/** The stored Cloudflare API token, or "" when not connected. */
+export function getCfToken(): string {
+  return read(TOKEN_STORAGE);
+}
+
+/** Persist (or clear, with a blank value) the Cloudflare API token. */
+export function setCfToken(token: string): void {
+  write(TOKEN_STORAGE, token);
+}
+
+/** The selected Cloudflare account id, or "" when none chosen yet. */
+export function getCfAccountId(): string {
+  return read(ACCOUNT_STORAGE);
+}
+
+/** Persist (or clear) the selected Cloudflare account id. */
+export function setCfAccountId(accountId: string): void {
+  write(ACCOUNT_STORAGE, accountId);
+}