@jxsuite/studio 0.31.1 → 0.33.0

package/src/services/context-manager.ts

@@ -0,0 +1,200 @@
+/**
+ * Context-manager.js — Token budget management for the AI assistant
+ *
+ * Estimates token usage and trims conversation history before each send to keep the
+ * context window within safe limits (ADR docs/ai-assistant-decision.md §11.4).
+ *
+ * Strategy (MVP): keep the system prompt + the most recent messages, dropping the oldest
+ * messages when the estimated total exceeds the configured token budget. Dropped messages
+ * are replaced with a single summary note so the model knows history was truncated.
+ *
+ * @license MIT
+ */
+
+import type { createChatState } from "@jxsuite/ai/chat-state";
+
+/** Shape of a single entry returned by `chatState.toMessagesArray()`. */
+interface MessageArrayEntry {
+  role: string;
+  content?: string | null;
+  tool_calls?: {
+    function?: { name?: string; arguments?: string };
+  }[];
+}
+
+// ─── Constants ──────────────────────────────────────────────────────────────
+
+/** Rough heuristic: average 4 characters per token. */
+const CHARS_PER_TOKEN = 4;
+
+/**
+ * Approximate context windows (in tokens) per model id, longest-prefix matched. Used to derive a
+ * model-aware budget instead of a flat cap (ADR §14.2). Conservative fallback for unknown models.
+ */
+const MODEL_CONTEXT_WINDOWS: [string, number][] = [
+  ["gpt-4o", 128_000],
+  ["gpt-4.1", 1_000_000],
+  ["gpt-4-turbo", 128_000],
+  ["gpt-4", 8192],
+  ["gpt-3.5", 16_385],
+  ["o1", 200_000],
+  ["o3", 200_000],
+  ["claude", 200_000],
+];
+
+/** Fallback window for models not in the table above. */
+const DEFAULT_CONTEXT_WINDOW = 32_000;
+
+/** Fraction of the window we'll actually fill before trimming. */
+const BUDGET_FRACTION = 0.8;
+
+/** Fraction of the window at which we surface a "context getting large" warning. */
+const WARN_FRACTION = 0.5;
+
+/**
+ * Resolve the context window (tokens) for a model id via longest-prefix match.
+ *
+ * @param {string | undefined} model
+ * @returns {number}
+ */
+function contextWindowFor(model: string | undefined): number {
+  if (!model) {
+    return DEFAULT_CONTEXT_WINDOW;
+  }
+  const id = model.toLowerCase();
+  let best = 0;
+  let window = DEFAULT_CONTEXT_WINDOW;
+  for (const [prefix, size] of MODEL_CONTEXT_WINDOWS) {
+    if (id.startsWith(prefix) && prefix.length > best) {
+      best = prefix.length;
+      window = size;
+    }
+  }
+  return window;
+}
+
+/** Messages to keep at the tail (most recent), regardless of budget. */
+const KEEP_RECENT = 20;
+
+/**
+ * Minimum number of user or tool messages we must preserve beyond the recent window so the model
+ * retains conversation grounding.
+ */
+const MIN_USER_TURNS = 3;
+
+// ─── Helpers ────────────────────────────────────────────────────────────────
+
+/**
+ * Estimate token count from a string or array of messages.
+ *
+ * @param {string | object[]} input
+ * @returns {number}
+ */
+function estimateTokens(input: string | MessageArrayEntry[]): number {
+  if (typeof input === "string") {
+    return Math.ceil(input.length / CHARS_PER_TOKEN);
+  }
+  let total = 0;
+  for (const msg of input) {
+    total += estimateTokens(msg.content || "");
+    // Tool calls carry extra tokens for the function name + arguments.
+    if (msg.tool_calls) {
+      for (const tc of msg.tool_calls) {
+        total +=
+          estimateTokens(tc.function?.name || "") +
+          estimateTokens(tc.function?.arguments || "") +
+          4; // Framing overhead
+      }
+    }
+    // Each message has ~4 tokens of framing overhead (role, etc.)
+    total += 4;
+  }
+  return total;
+}
+
+// ─── Trim ───────────────────────────────────────────────────────────────────
+
+/**
+ * Trim chat history so the total estimated token count stays within the budget. Returns trimming
+ * metadata, or null if no trimming was needed.
+ *
+ * Side effect: drops messages from chatState.messages (in-place via splice) and may insert a
+ * summary note.
+ *
+ * @param {ReturnType<typeof import("@jxsuite/ai/chat-state").createChatState>} chatState
+ * @param {string} systemPrompt
+ * @returns {{ estimatedTokens: number; droppedCount: number } | null}
+ */
+export function trimContext(
+  chatState: ReturnType<typeof createChatState>,
+  systemPrompt: string,
+): { estimatedTokens: number; droppedCount: number } | null {
+  const window = contextWindowFor(chatState.model);
+  const maxTokens = Math.floor(window * BUDGET_FRACTION);
+  const warnTokens = Math.floor(window * WARN_FRACTION);
+
+  const systemTokens = estimateTokens(systemPrompt);
+  const allMessages = chatState.messages;
+  const messageTokens = estimateTokens(chatState.toMessagesArray());
+  const total = systemTokens + messageTokens;
+
+  if (total <= maxTokens) {
+    chatState.setTokenCount(total);
+    // Warn once the conversation crosses half the window, even before we trim.
+    chatState.setContextWarning(total >= warnTokens);
+    return { estimatedTokens: total, droppedCount: 0 };
+  }
+
+  // Must trim. How many messages to drop?
+  // Keep the most recent KEEP_RECENT messages.
+  // But also ensure we keep at least MIN_USER_TURNS worth of user/tool context.
+  let keepFrom = Math.max(0, allMessages.length - KEEP_RECENT);
+
+  // Walk backward from keepFrom to find MIN_USER_TURNS user/tool messages to preserve.
+  let preservedTurns = 0;
+  for (let i = allMessages.length - 1; i >= keepFrom; i--) {
+    const { role } = allMessages[i]!;
+    if (role === "user" || role === "tool") {
+      preservedTurns += 1;
+    }
+  }
+
+  // If we don't have enough turns in the recent window, extend backward.
+  if (preservedTurns < MIN_USER_TURNS) {
+    for (let i = keepFrom - 1; i >= 0 && preservedTurns < MIN_USER_TURNS; i--) {
+      keepFrom = i;
+      const { role } = allMessages[i]!;
+      if (role === "user" || role === "tool") {
+        preservedTurns += 1;
+      }
+    }
+  }
+
+  // Never drop the system message (which is at index 0 if role === "system").
+  // For the Jx assistant, there is no system message in the messages array —
+  // The system prompt is passed separately. So keepFrom is safe.
+
+  if (keepFrom <= 0) {
+    // Can't trim further without losing everything. Warn but don't truncate.
+    chatState.setTokenCount(total);
+    chatState.setContextWarning(true);
+    return { estimatedTokens: total, droppedCount: 0 };
+  }
+
+  const droppedCount = keepFrom;
+  allMessages.splice(0, keepFrom);
+
+  // Insert a summary note so the model knows context was trimmed.
+  allMessages.unshift({
+    id: `ctx_summary_${Date.now()}`,
+    role: "user",
+    content: `[Earlier conversation truncated. ${droppedCount} messages dropped to stay within token budget. The most recent ${allMessages.length - 1} messages are preserved.]`,
+    timestamp: Date.now(),
+  });
+
+  const newTotal = systemTokens + estimateTokens(chatState.toMessagesArray());
+  chatState.setTokenCount(newTotal);
+  chatState.setContextWarning(true);
+
+  return { estimatedTokens: newTotal, droppedCount };
+}

