@jxsuite/studio 4.1.0 → 5.1.0

package/src/surfaces/welcome.ts

@@ -0,0 +1,338 @@
+/// <reference lib="dom" />
+/**
+ * Start pane — the pane-grid surface shown when no project is loaded and no document tabs are open.
+ *
+ * Three regions, in the order a first run needs them: **Start** (the ways to get a project in front
+ * of you), **Recent** (projects you have opened, identified by name + the folder that tells two
+ * same-named projects apart + when you last opened them), and **Projects** (the catalogue a cloud
+ * platform enumerates). A repository-access prompt sits above them when the account has no GitHub
+ * App installation yet, because nothing else on the pane can succeed until it does.
+ *
+ * Recents never render a raw absolute path: `recentLocations()` gives every row the shortest
+ * trailing path that distinguishes it from the other rows sharing its name.
+ *
+ * The pane is the `welcome` surface (`surfaces/welcome.json`): this module is the projection —
+ * which start actions the platform offers, the recents with their labels, the catalogue minus the
+ * recents — and the four things a click can do. The scope is reactive, so a removed recent
+ * reconciles in place.
+ *
+ * @docs studio/interface/welcome-screen
+ */
+
+import { getAccountStatus, needsAppInstall } from "../account-status";
+import { platformSupportsAddRepo } from "../new-project/add-repo-modal";
+import { getProjectList } from "../project-list";
+import { reactive } from "../reactivity";
+import { now } from "../services/clock";
+import { clearRecentProjects, getRecentProjects, removeRecentProject } from "../recent-projects";
+import { platformSupportsClone } from "../panels/git-panel";
+import { mountSurface, registerSurface } from "../ui/surface";
+import welcomeDoc from "./welcome.json";
+import type { JxDocument } from "@jxsuite/schema/types";
+import type { SurfaceHandle } from "../ui/surface";
+
+registerSurface("welcome", welcomeDoc as unknown as JxDocument);
+
+interface WelcomeCtx {
+  openProject: () => void;
+  openRecentProject: (root: string) => void;
+  openNewProject: (options?: { tab?: "starter" }) => void;
+  cloneRepository: () => void;
+  addExistingRepo: () => void;
+}
+
+let _ctx: WelcomeCtx | null = null;
+
+/** @param {WelcomeCtx} ctx */
+export function initWelcome(ctx: WelcomeCtx) {
+  _ctx = ctx;
+}
+
+// ─── Location labels ──────────────────────────────────────────────────────────
+
+/** Home-relative form of an absolute path (`/home/you/x` → `~/x`); other paths are unchanged. */
+export function shortenPath(path: string): string {
+  const match = /^\/(?:home|Users)\/[^/]+(?=\/|$)/.exec(path);
+  return match ? `~${path.slice(match[0].length)}` : path;
+}
+
+/** The ancestor segments of a root, home-shortened — everything above the project folder itself. */
+function ancestorSegments(root: string): string[] {
+  const segments = shortenPath(root).split("/").filter(Boolean);
+  return segments.slice(0, -1);
+}
+
+/**
+ * The last `depth` ancestor folders of a root, as a path. Truncated labels lead with `…/`; a
+ * complete absolute one keeps its leading `/`, so the string always says how much it is showing.
+ */
+function ancestorLabel(root: string, depth: number): string {
+  const segments = ancestorSegments(root);
+  if (segments.length === 0) {
+    return shortenPath(root);
+  }
+  const tail = segments.slice(Math.max(0, segments.length - depth));
+  if (tail.length < segments.length) {
+    return `…/${tail.join("/")}`;
+  }
+  return tail[0] === "~" || !root.startsWith("/") ? tail.join("/") : `/${tail.join("/")}`;
+}
+
+/**
+ * The location line for each entry: the shortest trailing path that tells apart the entries sharing
+ * a display name. One folder deep is enough for almost every list; same-named projects under the
+ * same parent fall back to their whole home-shortened root, which is unique because roots are.
+ *
+ * @param entries Projects to label, in any order.
+ * @returns Root → location label, one entry per distinct root.
+ */
+export function recentLocations(
+  entries: readonly { name: string; root: string }[],
+): Map<string, string> {
+  const groups = new Map<string, { name: string; root: string }[]>();
+  for (const entry of entries) {
+    const group = groups.get(entry.name);
+    if (group) {
+      group.push(entry);
+    } else {
+      groups.set(entry.name, [entry]);
+    }
+  }
+
+  const labels = new Map<string, string>();
+  for (const group of groups.values()) {
+    const maxDepth = Math.max(...group.map((e) => ancestorSegments(e.root).length), 1);
+    let chosen = group.map((e) => ancestorLabel(e.root, maxDepth));
+    for (let depth = 1; depth <= maxDepth; depth++) {
+      const candidate = group.map((e) => ancestorLabel(e.root, depth));
+      if (new Set(candidate).size === group.length) {
+        chosen = candidate;
+        break;
+      }
+    }
+    if (new Set(chosen).size !== group.length) {
+      chosen = group.map((e) => shortenPath(e.root));
+    }
+    for (const [index, entry] of group.entries()) {
+      labels.set(entry.root, chosen[index]!);
+    }
+  }
+  return labels;
+}
+
+const MINUTE = 60_000;
+const HOUR = 60 * MINUTE;
+const DAY = 24 * HOUR;
+
+/**
+ * "When you last opened it", in the coarse units a project list is read in. Deliberately vague past
+ * a week — the exact timestamp is in the row's tooltip.
+ *
+ * @param timestamp Epoch milliseconds.
+ * @param at Epoch milliseconds to measure against. Defaults to the {@link now} seam, so a pinned
+ *   clock makes "last opened" answer the same on every read.
+ */
+export function lastOpenedLabel(timestamp: number, at: number = now()): string {
+  const elapsed = Math.max(0, at - timestamp);
+  if (elapsed < MINUTE) {
+    return "just now";
+  }
+  if (elapsed < HOUR) {
+    const minutes = Math.floor(elapsed / MINUTE);
+    return `${minutes} minute${minutes === 1 ? "" : "s"} ago`;
+  }
+  if (elapsed < DAY) {
+    const hours = Math.floor(elapsed / HOUR);
+    return `${hours} hour${hours === 1 ? "" : "s"} ago`;
+  }
+  const days = Math.floor(elapsed / DAY);
+  if (days === 1) {
+    return "yesterday";
+  }
+  if (days < 30) {
+    return `${days} days ago`;
+  }
+  const months = Math.floor(days / 30);
+  return months < 12 ? `${months} month${months === 1 ? "" : "s"} ago` : "over a year ago";
+}
+
+// ─── The surface ──────────────────────────────────────────────────────────────
+
+/** One Start-list action: a labelled, icon-led button, run through `run`. */
+interface StartAction {
+  id: "new" | "open" | "clone" | "add";
+  title: string;
+  icon: string;
+}
+
+interface RecentRow {
+  root: string;
+  name: string;
+  location: string;
+  when: string;
+}
+
+interface CatalogueRow {
+  root: string;
+  name: string;
+  detail: string;
+}
+
+interface WelcomeScope extends Record<string, unknown> {
+  actions: StartAction[];
+  installNeeded: boolean;
+  installUrl: string;
+  hasRecent: boolean;
+  recent: RecentRow[];
+  hasCatalogue: boolean;
+  catalogue: CatalogueRow[];
+  run: (id: string) => void;
+  open: (root: string) => void;
+  remove: (root: string) => void;
+  clear: () => void;
+}
+
+let _state: WelcomeScope | null = null;
+let _host: HTMLElement | null = null;
+let _mount: Promise<SurfaceHandle> | null = null;
+let _handle: SurfaceHandle | null = null;
+
+/** The pane, as the surface reads it, from the platform and the stores as they stand now. */
+function project(): Omit<WelcomeScope, "run" | "open" | "remove" | "clear"> {
+  const recent = getRecentProjects();
+  // Catalogue entries already in Recent stay in that section only.
+  const catalogue = getProjectList().filter((p) => !recent.some((r) => r.root === p.root));
+  const recentLabels = recentLocations(recent);
+  const catalogueLabels = recentLocations(catalogue);
+  const actions: StartAction[] = [
+    // One entry, not two: the starter gallery IS the first step of New Project now, so the
+    // Separate "Start from an Example…" button it used to hide behind is gone.
+    { icon: "plus", id: "new", title: "New Project…" },
+    { icon: "folder-open", id: "open", title: "Open Project…" },
+    ...(platformSupportsClone()
+      ? [{ icon: "download-simple", id: "clone", title: "Clone Git Repository…" } as const]
+      : []),
+    ...(platformSupportsAddRepo()
+      ? [{ icon: "cube", id: "add", title: "Add Existing Repository…" } as const]
+      : []),
+  ];
+  return {
+    actions,
+    catalogue: catalogue.map((entry) => ({
+      detail: entry.description ?? catalogueLabels.get(entry.root) ?? entry.root,
+      name: entry.name,
+      root: entry.root,
+    })),
+    hasCatalogue: catalogue.length > 0,
+    hasRecent: recent.length > 0,
+    /* The GitHub-App install prompt, gated on `needsAppInstall()`: the account is connected,
+       reports zero installations, and told us where to fix that — the recovery path for the
+       structured needs-installation 403 that `platform-errors.ts` decodes. */
+    installNeeded: needsAppInstall(),
+    installUrl: getAccountStatus()?.appInstallUrl ?? "#",
+    recent: recent.map((entry) => ({
+      location: recentLabels.get(entry.root) ?? entry.root,
+      name: entry.name,
+      root: entry.root,
+      when: lastOpenedLabel(entry.timestamp),
+    })),
+  };
+}
+
+/** The reactive scope the surface reads, made once. */
+function state(): WelcomeScope {
+  _state ??= reactive({
+    actions: [],
+    catalogue: [],
+    clear: () => {
+      clearRecentProjects();
+      refresh();
+    },
+    hasCatalogue: false,
+    hasRecent: false,
+    installNeeded: false,
+    installUrl: "#",
+    open: (root: string) => {
+      _ctx?.openRecentProject(root);
+    },
+    recent: [],
+    remove: (root: string) => {
+      removeRecentProject(root);
+      refresh();
+    },
+    run: (id: string) => {
+      switch (id) {
+        case "new": {
+          _ctx?.openNewProject();
+          break;
+        }
+        case "open": {
+          _ctx?.openProject();
+          break;
+        }
+        case "clone": {
+          _ctx?.cloneRepository();
+          break;
+        }
+        case "add": {
+          _ctx?.addExistingRepo();
+          break;
+        }
+        default: {
+          break;
+        }
+      }
+    },
+  }) as WelcomeScope;
+  return _state;
+}
+
+/** Recompute the projection; the surface follows. */
+function refresh(): void {
+  Object.assign(state(), project());
+}
+
+/**
+ * Draw the pane into `host`, or bring the one already there up to date.
+ *
+ * The canvas calls this on every render while nothing is open, into the same wrap it clears when
+ * something opens — so a mount whose root has since left the document is disposed and remade, and
+ * one still standing is only refreshed.
+ *
+ * @param {HTMLElement} host
+ */
+export function renderWelcome(host: HTMLElement): void {
+  refresh();
+  const standing = _host === host && _handle !== null && _handle.root.isConnected;
+  if (standing) {
+    return;
+  }
+  if (_mount && _host === host && !_handle) {
+    // Still mounting into this very host.
+    return;
+  }
+  disposeWelcome();
+  _host = host;
+  const pending = mountSurface("welcome", state(), host);
+  _mount = pending;
+  void pending.then((handle) => {
+    if (_mount === pending) {
+      _handle = handle;
+    } else {
+      handle.dispose();
+    }
+  });
+}
+
+/** Take the pane down and forget its host. */
+export function disposeWelcome(): void {
+  const pending = _mount;
+  _mount = null;
+  if (_handle) {
+    _handle.dispose();
+    _handle = null;
+  } else if (pending) {
+    void pending.then((handle) => handle.dispose());
+  }
+  _host = null;
+}

