@jxsuite/studio 4.0.0 → 5.0.0

package/src/files/media-usage.ts

@@ -1,164 +1,74 @@
 /**
- * Media usage — "which pages use this image?", asked in the shape an author actually wrote.
+ * Media usage — "which pages use this image?", asked once.
  *
- * `services/references.ts` already answers "where is this used?" for documents, and its answer is
- * what every destructive confirmation says out loud. Media does not fit through it unmodified, for
- * one reason: **the reference index resolves refs, and a media file's authored ref usually resolves
- * somewhere else.** `public/hero.jpg` is written `/hero.jpg`, which the compiler — and therefore
- * the sweep — resolves to `hero.jpg`. Ask about the file and every reference to it is invisible;
- * the query succeeds, returns zero, and the delete dialog says nothing else refers to it while
- * seven pages break. A confident zero is the one answer a destructive dialog must never invent.
+ * `services/references.ts` answers "where is this used?" for every kind of file, and its answer is
+ * what every destructive confirmation says out loud. Media needs three things on top of it, and no
+ * longer needs the fourth this module was built for.
  *
- * So the query is keyed on the AUTHORED ref. {@link authoredRefTargets} enumerates every path a
- * reference to this file resolves to — the file, its served path, its asset-mount path — and this
- * module asks all of them and unions the answers. Everything else is deliberately inherited rather
- * than re-implemented: the same `loadUsages` cache (so a dialog and a panel asking at once are one
- * round trip), the same `invalidateUsages` on any filesystem event, the same `usageWarning`
- * sentence in the confirmation, and the same `usageHeadline` wording on a panel.
+ * **What it still does.** A media path is normalized before it becomes a query (a leading `./` is
+ * not part of a file's identity), an empty path is a FAILURE rather than "nothing uses it", and
+ * {@link mediaUsageHeadline} renders the one line a media surface shows beside a file — where a
+ * failed query says **unknown**, which is a different fact from "unused" and has to read like one.
  *
- * **A partial answer is `failed`, not a total.** If one lane of the union cannot be counted, the
- * union cannot either — a number assembled from the lanes that worked reads exactly like a complete
- * one, and would understate what a delete breaks. Unknown is the honest answer, and
- * {@link mediaUsageHeadline} says the word.
+ * **What it no longer does, and why that matters.** A media file's authored reference usually
+ * resolves somewhere else: `public/hero.jpg` is written `/hero.jpg`, and a content asset is written
+ * `./images/hero.png` and republished at its collection's mount. `findReferences` used to resolve a
+ * rooted reference against the project root ALONE, so asking it about the file matched none of
+ * those and returned a confident zero — the one answer a destructive dialog must never invent. This
+ * module's answer was to enumerate every authored spelling of the file and union the results.
+ *
+ * That was a workaround in the wrong place. A client-side union can make a COUNT come out right and
+ * can do nothing at all about the REWRITE, which happens inside the engine — so the engine learned
+ * to resolve every lane itself (issue 239/241, `site-architecture.md` §9.3), and the union became a
+ * second implementation of a rule that now has one. It is gone: one path in, one query, one answer,
+ * and the lanes are the engine's business.
  *
  * @docs studio/projects/media
  */
 
-import { authoredRefTargets } from "./media-paths";
+import { normalizeProjectPath } from "./media-paths";
 import { loadUsages, peekUsages, retryUsages, usageHeadline } from "../services/references";
-import type { UsageQuery, UsageState } from "../services/references";
-import type { ReferenceFile, ReferenceHit, ReferencesResult } from "../types";
+import type { UsageState } from "../services/references";
 