package/src/services/document-assistant.ts

@@ -0,0 +1,183 @@
+/// <reference lib="dom" />
+/**
+ * Document-assistant.js — Stack B (canonical) document AI assistant session
+ *
+ * Wires the @jxsuite/ai infrastructure (chat-state, proxy streaming client, tool registry) to
+ * the active Jx document via `transactDoc()`-backed tools, and drives the error-correction
+ * agent loop. See docs/ai-assistant-decision.md.
+ *
+ * @license MIT
+ */
+
+import { createChatState, createProxyStreamingClient, createToolRegistry } from "@jxsuite/ai";
+import type { ProjectConfig } from "@jxsuite/schema/types";
+import { getPlatform } from "../platform";
+import { activeTab, workspace } from "../workspace/workspace";
+import { toRaw } from "../reactivity";
+import { componentRegistry } from "../files/components";
+import { registerAiTools } from "./ai-tools";
+import { runAgentLoop } from "./tool-executor";
+import { buildSystemPrompt } from "./ai-system-prompt";
+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;
+
+/**
+ * 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.
+ *
+ * @returns {string}
+ */
+function persistKey() {
+  return workspace.projectRoot
+    ? `${PERSIST_KEY_PREFIX}:${workspace.projectRoot}`
+    : PERSIST_KEY_PREFIX;
+}
+
+/**
+ * Create a document-assistant session bound to the currently active tab.
+ *
+ * @returns {{
+ *   chatState: ReturnType<typeof createChatState>;
+ *   sendMessage: (text: string) => Promise<void>;
+ *   stop: () => void;
+ *   newChat: () => void;
+ * }}
+ */
+export function createDocumentAssistant() {
+  const chatState = createChatState({ model: getModel() });
+
+  const toolRegistry = createToolRegistry();
+  registerAiTools(toolRegistry, {
+    getTab: () => activeTab.value,
+    saveFile: async (relPath: string, content: string) => {
+      const plat = getPlatform();
+      await plat.writeFile(relPath, content);
+    },
+    renderCheck: renderCheck as (
+      doc: unknown,
+    ) => Promise<{ ok: true } | { ok: false; error: string }>,
+    openDocument: openFileInTab,
+    projectStyle: (workspace.projectConfig as ProjectConfig | null)?.style as
+      | Record<string, string>
+      | undefined,
+  });
+
+  let controller: AbortController | null = null;
+
+  function buildPrompt() {
+    const tab = activeTab.value;
+    return buildSystemPrompt({
+      document: tab ? toRaw(tab.doc.document) : undefined,
+      projectConfig: (workspace.projectConfig as ProjectConfig | null) || undefined,
+      components: componentRegistry.length > 0 ? componentRegistry : undefined,
+      projectRoot: workspace.projectRoot || undefined,
+    });
+  }
+
+  async function sendMessage(text: string) {
+    if (!text.trim() || chatState.status === "streaming") {
+      return;
+    }
+
+    chatState.sendMessage(text);
+
+    // Trim context before streaming to keep the conversation within token limits.
+    const trimmed = trimContext(chatState, buildPrompt());
+    if (trimmed) {
+      chatState.setTokenCount(trimmed.estimatedTokens);
+    }
+
+    // Persist after trimming so the saved history reflects what's actually sent.
+    persistChat(chatState);
+
+    try {
+      const plat = getPlatform();
+      const chatUrl = await Promise.resolve(plat.aiChatUrl());
+      // Re-read the persisted model each send: the session is constructed once at module load
+      // (before the user sets a key/model), so the picker's choice must be picked up here.
+      chatState.setModel(getModel());
+      const streamingClient = createProxyStreamingClient({
+        chatUrl,
+        model: chatState.model,
+        // Sent as X-Api-Key; the proxy falls back to the server's OPENAI_API_KEY when empty.
+        apiKey: getOpenAiKey() || undefined,
+        // Optional OpenAI-compatible endpoint override; empty uses the proxy default.
+        baseUrl: getBaseUrl() || undefined,
+      });
+
+      controller = new AbortController();
+      await runAgentLoop({
+        chatState,
+        streamingClient,
+        toolRegistry,
+        systemPrompt: buildPrompt(),
+        signal: controller.signal,
+        getTab: () => activeTab.value,
+      });
+    } catch (error) {
+      /*
+       * Synchronous failure (e.g. platform not registered, network unreachable before the
+       * stream starts). Set the error so the panel can display it.
+       */
+      chatState.setError(error instanceof Error ? error.message : String(error));
+    } finally {
+      controller = null;
+    }
+  }
+
+  function stop() {
+    controller?.abort();
+    chatState.cancelStream();
+  }
+
+  function newChat() {
+    stop();
+    chatState.clearChat();
+    persistChat(chatState);
+  }
+
+  // ── 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.
+    }
+  }
+
+  /** Restore messages from a previous session, 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.
+    }
+  }
+
+  // Restore once on creation.
+  restoreChat();
+
+  return { chatState, sendMessage, stop, newChat };
+}

package/src/services/jx-validate.ts

@@ -0,0 +1,65 @@
+/**
+ * Jx-validate.js — cached Jx document schema validation for the AI assistant.
+ *
+ * Uses `@jxsuite/schema`'s pre-generated `schema.json` (the committed output of `generateSchema()`)
+ * as the eval signal for the agent loop (ADR docs/ai-assistant-decision.md §6b). We import the
+ * generated JSON rather than the generator itself: `generateSchema()` pulls in `@webref/*` + Node
+ * builtins (node:path/process) and would crash a browser bundle. The ajv validator is compiled once
+ * per session — `@jxsuite/schema`'s `validateDocument` recompiles on every call, which is too slow
+ * to run after every mutation in the loop.
+ *
+ * @license MIT
+ */
+
+import schema from "@jxsuite/schema/schema.json";
+
+type ValidateFn = ((doc: unknown) => boolean) & {
+  errors?: { instancePath?: string; message?: string }[] | null;
+};
+
+let _validate: ValidateFn | null = null;
+let _loading: Promise<ValidateFn | null> | null = null;
+
+/** Compile (once) and return the ajv validate function, or null if ajv is unavailable. */
+function getValidator() {
+  if (_validate) {
+    return Promise.resolve(_validate);
+  }
+  if (!_loading) {
+    _loading = (async () => {
+      try {
+        // The generated schema is JSON Schema draft 2020-12, so it needs Ajv's 2020 build —
+        // The default export only knows draft-07 and throws on the 2020 meta-schema ref.
+        // Optional peer dependency: validation degrades to a no-op if ajv is absent or the
+        // Schema fails to compile.
+        const { default: Ajv2020 } = await import("ajv/dist/2020.js");
+        const { default: addFormats } = await import("ajv-formats");
+        const ajv = new Ajv2020({ allErrors: true, strict: false, allowUnionTypes: true });
+        addFormats(ajv);
+        _validate = ajv.compile(schema as object);
+        return _validate;
+      } catch {
+        return null;
+      }
+    })();
+  }
+  return _loading;
+}
+
+/**
+ * Validate a Jx document against the schema.
+ *
+ * @param {unknown} doc
+ * @returns {Promise<string[]>} Formatted error strings; empty when valid or validation unavailable
+ */
+export async function validateDoc(doc: unknown) {
+  const validate = await getValidator();
+  if (!validate) {
+    return [];
+  }
+  const valid = validate(doc);
+  if (valid) {
+    return [];
+  }
+  return (validate.errors || []).map((e) => `${e.instancePath || "(root)"}: ${e.message}`);
+}

