@jxsuite/studio 1.0.0 → 1.2.0

package/src/services/document-assistant.ts

@@ -12,16 +12,22 @@
 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 { activeTab, setWorkspaceProject, workspace } from "../workspace/workspace";
 import { toRaw } from "../reactivity";
+import { projectState, setProjectState } from "../store";
+import type { Tab } from "../tabs/tab";
 import { componentRegistry } from "../files/components";
 import { registerAiTools } from "./ai-tools";
+import { registerProjectTools } from "./ai-project-tools";
+import { createGatedToolRegistry } from "./gated-registry";
+import type { ToolAvailability } from "./gated-registry";
+import { adoptProject } from "./project-adoption";
 import { runAgentLoop } from "./tool-executor";
-import { buildSystemPrompt } from "./ai-system-prompt";
+import { AI_TOOL_TIERS, buildSystemPrompt, tierActive } 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";
+import { openFileInTab, reloadFileInTab } from "../files/files";
 import * as sessionStore from "./ai-session-store";
 
 /**
@@ -51,8 +57,23 @@ function projectRoot() {
 export function createDocumentAssistant() {
   const chatState = createChatState({ model: getModel() });
 
-  const toolRegistry = createToolRegistry();
-  registerAiTools(toolRegistry, {
+  /** The persisted session backing the live chat; null = fresh unsaved chat. */
+  let sessionId: string | null = null;
+
+  const getProjectStyle = () =>
+    (workspace.projectConfig as ProjectConfig | null)?.style as Record<string, string> | undefined;
+
+  const findOpenTab = (path: string): Tab | null => {
+    for (const tab of workspace.tabs.values()) {
+      if (tab.documentPath === path) {
+        return tab;
+      }
+    }
+    return null;
+  };
+
+  const innerRegistry = createToolRegistry();
+  registerAiTools(innerRegistry, {
     getTab: () => activeTab.value,
     saveFile: async (relPath: string, content: string) => {
       const plat = getPlatform();
@@ -62,23 +83,72 @@ export function createDocumentAssistant() {
       doc: unknown,
     ) => Promise<{ ok: true } | { ok: false; error: string }>,
     openDocument: openFileInTab,
-    projectStyle: (workspace.projectConfig as ProjectConfig | null)?.style as
-      | Record<string, string>
-      | undefined,
+    getProjectStyle,
+    findOpenTab,
+    reloadTab: reloadFileInTab,
+  });
+  registerProjectTools(innerRegistry, {
+    getTab: () => activeTab.value,
+    renderCheck: renderCheck as (
+      doc: unknown,
+    ) => Promise<{ ok: true } | { ok: false; error: string }>,
+    getProjectStyle,
+    findOpenTab,
+    reloadTab: reloadFileInTab,
+    adoptProject,
+    // Re-key the live chat from the unscoped store to the adopted project so the bootstrap
+    // Conversation keeps persisting (saveSession drops writes for ids missing from the index).
+    onProjectAdopted: (root: string) => {
+      if (sessionId) {
+        sessionStore.moveSession("", root, sessionId);
+      }
+    },
+    onProjectConfigWritten: (config: object) => {
+      setWorkspaceProject(workspace.projectRoot, config);
+      if (projectState) {
+        setProjectState({ ...projectState, projectConfig: config as ProjectConfig });
+      }
+    },
   });
 
-  let controller: AbortController | null = null;
+  /*
+   * Gate tool advertisement/execution on live studio state, derived from the same tier table the
+   * system prompt renders — the model is never shown a tool it cannot execute. listForLLM() runs
+   * every agent-loop round, so a mid-loop create_project unlocks the higher tiers immediately.
+   */
+  const TIER_REQUIREMENTS = {
+    "no-project": "no project to be open (it bootstraps one)",
+    project: "an open project",
+    document: "an open document (use open_document first)",
+  } as const;
+  const availability = new Map<string, ToolAvailability>(
+    AI_TOOL_TIERS.map((t) => [
+      t.name,
+      {
+        when: () => tierActive(t.tier, Boolean(workspace.projectRoot), Boolean(activeTab.value)),
+        requires: TIER_REQUIREMENTS[t.tier],
+      },
+    ]),
+  );
+  const toolRegistry = createGatedToolRegistry(innerRegistry, availability);
 
-  /** The persisted session backing the live chat; null = fresh unsaved chat. */
-  let sessionId: string | null = null;
+  let controller: AbortController | null = null;
 
   function buildPrompt() {
     const tab = activeTab.value;
+    const inventory = projectState
+      ? [...projectState.dirs.values()]
+          .flat()
+          .filter((e) => e.type === "file")
+          .map((e) => e.path)
+      : undefined;
     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,
+      hasProject: Boolean(workspace.projectRoot),
+      ...(inventory && inventory.length > 0 ? { fileInventory: inventory } : {}),
     });
   }
 

