@jxsuite/studio 10.0.0 → 10.2.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jxsuite/studio",
-  "version": "10.0.0",
+  "version": "10.2.0",
   "description": "Jx Studio — visual builder for Jx documents",
   "license": "MIT",
   "repository": {
@@ -60,12 +60,12 @@
   "dependencies": {
     "@atlaskit/pragmatic-drag-and-drop": "^4.0.0",
     "@atlaskit/pragmatic-drag-and-drop-hitbox": "^3.0.0",
-    "@jxsuite/ai": "^0.41.1",
+    "@jxsuite/ai": "^0.42.0",
     "@jxsuite/collab": "^0.11.4",
-    "@jxsuite/create": "^1.5.0",
+    "@jxsuite/create": "^1.5.2",
     "@jxsuite/formulas": "^0.0.26",
     "@jxsuite/markup": "^1.0.2",
-    "@jxsuite/protocol": "^6.0.0",
+    "@jxsuite/protocol": "^6.2.0",
     "@jxsuite/runtime": "^6.0.1",
     "@jxsuite/schema": "^5.0.0",
     "@jxsuite/site": "^2.2.2",

package/src/browse/library-model.ts

@@ -200,44 +200,64 @@ export function entryCollectionOf(path: string, pageExtensions?: readonly string
  */
 const SKIP_DIRS = new Set(["node_modules", ".git", ".jx", ".cache"]);
 
+/** What every branch of one scan shares. */
+interface ScanRun {
+  platform: Pick<StudioPlatform, "listDirectory">;
+  out: LibraryFile[];
+  failures: ScanFailure[];
+  i18n: ResolvedI18n | null;
+  pageExtensions: readonly string[] | undefined;
+  /**
+   * Every directory some branch has claimed, the roots included. A collection may live in an
+   * ANCESTOR of the project (a site inside the vault it publishes declares `source: "../.."`), and
+   * that walk reaches the project's own directories under the same project-relative paths the roots
+   * walk: every page was listed twice. A directory is walked by whichever branch claims it first.
+   */
+  claimed: Set<string>;
+}
+
+/**
+ * The project root as a listing names it from outside: `""` (relative to itself) or `"."`. A walk
+ * from an ancestor stops there; the project's own directories are roots of the scan already, and
+ * the rest of the root (`dist/`, `scripts/`) holds no collection's entries.
+ */
+function isProjectRoot(path: string): boolean {
+  const normalized = normalizeDir(path);
+  return normalized === "" || normalized === ".";
+}
+
 /**
  * Walk one directory tree, collecting files and recording — never swallowing — what it could not
  * read. A failure at depth is reported against the directory that failed, not the root, so the
  * Problem names the path the author can act on.
  */
-async function walk(
-  dir: string,
-  platform: Pick<StudioPlatform, "listDirectory">,
-  out: LibraryFile[],
-  failures: ScanFailure[],
-  i18n: ResolvedI18n | null,
-  optional = false,
-  pageExtensions?: readonly string[],
-): Promise<void> {
+async function walk(dir: string, run: ScanRun, optional = false): Promise<void> {
   let entries: DirEntry[];
   try {
     // Noted: the Library walks every media directory, so it is where most versions are learned.
-    entries = await notedListing(() => platform.listDirectory(dir));
+    entries = await notedListing(() => run.platform.listDirectory(dir));
   } catch (error) {
     // A declared collection's folder that does not exist yet is an empty collection, not a fault.
     if (!optional) {
-      failures.push({ dir, error: errorMessage(error) });
+      run.failures.push({ dir, error: errorMessage(error) });
     }
     return;
   }
   const subdirectories: string[] = [];
   for (const entry of entries) {
     if (entry.type === "directory") {
-      if (!SKIP_DIRS.has(entry.name)) {
+      const key = normalizeDir(entry.path);
+      if (!SKIP_DIRS.has(entry.name) && !isProjectRoot(key) && !run.claimed.has(key)) {
+        run.claimed.add(key);
         subdirectories.push(entry.path);
       }
       continue;
     }
     const ext = extensionOf(entry.name);
-    out.push({
-      collection: entryCollectionOf(entry.path, pageExtensions),
+    run.out.push({
+      collection: entryCollectionOf(entry.path, run.pageExtensions),
       ext,
-      locale: servedLocaleOfPath(entry.path, i18n) ?? undefined,
+      locale: servedLocaleOfPath(entry.path, run.i18n) ?? undefined,
       media: MEDIA_EXTENSIONS.has(ext),
       modified: entry.modified,
       name: entry.name,
@@ -248,9 +268,7 @@ async function walk(
   }
   // Siblings in parallel, depth serialized per branch: the platform counts every call as in-flight,
   // So `probe.idle()` already knows the scan is running without the Library declaring a source.
-  await Promise.all(
-    subdirectories.map((sub) => walk(sub, platform, out, failures, i18n, false, pageExtensions)),
-  );
+  await Promise.all(subdirectories.map((sub) => walk(sub, run)));
 }
 
 /**
@@ -265,16 +283,31 @@ export async function scanLibrary(
   optional: ReadonlySet<string> = new Set(),
   pageExtensions?: readonly string[],
 ): Promise<LibraryScan> {
-  const files: LibraryFile[] = [];
-  const failures: ScanFailure[] = [];
   // Resolved ONCE for the whole walk. `resolveI18n` canonicalizes every declared tag through
   // `Intl.Locale`, and a project with 300 pages would otherwise pay for that per file.
   const { i18n } = resolveI18n(projectState?.projectConfig ?? {});
+  const run: ScanRun = {
+    claimed: new Set(),
+    failures: [],
+    i18n,
+    out: [],
+    pageExtensions,
+    platform,
+  };
+  /* Every root is claimed before any walk descends: `map` runs to the end synchronously, and a walk
+     claims its subdirectories only after its own listing has been awaited. A root named twice is
+     walked once. */
   await Promise.all(
-    dirs.map((dir) =>
-      walk(dir, platform, files, failures, i18n, optional.has(dir), pageExtensions),
-    ),
+    dirs.map((dir) => {
+      const key = normalizeDir(dir);
+      if (run.claimed.has(key)) {
+        return Promise.resolve();
+      }
+      run.claimed.add(key);
+      return walk(dir, run, optional.has(dir));
+    }),
   );
+  const { failures, out: files } = run;
   files.sort((a, b) => a.path.localeCompare(b.path));
   return { failures, files };
 }

package/src/commands/context.ts

@@ -107,6 +107,7 @@ const EDITOR_KIND_BY_MODE = new Map<string, EditorKind>([
   ["content-home", "home"],
   ["media-home", "home"],
   ["publish-home", "home"],
+  ["settings-home", "home"],
   /* The Media viewer — `media/media-pane.ts`. An image, a video, a font specimen: files the studio
      can SHOW but has no document model for, which is why clicking one used to end in "No format
      class imported for …", advice that means nothing about a PNG. */

package/src/editor/shortcuts.ts

@@ -1010,6 +1010,9 @@ const SELF_SCROLLING_MODES: ReadonlySet<string> = new Set([
   "media-home",
   "preview",
   "publish-home",
+  /* Project Settings' home — `settings/settings-workspace.ts`. Two columns, each scrolling its own
+     list, with nothing to zoom. */
+  "settings-home",
   /* The Styles workspace's Variables view — `style/variables-view.ts`. An `overflow-y: auto`
      column over the stage; without it here the wheel panned an artboard that does not exist. */
   "tokens",

package/src/panels/data-grid.ts

@@ -23,7 +23,6 @@ import { mountDataActionsSurface } from "../surfaces/data-actions";
 import { mountPushPlanSurface } from "../surfaces/push-plan";
 import { dataSurfaceAvailable, pushSchema, testConnection } from "../services/data-service";
 import { openGridSourcePicker } from "../grid/grid-open";
-import { closeSettingsDialog } from "../settings/settings-dialog";
 import type { DataActionsSurfaceHandle, DataActionsView } from "../surfaces/data-actions";
 import type { DialogSurfaceHandle } from "../surfaces/dialog";
 import type { PushPlanSurfaceHandle, PushPlanView } from "../surfaces/push-plan";
@@ -278,9 +277,6 @@ function paintSectionActions(
     host,
     mountDataActionsSurface(host, projectActions(sectionKey, selected), {
       openGrid: () => {
-        /* The actions row is drawn in the settings dialog, and a grid opens as a TAB: left up, the
-           dialog would cover the very tab the reader asked for (§17.1). */
-        closeSettingsDialog();
         void openGridSourcePicker();
       },
       push: () => {

package/src/panels/settings-menu.ts

@@ -15,15 +15,15 @@
  * a record joins the menu by declaring the placement and leaves by not declaring it. The submenus
  * are the enumeration of each parent command's own `section` ARGUMENT, read from that argument's
  * own definition site — which is state the command already validates, not a second vocabulary
- * (`studio-ui-guidelines.md` §12.5). Project Settings' submenu is GROUPED as its dialog's nav is
+ * (`studio-ui-guidelines.md` §12.5). Project Settings' submenu is GROUPED as its own nav is
  * (General, Integrations, Advanced), with a divider where the group changes.
  *
  * **A parent row runs its own command AND owns a submenu.** The APG menu pattern does not describe
  * that and Spectrum's stock submenu forbade it outright; the kit's `jx-menu-item` makes it the rule
  * (`ui.md` §5.1), so the deviation `specs/studio-ui-guidelines.md` §8.4 records is now what the
  * element does rather than what this file hand-rolls around it. Nothing is unreachable by keyboard:
- * Enter runs the row, ArrowRight reaches every child, and every child is also in the settings
- * dialog's own nav.
+ * Enter runs the row, ArrowRight reaches every child, and every child is also in Project Settings'
+ * own nav.
  *
  * The menu is the `menu` surface (`surfaces/menu.json`, through `surfaces/menu.ts`). What is left
  * here is the projection — which records, which sections, what each row runs — and where the panel

package/src/panels/settings-pane.ts

@@ -1,26 +1,25 @@
 /// <reference lib="dom" />
 /**
  * The Project Settings editor's flow: the grouped section list, the section body, and the Moved
- * footnote, drawn inside the settings dialog (§17.1).
+ * footnote, drawn as the Settings workspace's home (§17.1, §22.9).
  *
  * Two columns. The list is the section registry in its three groups (General, Integrations,
- * Advanced), so an extension's section joins the dialog by registering and leaves by going away;
- * the body is whichever section is current, drawn by that section's own renderer.
+ * Advanced), so an extension's section joins Settings by registering and leaves by going away; the
+ * body is whichever section is current, drawn by that section's own renderer.
  *
  * **This file is the FLOW; the markup is a document.** `surfaces/settings-pane.json` owns the two
  * columns, the lists' ARIA and keyboard, and every value in their style;
  * `surfaces/settings-pane.ts` mounts it (studio-ui-guidelines.md §6, §9.3), and
- * `settings/settings-dialog.ts` owns the dialog it is mounted into. What stays here is the part
+ * `settings/settings-workspace.ts` owns the pane it is mounted into. What stays here is the part
  * that is a decision: which sections there are, which one is current, which renderer gets the body,
  * and what a renderer's failure says.
  *
  * **It imports the registry, never the sections.** The section RENDERERS are registered by
  * `settings/settings-document.ts`, which the app loads when it registers its commands.
  *
- * Nothing here is stamped with a region of its own. The dialog carries `overlay.dialog:settings`,
- * and the entry rows and entry editor of a map-layout section are stamped by
- * `settings/contributed-section.ts` under it, as `overlay.dialog:settings/entry:<key>` and
- * `overlay.dialog:settings/editor`.
+ * The home carries the region its host hands in, `pane.<id>/settings`, and the entry rows and entry
+ * editor of a map-layout section are stamped by `settings/contributed-section.ts` under it, as
+ * `pane.<id>/settings/entry:<key>` and `pane.<id>/settings/editor`.
  *
  * @docs studio/projects/settings
  */
@@ -41,6 +40,9 @@ import type { WorkspaceId } from "../workspace/workspace-ids";
 import type { StylesView } from "../style/project-styles";
 import type { PublishTab } from "../publish/publish-ids";
 
+/** The home's heading: the workspace's own title, so the two cannot drift apart. */
+const HEADING = workspaceInfo("settings").title;
+
 /** What the body says when the section that is current is registered by nobody. */
 const NO_SECTIONS = "No settings sections.";
 
@@ -80,9 +82,15 @@ const MOVED: readonly {
 
 /** What the mounted editor is told to do by things only its host can do. */
 export interface SettingsPaneOptions {
+  /** The region the home is stamped with: `pane.<id>/settings`. */
+  region: string;
+  /** Where the Back control goes, as its text says it ("Back to Design"). Read on every draw. */
+  backLabel: () => string;
+  /** The Back control: leave Settings for the workspace it was opened from. */
+  back: () => void;
   /**
-   * A Moved footnote's button: close the dialog and go to the named workspace, and to the named
-   * Inspector tab or Styles view there when the row names one.
+   * A Moved footnote's button: go to the named workspace, and to the named Inspector tab or Styles
+   * view there when the row names one.
    */
   openMoved: (
     workspace: WorkspaceId,
@@ -96,15 +104,10 @@ export interface SettingsPaneOptions {
 export interface SettingsPaneMount {
   /** Settles once the columns are mounted and the current section has been drawn once. */
   ready: Promise<void>;
-  /** Put the keyboard on the current section's row. */
-  focusActive: () => void;
-  /**
-   * Stop following the section registry while the dialog is closed. The editor stays built; a
-   * section registering or a project closing in the meantime is caught up on by {@link resume}.
-   */
-  suspend: () => void;
-  /** Follow the registry again and redraw the current section: the dialog is being shown again. */
-  resume: () => void;
+  /** Put the keyboard on the current section's row. Settles once it has moved. */
+  focusActive: () => Promise<void>;
+  /** Whether the home still stands in the stage it was mounted into. */
+  attached: () => boolean;
   /** Take the editor down and unsubscribe. Idempotent. */
   dispose: () => void;
 }
@@ -122,14 +125,16 @@ function movedRow(value: string): (typeof MOVED)[number] | null {
 /**
  * Everything the document draws, decided here so the document decides nothing.
  *
+ * @param {SettingsPaneOptions} options The host's region and Back control
  * @param {string} failure The current section's failure sentence, or the empty string
  * @returns {SettingsPaneValues}
  */
-function values(failure: string): SettingsPaneValues {
+function values(options: SettingsPaneOptions, failure: string): SettingsPaneValues {
   const active = settingsDocumentSection();
   const grouped = groupedSettingsSections();
   return {
     active,
+    backLabel: options.backLabel(),
     activeTabId: tabIdFor(active),
     empty: NO_SECTIONS,
     failure,
@@ -146,6 +151,7 @@ function values(failure: string): SettingsPaneValues {
       titleId: `settings-group-${group.id}`,
     })),
     hasSection: settingsSection(active) !== undefined,
+    heading: HEADING,
     // The section's own sentence when it has one, its group's otherwise.
     intro:
       settingsSection(active)?.intro ||
@@ -161,11 +167,12 @@ function values(failure: string): SettingsPaneValues {
         workspace: row.workspace,
       };
     }),
+    region: options.region,
   };
 }
 
 /**
- * Mount the editor into `host`, the settings dialog's pane slot, and keep it current.
+ * Mount the editor into `host`, a pane's stage, and keep it current until it is disposed.
  *
  * It subscribes to the section registry and to the chosen section, so an extension's section
  * appearing a tick later redraws the nav, and a deep link to an entry inside the section already on
@@ -198,7 +205,10 @@ export function mountSettingsPane(
   /** Counts renders, so a late rejection from a superseded one cannot overwrite a newer answer. */
   let generation = 0;
 
-  const surface: SettingsPaneHandle = mountSettingsPaneSurface(host, values(failure), {
+  const surface: SettingsPaneHandle = mountSettingsPaneSurface(host, values(options, failure), {
+    back: () => {
+      options.back();
+    },
     openMoved: (workspace: string) => {
       const target = movedRow(workspace);
       if (target !== null) {
@@ -217,7 +227,7 @@ export function mountSettingsPane(
     }
     const label = settingsSection(key)?.label ?? key;
     failure = `Could not show ${label}: ${reason}`;
-    surface.update(values(failure));
+    surface.update(values(options, failure));
   }
 
   /**
@@ -237,7 +247,7 @@ export function mountSettingsPane(
       rendered = null;
     }
     if (!island || (!force && rendered === active)) {
-      surface.update(values(failure));
+      surface.update(values(options, failure));
       return;
     }
     /* Read BEFORE the write: whether the section is changing is what decides the host, and
@@ -245,10 +255,10 @@ export function mountSettingsPane(
     const changed = rendered !== active;
     rendered = active;
     failure = "";
-    surface.update(values(failure));
+    surface.update(values(options, failure));
     const section = settingsSection(active);
     if (!section) {
-      /* Every section unregistered at once: a project closing while the dialog is open. The
+      /* Every section unregistered at once: a project closing while Settings is on screen. The
          document says so itself (`hasSection`), and the island is emptied so a renderer's leftovers
          do not sit under the sentence explaining that there is nothing to draw. */
       sectionHost = null;
@@ -276,12 +286,9 @@ export function mountSettingsPane(
     }
   }
 
-  const follow = (): (() => void) =>
-    onSettingsDocumentChanged(() => {
-      draw(true);
-    });
-  /** The registry subscription, or null while the dialog is closed. */
-  let off: (() => void) | null = follow();
+  const off = onSettingsDocumentChanged(() => {
+    draw(true);
+  });
   /* The island does not exist until the mount lands, so the first pass that reaches a section
      renderer is this one. */
   const ready = surface.ready.then(() => {
@@ -289,37 +296,16 @@ export function mountSettingsPane(
   });
 
   return {
+    attached: () => surface.attached(),
     dispose() {
       if (disposed) {
         return;
       }
       disposed = true;
-      off?.();
-      off = null;
+      off();
       surface.dispose();
     },
-    focusActive: () => {
-      surface.focusActive();
-    },
+    focusActive: () => surface.focusActive(),
     ready,
-    resume() {
-      if (disposed || off !== null) {
-        return;
-      }
-      off = follow();
-      /* Redrawn rather than trusted: anything may have moved while it was closed (a section
-         registered, the project closed or changed, the configuration edited in Styles). Into a
-         FRESH host, as every open drew into when each one built its own frame: several sections
-         keep their form state (a half-typed entry, a failed save's error) in a WeakMap keyed on
-         the host they were given, and an open is a new visit, so none of that may come back from
-         the last one, or from another project's. Only a redraw WHILE open keeps the host, which is
-         what keeps the caret in the field being typed in. */
-      sectionHost = null;
-      draw(true);
-    },
-    suspend() {
-      off?.();
-      off = null;
-    },
   };
 }

package/src/platform-errors.ts

@@ -26,6 +26,8 @@ export interface PlatformErrorInfo {
   heading?: string;
   /** What to do once one of its actions is done. */
   retry?: RetryHint;
+  /** The paths a `conflict` names: the files the remote changed that this side changed too. */
+  conflicts?: string[];
 }
 
 const RETRY_HINTS = new Set<string>(["reload", "repeat", "none"]);
@@ -90,7 +92,7 @@ export function platformErrorInfo(cause: unknown): PlatformErrorInfo {
   if (!isJsonObject(cause)) {
     return {};
   }
-  const { actions, code, heading, installUrl, retry, type } = cause;
+  const { actions, code, conflicts, heading, installUrl, retry, type } = cause;
   const info: PlatformErrorInfo = {};
   // A problem type wins over a legacy code: it is the shape the backend is migrating toward.
   const derived = problemSlug(type) ?? (isString(code) ? normalizeCode(code) : null);
@@ -109,9 +111,23 @@ export function platformErrorInfo(cause: unknown): PlatformErrorInfo {
   if (isRetryHint(retry)) {
     info.retry = retry;
   }
+  if (Array.isArray(conflicts)) {
+    info.conflicts = conflicts.filter((path) => isString(path));
+  }
   return info;
 }
 
+/**
+ * The files a refused publish overlaps on the remote, when the error is that refusal: a pull or a
+ * commit the remote has moved under, whose changes touch the same paths (`pull_conflict`, or the
+ * `conflict` problem type carrying `conflicts`). Null for every other failure.
+ */
+export function remoteConflictsOf(cause: unknown): string[] | null {
+  const info = platformErrorInfo(cause);
+  const conflicting = info.code === "pull-conflict" || info.code === "conflict";
+  return conflicting && info.conflicts ? info.conflicts : null;
+}
+
 /** The GitHub-App install link when the error is the structured needs-installation 403. */
 export function installUrlOf(cause: unknown): string | null {
   const info = platformErrorInfo(cause);

package/src/platforms/cloud.ts

@@ -37,6 +37,7 @@ import type {
   FsEvent,
   FsResyncReason,
   GitBranchesResult,
+  GitCommitBranchResult,
   GitLogEntry,
   GitStatusResult,
   ImportProgressEvent,
@@ -220,6 +221,7 @@ interface StructuredBody extends ErrorBody {
   actions?: JsonValue;
   heading?: JsonValue;
   retry?: JsonValue;
+  conflicts?: JsonValue;
 }
 
 /** What {@link platformError} carries on the Error it returns: the HTTP status, plus what it found. */
@@ -271,6 +273,10 @@ async function platformError(res: Response, fallback: string): Promise<Error> {
   if (retry !== undefined) {
     details.retry = retry;
   }
+  const conflicts = body?.conflicts;
+  if (Array.isArray(conflicts)) {
+    details.conflicts = conflicts.filter((path) => isString(path));
+  }
   return Object.assign(new Error(problemDetail(body) ?? fallback), details);
 }
 
@@ -1590,6 +1596,14 @@ export function createCloudPlatform(project: CloudProject | null): StudioPlatfor
       await okJson(await postJson("/git/create-branch", { name }), "Failed to create branch");
     },
 
+    /** One commit, parented on the session's base, onto a branch the backend creates for it. */
+    async gitCommitBranch(opts: { branch: string; message: string }) {
+      return okJson<GitCommitBranchResult>(
+        await postJson("/git/commit-branch", { branch: opts.branch, message: opts.message }),
+        `Could not publish to ${opts.branch}`,
+      );
+    },
+
     async gitDiff(path?: string) {
       const data = await okJson<{ diff: string }>(
         await api(`/git/diff?path=${encodeURIComponent(path ?? "")}`),