@jxsuite/studio 3.0.0 → 4.0.0

package/src/new-project/new-project-modal.ts

@@ -30,6 +30,7 @@ import { installUrlOf } from "../platform-errors";
 import { hasAiCredentials } from "../services/ai-models";
 import { setPendingAgentPrompt } from "../services/agent-seed";
 import { initProjectRepo } from "../files/files";
+import { runImportHandoff } from "../services/import-seed";
 import { createAiCredentialsForm } from "../ui/ai-credentials-form";
 import { createManagedConnect } from "../ui/ai-managed-connect";
 import {
@@ -39,14 +40,10 @@ import {
   resetLocationFields,
 } from "./location-fields";
 import {
-  cancelImport,
+  handoffImport,
   importButtonLabel,
-  isImportRunning,
-  renderImportProgress,
   renderImportSource,
-  renderImportStatus,
   resetImportTab,
-  startImport,
   validateImportSource,
 } from "./import-tab";
 import type { ProjectConfig } from "@jxsuite/schema/types";
@@ -211,9 +208,6 @@ export function closeNewProjectModal() {
   if (!_handle || _creating) {
     return;
   }
-  if (isImportRunning()) {
-    cancelImport(importCtxFor(renderModal));
-  }
   _handle.close();
   _handle = null;
   if (_resolve) {
@@ -223,7 +217,7 @@ export function closeNewProjectModal() {
 }
 
 /** Close the modal and resolve its promise with a created/imported project. */
-function finish(result: { root: string; config: ProjectConfig }) {
+function finish(result: { root: string; config: ProjectConfig } | null) {
   _creating = false;
   if (_handle) {
     _handle.close();
@@ -236,8 +230,12 @@ function finish(result: { root: string; config: ProjectConfig }) {
 }
 
 /**
- * Every path out of the wizard that produced a project: initialise version control for it, then
- * hand it to the caller. A scaffold is not a repository, and Delete and Rename are one click away.
+ * Every path out of the wizard that produced a project HERE: initialise version control for it,
+ * then hand it to the caller. A scaffold is not a repository, and Delete and Rename are one click
+ * away.
+ *
+ * The Import path does not come through here any more — `import_site` creates the project, so the
+ * obligation moved with it into `services/project-adoption.ts`, which both bootstrap tools share.
  */
 async function finishCreated(result: { root: string; config: ProjectConfig }) {
   await initProjectRepo(result.root);
@@ -275,9 +273,13 @@ function importCtxFor(rerender: () => void): ImportTabCtx {
     credsForm: credsForm(),
     form: _form,
     managedConnect: managedConnect(),
-    onDone: (result) => {
-      // See above: the discard is deliberate, and `void` as a statement is what says so.
-      void finishCreated(result);
+    /* The wizard creates nothing on this path. `import_site` is `no-project` tiered and does the
+       creating — including the git init every create path owes (`specs/desktop.md` §4.5), which
+       moved into `adoptCreatedProject` with it. The modal resolves `null`, the same as a dismissal,
+       because nothing was created HERE. */
+    onHandoff: (brief) => {
+      finish(null);
+      void runImportHandoff(brief);
     },
     rerender,
     resolveDestination: () => validateParams(),
@@ -338,7 +340,7 @@ function renderModal() {
   };
 
   const onTabChange = (e: Event) => {
-    if (_creating || isImportRunning()) {
+    if (_creating) {
       return;
     }
     _tab = (e.target as HTMLElement & { selected: string }).selected as NewProjectTab;
@@ -363,7 +365,7 @@ function renderModal() {
   };
 
   const goBack = () => {
-    if (_creating || isImportRunning()) {
+    if (_creating) {
       return;
     }
     _step = "source";
@@ -524,7 +526,12 @@ function renderModal() {
     })}
     ${
       _tab === "import"
-        ? renderImportStatus()
+        ? html`
+            <div class="new-project-tab-intro">
+              The assistant runs the import and reports as it goes — this dialog closes as soon as
+              it starts.
+            </div>
+          `
         : html`
             <div class="new-project-tab-intro">
               The site's address, deployment target and design tokens are project settings — set
@@ -542,15 +549,6 @@ function renderModal() {
         Cancel
       </sp-button>
     `;
-    if (isImportRunning()) {
-      // One cancel, not two: the run's own Cancel is the step's Cancel, and dismissing the modal
-      // (Escape, the underlay, the header ✕) aborts the run on the way out.
-      return html`
-        <sp-button variant="secondary" @click=${() => cancelImport(importCtx)}>
-          Cancel Import
-        </sp-button>
-      `;
-    }
     if (_step === "source") {
       const gated = (_tab === "import" || _tab === "agent") && !aiGateOpen();
       return html`
@@ -561,7 +559,7 @@ function renderModal() {
     const primary =
       _tab === "import"
         ? html`
-            <sp-button variant="accent" @click=${() => startImport(importCtx)}>
+            <sp-button variant="accent" @click=${() => handoffImport(importCtx)}>
               ${importButtonLabel()}
             </sp-button>
           `
@@ -583,12 +581,7 @@ function renderModal() {
     `;
   };
 
-  const bodyTpl = () => {
-    if (isImportRunning()) {
-      return renderImportProgress();
-    }
-    return _step === "source" ? sourceBodyTpl() : paramsBodyTpl();
-  };
+  const bodyTpl = () => (_step === "source" ? sourceBodyTpl() : paramsBodyTpl());
 
   const tpl = html`
     <sp-underlay open @close=${closeNewProjectModal}></sp-underlay>
@@ -602,7 +595,7 @@ function renderModal() {
         </sp-action-button>
       </div>
       ${
-        _step === "source" && !isImportRunning()
+        _step === "source"
           ? html`
               <div class="new-project-tabs">
                 <sp-tabs selected=${_tab} quiet @change=${onTabChange}>

package/src/packages/ensure-deps.ts

@@ -3,30 +3,36 @@
  * Ensure the active project's dependencies are installed before the editor loads. When the backend
  * reports node_modules is missing, run `bun install` behind a blocking progress modal so component
  * and format resolution see the real dependency tree. No-op on platforms without package support.
+ *
+ * It REPORTS whether an install actually ran, because "format resolution sees the real dependency
+ * tree" was only half true: project activation fetches the format registry before calling this, and
+ * `loadFormats` memoises its answer — so on a fresh clone the empty registry it got survived the
+ * whole session, and the New File picker offered nothing but JSON in a project whose `project.json`
+ * enables the markdown extension. The caller re-fetches on a true.
  */
 
 import { getPlatform } from "../platform";
 import { showProgressModal } from "../ui/progress-modal";
 import { shouldInstallAutomation } from "../services/automation";
 
-export async function ensureDependenciesInstalled(): Promise<void> {
+export async function ensureDependenciesInstalled(): Promise<boolean> {
   // Automation/screenshot runs open projects read-only to drive the canvas — they must never mutate
   // The project on disk (a `bun install` would litter node_modules/bun.lock into starter templates).
   if (shouldInstallAutomation(location.search)) {
-    return;
+    return false;
   }
   const platform = getPlatform();
   if (!platform.dependenciesNeedInstall || !platform.installDependencies) {
-    return;
+    return false;
   }
   let needs = false;
   try {
     needs = await platform.dependenciesNeedInstall();
   } catch {
-    return;
+    return false;
   }
   if (!needs) {
-    return;
+    return false;
   }
   const progress = showProgressModal({
     status: "Running bun install…",
@@ -36,10 +42,11 @@ export async function ensureDependenciesInstalled(): Promise<void> {
     const result = await platform.installDependencies();
     if (result.ok) {
       progress.done();
-    } else {
-      progress.fail(result.log ?? "bun install failed");
+      return true;
     }
+    progress.fail(result.log ?? "bun install failed");
   } catch (error) {
     progress.fail(error instanceof Error ? error.message : String(error));
   }
+  return false;
 }

package/src/packages/jxsuite-update.ts

@@ -16,7 +16,7 @@
  * build` and the project's types — not the running app. There is no reason for them to match
  * Studio, and pinning them to it was the residue of an assumption that is no longer true.
  *
- * The registry lookup is `platform.outdatedPackages()`, the same seam the dependencies editor uses.
+ * The registry lookup is `platform.packageVersions()`, the same seam the dependencies editor uses.
  * A host that does not offer it (the cloud session, which manages dependencies server-side) simply
  * gets no prompt: without the registry there is no honest target, and guessing is what this
  * replaced.
@@ -50,21 +50,22 @@ export interface JxsuiteUpdate {
  */
 export async function checkJxsuiteUpdate(): Promise<JxsuiteUpdate[]> {
   const platform = getPlatform();
-  if (!platform.outdatedPackages) {
+  if (!platform.packageVersions) {
     return [];
   }
   let reported;
   try {
-    reported = await platform.outdatedPackages();
+    reported = await platform.packageVersions();
   } catch {
     return [];
   }
   const outdated: JxsuiteUpdate[] = [];
   for (const p of reported) {
     /*
-     * `isUpgrade`, not merely "differs from latest". `outdatedPackages` reports any difference, and
-     * a project deliberately pinned AHEAD of the registry — a prerelease, or a range bumped before
-     * the publish landed — would otherwise be offered a downgrade described as an update.
+     * `isUpgrade`, not merely "differs from latest". `packageVersions` reports the registry's answer
+     * for every dependency, current ones included, and a project deliberately pinned AHEAD of the
+     * registry — a prerelease, or a range bumped before the publish landed — would otherwise be
+     * offered a downgrade described as an update.
      */
     if (p.name.startsWith(JXSUITE_PREFIX) && isUpgrade(p.current, p.latest)) {
       outdated.push({ current: p.current, dev: Boolean(p.dev), latest: p.latest, name: p.name });
@@ -146,11 +147,10 @@ export async function maybePromptJxsuiteUpdate(projectRoot: string): Promise<voi
   // That is not hypothetical: it put this dialog into the middle of 33 committed screenshots,
   // Including docs/images/hero.png, which is the jxsuite.com marketing hero.
   //
-  // Correct pins are NOT sufficient on their own. `outdatedPackages` compares the range's base
-  // Version against the registry's `latest` (packages/server/src/packages.ts: `latest ===
-  // StripRange(p.version)`), not whether the range resolves it — so a project pinned `^1.4.1` is
-  // "outdated" the moment 1.4.2 publishes, and every starter shot would be scrimmed again by the
-  // Next patch release of any @jxsuite package.
+  // Correct pins are NOT sufficient on their own. This compares the range's BASE version against
+  // The registry's `latest`, not whether the range resolves it — so a project pinned `^1.4.1` is
+  // Behind the moment 1.4.2 publishes, and every starter shot would be scrimmed again by the next
+  // Patch release of any @jxsuite package.
   if (shouldInstallAutomation(location.search)) {
     return;
   }

package/src/page-params.ts

@@ -10,6 +10,7 @@
  * matching built page.
  */
 
+import { documentUrlPattern as routePattern } from "@jxsuite/site/routes";
 import { getPlatform } from "./platform";
 import { loadExtensions } from "./format/format-host";
 import type { JxMutableNode, JxPathsDef } from "@jxsuite/schema/types";
@@ -17,54 +18,17 @@ import type { JxMutableNode, JxPathsDef } from "@jxsuite/schema/types";
 /** Param name → candidate values, in `$paths` declaration order. */
 export type ParamValues = Record<string, string[]>;
 
-/** Bracket route segments: `[param]` (named) and `[...param]` (catch-all). */
-const PARAM_SEGMENT = /\[\.\.\.(\w+)\]|\[(\w+)\]/g;
-
 /**
- * Param names declared by a document path's bracket segments, e.g. `pages/products/[sku].json` →
- * `["sku"]`. Mirrors the compiler's `fileToRoute` parsing.
+ * Route derivation is `@jxsuite/site/routes`, re-exported so this module stays the studio's one
+ * import for everything `$params`.
  *
- * @param {string | null | undefined} documentPath
- * @returns {string[]}
+ * These two used to be written out here, under a docblock admitting they mirrored the compiler's
+ * `fileToRoute`. A mirror is a copy that nothing checks, and a route is the worst place to keep
+ * one: a disagreement is a page that renders on the canvas and 404s in a browser. The studio cannot
+ * import `@jxsuite/compiler` (its graph carries `sharp` and `esbuild`, and this bundles for a
+ * browser), so the rules moved down to the package both CAN import.
  */
-export function dynamicRouteParams(documentPath: string | null | undefined) {
-  if (!documentPath) {
-    return [];
-  }
-  const params: string[] = [];
-  for (const match of documentPath.matchAll(PARAM_SEGMENT)) {
-    params.push((match[1] ?? match[2])!);
-  }
-  return params;
-}
-
-/**
- * URL pattern for a page document path, mirroring the compiler's `fileToRoute`:
- * `pages/products/[sku].json` → `/products/:sku`, `pages/index.json` → `/`.
- *
- * @param {string | null | undefined} documentPath
- * @returns {string}
- */
-export function documentUrlPattern(documentPath: string | null | undefined) {
-  if (!documentPath) {
-    return "/";
-  }
-  let urlPath = documentPath
-    .replace(/^\.\//, "")
-    .replace(/^pages\//, "")
-    .replace(/\.[^/.]+$/, "");
-  if (urlPath.endsWith("/index")) {
-    urlPath = urlPath.slice(0, -6) || "/";
-  } else if (urlPath === "index") {
-    urlPath = "/";
-  }
-  if (!urlPath.startsWith("/")) {
-    urlPath = `/${urlPath}`;
-  }
-  return urlPath.replaceAll(PARAM_SEGMENT, (_match, spread: string, named: string) =>
-    spread ? "*" : `:${named}`,
-  );
-}
+export { documentUrlPattern, dynamicRouteParams } from "@jxsuite/site/routes";
 
 /**
  * The `$paths` declaration of an open document. JSON pages carry it on the document root;
@@ -289,7 +253,7 @@ export function substitutePreviewParams(
   doc.state.$page = {
     params: { ...params },
     title: typeof doc.title === "string" ? doc.title : "",
-    url: documentUrlPattern(documentPath),
+    url: routePattern(documentPath),
   };
   return doc;
 }

package/src/panels/activity-bar.ts

@@ -30,6 +30,12 @@ import type { PanelRecord } from "./panel-registry";
 import type { CommandContext } from "../commands/context";
 import type { EffectScope } from "@vue/reactivity";
 import { activeRegistry } from "../commands/active-registry";
+import {
+  dismissSettingsMenu,
+  isSettingsMenuOpen,
+  openSettingsMenu,
+  SETTINGS_MENU_PLACEMENT,
+} from "./settings-menu";
 import type { TemplateResult } from "lit-html";
 
 let _scope: EffectScope | null = null;
@@ -55,6 +61,9 @@ export function mount() {
 }
 
 export function unmount() {
+  // Before the scope stops: an unmounted rail must not leave the menu's document-level capture
+  // Keydown listener behind, answering for a gear that is no longer on screen.
+  dismissSettingsMenu();
   _scope?.stop();
   _scope = null;
 }
@@ -168,36 +177,56 @@ function railButton(panel: PanelRecord, ctx: CommandContext): TemplateResult {
 }
 
 /**
- * The rail foot: **Preferences**, and only Preferences (plan §3.2 ②).
+ * The rail foot: the ⚙ **Settings** menu.
  *
  * It was two hand-authored buttons calling two module functions directly — the exact shape §2
- * principle 1 bans, and the reason the gear opened PROJECT configuration from an application-level
- * slot. Preferences is the application's own settings and follows the author between projects, so
- * it is the one that earns the pinned position; project configuration is `settings.open`, which
- * lives in the ⬢ menu and the palette because it is scoped to a project; and About is `help.about`,
- * reachable by name.
+ * principle 1 bans — and then, for a release, one button that ran `app.preferences` and nothing
+ * else. That was the right shape for a pinned SLOT: a slot holds one thing, so it held the
+ * application's settings, and project configuration went to the ⬢ menu and the palette because a
+ * slot at application level could not honestly offer it.
  *
- * Rendered FROM the record, so the label and the chord in its tooltip cannot drift from ⌘,.
+ * **This reverses that, and the reason it is not a regression is that the gear is no longer a
+ * slot.** A menu may host two levels — `commandbar/overflow` has admitted application, project and
+ * document since the matrix was written — because a menu prints each row's own name, chord and gate
+ * beside it, so nothing about a row's level has to be inferred from where the control sits. The
+ * levels are still separated: `settings/menu` is a matrix row admitting exactly application and
+ * project, and the menu draws a divider where the level changes. Its one-click meaning is gone
+ * deliberately: ⌘, still opens Preferences from anywhere, and the menu's first row prints that
+ * chord.
+ *
+ * Rendered FROM the placement, so a record joins the gear by declaring `settings/menu` and there is
+ * nothing here to update in step. With no project open the two project rows hide themselves and the
+ * menu is Preferences alone — which is the correct answer on the welcome screen, and the reason the
+ * button's own visibility asks the placement rather than one id.
  */
 function railFooterTpl(): TemplateResult {
   const registry = activeRegistry();
-  const command = registry?.get("app.preferences");
-  if (!registry || !command || !registry.isVisible("app.preferences")) {
+  if (!registry || registry.forPlacement(SETTINGS_MENU_PLACEMENT).length === 0) {
     return html`${nothing}`;
   }
-  const chord = registry.keymap.formatBinding("app.preferences");
+  const open = isSettingsMenuOpen();
   return html`
     <button
       type="button"
-      class="rail-item"
-      data-command="app.preferences"
-      title=${chord ? `${command.title} (${chord})` : command.title}
-      @click=${() => {
-        void registry.run("app.preferences");
+      class="rail-item${open ? " rail-item--menu-open" : ""}"
+      data-rail-menu="settings"
+      aria-haspopup="menu"
+      aria-expanded=${open ? "true" : "false"}
+      title="Settings"
+      @click=${(event: MouseEvent) => {
+        openSettingsMenu(event.currentTarget as HTMLElement, { rerender: renderActivityBar });
+      }}
+      @keydown=${(event: KeyboardEvent) => {
+        // The menu-button convention: either arrow opens, and the menu takes the keyboard from
+        // There. Enter and Space are the button's own activation and already reach `@click`.
+        if (event.key === "ArrowUp" || event.key === "ArrowDown") {
+          event.preventDefault();
+          openSettingsMenu(event.currentTarget as HTMLElement, { rerender: renderActivityBar });
+        }
       }}
     >
       <span class="rail-icon"><sp-icon-settings size="m"></sp-icon-settings></span>
-      <span class="rail-label">Preferences</span>
+      <span class="rail-label">Settings</span>
     </button>
   `;
 }

package/src/panels/ai-chat/attached-context.ts

@@ -15,7 +15,12 @@
 export const ATTACHED_CONTEXT_DELIMITER = "---- attached context ----";
 
 export interface ContextChip {
-  kind: "page" | "selection";
+  /**
+   * `"import"` is not attachable from the composer's menu — it is stamped by the New Project Import
+   * hand-off, which needs the same channel for a different reason: the run's parameters must reach
+   * the model, and message content is the only thing the streaming payload carries.
+   */
+  kind: "page" | "selection" | "import";
   /** Short chip label, e.g. the page path or `<h1>`. */
   label: string;
   /** The context line embedded into the message content. */