@jxsuite/studio 4.1.0 → 5.0.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,18 +33,24 @@
  * 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}) 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.
@@ -58,6 +64,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 { 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 +75,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 +103,34 @@ 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}), 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 +154,7 @@ function unbind(): void {
   }
   _bound = null;
   _committed = null;
+  _layout = null;
   _seeding = null;
 }
 
@@ -134,7 +163,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 +175,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.
  *
@@ -307,7 +361,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);
 

package/src/tabs/tab.ts

@@ -2,11 +2,13 @@
 import { effectScope, reactive } from "../reactivity";
 import { formatByName, formatForPath } from "../format/format-host";
 import { normalizeArrayChildren } from "../state";
+import type { JxPath } from "../state";
 import type { FormulaEditDef, FunctionEditDef, InlineEditDef, JsonValue } from "../types";
 import { editorKindForMode } from "../commands/context";
 import type { EditorKind } from "../commands/context";
 import type { JxMutableNode } from "@jxsuite/schema/types";
 import type { JxDocOp, JxFmOp } from "./patch-ops";
+import type { JsonLayout } from "../files/json-layout";
 
 /**
  * The project's configuration file, project-relative.
@@ -39,6 +41,29 @@ export interface TabUi {
   editZoom: number;
   activeMedia: string | null;
   activeSelector: string | null;
+  /**
+   * The popover the canvas is drawing OPEN, by document path, or null for none.
+   *
+   * Per tab rather than per pane, beside `activeMedia` and `previewColorScheme`, because it is a
+   * fact about a DOCUMENT's elements: two panes showing the same tab show the same open panel,
+   * which is correct — it is the same element.
+   *
+   * Exactly one, never a set. Several de-popovered panels in flow at once would shove the page
+   * around and make the canvas unreadable; native `popover="auto"` already enforces a single stack,
+   * so a set would model something the platform does not have; and "exactly one" makes the
+   * open-on-selection rule total, with no ordering decision to make.
+   *
+   * A VIEW state — it writes nothing to the document, so it takes no undo entry, does not dirty the
+   * tab and is not replicated over collaboration. It is also deliberately not restored with a
+   * session (§14.8): reopening a project with a modal spread across the page is a worse first frame
+   * than reopening it closed.
+   */
+  openPopover: JxPath | null;
+  /**
+   * The `<dialog>` the canvas draws open in place, per tab and exactly one; view state like
+   * `openPopover`.
+   */
+  openDialog: JxPath | null;
   editingFunction: FunctionEditDef | null;
   /** Logic-tab formula target ($expression editing); editingFunction wins if both are set. */
   editingFormula: FormulaEditDef | null;
