@jxsuite/studio 8.0.1 → 9.0.0

package/src/panels/stylebook-doc.ts

@@ -21,15 +21,9 @@ import { isKeyframesAtRule } from "@jxsuite/runtime/css";
 import type { StylebookEntry } from "./stylebook-panel";
 import type { ComponentEntry } from "../files/components";
 import type { JxPath } from "../state";
-import { isNonNullObject, isRef } from "@jxsuite/schema/guards";
+import { isNonNullObject } from "@jxsuite/schema/guards";
 import type { StylebookSpecimens } from "../style/stylebook-specimens";
-import type {
-  JxDocument,
-  JxHeadEntry,
-  JxMutableNode,
-  JxStateDefinition,
-  JxStyle,
-} from "@jxsuite/schema/types";
+import type { JxHeadEntry, JxMutableNode, JxStyle } from "@jxsuite/schema/types";
 
 export interface StylebookDocResult {
   /** The specimen document (plain JSON — safe to post over the bridge). */
@@ -210,40 +204,6 @@ export function catalogueRows(
   return out;
 }
 
-/**
- * A card's specimen for a component drawn as the first row of a list
- * (`style/stylebook-specimens.ts`): the list's repeater, reading its row from `rootState[key]` so
- * two cards' lists cannot collide, and the rest of the page state the row was drawn in, the first
- * card's value winning a shared name (`$page`, `$site`). Null when the sample is not a repeater
- * over a state list.
- */
-export function sampleRowSpecimen(
-  sample: JxDocument,
-  key: string,
-  rootState: Record<string, JxStateDefinition>,
-): JxMutableNode | null {
-  const [list] = Array.isArray(sample.children) ? sample.children : [];
-  if (!isNonNullObject(list) || Array.isArray(list) || !isRef(list.items)) {
-    return null;
-  }
-  const { $ref } = list.items;
-  const listKey = $ref.startsWith("#/state/") ? $ref.slice("#/state/".length) : "";
-  const rows = sample.state?.[listKey];
-  if (!Array.isArray(rows)) {
-    return null;
-  }
-  rootState[key] = rows;
-  for (const [name, value] of Object.entries(sample.state ?? {})) {
-    if (name !== listKey && !(name in rootState)) {
-      rootState[name] = value;
-    }
-  }
-  /* SAFETY: `list` is the repeater object a page's `children` held; only its `items` is replaced,
-     with a ref of the same shape. */
-  const repeater = { ...list, items: { $ref: `#/state/${key}` } } as JxMutableNode;
-  return { children: [repeater], tagName: "div" };
-}
-
 /** Options for {@link buildStylebookDoc}. */
 export interface BuildStylebookDocOpts {
   meta: { $sections: { label: string; elements: StylebookEntry[] }[] };
@@ -374,8 +334,6 @@ export function buildStylebookDoc(opts: BuildStylebookDocOpts): StylebookDocResu
 
   // Custom components from the registry — live custom elements registered via $elements.
   const $elements: (string | { $ref: string })[] = [];
-  // The data the sample-row cards read: each row's list, and the page context it was drawn in.
-  const rootState: Record<string, JxStateDefinition> = {};
   {
     let comps = opts.components;
     if (filter) {
@@ -404,12 +362,6 @@ export function buildStylebookDoc(opts: BuildStylebookDocOpts): StylebookDocResu
             const specimen: JxMutableNode = { $props: drawn.props, tagName: comp.tagName };
             return cardNode(comp.tagName, `<${comp.tagName}>`, specimen, cardPath, null);
           }
-          if (drawn?.kind === "row") {
-            const row = sampleRowSpecimen(drawn.sample.doc, `stylebookRow${ci}`, rootState);
-            if (row) {
-              return cardNode(comp.tagName, `<${comp.tagName}>`, row, cardPath, null);
-            }
-          }
           if (drawn?.kind !== "none") {
             const attributes: Record<string, string> = {};
             for (const p of comp.props ?? []) {
@@ -455,9 +407,6 @@ export function buildStylebookDoc(opts: BuildStylebookDocOpts): StylebookDocResu
     doc.$head = opts.effectiveHead;
   }
   doc.$media = opts.effectiveMedia;
-  if (Object.keys(rootState).length > 0) {
-    doc.state = rootState;
-  }
   doc.attributes = { class: "sb-root" };
   doc.children = sections;
   doc.style = transposeStylebookStyle(opts.effectiveStyle);

package/src/platform.ts

@@ -50,6 +50,26 @@ declare global {
   var __jxLauncher: LauncherSignal | undefined;
 }
 
+/**
+ * Whether this host offers Open Project at all: a native dialog (`openProject`), or the cloud's
+ * repository picker. The dev server has neither, because its windows open a project from the
+ * `?project=` URL parameter, so every surface that offers Open Project asks this first rather than
+ * drawing a control that cannot do anything.
+ */
+export function canOpenProject(platform: StudioPlatform | null | undefined): boolean {
+  if (!platform) {
+    return false;
+  }
+  if (isFunction(platform.openProject)) {
+    return true;
+  }
+  return (
+    platform.openProjectPicker === "repo-list" &&
+    isFunction(platform.listRepos) &&
+    isFunction(platform.importProject)
+  );
+}
+
 /** @param {StudioPlatform} platform */
 export function registerPlatform(platform: StudioPlatform) {
   globalThis.__jxPlatform = platform;

package/src/platforms/devserver.ts

@@ -2,18 +2,16 @@
  * Devserver.js — Dev Server Platform Adapter
  *
  * Implements the StudioPlatform interface for the @jxsuite/server development workflow. All file
- * I/O goes through /__studio/* REST endpoints. Project opening uses the Chrome File System Access
- * API (showDirectoryPicker).
+ * I/O goes through /__studio/* REST endpoints. There is no Open Project: a dev-server window opens
+ * a project from its `?project=` URL parameter (specs/desktop.md §8.2).
  *
  * See spec/desktop.md §8 for the full specification.
  */
 
 import { streamImport } from "../services/import-client";
-import { canPickDirectory, pickDirectoryPath } from "../services/directory-picker";
 import { negotiateCollab } from "@jxsuite/collab/negotiate";
 import type { CollabNegotiation } from "@jxsuite/collab/negotiate";
 import type { WsCollabConnection } from "@jxsuite/collab/client";
-import { isFunction } from "@jxsuite/schema/guards";
 import type { JsonObject, JsonValue, JxMutableNode, ProjectConfig } from "@jxsuite/schema/types";
 import type {
   DataConnectionsResponse,
@@ -80,16 +78,6 @@ interface FsEventBatch {
   events?: FsEvent[];
 }
 
-/** `showDirectoryPicker()` (WICG File System Access), which only Chromium-based browsers expose. */
-type ShowDirectoryPicker = (options: { mode: string }) => Promise<FileSystemDirectoryHandle>;
-
-/** True when the window implements the File System Access directory picker. */
-function hasDirectoryPicker(
-  host: Window,
-): host is Window & { showDirectoryPicker: ShowDirectoryPicker } {
-  return "showDirectoryPicker" in host && isFunction(host.showDirectoryPicker);
-}
-
 /** The options object {@link StudioPlatform.createProject} takes. */
 type CreateProjectOptions = Parameters<StudioPlatform["createProject"]>[0];
 
@@ -225,36 +213,6 @@ export function createDevServerPlatform() {
     return p.startsWith(`${_projectRoot}/`) ? p.slice(_projectRoot.length + 1) : p;
   }
 
-  /**
-   * Native folder chooser for the New Project modal's Browse… button. Present only when the browser
-   * implements `showDirectoryPicker` (Chromium-based); elsewhere the member stays undefined and the
-   * modal falls back to a typed Location field.
-   *
-   * The picked handle carries no filesystem path, so it is resolved by the id the picker tags the
-   * folder with (see `@jxsuite/studio/directory-picker`). Resolves `null` only when the user
-   * dismisses the chooser; every other failure rejects with a sentence the modal shows under
-   * Location. So `locate` keeps the helper's contract: `null` is "no folder holds this id" (the
-   * route's 200 `{ path: null }`), and a non-ok answer throws the problem the server sent rather
-   * than posing as a miss. A network failure (`TypeError: Failed to fetch`, e.g. a page that is not
-   * being served by the dev server at all) propagates as is, and the picker names it.
-   */
-  const directoryPicking: Pick<StudioPlatform, "pickDirectory"> = {};
-  if (canPickDirectory()) {
-    directoryPicking.pickDirectory = async (): Promise<string | null> =>
-      pickDirectoryPath(async ({ id, name }) => {
-        const res = await fetch(
-          `/__studio/locate-directory?name=${encodeURIComponent(name)}&id=${encodeURIComponent(id)}`,
-        );
-        if (!res.ok) {
-          // A proxy, or a `views://` host with no dev server behind it, may answer in HTML.
-          const body = await readJson<JsonValue>(res).catch(() => null);
-          throw new Error(problemMessage(body, res.status));
-        }
-        const found = await readJson<{ path?: string | null }>(res);
-        return found.path ?? null;
-      });
-  }
-
   return {
     id: "devserver",
 
@@ -293,80 +251,6 @@ export function createDevServerPlatform() {
       await postActivate(root ?? _projectRoot);
     },
 
-    // ─── Project opening ──────────────────────────────────────────────────
-
-    async openProject() {
-      // Use Chrome's showDirectoryPicker API
-      const host = window;
-      if (!hasDirectoryPicker(host)) {
-        throw new Error("showDirectoryPicker not available — use a Chromium-based browser");
-      }
-
-      let dirHandle;
-      try {
-        dirHandle = await host.showDirectoryPicker({ mode: "readwrite" });
-      } catch (error) {
-        // User cancelled the picker
-        if (error instanceof Error && error.name === "AbortError") {
-          return null;
-        }
-        throw error;
-      }
-
-      // Read project.json from the chosen directory
-      let siteHandle;
-      try {
-        siteHandle = await dirHandle.getFileHandle("project.json");
-      } catch {
-        throw new Error("No project.json found in selected folder");
-      }
-
-      const file = await siteHandle.getFile();
-      /* SAFETY: the user picked this folder as a project, and project.json is that project's own
-         config file; it is matched below against the server's parse of the same file, and every
-         adapter hands project.json to Studio as the ProjectConfig the session edits. */
-      const config = JSON.parse(await file.text()) as ProjectConfig;
-
-      // Resolve server-relative path by matching against known sites
-      const sitesRes = await fetch("/__studio/sites");
-      if (!sitesRes.ok) {
-        throw new Error("Failed to fetch site list from server");
-      }
-      const sites = await readJson<SiteEntry[]>(sitesRes);
-      const match = sites.find(
-        (s: SiteEntry) => JSON.stringify(s.config) === JSON.stringify(config),
-      );
-
-      if (!match) {
-        // Project is outside dev server root — ask the server to find it by directory name
-        const findRes = await fetch(
-          `/__studio/find-project?name=${encodeURIComponent(dirHandle.name)}`,
-        );
-        if (!findRes.ok) {
-          throw new Error("Could not locate project on disk");
-        }
-        const found = await readJson<{ path?: string }>(findRes);
-        if (!found.path) {
-          throw new Error(`Could not find project directory "${dirHandle.name}"`);
-        }
-        _projectRoot = found.path;
-      } else {
-        _projectRoot = match.path;
-      }
-
-      // Notify server of active project for static file resolution
-      await this.activate();
-
-      return {
-        config,
-        handle: {
-          name: config.name || _projectRoot.split("/").pop()!,
-          projectConfig: config,
-          root: _projectRoot,
-        },
-      };
-    },
-
     /**
      * Probe the server root to see if it is itself a site project. Used at startup to auto-detect
      * projects.
@@ -408,8 +292,6 @@ export function createDevServerPlatform() {
       return await res.json();
     },
 
-    ...directoryPicking,
-
     /** List starter templates from the dev server. */
     async listStarters(): Promise<StarterInfo[]> {
       const res = await fetch("/__studio/starters");

package/src/services/ai-ask.ts

@@ -1,12 +1,10 @@
 /**
  * Ai-ask.ts — the assistant's one way to stop and put a question to the author.
  *
- * The agent loop `await`s `toolRegistry.execute` (`services/tool-executor.ts`), so a tool that
- * returns a pending promise suspends the turn. That is the whole mechanism: `ask_user` registers a
- * question, hands back a promise, and the panel resolves it when the human answers. No new chat
- * status, no pre-execution hook, and nothing in the published `@jxsuite/ai` changes —
- * `finishStream` has already set the state to `"idle"` by the time tools run, so a suspended turn
- * is idle by construction and this store is what "waiting" means.
+ * `ask_user` declares what it asks (`interaction`) and what its answer means (`settle`), and has no
+ * body that waits: the invoker answers `needs_input` before any tool code runs, the turn engine
+ * puts the question to the assistant's interaction store (`harness/interaction-store.ts`), and the
+ * person's answer comes back through `settle` as the call's result (specs/ai.md §3.4 and §3.11).
  *
  * Two decisions are load-bearing and easy to get wrong on a rewrite:
  *
@@ -17,29 +15,16 @@
  *   between them is a 400. The answer travels as the tool result, and the chat view renders it into
  *   the question's own chip.
  *
- * Exactly one question can be outstanding, because `runAgentLoop` executes a round's tool calls
- * serially. The guard below is defensive, not load-bearing.
- *
  * @license MIT
  */
 
+import { JX_TOOL_FACTS } from "@jxsuite/ai/jx-tools";
 import { createToolDefinition, toolError, toolSuccess } from "@jxsuite/ai/tools";
 import { isString } from "@jxsuite/schema/guards";
-import { reactive } from "../reactivity";
-
-import type { ToolRegistry } from "@jxsuite/ai/tools";
 
-/** A question the assistant is waiting on. `id` is the tool-call id, so the chip and this agree. */
-export interface PendingAsk {
-  id: string;
-  question: string;
-  /** Short choices rendered as buttons. Free text is always allowed alongside them. */
-  options: string[];
-  /** One line of why-I'm-asking, rendered under the question. */
-  context: string;
-}
+import type { InteractionResponse, ToolRegistry } from "@jxsuite/ai/tools";
 
-/** How a question was settled. `answer: null` with `skipped` is the author saying "you decide". */
+/** What a settled question's result carries: the answer, or `null` with `skipped` for "you decide". */
 export interface AskAnswer {
   answer: string | null;
   skipped: boolean;
@@ -48,112 +33,6 @@ export interface AskAnswer {
 /** Max choices rendered as buttons; beyond this the question wants free text, not a menu. */
 const MAX_OPTIONS = 6;
 
-const state = reactive<{ pending: PendingAsk | null }>({ pending: null });
-
-/** The resolver for {@link state.pending}, kept out of the reactive object (it is not render data). */
-let settle: ((answer: AskAnswer) => void) | null = null;
-
-/** Torn down with the question so a stopped turn does not leave a listener on a dead signal. */
-let detachAbort: (() => void) | null = null;
-
-function clear() {
-  state.pending = null;
-  settle = null;
-  detachAbort?.();
-  detachAbort = null;
-}
-
-/**
- * The outstanding question, or null. Reactive — read it inside an `effect()` to repaint on it.
- *
- * @returns {PendingAsk | null}
- */
-export function pendingAsk(): PendingAsk | null {
-  return state.pending;
-}
-
-/** Whether a turn is suspended on the author. The composer's Send becomes Answer on this. */
-export function isAwaitingAnswer(): boolean {
-  return state.pending !== null;
-}
-
-/**
- * Register a question and suspend until it is settled.
- *
- * @param {PendingAsk} ask
- * @param {AbortSignal} [signal] - The asking call's signal. Without one the question can still be
- *   settled by {@link cancelAsk}, but a Stop would leave the turn awaiting a promise nothing could
- *   resolve.
- * @returns {Promise<AskAnswer>} Resolves on an answer, a skip, or the turn being stopped (`{
- *   answer: null, skipped: false }` — the shape the tool reports as a failure).
- */
-export function askUser(ask: PendingAsk, signal?: AbortSignal): Promise<AskAnswer> {
-  return new Promise<AskAnswer>((resolve) => {
-    state.pending = ask;
-    settle = resolve;
-
-    if (signal?.aborted) {
-      clear();
-      resolve({ answer: null, skipped: false });
-      return;
-    }
-    if (signal) {
-      const onAbort = () => {
-        cancelAsk();
-      };
-      signal.addEventListener("abort", onAbort, { once: true });
-      detachAbort = () => signal.removeEventListener("abort", onAbort);
-    }
-  });
-}
-
-/**
- * Answer the outstanding question.
- *
- * @param {string} text
- * @returns {boolean} False when nothing was pending, so a caller can fall through to a normal send.
- */
-export function answerAsk(text: string): boolean {
-  if (!settle) {
-    return false;
-  }
-  const resolve = settle;
-  clear();
-  resolve({ answer: text, skipped: false });
-  return true;
-}
-
-/**
- * Decline to answer — "you decide". Settles as a success, so the turn carries on.
- *
- * @returns {boolean} False when nothing was pending.
- */
-export function skipAsk(): boolean {
-  if (!settle) {
-    return false;
-  }
-  const resolve = settle;
-  clear();
-  resolve({ answer: null, skipped: true });
-  return true;
-}
-
-/** Settle an outstanding question as unanswered. Called from `stop()` and from the turn's abort. */
-export function cancelAsk(): void {
-  if (!settle) {
-    return;
-  }
-  const resolve = settle;
-  clear();
-  resolve({ answer: null, skipped: false });
-}
-
-/** Drop any outstanding question without settling a turn. For New Chat and for tests. */
-export function resetAsk(): void {
-  cancelAsk();
-  clear();
-}
-
 /**
  * Register `ask_user` into a tool registry.
  *
@@ -163,24 +42,12 @@ export function resetAsk(): void {
  *
  * @param {Pick<ToolRegistry, "register">} registry
  */
-/** What the host that registers the question tool may hook. */
-export interface AskToolOptions {
-  /**
-   * Called once a question has been put to the author, before the turn waits on the answer. A host
-   * saves the conversation here: a turn suspended on a person may wait for as long as they like,
-   * and a reload in the meantime must still find the question to restore as open (`specs/ai.md`
-   * §3.4).
-   */
-  onPending?: () => void;
-}
-
-export function registerAskTool(
-  registry: Pick<ToolRegistry, "register">,
-  { onPending }: AskToolOptions = {},
-): void {
+export function registerAskTool(registry: Pick<ToolRegistry, "register">): void {
   registry.register(
     createToolDefinition({
       name: "ask_user",
+      title: "Ask the user",
+      annotations: JX_TOOL_FACTS.ask_user.annotations,
       // It suspends the turn on the author, so a round that only asked spends no work budget.
       interactive: true,
       description:
@@ -212,43 +79,32 @@ export function registerAskTool(
         },
         required: ["question"],
       },
-      execute: async (args, ctx) => {
+      interaction(args) {
         /* Every field is any JSON value, narrowed by a guard rather than by `?.`. The registry's
-           `validate()` is "a lightweight structural check, not a JSON Schema validator",
-           `strict: false` skips it entirely, and this tool may be registered into someone else's
-           registry — so an argument that is a number is a case, not an impossibility. Optional
-           chaining guards null, not type: `context?.trim()` threw on one. */
+           `validate()` is "a lightweight structural check, not a JSON Schema validator", and this
+           tool may be registered into someone else's registry, so an argument that is a number is
+           a case, not an impossibility. Optional chaining guards null, not type: `context?.trim()`
+           threw on one. */
         const { question, options, context } = args;
         if (!isString(question) || !question.trim()) {
-          return toolError('Pass "question" — the question to put to the user.');
-        }
-        if (isAwaitingAnswer()) {
-          return toolError("A question is already waiting for the user.");
+          return { refusal: 'Pass "question" — the question to put to the user.' };
         }
         const choices = Array.isArray(options)
           ? options
               .filter((o): o is string => isString(o) && o.trim().length > 0)
               .slice(0, MAX_OPTIONS)
           : [];
-
-        const answering = askUser(
-          {
-            context: isString(context) ? context.trim() : "",
-            /* The tool-call id, so the chip the transcript draws and the question this registers
-               are the same thing. Without it a restored, permanently unanswered question would
-               render identically to the live one. */
-            id: ctx.callId,
-            options: choices,
-            question: question.trim(),
-          },
-          ctx.signal,
-        );
-        // The question is published by now (`askUser` sets it synchronously); the answer is not.
-        if (isAwaitingAnswer()) {
-          onPending?.();
-        }
-        const { answer, skipped } = await answering;
-
+        return {
+          context: isString(context) ? context.trim() : "",
+          kind: "question",
+          options: choices,
+          question: question.trim(),
+        };
+      },
+      settle(_args, response) {
+        /* SAFETY: `ask_user` only ever asks a question, so the response the invoker hands back is
+           the answer to one. */
+        const { answer, skipped } = response as Extract<InteractionResponse, { kind: "question" }>;
         if (skipped) {
           /* A success: the model asked, and "you decide" is an answer. Rendering it as a failure
              would have the model apologise for having asked a fair question. */
@@ -262,6 +118,8 @@ export function registerAskTool(
         }
         return toolSuccess({ answer, skipped: false }, `The user answered: "${answer}"`);
       },
+      // Never reached through the invoker, which settles an interaction instead of executing it.
+      execute: () => toolError("ask_user needs a person, and none is available here."),
     }),
   );
 }