@jxsuite/studio 3.0.0 → 4.1.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

@@ -0,0 +1,60 @@
+/**
+ * A tab's document, as the bytes a file would hold.
+ *
+ * Its own module because four callers need it and one of them is `file-ops` itself: the save path
+ * writes what this returns, the source view shows it, the collab layer publishes it, and the live
+ * preview overlay sends it. Leaving it in `file-ops` meant the overlay had to import the module
+ * that imports the overlay, and the collab layer had already worked around the same shape by
+ * injecting the function at boot. One home resolves both.
+ *
+ * That every one of them goes through this function is the point rather than an accident: what a
+ * reader sees in a preview, what a peer sees in a session and what lands on disk are the same
+ * bytes, so they cannot drift.
+ */
+
+import { getGridController } from "../grid/grid-controller";
+import {
+  defaultContentFormat,
+  formatByName,
+  formatSerialize,
+  loadFormats,
+} from "../format/format-host";
+import type { Tab } from "../tabs/tab";
+
+/**
+ * Serialize the current document to its output format. Format tabs round-trip through the format
+ * class's serialize capability; everything else is native JSON.
+ *
+ * @param {import("../tabs/tab.js").Tab} tab
+ * @returns {Promise<string>}
+ */
+export async function serializeDocument(tab: Tab): Promise<string> {
+  // Grid tabs serialize through their source (pending edits included) — e.g. the Monaco source
+  // View of a CSV grid tab shows the live file text.
+  const grid = getGridController(tab);
+  const gridText = grid?.serializeForSource();
+  if (gridText) {
+    return gridText;
+  }
+  await loadFormats();
+  const sourceFormat = formatByName(tab.doc.sourceFormat);
+  if (sourceFormat?.capabilities.serialize) {
+    const fm = tab.doc.content?.frontmatter || {};
+    const doc = tab.doc.document;
+    const fullDoc = { ...fm, ...doc, children: doc.children ?? [] };
+    return formatSerialize(sourceFormat.name, fullDoc, { mode: "roundtrip" });
+  }
+  if (tab.doc.mode === "content") {
+    const format = defaultContentFormat();
+    if (format) {
+      const fm = tab.doc.content?.frontmatter ?? {};
+      const hasFrontmatter = Object.keys(fm).length > 0;
+      const fullDoc = { ...fm, ...tab.doc.document };
+      return formatSerialize(format.name, fullDoc, {
+        frontmatter: hasFrontmatter,
+        mode: "roundtrip",
+      });
+    }
+  }
+  return JSON.stringify(tab.doc.document, null, 2);
+}