package/src/tabs/project-config.ts

@@ -33,21 +33,30 @@
  * from the other side: a config that reached disk without passing through here (the assistant's
  * `write_file`) is put INTO the document rather than left beside it as a rival.
  *
- * **One serialisation.** {@link serializeProjectConfig} is `JSON.stringify(config, null, 2)` —
- * byte-for-byte what `files/file-ops.ts`'s native-JSON branch writes, so a ⌘S on the open tab and a
- * settings edit produce the same file. The predecessor had `null, 2` in `site-context.ts` and
- * `"\t"` in both `settings/contributed-section.ts` and `settings/defs-editor.ts`, so a settings
- * edit re-indented the entire file — every `project.json` in this repository is on disk with two
- * spaces.
+ * **One serialisation.** {@link serializeProjectConfig} is `files/json-layout.ts`'s serializer over
+ * the layout the file was read in — byte-for-byte what `files/serialize-document.ts`'s native-JSON
+ * branch writes, so a ⌘S on the open tab and a settings edit produce the same file. The predecessor
+ * had `null, 2` in `site-context.ts` and `"\t"` in both `settings/contributed-section.ts` and
+ * `settings/defs-editor.ts`, so a settings edit re-indented the entire file — every `project.json`
+ * in this repository is on disk with two spaces. It was then `JSON.stringify(config, null, 2)`,
+ * which agreed with the tab's save and disagreed with the formatter: a one-field edit re-laid every
+ * short array in the file (issue 308).
  *
  * **A no-op edit writes nothing.** A form that re-commits the value it already holds — and every
  * one of these surfaces has such a path — used to rewrite the whole file. A commit now compares the
  * serialised result against what the file itself says and returns without a transaction, without a
  * write, and therefore with an empty diff.
  *