package/src/services/render-critic.ts

@@ -0,0 +1,75 @@
+/**
+ * Render-critic.js — Detached render probe for the AI agent loop
+ *
+ * After a mutation passes schema validation, this module attempts a lightweight headless render
+ * (buildScope → renderNode into a throwaway div) and reports render-time errors back through the
+ * same { ok, error } shape that applyAndValidate consumes. The model can then self-correct
+ * within the round budget instead of the user discovering a blank canvas.
+ *
+ * v1 scope: catches render throws only (missing $ref, malformed Function body, bad template
+ * expressions). Does NOT detect empty/zero-node output or deep-render custom element internals
+ * (connectedCallback doesn't fire on detached nodes).
+ *
+ * @license MIT
+ */
+
+import { buildScope, renderNode, setSkipServerFunctions } from "@jxsuite/runtime";
+import type { JxDocument } from "@jxsuite/schema/types";
+import { effectScope } from "../reactivity";
+
+/**
+ * Translate a render-time error into an actionable message the model can fix.
+ *
+ * @param {Error} err
+ * @returns {string}
+ */
+function translateRenderError(err: Error): string {
+  const msg = err.message || String(err);
+
+  if (msg.includes("is not defined") || msg.includes("Cannot read properties of")) {
+    return `Render error: ${msg}\n  → Fix: A $ref or template expression references a name that doesn't exist in state. Check that all $ref paths and \${...} expressions match entries in the document's "state" object.`;
+  }
+
+  if (msg.includes("is not a function")) {
+    return `Render error: ${msg}\n  → Fix: An event handler or computed value references something that isn't a function. Check $prototype: "Function" entries have a valid "body" string, and $ref event handlers point to function-typed state entries.`;
+  }
+
+  if (msg.includes("is not a constructor")) {
+    return `Render error: ${msg}\n  → Fix: A $prototype entry references a class or constructor that couldn't be resolved. Check the import path and $export name.`;
+  }
+
+  return `Render error: ${msg}\n  → Fix: The document is schema-valid but fails to render. Review the last change for typos in $ref paths, template expressions, or event handler definitions.`;
+}
+
+/**
+ * Attempt a detached render of a Jx document. Returns { ok: true } on success or { ok: false,
+ * error: string } with an actionable message on failure.
+ *
+ * @param {import("@jxsuite/schema/types").JxDocument} doc
+ * @returns {Promise<{ ok: true } | { ok: false; error: string }>}
+ */
+export async function renderCheck(
+  doc: JxDocument,
+): Promise<{ ok: true } | { ok: false; error: string }> {
+  const scope = effectScope();
+  try {
+    setSkipServerFunctions(true);
+
+    const state = await buildScope(doc, {});
+
+    const container = document.createElement("div");
+    scope.run(() => {
+      container.append(renderNode(doc, state));
+    });
+
+    return { ok: true };
+  } catch (error) {
+    return { ok: false, error: translateRenderError(error as Error) };
+  } finally {
+    // Dispose all effects created synchronously by renderNode. Effects from the async
+    // BuildScope (prototype/computed setup) escape the scope because Vue tracks the active
+    // Scope synchronously — they're GC-eligible once the throwaway state/container are
+    // Unreferenced. This bounded leak is acceptable for v1.
+    scope.stop();
+  }
+}