-/**
- * The queries whose union answers "what uses this media file?".
- *
- * One per authored form. An empty list means there is no question to ask (an empty path), which
- * {@link loadMediaUsages} reports as a failure rather than as "nothing uses it".
- */
-export function mediaUsageQueries(path: string): UsageQuery[] {
-  return authoredRefTargets(path).map((target) => ({ path: target }));
-}
-
-/** Merge one file's hits into the accumulator, summing counts per `(refType, ref)`. */
-function mergeFile(into: Map<string, ReferenceFile>, file: ReferenceFile): void {
-  const existing = into.get(file.path);
-  if (!existing) {
-    into.set(file.path, { count: file.count, path: file.path, refs: [...file.refs] });
-    return;
-  }
-  for (const hit of file.refs) {
-    const same = existing.refs.find(
-      (candidate: ReferenceHit) => candidate.refType === hit.refType && candidate.ref === hit.ref,
-    );
-    if (same) {
-      same.count += hit.count;
-    } else {
-      existing.refs.push({ ...hit });
-    }
-  }
-  existing.count += file.count;
-}
+/** The state a caller gets for a path that names no file. */
+const NO_FILE: UsageState = { message: "no media file to look for", status: "failed" };
 
 /**
- * One result out of several, for the same file asked about under different names.
+ * The query for a media file, or null when the path names nothing.
  *
- * The lanes cannot double-count: each asks about a DIFFERENT resolved path, and one authored string
- * resolves to exactly one of them. Errors are unioned by path so a document that failed to parse in
- * every lane is reported once, and `path` reports the media file the caller asked about rather than
- * whichever lane happened to be first.
+ * Normalizing here rather than at each call site is the whole of what this wrapper adds over
+ * `loadUsages`: the file tree, a drop handler and a library tile do not agree on whether a path
+ * carries a leading `./`, and two spellings of one file must not become two cache entries.
  */
-function unionResults(path: string, results: readonly ReferencesResult[]): ReferencesResult {
-  const files = new Map<string, ReferenceFile>();
-  const errors = new Map<string, { path: string; error: string }>();
-  for (const result of results) {
-    for (const file of result.files) {
-      mergeFile(files, file);
-    }
-    for (const error of result.errors) {
-      if (!errors.has(error.path)) {
-        errors.set(error.path, error);
-      }
-    }
-  }
-  const merged = [...files.values()].toSorted((a, b) => a.path.localeCompare(b.path));
-  return {
-    errors: [...errors.values()],
-    files: merged,
-    filesReferencing: merged.length,
-    path,
-    refsTotal: merged.reduce((sum, file) => sum + file.count, 0),
-    tagName: null,
-  };
-}
-
-/**
- * Reduce the lanes to one state.
- *
- * Precedence is strictly least-informative-wins, because every step down is a step away from a
- * number the caller could act on: unsupported (the host cannot answer at all) beats failed (it
- * tried and could not) beats pending beats a real union.
- */
-function combine(path: string, states: readonly UsageState[]): UsageState {
-  if (states.some((state) => state.status === "unsupported")) {
-    return { status: "unsupported" };
-  }
-  const failure = states.find((state) => state.status === "failed");
-  if (failure) {
-    return failure;
-  }
-  if (states.some((state) => state.status === "pending")) {
-    return { status: "pending" };
-  }
-  return {
-    result: unionResults(
-      path,
-      states.map((state) => (state as { result: ReferencesResult }).result),
-    ),
-    status: "ready",
-  };
+function mediaQuery(path: string): { path: string } | null {
+  const normalized = normalizeProjectPath(path);
+  return normalized === "" ? null : { path: normalized };
 }
 
 /**
  * The answer right now, WITHOUT starting a request — the synchronous read a lit template needs.
  *
- * `null` means at least one lane has never been asked, and the caller decides whether this paint is
- * the one that asks (see {@link loadMediaUsages}).
+ * `null` means the question has never been asked, and the caller decides whether this paint is the
+ * one that asks (see {@link loadMediaUsages}).
  */
 export function peekMediaUsages(path: string): UsageState | null {
-  const queries = mediaUsageQueries(path);
-  if (queries.length === 0) {
-    return null;
-  }
-  const states: UsageState[] = [];
-  for (const query of queries) {
-    const state = peekUsages(query);
-    if (state === null) {
-      return null;
-    }
-    states.push(state);
-  }
-  return combine(path, states);
+  const query = mediaQuery(path);
+  return query === null ? null : peekUsages(query);
 }
 
 /**
- * Ask every lane and union the answers. Never rejects — a failure is a STATE, because the caller
+ * Ask, or join the ask already in flight. Never rejects — a failure is a STATE, because the caller
  * has to render something and "unknown" is the honest something.
  */
 export async function loadMediaUsages(path: string): Promise<UsageState> {
-  const queries = mediaUsageQueries(path);
-  if (queries.length === 0) {
-    return { message: "no media file to look for", status: "failed" };
-  }
-  return combine(path, await Promise.all(queries.map((query) => loadUsages(query))));
+  const query = mediaQuery(path);
+  return query === null ? NO_FILE : loadUsages(query);
 }
 
-/** Forget every lane's answer and ask again — the Retry behind a failed media count. */
+/** Forget the answer and ask again — the Retry behind a failed media count. */
 export async function retryMediaUsages(path: string): Promise<UsageState> {
-  const queries = mediaUsageQueries(path);
-  if (queries.length === 0) {
-    return { message: "no media file to look for", status: "failed" };
-  }
-  return combine(path, await Promise.all(queries.map((query) => retryUsages(query))));
+  const query = mediaQuery(path);
+  return query === null ? NO_FILE : retryUsages(query);
 }
 
 /**

package/src/files/serialize-document.ts

@@ -19,6 +19,7 @@ import {
   formatSerialize,
   loadFormats,
 } from "../format/format-host";
+import { serializeJson } from "./json-layout";
 import type { Tab } from "../tabs/tab";
 
 /**
@@ -56,5 +57,11 @@ export async function serializeDocument(tab: Tab): Promise<string> {
       });
     }
   }
-  return JSON.stringify(tab.doc.document, null, 2);
+  /* Native JSON, in the layout the file was read in (`json-layout.ts`, issue 308).
+     `tab.doc.layout` is what the read recorded — which objects the author kept on one line, where
+     a blank line sits, which characters were escaped — and it is null for a document with no JSON
+     source, where every object expands and every array is laid by fit: the formatter's own answer
+     for stringified output. Either way the text ends with one newline, as every formatted file
+     does. */
+  return serializeJson(tab.doc.document, tab.doc.layout ?? null);
 }