+ * **A real edit is a one-line diff.** The file's layout — which objects sit on one line, where a
+ * blank line falls — is read once per binding ({@link seedCommitted}), replaced by the record of
+ * whatever bytes reached the file another way ({@link adoptProjectConfig}), and every serialisation
+ * here honours it, so what changes on disk is the field that changed.
+ *
  * **Collaboration.** `project.json` is out of collab replication; the gate is in
  * `collab/collab-session.ts`'s `ensureCollab`, which is what would otherwise register the Yjs
  * history delegate over this tab.
+ *
+ * @docs studio/projects/settings
  */
 
 import { errorMessage } from "@jxsuite/schema/parse";
@@ -58,6 +67,8 @@ import { requireProjectState, setProjectState } from "../state";
 import { setWorkspaceProject, workspace } from "../workspace/workspace";
 import { PROJECT_CONFIG_PATH, createTab, disposeTab } from "./tab";
 import { transactDoc } from "./transact";
+import { deriveJsonLayout, parseJsonDocument, serializeJson } from "../files/json-layout";
+import type { JsonLayout } from "../files/json-layout";
 
 import type { Tab } from "./tab";
 import type { ProjectConfig } from "@jxsuite/schema/types";
@@ -67,15 +78,16 @@ export { PROJECT_CONFIG_PATH } from "./tab";
 /**
  * The project configuration, as a file.
  *
- * The ONE serialisation. Identical to the native-JSON branch of `files/file-ops.ts`'s
+ * The ONE serialisation. Identical to the native-JSON branch of `files/serialize-document.ts`'s
  * `serializeDocument`, which is what ⌘S on the open `project.json` tab goes through — the two must
- * agree or every save would fight the last one.
+ * agree or every save would fight the last one. Both honour the layout the file was read in ({@link
+ * configLayout}); with none known, the formatter's layout for fresh output.
  *
  * @param {ProjectConfig} config
  * @returns {string}
  */
 export function serializeProjectConfig(config: ProjectConfig): string {
-  return JSON.stringify(config, null, 2);
+  return serializeJson(config, configLayout());
 }
 
 // ─── The document of record ───────────────────────────────────────────────────