package/src/services/gated-registry.ts

@@ -0,0 +1,72 @@
+/**
+ * Gated-registry.ts — state-aware tool advertisement for the AI assistant.
+ *
+ * Wraps a `@jxsuite/ai` ToolRegistry so each tool is only advertised to the LLM while its
+ * availability predicate holds (no project open → bootstrap tools only; project open → file tools;
+ * document open → document tools). `runAgentLoop` calls `listForLLM()` every round, so availability
+ * flips mid-loop: after `create_project` succeeds, the very next round advertises the file and
+ * document tools without any extra plumbing.
+ *
+ * Executing a tool whose predicate currently fails returns a tool error naming the missing state
+ * instead of throwing, so the agent loop can self-correct.
+ *
+ * @license MIT
+ */
+
+import type { ToolDefinition, ToolRegistry } from "@jxsuite/ai/tools";
+
+export interface ToolAvailability {
+  /** Whether the tool is currently advertised/executable. */
+  when: () => boolean;
+  /** Human-readable requirement, surfaced when execution is refused (e.g. "a project is open"). */
+  requires: string;
+}
+
+/**
+ * Wrap `inner` so tools listed in `availability` are only advertised/executable while their
+ * predicate holds. Tools without an entry are always available.
+ *
+ * @param {ToolRegistry} inner
+ * @param {Map<string, ToolAvailability>} availability
+ * @returns {ToolRegistry}
+ */
+export function createGatedToolRegistry(
+  inner: ToolRegistry,
+  availability: Map<string, ToolAvailability>,
+): ToolRegistry {
+  function isAvailable(name: string): boolean {
+    const gate = availability.get(name);
+    return gate ? gate.when() : true;
+  }
+
+  return {
+    register(tool: ToolDefinition) {
+      inner.register(tool);
+    },
+    list() {
+      return inner.list().filter((t) => isAvailable(t.name));
+    },
+    listForLLM() {
+      const available = new Set(this.list().map((t) => t.name));
+      return inner
+        .listForLLM()
+        .filter((t) => available.has((t as { function?: { name?: string } }).function?.name ?? ""));
+    },
+    getDefinition(toolName: string) {
+      return inner.getDefinition(toolName);
+    },
+    validate(toolName: string, args: object) {
+      return inner.validate(toolName, args);
+    },
+    async execute(toolName: string, args: object) {
+      if (inner.getDefinition(toolName) && !isAvailable(toolName)) {
+        const gate = availability.get(toolName);
+        return {
+          success: false,
+          error: `Tool "${toolName}" is not available right now — it requires ${gate?.requires ?? "a different studio state"}.`,
+        };
+      }
+      return inner.execute(toolName, args);
+    },
+  };
+}

package/src/services/preview-eval.ts