@@ -161,6 +186,18 @@ export interface Tab {
     sourceFormat: string | null;
     handlersSource: string | null;
     dirty: boolean;
+    /**
+     * The layout the document's JSON file was written in (`files/json-layout.ts`), or null for a
+     * document with no JSON source — a format-class file, a new document, a stub.
+     *
+     * On the document record because it is a fact about the FILE the document came from, and it
+     * lives exactly as long as that fact does: every edit leaves it alone (the pointers it is keyed
+     * by survive a changed value, a new sibling, a removed one), a reload from disk or a
+     * source-view commit replaces it with the layout of the text just read, and opening a different
+     * file makes a new tab. The history ring never snapshots it — undo restores a document, not a
+     * file.
+     */
+    layout: JsonLayout | null;
   };
   session: {
     /**
@@ -216,6 +253,8 @@ function createDefaultUi(canvasMode: string, preview = false) {
   return {
     activeMedia: null,
     activeSelector: null,
+    openPopover: null,
+    openDialog: null,
     canvasMode,
     editZoom: 1,
     editingFormula: null,
@@ -239,7 +278,15 @@ function createDefaultUi(canvasMode: string, preview = false) {
   };
 }
 
-const ALL_MODES = ["edit", "design", "preview", "source", "stylebook"];
+/*
+ * `git-diff` is here because a comparison is a MODE of a document, and until now nothing said so.
+ * The Source Control panel reached it through the injected `setCanvasMode`, which performs no
+ * capability check — so the mode worked while `editorKindsOf` could never report `diff`, the Editor
+ * picker could never offer it, and `canvas.setMode { mode: "git-diff" }` threw for every document in
+ * the project. Declaring it makes the palette, the assistant and the screenshot runner able to open
+ * a comparison by name, and puts Diff on the Editor axis where §18.4 already says it belongs.
+ */
+const ALL_MODES = ["edit", "design", "preview", "source", "stylebook", "git-diff"];
 
 /**
  * Create a new tab with reactive doc/session/history trees, owned by an effectScope.
@@ -254,6 +301,7 @@ const ALL_MODES = ["edit", "design", "preview", "source", "stylebook"];
  *   capabilities?: { modes?: string[] };
  *   openedFrom?: TabOrigin | null;
  *   preview?: boolean;
+ *   layout?: JsonLayout | null;
  * }} opts
  * @returns {Tab}
  */
@@ -267,6 +315,7 @@ export function createTab({
   capabilities,
   openedFrom = null,
   preview: previewTab = false,
+  layout = null,
 }: {
   id: string;
   documentPath?: string | null;
@@ -277,6 +326,7 @@ export function createTab({
   capabilities?: { modes?: string[] };
   openedFrom?: TabOrigin | null;
   preview?: boolean;
+  layout?: JsonLayout | null;
 }) {
   const scope = effectScope();
 
@@ -299,6 +349,7 @@ export function createTab({
       dirty: false,
       document,
       handlersSource: null,
+      layout,
       mode: inferDocumentMode(documentPath, sourceFormat),
       sourceFormat,
     }),

package/src/types.ts

@@ -28,6 +28,7 @@ import type {
   DataRowsResult,
   DataRowUpdate,
   DirEntry,
+  ExtensionCatalogEntry,
   ExtensionsInfo,
   FsEvent,
   GitBranchesResult,
@@ -77,8 +78,10 @@ export type {
   DataRowUpdate,
   DirEntry,
   ErrorBody,
+  ExtensionCatalogEntry,
   ExtensionContributionInfo,
   ExtensionProjectBlock,
+  ExtensionSectionInfo,
   ExtensionsInfo,
   FsEvent,
   GitBranchesResult,
@@ -386,6 +389,25 @@ export interface StudioPlatform {
    * platforms without it lose descriptor-contributed settings sections.
    */
   listExtensions?: () => Promise<ExtensionsInfo[]>;
+  /**
+   * The extensions this backend can OFFER, enabled or not — the AVAILABLE half of the pair whose
+   * enabled half is {@link StudioPlatform.listExtensions} above.
+   *
+   * A capability rather than a constant because not every host can run every extension: a Worker
+   * ships a fixed set of extension packages (specs/extensions.md §5.5), and one it does not bundle
+   * is dropped from the registry before composition rather than passed to it. A studio that
+   * advertised a shipped list would offer rows the host would refuse.
+   *
+   * Each entry additionally carries two facts only a backend holds: whether THIS host resolves the
+   * package without a project install (`bundled`), and whether the project has it installed
+   * (`installed`) — the latter because `listPackages` does not mean one thing across backends.
+   * `enabled` is deliberately absent: it is `projectConfig.extensions.includes(name)`, which Studio
+   * already owns and rewrites through the `updateSiteConfig` chokepoint.
+   *
+   * Optional: platforms without it offer no catalogue, and adding an extension stays a typed
+   * package name.
+   */
+  listExtensionCatalog?: () => Promise<ExtensionCatalogEntry[]>;
   /**
    * Fetch the project's generated entry schemas (project.schema.json / document.schema.json),
    * PRE-BUNDLED into self-contained documents for editor registration. Optional: without it the