@@ -94,15 +106,35 @@ let _detached: Tab | null = null;
  * variables editor writes into `config.style` and then hands the same object over as a patch. A
  * value taken from memory would call every one of those edits a no-op.
  *
- * Comparing two `JSON.stringify(_, null, 2)` renderings of the same key order is a SEMANTIC test,
- * not a textual one, which is the point: `project.json` on disk is formatted by `oxfmt` (two-space
- * indent, short arrays kept on one line), so a byte comparison against the file would call every
- * edit a change and rewrite the whole file. This calls it unchanged and writes nothing.
+ * Comparing two renderings of the same key order through the same serializer is a SEMANTIC test,
+ * not a textual one, which is the point: a `project.json` formatted some other way than the
+ * serializer would lay it out — every array expanded, say — would otherwise look changed on every
+ * commit, and a byte comparison against the file would rewrite it whole. This calls it unchanged
+ * and writes nothing.
  *
  * `null` means "unknown" — no project file, or one that would not parse — and every commit writes.
  */
 let _committed: string | null = null;
 
+/**
+ * The layout the file was read in ({@link seedCommitted}) or last written in ({@link
+ * adoptProjectConfig}), for a binding with no open tab to carry it. Reset with the binding: a
+ * different project is a different file.
+ */
+let _layout: JsonLayout | null = null;
+
+/**
+ * The layout a configuration write honours.
+ *
+ * The open tab's, when there is one — it read the file when it opened, or was lent the seed's
+ * record ({@link lendProjectConfigLayout}), and a source-view commit or a reload from disk keeps it
+ * current — and otherwise what the seed read. The two describe the same file, so the choice only
+ * matters for freshness, and the tab is the fresher.
+ */
+function configLayout(): JsonLayout | null {
+  return openConfigTab()?.doc.layout ?? _layout;
+}
+
 /** Whether {@link _committed} has been sought for the current binding. One read per project. */
 let _seeding: Promise<void> | null = null;
 