@@ -0,0 +1,68 @@
+/// <reference lib="dom" />
+/**
+ * Parent-side live expression preview (spec §19.9).
+ *
+ * Evaluates an expression node against the canvas iframe's last dataScope snapshot
+ * (tab.session.canvas.scope) on a structuredClone, so mutating operators are safe — they mutate the
+ * clone, never the live canvas. The engine's trace hook reports every sub-node's value keyed by its
+ * path within the tree; values are formatted to display strings at report time so later mutations
+ * of the clone cannot retroactively change a badge.
+ */
+
+import { evaluateExpression, isMutating } from "@jxsuite/runtime/expression";
+import { toRaw } from "../reactivity";
+// Imported for local use AND re-exported below so existing consumers keep their import site.
+// oxlint-disable-next-line unicorn/prefer-export-from
+import { formatPreviewValue } from "../utils/preview-format";
+
+import type { ExpressionNode } from "@jxsuite/runtime/expression";
+
+export interface ExpressionPreview {
+  /** Path-keyed display values: "" is the root node, "value/target" a nested operand, etc. */
+  values: Map<string, string>;
+  /** Evaluation error message, if the expression threw. */
+  error: string | null;
+  /** Whether the root operator mutates its target (badge renders as an effect, not a value). */
+  mutating: boolean;
+}
+
+// The formatter is shared with the in-iframe live evaluator: it lives in utils/preview-format.ts
+// (dependency-light, safe for the iframe bundle) and is re-exported here so existing consumers
+// Keep their import site.
+export { formatPreviewValue };
+
+/**
+ * Evaluate `node` against a scope snapshot for display. Returns null when no snapshot is available
+ * (canvas not yet rendered) — the editor renders no badges rather than wrong ones.
+ */
+export function previewExpression(
+  node: unknown,
+  scope?: Record<string, unknown> | null,
+): ExpressionPreview | null {
+  if (!scope || !node || typeof node !== "object" || !("operator" in node)) {
+    return null;
+  }
+
+  let state: Record<string, unknown>;
+  try {
+    // Callers hand over tab.session.canvas.scope, which the reactive session tree wraps in a
+    // Proxy — structuredClone rejects proxies, so unwrap to the raw snapshot first.
+    state = structuredClone(toRaw(scope));
+  } catch {
+    // Snapshot values are JSON-safe by construction (serialize-scope), but stay defensive.
+    return null;
+  }
+
+  const values = new Map<string, string>();
+  const expr = node as ExpressionNode;
+  let errorMessage: string | null = null;
+  try {
+    evaluateExpression(expr, state, null, undefined, {
+      report: (path, value) => values.set(path.join("/"), formatPreviewValue(value)),
+    });
+  } catch (error) {
+    errorMessage = error instanceof Error ? error.message : String(error);
+  }
+
+  return { error: errorMessage, mutating: isMutating(expr.operator), values };
+}

package/src/services/project-adoption.ts

@@ -0,0 +1,31 @@
+/**
+ * Project-adoption.ts — a late-bound slot for opening a freshly created project in this window.
+ *
+ * The AI `create_project` tool (services/ai-project-tools.ts) needs to run the full project-open
+ * flow (`openRecentProject` in studio.ts), but services must not import studio.ts — the entry
+ * module imports the services. studio.ts registers the adopter at boot; the tool calls
+ * `adoptProject(root)`.
+ *
+ * @license MIT
+ */
+
+let _adopter: ((root: string) => Promise<void>) | null = null;
+
+/** Register the project-open flow (studio.ts boot). */
+export function setProjectAdopter(fn: (root: string) => Promise<void>): void {
+  _adopter = fn;
+}
+
+/**
+ * Open the project at `root` in this window via the registered flow.
+ *
+ * @param {string} root - Absolute project root.
+ */
+export async function adoptProject(root: string): Promise<void> {
+  if (!_adopter) {
+    throw new Error(
+      "Project adoption is not available in this environment — open the project manually from the welcome screen.",
+    );
+  }
+  await _adopter(root);
+}

package/src/settings/css-vars-editor.ts

@@ -1,17 +1,26 @@
 /// <reference lib="dom" />
 /**
- * CSS Variables editor — form-based editor for managing design tokens. Colors and fonts are NOT
- * media-aware; sizes/spacing are media-aware.
+ * CSS Variables editor — form-based editor for managing design tokens. Colors are scheme-aware
+ * (per-scheme overrides in `@--dark`-style blocks, spec §9.5); sizes/spacing are media-aware; fonts
+ * are neither.
  */
 
 import { html, render as litRender, nothing } from "lit-html";
 import { ref } from "lit-html/directives/ref.js";
 import { projectState } from "../store";
 import { getEffectiveMedia, updateSiteConfig } from "../site-context";
+import { postSiteStyleToLiveHosts } from "../canvas/iframe-host";
+import { isSchemeQuery, schemeOfQuery } from "../utils/canvas-media";
 import { friendlyNameToVar, varDisplayName } from "../utils/studio-utils";
 
 import type { JxStyle } from "@jxsuite/schema/types";
 