package/src/services/token-lint.ts

@@ -0,0 +1,140 @@
+/**
+ * Token-lint.js — flags hard-coded values in a Jx document that match a project design token.
+ *
+ * Soft hints: findings are surfaced in tool-result summaries so the model can self-correct. Does
+ * NOT fail mutations — see docs/ai-assistant-premium-components-plan.md §5 Phase 4.
+ */
+
+import type { JxMutableNode } from "@jxsuite/schema/types";
+
+interface TokenLintFinding {
+  path: string;
+  property: string;
+  value: string;
+  suggestedToken: string;
+}
+
+/**
+ * Build a reverse lookup from token values to token names. Normalizes hex colors to lowercase for
+ * case-insensitive matching.
+ *
+ * @param {Record<string, string>} projectStyle
+ * @returns {Map<string, string>}
+ */
+function buildTokenIndex(projectStyle: Record<string, string>) {
+  const index = new Map<string, string>();
+  for (const [key, value] of Object.entries(projectStyle)) {
+    if (!key.startsWith("--") || typeof value !== "string") {
+      continue;
+    }
+    const norm = value.toLowerCase().trim();
+    if (!index.has(norm)) {
+      index.set(norm, key);
+    }
+  }
+  return index;
+}
+
+/**
+ * Check whether a CSS value is already a token reference.
+ *
+ * @param {string} value
+ * @returns {boolean}
+ */
+function isTokenRef(value: string) {
+  return typeof value === "string" && value.includes("var(--");
+}
+
+/**
+ * Check whether a CSS value is a template expression (dynamic).
+ *
+ * @param {string} value
+ * @returns {boolean}
+ */
+function isTemplate(value: string) {
+  return typeof value === "string" && value.includes("${");
+}
+
+/**
+ * Scan a Jx document for hard-coded style values that match a project design token.
+ *
+ * @param {object} doc - The Jx document (or subtree)
+ * @param {Record<string, string>} projectStyle - The project.json style object
+ * @returns {TokenLintFinding[]}
+ */
+export function flagHardcodedTokens(
+  doc: JxMutableNode | null | undefined,
+  projectStyle: Record<string, string> | null | undefined,
+): TokenLintFinding[] {
+  if (!doc || !projectStyle) {
+    return [];
+  }
+
+  const tokenIndex = buildTokenIndex(projectStyle);
+  if (tokenIndex.size === 0) {
+    return [];
+  }
+
+  const findings: TokenLintFinding[] = [];
+
+  function walk(node: unknown, pathPrefix: string) {
+    if (!node || typeof node !== "object") {
+      return;
+    }
+    const el = node as JxMutableNode;
+
+    if (el.style && typeof el.style === "object") {
+      for (const [prop, val] of Object.entries(el.style)) {
+        if (prop.startsWith("@")) {
+          continue;
+        }
+        if (typeof val !== "string") {
+          continue;
+        }
+        if (isTokenRef(val) || isTemplate(val)) {
+          continue;
+        }
+
+        const norm = val.toLowerCase().trim();
+        const token = tokenIndex.get(norm);
+        if (token) {
+          findings.push({
+            path: pathPrefix,
+            property: prop,
+            value: val,
+            suggestedToken: token,
+          });
+        }
+      }
+    }
+
+    if (Array.isArray(el.children)) {
+      for (let i = 0; i < el.children.length; i++) {
+        const child = el.children[i];
+        if (child && typeof child === "object") {
+          walk(child, `${pathPrefix} > ${child.tagName || `[${i}]`}`);
+        }
+      }
+    }
+  }
+
+  const tag = doc.tagName || "root";
+  walk(doc, tag);
+  return findings;
+}
+
+/**
+ * Format findings as a human/model-readable hint string.
+ *
+ * @param {TokenLintFinding[]} findings
+ * @returns {string}
+ */
+export function formatTokenHints(findings: TokenLintFinding[]) {
+  if (findings.length === 0) {
+    return "";
+  }
+  const lines = findings.map(
+    (f) => `- ${f.path} → ${f.property}: "${f.value}" — use var(${f.suggestedToken}) instead`,
+  );
+  return `Token hints (prefer design tokens over hard-coded values):\n${lines.join("\n")}`;
+}