@@ -126,6 +158,7 @@ function unbind(): void {
   }
   _bound = null;
   _committed = null;
+  _layout = null;
   _seeding = null;
 }
 
@@ -134,7 +167,9 @@ function seedCommitted(): Promise<void> {
   _seeding ??= (async () => {
     try {
       const text = await getPlatform().readFile(PROJECT_CONFIG_PATH);
-      _committed = serializeProjectConfig(JSON.parse(text) as ProjectConfig);
+      const { document, layout } = parseJsonDocument(text);
+      _layout = layout;
+      _committed = serializeProjectConfig(document as unknown as ProjectConfig);
     } catch {
       // No file, an unreadable one, or one that does not parse. "Unknown" is the honest answer,
       // And an unknown file is one every commit must write.
@@ -144,6 +179,29 @@ function seedCommitted(): Promise<void> {
   return _seeding;
 }
 
+/**
+ * Lend the file's layout to `tab` when it has none of its own.
+ *
+ * The Settings door (`settings/settings-document.ts`) opens the `project.json` tab over the
+ * configuration object the project was loaded with — an object the platform parsed, with no text
+ * behind it — so that tab arrives with `doc.layout === null`. Left there, a ⌘S on it would write
+ * the formatter's layout for fresh output while a settings commit on the SAME document wrote the
+ * file's: every short object in the file blown open by the save the settings edit had just kept,
+ * which is the one disagreement this module exists to make impossible. The file is read once per
+ * binding anyway ({@link seedCommitted}); this hands the record that read made to the tab, and
+ * {@link configLayout} then takes it back from the tab like every other writer. A tab that read the
+ * file itself — the Files tree, a reload, a source-view commit — keeps the fresher record it has.
+ *
+ * @param {Tab} tab
+ * @returns {Promise<void>}
+ */
+export async function lendProjectConfigLayout(tab: Tab): Promise<void> {
+  await seedCommitted();
+  if (tab.doc.layout === null && _layout !== null) {
+    tab.doc.layout = _layout;
+  }
+}
+
 /**
  * Forget the configuration document — the project-switch and test hook.
  *
@@ -187,16 +245,28 @@ function liveConfig(): ProjectConfig | null {
 }
 
 /**
- * Make `target` hold exactly `source`'s keys — assignment alone would leave the removals behind.
+ * Make `target` hold exactly `source`'s keys, in `source`'s ORDER.
+ *
+ * Every key goes, the ones `source` keeps included, before `source` is assigned over the empty
+ * object. Assignment alone would leave the removals behind; deleting only the removals would leave
+ * the ORDER behind, because a key that survives keeps the position it had and only a new one takes
+ * `source`'s. Key order is what the serializer writes the file in, so a document holding the
+ * assistant's configuration in the previous file's order re-lays the file the assistant just wrote
+ * on the next commit — even a no-op one, which then disagrees with {@link _committed} (issue 331).
+ * The rival handover in {@link commitProjectConfig} is the same case from the other side: the
+ * object of record is the source, and its order is the file's.
+ *
+ * The transient — an observer of a single key would see it gone and back within the transaction —
+ * is one the removals already had, and nothing observes the configuration document key by key: the
+ * settings surfaces render from `projectState` and mutate it in place, and every reader of the
+ * document follows the root reference {@link transactDoc} replaces when the transaction ends.
  *
  * @param {Record<string, unknown>} target
  * @param {ProjectConfig} source
  */
 function replaceContents(target: Record<string, unknown>, source: ProjectConfig): void {
   for (const key of Object.keys(target)) {
-    if (!Object.hasOwn(source, key)) {
-      delete target[key];
-    }
+    delete target[key];
   }
   Object.assign(target, source);
 }
@@ -307,7 +377,9 @@ export async function commitProjectConfig(
   // Tab's own parse, and the caller has already mutated the object it rendered from.
   const live = liveConfig();
   const tab = projectConfigDocument();
-  await seedCommitted();
+  // The seed, and the record it read handed to the document — so the tab the Settings door opened
+  // Writes the same bytes from ⌘S that this commit is about to.
+  await lendProjectConfigLayout(tab);
   const current = toRaw(tab.doc.document) as unknown as ProjectConfig;
   const currentText = serializeProjectConfig(current);
 
@@ -388,14 +460,26 @@ export async function commitProjectConfig(
  * assistant's write back out of existence. Putting the bytes into the document instead keeps the
  * one-object rule true, and the state sync follows from the bind effect like every other change.
  *
+ * **The layout record travels with the write.** The assistant authored the whole file, and the text
+ * it wrote is the file now — so the record the next commit honours is derived from THAT text
+ * (`json-layout.ts`'s `deriveJsonLayout`), exactly as a reload from disk would derive it, and it
+ * replaces both the seed's record and the open tab's. Keeping the record the chokepoint read BEFORE
+ * the write is what turned the settings edit after an assistant rewrite into a whole-file diff: the
+ * file was on disk in the assistant's layout and the commit re-laid it in the previous one (issue
+ * 331). The key order travels the same way: {@link replaceContents} installs `config`'s order on
+ * the document, so a rewrite that moved a top-level key stays moved. Nothing here re-reads the file
+ * to learn any of this: the caller just produced the bytes, and a second parse of `project.json` is
+ * the rival object this door exists to prevent.
+ *
  * `skipHistory`, because this is a RELOAD and not an edit: the file already says this, and
  * `write_file` tells the model in as many words that its disk writes are not undoable. A history
  * entry here would offer ⌘Z a change it could not take back from the file.
  *
  * @param {ProjectConfig} config The configuration as written — already past the schema gate.
+ * @param {string} text The bytes that reached the file, which `config` is the parse of.
  * @returns {Promise<void>}
  */
-export async function adoptProjectConfig(config: ProjectConfig): Promise<void> {
+export async function adoptProjectConfig(config: ProjectConfig, text: string): Promise<void> {
   if (!requireProjectState()) {
     // No project state is no configuration document either ({@link projectConfigDocument} reads
     // One). The workspace copy is then the only thing there is to keep true.
@@ -410,7 +494,13 @@ export async function adoptProjectConfig(config: ProjectConfig): Promise<void> {
   );
   tab.doc.dirty = false;
   // Settle a read already in flight before saying what the file holds, or it would resolve after
-  // This line with the PREVIOUS bytes and make the next real commit look like a no-op.
+  // These lines with the PREVIOUS bytes and record, and make the next real commit look like a
+  // No-op — or re-lay the file the assistant just formatted.
   await seedCommitted();
+  // The record of the bytes just written, on the tab as well as on the seed: `configLayout`
+  // Prefers the open tab's, and the tab's is the record of the file it opened, which the write has
+  // Just replaced. The tab holds the config now; it holds the config's layout too.
+  _layout = deriveJsonLayout(text);
+  tab.doc.layout = _layout;
   _committed = serializeProjectConfig(config);
 }