+/** A declared scheme query in $media: the block key name plus the scheme it targets. */
+export interface SchemeEntry {
+  name: string;
+  scheme: "light" | "dark";
+}
+
 /** @param {HTMLElement} container */
 export function renderCssVarsEditor(container: HTMLElement) {
   const config = projectState?.projectConfig || {};
@@ -50,10 +59,20 @@ export function renderCssVarsEditor(container: HTMLElement) {
     }
   }
 
-  const mediaNames = media ? Object.keys(media).filter((m) => m !== "--") : [];
+  const mediaNames = media
+    ? Object.keys(media).filter((m) => m !== "--" && !isSchemeQuery(String(media[m])))
+    : [];
+  const schemeEntries: SchemeEntry[] = media
+    ? Object.entries(media).flatMap(([name, query]) => {
+        const scheme = schemeOfQuery(String(query));
+        return scheme ? [{ name, scheme }] : [];
+      })
+    : [];
 
   const save = () => {
     void updateSiteConfig({ style: { ...rootStyle } });
+    // Live canvas feedback: replace the site-style sheet in place — no re-render needed.
+    postSiteStyleToLiveHosts();
   };
 
   const updateVar = (name: string, val: string) => {
@@ -61,6 +80,35 @@ export function renderCssVarsEditor(container: HTMLElement) {
     save();
   };
 
+  // Write/clear a per-scheme token override in the scheme's `@--name` block (spec §9.5). An empty
+  // Value clears the override (and drops the block when it empties) — the token inherits the base.
+  const updateSchemeVar = (schemeName: string, varName: string, val: string) => {
+    const key = `@${schemeName}`;
+    if (val) {
+      const block = (rootStyle[key] ??= {}) as Record<string, unknown>;
+      block[varName] = val;
+    } else {
+      const block = rootStyle[key];
+      if (block && typeof block === "object") {
+        delete (block as Record<string, unknown>)[varName];
+        if (Object.keys(block).length === 0) {
+          delete rootStyle[key];
+        }
+      }
+    }
+    save();
+    renderCssVarsEditor(container);
+  };
+
+  // Without a declared scheme query nothing ever shows the scheme UI (here or in the tab bar) —
+  // This is the opt-in affordance for existing projects. Re-render after the async config update
+  // Lands (unlike style edits, $media is not mutated in place).
+  const enableDarkScheme = () => {
+    void updateSiteConfig({
+      $media: { ...config.$media, "--dark": "(prefers-color-scheme: dark)" },
+    }).then(() => renderCssVarsEditor(container));
+  };
+
   const deleteVar = (name: string) => {
     delete rootStyle[name];
     save();
@@ -81,7 +129,16 @@ export function renderCssVarsEditor(container: HTMLElement) {
     <div class="settings-section">
       <h3 class="settings-section-title">CSS Variables</h3>
 
-      ${renderColorSection(groups.color, updateVar, deleteVar, addVar)}
+      ${renderColorSection(
+        groups.color,
+        updateVar,
+        deleteVar,
+        addVar,
+        rootStyle,
+        schemeEntries,
+        updateSchemeVar,
+        enableDarkScheme,
+      )}
       ${renderFontSection(groups.font, updateVar, deleteVar, addVar)}
       ${renderSizeSection(groups.size, updateVar, deleteVar, addVar, rootStyle, mediaNames)}
       ${groups.other.length > 0
@@ -104,6 +161,10 @@ function renderColorSection(
   updateVar: (name: string, val: string) => void,
   deleteVar: (name: string) => void,
   addVar: (prefix: string, friendlyName: string, val: string) => void,
+  rootStyle: JxStyle,
+  schemeEntries: SchemeEntry[],
+  updateSchemeVar: (schemeName: string, varName: string, val: string) => void,
+  enableDarkScheme: () => void,
 ) {
   return html`
     <div class="css-vars-group">
@@ -129,9 +190,66 @@ function renderColorSection(
               <sp-icon-delete slot="icon"></sp-icon-delete>
             </sp-action-button>
           </div>
+          ${schemeEntries.map((entry) =>
+            renderSchemeOverride(name, rootStyle, entry, updateSchemeVar),
+          )}
         `,
       )}
       ${renderAddRow("--color-", "Primary Blue", "#3b82f6", addVar)}
+      ${schemeEntries.length === 0
+        ? html`
+            <sp-action-button
+              size="s"
+              class="css-vars-enable-dark"
+              title="Add a dark color scheme: declares --dark in $media so every color token can carry a dark value"
+              @click=${enableDarkScheme}
+            >
+              Enable dark scheme
+            </sp-action-button>
+          `
+        : nothing}
+    </div>
+  `;
+}
+
+/**
+ * One per-scheme override row under a color token: swatch + field bound to the scheme block's
+ * value. Empty shows "inherits" (the base value applies); clearing deletes the override.
+ *
+ * @param {string} varName
+ * @param {JxStyle} rootStyle
+ * @param {SchemeEntry} entry
+ * @param {(schemeName: string, varName: string, val: string) => void} updateSchemeVar
+ */
+function renderSchemeOverride(
+  varName: string,
+  rootStyle: JxStyle,
+  entry: SchemeEntry,
+  updateSchemeVar: (schemeName: string, varName: string, val: string) => void,
+) {
+  const block = rootStyle[`@${entry.name}`];
+  const current =
+    block && typeof block === "object" ? (block as Record<string, unknown>)[varName] : undefined;
+  const label = entry.scheme === "dark" ? "Dark" : "Light";
+  return html`
+    <div class="css-var-media-row css-var-scheme-row">
+      <span class="css-var-media-label">${label}</span>
+      <div class="css-var-swatch" style="background:${current ?? "transparent"}">
+        <input
+          type="color"
+          .value=${current && String(current).startsWith("#") ? String(current) : "#111111"}
+          @input=${(e: Event) =>
+            updateSchemeVar(entry.name, varName, (e.target as HTMLInputElement).value)}
+        />
+      </div>
+      <sp-textfield
+        size="s"
+        placeholder="inherits"
+        .value=${current == null ? "" : String(current)}
+        @change=${(e: Event) =>
+          updateSchemeVar(entry.name, varName, (e.target as HTMLInputElement).value)}
+        style="flex:1;max-width:160px"
+      ></sp-textfield>
     </div>
   `;
 }

package/src/site-context.ts

@@ -8,6 +8,7 @@
 
 import { projectState, requireProjectState, setProjectState } from "./store";
 import { getPlatform } from "./platform";
+import { setWorkspaceProject, workspace } from "./workspace/workspace";
 
 import type {
   JxElement,
@@ -272,6 +273,7 @@ export async function updateSiteConfig(patch: Partial<ProjectConfig>) {
   } as ProjectConfig;
   await platform.writeFile("project.json", JSON.stringify(config, null, 2));
   setProjectState({ ...requireProjectState(), projectConfig: config });
+  setWorkspaceProject(workspace.projectRoot, config);
   if ("extensions" in patch) {
     const { loadFormats, refreshExtensionUi, refreshFormats } =
       await import("./format/format-host");

package/src/store.ts

@@ -37,16 +37,20 @@ export let canvasWrap = null as unknown as HTMLElement;
 export let activityBar = null as unknown as HTMLElement;
 export let leftPanel = null as unknown as HTMLElement;
 export let rightPanel = null as unknown as HTMLElement;
+export let chatPanelEl = null as unknown as HTMLElement;
 export let toolbarEl = null as unknown as HTMLElement;
 export let statusbarEl = null as unknown as HTMLElement;
+export let frontmatterPanelEl = null as unknown as HTMLElement;
 
 export function initShellRefs() {
   canvasWrap = document.querySelector("#canvas-wrap") as HTMLElement;
   activityBar = document.querySelector("#activity-bar") as HTMLElement;
   leftPanel = document.querySelector("#left-panel") as HTMLElement;
   rightPanel = document.querySelector("#right-panel") as HTMLElement;
+  chatPanelEl = document.querySelector("#chat-panel") as HTMLElement;
   toolbarEl = document.querySelector("#toolbar") as HTMLElement;
   statusbarEl = document.querySelector("#statusbar") as HTMLElement;
+  frontmatterPanelEl = document.querySelector("#frontmatter-panel") as HTMLElement;
 }
 
 // ─── Shared containers (mutated in place by owner modules) ───────────────────