package/src/format/convert-file.ts

@@ -27,6 +27,8 @@ import {
   stringProperty,
 } from "../commands/command-args";
 import { convertTargetExtensions, convertTargets } from "./format-choices";
+import { parseJsonDocument, serializeJson } from "../files/json-layout";
+import type { JsonLayout } from "../files/json-layout";
 import type { AnyCommand, CommandRegistry } from "../commands/registry";
 
 /** What a conversion will do, resolved in full before the reader is asked to confirm it. */
@@ -97,7 +99,12 @@ async function writeDocument(
 ): Promise<string> {
   const merged = { ...frontmatter, ...document };
   if (targetExt === ".json") {
-    return `${JSON.stringify(merged, null, 2)}\n`;
+    /* The same serializer a save uses (`files/json-layout.ts`), with NO layout: the source was
+       markdown or CSV, so there is no JSON text whose line breaks could be kept. Every object
+       expands and every short array stays on one line — which is exactly what the repository's
+       formatter would make of `JSON.stringify` output, so the converted file needs no reformat and
+       the tab it opens in reads its layout straight back. The newline is the serializer's own. */
+    return serializeJson(merged, null);
   }
   const { formatByExtension, formatSerialize } = await import("./format-host");
   const format = formatByExtension(targetExt, "serialize");
@@ -368,12 +375,16 @@ async function rebuildTab(from: string, to: string, text: string): Promise<void>
   const format = formatForPath(to);
   let document: Record<string, unknown>;
   let frontmatter: Record<string, unknown> | undefined;
+  // The layout of the JSON just written, as every other JSON reader records it (`files/files.ts`,
+  // `files/file-ops.ts`): the text is the serializer's own, so the record says what a layout-less
+  // Write would do anyway — but the tab reads its file rather than assuming it.
+  let layout: JsonLayout | null = null;
   try {
     if (format) {
       const { parseSourceForPath } = await import("../files/file-ops");
       ({ document, frontmatter } = await parseSourceForPath(to, text));
     } else {
-      document = JSON.parse(text) as Record<string, unknown>;
+      ({ document, layout } = parseJsonDocument(text));
     }
   } catch {
     // The bytes on disk are the ones just written and the conversion has already succeeded, so a
@@ -386,6 +397,7 @@ async function rebuildTab(from: string, to: string, text: string): Promise<void>
     documentPath: to,
     ...(frontmatter === undefined ? {} : { frontmatter }),
     id: to,
+    layout,
     sourceFormat: format?.name ?? null,
   });
 }
@@ -485,14 +497,8 @@ export function fileFormatCommands(): AnyCommand[] {
       // Nothing restores it: the file has moved and its references have been rewritten with it.
       // The confirmation carrying the count is what stands in for an undo.
       undo: "none",
-      aiTool: {
-        description:
-          "Convert a document between formats in place — Markdown to JSON and back. The file is " +
-          "renamed to the new extension and every reference to it is rewritten. Refused for " +
-          "layouts, for anything inside a content collection, and while the file is open with " +
-          "unsaved changes.",
-        name: "convert_file_format",
-      },
+      /* No `aiTool`, by §12.4's second deletion rule: `run` awaits a confirm dialog the person
+         answers. */
       run: async (_ctx, args: Record<string, unknown>) => {
         const target = typeof args.format === "string" ? args.format : undefined;
         await convertFile(

package/src/format/format-host.ts

@@ -9,7 +9,7 @@
 
 import { setProjectSchemasForMonaco } from "../services/monaco-lazy";
 import { getPlatform } from "../platform";
-import type { ExtensionsInfo } from "../types";
+import type { ExtensionCatalogEntry, ExtensionsInfo } from "../types";
 import type { JxMutableNode } from "@jxsuite/schema/types";
 
 export interface StudioFormatHints {
@@ -76,6 +76,8 @@ export function refreshFormats() {
   _formats = [];
   _extensionsLoaded = null;
   _extensions = [];
+  _catalogLoaded = null;
+  _catalog = [];
 }
 
 /** Seed the registry directly (tests and hosts that preload format metadata). */
@@ -122,6 +124,50 @@ export function setExtensions(extensions: ExtensionsInfo[]) {
   _extensionsLoaded = Promise.resolve(extensions);
 }
 
+// ─── Extension catalogue (specs/extensions.md §9.2) ──────────────────────────
+/* The AVAILABLE half beside the ENABLED half above, cached the same way and for a sharper reason:
+   the Extensions section and the AI assistant's system prompt both need "what could this project
+   turn on", and `buildSystemPrompt` is synchronous. Two caches would be two answers to one
+   question, so there is one, loaded here and read synchronously by both. */
+
+let _catalog: ExtensionCatalogEntry[] = [];
+let _catalogLoaded: Promise<ExtensionCatalogEntry[]> | null = null;
+
+/**
+ * Load (and cache) what this backend can offer. Backed by the optional `listExtensionCatalog`
+ * member; a platform without it (or a failure) degrades to an empty list, and the Extensions
+ * section falls back to a typed package name.
+ *
+ * @returns {Promise<ExtensionCatalogEntry[]>}
+ */
+export function loadExtensionCatalog(): Promise<ExtensionCatalogEntry[]> {
+  if (!_catalogLoaded) {
+    _catalogLoaded = (async () => {
+      try {
+        const platform = getPlatform() as {
+          listExtensionCatalog?: () => Promise<ExtensionCatalogEntry[]>;
+        };
+        _catalog = (await platform.listExtensionCatalog?.()) ?? [];
+      } catch {
+        _catalog = [];
+      }
+      return _catalog;
+    })();
+  }
+  return _catalogLoaded;
+}
+
+/** The last-loaded catalogue (synchronous access for render and prompt paths). */
+export function getExtensionCatalog(): ExtensionCatalogEntry[] {
+  return _catalog;
+}
+
+/** Seed the catalogue directly (tests and hosts that preload it). */
+export function setExtensionCatalog(catalog: ExtensionCatalogEntry[]) {
+  _catalog = catalog;
+  _catalogLoaded = Promise.resolve(catalog);
+}
+
 /**
  * Fetch the active project's entry documents ONCE and hand the same payload to every consumer.
  *
@@ -166,6 +212,9 @@ export function refreshExtensionUi(platform: {
   fetchProjectSchemas?: () => Promise<{ project?: unknown; document?: unknown }>;
 }): void {
   void shareProjectSchemas(platform);
+  // `installed` and `bundled` are per-project facts, so an install or a project switch can move
+  // Them even when the shipped half has not changed.
+  void loadExtensionCatalog();
   void import("../settings/extension-sections")
     .then(({ syncExtensionSettingsSections }) => syncExtensionSettingsSections())
     .catch(() => {

package/src/github/github-auth.ts

@@ -34,16 +34,25 @@
  * here — the browser withholds the reason on purpose — so the detail names both rather than
  * guessing between them.
  *
+ * **The waiting room is a document.** `surfaces/github-auth.json` draws the code, the link and the
+ * wait, over the kit's `jx-dialog`; this module keeps the client id, the poll loop, its failure
+ * budget and every report above. The dialog it replaced was an `<sp-dialog-wrapper>` whose one
+ * `@cancel`/`@close` handler both stopped the loop and resolved the promise, so "the reader
+ * dismissed this" and "GitHub answered" were the same code path — and the promise could be resolved
+ * a second time with `null` by the close that a successful sign-in itself provokes. Answering and
+ * closing are two steps now, in that order.
+ *
  * The token is returned to callers and never rendered. In a browser it is stored in `localStorage`;
  * on the desktop it is in the launcher's `0600` credential store and this module holds it only in
  * memory for the session. `settings/preferences-accounts.ts` lists it as _stored or not_ and is the
  * only place it can be revoked (`studio.md` §15 rule 1).
  */
 
-import { html } from "lit-html";
 import { errorMessage } from "@jxsuite/schema/parse";
 import { notify } from "../services/notify";
-import { showDialog } from "../ui/layers";
+import { layerHost } from "../ui/layers";
+import { openGithubAuthSurface } from "../surfaces/github-auth";
+import type { GithubAuthSurfaceHandle } from "../surfaces/github-auth";
 
 const CLIENT_ID = "Ov23liYVlMFpgjOEPXJH";
 const STORAGE_KEY = "jx_github_token";
@@ -247,17 +256,52 @@ export async function authenticateGithub() {
 
   const { device_code, user_code, verification_uri, interval = 5 } = codeData;
 
-  return showDialog<string | null>((done) => {
+  return new Promise<string | null>((resolve) => {
     let cancelled = false;
     let pollTimer: ReturnType<typeof setTimeout> | null = null;
     let failures = 0;
-
-    const stop = () => {
+    let answered = false;
+
+    /**
+     * Stop the loop and answer, once.
+     *
+     * Separate from {@link done} because both ends arrive and either may be first: a token that
+     * lands closes the dialog, which raises `onClosed` behind it, and a dialog the reader dismisses
+     * raises `onClosed` with no token at all. Answering here and closing there is what keeps the
+     * second of those from overwriting the first with `null`.
+     */
+    const settle = (token: string | null): void => {
+      if (answered) {
+        return;
+      }
+      answered = true;
       cancelled = true;
       if (pollTimer) {
         clearTimeout(pollTimer);
+        pollTimer = null;
+      }
+      resolve(token);
+    };
+
+    /**
+     * Take the dialog down, once.
+     *
+     * Guarded here rather than trusted to the handle, because closing is what RAISES `onClosed` —
+     * so a teardown that re-entered through it would call itself until the stack ran out.
+     */
+    let closing = false;
+    const takeDown = (): void => {
+      if (closing) {
+        return;
       }
-      done(null);
+      closing = true;
+      handle.close();
+    };
+
+    /** The poll's own exit: answer, then take the dialog down. */
+    const done = (token: string | null): void => {
+      settle(token);
+      takeDown();
     };
 
     const poll = async () => {
@@ -306,13 +350,11 @@ export async function authenticateGithub() {
               ? "The device code expired before it was entered."
               : `GitHub answered "${tokenData.error ?? "an unrecognised response"}".`,
         );
-        cancelled = true;
         done(null);
       } catch (error) {
         failures += 1;
         if (failures >= MAX_POLL_FAILURES) {
           reportUnreachable(error);
-          cancelled = true;
           done(null);
           return;
         }
@@ -320,27 +362,27 @@ export async function authenticateGithub() {
       }
     };
 
-    pollTimer = setTimeout(poll, interval * 1000);
+    /*
+     * The dialog first, then the timer. `done` reaches for `handle`, and a poll that fired before
+     * the surface existed would find a binding that is not initialised yet — which a zero-second
+     * device interval makes reachable rather than theoretical.
+     */
+    const handle: GithubAuthSurfaceHandle = openGithubAuthSurface({
+      layer: layerHost("dialog"),
+      onCancel: () => {
+        takeDown();
+      },
+      /* `done`, not `settle`: a `close` the flow did not ask for — Escape, or a dismissal the
+         platform allows — must ALSO take the document out of the dialog layer, or the surface
+         outlives the dialog it drew. `settle` is idempotent, so a close that follows a token
+         answers nothing and only cleans up. */
+      onClosed: () => {
+        done(null);
+      },
+      userCode: user_code,
+      verificationUri: verification_uri,
+    });
 
-    return html`
-      <sp-dialog-wrapper
-        open
-        headline="Sign in to GitHub"
-        cancel-label="Cancel"
-        @cancel=${stop}
-        @close=${stop}
-      >
-        <div class="github-auth-dialog">
-          <p>Enter this code on GitHub to authorize Jx Studio:</p>
-          <div class="github-auth-code">${user_code}</div>
-          <p>
-            <a href="${verification_uri}" target="_blank" rel="noopener"
-              >Open ${verification_uri}</a
-            >
-          </p>
-          <p class="github-auth-waiting">Waiting for authorization…</p>
-        </div>
-      </sp-dialog-wrapper>
-    `;
+    pollTimer = setTimeout(poll, interval * 1000);
   });
 }